getOrCreateScope static method

ZenScope getOrCreateScope({ required String name, ZenScope? parentScope, bool? autoDispose, bool useRootAsDefault = false, })

Creates or retrieves a scope with intelligent parent-child linking

Auto-dispose behavior:

• null parent → auto-dispose = true (temporary scope)
• has parent → auto-dispose = false (persistent scope)
• explicit autoDispose → overrides auto-detection

Implementation

static ZenScope getOrCreateScope({
  required String name,
  ZenScope? parentScope,
  bool? autoDispose,
  bool useRootAsDefault = false,
}) {
  // Check for existing scope
  ZenScope? existingScope =
      _persistentScopes[name] ?? _autoDisposeScopes[name];
  if (existingScope != null && !existingScope.isDisposed) {
    final currentParent = existingScope.parent;
    final newParent = parentScope;

    if (currentParent != newParent) {
      if (ZenConfig.enableDebugLogs) {
        ZenLogger.logDebug(
            '🔄 Scope $name exists but parent changed. Recreating scope.');
      }
      _disposeScopeAndCleanup(name, existingScope);
    } else {
      if (ZenConfig.enableDebugLogs) {
        ZenLogger.logDebug('♻️ Reusing existing scope: $name');
      }
      return existingScope;
    }
  } else if (existingScope != null && existingScope.isDisposed) {
    _removeScopeFromTracking(name);
  }

  // Determine effective parent scope
  ZenScope? effectiveParentScope;
  if (parentScope != null) {
    effectiveParentScope = parentScope;
  } else if (useRootAsDefault) {
    effectiveParentScope = rootScope;
  }

  // Determine auto-dispose behavior
  bool effectiveAutoDispose;
  String? effectiveParentName = effectiveParentScope?.name;

  if (autoDispose != null) {
    effectiveAutoDispose = autoDispose;
    if (autoDispose == false) {
      _explicitlyPersistentScopes.add(name);
    }
  } else {
    effectiveAutoDispose = (effectiveParentName == null);
    if (ZenConfig.enableDebugLogs) {
      ZenLogger.logDebug(
          '🎯 Auto-configured scope "$name" with autoDispose=$effectiveAutoDispose');
    }
  }

  // Create new scope
  final newScope = ZenScope(name: name, parent: effectiveParentScope);

  // Track scope
  if (effectiveAutoDispose) {
    _autoDisposeScopes[name] = newScope;
    if (effectiveParentName != null && effectiveParentName != 'RootScope') {
      _parentScopes[name] = effectiveParentName;
      _activeAutoDisposeChildren
          .putIfAbsent(effectiveParentName, () => <String>{})
          .add(name);
    }
    if (ZenConfig.enableDebugLogs) {
      ZenLogger.logDebug('⚡ Created auto-dispose scope: $name');
    }
  } else {
    _persistentScopes[name] = newScope;
    if (effectiveParentName != null && effectiveParentName != 'RootScope') {
      _parentScopes[name] = effectiveParentName;
      _childScopes
          .putIfAbsent(effectiveParentName, () => <String>{})
          .add(name);
    }
    if (ZenConfig.enableDebugLogs) {
      ZenLogger.logDebug('🔒 Created persistent scope: $name');
    }
  }

  return newScope;
}