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

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/framework-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/framework-adapter.ts"],"names":[],"mappings":"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"}

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/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}

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/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;OAEG;;IAGH;;OAEG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAG,QAAiB,CAAC"}

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/Cubit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cubit.d.ts","sourceRoot":"","sources":["../../src/core/Cubit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;GAKG;AACH,8BAAsB,KAAK,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACtD;;;OAGG;gBACS,YAAY,EAAE,CAAC;IAI3B;;OAEG;IACI,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI;IAI9B;;OAEG;IACI,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI;IAI/C;;;;;;;;;;;;;OAaG;IACI,KAAK,EAKN,CAAC,SAAS,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC;CAChE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK,CAAC,MAAM,CAAC;;IAK7C,SAAS,QAAO,IAAI,CAElB;IAEF,SAAS,QAAO,IAAI,CAElB;IAEF,KAAK,QAAO,IAAI,CAEd;IAEF,SAAS,GAAI,QAAQ,MAAM,KAAG,IAAI,CAEhC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1D,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,SAAU,SAAQ,KAAK,CAAC,SAAS,CAAC;IAC7C,MAAM,CAAC,SAAS,UAAQ;IACxB,OAAO,CAAC,MAAM,CAAK;;IAUnB,OAAO,GAAI,MAAM,MAAM,KAAG,IAAI,CAQ5B;IAEF,UAAU,GAAI,IAAI,MAAM,KAAG,IAAI,CAO7B;IAEF,UAAU,GAAI,IAAI,MAAM,KAAG,IAAI,CAK7B;IAEF,SAAS,GAAI,QAAQ,SAAS,CAAC,QAAQ,CAAC,KAAG,IAAI,CAE7C;IAEF,UAAU,GAAI,WAAW,OAAO,KAAG,IAAI,CAErC;IAEF,IAAI,YAAY;YAnDG,MAAM;cAAQ,MAAM;cAAQ,OAAO;QAgErD;IAED,IAAI,eAAe,WAElB;CACF"}

package/dist/core/StateContainer.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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);
+    initiConfig(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;
+    /**
+     * 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/StateContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateContainer.d.ts","sourceRoot":"","sources":["../../src/core/StateContainer.ts"],"names":[],"mappings":"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"}