@but212/atom-effect 0.1.0 → 0.1.1

package/dist/scheduler/scheduler.d.ts

@@ -1,19 +1,149 @@
+/**
+ * Scheduler for managing reactive updates and batching operations.
+ *
+ * The Scheduler is responsible for coordinating when reactive computations
+ * are executed. It supports both immediate (microtask) execution and
+ * batched synchronous execution for optimal performance.
+ *
+ * Key features:
+ * - Deduplication of callbacks via Set
+ * - Nested batch support with depth tracking
+ * - Infinite loop protection with configurable iteration limit
+ * - Error isolation to prevent one callback from breaking others
+ *
+ * @example
+ * ```typescript
+ * // Schedule a callback for microtask execution
+ * scheduler.schedule(() => console.log('Updated!'));
+ *
+ * // Batch multiple updates
+ * scheduler.startBatch();
+ * scheduler.schedule(() => console.log('Update 1'));
+ * scheduler.schedule(() => console.log('Update 2'));
+ * scheduler.endBatch(); // Both execute synchronously here
+ * ```
+ */
 declare class Scheduler {
+    /** Queue of callbacks waiting for microtask execution */
     private queue;
+    /** Whether the scheduler is currently processing the queue */
     private isProcessing;
+    /** Whether batching is currently active */
     isBatching: boolean;
+    /** Current nesting depth of batch operations */
     private batchDepth;
+    /** Array of callbacks queued during batching */
     private batchQueue;
+    /** Current size of the batch queue (for array reuse) */
     private batchQueueSize;
+    /** Whether synchronous flush is in progress */
     private isFlushingSync;
+    /** Maximum iterations allowed during flush to prevent infinite loops */
     private maxFlushIterations;
+    /**
+     * Schedules a callback for execution.
+     *
+     * If batching is active or a sync flush is in progress, the callback
+     * is added to the batch queue. Otherwise, it's added to the main queue
+     * and a flush is triggered via microtask.
+     *
+     * @param callback - The function to schedule for execution
+     * @throws {SchedulerError} If callback is not a function
+     *
+     * @example
+     * ```typescript
+     * scheduler.schedule(() => {
+     *   // This runs in the next microtask (or sync if batching)
+     *   updateUI();
+     * });
+     * ```
+     */
     schedule(callback: () => void): void;
+    /**
+     * Flushes the queue asynchronously via microtask.
+     *
+     * Executes all queued callbacks in a microtask, allowing the current
+     * synchronous execution to complete first. Errors in individual
+     * callbacks are caught and logged without interrupting others.
+     *
+     * @private
+     * @remarks
+     * This method is idempotent - calling it multiple times while
+     * processing is active has no effect.
+     */
     private flush;
+    /**
+     * Flushes all queued callbacks synchronously.
+     *
+     * This method is called when a batch ends. It processes all callbacks
+     * in the batch queue and main queue synchronously, allowing callbacks
+     * to schedule additional callbacks that are processed in the same flush.
+     *
+     * @private
+     * @remarks
+     * - Includes infinite loop protection via maxFlushIterations
+     * - Errors in callbacks are caught and logged individually
+     * - The isFlushingSync flag prevents re-entrancy issues
+     */
     private flushSync;
+    /**
+     * Starts a new batch operation.
+     *
+     * While batching is active, all scheduled callbacks are deferred
+     * until endBatch() is called. Batches can be nested - only the
+     * outermost endBatch() triggers execution.
+     *
+     * @example
+     * ```typescript
+     * scheduler.startBatch();
+     * // All updates here are deferred
+     * atom1.value = 'a';
+     * atom2.value = 'b';
+     * scheduler.endBatch(); // Both updates processed together
+     * ```
+     */
     startBatch(): void;
+    /**
+     * Ends a batch operation.
+     *
+     * Decrements the batch depth counter. When depth reaches zero,
+     * all queued callbacks are flushed synchronously and batching
+     * is disabled.
+     *
+     * @remarks
+     * Safe to call even if startBatch() wasn't called - depth is
+     * clamped to zero minimum.
+     *
+     * @example
+     * ```typescript
+     * scheduler.startBatch();
+     * try {
+     *   // ... batched operations
+     * } finally {
+     *   scheduler.endBatch(); // Always end batch, even on error
+     * }
+     * ```
+     */
     endBatch(): void;
+    /**
+     * Sets the maximum number of flush iterations allowed.
+     *
+     * This limit prevents infinite loops when reactive dependencies
+     * form cycles. If exceeded, the queue is cleared and an error
+     * is logged.
+     *
+     * @param max - Maximum iterations (must be at least 10)
+     * @throws {SchedulerError} If max is less than 10
+     *
+     * @example
+     * ```typescript
+     * // Increase limit for complex dependency graphs
+     * scheduler.setMaxFlushIterations(5000);
+     * ```
+     */
     setMaxFlushIterations(max: number): void;
 }
