@but212/atom-effect 0.30.1 → 0.32.0

package/dist/symbols.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The global brand symbol used for type identification across all reactive primitives.
+ *
+ * Optimization: A single consolidated symbol is used to store multiple type markers
+ * using bitwise flags. This strategy minimizes property lookup overhead and reduces
+ * the overall object size by avoiding multiple type-specific properties.
+ *
+ * When to use:
+ * - To access the internal type metadata of a reactive node.
+ * - To implement custom branded objects that need to integrate with the reactive system.
+ */
+export declare const BRAND: unique symbol;
+/**
+ * A collection of bitwise flags used for precise type discrimination.
+ *
+ * When to use:
+ * - To identify the specific category of a reactive node (e.g., Atom, Computed, Effect).
+ * - To verify the capabilities of a node (e.g., checking if it is writable).
+ */
+export declare const BrandFlags: {
+    /** Indicates that the primitive is an atom (either Readonly or Writable). */
+    readonly Atom: number;
+    /** Indicates that the primitive supports write operations, such as `.set()` or `.update()`. */
+    readonly Writable: number;
+    /** Indicates that the primitive is a computed value with dependency tracking logic. */
+    readonly Computed: number;
+    /** Indicates that the primitive is an effect handle. */
+    readonly Effect: number;
+};
+//# sourceMappingURL=symbols.d.ts.map

