@blac/core 2.0.0-rc.0 → 2.0.0-rc.10

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

@@ -0,0 +1,33 @@
+import type { StateContainer } from '../core/StateContainer';
+import type { TrackerState, GetterTrackerState } from '../tracking';
+import type { ExtractState } from '../types/utilities';
+export interface AdapterState<TBloc extends StateContainer<any, any>> {
+    tracker: TrackerState<ExtractState<TBloc>> | null;
+    manualDepsCache: unknown[] | null;
+    getterTracker: GetterTrackerState | null;
+    proxiedBloc: TBloc | null;
+}
+export interface ManualDepsConfig<TBloc extends StateContainer<any, any>> {
+    dependencies: (state: any, bloc: TBloc) => unknown[];
+}
+export type SubscriptionCallback = () => void;
+export type SubscribeFunction = (callback: SubscriptionCallback) => () => void;
+export type SnapshotFunction<TState> = () => TState;
+export declare class ExternalDependencyManager {
+    private subscriptions;
+    private previousDeps;
+    private areDependenciesEqual;
+    updateSubscriptions(getterTracker: GetterTrackerState | null, rawInstance: StateContainer<any, any>, onGetterChange: () => void): boolean;
+    cleanup(): void;
+}
+export declare function createAutoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SubscribeFunction;
+export declare function createManualDepsSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;
+export declare function createNoTrackSubscribe<TBloc extends StateContainer<any, any>>(instance: TBloc): SubscribeFunction;
+export declare function createAutoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createManualDepsSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;
+export declare function createNoTrackSnapshot<TBloc extends StateContainer<any, any>>(instance: TBloc): SnapshotFunction<ExtractState<TBloc>>;
+export declare function initAutoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initManualDepsState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function initNoTrackState<TBloc extends StateContainer<any, any>>(instance: TBloc): AdapterState<TBloc>;
+export declare function disableGetterTracking<TBloc extends StateContainer<any, any>>(adapterState: AdapterState<TBloc>, rawInstance: TBloc): void;
+//# sourceMappingURL=framework-adapter.d.ts.map

package/dist/adapter/index.d.ts

