@blac/core 2.0.0-rc.6 → 2.0.0-rc.9

package/dist/adapter/framework-adapter.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Framework Adapter - Reusable logic for integrating BlaC with any reactive framework
+ *
+ * This module provides framework-agnostic utilities for:
+ * - Subscription management (auto-tracking, manual deps, no-tracking modes)
+ * - Snapshot generation (state proxies with tracking)
+ * - External dependency management (cross-bloc subscriptions)
+ * - Change detection (state and getter tracking)
+ *
+ * Can be used to integrate BlaC with React, Vue, Solid, Svelte, Angular, etc.
+ */
+import type { StateContainer } from '../core/StateContainer';
+import type { TrackerState, GetterTrackerState } from '../tracking';
+import type { ExtractState } from '../types/utilities';
+/**
+ * Framework-agnostic adapter state
+ * Frameworks should store this in their component state mechanism
+ */
+export interface AdapterState<TBloc extends StateContainer<any>> {
+    /** State property tracker */
+    tracker: TrackerState<ExtractState<TBloc>> | null;
+    /** Manual dependencies cache */
+    manualDepsCache: unknown[] | null;
+    /** Getter tracking state */
+    getterTracker: GetterTrackerState | null;
+    /** Cached proxied bloc instance */
+    proxiedBloc: TBloc | null;
+}
+/**
+ * Configuration for manual dependencies mode
+ */
+export interface ManualDepsConfig<TBloc extends StateContainer<any>> {
+    dependencies: (state: any, bloc: TBloc) => unknown[];
+}
+/**
+ * Subscription callback type
+ * Called when the framework should re-render
+ */
+export type SubscriptionCallback = () => void;
+/**
+ * Subscription function type
+ * Returns an unsubscribe function
+ */
+export type SubscribeFunction = (callback: SubscriptionCallback) => () => void;
+/**
+ * Snapshot function type
+ * Returns the current state (possibly proxied)
+ */
+export type SnapshotFunction<TState> = () => TState;
+/**
+ * External dependency manager
+ * Handles subscriptions to external blocs accessed in getters
+ */
+export declare class ExternalDependencyManager {
+    private subscriptions;
+    private previousDeps;
+    /**
+     * Check if dependencies have changed
+     */
+    private areDependenciesEqual;
+    /**
+     * Update external subscriptions
+     * @param getterTracker - The getter tracker state
+     * @param rawInstance - The raw bloc instance (exclude from subscriptions)
+     * @param onGetterChange - Callback when external getter changes
+     * @returns Whether subscriptions were updated
+     */
+    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainer<any>, onGetterChange: () => void): boolean;
+    /**
+     * Cleanup all subscriptions
+     */
+    cleanup(): void;
+}
+/**
+ * Create a subscription function for auto-tracking mode
+ */
+export declare function createAutoTrackSubscribe<TBloc extends StateContainer<any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SubscribeFunction;
+/**
+ * Create a subscription function for manual dependencies mode
+ */
+export declare function createManualDepsSubscribe<TBloc extends StateContainer<any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+/**
+ * Create a subscription function for no-tracking mode
+ */
+export declare function createNoTrackSubscribe<TBloc extends StateContainer<any>>(instance: TBloc): SubscribeFunction;
+/**
+ * Create a snapshot function for auto-tracking mode
+ */
+export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+/**
+ * Create a snapshot function for manual dependencies mode
+ */
+export declare function createManualDepsSnapshot<TBloc extends StateContainer<any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+/**
+ * Create a snapshot function for no-tracking mode
+ */
+export declare function createNoTrackSnapshot<TBloc extends StateContainer<any>>(instance: TBloc): SnapshotFunction<ExtractState<TBloc>>;
+/**
+ * Initialize adapter state for auto-tracking mode
+ */
+export declare function initAutoTrackState<TBloc extends StateContainer<any>>(instance: TBloc): AdapterState<TBloc>;
+/**
+ * Initialize adapter state for manual dependencies mode
+ */
+export declare function initManualDepsState<TBloc extends StateContainer<any>>(instance: TBloc): AdapterState<TBloc>;
+/**
+ * Initialize adapter state for no-tracking mode
+ */
+export declare function initNoTrackState<TBloc extends StateContainer<any>>(instance: TBloc): AdapterState<TBloc>;
+/**
+ * Disable getter tracking (call after render completes)
+ */
+export declare function disableGetterTracking<TBloc extends StateContainer<any>>(adapterState: AdapterState<TBloc>, rawInstance: TBloc): void;
+//# sourceMappingURL=framework-adapter.d.ts.map