+/** Global scheduler instance for reactive updates */
 export declare const scheduler: Scheduler;
 export {};
 //# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/scheduler.ts"],"names":[],"mappings":"AAEA,cAAM,SAAS;IACb,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,YAAY,CAAkB;IAC/B,UAAU,EAAE,OAAO,CAAS;IACnC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,kBAAkB,CAAgB;IAE1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAepC,OAAO,CAAC,KAAK;IA0Bb,OAAO,CAAC,SAAS;IAoDjB,UAAU,IAAI,IAAI;IAKlB,QAAQ,IAAI,IAAI;IAShB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAMzC;AAED,eAAO,MAAM,SAAS,WAAkB,CAAC"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler/scheduler.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,cAAM,SAAS;IACb,yDAAyD;IACzD,OAAO,CAAC,KAAK,CAA8B;IAE3C,8DAA8D;IAC9D,OAAO,CAAC,YAAY,CAAkB;IAEtC,2CAA2C;IACpC,UAAU,EAAE,OAAO,CAAS;IAEnC,gDAAgD;IAChD,OAAO,CAAC,UAAU,CAAa;IAE/B,gDAAgD;IAChD,OAAO,CAAC,UAAU,CAAyB;IAE3C,wDAAwD;IACxD,OAAO,CAAC,cAAc,CAAK;IAE3B,+CAA+C;IAC/C,OAAO,CAAC,cAAc,CAAkB;IAExC,wEAAwE;IACxE,OAAO,CAAC,kBAAkB,CAAgB;IAE1C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAepC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,KAAK;IA0Bb;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAoDjB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,IAAI,IAAI;IAShB;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAMzC;AAED,qDAAqD;AACrD,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/dist/tracking/context.d.ts

@@ -1,8 +1,76 @@
 import { Listener } from './tracking.types';
+/**
+ * Interface for the tracking context that manages dependency tracking.
+ *
+ * The tracking context is responsible for maintaining the current listener
+ * during reactive computations, enabling automatic dependency collection.
+ *
+ * @interface TrackingContext
+ */
 export interface TrackingContext {
+    /**
+     * The currently active listener being tracked.
+     * `null` when no tracking is in progress.
+     */
     current: Listener | null;
+    /**
+     * Executes a function within a tracking context.
+     *
+     * Sets the provided listener as the current tracking target,
+     * executes the function, and restores the previous context.
+     *
+     * @template T - The return type of the function
+     * @param listener - The listener to set as current during execution
+     * @param fn - The function to execute within the tracking context
+     * @returns The result of the executed function
+     *
+     * @example
+     * ```typescript
+     * const result = trackingContext.run(myListener, () => {
+     *   // Any atom access here will be tracked
+     *   return someAtom.value + otherAtom.value;
+     * });
+     * ```
+     */
     run<T>(listener: Listener, fn: () => T): T;
+    /**
+     * Gets the currently active listener.
+     *
+     * @returns The current listener or `null` if no tracking is active
+     *
+     * @example
+     * ```typescript
+     * const current = trackingContext.getCurrent();
+     * if (current) {
+     *   // Dependency tracking is active
+     * }
+     * ```
+     */
     getCurrent(): Listener | null;
 }
+/**
+ * Global tracking context singleton for dependency tracking.
+ *
+ * This object manages the current listener during reactive computations,
+ * enabling atoms and computed values to automatically track their dependencies.
+ *
+ * @remarks
+ * - The context uses a stack-like behavior via the `run` method
+ * - Nested `run` calls properly restore the previous context
+ * - Thread-safe within a single JavaScript execution context
+ *
+ * @example
+ * ```typescript
+ * // Setting up tracking for a computed value
+ * const value = trackingContext.run(computedListener, () => {
+ *   return atom1.value + atom2.value; // Both atoms are tracked
+ * });
+ *
+ * // Checking if tracking is active
+ * if (trackingContext.getCurrent()) {
+ *   // Register this atom as a dependency
+ * }
+ * ```
+ */
 export declare const trackingContext: TrackingContext;
 //# sourceMappingURL=context.d.ts.map

