@but212/atom-effect 0.30.1 → 0.32.0

package/dist/constants.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Compound bitmasks for multi-state validation and bulk resets.
+ *
+ * Optimization: Bulk Validation
+ * Using compound masks reduces the number of bitwise comparisons in hot paths
+ * (e.g., checking if a node is in any async state).
+ *
+ * @internal
+ */
+export declare const STATE_MASKS: Readonly<{
+    /** Covers all asynchronous lifecycle states. */
+    ASYNC_STATE: number;
+    /** Covers all states indicating a requirement for re-computation. */
+    COMPUTED_DIRTY_MASK: number;
+}>;
+/**
+ * Asynchronous operation states for public API consumption.
+ *
+ * When to use:
+ * - To verify or branch logic based on the status of an asynchronous atom or computed node.
+ *
+ * @example
+ * ```typescript
+ * import { AsyncState } from '@but212/atom-effect';
+ *
+ * if (userProfile.status === AsyncState.PENDING) {
+ *   showSpinner();
+ * }
+ * ```
+ */
+export declare const AsyncState: Readonly<{
+    IDLE: string;
+    PENDING: string;
+    RESOLVED: string;
+    REJECTED: string;
+}>;
+/**
+ * Logic: Shared State Interface
+ * Defines the bitmask contract for Effect-type nodes.
+ * @internal
+ */
+export declare const EFFECT_STATE_FLAGS: Readonly<{
+    DISPOSED: number;
+    EXECUTING: number;
+}>;
+/**
+ * Logic: Shared State Interface
+ * Defines the bitmask contract for Computed-type nodes.
+ * @internal
+ */
+export declare const COMPUTED_STATE_FLAGS: Readonly<{
+    DISPOSED: number;
+    IS_COMPUTED: number;
+    DIRTY: number;
+    IDLE: number;
+    PENDING: number;
+    RESOLVED: number;
+    REJECTED: number;
+    RECOMPUTING: number;
+    HAS_ERROR: number;
+    FORCE_COMPUTE: number;
+}>;
+/**
+ * Logic: Shared State Interface
+ * Defines the bitmask contract for Atom-type nodes.
+ * @internal
+ */
+export declare const ATOM_STATE_FLAGS: Readonly<{
+    DISPOSED: number;
+    SYNC: number;
+    NOTIFICATION_SCHEDULED: number;
+}>;
+/**
+ * Global configuration parameters for the Scheduler.
+ *
+ * Caution: Modification of these thresholds can lead to instability,
+ * memory leaks, or execution overflows in complex dependency graphs.
+ */
+export declare const SCHEDULER_CONFIG: Readonly<{
+    /**
+     * Reason: Prevents infinite loops or runaway effects from freezing the main thread.
+     */
+    MAX_EXECUTIONS_PER_SECOND: number;
+    /**
+     * Reason: Detects and stops circular dependencies within a single microtask.
+     */
+    MAX_EXECUTIONS_PER_EFFECT: number;
+    /**
+     * Reason: Limits the total workload per flush to maintain frame-rate stability.
+     */
+    MAX_EXECUTIONS_PER_FLUSH: number;
+    /**
+     * Reason: Safety break for the drain-loop to prevent stack overflows or infinite flushing.
+     */
+    MAX_FLUSH_ITERATIONS: number;
+    /**
+     * Optimization: Batching
+     * Ensures a minimum number of iterations are processed to allow for nested batched updates.
+     */
+    MIN_FLUSH_ITERATIONS: number;
+    /**
+     * Optimization: Memory Pressure
+     * Threshold for shrinking the internal batch queue to release memory back to the heap.
+     */
+    BATCH_QUEUE_SHRINK_THRESHOLD: number;
+}>;
+/**
+ * Optimization: V8 SMI (Small Integer) Limit
+ *
+ * Values within this range (up to 30-bit signed) are stored directly in CPU registers
+ * by V8, bypassing heap allocation and boxing overhead.
+ *
+ * @internal
+ */
+export declare const SMI_MAX = 1073741823;
+/**
+ * Thresholds for development-time diagnostics.
+ * @internal
+ */
+export declare const DEBUG_CONFIG: Readonly<{
+    /** Enables console warnings when potential infinite loops are detected. */
+    WARN_INFINITE_LOOP: true;
+    /** The time window (ms) for monitoring update frequency. */
+    EFFECT_FREQUENCY_WINDOW: number;
+    /** The update count limit before triggering a loop warning. */
+    LOOP_THRESHOLD: number;
+}>;
+/**
+ * Sentinel values for epoch-based staleness tracking.
+ *
+ * Logic: Drift Detection
+ * Epochs are used to determine if a dependency has changed since the last
+ * computation without needing deep comparison.
+ *
+ * @internal
+ */
+export declare const EPOCH_CONSTANTS: Readonly<{
+    /** Initial state indicating no computation has occurred. */
+    UNINITIALIZED: -1;
+    /** Reset floor for epoch counters to avoid 0/falsy confusion. */
+    MIN: 1;
+}>;
+/**
+ * Indicates if the library is running in a development environment.
+ * When true, additional validation, diagnostic warnings, and loop protections are active.
+ */
+export declare const IS_DEV: boolean;
+/**
+ * Optimization: Shared Immutable Empty State
+ *
+ * Constraint: Must remain immutable to prevent memory leaks and unexpected
+ * side-effects in subscriber logic that expects an array structure.
+ *
+ * @internal
+ */
+export declare const EMPTY_ERROR_ARRAY: readonly Error[];
+//# 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":"AA+CA;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;IACtB,gDAAgD;;IAEhD,qEAAqE;;EAErE,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU;;;;;EAKY,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;EAG7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;EAW/B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;EAI3B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;OAEG;;IAEH;;OAEG;;IAGH;;OAEG;;IAEH;;OAEG;;IAEH;;;OAGG;;IAGH;;;OAGG;;EAEuB,CAAC;AAE7B;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,aAAa,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,YAAY;IACvB,2EAA2E;;IAE3E,4DAA4D;;IAE5D,+DAA+D;;EAEpB,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;IAC1B,4DAA4D;;IAE5D,iEAAiE;;EAEjE,CAAC;AAyCH;;;GAGG;AACH,eAAO,MAAM,MAAM,SACgE,CAAC;AAIpF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,KAAK,EAAsB,CAAC"}

