@blac/core 2.0.3 → 2.0.5

package/README.md

@@ -1,5 +1,7 @@
 # @blac/core
 
+> ⚠️ **Warning:** This project is currently under active development. The API may change in future releases. Use with caution in production environments.
+
 Core state management library implementing the BloC pattern for TypeScript applications.
 
 ## Installation

package/dist/constants.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Default configuration constants for BlaC
+ *
+ * Centralized location for all magic numbers and default values.
+ */
+/**
+ * Default configuration constants for BlaC
+ */
+export declare const BLAC_DEFAULTS: {
+    /**
+     * Default instance key for shared instances
+     */
+    readonly DEFAULT_INSTANCE_KEY: "default";
+    /**
+     * Maximum getter nesting depth (prevents infinite recursion)
+     */
+    readonly MAX_GETTER_DEPTH: 10;
+    /**
+     * Default cleanup interval for subscriptions (30 seconds)
+     */
+    readonly CLEANUP_INTERVAL_MS: 30000;
+    /**
+     * Cleanup interval for weak reference stage (10 seconds)
+     */
+    readonly WEAKREF_CLEANUP_INTERVAL_MS: 10000;
+    /**
+     * Default maximum subscriptions per container
+     */
+    readonly MAX_SUBSCRIPTIONS: 1000;
+    /**
+     * Maximum subscriptions for high-performance mode
+     */
+    readonly MAX_SUBSCRIPTIONS_HIGH_PERF: 10000;
+    /**
+     * Default timeout for pipeline execution (5 seconds)
+     */
+    readonly PIPELINE_TIMEOUT_MS: 5000;
+    /**
+     * Cleanup interval for high-performance mode (5 seconds)
+     */
+    readonly CLEANUP_INTERVAL_HIGH_PERF_MS: 5000;
+    /**
+     * Maximum number of stages in a pipeline
+     */
+    readonly MAX_PIPELINE_STAGES: 30;
+};
+/**
+ * Static property names for StateContainer classes
+ * Used for feature flags and configuration on bloc classes
+ */
+export declare const BLAC_STATIC_PROPS: {
+    /**
+     * Mark a bloc as isolated (each component gets its own instance)
+     */
+    readonly ISOLATED: "isolated";
+    /**
+     * Mark a bloc to never be auto-disposed (kept alive permanently)
+     */
+    readonly KEEP_ALIVE: "keepAlive";
+    /**
+     * Exclude a bloc from DevTools reporting (prevents infinite loops)
+     */
+    readonly EXCLUDE_FROM_DEVTOOLS: "__excludeFromDevTools";
+};
+/**
+ * ID generation patterns and constants
+ */
+export declare const BLAC_ID_PATTERNS: {
+    /**
+     * Prefix for isolated instance keys
+     */
+    readonly ISOLATED_PREFIX: "isolated-";
+    /**
+     * Length of generated ID portion (9 characters from base36)
+     */
+    readonly ID_LENGTH: 9;
+};
+/**
+ * Standard error message prefix
+ */
+export declare const BLAC_ERROR_PREFIX: "[BlaC]";

package/dist/core/Cubit.d.ts

@@ -0,0 +1,24 @@
+import { StateContainer } from './StateContainer';
+/**
+ * Simple state container with direct state emission.
+ * Extends StateContainer with public methods for emitting and updating state.
+ *
+ * @template S - State type
+ */
+export declare abstract class Cubit<S extends object = any> extends StateContainer<S> {
+    constructor(initialState: S);
+    /**
+     * Replace state with a new value and notify all listeners
+     * @param newState - The new state value
+     */
+    emit(newState: S): void;
+    /**
+     * Transform current state using an updater function and emit the new state
+     * @param updater - Function that receives current state and returns new state
+     */
+    update(updater: (current: S) => S): void;
+    /**
+     * Merge partial state changes into current state (only for object states)
+     */
+    patch: S extends object ? (partial: Partial<S>) => void : never;
+}