package/dist/tracking/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tracking/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3C,UAAU,IAAI,QAAQ,GAAG,IAAI,CAAC;CAC/B;AAED,eAAO,MAAM,eAAe,EAAE,eAgB7B,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tracking/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAE3C;;;;;;;;;;;;OAYG;IACH,UAAU,IAAI,QAAQ,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAC"}

package/dist/tracking/dependency-manager.d.ts

@@ -1,17 +1,220 @@
 import { Dependency } from '../types';
+/**
+ * Manages reactive dependencies with automatic cleanup and memory-efficient tracking.
+ *
+ * This class provides a centralized way to track dependencies between reactive
+ * primitives (atoms, computed values) and their subscribers. It uses WeakRef
+ * and WeakMap for memory-efficient storage that allows garbage collection
+ * of unused dependencies.
+ *
+ * @remarks
+ * - Uses WeakMap for O(1) lookup and automatic GC of unreferenced dependencies
+ * - Uses WeakRef array for iteration while allowing GC
+ * - Periodic cleanup removes stale WeakRefs to prevent memory leaks
+ * - Thread-safe for single-threaded JavaScript execution
+ *
+ * @example
+ * ```typescript
+ * const manager = new DependencyManager();
+ *
+ * // Add a dependency with its unsubscribe callback
+ * const unsubscribe = atom.subscribe(() => recompute());
+ * manager.addDependency(atom, unsubscribe);
+ *
+ * // Check if dependency exists
+ * if (manager.hasDependency(atom)) {
+ *   console.log('Dependency tracked');
+ * }
+ *
+ * // Remove specific dependency
+ * manager.removeDependency(atom);
+ *
+ * // Clean up all dependencies
+ * manager.unsubscribeAll();
+ * ```
+ */
 export declare class DependencyManager {
+    /**
+     * WeakMap storing dependency -> unsubscribe function mappings.
+     * Allows O(1) lookup and automatic garbage collection.
+     */
     private depMap;
+    /**
+     * Array of WeakRefs for iteration over live dependencies.
+     * WeakRefs allow the referenced objects to be garbage collected.
+     */
     private depRefs;
+    /**
+     * Number of additions before triggering automatic cleanup.
+     * @defaultValue 100
+     */
     private cleanupThreshold;
+    /**
+     * Counter tracking additions since last cleanup.
+     */
     private addCount;
+    /**
+     * Adds a dependency with its associated unsubscribe callback.
+     *
+     * If the dependency already exists, the new unsubscribe callback is
+     * immediately called to prevent duplicate subscriptions.
+     *
+     * @param dep - The dependency to track (atom, computed, etc.)
+     * @param unsubscribe - Callback to invoke when removing the dependency
+     *
+     * @remarks
+     * - Duplicate dependencies are rejected with immediate unsubscribe
+     * - Automatic cleanup is triggered every `cleanupThreshold` additions
+     * - Time complexity: O(1) for add, O(n) when cleanup triggers
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = atom.subscribe(() => markDirty());
+     * manager.addDependency(atom, unsubscribe);
+     * ```
+     */
     addDependency(dep: Dependency, unsubscribe: () => void): void;
+    /**
+     * Removes a dependency and calls its unsubscribe callback.
+     *
+     * @param dep - The dependency to remove
+     * @returns `true` if the dependency was found and removed, `false` otherwise
+     *
+     * @remarks
+     * - Unsubscribe errors are caught and logged to prevent cascading failures
+     * - The WeakRef entry is not immediately removed (cleaned up lazily)
+     * - Time complexity: O(1)
+     *
+     * @example
+     * ```typescript
+     * const wasRemoved = manager.removeDependency(atom);
+     * if (wasRemoved) {
+     *   console.log('Dependency successfully removed');
+     * }
+     * ```
+     */
     removeDependency(dep: Dependency): boolean;
+    /**
+     * Checks if a dependency is currently being tracked.
+     *
+     * @param dep - The dependency to check
+     * @returns `true` if the dependency exists in the manager
+     *
+     * @remarks
+     * Time complexity: O(1)
+     *
+     * @example
+     * ```typescript
+     * if (manager.hasDependency(atom)) {
+     *   // Dependency is already tracked
+     * }
+     * ```
+     */
     hasDependency(dep: Dependency): boolean;
+    /**
+     * Removes all dependencies and calls their unsubscribe callbacks.
+     *
+     * This method iterates through all tracked dependencies, calls their
+     * unsubscribe callbacks, and clears internal storage.
+     *
+     * @remarks
+     * - Errors during unsubscribe are caught and logged individually
+     * - Safe to call multiple times (idempotent after first call)
+     * - Time complexity: O(n) where n is the number of dependencies
+     *
+     * @example
+     * ```typescript
+     * // Clean up when disposing a computed value
+     * manager.unsubscribeAll();
+     * ```
+     */
     unsubscribeAll(): void;
+    /**
+     * Removes stale WeakRefs from the internal array.
+     *
+     * WeakRefs whose targets have been garbage collected are filtered out
+     * to prevent unbounded growth of the depRefs array.
+     *
+     * @remarks
+     * - Called automatically every `cleanupThreshold` additions
+     * - Can be called manually for immediate cleanup
+     * - Time complexity: O(n) where n is the number of WeakRefs
+     *
+     * @example
+     * ```typescript
+     * // Force immediate cleanup
+     * manager.cleanup();
+     * ```
+     */
     cleanup(): void;
+    /**
+     * Gets the current number of live dependencies.
+     *
+     * @returns The count of dependencies that haven't been garbage collected
+     *
+     * @remarks
+     * - Triggers cleanup before counting for accurate results
+     * - Time complexity: O(n) due to cleanup
+     *
+     * @example
+     * ```typescript
+     * console.log(`Tracking ${manager.count} dependencies`);
+     * ```
+     */
     get count(): number;
+    /**
+     * Gets an array of all live dependencies.
+     *
+     * @returns Array of dependencies that haven't been garbage collected
+     *
+     * @remarks
+     * - Returns a new array (safe to modify)
+     * - Does not trigger cleanup (may include some stale refs)
+     * - Time complexity: O(n)
+     *
+     * @example
+     * ```typescript
+     * const deps = manager.getDependencies();
+     * deps.forEach(dep => console.log(dep));
+     * ```
+     */
     getDependencies(): Dependency[];
+    /**
+     * Gets the internal WeakMap for advanced use cases.
+     *
+     * @returns The internal dependency -> unsubscribe WeakMap
+     *
+     * @remarks
+     * - Returns the actual internal map (not a copy)
+     * - Modifications will affect the manager's state
+     * - Use with caution in production code
+     *
+     * @example
+     * ```typescript
+     * const map = manager.getDepMap();
+     * const unsubscribe = map.get(someDependency);
+     * ```
+     */
     getDepMap(): WeakMap<Dependency, () => void>;
+    /**
+     * Sets the threshold for automatic cleanup triggering.
+     *
+     * @param threshold - Number of additions before cleanup (minimum 1)
+     *
+     * @remarks
+     * - Lower values mean more frequent cleanup (less memory, more CPU)
+     * - Higher values mean less frequent cleanup (more memory, less CPU)
+     * - Default is 100, suitable for most use cases
+     *
+     * @example
+     * ```typescript
+     * // More aggressive cleanup for memory-constrained environments
+     * manager.setCleanupThreshold(50);
+     *
+     * // Less frequent cleanup for performance-critical paths
+     * manager.setCleanupThreshold(500);
+     * ```
+     */
     setCleanupThreshold(threshold: number): void;
 }
 //# sourceMappingURL=dependency-manager.d.ts.map

