uneventful 0.0.13 → 0.0.15

package/dist/{call-or-wait-CvOF0pao.mjs → call-or-wait-BTeEcToS.mjs}

@@ -1,5 +1,5 @@
-import { s as start, j as connect, p as isValue, h as isError, f as markHandled } from './jobutils-O9tOTNKC.mjs';
-import { i as isFunction } from './utils-BgqyDPjA.mjs';
+import { s as start, j as connect, p as isValue, h as isError, f as markHandled } from './jobutils-DYe7dvZO.mjs';
+import { i as isFunction } from './utils-CwhAPj4M.mjs';
 
 function callOrWait(source, method, handler, noArgs) {
   if (source && isFunction(source[method]))

package/dist/ext.d.ts

@@ -1,4 +1,4 @@
-import { P as PlainFunction } from './types-pElgImr7.js';
+import { P as PlainFunction } from './types-C3WWddF2.js';
 
 /**
  * This module provides helpers for creating *extensions*: a way of extending

package/dist/ext.mjs

@@ -1,4 +1,4 @@
-import { s as setMap } from './utils-BgqyDPjA.mjs';
+import { s as setMap } from './utils-CwhAPj4M.mjs';
 
 function ext(factory, map = /* @__PURE__ */ new WeakMap()) {
   return (tgt) => map.has(tgt) ? map.get(tgt) : setMap(map, tgt, factory(tgt, map));

package/dist/{hooks-BnMYHRlM.mjs → hooks-Bx4Lqd9S.mjs}

@@ -1,5 +1,5 @@
-import { M as pushCtx, N as popCtx, c as backpressure, I as IsStream, _ as _Job, d as root, h as isError, f as markHandled, g as getJob, o as currentCell } from './jobutils-O9tOTNKC.mjs';
-import { h as batch, d as defer, c as apply, s as setMap } from './utils-BgqyDPjA.mjs';
+import { N as pushCtx, O as popCtx, c as backpressure, I as IsStream, l as currentCell, _ as _Job, d as root, h as isError, f as markHandled, g as getJob } from './jobutils-DYe7dvZO.mjs';
+import { d as defer, b as apply, s as setMap, h as batch } from './utils-CwhAPj4M.mjs';
 
 const ruleQueues = /* @__PURE__ */ new WeakMap();
 function ruleQueue(scheduleFn = defer) {
@@ -209,6 +209,8 @@ class Cell {
       this.catchUp();
       if (this.adding === s)
         s.ts = this.lastChanged;
+    } else if (dep === false) {
+      throw new Error("Reactive values can't be used while creating singletons or lazy constants");
     } else
       this.catchUp();
     if (this.flags & 16 /* Error */)
@@ -241,7 +243,7 @@ class Cell {
     if (this.shouldWrite(val !== this.value || isErr !== !!(this.flags & 16 /* Error */))) {
       this.value = val;
       this.lastChanged = timestamp;
-      this.flags = isErr ? this.flags | 16 /* Error */ : this.flags & ~16 /* Error */;
+      this.flags = isErr ? this.flags | 16 /* Error */ : this.flags & -17 /* Error */;
     }
     this.compute = isErr ? throwValue : returnValue;
   }
@@ -318,11 +320,11 @@ class Cell {
           throw e;
       }
     } finally {
-      this.flags &= ~32 /* Running */;
+      this.flags &= -33 /* Running */;
       if (this.flags & 64 /* Stateful */) {
         demandChanges.delete(this);
         if (this.flags & (16 /* Error */ | 2 /* Stopped */)) {
-          this.flags &= ~2 /* Stopped */;
+          this.flags &= -3 /* Stopped */;
           this.job?.restart();
         } else if (this.flags & 1 /* Observed */) ; else {
           this.job?.restart();
@@ -350,7 +352,7 @@ class Cell {
       mksub(dummySource ||= Cell.mkValue(null), this);
       return;
     }
-    this.flags &= ~4 /* Compute */;
+    this.flags &= -5 /* Compute */;
     if (this.flags & 132 /* Variable */)
       return;
     while (this.adding)
@@ -480,7 +482,7 @@ class Cell {
     try {
       return apply(fn, thisArg, args);
     } finally {
-      this.flags &= ~8 /* Peeking */;
+      this.flags &= -9 /* Peeking */;
     }
   }
   unchangedIf(newVal, equals) {
@@ -572,7 +574,13 @@ function perSignal(func, site, name) {
       if (findOrCreateMemos(hooks2, site, 1)) {
         return getMemo(hooks2, 1)();
       } else {
-        const result = func(...args);
+        let result;
+        pushCtx(void 0, false);
+        try {
+          result = func(...args);
+        } finally {
+          popCtx();
+        }
         setMemo(hooks2, 1, () => result);
         return result;
       }

package/dist/{jobutils-O9tOTNKC.mjs → jobutils-DYe7dvZO.mjs}

@@ -1,4 +1,4 @@
-import { h as batch, d as defer, i as isFunction, G as GeneratorBase, c as apply } from './utils-BgqyDPjA.mjs';
+import { h as batch, d as defer, i as isFunction, G as GeneratorBase, b as apply } from './utils-CwhAPj4M.mjs';
 
 function resolve(request, val) {
   request("next", val);
@@ -80,7 +80,7 @@ function popCtx() {
   currentCell = cells.pop();
 }
 function cellJob() {
-  return currentJob ||= currentCell?.getJob();
+  return currentJob ||= currentCell ? currentCell.getJob() : void 0;
 }
 
 const catchers = /* @__PURE__ */ new WeakMap(), defaultCatch = (e) => {
@@ -93,6 +93,20 @@ const pulls = /* @__PURE__ */ batch((pulls2) => {
     conn.doPull();
   }
 }, defer);
+let singletons;
+function resetSingletons() {
+  singletons = /* @__PURE__ */ new WeakMap();
+  activeServices.forEach((r) => {
+    const c = r.deref();
+    if (c) {
+      c.valid = false;
+      c.value = void 0;
+    } else {
+      activeServices.delete(r);
+    }
+  });
+}
+const activeServices = /* @__PURE__ */ new Set();
 
 function chain() {
   return link(0, void 0, void 0);
@@ -259,7 +273,7 @@ class _Job {
     });
   }
   result() {
-    return this._done || currentCell?.recalcWhen(this, recalcJob) || void 0;
+    return this._done || currentCell && currentCell.recalcWhen(this, recalcJob) || void 0;
   }
   get [Symbol.toStringTag]() {
     return "Job";
@@ -451,6 +465,7 @@ let root;
 newRoot();
 function newRoot() {
   root?.end();
+  resetSingletons();
   const job = root = new _Job().asyncCatch(defaultCatch);
   job.release(() => root === job && (root = null));
   return root;
@@ -614,7 +629,7 @@ function start(init, fn) {
   return getJob().start(init, fn);
 }
 function isJobActive() {
-  return !!(currentJob || currentCell?.isObserved());
+  return !!(currentJob || currentCell && currentCell.isObserved());
 }
 const timers = /* @__PURE__ */ new WeakMap();
 function timeout(ms = 0, job = getJob()) {
@@ -679,4 +694,4 @@ function task(fn, _ctx, desc) {
   };
 }
 
-export { CancelError as A, pipe as B, CancelResult as C, compose as D, ErrorResult as E, into as F, isJobActive as G, timeout as H, IsStream as I, abortSignal as J, task as K, currentJob as L, pushCtx as M, popCtx as N, ValueResult as V, _Job as _, rejecter as a, resolve as b, backpressure as c, root as d, isUnhandled as e, markHandled as f, getJob as g, isError as h, isCancel as i, connect as j, fulfillPromise as k, restarting as l, must as m, noop as n, currentCell as o, isValue as p, nativePromise as q, resolver as r, start as s, throttle as t, makeJob as u, newRoot as v, reject as w, isHandled as x, getResult as y, propagateResult as z };
+export { makeJob as A, nativePromise as B, CancelError as C, newRoot as D, ErrorResult as E, pipe as F, propagateResult as G, reject as H, IsStream as I, task as J, timeout as K, singletons as L, activeServices as M, pushCtx as N, popCtx as O, currentJob as P, ValueResult as V, _Job as _, resolver as a, rejecter as b, backpressure as c, root as d, isUnhandled as e, markHandled as f, getJob as g, isError as h, isCancel as i, connect as j, fulfillPromise as k, currentCell as l, must as m, noop as n, restarting as o, isValue as p, CancelResult as q, resolve as r, start as s, throttle as t, abortSignal as u, compose as v, getResult as w, into as x, isHandled as y, isJobActive as z };

package/dist/mod.d.ts

@@ -1,6 +1,6 @@
-import { J as Job, C as CleanupFn, Y as Yielding, S as Source, D as DisposeFn, a as Stream, B as Backpressure, T as Transformer, b as Sink, O as OptionalCleanup, c as StartFn, d as StartObj, A as AnyFunction } from './types-pElgImr7.js';
-export { e as AsyncStart, z as CancelError, m as CancelResult, K as Connection, E as ErrorResult, H as HandledError, I as Inlet, M as IsStream, g as JobIterator, o as JobResult, N as Nothing, P as PlainFunction, i as RecalcSource, R as Request, L as SignalSource, h as Suspend, f as SyncStart, G as Throttle, U as UnhandledError, V as ValueResult, F as backpressure, Z as compose, Q as connect, x as fulfillPromise, w as getResult, _ as into, p as isCancel, s as isError, u as isHandled, t as isUnhandled, q as isValue, v as markHandled, n as noop, X as pipe, y as propagateResult, j as reject, l as rejecter, r as resolve, k as resolver, W as throttle } from './types-pElgImr7.js';
-export { a as Each, E as EachResult, N as NextMethod, U as UntilMethod, e as each, f as forEach, i as isObserved, n as next, r as recalcWhen } from './sinks-B_LfTZgF.js';
+import { J as Job, C as CleanupFn, Y as Yielding, S as Source, B as Backpressure, D as DisposeFn, a as Stream, T as Transformer, b as Sink, O as OptionalCleanup, A as AnyFunction, c as StartFn, d as StartObj } from './types-C3WWddF2.js';
+export { e as AsyncStart, f as CancelError, g as CancelResult, h as Connection, E as ErrorResult, H as HandledError, I as Inlet, i as IsStream, j as JobIterator, k as JobResult, N as Nothing, P as PlainFunction, R as RecalcSource, l as Request, m as SignalSource, n as Suspend, o as SyncStart, p as Throttle, U as UnhandledError, V as ValueResult, q as backpressure, r as compose, s as connect, t as fulfillPromise, u as getResult, v as into, w as isCancel, x as isError, y as isHandled, z as isUnhandled, F as isValue, G as markHandled, K as noop, L as pipe, M as propagateResult, Q as reject, W as rejecter, X as resolve, Z as resolver, _ as throttle } from './types-C3WWddF2.js';
+export { E as Each, a as EachResult, N as NextMethod, U as UntilMethod, e as each, f as forEach, i as isObserved, n as next, r as recalcWhen } from './sinks-CoXxbJrs.js';
 
 /**
  * Invoke a no-argument function as a microtask, using queueMicrotask or Promise.resolve().then()

package/dist/mod.mjs

@@ -1,7 +1,7 @@
-import { d as defer, i as isFunction } from './utils-BgqyDPjA.mjs';
-import { r as resolver, a as rejecter, b as resolve, I as IsStream, c as backpressure, m as must, s as start, g as getJob, n as noop, d as root, i as isCancel, e as isUnhandled, f as markHandled, h as isError, t as throttle, j as connect, k as fulfillPromise, l as restarting, o as currentCell, p as isValue } from './jobutils-O9tOTNKC.mjs';
-export { A as CancelError, C as CancelResult, E as ErrorResult, V as ValueResult, J as abortSignal, D as compose, y as getResult, F as into, x as isHandled, G as isJobActive, u as makeJob, q as nativePromise, v as newRoot, B as pipe, z as propagateResult, w as reject, K as task, H as timeout } from './jobutils-O9tOTNKC.mjs';
-import { c as callOrWait, m as mustBeSourceOrSignal } from './call-or-wait-CvOF0pao.mjs';
+import { d as defer, i as isFunction } from './utils-CwhAPj4M.mjs';
+import { r as resolve, a as resolver, b as rejecter, I as IsStream, c as backpressure, m as must, s as start, g as getJob, n as noop, d as root, i as isCancel, e as isUnhandled, f as markHandled, h as isError, t as throttle, j as connect, k as fulfillPromise, l as currentCell, o as restarting, p as isValue } from './jobutils-DYe7dvZO.mjs';
+export { C as CancelError, q as CancelResult, E as ErrorResult, V as ValueResult, u as abortSignal, v as compose, w as getResult, x as into, y as isHandled, z as isJobActive, A as makeJob, B as nativePromise, D as newRoot, F as pipe, G as propagateResult, H as reject, J as task, K as timeout } from './jobutils-DYe7dvZO.mjs';
+import { c as callOrWait, m as mustBeSourceOrSignal } from './call-or-wait-BTeEcToS.mjs';
 
 function* to(p) {
   return yield (res) => Promise.resolve(p).then(resolver(res), rejecter(res));
@@ -276,10 +276,10 @@ function forEach(src, sink, inlet) {
   return (src2) => forEach(src2, sink, inlet);
 }
 function recalcWhen(fnOrKey, fn) {
-  currentCell?.recalcWhen(fnOrKey, fn);
+  currentCell && currentCell.recalcWhen(fnOrKey, fn);
 }
 function isObserved() {
-  return currentCell?.isObserved();
+  return currentCell ? currentCell.isObserved() : void 0;
 }
 
 function concat(sources) {

package/dist/shared.d.ts

@@ -1,33 +1,84 @@
-import { Y as Yielding } from './types-pElgImr7.js';
+import { Y as Yielding } from './types-C3WWddF2.js';
 
 /** @inline */
 type CallSite = TemplateStringsArray;
 
 /**
  * Tools for sharing tasks, values, services, etc., especially across job
- * boundaries.
+ * boundaries, but also across reactive expression lifetimes (similar to React
+ * hooks).
  *
  * @module uneventful/shared
  * @disableGroups
  */
 
 /**
- * Wrap a factory function to create a singleton service accessor
+ * A function, or class constructor producing a value that will be cached by
+ * `$()` and `service()` accessors for the life of the root job, or until
+ * overridden or unset via `$cache`.
+ *
+ * The function or constructor will be run in the then-current root job, and its
+ * value cached.  If the function is a native generator function, it is
+ * automatically wrapped with {@link fork}(), so that its job will not end when
+ * the generator ends, and the result can be waited on by multiple callers.  (If
+ * your factory is *not* a native generator function but still returns a
+ * generator to produce an async result, you should wrap that generator with
+ * {@link fork} before returning it.)
+ *
+ * Note: if an original or replacement factory (set via
+ * {@link $cache.replace}()) directly or indirectly requests its own value (even
+ * via a {@link service}() accessor), an error is thrown to prevent infinite
+ * recursion.  An error is also thrown if a reactive value is directly or
+ * indirectly accessed during the factory's execution, to prevent your cached
+ * singleton from unintentionally retaining a stale value.  (Rules and
+ * {@link uneventful/signals.fx fx()} are unaffected, as they will update their
+ * state as needed.)
+ *
+ * @category Types and Interfaces
+ */
+type SingletonFactory<T> = (() => T) | (new () => T);
+/**
+ * A function, or class constructor producing a value that will be cached by
+ * ```$``()``` as a permanent-per-signal constant at a given call site.
  *
- * The returned function, when called, will run the factory in a new job and
- * cache the result.  The job the factory ran in will end when the {@link root}
- * job does, after which the cached result will be cleared.
+ * The function or constructor will be run *without* an active job, and its
+ * value cached.  While it runs, any attempt to directly access a reactive value
+ * or expression will be blocked by a thrown error, to prevent your cached
+ * result from capturing a stale value.
  *
- * @param factory A function returning whatever result you want to share: a
- * value, a function, an object, etc.  It will be called at most once per root
- * job lifetime, in a job that is an immediate child of the root job.
+ * Note that unlike {@link SingletonFactory}, a ConstantFactory *cannot* use job
+ * APIs, rules, or fx(), nor is there any special handling for generator
+ * functions.  None of these things make any sense for a lazy constant, as there
+ * is no way to clean up after them: they simply exist for the life of the
+ * signal and so should be relatively stateless.
  *
- * (Note: if your factory is a native generator function, it is automatically
- * wrapped with {@link fork}() so that its job will not end when the generator
- * ends, and the result can be waited on by multiple callers.  If your factory
- * is *not* a native generator function but still returns a generator to produce
- * an async result, you should wrap that generator with {@link fork} before
- * returning it.)
+ * @category Types and Interfaces
+ */
+type ConstantFactory<T> = (() => T) | (new () => T);
+/**
+ * Wrap a factory function to create a "service" accessor (a shorthand function
+ * for getting {@link $ `$(factory)`}).
+ *
+ * This function returns an equivalent to `() => $(factory)` or `$.bind(null,
+ * factory)`, but optimized for raw access speed (close to a module export
+ * binding) at the expense of slightly-higher memory use.
+ *
+ * Every distinct `factory` passed to `service()` consumes some bookkeeping
+ * space that will *not* be released until the application exits.  (Or the next
+ * call to {@link newRoot}() happens, but that's normally only used for
+ * testing!)
+ *
+ * So this is for stable/static accessors: module-level constants, classes,
+ * etc., not factories that are created on the fly from closures in functions
+ * that get called a lot. (For those use cases, just substitute `() =>
+ * $(factory)` or `$.bind(null, factory)`.)
+ *
+ * @param factory The {@link SingletonFactory} function or class whose
+ * shared/cached value the accessor returns.  See {@link SingletonFactory} for
+ * important details on how the factory is run and the restrictions on what it
+ * can do.  Note that since the accessor is just shorthand for `$()`, its state
+ * and implementation can be created, deleted, replaced, etc. using the
+ * {@link $cache} APIs.
  *
  * @remarks Note that if you want your code to be testable with {@link newRoot},
  * you should avoid storing the *result* of calling the service accessor
@@ -41,9 +92,9 @@ type CallSite = TemplateStringsArray;
  * such a thing should not be necessary in your production builds, however,
  * since at runtime you will normally only ever have one root job.)
  *
- * @category Resources
+ * @category Singletons & Lazy Constants
  */
-declare function service<T>(factory: () => T): () => T;
+declare function service<T>(factory: SingletonFactory<T>): () => T;
 /**
  * Proxy an object so it "expires" (becomes inaccessible) with the calling job.
  *
@@ -65,31 +116,30 @@ declare function fork<T, F extends (...args: any[]) => Yielding<T>>(genFunc: F,
 declare function fork<T, F extends (...args: any[]) => Yielding<T>, D extends {
     value?: F;
 }>(clsOrProto: any, name: string | symbol, desc: D): D;
-/** @inline */
-type Factory<T> = (() => T) | (new () => T);
 /**
  * Return a singleton instance for the given factory
  *
- * Every call to `$()` with a given factory will return the same result. (Unless
- * overridden using {@link $cache.set}, {@link $cache.unset} or
- * {@link $cache.replace}.)  On first use, the factory is called (or
- * constructed, if it's a class) and the result (if not an error) is cached for
- * future calls.
+ * Every call to `$()` with a given factory will return the same result. (Until
+ * a new root job is started, or the result is overridden using
+ * {@link $cache.set}, {@link $cache.unset} or {@link $cache.replace}.)  On
+ * first use, the factory is called (or constructed, if it's a class) and the
+ * result (if not an error) is cached for future calls.
  *
+ * @param factory The {@link SingletonFactory} function or class whose
+ * shared/cached value you want to get.  (See {@link SingletonFactory} for
+ * important details on how the factory is run and the restrictions on what it
+ * can do.)
  */
-declare function $<T>(factory: Factory<T>): T;
+declare function $<T>(factory: SingletonFactory<T>): T;
 /**
  * Create a per-signal lazy constant, via ```$``()```
  *
  * When you call ```$``(factory)``` inside a given signal function for the first
- * time, `factory()` will be called (or constructed, if it's a class) and
- * returned, and the result cached for future calls *at the same location in
- * that specific signal*.  An error results if called outside a signal function.
- *
- * The primary difference between this and the singleton operator (plain `$()`),
- * is that lazy constants are singletons *per call-site*, *per signal*.  A
- * specific invocation of ```$``()``` in a specific signal will always return
- * the same value.
+ * time, the {@link ConstantFactory} will be called (or constructed, if it's a
+ * class) and the returned result will be cached for ALL future calls *at the
+ * same code location in that specific signal*.  An error results if called
+ * outside a signal function.  See the {@link ConstantFactory} docs for more
+ * details on how the factory is called, and the restrictions on what it can do.
  *
  * @remarks
  * Lazy constants are somewhat similar in concept to a React `useMemo()`, but
@@ -107,8 +157,12 @@ declare function $<T>(factory: Factory<T>): T;
  * call a wrapping function more than once in a signal, and expect to get
  * different results: a lazy constant is a per-signal *constant*, not a React
  * hook!)
+ *
+ * @experimental
  */
-declare function $(callSite: CallSite): <T>(factory: Factory<T>) => T;
+declare function $(callSite: CallSite): <T>(factory: ConstantFactory<T>) => T;
+/** @hidden - this makes this the generic for bind() */
+declare function $<T>(factory: SingletonFactory<T>): T;
 /**
  * Utilities for manipulating the singleton cache (e.g. for testing)
  *
@@ -122,26 +176,45 @@ declare const $cache: {
      * testing)
      *
      * All subsequent calls to `$(factory)` will return the given result, until
-     * manually set again, or reset via {@link $cache.unset}.
+     * manually set again, reset via {@link $cache.unset}, or cleared by
+     * {@link newRoot}().
      */
-    set<T>(factory: Factory<T>, result: T): void;
+    set<T>(factory: SingletonFactory<T>, result: T): void;
     /**
      * Unset the cached singleton for a given factory, such that the next call
      * to `$(factory)` will create a new instance.
      */
-    unset<T>(factory: Factory<T>): void;
+    unset<T>(factory: SingletonFactory<T>): void;
     /**
-     * Replace the implementation for a given factory, such that future calls to
-     * `$(factory)` will call or construct the replacement instead.
+     * Replace the implementation for a given factory (the "original"), such
+     * that future calls to `$(original)` will call or construct the replacement
+     * instead.
+     *
+     * Replacements are run under the same conditions as any other
+     * {@link SingletonFactory}: root job, no reactive reads, and generator
+     * function auto-{@link fork}()ing.  They don't have to be *implemented* the
+     * same way, though: the original could be a class, and the replacement a
+     * function, or vice versa: they just need to produce something that
+     * satisfies the type expected by the original's consumers.
      *
-     * If the replacement is omitted, null, or undefined, future calls will
-     * invoke the original factory again.
+     * The replacement can even be a generic wrapper, as the current creation
+     * target (i.e. the "original" factory) can be obtained via
+     * {@link $cache.creating}(). If the replacement is omitted, null, or
+     * undefined, future calls will invoke the original factory again.
      *
      * (Note: in all cases the replacement will not take effect if there's
-     * already a cached singleton, so you may wish to call
+     * already a cached singleton, so you may wish to also call
      * {@link $cache.unset}() to ensure a future call is actually executed.)
      */
-    replace<T>(factory: Factory<T>, replacement?: Factory<T>): void;
+    replace<T>(original: SingletonFactory<T>, replacement?: SingletonFactory<T>): void;
+    /**
+     * The original factory whose singleton `$()` is currently creating, if any.
+     * (Only useful for generic {@link replace} factories.)
+     *
+     * Note: The return value is the original factory argument that was passed
+     * to `$()`, not its replacement.
+     */
+    creating(): SingletonFactory<unknown>;
 };
 
-export { $, $cache, expiring, fork, service };
+export { $, $cache, type ConstantFactory, type SingletonFactory, expiring, fork, service };

package/dist/shared.mjs

@@ -1,25 +1,20 @@
-import { p as perSignal } from './hooks-BnMYHRlM.mjs';
-import { d as root, m as must, s as start, n as noop } from './jobutils-O9tOTNKC.mjs';
-import { a as isGeneratorFunction, b as decorateMethod, i as isFunction, c as apply, s as setMap, e as isClass } from './utils-BgqyDPjA.mjs';
+import { L as singletons, m as must, s as start, n as noop, M as activeServices, N as pushCtx, d as root, O as popCtx } from './jobutils-DYe7dvZO.mjs';
+import { p as perSignal } from './hooks-Bx4Lqd9S.mjs';
+import { i as isFunction, s as setMap, a as decorateMethod, b as apply, c as isGeneratorFunction, e as isClass } from './utils-CwhAPj4M.mjs';
 
 function service(factory) {
-  let known = false, value = void 0;
-  if (isGeneratorFunction(factory))
-    factory = fork(factory);
-  return () => {
-    if (known)
-      return value;
-    root.start(() => {
-      value = factory();
-      known = true;
-      must(() => {
-        value = void 0;
-        known = false;
-      });
-    });
-    return value;
-  };
+  if (services.has(factory))
+    return services.get(factory).get;
+  const c = {
+    valid: false,
+    value: noop,
+    // prebuild shape for object/function pointer
+    get: () => c.valid ? c.value : (c.value = $(factory), c.valid = true, c.value)
+  }, r = new WeakRef(c);
+  activeServices.add(r);
+  return setMap(services, factory, setMap(services, c.get, c)).get;
 }
+const services = /* @__PURE__ */ new WeakMap();
 function expiring(obj) {
   const p = Proxy.revocable(obj, {});
   must(p.revoke);
@@ -49,17 +44,32 @@ function fork(genOrFunc, ...args) {
   }
 }
 const forks = /* @__PURE__ */ new WeakMap();
-const constants = /* @__PURE__ */ new WeakMap(), factories = /* @__PURE__ */ new WeakMap();
+const factories = /* @__PURE__ */ new WeakMap();
 function $(key) {
   if (isFunction(key)) {
-    return constants.has(key) ? constants.get(key) : setMap(
-      constants,
+    return singletons.has(key) ? singletons.get(key) : setMap(
+      singletons,
       key,
-      callOrConstruct(factories.has(key) ? factories.get(key) : key)
+      createSingleton(key, factories.has(key) ? factories.get(key) : key)
     );
   }
   return perSignal(callOrConstruct, key, "$``() ");
 }
+const stack = [];
+function createSingleton(key, f) {
+  if (stack.indexOf(key) > -1)
+    throw new Error("Singleton factory depends on itself");
+  if (isGeneratorFunction(f))
+    f = fork(f);
+  stack.unshift(key);
+  pushCtx(root, false);
+  try {
+    return callOrConstruct(f);
+  } finally {
+    stack.shift();
+    popCtx();
+  }
+}
 function callOrConstruct(f) {
   return isClass(f) ? new f() : f();
 }
@@ -69,31 +79,62 @@ const $cache = {
    * testing)
    *
    * All subsequent calls to `$(factory)` will return the given result, until
-   * manually set again, or reset via {@link $cache.unset}.
+   * manually set again, reset via {@link $cache.unset}, or cleared by
+   * {@link newRoot}().
    */
   set(factory, result) {
-    constants.set(factory, result);
+    singletons.set(factory, result);
+    const a = services.get(factory);
+    if (a) {
+      a.valid = true;
+      a.value = result;
+    }
   },
   /**
    * Unset the cached singleton for a given factory, such that the next call
    * to `$(factory)` will create a new instance.
    */
   unset(factory) {
-    constants.delete(factory);
+    singletons.delete(factory);
+    const a = services.get(factory);
+    if (a) {
+      a.valid = false;
+      a.value = void 0;
+    }
   },
   /**
-   * Replace the implementation for a given factory, such that future calls to
-   * `$(factory)` will call or construct the replacement instead.
+   * Replace the implementation for a given factory (the "original"), such
+   * that future calls to `$(original)` will call or construct the replacement
+   * instead.
+   *
+   * Replacements are run under the same conditions as any other
+   * {@link SingletonFactory}: root job, no reactive reads, and generator
+   * function auto-{@link fork}()ing.  They don't have to be *implemented* the
+   * same way, though: the original could be a class, and the replacement a
+   * function, or vice versa: they just need to produce something that
+   * satisfies the type expected by the original's consumers.
    *
-   * If the replacement is omitted, null, or undefined, future calls will
-   * invoke the original factory again.
+   * The replacement can even be a generic wrapper, as the current creation
+   * target (i.e. the "original" factory) can be obtained via
+   * {@link $cache.creating}(). If the replacement is omitted, null, or
+   * undefined, future calls will invoke the original factory again.
    *
    * (Note: in all cases the replacement will not take effect if there's
-   * already a cached singleton, so you may wish to call
+   * already a cached singleton, so you may wish to also call
    * {@link $cache.unset}() to ensure a future call is actually executed.)
    */
-  replace(factory, replacement) {
-    replacement != null && replacement !== factory ? factories.set(factory, replacement) : factories.delete(factory);
+  replace(original, replacement) {
+    replacement != null && replacement !== original ? factories.set(original, replacement) : factories.delete(original);
+  },
+  /**
+   * The original factory whose singleton `$()` is currently creating, if any.
+   * (Only useful for generic {@link replace} factories.)
+   *
+   * Note: The return value is the original factory argument that was passed
+   * to `$()`, not its replacement.
+   */
+  creating() {
+    return stack[0];
   }
 };
 

package/dist/signals.d.ts

@@ -1,5 +1,5 @@
-import { A as AnyFunction, O as OptionalCleanup, D as DisposeFn, L as SignalSource, Y as Yielding, S as Source, P as PlainFunction, a as Stream } from './types-pElgImr7.js';
-import { U as UntilMethod } from './sinks-B_LfTZgF.js';
+import { A as AnyFunction, O as OptionalCleanup, D as DisposeFn, m as SignalSource, Y as Yielding, S as Source, P as PlainFunction, a as Stream } from './types-C3WWddF2.js';
+import { U as UntilMethod } from './sinks-CoXxbJrs.js';
 
 /**
  * A decorator function that supports both TC39 and "legacy" decorator protocols

package/dist/signals.mjs

@@ -1,8 +1,8 @@
-import { d as root, o as currentCell, g as getJob, m as must, L as currentJob, w as reject, b as resolve } from './jobutils-O9tOTNKC.mjs';
-import { C as Cell, r as ruleQueue, d as defaultQ, c as currentRule, p as perSignal, g as getCell } from './hooks-BnMYHRlM.mjs';
-export { a as CircularDependency, W as WriteConflict } from './hooks-BnMYHRlM.mjs';
-import { d as defer, C as CallableObject, c as apply, s as setMap, b as decorateMethod, i as isFunction, f as isPlainFunction, g as arrayEq } from './utils-BgqyDPjA.mjs';
-import { c as callOrWait } from './call-or-wait-CvOF0pao.mjs';
+import { d as root, l as currentCell, g as getJob, m as must, P as currentJob, H as reject, r as resolve } from './jobutils-DYe7dvZO.mjs';
+import { C as Cell, r as ruleQueue, d as defaultQ, c as currentRule, p as perSignal, g as getCell } from './hooks-Bx4Lqd9S.mjs';
+export { a as CircularDependency, W as WriteConflict } from './hooks-Bx4Lqd9S.mjs';
+import { d as defer, C as CallableObject, b as apply, s as setMap, a as decorateMethod, i as isFunction, f as isPlainFunction, g as arrayEq } from './utils-CwhAPj4M.mjs';
+import { c as callOrWait } from './call-or-wait-BTeEcToS.mjs';
 
 class RF extends CallableObject {
   constructor(q) {
@@ -96,9 +96,12 @@ function fx(f, ...args) {
     let jobs, cell = Cell.mkCached(f);
     return () => {
       if (currentCell) {
-        if (currentCell.isObserved())
+        if (currentCell.isObserved()) {
+          cell.isObserved() || (cell.validThrough = 0);
           cell.getValue();
+        }
       } else {
+        cell.isObserved() || (cell.validThrough = 0);
         if (!sosHas(jobs, getJob())) {
           const job = currentJob;
           jobs = sosAdd(jobs, job);

package/dist/{sinks-B_LfTZgF.d.ts → sinks-CoXxbJrs.d.ts}

@@ -1,4 +1,4 @@
-import { h as Suspend, a as Stream, Y as Yielding, b as Sink, I as Inlet, K as Connection, i as RecalcSource } from './types-pElgImr7.js';
+import { n as Suspend, Y as Yielding, a as Stream, b as Sink, I as Inlet, h as Connection, R as RecalcSource } from './types-C3WWddF2.js';
 
 /**
  * The result type returned from calls to {@link Each}.next()
@@ -204,4 +204,4 @@ declare function recalcWhen<T extends WeakKey>(key: T, factory: (key: T) => Reca
  */
 declare function isObserved(): boolean | undefined;
 
-export { type EachResult as E, type NextMethod as N, type UntilMethod as U, type Each as a, each as e, forEach as f, isObserved as i, next as n, recalcWhen as r };
+export { type Each as E, type NextMethod as N, type UntilMethod as U, type EachResult as a, each as e, forEach as f, isObserved as i, next as n, recalcWhen as r };

package/dist/{types-pElgImr7.d.ts → types-C3WWddF2.d.ts}

@@ -914,4 +914,4 @@ interface Request<T> {
  */
 type RecalcSource = ((cb: () => void) => unknown);
 
-export { type AnyFunction as A, type Backpressure as B, type CleanupFn as C, type DisposeFn as D, ErrorResult as E, backpressure as F, type Throttle as G, type HandledError as H, type Inlet as I, type Job as J, type Connection as K, type SignalSource as L, IsStream as M, type Nothing as N, type OptionalCleanup as O, type PlainFunction as P, connect as Q, type Request as R, type Source as S, type Transformer as T, type UnhandledError as U, ValueResult as V, throttle as W, pipe as X, type Yielding as Y, compose as Z, into as _, type Stream as a, type Sink as b, type StartFn as c, type StartObj as d, type AsyncStart as e, type SyncStart as f, type JobIterator as g, type Suspend as h, type RecalcSource as i, reject as j, resolver as k, rejecter as l, CancelResult as m, noop as n, type JobResult as o, isCancel as p, isValue as q, resolve as r, isError as s, isUnhandled as t, isHandled as u, markHandled as v, getResult as w, fulfillPromise as x, propagateResult as y, CancelError as z };
+export { type AnyFunction as A, type Backpressure as B, type CleanupFn as C, type DisposeFn as D, ErrorResult as E, isValue as F, markHandled as G, type HandledError as H, type Inlet as I, type Job as J, noop as K, pipe as L, propagateResult as M, type Nothing as N, type OptionalCleanup as O, type PlainFunction as P, reject as Q, type RecalcSource as R, type Source as S, type Transformer as T, type UnhandledError as U, ValueResult as V, rejecter as W, resolve as X, type Yielding as Y, resolver as Z, throttle as _, type Stream as a, type Sink as b, type StartFn as c, type StartObj as d, type AsyncStart as e, CancelError as f, CancelResult as g, type Connection as h, IsStream as i, type JobIterator as j, type JobResult as k, type Request as l, type SignalSource as m, type Suspend as n, type SyncStart as o, type Throttle as p, backpressure as q, compose as r, connect as s, fulfillPromise as t, getResult as u, into as v, isCancel as w, isError as x, isHandled as y, isUnhandled as z };

package/dist/{utils-BgqyDPjA.mjs → utils-CwhAPj4M.mjs}

@@ -10,7 +10,7 @@ class _Batch {
     this._flags = 0 /* Unset */;
     this.q = /* @__PURE__ */ new Set();
     this._run = () => {
-      this._flags &= ~2 /* Scheduled */;
+      this._flags &= -3 /* Scheduled */;
       this.flush();
     };
     /** Run all pending items */
@@ -24,7 +24,7 @@ class _Batch {
       try {
         this.reap(queue);
       } finally {
-        this._flags &= ~1 /* Running */;
+        this._flags &= -2 /* Running */;
         !queue.size || this._flags & 2 /* Scheduled */ || this._sched();
       }
     };
@@ -123,4 +123,4 @@ function isGeneratorFunction(fn) {
   return isFunction(fn) && fn.prototype instanceof GeneratorBase;
 }
 
-export { CallableObject as C, GeneratorBase as G, isGeneratorFunction as a, decorateMethod as b, apply as c, defer as d, isClass as e, isPlainFunction as f, arrayEq as g, batch as h, isFunction as i, isArray as j, isPlainObject as k, call as l, setMap as s };
+export { CallableObject as C, GeneratorBase as G, decorateMethod as a, apply as b, isGeneratorFunction as c, defer as d, isClass as e, isPlainFunction as f, arrayEq as g, batch as h, isFunction as i, call as j, isArray as k, isPlainObject as l, setMap as s };

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import { A as AnyFunction } from './types-pElgImr7.js';
+import { A as AnyFunction } from './types-C3WWddF2.js';
 
 /**
  * A generic batch processing queue, implemented as a set.  (So items are

package/dist/utils.mjs

@@ -1 +1 @@
-export { C as CallableObject, G as GeneratorBase, c as apply, g as arrayEq, h as batch, l as call, b as decorateMethod, j as isArray, e as isClass, i as isFunction, a as isGeneratorFunction, f as isPlainFunction, k as isPlainObject, s as setMap } from './utils-BgqyDPjA.mjs';
+export { C as CallableObject, G as GeneratorBase, b as apply, g as arrayEq, h as batch, j as call, a as decorateMethod, k as isArray, e as isClass, i as isFunction, c as isGeneratorFunction, f as isPlainFunction, l as isPlainObject, s as setMap } from './utils-CwhAPj4M.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "uneventful",
-    "version": "0.0.13",
+    "version": "0.0.15",
     "description": "Declarative, event-driven reactivity: signals, streams, structured concurrency, and easy resource cleanup",
     "keywords": [
         "signals",
@@ -84,7 +84,7 @@
         "chai-as-promised": "^7.1.1",
         "cross-env": "^7.0.3",
         "markdown-it-footnote": "^4.0.0",
-        "mocha": "^10.2.0",
+        "mocha": "^10.8.2",
         "monkey-around": "^3",
         "pkgroll": "^2.1.1",
         "sinon": "^17.0.1",
@@ -92,7 +92,7 @@
         "ts-expect": "^1.3.0",
         "ts-node": "^10.9.1",
         "tsx": "^4.6.1",
-        "typedoc": "pjeby/typedoc#no-merged-comments",
+        "typedoc": "^0.28.17",
         "typescript": "^5.9.3"
     }
 }