package/dist/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../src/symbols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,MAAwC,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;IACrB,6EAA6E;;IAE7E,+FAA+F;;IAE/F,uFAAuF;;IAEvF,wDAAwD;;CAEhD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,259 @@
+import { Equal, If, Merge, Prettify } from '@but212/atom-effect-utils';
+import { AsyncState } from './constants';
+import { BRAND } from './symbols';
+export type { Equal, If, Merge, Prettify };
+/**
+ * Logic: Dependency Value Extraction
+ * Extracts the inner value type `V` from a `Dependency<V>`.
+ * @internal
+ */
+export type UnboxDependency<D> = D extends Dependency<infer V> ? V : never;
+/**
+ * Logic: Safe Object Merging
+ * Merges a union of dependency values into a single object.
+ * @internal
+ */
+export type MergedDependencyValue<T extends readonly unknown[]> = Merge<UnboxDependency<T[number]>>;
+/** A unique monotonic identifier for reactive dependencies. */
+export type DependencyId = number;
+/**
+ * Interface for objects requiring explicit resource release (timers, observers, listeners).
+ */
+export interface Disposable {
+    /**
+     * Releases internal resources and detaches from the reactive graph.
+     */
+    dispose(): void;
+}
+/** Represents the possible states of an asynchronous reactive node. */
+export type AsyncStateType = (typeof AsyncState)[keyof typeof AsyncState];
+/** Configuration for initializing an atom. */
+export interface AtomOptions<T = unknown> {
+    /** Identifier for debugger and devtools. */
+    name?: string;
+    /**
+     * When true, updates bypass the scheduler and notify subscribers immediately.
+     * Caution: Can lead to inconsistent states if multiple synchronous updates depend on each other.
+     */
+    sync?: boolean;
+    /** Custom comparator to prevent unnecessary updates if the value is structurally identical. */
+    equal?: (a: T, b: T) => boolean;
+}
+/**
+ * Internal contract for dependency tracking and re-execution.
+ *
+ * Optimization: Monomorphic Access
+ * All properties are non-optional to ensure V8 optimizes property access
+ * during high-frequency graph traversals.
+ *
+ * Constraint: Managed State
+ * The `version`, `flags`, and `_lastSeenEpoch` fields are internal engine
+ * state and must not be modified by external logic.
+ *
+ * @internal
+ */
+export interface Dependency<T = unknown> {
+    /** @internal */
+    readonly [BRAND]?: number;
+    /** Unique engine-level ID. */
+    readonly id: DependencyId;
+    /** Monotonic update counter used for drift detection. */
+    version: number;
+    /** State bitmask defined in `constants.ts`. */
+    flags: number;
+    /** Used by the scheduler to identify if a node was visited in the current epoch. */
+    _lastSeenEpoch: number;
+    /** Type discriminator for fast-path checks. */
+    readonly isComputed: boolean;
+    /** Error state flag. */
+    readonly hasError: boolean;
+    /** Engine-level subscription method. */
+    subscribe(listener: ((newValue?: T, oldValue?: T) => void) | Subscriber): () => void;
+    /** Non-reactive read. */
+    peek(): T;
+    /** Current value. */
+    readonly value: T;
+}
+/**
+ * A read-only reactive container.
+ *
+ * When to use:
+ * - To expose state while preventing external mutation (Unidirectional Data Flow).
+ * - To serve as a base for computed or derived values.
+ */
+export interface ReadonlyAtom<T = unknown> extends Dependency<T>, Disposable {
+    /** Returns the active subscriber count for diagnostic purposes. */
+    subscriberCount(): number;
+}
+/**
+ * A reactive container supporting read and write operations.
+ *
+ * When to use:
+ * - As the primary source of truth for application state.
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * count.value++; // Triggers downstream updates.
+ * ```
+ */
+export interface WritableAtom<T = unknown> extends ReadonlyAtom<T> {
+    /** Setting the value triggers a notification cycle for all dependents. */
+    value: T;
+}
+/** Configuration for derived computed atoms. */
+export interface ComputedOptions<T = unknown> {
+    /** Identifier for debugging. */
+    name?: string;
+    /** Comparator to prune updates if the computed result hasn't changed. */
+    equal?: (a: T, b: T) => boolean;
+    /** Value returned before the first computation completes. */
+    defaultValue?: T;
+    /** When true, computation only runs when the `.value` property is accessed. */
+    lazy?: boolean;
+    /** Error boundary for the computation logic. */
+    onError?: (error: Error) => void;
+}
+/**
+ * A derived reactive value resolving synchronously or asynchronously.
+ *
+ * When to use:
+ * - To encapsulate business logic that depends on other atoms.
+ * - To handle asynchronous data fetching with built-in status tracking.
+ *
+ * @example
+ * ```typescript
+ * const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+ * console.log(fullName.value);
+ * ```
+ */
+export interface ComputedAtom<T = unknown> extends ReadonlyAtom<T> {
+    /** @internal */
+    readonly [BRAND]?: number;
+    /** Current async status (idle, pending, resolved, rejected). */
+    readonly state: AsyncStateType;
+    /** True if the last computation threw an error. */
+    readonly hasError: boolean;
+    /** The most recent error encountered. */
+    readonly lastError: Error | null;
+    /** True during async execution. */
+    readonly isPending: boolean;
+    /** True if at least one successful resolution has occurred. */
+    readonly isResolved: boolean;
+    /** True if the current value is valid (resolved and no active error). */
+    readonly isValid: boolean;
+    /**
+     * Aggregate list of errors from the last evaluation cycle.
+     * Optimization: Shared with `EMPTY_ERROR_ARRAY` when no errors exist.
+     */
+    readonly errors: readonly Error[];
+    /**
+     * Manually flags the computation as dirty.
+     * When to use: When external, non-reactive state influences the result.
+     */
+    invalidate(): void;
+}
+/**
+ * Contract for nodes that can be scheduled for execution.
+ * @internal
+ */
+export interface Subscriber {
+    /** Invoked by the scheduler to perform the node's update logic. */
+    execute(): void;
+}
+/** Cleanup callback for effects. */
+export type EffectCleanup = () => void;
+/**
+ * Execution logic for a reactive effect.
+ * Supports async execution and optional teardown logic.
+ */
+export type EffectFunction = () => (void | EffectCleanup) | Promise<void | EffectCleanup>;
+/** Configuration for reactive side-effects. */
+export interface EffectOptions {
+    /** Identifier for diagnostics. */
+    name?: string;
+    /** When true, runs immediately upon creation. */
+    sync?: boolean;
+    /** Reason: Protection against runaway recursive loops. */
+    maxExecutionsPerSecond?: number;
+    /** Reason: Protection against circular dependencies in a single flush. */
+    maxExecutionsPerFlush?: number;
+    /** Error handler for the effect logic and its cleanup. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Handle for a managed reactive effect.
+ */
+export interface EffectObject extends Disposable {
+    /** @internal */
+    readonly [BRAND]?: number;
+    /** Manually triggers the effect. */
+    run(): void;
+    /** True if the effect is no longer active. */
+    readonly isDisposed: boolean;
+    /** Total execution count since creation. */
+    readonly executionCount: number;
+    /** True while the effect function is running. */
+    readonly isExecuting: boolean;
+}
+/** Diagnostic metrics for memory and resource management. @internal */
+export interface PoolStats {
+    acquired: number;
+    released: number;
+    rejected: {
+        frozen: number;
+        tooLarge: number;
+        poolFull: number;
+    };
+    leaked: number;
+    poolSize: number;
+}
+/**
+ * Internal interface for engine instrumentation and debugging.
+ * @internal
+ */
+export interface DebugConfig {
+    /** Master toggle for diagnostic features. */
+    enabled: boolean;
+    /** Toggle for infinite loop detection. */
+    warnInfiniteLoop: boolean;
+    /** Enables full graph traversal tracking (Performance impact: High). */
+    trackGraph: boolean;
+    /** Internal logger. */
+    warn(condition: boolean, message: string): void;
+    /** Instruments objects with metadata for devtools. */
+    attachDebugInfo(obj: object, type: string, id: number, customName?: string): void;
+    /** Resolves human-readable names for diagnostic messages. */
+    getDebugName(obj: object | null | undefined): string | undefined;
+    /** Identifies the internal node type. */
+    getDebugType(obj: object | null | undefined): string | undefined;
+    /** Records update frequency for loop detection. */
+    trackUpdate(id: DependencyId, name?: string): void;
+    /** Registers nodes for global graph snapshots. */
+    registerNode(node: object & {
+        id: DependencyId;
+    }): void;
+    /** Records evaluation failures during dirty checks. */
+    trackEvaluationFailure(id: DependencyId): void;
+    /** Generates a JSON snapshot of the dependency graph. */
+    dumpGraph(): Record<string, unknown>[];
+}
+/**
+ * Global configuration parameters for the Scheduler.
+ * @internal
+ */
+export interface SchedulerConfig {
+    /** Prevents infinite loops or runaway effects from freezing the main thread. */
+    MAX_EXECUTIONS_PER_SECOND: number;
+    /** Detects and stops circular dependencies within a single microtask. */
+    MAX_EXECUTIONS_PER_EFFECT: number;
+    /** Limits the total workload per flush to maintain frame-rate stability. */
+    MAX_EXECUTIONS_PER_FLUSH: number;
+    /** Safety break for the drain-loop to prevent stack overflows or infinite flushing. */
+    MAX_FLUSH_ITERATIONS: number;
+    /** Ensures a minimum number of iterations are processed to allow for nested batched updates. */
+    MIN_FLUSH_ITERATIONS: number;
+    /** Threshold for shrinking the internal batch queue to release memory back to the heap. */
+    BATCH_QUEUE_SHRINK_THRESHOLD: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils/debug.d.ts

@@ -0,0 +1,20 @@
+import { DebugConfig, DependencyId } from '../types';
+/** Sentinel value used to distinguish between 'undefined' and 'not set'. */
+export declare const NO_DEFAULT_VALUE: unique symbol;
+/**
+ * Global diagnostic hub.
+ *
+ * @example
+ * ```typescript
+ * import { debug } from '@but212/atom-effect';
+ *
+ * // View all active nodes in the console
+ * console.table(debug.dumpGraph());
+ * ```
+ */
+export declare const debug: DebugConfig;
+/**
+ * Generates an internal unique ID for a reactive node.
+ */
+export declare const generateId: () => DependencyId;
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIzD,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,eAAsC,CAAC;AAkPpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,EAAE,WAAqE,CAAC;AAK1F;;GAEG;AACH,eAAO,MAAM,UAAU,QAAO,YAAwC,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+import { Dependency, MergedDependencyValue } from '../types';
+/**
+ * Merges the values of multiple object-based atoms into a single object.
+ * @internal
+ *
+ * @param atoms - List of atoms to merge.
+ * @param peek - If true, uses .peek() instead of .value to avoid reactive tracking.
+ * @returns A single object containing all properties from the input atoms.
+ */
+export declare function mergeAtomValues<T extends Dependency<unknown>[]>(atoms: T, peek?: boolean): MergedDependencyValue<T>;
+export { debug, NO_DEFAULT_VALUE } from './debug';
+export { isAtom, isComputed, isEffect, isPromise, isWritable } from './type-guards';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,EAC7D,KAAK,EAAE,CAAC,EACR,IAAI,UAAQ,GACX,qBAAqB,CAAC,CAAC,CAAC,CAW1B;AAED,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,81 @@
+import { isPromise } from '@but212/atom-effect-utils';
+import { ComputedAtom, EffectObject, ReadonlyAtom, WritableAtom } from '../types';
+/**
+ * Determines whether a value is a ReadonlyAtom.
+ *
+ * When to use:
+ * - To validate user input in APIs that expect reactive atoms.
+ * - To differentiate between raw values and reactive containers.
+ *
+ * @param obj - The value to check.
+ * @returns True if the value is an atom.
+ *
+ * @example
+ * ```typescript
+ * import { isAtom } from '@but212/atom-effect';
+ *
+ * if (isAtom(maybeAtom)) {
+ *   console.log(maybeAtom.value);
+ * }
+ * ```
+ */
+export declare function isAtom(obj: unknown): obj is ReadonlyAtom;
+/**
+ * Determines whether a value is a WritableAtom.
+ *
+ * When to use:
+ * - To verify if an atom can be modified via `.set()` or `.update()` before attempting the operation.
+ *
+ * @param obj - The value to check.
+ * @returns True if the value is a writable atom.
+ *
+ * @example
+ * ```typescript
+ * import { isWritable } from '@but212/atom-effect';
+ *
+ * if (isWritable(maybeAtom)) {
+ *   maybeAtom.value = 123;
+ * }
+ * ```
+ */
+export declare function isWritable(obj: unknown): obj is WritableAtom;
+/**
+ * Determines whether a value is a ComputedAtom.
+ *
+ * When to use:
+ * - To identify derived state containers that may have underlying dependencies.
+ *
+ * @param obj - The value to check.
+ * @returns True if the value is a computed atom.
+ *
+ * @example
+ * ```typescript
+ * import { isComputed } from '@but212/atom-effect';
+ *
+ * if (isComputed(maybeAtom)) {
+ *   console.log('This atom is a derived value.');
+ * }
+ * ```
+ */
+export declare function isComputed(obj: unknown): obj is ComputedAtom;
+/**
+ * Determines whether a value is an EffectObject.
+ *
+ * When to use:
+ * - To validate objects that manage reactive side-effects.
+ *
+ * @param obj - The value to check.
+ * @returns True if the value is an effect handle.
+ *
+ * @example
+ * ```typescript
+ * import { isEffect } from '@but212/atom-effect';
+ *
+ * if (isEffect(maybeEffect)) {
+ *   maybeEffect.dispose();
+ * }
+ * ```
+ */
+export declare function isEffect(obj: unknown): obj is EffectObject;
+export { isPromise };
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA4BtF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAExD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAE5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAE5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY,CAE1D;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@but212/atom-effect",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "type": "module",
   "description": "A reactive state management library that combines the power of `atom`, `computed`, and `effect` for seamless management of reactive state.",
   "main": "./dist/index.cjs",
@@ -39,16 +39,18 @@
     "directory": "packages/core"
   },
   "devDependencies": {
-    "@types/jsdom": "^28.0.1",
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "@vitest/ui": "^4.1.4",
-    "happy-dom": "^20.8.9",
-    "jsdom": "^29.0.2",
-    "tinybench": "^6.0.0",
-    "vite": "^8.0.8",
+    "@types/node": "^25.6.2",
+    "@vitest/browser": "^4.1.5",
+    "@vitest/browser-playwright": "^4.1.5",
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/ui": "^4.1.5",
+    "playwright": "^1.59.1",
+    "tinybench": "^6.0.1",
+    "vite": "^8.0.11",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.5",
+    "@but212/atom-effect-configs": "0.0.0",
+    "@but212/atom-effect-utils": "0.0.0"
   },
   "scripts": {
     "build": "vite build",
@@ -66,10 +68,9 @@
     "bench": "vitest bench --config vitest.bench.config.ts",
     "bench:micro": "pnpm run bench __benchmarks__/micro",
     "bench:macro": "pnpm run bench __benchmarks__/macro",
-    "bench:atom": "pnpm run bench __benchmarks__/micro/atom.bench",
-    "bench:computed": "pnpm run bench __benchmarks__/micro/computed.bench",
-    "bench:effect": "pnpm run bench __benchmarks__/micro/effect.bench",
+    "bench:state": "pnpm run bench __benchmarks__/state",
     "bench:realistic": "pnpm run bench __benchmarks__/realistic",
-    "bench:propagation": "pnpm run bench __benchmarks__/micro/propagation.bench"
+    "bench:scheduler": "pnpm run bench __benchmarks__/micro/scheduler.bench.ts",
+    "bench:all": "pnpm run bench"
   }
 }