@blac/core 2.0.15 → 2.0.17

package/dist/StateContainerRegistry-v_prqMcI.cjs

@@ -1,711 +0,0 @@
-//#region src/constants.ts
-/**
- * Default configuration constants for BlaC
- *
- * Centralized location for all magic numbers and default values.
- */
-/**
- * Default configuration constants for BlaC
- */
-const BLAC_DEFAULTS = {
-  DEFAULT_INSTANCE_KEY: 'default',
-  MAX_GETTER_DEPTH: 10,
-  CLEANUP_INTERVAL_MS: 3e4,
-  WEAKREF_CLEANUP_INTERVAL_MS: 1e4,
-  MAX_SUBSCRIPTIONS: 1e3,
-  MAX_SUBSCRIPTIONS_HIGH_PERF: 1e4,
-  PIPELINE_TIMEOUT_MS: 5e3,
-  CLEANUP_INTERVAL_HIGH_PERF_MS: 5e3,
-  MAX_PIPELINE_STAGES: 30,
-};
-/**
- * Static property names for StateContainer classes
- * Used for feature flags and configuration on bloc classes
- */
-const BLAC_STATIC_PROPS = {
-  KEEP_ALIVE: 'keepAlive',
-  EXCLUDE_FROM_DEVTOOLS: '__excludeFromDevTools',
-};
-/**
- * Standard error message prefix
- */
-const BLAC_ERROR_PREFIX = '[BlaC]';
-//#endregion
-//#region src/plugin/PluginManager.ts
-/**
- * Manages plugin lifecycle for the BlaC state management system.
- * Plugins receive notifications about state container lifecycle events.
- *
- * @example
- * ```ts
- * const manager = createPluginManager(registry);
- * manager.install(myPlugin, { environment: 'development' });
- * ```
- */
-var PluginManager = class {
-  /**
-   * Create a new PluginManager
-   * @param registry - The StateContainerRegistry to monitor for lifecycle events
-   */
-  constructor(registry) {
-    this.plugins = /* @__PURE__ */ new Map();
-    this.registry = registry;
-    this.setupLifecycleHooks();
-  }
-  /**
-   * Install a plugin with optional configuration
-   * @param plugin - The plugin to install
-   * @param config - Optional plugin configuration
-   * @throws Error if plugin is already installed
-   */
-  install(plugin, config = {}) {
-    const effectiveConfig = {
-      enabled: true,
-      environment: 'all',
-      ...config,
-    };
-    if (!this.shouldEnablePlugin(effectiveConfig)) {
-      console.log(
-        `[BlaC] Plugin "${plugin.name}" skipped (environment mismatch)`,
-      );
-      return;
-    }
-    if (this.plugins.has(plugin.name))
-      throw new Error(`Plugin "${plugin.name}" is already installed`);
-    const context = this.createPluginContext();
-    this.plugins.set(plugin.name, {
-      plugin,
-      config: effectiveConfig,
-      context,
-    });
-    if (plugin.onInstall)
-      try {
-        plugin.onInstall(context);
-      } catch (error) {
-        console.error(
-          `[BlaC] Error installing plugin "${plugin.name}":`,
-          error,
-        );
-        this.plugins.delete(plugin.name);
-        throw error;
-      }
-    console.log(`[BlaC] Plugin "${plugin.name}" v${plugin.version} installed`);
-  }
-  /**
-   * Uninstall a plugin by name
-   * @param pluginName - The name of the plugin to uninstall
-   * @throws Error if plugin is not installed
-   */
-  uninstall(pluginName) {
-    const installed = this.plugins.get(pluginName);
-    if (!installed) throw new Error(`Plugin "${pluginName}" is not installed`);
-    if (installed.plugin.onUninstall)
-      try {
-        installed.plugin.onUninstall();
-      } catch (error) {
-        console.error(
-          `[BlaC] Error uninstalling plugin "${pluginName}":`,
-          error,
-        );
-      }
-    this.plugins.delete(pluginName);
-    console.log(`[BlaC] Plugin "${pluginName}" uninstalled`);
-  }
-  /**
-   * Get an installed plugin by name
-   * @param pluginName - The name of the plugin to retrieve
-   * @returns The plugin instance or undefined if not found
-   */
-  getPlugin(pluginName) {
-    return this.plugins.get(pluginName)?.plugin;
-  }
-  /**
-   * Get all installed plugins
-   * @returns Array of all installed plugins
-   */
-  getAllPlugins() {
-    return Array.from(this.plugins.values()).map((p) => p.plugin);
-  }
-  /**
-   * Check if a plugin is installed
-   * @param pluginName - The name of the plugin to check
-   * @returns true if the plugin is installed
-   */
-  hasPlugin(pluginName) {
-    return this.plugins.has(pluginName);
-  }
-  /**
-   * Uninstall all plugins
-   */
-  clear() {
-    for (const name of this.plugins.keys()) this.uninstall(name);
-  }
-  /**
-   * Setup lifecycle hooks to notify plugins
-   */
-  setupLifecycleHooks() {
-    this.registry.on('created', (instance) => {
-      this.notifyPlugins('onInstanceCreated', instance);
-    });
-    this.registry.on(
-      'stateChanged',
-      (instance, previousState, currentState, callstack) => {
-        this.notifyPlugins(
-          'onStateChanged',
-          instance,
-          previousState,
-          currentState,
-          callstack,
-        );
-      },
-    );
-    this.registry.on('disposed', (instance) => {
-      this.notifyPlugins('onInstanceDisposed', instance);
-    });
-    this.registry.on('refAcquired', (instance, refId) => {
-      this.notifyPlugins('onRefAcquired', instance, refId);
-    });
-    this.registry.on('refReleased', (instance, refId) => {
-      this.notifyPlugins('onRefReleased', instance, refId);
-    });
-  }
-  /**
-   * Notify all plugins of a lifecycle event
-   */
-  notifyPlugins(hookName, ...args) {
-    for (const { plugin, config, context } of this.plugins.values()) {
-      if (!config.enabled) continue;
-      const hook = plugin[hookName];
-      if (typeof hook === 'function')
-        try {
-          hook.apply(plugin, [...args, context]);
-        } catch (error) {
-          console.error(
-            `[BlaC] Error in plugin "${plugin.name}" ${hookName}:`,
-            error,
-          );
-        }
-    }
-  }
-  /**
-   * Create plugin context with safe API access
-   */
-  createPluginContext() {
-    return {
-      getInstanceMetadata: (instance) => {
-        return {
-          id: instance.instanceId,
-          className: instance.constructor.name,
-          isDisposed: instance.isDisposed,
-          name: instance.name,
-          lastStateChangeTimestamp: instance.lastUpdateTimestamp,
-          createdAt: instance.createdAt,
-          state: instance.state,
-          hydrationStatus: instance.hydrationStatus,
-          isHydrated: instance.isHydrated,
-          hydrationError: instance.hydrationError,
-          changedWhileHydrating: instance.changedWhileHydrating,
-          createdFrom: instance.createdFrom || void 0,
-        };
-      },
-      getState: (instance) => {
-        return instance.state;
-      },
-      getHydrationStatus: (instance) => {
-        return instance.hydrationStatus;
-      },
-      startHydration: (instance) => {
-        instance.beginHydration();
-      },
-      applyHydratedState: (instance, state) => {
-        return instance.applyHydratedState(state);
-      },
-      finishHydration: (instance) => {
-        instance.finishHydration();
-      },
-      failHydration: (instance, error) => {
-        instance.failHydration(error);
-      },
-      waitForHydration: (instance) => {
-        return instance.waitForHydration();
-      },
-      queryInstances: (typeClass) => {
-        return this.registry.getAll(typeClass);
-      },
-      getAllTypes: () => {
-        return this.registry.getTypes();
-      },
-      getStats: () => {
-        return this.registry.getStats();
-      },
-      getRefIds: (instanceId) => {
-        for (const Type of this.registry.getTypes()) {
-          const map = this.registry.getInstancesMap(Type);
-          for (const [, entry] of map)
-            if (entry.instance.instanceId === instanceId)
-              return Array.from(entry.refs.keys());
-        }
-        return [];
-      },
-    };
-  }
-  /**
-   * Check if plugin should be enabled based on environment
-   */
-  shouldEnablePlugin(config) {
-    if (!config.enabled) return false;
-    if (config.environment === 'all') return true;
-    return this.getCurrentEnvironment() === config.environment;
-  }
-  /**
-   * Get current environment
-   */
-  getCurrentEnvironment() {
-    if (typeof process !== 'undefined') {
-      if (process.env.NODE_ENV === 'test') return 'test';
-      if (process.env.NODE_ENV === 'production') return 'production';
-      return 'development';
-    }
-    return 'development';
-  }
-};
-/**
- * Create a plugin manager instance
- * @param registry - The StateContainerRegistry to monitor for lifecycle events
- * @returns A new PluginManager instance
- */
-function createPluginManager(registry) {
-  return new PluginManager(registry);
-}
-//#endregion
-//#region src/utils/static-props.ts
-/**
- * Utility functions for accessing static properties on StateContainer classes
- */
-/**
- * Get a static property from a class constructor
- * Type-safe helper that avoids (Type as any) casts
- *
- * @param Type - The class constructor
- * @param propName - The property name to access
- * @param defaultValue - Optional default value if property is undefined
- * @returns The property value or default
- */
-function getStaticProp(Type, propName, defaultValue) {
-  return Type[propName] ?? defaultValue;
-}
-/**
- * Check if a class is marked as keepAlive.
- * KeepAlive classes are never auto-disposed when ref count reaches 0.
- * @param Type - The class constructor to check
- * @returns true if the class has `static keepAlive = true`
- */
-function isKeepAliveClass(Type) {
-  return getStaticProp(Type, BLAC_STATIC_PROPS.KEEP_ALIVE) === true;
-}
-//#endregion
-//#region src/core/StateContainerRegistry.ts
-let autoRefIdCounter = 0;
-/**
- * Central registry for managing StateContainer instances.
- * Handles instance lifecycle, named ref tracking, and lifecycle event emission.
- *
- * @example
- * ```ts
- * const registry = new StateContainerRegistry();
- * const instance = registry.acquire(MyBloc);  // ownership, must release
- * const other = registry.ensure(OtherBloc);   // no ownership, bloc-to-bloc
- * registry.on('stateChanged', (container, prev, next) => {
- *   console.log('State changed:', prev, '->', next);
- * });
- * ```
- */
-var StateContainerRegistry = class {
-  constructor() {
-    this.instancesByConstructor = /* @__PURE__ */ new WeakMap();
-    this.types = /* @__PURE__ */ new Set();
-    this.registeredTypeNames = /* @__PURE__ */ new Set();
-    this.listeners = /* @__PURE__ */ new Map();
-  }
-  /**
-   * Register a type for lifecycle event tracking
-   * @param constructor - The StateContainer class constructor
-   */
-  registerType(constructor) {
-    this.types.add(constructor);
-  }
-  /**
-   * Register a StateContainer class with configuration
-   * @param constructor - The StateContainer class constructor
-   * @throws Error if type is already registered
-   */
-  register(constructor) {
-    const className = constructor.name;
-    if (this.registeredTypeNames.has(className))
-      throw new Error(
-        `${BLAC_ERROR_PREFIX} Type "${className}" is already registered`,
-      );
-    this.registeredTypeNames.add(className);
-    this.registerType(constructor);
-  }
-  ensureInstancesMap(Type) {
-    let instances = this.instancesByConstructor.get(Type);
-    if (!instances) {
-      instances = /* @__PURE__ */ new Map();
-      this.instancesByConstructor.set(Type, instances);
-    }
-    return instances;
-  }
-  /**
-   * Get the instances Map for a specific class (public API for stats/debugging)
-   */
-  getInstancesMap(Type) {
-    return this.instancesByConstructor.get(Type) || /* @__PURE__ */ new Map();
-  }
-  /**
-   * Acquire an instance with ref tracking (ownership semantics).
-   * Creates a new instance if one doesn't exist, or returns existing and adds a ref.
-   * You must call `release()` with the same refId when done.
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @param options - Acquisition options
-   * @param options.canCreate - Whether to create new instance if not found (default: true)
-   * @param options.countRef - Whether to add a reference (default: true)
-   * @param options.refId - Named reference ID for debugging; auto-generated if omitted
-   * @returns The state container instance
-   */
-  acquire(
-    Type,
-    instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY,
-    options = {},
-  ) {
-    const { canCreate = true, countRef = true } = options;
-    const config = { instanceId: instanceKey };
-    const instances = this.ensureInstancesMap(Type);
-    let entry = instances.get(instanceKey);
-    if (entry?.instance.isDisposed) {
-      instances.delete(instanceKey);
-      entry = void 0;
-    }
-    if (entry && countRef) {
-      const refId = options.refId ?? `_auto_${autoRefIdCounter++}`;
-      entry.refs.add(refId);
-      this.emit('refAcquired', entry.instance, refId);
-    }
-    if (entry) return entry.instance;
-    if (!canCreate)
-      throw new Error(
-        `${BLAC_ERROR_PREFIX} ${Type.name} instance "${instanceKey}" not found and creation is disabled.`,
-      );
-    const refId = countRef
-      ? (options.refId ?? `_auto_${autoRefIdCounter++}`)
-      : void 0;
-    const instance = new Type();
-    instance.initConfig(config);
-    instances.set(instanceKey, {
-      instance,
-      refs: new Set(refId ? [refId] : []),
-    });
-    this.registerType(Type);
-    if (refId) this.emit('refAcquired', instance, refId);
-    return instance;
-  }
-  /**
-   * Borrow an existing instance without adding a ref (borrowing semantics).
-   * Tracks cross-bloc dependency for reactive updates.
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns The state container instance
-   * @throws Error if instance doesn't exist
-   */
-  borrow(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    return this.acquire(Type, instanceKey, {
-      canCreate: false,
-      countRef: false,
-    });
-  }
-  /**
-   * Safely borrow an existing instance (borrowing semantics with error handling).
-   * Returns discriminated union for type-safe conditional access.
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns Discriminated union with either the instance or an error
-   */
-  borrowSafe(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    try {
-      return {
-        error: null,
-        instance: this.borrow(Type, instanceKey),
-      };
-    } catch (error) {
-      return {
-        error,
-        instance: null,
-      };
-    }
-  }
-  /**
-   * Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
-   * Gets existing instance OR creates it if it doesn't exist, without adding a ref.
-   * Tracks cross-bloc dependency for reactive updates.
-   *
-   * Use this in bloc-to-bloc communication when you need to ensure an instance exists
-   * but don't want to claim ownership (no ref added).
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns The state container instance
-   */
-  ensure(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    return this.acquire(Type, instanceKey, {
-      canCreate: true,
-      countRef: false,
-    });
-  }
-  /**
-   * Release a reference to an instance.
-   * Removes the ref and disposes when refs is empty (unless keepAlive).
-   * Releasing an already-removed refId is a no-op (idempotent).
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @param forceDispose - Force immediate disposal regardless of refs
-   * @param refId - The specific ref to remove; removes one arbitrary ref if omitted
-   */
-  release(
-    Type,
-    instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY,
-    forceDispose = false,
-    refId,
-  ) {
-    const instances = this.ensureInstancesMap(Type);
-    const entry = instances.get(instanceKey);
-    if (!entry) return;
-    if (forceDispose) {
-      if (!entry.instance.isDisposed) entry.instance.dispose();
-      instances.delete(instanceKey);
-      return;
-    }
-    let releasedRefId;
-    if (refId !== void 0) {
-      entry.refs.delete(refId);
-      releasedRefId = refId;
-    } else {
-      const first = entry.refs.values().next().value;
-      if (first !== void 0) {
-        entry.refs.delete(first);
-        releasedRefId = first;
-      }
-    }
-    if (releasedRefId) this.emit('refReleased', entry.instance, releasedRefId);
-    const keepAlive = isKeepAliveClass(Type);
-    if (entry.refs.size === 0 && !keepAlive) {
-      if (!entry.instance.isDisposed) entry.instance.dispose();
-      instances.delete(instanceKey);
-    }
-  }
-  /**
-   * Get all instances of a specific type.
-   * @param Type - The StateContainer class constructor
-   * @returns Array of all instances
-   */
-  getAll(Type) {
-    const instances = this.ensureInstancesMap(Type);
-    const result = [];
-    for (const entry of instances.values()) result.push(entry.instance);
-    return result;
-  }
-  /**
-   * Safely iterate over all instances of a type.
-   * Skips disposed instances and catches callback errors.
-   * @param Type - The StateContainer class constructor
-   * @param callback - Function to call for each instance
-   */
-  forEach(Type, callback) {
-    const instances = this.ensureInstancesMap(Type);
-    for (const entry of instances.values()) {
-      const instance = entry.instance;
-      if (!instance.isDisposed)
-        try {
-          callback(instance);
-        } catch (error) {
-          console.error(
-            `${BLAC_ERROR_PREFIX} forEach callback error for ${Type.name}:`,
-            error,
-          );
-        }
-    }
-  }
-  /**
-   * Clear all instances of a specific type (disposes them).
-   * @param Type - The StateContainer class constructor
-   */
-  clear(Type) {
-    const instances = this.ensureInstancesMap(Type);
-    for (const entry of instances.values())
-      if (!entry.instance.isDisposed) entry.instance.dispose();
-    instances.clear();
-  }
-  /**
-   * Get reference count for an instance (number of active refs).
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns Current ref count (0 if instance doesn't exist)
-   */
-  getRefCount(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    return this.ensureInstancesMap(Type).get(instanceKey)?.refs.size ?? 0;
-  }
-  /**
-   * Get all active reference IDs for an instance.
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns ReadonlySet of ref ID strings (empty if instance doesn't exist)
-   */
-  getRefIds(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    return (
-      this.ensureInstancesMap(Type).get(instanceKey)?.refs ??
-      /* @__PURE__ */ new Set()
-    );
-  }
-  /**
-   * Check if an instance exists.
-   * @param Type - The StateContainer class constructor
-   * @param instanceKey - Instance key (defaults to 'default')
-   * @returns true if instance exists
-   */
-  hasInstance(Type, instanceKey = BLAC_DEFAULTS.DEFAULT_INSTANCE_KEY) {
-    return this.ensureInstancesMap(Type).has(instanceKey);
-  }
-  /**
-   * Clear all instances from all types (for testing)
-   *
-   * Iterates all registered types and clears their instances.
-   * Also clears type tracking to reset the registry state.
-   */
-  clearAll() {
-    for (const Type of this.types) this.clear(Type);
-    this.types.clear();
-    this.registeredTypeNames.clear();
-  }
-  /**
-   * Get registry statistics for debugging.
-   * @returns Object with registeredTypes, totalInstances, and typeBreakdown
-   */
-  getStats() {
-    const typeBreakdown = {};
-    let totalInstances = 0;
-    for (const Type of this.types) {
-      const typeName = Type.name;
-      const count = this.getInstancesMap(Type).size;
-      typeBreakdown[typeName] = count;
-      totalInstances += count;
-    }
-    return {
-      registeredTypes: this.types.size,
-      totalInstances,
-      typeBreakdown,
-    };
-  }
-  /**
-   * Get all registered types (for plugin system).
-   * @returns Array of all registered StateContainer class constructors
-   */
-  getTypes() {
-    return Array.from(this.types);
-  }
-  /**
-   * Subscribe to lifecycle events
-   * @param event - The lifecycle event to listen for
-   * @param listener - The listener function to call when the event occurs
-   * @returns Unsubscribe function
-   */
-  on(event, listener) {
-    if (!this.listeners.has(event))
-      this.listeners.set(event, /* @__PURE__ */ new Set());
-    const instance = this.listeners.get(event);
-    if (!instance)
-      throw new Error(
-        `${BLAC_ERROR_PREFIX} Failed to register listener for event '${event}'`,
-      );
-    instance.add(listener);
-    return () => {
-      this.listeners.get(event)?.delete(listener);
-    };
-  }
-  /**
-   * Emit lifecycle event to all listeners
-   * @internal - Called by StateContainer lifecycle methods
-   */
-  emit(event, ...args) {
-    const listeners = this.listeners.get(event);
-    if (!listeners || listeners.size === 0) return;
-    for (const listener of listeners)
-      try {
-        listener(...args);
-      } catch (error) {
-        console.error(
-          `${BLAC_ERROR_PREFIX} Listener error for '${event}':`,
-          error,
-        );
-      }
-  }
-};
-/**
- * Global default registry instance
- */
-const globalRegistry = new StateContainerRegistry();
-/**
- * Global plugin manager (initialized lazily)
- */
-let _globalPluginManager = null;
-/**
- * Get the global plugin manager
- */
-function getPluginManager() {
-  if (!_globalPluginManager)
-    _globalPluginManager = createPluginManager(globalRegistry);
-  return _globalPluginManager;
-}
-//#endregion
-Object.defineProperty(exports, 'BLAC_DEFAULTS', {
-  enumerable: true,
-  get: function () {
-    return BLAC_DEFAULTS;
-  },
-});
-Object.defineProperty(exports, 'BLAC_ERROR_PREFIX', {
-  enumerable: true,
-  get: function () {
-    return BLAC_ERROR_PREFIX;
-  },
-});
-Object.defineProperty(exports, 'BLAC_STATIC_PROPS', {
-  enumerable: true,
-  get: function () {
-    return BLAC_STATIC_PROPS;
-  },
-});
-Object.defineProperty(exports, 'PluginManager', {
-  enumerable: true,
-  get: function () {
-    return PluginManager;
-  },
-});
-Object.defineProperty(exports, 'StateContainerRegistry', {
-  enumerable: true,
-  get: function () {
-    return StateContainerRegistry;
-  },
-});
-Object.defineProperty(exports, 'getPluginManager', {
-  enumerable: true,
-  get: function () {
-    return getPluginManager;
-  },
-});
-Object.defineProperty(exports, 'globalRegistry', {
-  enumerable: true,
-  get: function () {
-    return globalRegistry;
-  },
-});
-
-//# sourceMappingURL=StateContainerRegistry-v_prqMcI.cjs.map