package/dist/core/StateContainer.d.ts

@@ -0,0 +1,127 @@
+import type { StateContainerConstructor } from '../types/utilities';
+/**
+ * Configuration options for initializing a StateContainer instance
+ */
+export interface StateContainerConfig {
+    /** Display name for the instance (defaults to class name) */
+    name?: string;
+    /** Enable debug logging for this instance */
+    debug?: boolean;
+    /** Custom instance identifier */
+    instanceId?: string;
+}
+/**
+ * Listener function for state changes
+ * @internal
+ */
+type StateListener<S> = (state: S) => void;
+/**
+ * System events emitted by StateContainer lifecycle
+ */
+export type SystemEvent = 'stateChanged' | 'dispose';
+/**
+ * Payload types for each system event
+ * @template S - State type
+ */
+export interface SystemEventPayloads<S> {
+    /** Emitted when state changes via emit() or update() */
+    stateChanged: {
+        state: S;
+        previousState: S;
+    };
+    /** Emitted when the instance is disposed */
+    dispose: void;
+}
+/**
+ * Handler function for system events
+ * @internal
+ */
+type SystemEventHandler<S, E extends SystemEvent> = (payload: SystemEventPayloads<S>[E]) => void;
+/**
+ * Abstract base class for all state containers in BlaC.
+ * Provides lifecycle management, subscription handling, ref counting,
+ * and integration with the global registry.
+ *
+ * @template S - State type managed by this container
+ *
+ * @example
+ * ```ts
+ * class CounterBloc extends StateContainer<{ count: number }> {
+ *   constructor() {
+ *     super({ count: 0 });
+ *   }
+ *   increment() {
+ *     this.emit({ count: this.state.count + 1 });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StateContainer<S extends object = any> {
+    static __excludeFromDevTools: boolean;
+    static enableStackTrace: boolean;
+    private _state;
+    private readonly listeners;
+    private _disposed;
+    private config;
+    private readonly systemEventHandlers;
+    /** Display name for this instance */
+    name: string;
+    /** Whether debug logging is enabled */
+    debug: boolean;
+    /** Unique identifier for this instance */
+    instanceId: string;
+    /** Timestamp when this instance was created */
+    createdAt: number;
+    private _dependencies;
+    get dependencies(): ReadonlyMap<StateContainerConstructor, string>;
+    protected depend<T extends StateContainerConstructor>(Type: T, instanceKey?: string): () => InstanceType<T>;
+    constructor(initialState: S);
+    /**
+     * Initialize configuration for this instance.
+     * Called by the registry after construction.
+     * @param config - Configuration options
+     */
+    initConfig(config: StateContainerConfig): void;
+    /** Current state value */
+    get state(): Readonly<S>;
+    /** Whether this instance has been disposed */
+    get isDisposed(): boolean;
+    /**
+     * Subscribe to state changes
+     * @param listener - Function called when state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: StateListener<S>): () => void;
+    /**
+     * Dispose this instance and clean up resources.
+     * Clears all listeners and emits the 'dispose' system event.
+     */
+    dispose(): void;
+    /**
+     * Emit a new state value and notify all listeners.
+     * @param newState - The new state value
+     * @protected
+     */
+    protected emit(newState: S): void;
+    private captureStackTrace;
+    private formatStackLine;
+    private cleanFilePath;
+    /** Timestamp of the last state update */
+    lastUpdateTimestamp: number;
+    /**
+     * Update state using a transform function.
+     * @param updater - Function that receives current state and returns new state
+     * @protected
+     */
+    protected update(updater: (current: S) => S): void;
+    /**
+     * Subscribe to system lifecycle events.
+     * @param event - The event type to listen for
+     * @param handler - Handler function called when event occurs
+     * @returns Unsubscribe function
+     * @protected
+     */
+    protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, E>) => (() => void);
+    private emitSystemEvent;
+}
+export {};

