@but212/atom-effect 0.30.1 → 0.32.0

package/dist/index.d.ts

@@ -1,510 +1,8 @@
-/**
- * Async operation states for public API and high-level checks.
- */
-export declare const AsyncState: Readonly<{
-    IDLE: "idle";
-    PENDING: "pending";
-    RESOLVED: "resolved";
-    REJECTED: "rejected";
-}>;
-
-/**
- * Async state values.
- */
-export declare type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState];
-
-/**
- * Creates a reactive atom holding mutable state.
- *
- * @param initialValue - The initial value of the atom.
- * @param options - Configuration options (sync: boolean).
- */
-export declare function atom<T>(initialValue: T, options?: AtomOptions): WritableAtom<T>;
-
-/**
- * Base error class for the Atom system.
- * Designed for high performance, traceability, and cycle protection.
- */
-export declare class AtomError extends Error {
-    readonly cause: unknown;
-    readonly recoverable: boolean;
-    readonly code?: string | undefined;
-    readonly name: string;
-    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string | undefined);
-    /**
-     * Returns the entire error chain as an array.
-     * Includes the circular node if a cycle is detected.
-     */
-    getChain(): Array<AtomError | Error | unknown>;
-    /**
-     * Serializes the error to a structured object for logging.
-     * Protected against circular references.
-     */
-    toJSON(seen?: Set<unknown>): AtomErrorJSON;
-    /**
-     * Internal helper to format wrapped messages consistently.
-     */
-    static format(source: string, context: string, message: string): string;
-}
-
-/**
- * Structured JSON representation of an AtomError.
- */
-declare interface AtomErrorJSON {
-    name: string;
-    message: string;
-    code?: string | undefined;
-    recoverable: boolean;
-    stack?: string | undefined;
-    cause?: unknown | undefined;
-}
-
-/**
- * Creates a two-way "lens" for a specific property path on an object-based atom.
- *
- * @example
- * const store = atom({ user: { name: 'Alice' } });
- * const nameLens = atomLens(store, 'user.name');
- * console.log(nameLens.value); // 'Alice'
- * nameLens.value = 'Bob'; // Updates store.user.name immutably
- */
-export declare function atomLens<T extends object, P extends Paths<T>>(atom: WritableAtom<T>, path: P): WritableAtom<PathValue<T, P>>;
-
-/**
- * Atom options.
- */
-export declare interface AtomOptions<T = unknown> {
-    /** Optional name for debugging. */
-    name?: string;
-    /** If true, subscribers are notified synchronously. Default: false (microtask scheduled). */
-    sync?: boolean;
-    /** Equality check. */
-    equal?: (a: T, b: T) => boolean;
-}
-
-/**
- * Groups multiple state updates into a single batch, delaying effects and computations
- * until the batch is closed.
- *
- * @param fn - The function containing state updates.
- * @returns The result of the function execution.
- * @throws {TypeError} If fn is not a function.
- */
-export declare function batch<T>(fn: () => T): T;
-
-/**
- * Global brand symbol for all reactive primitives.
- * Uses a bitwise mask for high-performance type identification.
- */
-declare const BRAND: unique symbol;
-
-/**
- * Composes an existing lens with a sub-path to create a deeper lens.
- */
-export declare const composeLens: <T extends object, P extends Paths<T>>(lens: WritableAtom<T>, path: P) => WritableAtom<PathValue<T, P>>;
-
-/**
- * Creates a computed value.
- * @param fn - Computation function
- * @param options - Options object
- */
-export declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): ComputedAtom<T>;
-
-export declare function computed<T>(fn: () => Promise<T>, options: ComputedOptions<T> & {
-    defaultValue: T;
-}): ComputedAtom<T>;
-
-/**
- * Computed atom interface.
- */
-export declare interface ComputedAtom<T = unknown> extends ReadonlyAtom<T>, Disposable_2 {
-    /* Excluded from this release type: [BRAND] */
-    readonly state: AsyncStateType;
-    readonly hasError: boolean;
-    readonly lastError: Error | null;
-    readonly isPending: boolean;
-    readonly isResolved: boolean;
-    readonly isValid: boolean;
-    /** List of errors encountered during computation. */
-    readonly errors: readonly Error[];
-    /** Invalidates atom. */
-    invalidate(): void;
-    dispose(): void;
-    [Symbol.dispose](): void;
-}
-
-/** Thrown when a computation fails. */
-export declare class ComputedError extends AtomError {
-    readonly name = "ComputedError";
-}
-
-/**
- * Computed options.
- */
-export declare interface ComputedOptions<T = unknown> {
-    /** Optional name for debugging. */
-    name?: string;
-    /** Equality check. */
-    equal?: (a: T, b: T) => boolean;
-    /** Initial value. */
-    defaultValue?: T;
-    /** Lazy evaluation. */
-    lazy?: boolean;
-    /** Error handler. */
-    onError?: (error: Error) => void;
-}
-
-/**
- * Debugging thresholds.
- */
-export declare const DEBUG_CONFIG: Readonly<{
-    WARN_INFINITE_LOOP: true;
-    EFFECT_FREQUENCY_WINDOW: 1000;
-    LOOP_THRESHOLD: 100;
-}>;
-
-declare interface DebugConfig {
-    enabled: boolean;
-    warnInfiniteLoop: boolean;
-    warn(condition: boolean, message: string): void;
-    attachDebugInfo(obj: object, type: string, id: number, customName?: string): void;
-    getDebugName(obj: object | null | undefined): string | undefined;
-    getDebugType(obj: object | null | undefined): string | undefined;
-    trackUpdate(id: DependencyId, name?: string): void;
-    registerNode(node: object & {
-        id: DependencyId;
-    }): void;
-    dumpGraph(): Record<string, unknown>[];
-}
-
-/**
- * Dependency interface.
- * Core contract for reactive nodes. All properties are required to ensure
- * high-performance access within the engine.
- *
- * @remarks
- * Internal fields (`version`, `flags`, `_lastSeenEpoch`) are part of the
- * engine contract between reactive nodes and must not be mutated externally.
- */
-export declare interface Dependency<T = unknown> {
-    /* Excluded from this release type: [BRAND] */
-    readonly id: DependencyId;
-    /* Excluded from this release type: version */
-    /* Excluded from this release type: flags */
-    /* Excluded from this release type: _lastSeenEpoch */
-    /* Excluded from this release type: isComputed */
-    /* Excluded from this release type: hasError */
-    /**
-     * Adds a subscriber to this dependency.
-     * The listener may optionally receive the new and previous values.
-     * @param listener - A callback or Subscriber object.
-     */
-    subscribe(listener: ((newValue?: T, oldValue?: T) => void) | Subscriber): () => void;
-    /**
-     * Non-reactive read of the current value.
-     */
-    peek(): T;
-    /**
-     * Current value accessor.
-     */
-    readonly value: T;
-}
-
-/**
- * Dependency ID.
- */
-declare type DependencyId = number;
-
-/**
- * Custom Disposable interface for explicit resource management.
- */
-declare interface Disposable_2 {
-    /**
-     * Cleans up the object and releases resources.
-     */
-    dispose(): void;
-    /**
-     * Support for explicit resource management (TS 5.2+).
-     */
-    [Symbol.dispose](): void;
-}
-export { Disposable_2 as Disposable }
-
-/**
- * Creates and starts an effect.
- *
- * @param fn - Effect function.
- * @param options - Configuration options.
- * @returns Effect instance.
- */
-export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
-
-/**
- * Effect cleanup function.
- */
-export declare type EffectCleanup = () => void;
-
-/** Thrown when an effect execution or cleanup fails. */
-export declare class EffectError extends AtomError {
-    readonly name = "EffectError";
-    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
-}
-
-/**
- * Effect function type.
- * Sync effects can return a cleanup function.
- * Async effects can return a promise that resolves to a cleanup function or void.
- */
-export declare type EffectFunction = () => (void | EffectCleanup) | Promise<void | EffectCleanup>;
-
-export declare interface EffectObject extends Disposable_2 {
-    /* Excluded from this release type: [BRAND] */
-    dispose(): void;
-    [Symbol.dispose](): void;
-    run(): void;
-    readonly isDisposed: boolean;
-    readonly executionCount: number;
-    readonly isExecuting: boolean;
-}
-
-export declare interface EffectOptions {
-    name?: string;
-    sync?: boolean;
-    maxExecutionsPerSecond?: number;
-    maxExecutionsPerFlush?: number;
-    onError?: (error: unknown) => void;
-}
-
-/**
- * Helper to retrieve a nested value from an object/array at a given path.
- */
-export declare function getPathValue(source: unknown, parts: string[]): unknown;
-
-/** Global scheduler instance. */
-export declare const globalScheduler: Scheduler_2;
-
-/**
- * Readonly atom check.
- */
-export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
-
-/**
- * Computed atom check.
- */
-export declare function isComputed(obj: unknown): obj is ComputedAtom;
-
-/**
- * Effect object check.
- */
-export declare function isEffect(obj: unknown): obj is EffectObject;
-
-/**
- * Creates a lens factory bound to a specific atom.
- */
-export declare const lensFor: <T extends object>(atom: WritableAtom<T>) => <P extends Paths<T>>(path: P) => WritableAtom<PathValue<T, P>>;
-
-/** Max recursion depth for dot-paths. */
-declare type MaxDepth = 8;
-
-/**
- * Generates a union of all possible dot-separated paths for a given type T.
- * Excludes prototype methods and stops at TerminalTypes.
- *
- * Used for `atomLens` to provide IDE autocomplete and type safety when
- * zooming into deeply nested reactive objects.
- */
-export declare type Paths<T, D extends unknown[] = []> = D['length'] extends MaxDepth ? never : T extends TerminalTypes ? never : T extends object ? {
-    [K in keyof T & (string | number)]: T[K] extends Function ? never : NonNullable<T[K]> extends object ? `${K}` | `${K}.${Paths<NonNullable<T[K]>, [...D, 1]>}` : `${K}`;
-}[keyof T & (string | number)] : never;
-
-/**
- * Resolves the type of a value at a specific dot-path P within type T.
- * Uses NonNullable to correctly handle optional (?) or nullable properties.
- *
- * Works in tandem with `Paths<T>` to ensure that lensed atoms have
- * the correct inferred type for the member they point to.
- */
-export declare type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? StringKeyToNumber<K> extends keyof NonNullable<T> ? PathValue<NonNullable<NonNullable<T>[StringKeyToNumber<K> & keyof NonNullable<T>]>, Rest> : never : StringKeyToNumber<P> extends keyof NonNullable<T> ? NonNullable<T>[StringKeyToNumber<P> & keyof NonNullable<T>] : never;
-
-/**
- * Readonly atom interface.
- */
-export declare interface ReadonlyAtom<T = unknown> {
-    /* Excluded from this release type: [BRAND] */
-    /** The current value of the atom. */
-    readonly value: T;
-    /**
-     * Subscribes to value changes.
-     * @param listener - Function called when value changes.
-     * @returns Unsubscribe function.
-     */
-    subscribe(listener: ((newValue?: T, oldValue?: T) => void) | Subscriber): () => void;
-    /**
-     * Non-reactive read.
-     */
-    peek(): T;
-    /**
-     * Returns the number of active subscribers.
-     */
-    subscriberCount(): number;
-}
-
-/**
- * The global debug singleton instance.
- * Automatically switches between development and production implementations
- * based on the environment configuration (IS_DEV).
- *
- * In production, this becomes a lightweight object with empty methods,
- * allowing engines to inline or ignore calls, effectively providing zero overhead.
- *
- * @public
- */
-export declare const runtimeDebug: DebugConfig;
-
-/**
- * Core Scheduler that manages asynchronous and synchronous task execution.
- *
- * Features:
- * - Double buffering for stable queue processing.
- * - Automatic job deduplication via Epoch tagging.
- * - Nested batching support with automatic coalescence.
- * - Microsecond-level scheduling via queueMicrotask.
- */
-declare class Scheduler_2 {
-    /** Double buffer to allow scheduling new jobs while processing the current queue. */
-    private _queueBuffer;
-    /** Pointer to the currently active buffer for ingestion. */
-    private _bufferIndex;
-    /** Current size of the active ingestion buffer. */
-    private _size;
-    /** Current internal epoch for job tagging. */
-    private _epoch;
-    /** Flag indicating the scheduler is currently draining a microtask loop. */
-    private _isProcessing;
-    /** Flag indicating a synchronous flush (batch end) is currently active. */
-    private _isFlushingSync;
-    /** Number of active nested batch contexts. */
-    private _batchDepth;
-    /** Temporary holding area for jobs scheduled during an active batch or sync flush. */
-    private _batchQueue;
-    /** Current number of jobs in the batch holding area. */
-    private _batchQueueSize;
-    /** Maximum allowed internal loop iterations before assuming an infinite loop. */
-    private _maxFlushIterations;
-    /** Optional callback fired when the scheduler drops jobs due to overflow. */
-    onOverflow: ((droppedCount: number) => void) | null;
-    private readonly _boundRunLoop;
-    /** Returns the total number of pending jobs (active + batched). */
-    get queueSize(): number;
-    /** Returns true if the scheduler is currently within a `batch()` scope. */
-    get isBatching(): boolean;
-    /**
-     * Schedules a job for execution.
-     * Jobs are deduplicated based on the current epoch; if the same job is scheduled twice
-     * in the same epoch, the second call is ignored.
-     *
-     * @param callback - The task to be executed.
-     */
-    schedule(callback: SchedulerJob): void;
-    /** Initiates an asynchronous flush via microtask. */
-    private _flush;
-    /** Internal microtask execution loop. */
-    private _runLoop;
-    /** Internal synchronous flush typically triggered at the end of a batch. */
-    _flushSync(): void;
-    /**
-     * Merges the temporal batch queue into the main active buffer.
-     * Increments the epoch to allow previously executed jobs to be re-scheduled if needed.
-     */
-    private _mergeBatchQueue;
-    /**
-     * Continuous loop that drains both main and batch queues.
-     * Processes until all queues are empty or max iterations reached.
-     */
-    private _drainQueue;
-    /** Executes all jobs currently in the primary buffer and swaps buffers. */
-    private _processQueue;
-    /** Resets the scheduler state on infinite loop detection and notifies via onOverflow. */
-    private _handleFlushOverflow;
-    /** Enters a new batching depth. */
-    startBatch(): void;
-    /**
-     * Decrements batching depth. If depth reaches 0, triggers a synchronous flush
-     * to apply all coherent updates collected during the batch.
-     */
-    endBatch(): void;
-    /** Configures the maximum safety iterations for the flush loop. */
-    setMaxFlushIterations(max: number): void;
-}
-
-/**
- * Scheduler configuration.
- */
-export declare const SCHEDULER_CONFIG: Readonly<{
-    MAX_EXECUTIONS_PER_SECOND: 1000;
-    MAX_EXECUTIONS_PER_EFFECT: 100;
-    MAX_EXECUTIONS_PER_FLUSH: 10000;
-    MAX_FLUSH_ITERATIONS: 1000;
-    MIN_FLUSH_ITERATIONS: 10;
-    BATCH_QUEUE_SHRINK_THRESHOLD: 1000;
-}>;
-
-/** Thrown by the execution engine or scheduler. */
-export declare class SchedulerError extends AtomError {
-    readonly name = "SchedulerError";
-    constructor(message: string, cause?: unknown, recoverable?: boolean, code?: string);
-}
-
-/** Union type representing any valid schedulable task. */
-declare type SchedulerJob = SchedulerJobFunction | SchedulerJobObject;
-
-/** Represents a job that can be executed by the scheduler via a function interface. */
-declare interface SchedulerJobFunction {
-    (): void;
-    /** Internal tracking for deduplication within the same epoch. */
-    _nextEpoch?: number | undefined;
-}
-
-declare interface SchedulerJobObject {
-    execute(): void;
-    /** Internal tracking for deduplication within the same epoch. */
-    _nextEpoch?: number | undefined;
-}
-
-/**
- * Internal recursive helper for creating deep immutable copies with structural sharing.
- * Only clones nodes along the path where changes occur.
- */
-export declare function setDeepValue(obj: unknown, keys: string[], index: number, value: unknown): unknown;
-
-/** Helper to convert numeric string to number for array indexing. */
-declare type StringKeyToNumber<S extends string> = S extends `${infer N extends number}` ? N : S;
-
-declare interface Subscriber {
-    execute(): void;
-}
-
-/** Types that should be treated as terminals (no further path exploration). */
-declare type TerminalTypes = Date | RegExp | Map<unknown, unknown> | Set<unknown> | Promise<unknown> | Function;
-
-/**
- * Executes a function without dependency tracking.
- *
- * @param fn - Function to execute.
- * @returns Result of `fn`.
- */
-export declare function untracked<T>(fn: () => T): T;
-
-/**
- * Writable atom interface.
- */
-export declare interface WritableAtom<T = unknown> extends ReadonlyAtom<T>, Disposable_2 {
-    value: T;
-    /**
-     * Cleans up the atom and releases resources.
-     */
-    dispose(): void;
-    [Symbol.dispose](): void;
-}
-
-export { }
+export { AsyncState, IS_DEV, SCHEDULER_CONFIG } from './constants';
+export type { Paths, PathValue } from './core';
+export { aeNextTick, atom, atomLens, batch, composeLens, computed, effect, getPathValue, lensFor, mergeAtoms, mergeLenses, scheduler as globalScheduler, setDeepValue, untracked, } from './core';
+export { AtomError, ComputedError, EffectError, SchedulerError, } from './errors';
+export { BRAND, BrandFlags } from './symbols';
+export type { AsyncStateType, AtomOptions, ComputedAtom, ComputedOptions, Dependency, Disposable, EffectCleanup, EffectFunction, EffectObject, EffectOptions, MergedDependencyValue, ReadonlyAtom, WritableAtom, } from './types';
+export { debug as runtimeDebug, isAtom, isComputed, isEffect, isPromise, isWritable, } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACL,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,WAAW,EACX,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,OAAO,EACP,UAAU,EACV,WAAW,EACX,SAAS,IAAI,eAAe,EAC5B,YAAY,EACZ,SAAS,GACV,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,eAAe,EACf,UAAU,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,KAAK,IAAI,YAAY,EACrB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,SAAS,CAAC"}