@@ -1,3 +1,8 @@
-export * from './BlacAdapter';
-export * from './ProxyFactory';
+/**
+ * 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,40 @@
+import { StateContainer } from './StateContainer';
+export declare abstract class Cubit<S, P = undefined> extends StateContainer<S, P> {
+    constructor(initialState: S);
+    emit(newState: S): void;
+    update(updater: (current: S) => S): void;
+    patch: S extends object ? (partial: Partial<S>) => void : never;
+}
+export declare class CounterCubit extends Cubit<number> {
+    constructor();
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    addAmount: (amount: number) => void;
+}
+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,78 @@
+import { StateContainerRegistry } from './StateContainerRegistry';
+export interface StateContainerConfig {
+    name?: string;
+    debug?: boolean;
+    instanceId?: string;
+}
+type StateListener<S> = (state: S) => void;
+export type SystemEvent = 'propsUpdated' | 'stateChanged' | 'dispose';
+export interface SystemEventPayloads<S, P> {
+    propsUpdated: {
+        props: P;
+        previousProps: P | undefined;
+    };
+    stateChanged: {
+        state: S;
+        previousState: S;
+    };
+    dispose: void;
+}
+type SystemEventHandler<S, P, E extends SystemEvent> = (payload: SystemEventPayloads<S, P>[E]) => void;
+export declare abstract class StateContainer<S, P = undefined> {
+    static __excludeFromDevTools: boolean;
+    protected static _registry: StateContainerRegistry;
+    static getRegistry(): StateContainerRegistry;
+    static setRegistry(registry: StateContainerRegistry): void;
+    static register<T extends StateContainer<any>>(this: new (...args: any[]) => T, isolated?: boolean): void;
+    static resolve<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static get<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): T;
+    static getSafe<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): {
+        error: Error;
+        instance: null;
+    } | {
+        error: null;
+        instance: T;
+    };
+    static connect<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, constructorArgs?: any): T;
+    static release<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string, forceDispose?: boolean): void;
+    static getAll<T extends StateContainer<any>>(this: new (...args: any[]) => T): T[];
+    static forEach<T extends StateContainer<any>>(this: new (...args: any[]) => T, callback: (instance: T) => void): void;
+    static clear<T extends StateContainer<any>>(this: new (...args: any[]) => T): void;
+    static clearAllInstances(): void;
+    static getStats(): {
+        registeredTypes: number;
+        totalInstances: number;
+        typeBreakdown: Record<string, number>;
+    };
+    static getRefCount<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): number;
+    static hasInstance<T extends StateContainer<any>>(this: new (...args: any[]) => T, instanceKey?: string): boolean;
+    private _state;
+    private readonly listeners;
+    private _disposed;
+    private config;
+    private _props;
+    private readonly systemEventHandlers;
+    name: string;
+    debug: boolean;
+    instanceId: string;
+    createdAt: number;
+    get props(): P | undefined;
+    constructor(initialState: S);
+    initConfig(config: StateContainerConfig): void;
+    get state(): S;
+    get isDisposed(): boolean;
+    subscribe(listener: StateListener<S>): () => void;
+    dispose(): void;
+    protected emit(newState: S): void;
+    static enableStackTrace: boolean;
+    private captureStackTrace;
+    private formatStackLine;
+    private cleanFilePath;
+    lastUpdateTimestamp: number;
+    protected update(updater: (current: S) => S): void;
+    protected onSystemEvent: <E extends SystemEvent>(event: E, handler: SystemEventHandler<S, P, E>) => (() => void);
+    private emitSystemEvent;
+    updateProps(newProps: P): void;
+}
+export {};
+//# sourceMappingURL=StateContainer.d.ts.map

package/dist/core/StateContainerRegistry.d.ts

@@ -0,0 +1,119 @@
+import type { StateContainer } from './StateContainer';
+import type { Vertex } from './Vertex';
+export interface InstanceEntry<T = any> {
+    instance: T;
+    refCount: number;
+}
+export type LifecycleEvent = 'created' | 'stateChanged' | 'eventAdded' | 'disposed';
+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;
+export declare class StateContainerRegistry {
+    private readonly instancesByConstructor;
+    private readonly types;
+    private readonly typeConfigs;
+    private readonly listeners;
+    registerType<T extends StateContainer<any>>(constructor: new (...args: any[]) => T): void;
+    register<T extends StateContainer<any>>(constructor: new (...args: any[]) => T, isolated?: boolean): void;
+    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

package/dist/core/Vertex.d.ts

@@ -0,0 +1,74 @@
+import { StateContainer } from './StateContainer';
+import { BaseEvent } from '../types/events';
+export type EventHandler<E extends BaseEvent, S> = (event: E, emit: (state: S) => void) => void;
+export type EventConstructor<T extends BaseEvent = BaseEvent> = new (...args: never[]) => T;
+export declare abstract class Vertex<S, E extends BaseEvent = BaseEvent, P = undefined> extends StateContainer<S, P> {
+    private eventHandlers;
+    private isProcessing;
+    private eventQueue;
+    constructor(initialState: S);
+    protected on: <T extends E>(EventClass: EventConstructor<T>, handler: EventHandler<T, S>) => void;
+    add: (event: E) => void;
+    private processEvent;
+    private handleEvent;
+    protected onEventError(_event: E, _error: Error): void;
+}
+/**
+ * Example: Counter Events
+ */
+export declare class IncrementEvent implements BaseEvent {
+    readonly amount: number;
+    readonly type = "increment";
+    readonly timestamp: number;
+    constructor(amount?: number);
+}
+export declare class DecrementEvent implements BaseEvent {
+    readonly amount: number;
+    readonly type = "decrement";
+    readonly timestamp: number;
+    constructor(amount?: number);
+}
+export declare class ResetEvent implements BaseEvent {
+    readonly type = "reset";
+    readonly timestamp: number;
+}
+/**
+ * Example: Counter Vertex
+ * Demonstrates proper typing and event handling
+ */
+export declare class CounterVertex extends Vertex<number> {
+    constructor();
+    increment: (amount?: number) => void;
+    decrement: (amount?: number) => void;
+    reset: () => void;
+}
+/**
+ * Auth State and Events for testing async handlers
+ */
+export interface AuthState {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: {
+        id: string;
+        name: string;
+        email: string;
+    } | null;
+    error: string | null;
+}
+export declare class LoginEvent implements BaseEvent {
+    readonly email: string;
+    readonly password: string;
+    readonly type = "login";
+    readonly timestamp: number;
+    constructor(email: string, password: string);
+}
+export declare class LogoutEvent implements BaseEvent {
+    readonly type = "logout";
+    readonly timestamp: number;
+}
+export declare class AuthVertex extends Vertex<AuthState> {
+    constructor();
+    login: (email: string, password: string) => void;
+    logout: () => void;
+}
+//# sourceMappingURL=Vertex.d.ts.map

package/dist/decorators/blac.d.ts

@@ -0,0 +1,31 @@
+export type BlacOptions = {
+    isolated: true;
+} | {
+    keepAlive: true;
+} | {
+    excludeFromDevTools: true;
+};
+/**
+ * Decorator to configure StateContainer classes.
+ *
+ * @example Decorator syntax (requires experimentalDecorators or TC39 decorators)
+ * ```typescript
+ * @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)
+ * ```typescript
+ * 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;
+//# sourceMappingURL=blac.d.ts.map

package/dist/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export { blac, type BlacOptions } from './blac';
+//# sourceMappingURL=index.d.ts.map