package/dist/core/StateContainerRegistry.d.ts

@@ -0,0 +1,189 @@
+import type { StateContainer } from './StateContainer';
+import { InstanceReadonlyState, StateContainerConstructor } from '../types/utilities';
+/**
+ * Entry in the instance registry, tracking the instance and its reference count
+ * @template T - Instance type
+ */
+export interface InstanceEntry<T = any> {
+    /** The state container instance */
+    instance: T;
+    /** Number of active references to this instance */
+    refCount: number;
+}
+/**
+ * Lifecycle events emitted by the registry
+ */
+export type LifecycleEvent = 'created' | 'stateChanged' | 'disposed';
+/**
+ * Listener function type for each lifecycle event
+ * @template E - The lifecycle event type
+ */
+export type LifecycleListener<E extends LifecycleEvent> = E extends 'created' ? (container: StateContainer<any>) => void : E extends 'stateChanged' ? (container: StateContainer<any>, previousState: any, currentState: any, callstack?: string) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+/**
+ * Central registry for managing StateContainer instances.
+ * Handles instance lifecycle, ref counting, 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);
+ * });
+ * ```
+ */
+export declare class StateContainerRegistry {
+    private readonly instancesByConstructor;
+    private readonly types;
+    private readonly typeConfigs;
+    private readonly listeners;
+    /**
+     * Register a type for lifecycle event tracking
+     * @param constructor - The StateContainer class constructor
+     */
+    registerType<T extends StateContainerConstructor>(constructor: T): void;
+    /**
+     * Register a StateContainer class with configuration
+     * @param constructor - The StateContainer class constructor
+     * @param isolated - Whether instances should be isolated (component-scoped)
+     * @throws Error if type is already registered
+     */
+    register<T extends StateContainerConstructor>(constructor: T, isolated?: boolean): void;
+    private ensureInstancesMap;
+    /**
+     * Get the instances Map for a specific class (public API for stats/debugging)
+     */
+    getInstancesMap<T extends StateContainerConstructor>(Type: T): Map<string, InstanceEntry>;
+    /**
+     * Acquire an instance with ref counting (ownership semantics).
+     * Creates a new instance if one doesn't exist, or returns existing and increments ref count.
+     * You must call `release()` when done to decrement the ref count.
+     * @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 increment ref count (default: true)
+     * @returns The state container instance
+     */
+    acquire<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string, options?: {
+        canCreate?: boolean;
+        countRef?: boolean;
+    }): InstanceType<T>;
+    /**
+     * Borrow an existing instance without incrementing ref count (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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * 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<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: InstanceType<T>;
+    };
+    /**
+     * Ensure an instance exists without taking ownership (for bloc-to-bloc communication).
+     * Gets existing instance OR creates it if it doesn't exist, without incrementing ref count.
+     * 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 count increment).
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns The state container instance
+     */
+    ensure<T extends StateContainerConstructor = StateContainerConstructor>(Type: T, instanceKey?: string): InstanceType<T>;
+    /**
+     * Release a reference to an instance.
+     * Decrements ref count and disposes when it reaches 0 (unless keepAlive).
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @param forceDispose - Force immediate disposal regardless of ref count
+     */
+    release<T extends StateContainerConstructor>(Type: T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of a specific type.
+     * @param Type - The StateContainer class constructor
+     * @returns Array of all instances
+     */
+    getAll<T extends StateContainerConstructor>(Type: T): InstanceReadonlyState<T>[];
+    /**
+     * 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<T extends StateContainerConstructor>(Type: T, callback: (instance: InstanceReadonlyState<T>) => void): void;
+    /**
+     * Clear all instances of a specific type (disposes them).
+     * @param Type - The StateContainer class constructor
+     */
+    clear<T extends StateContainerConstructor>(Type: T): void;
+    /**
+     * Get reference count for an instance.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns Current ref count (0 if instance doesn't exist)
+     */
+    getRefCount<T extends StateContainerConstructor>(Type: T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists.
+     * @param Type - The StateContainer class constructor
+     * @param instanceKey - Instance key (defaults to 'default')
+     * @returns true if instance exists
+     */
+    hasInstance<T extends StateContainerConstructor>(Type: T, instanceKey?: string): boolean;
+    /**
+     * 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(): void;
+    /**
+     * Get registry statistics for debugging.
+     * @returns Object with registeredTypes, totalInstances, and typeBreakdown
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system).
+     * @returns Array of all registered StateContainer class constructors
+     */
+    getTypes(): StateContainerConstructor[];
+    /**
+     * 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<E extends LifecycleEvent>(event: E, listener: LifecycleListener<E>): () => void;
+    /**
+     * Emit lifecycle event to all listeners
+     * @internal - Called by StateContainer lifecycle methods
+     */
+    emit(event: LifecycleEvent, ...args: any[]): void;
+}
+/**
+ * Global default registry instance
+ */
+export declare const globalRegistry: StateContainerRegistry;
+/**
+ * Get the global plugin manager
+ */
+export declare function getPluginManager(): any;

package/dist/debug.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Debug/Advanced Subpath Export
+ *
+ * Advanced registry introspection and debugging utilities.
+ * Import from '@blac/core/debug'
+ *
+ * These utilities are intended for debugging, testing, and advanced use cases.
+ * Most applications don't need these - use the main '@blac/core' exports instead.
+ *
+ * @example
+ * ```typescript
+ * import { getStats, globalRegistry, hasInstance } from '@blac/core/debug';
+ *
+ * // Get registry statistics
+ * const stats = getStats();
+ * console.log(`Total instances: ${stats.totalInstances}`);
+ *
+ * // Check if an instance exists
+ * if (hasInstance(UserBloc)) {
+ *   console.log('UserBloc is registered');
+ * }
+ *
+ * // Iterate over all instances of a type
+ * forEach(UserBloc, (instance) => {
+ *   console.log(instance.state);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { hasInstance, getRefCount, getAll, forEach } from './registry/queries';
+export { register } from './registry/management';
+export { getRegistry, setRegistry, getStats } from './registry/config';
+export { globalRegistry } from './core/StateContainerRegistry';
+export type { LifecycleEvent, LifecycleListener, InstanceEntry, } from './core/StateContainerRegistry';

package/dist/decorators/blac.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration options for the @blac decorator.
+ * Only one option can be specified at a time (union type).
+ */
+export type BlacOptions = 
+/** Mark bloc as isolated (each component gets its own instance) */
+{
+    isolated: true;
+}
+/** Mark bloc to never be auto-disposed when ref count reaches 0 */
+ | {
+    keepAlive: true;
+}
+/** Exclude bloc from DevTools tracking (prevents infinite loops) */
+ | {
+    excludeFromDevTools: true;
+};
+/**
+ * Decorator to configure StateContainer classes.
+ *
+ * @example Decorator syntax (requires experimentalDecorators or TC39 decorators)
+ * ```ts
+ * @blac({ isolated: true })
+ * class FormBloc extends Cubit<FormState> {}
+ *
+ * @blac({ keepAlive: true })
+ * class AuthBloc extends Cubit<AuthState> {}
+ *
+ * @blac({ excludeFromDevTools: true })
+ * class InternalBloc extends Cubit<InternalState> {}
+ * ```
+ *
+ * @example Function syntax (no decorator support needed)
+ * ```ts
+ * const FormBloc = blac({ isolated: true })(
+ *   class extends Cubit<FormState> {}
+ * );
+ * ```
+ */
+export declare function blac(options: BlacOptions): <T extends new (...args: any[]) => any>(target: T, _context?: ClassDecoratorContext) => T;

package/dist/decorators/index.d.ts

@@ -0,0 +1 @@
+export { blac, type BlacOptions } from './blac';