signalium 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # signalium
 
+## 4.0.2
+
+### Patch Changes
+
+- 2bf532c: Fix `watchOnce` letting a pending async graph be garbage collected before it settles. The watcher is now kept alive until its promise fulfills or rejects.
+
 ## 4.0.1
 
 ### Patch Changes

package/dist/cjs/development/utils.js

@@ -3,21 +3,26 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const snapshot = require("./snapshot-BLa9mv8h.js");
 const debug = require("./debug-BS6RdX4D.js");
 const config = require("./config-D6wyrhrW.js");
+const pendingOnceWatchers = /* @__PURE__ */ new Set();
 function watchOnce(fn) {
   const signal = snapshot.watcher(fn);
+  pendingOnceWatchers.add(signal);
+  const release = () => {
+    if (pendingOnceWatchers.delete(signal)) {
+      debug.unwatchSignal(signal);
+    }
+  };
   try {
     debug.watchSignal(signal);
     let result = debug.getSignal(signal);
-    if (debug.isReactivePromise(result) || debug.isPromise(result)) {
-      result = result.finally(() => {
-        debug.unwatchSignal(signal);
-      });
+    if (result !== null && typeof result === "object" && (debug.isReactivePromise(result) || debug.isPromise(result))) {
+      result = result.finally(release);
     } else {
-      debug.unwatchSignal(signal);
+      release();
     }
     return result;
   } catch (error) {
-    debug.unwatchSignal(signal);
+    release();
     throw error;
   }
 }

package/dist/cjs/development/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n *\n * @param fn - A sync or async function to watch once\n * @returns A promise that resolves with the function's return value\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (isReactivePromise(result) || isPromise(result)) {\n            result = result.finally(() => {\n                unwatchSignal(signal);\n            });\n        }\n        else {\n            unwatchSignal(signal);\n        }\n        return result;\n    }\n    catch (error) {\n        unwatchSignal(signal);\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":["watcher","watchSignal","getSignal","isReactivePromise","isPromise","unwatchSignal","MAX_TIMEOUT"],"mappings":";;;;;AA8BO,SAAS,UAAU,IAAI;AAE1B,QAAM,SAASA,SAAAA,QAAQ,EAAE;AACzB,MAAI;AAEAC,UAAAA,YAAY,MAAM;AAElB,QAAI,SAASC,MAAAA,UAAU,MAAM;AAC7B,QAAIC,MAAAA,kBAAkB,MAAM,KAAKC,MAAAA,UAAU,MAAM,GAAG;AAChD,eAAS,OAAO,QAAQ,MAAM;AAC1BC,cAAAA,cAAc,MAAM;AAAA,MACxB,CAAC;AAAA,IACL,OACK;AACDA,YAAAA,cAAc,MAAM;AAAA,IACxB;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACVA,UAAAA,cAAc,MAAM;AACpB,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAASL,SAAAA,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEAE,UAAAA,UAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAKI,OAAAA,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAACH,MAAAA,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;;;;;;;;;;;"}
+{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n// Promise reactions and weak graph edges do not root their producing watcher.\nconst pendingOnceWatchers = new Set();\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n * Pending operations keep their watcher alive until fulfillment or rejection.\n * There is no timeout or cancellation; work that never settles remains watched.\n *\n * @param fn - A sync or async function to watch once\n * @returns The synchronous value, or a native promise for an asynchronous result\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    pendingOnceWatchers.add(signal);\n    const release = () => {\n        if (pendingOnceWatchers.delete(signal)) {\n            unwatchSignal(signal);\n        }\n    };\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (result !== null && typeof result === 'object' && (isReactivePromise(result) || isPromise(result))) {\n            result = result.finally(release);\n        }\n        else {\n            release();\n        }\n        return result;\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":["watcher","unwatchSignal","watchSignal","getSignal","isReactivePromise","isPromise","MAX_TIMEOUT"],"mappings":";;;;;AASA,MAAM,sBAAsB,oBAAI,IAAG;AAyB5B,SAAS,UAAU,IAAI;AAE1B,QAAM,SAASA,SAAAA,QAAQ,EAAE;AACzB,sBAAoB,IAAI,MAAM;AAC9B,QAAM,UAAU,MAAM;AAClB,QAAI,oBAAoB,OAAO,MAAM,GAAG;AACpCC,YAAAA,cAAc,MAAM;AAAA,IACxB;AAAA,EACJ;AACA,MAAI;AAEAC,UAAAA,YAAY,MAAM;AAElB,QAAI,SAASC,MAAAA,UAAU,MAAM;AAC7B,QAAI,WAAW,QAAQ,OAAO,WAAW,aAAaC,wBAAkB,MAAM,KAAKC,MAAAA,UAAU,MAAM,IAAI;AACnG,eAAS,OAAO,QAAQ,OAAO;AAAA,IACnC,OACK;AACD,cAAO;AAAA,IACX;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAASL,SAAAA,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEAG,UAAAA,UAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAKG,OAAAA,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAACF,MAAAA,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;;;;;;;;;;;"}

package/dist/cjs/production/utils.js

@@ -3,21 +3,26 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const snapshot = require("./snapshot-gv-aZDmB.js");
 const contexts = require("./contexts-Bkwv59kH.js");
 const config = require("./config-BHvmcsLQ.js");
+const pendingOnceWatchers = /* @__PURE__ */ new Set();
 function watchOnce(fn) {
   const signal = snapshot.watcher(fn);
+  pendingOnceWatchers.add(signal);
+  const release = () => {
+    if (pendingOnceWatchers.delete(signal)) {
+      contexts.unwatchSignal(signal);
+    }
+  };
   try {
     contexts.watchSignal(signal);
     let result = contexts.getSignal(signal);
-    if (contexts.isReactivePromise(result) || contexts.isPromise(result)) {
-      result = result.finally(() => {
-        contexts.unwatchSignal(signal);
-      });
+    if (result !== null && typeof result === "object" && (contexts.isReactivePromise(result) || contexts.isPromise(result))) {
+      result = result.finally(release);
     } else {
-      contexts.unwatchSignal(signal);
+      release();
     }
     return result;
   } catch (error) {
-    contexts.unwatchSignal(signal);
+    release();
     throw error;
   }
 }

package/dist/cjs/production/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n *\n * @param fn - A sync or async function to watch once\n * @returns A promise that resolves with the function's return value\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (isReactivePromise(result) || isPromise(result)) {\n            result = result.finally(() => {\n                unwatchSignal(signal);\n            });\n        }\n        else {\n            unwatchSignal(signal);\n        }\n        return result;\n    }\n    catch (error) {\n        unwatchSignal(signal);\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":["watcher","watchSignal","getSignal","isReactivePromise","isPromise","unwatchSignal","MAX_TIMEOUT"],"mappings":";;;;;AA8BO,SAAS,UAAU,IAAI;AAE1B,QAAM,SAASA,SAAAA,QAAQ,EAAE;AACzB,MAAI;AAEAC,aAAAA,YAAY,MAAM;AAElB,QAAI,SAASC,SAAAA,UAAU,MAAM;AAC7B,QAAIC,SAAAA,kBAAkB,MAAM,KAAKC,SAAAA,UAAU,MAAM,GAAG;AAChD,eAAS,OAAO,QAAQ,MAAM;AAC1BC,iBAAAA,cAAc,MAAM;AAAA,MACxB,CAAC;AAAA,IACL,OACK;AACDA,eAAAA,cAAc,MAAM;AAAA,IACxB;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACVA,aAAAA,cAAc,MAAM;AACpB,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAASL,SAAAA,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEAE,aAAAA,UAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAKI,OAAAA,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAACH,SAAAA,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;;;;;;;;;;;"}
+{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n// Promise reactions and weak graph edges do not root their producing watcher.\nconst pendingOnceWatchers = new Set();\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n * Pending operations keep their watcher alive until fulfillment or rejection.\n * There is no timeout or cancellation; work that never settles remains watched.\n *\n * @param fn - A sync or async function to watch once\n * @returns The synchronous value, or a native promise for an asynchronous result\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    pendingOnceWatchers.add(signal);\n    const release = () => {\n        if (pendingOnceWatchers.delete(signal)) {\n            unwatchSignal(signal);\n        }\n    };\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (result !== null && typeof result === 'object' && (isReactivePromise(result) || isPromise(result))) {\n            result = result.finally(release);\n        }\n        else {\n            release();\n        }\n        return result;\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":["watcher","unwatchSignal","watchSignal","getSignal","isReactivePromise","isPromise","MAX_TIMEOUT"],"mappings":";;;;;AASA,MAAM,sBAAsB,oBAAI,IAAG;AAyB5B,SAAS,UAAU,IAAI;AAE1B,QAAM,SAASA,SAAAA,QAAQ,EAAE;AACzB,sBAAoB,IAAI,MAAM;AAC9B,QAAM,UAAU,MAAM;AAClB,QAAI,oBAAoB,OAAO,MAAM,GAAG;AACpCC,eAAAA,cAAc,MAAM;AAAA,IACxB;AAAA,EACJ;AACA,MAAI;AAEAC,aAAAA,YAAY,MAAM;AAElB,QAAI,SAASC,SAAAA,UAAU,MAAM;AAC7B,QAAI,WAAW,QAAQ,OAAO,WAAW,aAAaC,2BAAkB,MAAM,KAAKC,SAAAA,UAAU,MAAM,IAAI;AACnG,eAAS,OAAO,QAAQ,OAAO;AAAA,IACnC,OACK;AACD,cAAO;AAAA,IACX;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAASL,SAAAA,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEAG,aAAAA,UAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAKG,OAAAA,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAACF,SAAAA,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;;;;;;;;;;;"}

package/dist/esm/development/utils.js

@@ -3,21 +3,26 @@ import { a, s, b, c } from "./snapshot-CMsut-I_.js";
 import { z as watchSignal, B as getSignal, j as isReactivePromise, r as isPromise, C as unwatchSignal } from "./debug-D7mtRqCt.js";
 import { l, D, E } from "./debug-D7mtRqCt.js";
 import { M as MAX_TIMEOUT } from "./config-CQLKpPRj.js";
+const pendingOnceWatchers = /* @__PURE__ */ new Set();
 function watchOnce(fn) {
   const signal = watcher(fn);
+  pendingOnceWatchers.add(signal);
+  const release = () => {
+    if (pendingOnceWatchers.delete(signal)) {
+      unwatchSignal(signal);
+    }
+  };
   try {
     watchSignal(signal);
     let result = getSignal(signal);
-    if (isReactivePromise(result) || isPromise(result)) {
-      result = result.finally(() => {
-        unwatchSignal(signal);
-      });
+    if (result !== null && typeof result === "object" && (isReactivePromise(result) || isPromise(result))) {
+      result = result.finally(release);
     } else {
-      unwatchSignal(signal);
+      release();
     }
     return result;
   } catch (error) {
-    unwatchSignal(signal);
+    release();
     throw error;
   }
 }

package/dist/esm/development/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n *\n * @param fn - A sync or async function to watch once\n * @returns A promise that resolves with the function's return value\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (isReactivePromise(result) || isPromise(result)) {\n            result = result.finally(() => {\n                unwatchSignal(signal);\n            });\n        }\n        else {\n            unwatchSignal(signal);\n        }\n        return result;\n    }\n    catch (error) {\n        unwatchSignal(signal);\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":[],"mappings":";;;;;AA8BO,SAAS,UAAU,IAAI;AAE1B,QAAM,SAAS,QAAQ,EAAE;AACzB,MAAI;AAEA,gBAAY,MAAM;AAElB,QAAI,SAAS,UAAU,MAAM;AAC7B,QAAI,kBAAkB,MAAM,KAAK,UAAU,MAAM,GAAG;AAChD,eAAS,OAAO,QAAQ,MAAM;AAC1B,sBAAc,MAAM;AAAA,MACxB,CAAC;AAAA,IACL,OACK;AACD,oBAAc,MAAM;AAAA,IACxB;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,kBAAc,MAAM;AACpB,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAAS,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEA,cAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAK,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAAC,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;"}
+{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n// Promise reactions and weak graph edges do not root their producing watcher.\nconst pendingOnceWatchers = new Set();\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n * Pending operations keep their watcher alive until fulfillment or rejection.\n * There is no timeout or cancellation; work that never settles remains watched.\n *\n * @param fn - A sync or async function to watch once\n * @returns The synchronous value, or a native promise for an asynchronous result\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    pendingOnceWatchers.add(signal);\n    const release = () => {\n        if (pendingOnceWatchers.delete(signal)) {\n            unwatchSignal(signal);\n        }\n    };\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (result !== null && typeof result === 'object' && (isReactivePromise(result) || isPromise(result))) {\n            result = result.finally(release);\n        }\n        else {\n            release();\n        }\n        return result;\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":[],"mappings":";;;;;AASA,MAAM,sBAAsB,oBAAI,IAAG;AAyB5B,SAAS,UAAU,IAAI;AAE1B,QAAM,SAAS,QAAQ,EAAE;AACzB,sBAAoB,IAAI,MAAM;AAC9B,QAAM,UAAU,MAAM;AAClB,QAAI,oBAAoB,OAAO,MAAM,GAAG;AACpC,oBAAc,MAAM;AAAA,IACxB;AAAA,EACJ;AACA,MAAI;AAEA,gBAAY,MAAM;AAElB,QAAI,SAAS,UAAU,MAAM;AAC7B,QAAI,WAAW,QAAQ,OAAO,WAAW,aAAa,kBAAkB,MAAM,KAAK,UAAU,MAAM,IAAI;AACnG,eAAS,OAAO,QAAQ,OAAO;AAAA,IACnC,OACK;AACD,cAAO;AAAA,IACX;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAAS,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEA,cAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAK,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAAC,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;"}

package/dist/esm/production/utils.js

@@ -3,21 +3,26 @@ import { a, s, b, c } from "./snapshot-Bx73RooF.js";
 import { D as watchSignal, E as getSignal, l as isReactivePromise, v as isPromise, F as unwatchSignal } from "./contexts-D2PPNujL.js";
 import { n, G, H } from "./contexts-D2PPNujL.js";
 import { M as MAX_TIMEOUT } from "./config-BhtwQYAN.js";
+const pendingOnceWatchers = /* @__PURE__ */ new Set();
 function watchOnce(fn) {
   const signal = watcher(fn);
+  pendingOnceWatchers.add(signal);
+  const release = () => {
+    if (pendingOnceWatchers.delete(signal)) {
+      unwatchSignal(signal);
+    }
+  };
   try {
     watchSignal(signal);
     let result = getSignal(signal);
-    if (isReactivePromise(result) || isPromise(result)) {
-      result = result.finally(() => {
-        unwatchSignal(signal);
-      });
+    if (result !== null && typeof result === "object" && (isReactivePromise(result) || isPromise(result))) {
+      result = result.finally(release);
     } else {
-      unwatchSignal(signal);
+      release();
     }
     return result;
   } catch (error) {
-    unwatchSignal(signal);
+    release();
     throw error;
   }
 }

package/dist/esm/production/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n *\n * @param fn - A sync or async function to watch once\n * @returns A promise that resolves with the function's return value\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (isReactivePromise(result) || isPromise(result)) {\n            result = result.finally(() => {\n                unwatchSignal(signal);\n            });\n        }\n        else {\n            unwatchSignal(signal);\n        }\n        return result;\n    }\n    catch (error) {\n        unwatchSignal(signal);\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":[],"mappings":";;;;;AA8BO,SAAS,UAAU,IAAI;AAE1B,QAAM,SAAS,QAAQ,EAAE;AACzB,MAAI;AAEA,gBAAY,MAAM;AAElB,QAAI,SAAS,UAAU,MAAM;AAC7B,QAAI,kBAAkB,MAAM,KAAK,UAAU,MAAM,GAAG;AAChD,eAAS,OAAO,QAAQ,MAAM;AAC1B,sBAAc,MAAM;AAAA,MACxB,CAAC;AAAA,IACL,OACK;AACD,oBAAc,MAAM;AAAA,IACxB;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,kBAAc,MAAM;AACpB,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAAS,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEA,cAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAK,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAAC,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;"}
+{"version":3,"file":"utils.js","sources":["../../../.tsc-out/utils.js"],"sourcesContent":["export { hashValue, registerCustomHash } from './internals/utils/hash.js';\nexport { snapshot, registerCustomSnapshot, snapshotArray, snapshotPlainObject, } from './internals/utils/snapshot.js';\nimport { watcher } from './internals/core-api.js';\nimport { watchSignal, unwatchSignal } from './internals/watch.js';\nimport { getSignal } from './internals/get.js';\nimport { isReactivePromise } from './internals/async.js';\nimport { isPromise } from './internals/utils/type-utils.js';\nimport { MAX_TIMEOUT } from './internals/config.js';\n// Promise reactions and weak graph edges do not root their producing watcher.\nconst pendingOnceWatchers = new Set();\n/**\n * Watches a function once in a reactive context, activating any relays,\n * then automatically tears down the watcher when complete.\n *\n * This is useful for testing or one-time reactive operations where you need\n * relays to be active but don't want the watcher to reschedule on updates.\n * Pending operations keep their watcher alive until fulfillment or rejection.\n * There is no timeout or cancellation; work that never settles remains watched.\n *\n * @param fn - A sync or async function to watch once\n * @returns The synchronous value, or a native promise for an asynchronous result\n *\n * @example\n * ```ts\n * await watchOnce(async () => {\n *   const data = relay((state) => {\n *     // relay will be activated during watchOnce\n *     fetch('/api/data').then(res => state.value = res.data);\n *   });\n *   await data;\n *   return data.value;\n * });\n * ```\n */\nexport function watchOnce(fn) {\n    // Create a watcher signal\n    const signal = watcher(fn);\n    pendingOnceWatchers.add(signal);\n    const release = () => {\n        if (pendingOnceWatchers.delete(signal)) {\n            unwatchSignal(signal);\n        }\n    };\n    try {\n        // Watch the signal to activate any relays\n        watchSignal(signal);\n        // Get the value, which runs the function\n        let result = getSignal(signal);\n        if (result !== null && typeof result === 'object' && (isReactivePromise(result) || isPromise(result))) {\n            result = result.finally(release);\n        }\n        else {\n            release();\n        }\n        return result;\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n}\n/**\n * Keeps `fn`'s dependencies (relays, queries) watched until `ttl` ms pass or the returned\n * `release` is called. Without a `ttl`, or with `Infinity`, it lasts until released. A `ttl` above\n * 2^31 - 1 ms is clamped; a negative or `NaN` one throws a `RangeError`.\n *\n * Use it to keep data warm without rendering it, e.g. prefetching a likely next screen. `fn` runs\n * now, in the current scope, and again when its dependencies change.\n *\n * @example\n * ```ts\n * const release = retain(() => fetchTokenDetail(id), { ttl: 30_000 });\n * ```\n */\nexport function retain(fn, opts) {\n    const ttl = opts?.ttl;\n    if (ttl !== undefined && (typeof ttl !== 'number' || Number.isNaN(ttl) || ttl < 0)) {\n        throw new RangeError(`signalium: retain() ttl must be a non-negative number of milliseconds, got ${String(ttl)}`);\n    }\n    const signal = watcher(fn);\n    const unsubscribe = signal.addListener(noop);\n    let timer;\n    const release = () => {\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            timer = undefined;\n        }\n        unsubscribe();\n    };\n    try {\n        // Run now so relays activate immediately, not on the next flush.\n        getSignal(signal);\n    }\n    catch (error) {\n        release();\n        throw error;\n    }\n    // `setTimeout` fires immediately for delays above MAX_TIMEOUT.\n    if (ttl !== undefined && ttl !== Infinity) {\n        timer = setTimeout(release, Math.min(ttl, MAX_TIMEOUT));\n    }\n    return release;\n}\nconst noop = () => { };\nexport { setReactivePromise } from './internals/async.js';\n/**\n * Forwards state from a source relay to the target relay's state.\n * This enables composition patterns where relays can add side effects\n * while transparently forwarding state from another relay.\n *\n * The forwarding is automatically tracked through the signal graph.\n * When the source relay updates, the target relay will re-run its\n * activation function, and forwardRelay will forward the new state.\n * No cleanup is needed - dependencies are managed automatically.\n *\n * @param state - The target relay's state object\n * @param sourceRelay - The source relay to forward state from\n *\n * @example\n * ```ts\n * const sourceRelay = relay(state => {\n *   // ... source relay logic\n * });\n *\n * const forwardedRelay = relay(state => {\n *   // Add additional side effect\n *   const cleanup = setupSomeEffect();\n *\n *   // Forward state from source relay (automatically tracked and cleaned up)\n *   forwardRelay(state, sourceRelay);\n *\n *   return cleanup; // Only return cleanup for the additional effect\n * });\n * ```\n */\nexport function forwardRelay(state, sourceRelay) {\n    // Verify that sourceRelay is actually a ReactivePromiseImpl\n    if (!isReactivePromise(sourceRelay)) {\n        throw new Error('forwardRelay: sourceRelay must be a ReactivePromise');\n    }\n    // Read from source relay to establish dependency and forward state\n    // When sourceRelay updates, this relay's activation function will be called again,\n    // and forwardRelay will be called again, forwarding the new state\n    if (sourceRelay.isPending) {\n        // For pending state, try to forward the promise if available\n        // Accessing isPending establishes the dependency\n        const source = sourceRelay;\n        const promise = source['_promise'];\n        if (promise) {\n            state.setPromise(promise);\n        }\n    }\n    else if (sourceRelay.isRejected) {\n        // Accessing error establishes dependency and forwards it\n        const error = sourceRelay.error;\n        if (error !== undefined) {\n            state.setError(error);\n        }\n    }\n    else if (sourceRelay.isResolved && sourceRelay.isReady) {\n        // Accessing value establishes dependency and forwards it\n        const value = sourceRelay.value;\n        if (value !== undefined) {\n            state.value = value;\n        }\n    }\n}\n"],"names":[],"mappings":";;;;;AASA,MAAM,sBAAsB,oBAAI,IAAG;AAyB5B,SAAS,UAAU,IAAI;AAE1B,QAAM,SAAS,QAAQ,EAAE;AACzB,sBAAoB,IAAI,MAAM;AAC9B,QAAM,UAAU,MAAM;AAClB,QAAI,oBAAoB,OAAO,MAAM,GAAG;AACpC,oBAAc,MAAM;AAAA,IACxB;AAAA,EACJ;AACA,MAAI;AAEA,gBAAY,MAAM;AAElB,QAAI,SAAS,UAAU,MAAM;AAC7B,QAAI,WAAW,QAAQ,OAAO,WAAW,aAAa,kBAAkB,MAAM,KAAK,UAAU,MAAM,IAAI;AACnG,eAAS,OAAO,QAAQ,OAAO;AAAA,IACnC,OACK;AACD,cAAO;AAAA,IACX;AACA,WAAO;AAAA,EACX,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AACJ;AAcO,SAAS,OAAO,IAAI,MAAM;AAC7B,QAAM,MAAM,MAAM;AAClB,MAAI,QAAQ,WAAc,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,IAAI;AAChF,UAAM,IAAI,WAAW,8EAA8E,OAAO,GAAG,CAAC,EAAE;AAAA,EACpH;AACA,QAAM,SAAS,QAAQ,EAAE;AACzB,QAAM,cAAc,OAAO,YAAY,IAAI;AAC3C,MAAI;AACJ,QAAM,UAAU,MAAM;AAClB,QAAI,UAAU,QAAW;AACrB,mBAAa,KAAK;AAClB,cAAQ;AAAA,IACZ;AACA,gBAAW;AAAA,EACf;AACA,MAAI;AAEA,cAAU,MAAM;AAAA,EACpB,SACO,OAAO;AACV,YAAO;AACP,UAAM;AAAA,EACV;AAEA,MAAI,QAAQ,UAAa,QAAQ,UAAU;AACvC,YAAQ,WAAW,SAAS,KAAK,IAAI,KAAK,WAAW,CAAC;AAAA,EAC1D;AACA,SAAO;AACX;AACA,MAAM,OAAO,MAAM;AAAE;AAgCd,SAAS,aAAa,OAAO,aAAa;AAE7C,MAAI,CAAC,kBAAkB,WAAW,GAAG;AACjC,UAAM,IAAI,MAAM,qDAAqD;AAAA,EACzE;AAIA,MAAI,YAAY,WAAW;AAGvB,UAAM,SAAS;AACf,UAAM,UAAU,OAAO,UAAU;AACjC,QAAI,SAAS;AACT,YAAM,WAAW,OAAO;AAAA,IAC5B;AAAA,EACJ,WACS,YAAY,YAAY;AAE7B,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,SAAS,KAAK;AAAA,IACxB;AAAA,EACJ,WACS,YAAY,cAAc,YAAY,SAAS;AAEpD,UAAM,QAAQ,YAAY;AAC1B,QAAI,UAAU,QAAW;AACrB,YAAM,QAAQ;AAAA,IAClB;AAAA,EACJ;AACJ;"}

package/dist/esm/utils.d.ts

@@ -7,9 +7,11 @@ import { RelayState, ReactivePromise } from './types.js';
  *
  * This is useful for testing or one-time reactive operations where you need
  * relays to be active but don't want the watcher to reschedule on updates.
+ * Pending operations keep their watcher alive until fulfillment or rejection.
+ * There is no timeout or cancellation; work that never settles remains watched.
  *
  * @param fn - A sync or async function to watch once
- * @returns A promise that resolves with the function's return value
+ * @returns The synchronous value, or a native promise for an asynchronous result
  *
  * @example
  * ```ts

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AASvC,OAAO,EAAiB,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAwB3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,IAAI,CAkC7E;AAID,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CA8B3F"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AASvC,OAAO,EAAiB,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMxE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CA6B3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,IAAI,CAkC7E;AAID,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CA8B3F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalium",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "repository": {
     "type": "git",