@but212/atom-effect 0.1.0 → 0.1.1

package/dist/index.mjs

@@ -8,7 +8,7 @@ const S = {
   // 0001 - Effect has been disposed
   EXECUTING: 2
   // 0010 - Effect is currently executing
-}, o = {
+}, u = {
   DIRTY: 1,
   // 0001 - Needs recomputation
   IDLE: 2,
@@ -23,7 +23,7 @@ const S = {
   // 100000 - Currently recomputing
   HAS_ERROR: 64
   // 1000000 - Has error state
-}, B = {
+}, j = {
   /** Maximum number of pooled objects to prevent memory bloat */
   MAX_SIZE: 1e3,
   /** Number of objects to pre-allocate for performance-critical paths */
@@ -70,7 +70,7 @@ class b extends a {
     super(e, t, !1), this.name = "EffectError";
   }
 }
-class D extends a {
+class g extends a {
   /**
    * Creates a new SchedulerError
    * @param message - Error message
@@ -93,36 +93,130 @@ function E(i, e, t) {
 function A(i) {
   return i != null && typeof i.then == "function";
 }
-const u = {
+const o = {
+  // ─────────────────────────────────────────────────────────────────
   // Computed errors
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Error thrown when computed() receives a non-function argument.
+   */
   COMPUTED_MUST_BE_FUNCTION: "Computed function must be a function",
+  /**
+   * Error thrown when subscribe() receives a non-function listener.
+   */
   COMPUTED_SUBSCRIBER_MUST_BE_FUNCTION: "Subscriber listener must be a function",
+  /**
+   * Error thrown when accessing a pending async computed without a default value.
+   */
   COMPUTED_ASYNC_PENDING_NO_DEFAULT: "Async computation is pending. No default value provided",
+  /**
+   * Error thrown when a synchronous computed computation fails.
+   */
   COMPUTED_COMPUTATION_FAILED: "Computed computation failed",
+  /**
+   * Error thrown when an asynchronous computed computation fails.
+   */
   COMPUTED_ASYNC_COMPUTATION_FAILED: "Async computed computation failed",
+  /**
+   * Error thrown when subscribing to a dependency fails.
+   */
   COMPUTED_DEPENDENCY_SUBSCRIPTION_FAILED: "Failed to subscribe to dependency",
+  // ─────────────────────────────────────────────────────────────────
   // Atom errors
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Error thrown when atom.subscribe() receives a non-function listener.
+   */
   ATOM_SUBSCRIBER_MUST_BE_FUNCTION: "Subscription listener must be a function",
+  /**
+   * Error thrown when the atom subscriber notification process fails.
+   */
   ATOM_SUBSCRIBER_EXECUTION_FAILED: "Error occurred while executing atom subscribers",
+  /**
+   * Error logged when an individual subscriber throws during notification.
+   * @remarks This error is caught and logged to prevent cascading failures.
+   */
   ATOM_INDIVIDUAL_SUBSCRIBER_FAILED: "Error during individual atom subscriber execution",
+  // ─────────────────────────────────────────────────────────────────
   // Effect errors
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Error thrown when effect() receives a non-function argument.
+   */
   EFFECT_MUST_BE_FUNCTION: "Effect function must be a function",
+  /**
+   * Error thrown when an effect's execution fails.
+   */
   EFFECT_EXECUTION_FAILED: "Effect execution failed",
+  /**
+   * Error thrown when an effect's cleanup function fails.
+   */
   EFFECT_CLEANUP_FAILED: "Effect cleanup function execution failed",
+  // ─────────────────────────────────────────────────────────────────
   // Debug warnings
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Warning message for large dependency graphs.
+   *
+   * @param count - The number of dependencies detected
+   * @returns Formatted warning message with dependency count
+   *
+   * @example
+   * ```ts
+   * console.warn(ERROR_MESSAGES.LARGE_DEPENDENCY_GRAPH(150));
+   * // Output: "Large dependency graph detected: 150 dependencies"
+   * ```
+   */
   LARGE_DEPENDENCY_GRAPH: (i) => `Large dependency graph detected: ${i} dependencies`,
+  /**
+   * Warning logged when attempting to unsubscribe a non-existent listener.
+   */
   UNSUBSCRIBE_NON_EXISTENT: "Attempted to unsubscribe a non-existent listener",
+  /**
+   * Error logged when the onError callback itself throws an error.
+   * @remarks This prevents cascading failures from masking the original error.
+   */
   CALLBACK_ERROR_IN_ERROR_HANDLER: "Error occurred during onError callback execution"
 };
 class x {
   constructor() {
     this.queue = /* @__PURE__ */ new Set(), this.isProcessing = !1, this.isBatching = !1, this.batchDepth = 0, this.batchQueue = [], this.batchQueueSize = 0, this.isFlushingSync = !1, this.maxFlushIterations = 1e3;
   }
+  /**
+   * 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(e) {
     if (typeof e != "function")
-      throw new D("Scheduler callback must be a function");
+      throw new g("Scheduler callback must be a function");
     this.isBatching || this.isFlushingSync ? this.batchQueue[this.batchQueueSize++] = e : (this.queue.add(e), this.isProcessing || this.flush());
   }
+  /**
+   * 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.
+   */
   flush() {
     if (this.isProcessing || this.queue.size === 0) return;
     this.isProcessing = !0;
@@ -133,12 +227,25 @@ class x {
           e[t]?.();
         } catch (s) {
           console.error(
-            new D("Error occurred during scheduler execution", s)
+            new g("Error occurred during scheduler execution", s)
           );
         }
       this.isProcessing = !1, this.queue.size > 0 && !this.isBatching && this.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
+   */
   flushSync() {
     this.isFlushingSync = !0;
     try {
@@ -151,7 +258,7 @@ class x {
       for (; this.queue.size > 0; ) {
         if (++e > this.maxFlushIterations) {
           console.error(
-            new D(
+            new g(
               `Maximum flush iterations (${this.maxFlushIterations}) exceeded. Possible infinite loop in reactive dependencies. Consider increasing the limit with scheduler.setMaxFlushIterations()`
             )
           ), this.queue.clear(), this.batchQueueSize = 0;
@@ -164,7 +271,7 @@ class x {
             t[s]?.();
           } catch (r) {
             console.error(
-              new D("Error occurred during batch execution", r)
+              new g("Error occurred during batch execution", r)
             );
           }
         if (this.batchQueueSize > 0) {
@@ -177,33 +284,91 @@ class x {
       this.isFlushingSync = !1;
     }
   }
+  /**
+   * 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() {
     this.batchDepth++, this.isBatching = !0;
   }
+  /**
+   * 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() {
     this.batchDepth = Math.max(0, this.batchDepth - 1), this.batchDepth === 0 && (this.flushSync(), this.isBatching = !1);
   }
+  /**
+   * 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(e) {
     if (e < 10)
-      throw new D("Max flush iterations must be at least 10");
+      throw new g("Max flush iterations must be at least 10");
     this.maxFlushIterations = e;
   }
 }
-const g = new x();
-function j(i) {
+const D = new x();
+function G(i) {
   if (typeof i != "function")
     throw new a("Batch callback must be a function");
-  g.startBatch();
+  D.startBatch();
   try {
     return i();
   } catch (e) {
     throw new a("Error occurred during batch execution", e);
   } finally {
-    g.endBatch();
+    D.endBatch();
   }
 }
 const p = {
+  /** @inheritdoc */
   current: null,
+  /**
+   * @inheritdoc
+   * @throws Re-throws any error from the executed function after restoring context
+   */
   run(i, e) {
     const t = this.current;
     this.current = i;
@@ -213,6 +378,7 @@ const p = {
       this.current = t;
     }
   },
+  /** @inheritdoc */
   getCurrent() {
     return this.current;
   }
@@ -221,6 +387,26 @@ class F {
   constructor() {
     this.depMap = /* @__PURE__ */ new WeakMap(), this.depRefs = [], this.cleanupThreshold = 100, this.addCount = 0;
   }
+  /**
+   * 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(e, t) {
     if (this.depMap.has(e)) {
       t();
@@ -228,6 +414,25 @@ class F {
     }
     this.depMap.set(e, t), this.depRefs.push(new WeakRef(e)), ++this.addCount >= this.cleanupThreshold && (this.cleanup(), this.addCount = 0);
   }
+  /**
+   * 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(e) {
     const t = this.depMap.get(e);
     if (t) {
@@ -240,9 +445,42 @@ class F {
     }
     return !1;
   }
+  /**
+   * 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(e) {
     return this.depMap.has(e);
   }
+  /**
+   * 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() {
     for (let e = 0; e < this.depRefs.length; e++) {
       const t = this.depRefs[e].deref();
@@ -260,12 +498,59 @@ class F {
     }
     this.depRefs.length = 0, this.addCount = 0;
   }
+  /**
+   * 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() {
     this.depRefs = this.depRefs.filter((e) => e.deref() !== void 0);
   }
+  /**
+   * 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() {
     return this.cleanup(), this.depRefs.length;
   }
+  /**
+   * 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() {
     const e = [];
     for (let t = 0; t < this.depRefs.length; t++) {
@@ -274,14 +559,49 @@ class F {
     }
     return e;
   }
+  /**
+   * 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() {
     return this.depMap;
   }
+  /**
+   * 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(e) {
     this.cleanupThreshold = Math.max(1, e);
   }
 }
-function G(i) {
+function V(i) {
   if (typeof i != "function")
     throw new a("Untracked callback must be a function");
   const e = p.current;
@@ -294,43 +614,148 @@ function G(i) {
     p.current = e;
   }
 }
-const C = /* @__PURE__ */ Symbol("debugName"), P = /* @__PURE__ */ Symbol("id"), R = /* @__PURE__ */ Symbol("type"), T = /* @__PURE__ */ Symbol("noDefaultValue"), h = {
+const C = /* @__PURE__ */ Symbol("debugName"), P = /* @__PURE__ */ Symbol("id"), R = /* @__PURE__ */ Symbol("type"), T = /* @__PURE__ */ Symbol("noDefaultValue");
+function w(i) {
+  return i !== null && typeof i == "object" && "dependencies" in i && i.dependencies instanceof Set;
+}
+const h = {
+  /**
+   * Whether debug mode is enabled.
+   *
+   * @remarks
+   * Automatically set based on `NODE_ENV` environment variable.
+   * Only `'development'` enables debug features.
+   */
   enabled: typeof process < "u" && process.env?.NODE_ENV === "development",
+  /**
+   * Maximum number of dependencies before warning.
+   *
+   * @see {@link DEBUG_CONFIG.MAX_DEPENDENCIES}
+   */
   maxDependencies: m.MAX_DEPENDENCIES,
+  /**
+   * Whether to warn about potential infinite loops.
+   *
+   * @see {@link DEBUG_CONFIG.WARN_INFINITE_LOOP}
+   */
   warnInfiniteLoop: m.WARN_INFINITE_LOOP,
+  /**
+   * Logs a warning message when condition is true and debug is enabled.
+   *
+   * @param condition - When true, the warning is logged
+   * @param message - The warning message to display
+   *
+   * @example
+   * ```typescript
+   * debug.warn(deps.length > 100, 'Large dependency graph detected');
+   * ```
+   */
   warn(i, e) {
     this.enabled && i && console.warn(`[Atom Effect] ${e}`);
   },
+  /**
+   * Checks for circular dependencies in the dependency graph.
+   *
+   * Detects two types of circular references:
+   * 1. **Direct**: A depends on itself (A → A)
+   * 2. **Indirect**: A depends on B which depends on A (A → B → A)
+   *
+   * @param dep - The dependency being added
+   * @param current - The current reactive object adding the dependency
+   * @param visited - Set of already visited nodes (for recursion)
+   *
+   * @throws {ComputedError} When a circular dependency is detected
+   *
+   * @remarks
+   * - Direct circular detection runs in all environments
+   * - Indirect circular detection only runs in development mode
+   * - Uses depth-first traversal with O(n) time complexity
+   *
+   * @example
+   * ```typescript
+   * // This will throw for direct circular reference
+   * debug.checkCircular(computedA, computedA);
+   *
+   * // This will throw for indirect circular reference (dev only)
+   * // Given: A → B → C → A
+   * debug.checkCircular(computedC, computedA);
+   * ```
+   */
   checkCircular(i, e, t = /* @__PURE__ */ new Set()) {
     if (i === e)
       throw new d("Direct circular dependency detected");
     if (this.enabled) {
       if (t.has(i))
         throw new d("Indirect circular dependency detected");
-      if (t.add(i), i && typeof i == "object" && "dependencies" in i) {
-        const s = i.dependencies;
-        for (const r of s)
-          this.checkCircular(r, e, t);
-      }
+      if (t.add(i), w(i))
+        for (const s of i.dependencies)
+          this.checkCircular(s, e, t);
     }
   },
+  /**
+   * Attaches debug metadata to a reactive object.
+   *
+   * @param obj - The object to attach metadata to
+   * @param type - The type of reactive object ('atom' | 'computed' | 'effect')
+   * @param id - The unique identifier for this object
+   *
+   * @remarks
+   * Only attaches metadata when debug mode is enabled.
+   * Uses symbol keys to avoid property name collisions.
+   *
+   * @example
+   * ```typescript
+   * const atom = createAtomInternal(0);
+   * debug.attachDebugInfo(atom, 'atom', 1);
+   * // atom[DEBUG_NAME] === 'atom_1'
+   * // atom[DEBUG_ID] === 1
+   * // atom[DEBUG_TYPE] === 'atom'
+   * ```
+   */
   attachDebugInfo(i, e, t) {
-    if (!this.enabled) return;
+    if (!this.enabled)
+      return;
     const s = i;
     s[C] = `${e}_${t}`, s[P] = t, s[R] = e;
   },
+  /**
+   * Retrieves the debug display name from a reactive object.
+   *
+   * @param obj - The object to get the name from
+   * @returns The debug name (e.g., 'atom_1') or undefined if not set
+   *
+   * @example
+   * ```typescript
+   * const name = debug.getDebugName(myAtom);
+   * console.log(`Updating ${name ?? 'unknown'}`);
+   * ```
+   */
   getDebugName(i) {
-    if (i && typeof i == "object" && C in i)
+    if (i !== null && typeof i == "object" && C in i)
       return i[C];
   },
+  /**
+   * Retrieves the debug type from a reactive object.
+   *
+   * @param obj - The object to get the type from
+   * @returns The type ('atom' | 'computed' | 'effect') or undefined if not set
+   *
+   * @example
+   * ```typescript
+   * const type = debug.getDebugType(reactiveObj);
+   * if (type === 'computed') {
+   *   // Handle computed-specific logic
+   * }
+   * ```
+   */
   getDebugType(i) {
-    if (i && typeof i == "object" && R in i)
+    if (i !== null && typeof i == "object" && R in i)
       return i[R];
   }
 };
-let w = 1;
-const I = () => w++;
-class v {
+let v = 1;
+const I = () => v++;
+class L {
   /**
    * Creates a new AtomImpl instance.
    *
@@ -478,7 +903,7 @@ class v {
           l && l(e, t);
         } catch (l) {
           console.error(
-            new a(u.ATOM_INDIVIDUAL_SUBSCRIBER_FAILED, l)
+            new a(o.ATOM_INDIVIDUAL_SUBSCRIBER_FAILED, l)
           );
         }
       for (let f = 0; f < M; f++)
@@ -487,11 +912,11 @@ class v {
           l && l.execute();
         } catch (l) {
           console.error(
-            new a(u.ATOM_INDIVIDUAL_SUBSCRIBER_FAILED, l)
+            new a(o.ATOM_INDIVIDUAL_SUBSCRIBER_FAILED, l)
           );
         }
     };
-    this._sync && !g.isBatching ? r() : g.schedule(r);
+    this._sync && !D.isBatching ? r() : D.schedule(r);
   }
   /**
    * Subscribes a listener function to value changes.
@@ -510,7 +935,7 @@ class v {
    */
   subscribe(e) {
     if (typeof e != "function")
-      throw new a(u.ATOM_SUBSCRIBER_MUST_BE_FUNCTION);
+      throw new a(o.ATOM_SUBSCRIBER_MUST_BE_FUNCTION);
     return this._addFnSub(e);
   }
   /**
@@ -544,8 +969,8 @@ class v {
     return this._fnSubCount + this._objSubCount;
   }
 }
-function V(i, e = {}) {
-  return new v(i, e.sync ?? !1);
+function X(i, e = {}) {
+  return new L(i, e.sync ?? !1);
 }
 class N {
   constructor() {
@@ -686,11 +1111,11 @@ class N {
     return this.subscribers ? [...this.subscribers] : [];
   }
 }
-class L {
+class k {
   constructor(e, t = {}) {
     if (this._error = null, this._promiseId = 0, this.MAX_PROMISE_ID = Number.MAX_SAFE_INTEGER - 1, typeof e != "function")
-      throw new d(u.COMPUTED_MUST_BE_FUNCTION);
-    this._fn = e, this._stateFlags = o.DIRTY | o.IDLE, this._value = void 0;
+      throw new d(o.COMPUTED_MUST_BE_FUNCTION);
+    this._fn = e, this._stateFlags = u.DIRTY | u.IDLE, this._value = void 0;
     const {
       equal: s = Object.is,
       defaultValue: r = T,
@@ -709,14 +1134,14 @@ class L {
   }
   // === PUBLIC API ===
   get value() {
-    if ((this._stateFlags & (o.RESOLVED | o.DIRTY)) === o.RESOLVED)
+    if ((this._stateFlags & (u.RESOLVED | u.DIRTY)) === u.RESOLVED)
       return this._registerTracking(), this._value;
     const t = this._computeValue();
     return this._registerTracking(), t;
   }
   subscribe(e) {
     if (typeof e != "function")
-      throw new d(u.COMPUTED_SUBSCRIBER_MUST_BE_FUNCTION);
+      throw new d(o.COMPUTED_SUBSCRIBER_MUST_BE_FUNCTION);
     return this._functionSubscribers.add(e);
   }
   peek() {
@@ -741,47 +1166,47 @@ class L {
     this._markDirty();
   }
   dispose() {
-    this._dependencyManager.unsubscribeAll(), this._functionSubscribers.clear(), this._objectSubscribers.clear(), this._stateFlags = o.DIRTY | o.IDLE, this._error = null, this._value = void 0, this._promiseId = (this._promiseId + 1) % this.MAX_PROMISE_ID;
+    this._dependencyManager.unsubscribeAll(), this._functionSubscribers.clear(), this._objectSubscribers.clear(), this._stateFlags = u.DIRTY | u.IDLE, this._error = null, this._value = void 0, this._promiseId = (this._promiseId + 1) % this.MAX_PROMISE_ID;
   }
   // === PRIVATE: State Flag Operations (inlined for performance) ===
   _isDirty() {
-    return (this._stateFlags & o.DIRTY) !== 0;
+    return (this._stateFlags & u.DIRTY) !== 0;
   }
   _setDirty() {
-    this._stateFlags |= o.DIRTY;
+    this._stateFlags |= u.DIRTY;
   }
   _clearDirty() {
     this._stateFlags &= -2;
   }
   _isIdle() {
-    return (this._stateFlags & o.IDLE) !== 0;
+    return (this._stateFlags & u.IDLE) !== 0;
   }
   _setIdle() {
-    this._stateFlags |= o.IDLE, this._stateFlags &= -29;
+    this._stateFlags |= u.IDLE, this._stateFlags &= -29;
   }
   _isPending() {
-    return (this._stateFlags & o.PENDING) !== 0;
+    return (this._stateFlags & u.PENDING) !== 0;
   }
   _setPending() {
-    this._stateFlags |= o.PENDING, this._stateFlags &= -27;
+    this._stateFlags |= u.PENDING, this._stateFlags &= -27;
   }
   _isResolved() {
-    return (this._stateFlags & o.RESOLVED) !== 0;
+    return (this._stateFlags & u.RESOLVED) !== 0;
   }
   _setResolved() {
-    this._stateFlags |= o.RESOLVED, this._stateFlags &= -87;
+    this._stateFlags |= u.RESOLVED, this._stateFlags &= -87;
   }
   _isRejected() {
-    return (this._stateFlags & o.REJECTED) !== 0;
+    return (this._stateFlags & u.REJECTED) !== 0;
   }
   _setRejected() {
-    this._stateFlags |= o.REJECTED | o.HAS_ERROR, this._stateFlags &= -15;
+    this._stateFlags |= u.REJECTED | u.HAS_ERROR, this._stateFlags &= -15;
   }
   _isRecomputing() {
-    return (this._stateFlags & o.RECOMPUTING) !== 0;
+    return (this._stateFlags & u.RECOMPUTING) !== 0;
   }
   _setRecomputing(e) {
-    e ? this._stateFlags |= o.RECOMPUTING : this._stateFlags &= -33;
+    e ? this._stateFlags |= u.RECOMPUTING : this._stateFlags &= -33;
   }
   _getAsyncState() {
     return this._isPending() ? S.PENDING : this._isResolved() ? S.RESOLVED : this._isRejected() ? S.REJECTED : S.IDLE;
@@ -830,29 +1255,29 @@ class L {
     this._value = e, this._clearDirty(), this._setResolved(), this._error = null, this._setRecomputing(!1), t && this._notifySubscribers();
   }
   _handleAsyncRejection(e) {
-    const t = E(e, d, u.COMPUTED_ASYNC_COMPUTATION_FAILED);
+    const t = E(e, d, o.COMPUTED_ASYNC_COMPUTATION_FAILED);
     if (this._error = t, this._setRejected(), this._clearDirty(), this._setRecomputing(!1), this._onError && typeof this._onError == "function")
       try {
         this._onError(t);
       } catch (s) {
-        console.error(u.CALLBACK_ERROR_IN_ERROR_HANDLER, s);
+        console.error(o.CALLBACK_ERROR_IN_ERROR_HANDLER, s);
       }
     this._notifySubscribers();
   }
   _handleComputationError(e) {
-    const t = E(e, d, u.COMPUTED_COMPUTATION_FAILED);
+    const t = E(e, d, o.COMPUTED_COMPUTATION_FAILED);
     if (this._error = t, this._setRejected(), this._clearDirty(), this._setRecomputing(!1), this._onError && typeof this._onError == "function")
       try {
         this._onError(t);
       } catch (s) {
-        console.error(u.CALLBACK_ERROR_IN_ERROR_HANDLER, s);
+        console.error(o.CALLBACK_ERROR_IN_ERROR_HANDLER, s);
       }
     throw t;
   }
   _handlePending() {
     if (this._hasDefaultValue)
       return this._defaultValue;
-    throw new d(u.COMPUTED_ASYNC_PENDING_NO_DEFAULT);
+    throw new d(o.COMPUTED_ASYNC_PENDING_NO_DEFAULT);
   }
   _handleRejected() {
     if (this._error?.recoverable && this._hasDefaultValue)
@@ -892,7 +1317,7 @@ class L {
   _addDependency(e) {
     h.checkCircular(e, this);
     const t = this._dependencyManager.count;
-    h.warn(t > h.maxDependencies, u.LARGE_DEPENDENCY_GRAPH(t));
+    h.warn(t > h.maxDependencies, o.LARGE_DEPENDENCY_GRAPH(t));
     try {
       const s = e.subscribe(() => this._markDirty());
       this._dependencyManager.addDependency(e, s);
@@ -902,7 +1327,7 @@ class L {
   }
   // === PRIVATE: Subscriber Management ===
   _markDirty() {
-    this._isRecomputing() || this._isDirty() || (this._setDirty(), this._setIdle(), (this._functionSubscribers.hasSubscribers || this._objectSubscribers.hasSubscribers) && g.schedule(() => {
+    this._isRecomputing() || this._isDirty() || (this._setDirty(), this._setIdle(), (this._functionSubscribers.hasSubscribers || this._objectSubscribers.hasSubscribers) && D.schedule(() => {
       if (this._isDirty())
         try {
           this._recompute();
@@ -911,7 +1336,7 @@ class L {
     }));
   }
   _notifySubscribers() {
-    !this._functionSubscribers.hasSubscribers && !this._objectSubscribers.hasSubscribers || g.schedule(() => {
+    !this._functionSubscribers.hasSubscribers && !this._objectSubscribers.hasSubscribers || D.schedule(() => {
       this._functionSubscribers.forEachSafe(
         (e) => e(),
         (e) => console.error(e)
@@ -926,13 +1351,13 @@ class L {
     e && (typeof e == "function" ? this._functionSubscribers.add(e) : e.addDependency ? e.addDependency(this) : e.execute && this._objectSubscribers.add(e));
   }
 }
-function X(i, e = {}) {
-  return new L(i, e);
+function z(i, e = {}) {
+  return new k(i, e);
 }
 function O(i) {
   return i !== null && typeof i == "object" && "value" in i && "subscribe" in i && typeof i.subscribe == "function";
 }
-function z(i) {
+function q(i) {
   if (h.enabled) {
     const e = h.getDebugType(i);
     if (e)
@@ -940,14 +1365,39 @@ function z(i) {
   }
   return O(i) && "invalidate" in i && typeof i.invalidate == "function";
 }
-function q(i) {
+function Y(i) {
   return i !== null && typeof i == "object" && "dispose" in i && "run" in i && typeof i.dispose == "function" && typeof i.run == "function";
 }
-class k {
+class B {
+  /**
+   * Creates a new EffectImpl instance.
+   *
+   * @param fn - The effect function to execute. May return a cleanup function
+   *             or a Promise that resolves to a cleanup function.
+   * @param options - Configuration options for the effect
+   * @param options.sync - If true, re-executes synchronously on dependency changes.
+   *                       Defaults to false (scheduled execution).
+   * @param options.maxExecutionsPerSecond - Maximum executions per second before
+   *                                          infinite loop detection triggers.
+   *                                          Defaults to SCHEDULER_CONFIG.MAX_EXECUTIONS_PER_SECOND.
+   * @param options.trackModifications - If true, tracks and warns about dependencies
+   *                                     that are both read and modified. Defaults to false.
+   *
+   * @example
+   * ```typescript
+   * const impl = new EffectImpl(
+   *   () => {
+   *     console.log(counter.value);
+   *     return () => console.log('cleanup');
+   *   },
+   *   { sync: true }
+   * );
+   * ```
+   */
   constructor(e, t = {}) {
     this.run = () => {
       if (this.isDisposed)
-        throw new b(u.EFFECT_MUST_BE_FUNCTION);
+        throw new b(o.EFFECT_MUST_BE_FUNCTION);
       this.execute();
     }, this.dispose = () => {
       this.isDisposed || (this._setDisposed(), this._safeCleanup(), this._depManager.unsubscribeAll(), this._trackedDeps.size > 0 && (this._trackedDeps.forEach((s) => {
@@ -962,11 +1412,11 @@ class k {
     }, this.addDependency = (s) => {
       try {
         const r = s.subscribe(() => {
-          this._sync ? this.execute() : g.schedule(this.execute);
+          this._sync ? this.execute() : D.schedule(this.execute);
         });
         this._depManager.addDependency(s, r), this._trackModifications && O(s) && this._trackModificationsForDep(s);
       } catch (r) {
-        throw E(r, b, u.EFFECT_EXECUTION_FAILED);
+        throw E(r, b, o.EFFECT_EXECUTION_FAILED);
       }
     }, this.execute = () => {
       if (this.isDisposed || this.isExecuting) return;
@@ -977,40 +1427,145 @@ class k {
         this._checkLoopWarnings(), A(r) ? r.then((c) => {
           !this.isDisposed && typeof c == "function" && (this._cleanup = c);
         }).catch((c) => {
-          console.error(E(c, b, u.EFFECT_EXECUTION_FAILED));
+          console.error(E(c, b, o.EFFECT_EXECUTION_FAILED));
         }) : this._cleanup = typeof r == "function" ? r : null;
       } catch (r) {
-        console.error(E(r, b, u.EFFECT_EXECUTION_FAILED)), this._cleanup = null;
+        console.error(E(r, b, o.EFFECT_EXECUTION_FAILED)), this._cleanup = null;
       } finally {
         this._setExecuting(!1);
       }
     }, this._fn = e, this._sync = t.sync ?? !1, this._maxExecutions = t.maxExecutionsPerSecond ?? U.MAX_EXECUTIONS_PER_SECOND, this._trackModifications = t.trackModifications ?? !1, this._id = I(), this._flags = 0, this._cleanup = null, this._depManager = new F(), this._modifiedDeps = /* @__PURE__ */ new Set(), this._originalDescriptors = /* @__PURE__ */ new WeakMap(), this._trackedDeps = /* @__PURE__ */ new Set(), this._historyCapacity = this._maxExecutions + 5, this._history = new Float64Array(this._historyCapacity), this._historyIdx = 0, this._historyCount = 0, this._executionCount = 0, h.attachDebugInfo(this, "effect", this._id);
   }
+  /**
+   * Indicates whether this effect has been disposed.
+   *
+   * @returns `true` if the effect has been disposed, `false` otherwise
+   *
+   * @remarks
+   * A disposed effect will not execute and cannot be reactivated.
+   * Use this property to check if the effect is still active before
+   * performing operations that depend on it.
+   *
+   * @example
+   * ```typescript
+   * const fx = effect(() => console.log(counter.value));
+   * console.log(fx.isDisposed); // false
+   * fx.dispose();
+   * console.log(fx.isDisposed); // true
+   * ```
+   */
   get isDisposed() {
     return (this._flags & y.DISPOSED) !== 0;
   }
+  /**
+   * Returns the total number of times this effect has been executed.
+   *
+   * @returns The cumulative execution count since the effect was created
+   *
+   * @remarks
+   * This counter is useful for debugging, testing, and monitoring
+   * effect behavior. It increments on every execution, regardless
+   * of whether the execution succeeds or fails.
+   *
+   * @example
+   * ```typescript
+   * const fx = effect(() => console.log(counter.value));
+   * console.log(fx.executionCount); // 1 (initial execution)
+   * counter.value = 10;
+   * console.log(fx.executionCount); // 2
+   * ```
+   */
   get executionCount() {
     return this._executionCount;
   }
+  /**
+   * Indicates whether this effect is currently executing.
+   *
+   * @returns `true` if the effect is mid-execution, `false` otherwise
+   *
+   * @remarks
+   * This property is used internally to prevent re-entrant execution
+   * (an effect triggering itself during its own execution). It can
+   * also be useful for debugging to understand the effect's state.
+   *
+   * @example
+   * ```typescript
+   * const fx = effect(() => {
+   *   console.log('executing:', fx.isExecuting); // true
+   * });
+   * console.log(fx.isExecuting); // false (after execution completes)
+   * ```
+   */
   get isExecuting() {
     return (this._flags & y.EXECUTING) !== 0;
   }
+  /**
+   * Sets the disposed flag on this effect.
+   *
+   * @remarks
+   * This is a low-level method that only sets the bit flag.
+   * Use the public `dispose()` method for proper cleanup.
+   *
+   * @internal
+   */
   _setDisposed() {
     this._flags |= y.DISPOSED;
   }
+  /**
+   * Sets or clears the executing flag on this effect.
+   *
+   * @param value - `true` to mark as executing, `false` to clear
+   *
+   * @remarks
+   * Uses bitwise operations for efficient flag manipulation.
+   * This flag prevents re-entrant execution of the effect.
+   *
+   * @internal
+   */
   _setExecuting(e) {
     e ? this._flags |= y.EXECUTING : this._flags &= -3;
   }
+  /**
+   * Safely executes the cleanup function if one exists.
+   *
+   * @remarks
+   * This method:
+   * - Checks if a cleanup function exists and is callable
+   * - Wraps the cleanup call in a try-catch to prevent cleanup errors
+   *   from breaking the effect lifecycle
+   * - Logs any cleanup errors to the console
+   * - Clears the cleanup reference after execution
+   *
+   * @internal
+   */
   _safeCleanup() {
     if (this._cleanup && typeof this._cleanup == "function") {
       try {
         this._cleanup();
       } catch (e) {
-        console.error(E(e, b, u.EFFECT_CLEANUP_FAILED));
+        console.error(E(e, b, o.EFFECT_CLEANUP_FAILED));
       }
       this._cleanup = null;
     }
   }
+  /**
+   * Records an execution timestamp and checks for infinite loop conditions.
+   *
+   * @param now - The current timestamp in milliseconds (from `Date.now()`)
+   *
+   * @remarks
+   * This method implements a circular buffer to track recent execution
+   * timestamps. If the number of executions within the last second exceeds
+   * `_maxExecutions`, the effect is disposed and an error is thrown (in debug mode)
+   * or logged (in production mode).
+   *
+   * The circular buffer approach provides O(1) insertion and efficient
+   * memory usage for tracking execution history.
+   *
+   * @throws {EffectError} In debug mode, throws when infinite loop is detected
+   *
+   * @internal
+   */
   _recordExecution(e) {
     if (this._maxExecutions <= 0) return;
     const t = e - 1e3;
@@ -1024,6 +1579,21 @@ class k {
         throw n;
     }
   }
+  /**
+   * Sets up modification tracking for a dependency.
+   *
+   * @param dep - The dependency (atom) to track modifications on
+   *
+   * @remarks
+   * This method intercepts the `value` setter on the dependency to detect
+   * when the effect modifies a dependency it also reads. This pattern
+   * (read-after-write within the same effect) often indicates an infinite loop.
+   *
+   * The original property descriptor is preserved and can be restored
+   * when the effect is disposed.
+   *
+   * @internal
+   */
   _trackModificationsForDep(e) {
     const t = Object.getPrototypeOf(e), s = Object.getOwnPropertyDescriptor(t, "value");
     if (s?.set && !this._originalDescriptors.has(e)) {
@@ -1041,6 +1611,19 @@ class k {
       });
     }
   }
+  /**
+   * Checks for and warns about potential infinite loop patterns.
+   *
+   * @remarks
+   * When modification tracking is enabled and debug mode is active,
+   * this method checks if any dependencies were both read and modified
+   * during the effect execution. Such patterns often lead to infinite loops.
+   *
+   * Warnings are only emitted in debug mode to avoid performance overhead
+   * in production.
+   *
+   * @internal
+   */
   _checkLoopWarnings() {
     if (this._trackModifications && h.enabled) {
       const e = this._depManager.getDependencies();
@@ -1054,10 +1637,10 @@ class k {
     }
   }
 }
-function Y(i, e = {}) {
+function Q(i, e = {}) {
   if (typeof i != "function")
-    throw new b(u.EFFECT_MUST_BE_FUNCTION);
-  const t = new k(i, e);
+    throw new b(o.EFFECT_MUST_BE_FUNCTION);
+  const t = new B(i, e);
   return t.execute(), t;
 }
 export {
@@ -1067,17 +1650,17 @@ export {
   m as DEBUG_CONFIG,
   h as DEBUG_RUNTIME,
   b as EffectError,
-  B as POOL_CONFIG,
+  j as POOL_CONFIG,
   U as SCHEDULER_CONFIG,
-  D as SchedulerError,
-  V as atom,
-  j as batch,
-  X as computed,
-  Y as effect,
+  g as SchedulerError,
+  X as atom,
+  G as batch,
+  z as computed,
+  Q as effect,
   O as isAtom,
-  z as isComputed,
-  q as isEffect,
-  g as scheduler,
-  G as untracked
+  q as isComputed,
+  Y as isEffect,
+  D as scheduler,
+  V as untracked
 };
 //# sourceMappingURL=index.mjs.map