package/dist/adapter/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Framework Adapter
+ *
+ * Reusable utilities for integrating BlaC with any reactive framework.
+ * Use these to build integrations for React, Vue, Solid, Svelte, Angular, etc.
+ */
+export { type AdapterState, type ManualDepsConfig, type SubscriptionCallback, type SubscribeFunction, type SnapshotFunction, ExternalDependencyManager, createAutoTrackSubscribe, createManualDepsSubscribe, createNoTrackSubscribe, createAutoTrackSnapshot, createManualDepsSnapshot, createNoTrackSnapshot, initAutoTrackState, initManualDepsState, initNoTrackState, disableGetterTracking, } from './framework-adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/constants.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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]";
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/Cubit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Cubit - Simple state container with direct state emission
+ *
+ * This validates that our StateContainer design can support
+ * the simple Cubit pattern from the original BlaC.
+ */
+import { StateContainer } from './StateContainer';
+/**
+ * Cubit is a simple state container that allows direct state emission
+ *
+ * Unlike StateContainer (where emit is protected), Cubit exposes emit and update
+ * as public methods to allow direct state management.
+ */
+export declare abstract class Cubit<S> extends StateContainer<S> {
+    /**
+     * Create a new Cubit
+     * @param initialState Initial state value
+     */
+    constructor(initialState: S);
+    /**
+     * Emit a new state (public override of protected parent method)
+     */
+    emit(newState: S): void;
+    /**
+     * Update state using a function (public override of protected parent method)
+     */
+    update(updater: (current: S) => S): void;
+    /**
+     * Patch state with partial updates (shallow merge)
+     * Only available when state is an object type
+     * Arrow function to maintain correct 'this' binding in React
+     *
+     * @example
+     * ```typescript
+     * // Update single field
+     * this.patch({ count: 5 });
+     *
+     * // Update multiple fields
+     * this.patch({ count: 5, name: 'Updated' });
+     * ```
+     */
+    patch: S extends object ? (partial: Partial<S>) => void : never;
+}
+/**
+ * Example: Counter Cubit
+ */
+export declare class CounterCubit extends Cubit<number> {
+    constructor();
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    addAmount: (amount: number) => void;
+}
+/**
+ * Example: Complex State Cubit
+ */
+export interface TodoState {
+    todos: Array<{
+        id: string;
+        text: string;
+        done: boolean;
+    }>;
+    filter: 'all' | 'active' | 'completed';
+    isLoading: boolean;
+}
+export declare class TodoCubit extends Cubit<TodoState> {
+    static keepAlive: boolean;
+    private nextId;
+    constructor();
+    addTodo: (text: string) => void;
+    toggleTodo: (id: string) => void;
+    removeTodo: (id: string) => void;
+    setFilter: (filter: TodoState["filter"]) => void;
+    setLoading: (isLoading: boolean) => void;
+    get visibleTodos(): {
+        id: string;
+        text: string;
+        done: boolean;
+    }[];
+    get activeTodoCount(): number;
+}
+//# sourceMappingURL=Cubit.d.ts.map

package/dist/core/StateContainer.d.ts