package/dist/core/atom.d.ts

@@ -0,0 +1,19 @@
+import { AtomOptions, WritableAtom } from '../types';
+/**
+ * Creates a reactive atom holding mutable state.
+ *
+ * When to use:
+ * - As a primary source of truth for local or global state.
+ * - When state needs to be updated manually via `.value = ...`.
+ *
+ * @param initialValue - The starting value.
+ * @param options - Configuration for custom equality or synchronous delivery.
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * count.value++; // Triggers downstream updates
+ * ```
+ */
+export declare function atom<T>(initialValue: T, options?: AtomOptions<T>): WritableAtom<T>;
+//# sourceMappingURL=atom.d.ts.map

package/dist/core/atom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../../src/core/atom.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAiJzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAEtF"}

package/dist/core/base.d.ts

@@ -0,0 +1,136 @@
+import { SlotBuffer } from '@but212/atom-effect-utils';
+import { DependencyId, Subscriber } from '../types';
+import { DepBufferState } from './buffers';
+import { Subscription } from './tracking';
+/**
+ * A unified base class for all reactive primitives, including Atoms, Computeds, and Effects.
+ *
+ * When to use:
+ * - As an internal base for implementing new reactive primitives.
+ * - When a custom primitive requires integration with the core dependency graph.
+ *
+ * Optimization:
+ * Designed with a fixed field layout to maintain Hidden Class Monomorphism in V8.
+ * Avoid adding dynamic properties to instances to prevent de-optimization.
+ *
+ * @template T - The type of value produced by the node, used for subscriber notifications.
+ */
+export declare abstract class ReactiveNode<T> {
+    /**
+     * Internal bitfield representing the current state (Dirty, Computed, Disposed).
+     * Logic: Direct bitwise operations are used for high-frequency state checks.
+     */
+    flags: number;
+    /**
+     * A monotonically increasing counter representing the version of the node's value.
+     * Logic: Allows consumers to quickly verify if their cached values are stale.
+     */
+    version: number;
+    /**
+     * The epoch ID of the last time this node was visited during a dependency walk.
+     * Logic: Prevents redundant visits and infinite loops during graph traversal.
+     */
+    _lastSeenEpoch: number;
+    /**
+     * A tag used by the scheduler to deduplicate execution within a single flush cycle.
+     * @internal
+     */
+    _nextEpoch: number | undefined;
+    /**
+     * Unique identifier used for debugging and graph traversal.
+     * Optimization: Uses SMI (Small Integer) range for memory efficiency and faster comparisons.
+     */
+    readonly id: DependencyId;
+    /**
+     * Buffered storage for active subscribers.
+     * Logic: Uses `SlotBuffer` to support O(1) removal and deferred structural updates.
+     * @internal
+     */
+    _slots: SlotBuffer<Subscription<T>> | null;
+    /**
+     * Buffered storage for captured dependencies.
+     * @internal
+     */
+    _deps: DepBufferState | null;
+    constructor();
+    /**
+     * Indicates whether the node has been explicitly disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Indicates whether the node is a computed atom.
+     */
+    get isComputed(): boolean;
+    /**
+     * Indicates whether the node is currently notifying subscribers.
+     */
+    get isNotifying(): boolean;
+    private _hasFlag;
+    /**
+     * Indicates whether the node or its dependency sub-graph is currently in an error state.
+     * @internal
+     */
+    get hasError(): boolean;
+    /**
+     * Registers a subscriber to be notified when the node's value changes.
+     *
+     * When to use:
+     * - To observe value changes manually outside of reactive contexts (e.g., in UI adapters).
+     *
+     * @param listener - A callback function or a Subscriber object.
+     * @returns A cleanup function to terminate the subscription.
+     * @throws {AtomError} If the provided listener is not a function or a valid Subscriber.
+     *
+     * @example
+     * ```typescript
+     * const unsub = node.subscribe((next, prev) => {
+     *   console.log(`Value changed from ${prev} to ${next}`);
+     * });
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    subscribe(listener: ((newValue?: T, oldValue?: T) => void) | Subscriber): () => void;
+    private _hasSubscription;
+    /**
+     * Internal removal of a subscription link.
+     *
+     * Caution: Compaction is deferred if a notification loop is currently active to
+     * prevent index shifting during iteration.
+     */
+    protected _unsubscribe(link: Subscription<T>): void;
+    /**
+     * Returns the number of active subscribers for this node.
+     *
+     * When to use:
+     * - To monitor subscription health or detect leaks during development.
+     */
+    subscriberCount(): number;
+    /**
+     * Dispatches notifications to all registered subscribers.
+     *
+     * Logic:
+     * Increments the `_notifying` guard to protect the subscriber buffer from
+     * structural changes during iteration. Error handling is encapsulated per subscriber
+     * to ensure a single failing listener does not terminate the entire notification cycle.
+     */
+    protected _notifySubscribers(newValue: T | undefined, oldValue: T | undefined): void;
+    /**
+     * Determines if the node requires re-evaluation due to dependency changes.
+     * Logic: Checks the status of the cached dependency buffer.
+     */
+    protected _isDirty(): boolean;
+    /**
+     * Performs a shallow validation of immediate dependencies.
+     * Logic: Used for fast path guards that must not trigger re-computation.
+     * @internal
+     */
+    protected _isShallowDirty(): boolean;
+    /**
+     * Performs an exhaustive validation of the full dependency chain.
+     * Required for Computeds and Effects to handle deep dependency invalidation.
+     */
+    protected abstract _deepDirtyCheck(): boolean;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/core/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/core/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAGvD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAExD,OAAO,EAAE,KAAK,cAAc,EAAuC,MAAM,WAAW,CAAC;AACrF,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,8BAAsB,YAAY,CAAC,CAAC;IAClC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAE1B;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACH,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;;IAc7B;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,CAAC,QAAQ;IAIhB;;;OAGG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAMD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,UAAU,GAAG,MAAM,IAAI;IA8BpF,OAAO,CAAC,gBAAgB;IAQxB;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAQnD;;;;;OAKG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI;IAqBpF;;;OAGG;IACH,SAAS,CAAC,QAAQ,IAAI,OAAO;IAI7B;;;;OAIG;IACH,SAAS,CAAC,eAAe,IAAI,OAAO;IAIpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,OAAO;CAC9C"}

package/dist/core/buffers.d.ts

@@ -0,0 +1,113 @@
+import { SlotBuffer } from '@but212/atom-effect-utils';
+import { Dependency } from '../types';
+import { DependencyLink } from './tracking';
+/** @internal */
+export interface Indexer {
+    get(dep: Dependency): number | undefined;
+    set(dep: Dependency, index: number): void;
+    delete(dep: Dependency): void;
+}
+/**
+ * Logic: Subscription Reconciliation State
+ * Orchestrates the transition of dependencies between execution cycles.
+ * @internal
+ */
+export interface DepBufferState {
+    /**
+     * Ordered sequence of active subscriptions.
+     * Optimization: Uses SlotBuffer for contiguous memory and fast iteration.
+     */
+    slots: SlotBuffer<DependencyLink>;
+    /**
+     * Optimization: O(1) Lookup
+     * Always present via Indexer interface to avoid branching.
+     * Switched to NullIndexer when inactive.
+     */
+    map: Indexer;
+    /**
+     * Optimization: Skip Check
+     * When false, indicates no computed nodes are present, allowing the engine
+     * to skip recursive dirty validation.
+     */
+    hasComputeds: boolean;
+}
+/**
+ * Factory for dependency buffers.
+ * @internal
+ */
+export declare function createDepBuffer(): DepBufferState;
+/**
+ * Resets diagnostic flags before a new tracking phase.
+ * @internal
+ */
+export declare function prepareTracking(state: DepBufferState): void;
+/**
+ * Logic: Subscription Reuse (Claiming)
+ * Attempts to locate and move an existing subscription to the current
+ * tracking index.
+ *
+ * Why:
+ * Re-attaching listeners is expensive. Reusing the `unsub` handle from a
+ * previous run maintains the reactive connection without triggering
+ * subscriber count changes.
+ *
+ * Strategy:
+ * 1. Check if the current slot already holds the dependency (Fast Path).
+ * 2. Look ahead using the lookup map or linear search.
+ * 3. If found, swap the link to the front to preserve order for the next run.
+ *
+ * @internal
+ */
+export declare function claimExisting(state: DepBufferState, dep: Dependency, trackIndex: number): boolean;
+/**
+ * Logic: Displaced Occupant Preservation
+ * Inserts a new link at the current index. If an existing link is displaced,
+ * it is pushed to the tail so it can be reclaimed later in the same cycle.
+ * @internal
+ */
+export declare function insertNew(state: DepBufferState, trackIdx: number, link: DependencyLink): void;
+/**
+ * Atomic mutation that synchronizes the O(1) lookup map with the slot buffer.
+ * @internal
+ */
+export declare function depBufferSetAt(state: DepBufferState, index: number, item: DependencyLink | null): void;
+/**
+ * Atomic append operation that maintains the lookup map.
+ * @internal
+ */
+export declare function depBufferPush(state: DepBufferState, item: DependencyLink): number;
+/**
+ * Logic: Dirty Propagation Check
+ * @internal
+ */
+export declare function isBufferDirty(state: DepBufferState): boolean;
+/**
+ * Logic: Push-Path Validation
+ * A non-recursive check used during the notification phase to avoid
+ * re-entrant computation cascades.
+ *
+ * It returns true if:
+ * 1. Any dependency version has already changed.
+ * 2. Any dependency is already marked as DIRTY.
+ *
+ * @internal
+ */
+export declare function isBufferShallowDirty(state: DepBufferState): boolean;
+/**
+ * Logic: Post-Tracking Cleanup
+ * Removes and unsubscribes from all dependencies that were not reclaimed
+ * during the last tracking cycle.
+ *
+ * Constraint: Memory Integrity
+ * Failure to invoke `link.unsub()` results in "Ghost Executions" where
+ * disposed or inactive nodes continue to react to state changes.
+ *
+ * @internal
+ */
+export declare function depBufferTruncateFrom(state: DepBufferState, index: number): void;
+/**
+ * Releases all subscriptions and resets the buffer to an empty state.
+ * @internal
+ */
+export declare function disposeAll(state: DepBufferState): void;
+//# sourceMappingURL=buffers.d.ts.map

package/dist/core/buffers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffers.d.ts","sourceRoot":"","sources":["../../src/core/buffers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,gBAAgB;AAChB,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;CAC/B;AAUD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAClC;;;;OAIG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAMhD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAwBjG;AAkBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAO7F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,IAAI,CASN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAOjF;AA+BD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAc5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAcnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAuBhF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAGtD"}

package/dist/core/computed.d.ts

@@ -0,0 +1,84 @@
+import { ComputedAtom, ComputedOptions, Dependency, MergedDependencyValue } from '../types';
+import { DepBufferState } from './buffers';
+/**
+ * Logic: Computed Result Resolution
+ * Determines the final value or error to return based on current flags and cache.
+ * @internal
+ */
+export declare function resolveComputedResult<T>(flags: number, value: T, error: Error | null, defaultValue: T): T;
+/**
+ * Logic: Re-computation Heuristics
+ * Determines if a node requires re-evaluation based on its state and dependencies.
+ * @internal
+ */
+export declare function shouldRecompute(flags: number, deps: DepBufferState): boolean;
+/** @internal */
+interface InternalComputedNode {
+    readonly id: number;
+    readonly flags: number;
+    readonly lastError: Error | null;
+    readonly _deps: DepBufferState | null;
+}
+/**
+ * Logic: Iterative Graph Traversal
+ * Crawls the dependency graph to collect errors.
+ * @internal
+ */
+export declare function collectErrorsRecursive(startNode: InternalComputedNode, stopOnFirst: boolean): Error[];
+/**
+ * Creates a reactive computation derived from other atoms or computed nodes.
+ *
+ * When to use:
+ * - To define values that automatically update when their dependencies change.
+ * - To optimize performance through caching of expensive calculations.
+ * - To transform or aggregate raw state for UI presentation.
+ *
+ * @example
+ * ```typescript
+ * const count = atom(1);
+ * const doubled = computed(() => count.value * 2);
+ * ```
+ */
+export declare function computed<T>(fn: () => T, options?: ComputedOptions<T>): ComputedAtom<T>;
+/**
+ * Creates an asynchronous reactive computation.
+ *
+ * When to use:
+ * - For logic involving fetch, database queries, or long-running tasks.
+ *
+ * Attention:
+ * A `defaultValue` is mandatory for async computations to provide a valid
+ * state while the Promise is PENDING.
+ *
+ * @example
+ * ```typescript
+ * const user = computed(
+ *   async () => fetchUser(userId.value),
+ *   { defaultValue: null }
+ * );
+ * ```
+ */
+export declare function computed<T>(fn: () => Promise<T>, options: ComputedOptions<T> & {
+    defaultValue: T;
+}): ComputedAtom<T>;
+/**
+ * Combines multiple object-based atoms into a single computed atom with a flattened type.
+ *
+ * This utility merges the value types of all input atoms into a single
+ * unified object type using the {@link Merge} utility.
+ *
+ * @param atoms - A variadic list of atoms or computed nodes to merge.
+ *
+ * @example
+ * ```typescript
+ * const a = atom({ x: 1 });
+ * const b = atom({ y: 2 });
+ * const c = computed(() => ({ z: 3 }));
+ *
+ * const combined = mergeAtoms(a, b, c);
+ * // combined.value is { x: number; y: number; z: number }
+ * ```
+ */
+export declare function mergeAtoms<T extends Dependency<unknown>[]>(...atoms: T): ComputedAtom<MergedDependencyValue<T>>;
+export {};
+//# sourceMappingURL=computed.d.ts.map

package/dist/core/computed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/core/computed.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,YAAY,EACZ,eAAe,EACf,UAAU,EACV,qBAAqB,EAEtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAGL,KAAK,cAAc,EAMpB,MAAM,WAAW,CAAC;AA4CnB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,YAAY,EAAE,CAAC,GACd,CAAC,CAiBH;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAQ5E;AAED,gBAAgB;AAChB,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CACvC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,oBAAoB,EAC/B,WAAW,EAAE,OAAO,GACnB,KAAK,EAAE,CA6BT;AA6YD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AACxF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,YAAY,EAAE,CAAC,CAAA;CAAE,GAChD,YAAY,CAAC,CAAC,CAAC,CAAC;AAQnB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,EACxD,GAAG,KAAK,EAAE,CAAC,GACV,YAAY,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAExC"}

package/dist/core/effect.d.ts

@@ -0,0 +1,52 @@
+import { EffectFunction, EffectObject, EffectOptions } from '../types';
+/**
+ * Internal state for tracking effect execution budgets.
+ * @internal
+ */
+export interface EffectBudgetState {
+    loopCount: number;
+    lastFlushEpoch: number;
+    windowCount: number;
+    windowStart: number;
+    totalExecutions: number;
+}
+/**
+ * Factory for effect budget state.
+ * @internal
+ */
+export declare function createEffectBudgetState(): EffectBudgetState;
+/**
+ * Logic: Effect Budget Validation
+ * Ensures an effect doesn't run too many times in a single flush cycle,
+ * preventing infinite loops.
+ * @internal
+ */
+export declare function validateEffectBudget(state: EffectBudgetState, maxExecutionsPerFlush: number, currentFlushEpoch: number, incrementGlobalFlushCount: () => number, onAbort: (type: 'per-effect' | 'global') => never): void;
+/**
+ * Logic: Frequency Limiter
+ * Throttles effects that fire too rapidly in development mode.
+ * @internal
+ */
+export declare function checkEffectFrequencyLimit(state: EffectBudgetState, maxExecutions: number, onLimitExceeded: () => never): void;
+/**
+ * Creates a reactive side-effect.
+ *
+ * When to use:
+ * - To synchronize reactive state with the DOM or external APIs.
+ * - To perform logging or diagnostic tasks.
+ * - To manage timers or subscriptions that depend on atom values.
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * effect(() => {
+ *   const el = document.getElementById('display')!;
+ *   el.textContent = `Value: ${count.value}`;
+ *
+ *   // Optional teardown
+ *   return () => console.log('Cleaning up effect...');
+ * });
+ * ```
+ */
+export declare function effect(fn: EffectFunction, options?: EffectOptions): EffectObject;
+//# sourceMappingURL=effect.d.ts.map

package/dist/core/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../src/core/effect.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAc,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA2BvF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,iBAAiB,EACxB,qBAAqB,EAAE,MAAM,EAC7B,iBAAiB,EAAE,MAAM,EACzB,yBAAyB,EAAE,MAAM,MAAM,EACvC,OAAO,EAAE,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,KAAK,KAAK,GAChD,IAAI,CAeN;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,iBAAiB,EACxB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,KAAK,GAC3B,IAAI,CAcN;AAySD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CASpF"}

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+export { atom } from './atom';
+export { computed, mergeAtoms } from './computed';
+export { effect } from './effect';
+export type { Paths, PathValue } from './lens';
+export { atomLens, composeLens, getPathValue, lensFor, mergeLenses, setDeepValue, } from './lens';
+export { aeNextTick, batch, scheduler } from './scheduler';
+export { untracked } from './tracking';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,OAAO,EACP,WAAW,EACX,YAAY,GACb,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}