package/dist/tracking/dependency-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-manager.d.ts","sourceRoot":"","sources":["../../src/tracking/dependency-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,gBAAgB,CAAO;IAC/B,OAAO,CAAC,QAAQ,CAAK;IAErB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,GAAG,IAAI;IAe7D,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAc1C,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAIvC,cAAc,IAAI,IAAI;IAmBtB,OAAO,IAAI,IAAI;IAIf,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED,eAAe,IAAI,UAAU,EAAE;IAW/B,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAI5C,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAG7C"}
+{"version":3,"file":"dependency-manager.d.ts","sourceRoot":"","sources":["../../src/tracking/dependency-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAyC;IAEvD;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA6B;IAE5C;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAO;IAE/B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAK;IAErB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,GAAG,IAAI;IAe7D;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAc1C;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IAIvC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,IAAI,IAAI;IAmBtB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,IAAI,IAAI;IAIf;;;;;;;;;;;;;OAaG;IACH,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAAe,IAAI,UAAU,EAAE;IAW/B;;;;;;;;;;;;;;;OAeG;IACH,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAI5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAG7C"}

package/dist/tracking/untracked.d.ts

@@ -1,2 +1,25 @@
+/**
+ * Executes a function without tracking any reactive dependencies.
+ *
+ * This utility allows reading atom values without establishing
+ * a dependency relationship, useful for accessing values that
+ * shouldn't trigger recomputation when they change.
+ *
+ * @template T - The return type of the function
+ * @param fn - The function to execute without tracking
+ * @returns The result of the executed function
+ * @throws {AtomError} If the callback is not a function
+ * @throws {AtomError} If an error occurs during execution
+ *
+ * @example
+ * ```typescript
+ * const count = atom(0);
+ * const doubled = computed(() => {
+ *   // This read will NOT be tracked as a dependency
+ *   const untrackedValue = untracked(() => count.value);
+ *   return untrackedValue * 2;
+ * });
+ * ```
+ */
 export declare function untracked<T>(fn: () => T): T;
 //# sourceMappingURL=untracked.d.ts.map

package/dist/tracking/untracked.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"untracked.d.ts","sourceRoot":"","sources":["../../src/tracking/untracked.ts"],"names":[],"mappings":"AAGA,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAe3C"}
+{"version":3,"file":"untracked.d.ts","sourceRoot":"","sources":["../../src/tracking/untracked.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAe3C"}

package/dist/utils/debug.d.ts

@@ -1,14 +1,85 @@
 import { DebugConfig } from '../types';
 /**
- * Symbols for debug metadata to avoid property name collisions
+ * Symbol key for storing debug display name on reactive objects.
+ *
+ * @remarks
+ * Using symbols prevents property name collisions with user-defined properties.
+ *
+ * @example
+ * ```typescript
+ * const atom = createAtom(0);
+ * console.log(atom[DEBUG_NAME]); // "atom_1"
+ * ```
  */
 export declare const DEBUG_NAME: unique symbol;
+/**
+ * Symbol key for storing unique identifier on reactive objects.
+ *
+ * @remarks
+ * Each reactive object (atom, computed, effect) receives a unique numeric ID
+ * for debugging and tracking purposes.
+ */
 export declare const DEBUG_ID: unique symbol;
+/**
+ * Symbol key for storing the type discriminator on reactive objects.
+ *
+ * @remarks
+ * Possible values: 'atom' | 'computed' | 'effect'
+ */
 export declare const DEBUG_TYPE: unique symbol;
 /**
- * Sentinel value to distinguish "no default value" from undefined
+ * Sentinel value to distinguish "no default value provided" from `undefined`.
+ *
+ * @remarks
+ * This allows computed values to differentiate between:
+ * - User explicitly passing `undefined` as default
+ * - User not providing any default value
+ *
+ * @example
+ * ```typescript
+ * const hasDefault = options.defaultValue !== NO_DEFAULT_VALUE;
+ * ```
  */
 export declare const NO_DEFAULT_VALUE: unique symbol;
+/**
+ * Debug configuration instance with runtime utilities.
+ *
+ * Provides development-time features including:
+ * - Circular dependency detection (direct and indirect)
+ * - Large dependency graph warnings
+ * - Debug metadata attachment for inspection
+ *
+ * @remarks
+ * Most features are only active when `NODE_ENV === 'development'`
+ * to avoid performance overhead in production builds.
+ *
+ * @example
+ * ```typescript
+ * // Check for circular dependencies
+ * debug.checkCircular(dependencyAtom, computedAtom);
+ *
+ * // Warn about potential issues
+ * debug.warn(count > 100, 'Large dependency count detected');
+ *
+ * // Attach debug info to a reactive object
+ * debug.attachDebugInfo(atom, 'atom', 42);
+ * ```
+ */
 export declare const debug: DebugConfig;
+/**
+ * Generates a unique numeric identifier for reactive objects.
+ *
+ * @returns A unique positive integer, incrementing with each call
+ *
+ * @remarks
+ * IDs are globally unique within a single runtime session.
+ * The counter resets when the module is reloaded.
+ *
+ * @example
+ * ```typescript
+ * const atomId = generateId(); // 1
+ * const computedId = generateId(); // 2
+ * ```
+ */
 export declare const generateId: () => number;
 //# sourceMappingURL=debug.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,UAAU,eAAsB,CAAC;AAC9C,eAAO,MAAM,QAAQ,eAAe,CAAC;AACrC,eAAO,MAAM,UAAU,eAAiB,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAA2B,CAAC;AAEzD,eAAO,MAAM,KAAK,EAAE,WA0DnB,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,MAAkB,CAAC"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,MAA4B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,MAAqB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,MAAuB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAiC,CAAC;AAmBxE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,KAAK,EAAE,WAsKnB,CAAC;AASF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,QAAO,MAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@but212/atom-effect",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",