@@ -0,0 +1,205 @@
+/**
+ * StateContainer - Clean, minimal state management container
+ *
+ * Responsibilities:
+ * - State storage and updates
+ * - Change notifications to subscribers
+ * - Lifecycle management
+ */
+import { StateContainerRegistry } from './StateContainerRegistry';
+/**
+ * Configuration options for StateContainer
+ */
+export interface StateContainerConfig {
+    /** Container name for debugging */
+    name?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom instance identifier */
+    instanceId?: string;
+}
+/**
+ * Listener function for state changes
+ */
+type StateListener<S> = (state: S) => void;
+/**
+ * Base abstract class for all state containers
+ */
+export declare abstract class StateContainer<S> {
+    /**
+     * Exclude this class from DevTools reporting
+     * Set to true for internal/DevTools-related Blocs to prevent infinite loops
+     */
+    static __excludeFromDevTools: boolean;
+    /**
+     * Global registry for lifecycle events and instance management
+     */
+    protected static _registry: StateContainerRegistry;
+    /**
+     * Get the global registry (mainly for testing)
+     */
+    static getRegistry(): StateContainerRegistry;
+    /**
+     * Set a custom registry (mainly for testing)
+     *
+     * Clears all instances before switching to ensure clean test isolation.
+     */
+    static setRegistry(registry: StateContainerRegistry): void;
+    /**
+     * Register a type as isolated or shared
+     */
+    static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+    /**
+     * Resolve an instance with ref counting (ownership semantics)
+     *
+     * Delegates to the global registry for instance management.
+     *
+     * @param instanceKey - Optional instance key for shared instances
+     * @param constructorArgs - Constructor arguments
+     * @returns Instance with incremented ref count
+     */
+    static resolve<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Get an existing instance without ref counting (borrowing semantics)
+     * Delegates to the global registry.
+     */
+    static get<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): T;
+    /**
+     * Safely get an existing instance (borrowing semantics with error handling)
+     * Delegates to the global registry.
+     */
+    static getSafe<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    /**
+     * Connect to an instance with borrowing semantics (for B2B 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).
+     *
+     * Delegates to the global registry.
+     *
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param constructorArgs - Constructor arguments (only used if creating new instance)
+     * @returns The bloc instance
+     */
+    static connect<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Release a reference to an instance
+     * Delegates to the global registry.
+     */
+    static release<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of this type
+     * Delegates to the global registry.
+     */
+    static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    /**
+     * Safely iterate over all instances of this type
+     * Delegates to the global registry.
+     */
+    static forEach<T extends StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    /**
+     * Clear all instances of this type
+     * Delegates to the global registry.
+     */
+    static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+    /**
+     * Clear all instances from all types (for testing)
+     * Delegates to the global registry.
+     */
+    static clearAllInstances(): void;
+    /**
+     * Get registry statistics (for debugging)
+     * Delegates to the global registry.
+     */
+    static getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get reference count for an instance
+     * Delegates to the global registry.
+     */
+    static getRefCount<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists
+     * Delegates to the global registry.
+     */
+    static hasInstance<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    private _state;
+    private readonly listeners;
+    private _disposed;
+    private config;
+    name: string;
+    debug: boolean;
+    instanceId: string;
+    createdAt: number;
+    /**
+     * Create a new StateContainer
+     */
+    constructor(initialState: S);
+    initConfig(config: StateContainerConfig): void;
+    /**
+     * Get the current state
+     */
+    get state(): S;
+    /**
+     * Check if disposed
+     */
+    get isDisposed(): boolean;
+    /**
+     * Subscribe to state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: StateListener<S>): () => void;
+    /**
+     * Dispose the container
+     */
+    dispose(): void;
+    /**
+     * Emit a new state (with change detection)
+     */
+    protected emit(newState: S): void;
+    /**
+     * Enable stack trace capture in development
+     * Defaults to true, but can be disabled to improve performance
+     */
+    static enableStackTrace: boolean;
+    /**
+     * Capture stack trace for debugging
+     * Can be overridden to disable in production
+     */
+    private captureStackTrace;
+    /**
+     * Format a single stack trace line for better readability
+     * Removes URL prefixes, query params, and cleans up the output
+     */
+    private formatStackLine;
+    /**
+     * Clean up file path by removing URL prefixes and query params
+     */
+    private cleanFilePath;
+    lastUpdateTimestamp: number;
+    /**
+     * Update state using a function
+     */
+    protected update(updater: (current: S) => S): void;
+    /**
+     * Optional disposal hook for subclasses
+     */
+    protected onDispose?(): void;
+    /**
+     * Optional state change hook for subclasses
+     */
+    protected onStateChange?(newState: S, previousState: S): void;
+}
+export {};
+//# sourceMappingURL=StateContainer.d.ts.map

package/dist/core/StateContainerRegistry.d.ts

@@ -0,0 +1,176 @@
+/**
+ * StateContainerRegistry - Centralized instance and lifecycle management
+ *
+ * Responsibilities:
+ * - Instance storage and management (WeakMap per constructor)
+ * - Type registration and tracking
+ * - Lifecycle event notifications (plugin system)
+ * - Global operations (clearAllInstances)
+ */
+import type { StateContainer } from './StateContainer';
+import type { Vertex } from './Vertex';
+/**
+ * Internal entry for instance storage
+ * Each entry tracks an instance and its reference count
+ */
+export interface InstanceEntry<T = any> {
+    instance: T;
+    refCount: number;
+}
+/**
+ * Lifecycle events that can be observed
+ */
+export type LifecycleEvent = 'created' | 'stateChanged' | 'eventAdded' | 'disposed';
+/**
+ * Listener function types for each lifecycle event
+ */
+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 'eventAdded' ? (container: Vertex<any, any>, event: any) => void : E extends 'disposed' ? (container: StateContainer<any>) => void : never;
+/**
+ * Registry for coordinating StateContainer lifecycle and managing instances
+ *
+ * Centralizes all instance management using WeakMap to ensure proper isolation.
+ */
+export declare class StateContainerRegistry {
+    /**
+     * Global storage for all instance Maps, keyed by constructor
+     *
+     * IMPORTANT: JavaScript/TypeScript static properties are inherited by reference,
+     * meaning all subclasses would share the same Map. To ensure each subclass has
+     * its own instance storage, we use a WeakMap keyed by the constructor function.
+     *
+     * This approach guarantees:
+     * - CounterBloc instances are separate from UserBloc instances
+     * - Each class owns and manages its own instances
+     * - Automatic garbage collection when classes are no longer referenced
+     */
+    private readonly instancesByConstructor;
+    /**
+     * Strong Set for tracking all registered types
+     * Used for clearAllInstances() and getStats()
+     */
+    private readonly types;
+    /**
+     * Type configurations (isolated flag)
+     */
+    private readonly typeConfigs;
+    /**
+     * Lifecycle event listeners
+     */
+    private readonly listeners;
+    /**
+     * Register a type for tracking
+     * Called automatically on first instance creation
+     */
+    registerType<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    /**
+     * Register a type with isolation mode (explicit registration)
+     */
+    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    /**
+     * Get the instances Map for a specific class
+     * Creates a new Map on first access.
+     */
+    private ensureInstancesMap;
+    /**
+     * Get the instances Map for a specific class (public API for stats/debugging)
+     */
+    getInstancesMap<T extends StateContainer<any>>(Type: new (...args: any[]) => T): Map<string, InstanceEntry>;
+    /**
+     * Resolve an instance with ref counting (ownership semantics)
+     */
+    resolve<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Get an existing instance without ref counting (borrowing semantics)
+     * @throws Error if instance doesn't exist
+     */
+    get<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): T;
+    /**
+     * Safely get an existing instance (borrowing semantics with error handling)
+     * Returns discriminated union for type-safe conditional access
+     */
+    getSafe<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    /**
+     * Connect to an instance with borrowing semantics (for B2B 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 bloc class constructor
+     * @param instanceKey - Optional instance key (defaults to 'default')
+     * @param constructorArgs - Constructor arguments (only used if creating new instance)
+     * @returns The bloc instance
+     */
+    connect<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    /**
+     * Release a reference to an instance
+     */
+    release<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    /**
+     * Get all instances of a specific type
+     */
+    getAll<T extends StateContainer<any>>(Type: new (...args: any[]) => T): T[];
+    /**
+     * Safely iterate over all instances of a type
+     */
+    forEach<T extends StateContainer<any>>(Type: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    /**
+     * Clear all instances of a specific type
+     */
+    clear<T extends StateContainer<any>>(Type: new (...args: any[]) => T): void;
+    /**
+     * Get reference count for an instance
+     */
+    getRefCount<T extends StateContainer<any>>(Type: new (...args: any[]) => T, instanceKey?: string): number;
+    /**
+     * Check if an instance exists
+     */
+    hasInstance<T extends StateContainer<any>>(Type: new (...args: any[]) => 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)
+     */
+    getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    /**
+     * Get all registered types (for plugin system)
+     */
+    getTypes(): Array<new (...args: any[]) => StateContainer<any>>;
+    /**
+     * 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/Vertex 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;
+//# sourceMappingURL=StateContainerRegistry.d.ts.map