uneventful 0.0.12 → 0.0.13

package/dist/{jobutils-Dvu-e99o.mjs → jobutils-O9tOTNKC.mjs}

@@ -1,4 +1,4 @@
-import { e as batch, d as defer, i as isFunction, G as GeneratorBase, c as apply } from './utils-cyEhnyp7.mjs';
+import { h as batch, d as defer, i as isFunction, G as GeneratorBase, c as apply } from './utils-BgqyDPjA.mjs';
 
 function resolve(request, val) {
   request("next", val);
@@ -186,7 +186,7 @@ function getJob() {
 }
 function recalcJob(job) {
   return (cb) => {
-    currentJob.must(job.release(cb));
+    getJob().must(job.release(cb));
   };
 }
 function runChain(res, cbs) {
@@ -195,14 +195,14 @@ function runChain(res, cbs) {
     try {
       cb(res);
     } catch (e) {
-      _detached.asyncThrow(e);
+      root.asyncThrow(e);
     }
   cbs && recycle(cbs);
   return void 0;
 }
 var inProcess = /* @__PURE__ */ new Set();
 class _Job {
-  constructor() {
+  constructor(parent, stop) {
     this.end = () => {
       const res = this._done ||= CancelResult, cbs = this._cbs;
       if (!cbs && !isUnhandled(res))
@@ -212,7 +212,7 @@ class _Job {
       if (!ct)
         inProcess.add(null);
       if (cbs && cbs.u)
-        cbs.u = runChain(res, cbs.u);
+        cbs.u = (runChain(res, cbs.u), void 0);
       inProcess.add(this);
       if (ct) {
         popCtx();
@@ -221,7 +221,7 @@ class _Job {
       inProcess.delete(null);
       for (const item of inProcess) {
         if (item._cbs)
-          item._cbs = runChain(item._done, item._cbs);
+          item._cbs = (runChain(item._done, item._cbs), void 0);
         inProcess.delete(item);
         if (isUnhandled(item._done))
           item.throw(markHandled(item._done));
@@ -231,15 +231,10 @@ class _Job {
     this._done = void 0;
     // Chain whose .u stores a second chain for `release()` callbacks
     this._cbs = void 0;
-  }
-  /** @internal */
-  static create(parent, stop) {
-    const job = new _Job();
     if (parent || stop) {
-      job.must((parent ||= getJob()).release(stop || job.end));
-      owners.set(job, parent);
+      this.must((parent ||= getJob()).release(stop || this.end));
+      parent === root || owners.set(this, parent);
     }
-    return job;
   }
   do(cleanup) {
     unshift(this._chain(), cleanup);
@@ -285,14 +280,17 @@ class _Job {
   _end(res) {
     if (this._done)
       throw new Error("Job already ended");
-    if (this !== _detached)
-      this._done = res;
+    this._done = res;
     this.end();
     return this;
   }
   throw(err) {
     if (this._done) {
-      (owners.get(this) || _detached).asyncThrow(err);
+      const parent = owners.get(this) || root;
+      if (parent && parent !== this)
+        parent.asyncThrow(err);
+      else
+        defaultCatch(err);
       return this;
     }
     return this._end(ErrorResult(err));
@@ -319,7 +317,7 @@ class _Job {
   }
   start(fnOrCtx, fn) {
     if (!fnOrCtx)
-      return makeJob(this);
+      return new _Job(this);
     let init, result;
     if (isFunction(fn)) {
       init = fn.bind(fnOrCtx);
@@ -330,7 +328,7 @@ class _Job {
     } else {
       result = fnOrCtx;
     }
-    const job = makeJob(this);
+    const job = new _Job(this);
     try {
       if (init)
         result = job.run(init, job);
@@ -400,8 +398,6 @@ class _Job {
     return this;
   }
   release(cleanup) {
-    if (this === _detached)
-      return noop;
     let cbs = this._chain();
     if (!this._done || cbs.u)
       cbs = cbs.u ||= chain();
@@ -411,7 +407,7 @@ class _Job {
     try {
       (catchers.get(this) || this.throw).call(this, err);
     } catch (e) {
-      if (this === _detached)
+      if (this === root)
         catchers.set(this, defaultCatch);
       else
         catchers.delete(this);
@@ -429,8 +425,6 @@ class _Job {
     return this;
   }
   _chain() {
-    if (this === _detached)
-      this.end();
     if (this._done && isEmpty(this._cbs))
       defer(this.end);
     return this._cbs ||= chain();
@@ -441,26 +435,23 @@ function nativePromise(job) {
   if (!promises.has(job)) {
     promises.set(job, new Promise((res, rej) => {
       const toPromise = fulfillPromise.bind(null, res, rej);
-      if (job.result())
-        toPromise(job.result());
+      const result = job.result();
+      if (result)
+        toPromise(result);
       else
         job.do(toPromise);
     }));
   }
   return promises.get(job);
 }
-const makeJob = _Job.create;
-const _detached = makeJob();
-const detached = _detached;
-_detached.end = () => {
-  throw new Error("Can't do that with the detached job");
-};
-_detached.asyncCatch(defaultCatch);
+function makeJob(parent, stop) {
+  return new _Job(parent, stop);
+}
 let root;
 newRoot();
 function newRoot() {
   root?.end();
-  const job = root = makeJob().asyncCatch((e) => _detached.asyncThrow(e));
+  const job = root = new _Job().asyncCatch(defaultCatch);
   job.release(() => root === job && (root = null));
   return root;
 }
@@ -527,6 +518,95 @@ function runGen(g, job) {
   }
 }
 
+function backpressure(inlet = defaultInlet) {
+  const job = getJob();
+  return (cb) => {
+    if (!job.result() && inlet.isOpen()) {
+      if (cb)
+        inlet.onReady(cb, job);
+      return inlet.isReady();
+    }
+    return false;
+  };
+}
+const IsStream = "uneventful/is-stream";
+function connect(src, sink, inlet) {
+  return getJob().connect(src, sink, inlet);
+}
+function throttle(job = currentJob) {
+  return new _Throttle(job);
+}
+class _Throttle {
+  /** @internal */
+  constructor(_job) {
+    this._job = _job;
+    /** @internal */
+    this._callbacks = void 0;
+    this._isReady = true;
+    this._isPulling = false;
+  }
+  isOpen() {
+    return !this._job?.result();
+  }
+  /** Is the connection ready to receive data? */
+  isReady() {
+    return this.isOpen() && this._isReady;
+  }
+  onReady(cb, job) {
+    if (!this.isOpen())
+      return this;
+    const _callbacks = this._callbacks ||= /* @__PURE__ */ new Map();
+    const unlink = job.release(() => _callbacks.delete(cb));
+    if (this.isReady() && this && !_callbacks.size) {
+      pulls.add(this);
+    }
+    _callbacks.set(cb, unlink);
+    return this;
+  }
+  pause() {
+    this._isReady = false;
+    return this;
+  }
+  doPull() {
+    if (this._isPulling)
+      return;
+    const { _callbacks } = this;
+    if (!_callbacks?.size)
+      return;
+    this._isPulling = true;
+    try {
+      for (let [cb, unlink] of _callbacks) {
+        if (!this.isReady())
+          break;
+        unlink();
+        _callbacks.delete(cb);
+        cb();
+      }
+    } finally {
+      this._isPulling = false;
+    }
+  }
+  resume() {
+    if (this.isOpen()) {
+      this._isReady = true;
+      this.doPull();
+    }
+  }
+}
+const defaultInlet = throttle();
+function pipe() {
+  var v = arguments[0];
+  for (var i = 1; i < arguments.length; i++)
+    v = arguments[i](v);
+  return v;
+}
+function compose(...fns) {
+  return (val) => pipe(val, ...fns);
+}
+function into(...args) {
+  return (src) => src(...args);
+}
+
 function must(cleanup) {
   getJob().must(cleanup);
 }
@@ -534,7 +614,7 @@ function start(init, fn) {
   return getJob().start(init, fn);
 }
 function isJobActive() {
-  return !!currentJob;
+  return !!(currentJob || currentCell?.isObserved());
 }
 const timers = /* @__PURE__ */ new WeakMap();
 function timeout(ms = 0, job = getJob()) {
@@ -573,7 +653,7 @@ function abortSignal(job = getJob()) {
   return signal;
 }
 function restarting(task2) {
-  const outer = getJob(), inner = makeJob(outer), { end } = inner;
+  const outer = getJob(), inner = outer.start(), { end } = inner;
   task2 ||= (f) => {
     inner.must(f());
   };
@@ -599,4 +679,4 @@ function task(fn, _ctx, desc) {
   };
 }
 
-export { timeout as A, abortSignal as B, CancelResult as C, task as D, ErrorResult as E, pushCtx as F, popCtx as G, currentJob as H, pulls as I, ValueResult as V, rejecter as a, resolve as b, root as c, isUnhandled as d, markHandled as e, isError as f, getJob as g, fulfillPromise as h, isCancel as i, restarting as j, currentCell as k, isValue as l, must as m, noop as n, reject as o, isHandled as p, getResult as q, resolver as r, start as s, propagateResult as t, CancelError as u, nativePromise as v, makeJob as w, detached as x, newRoot as y, isJobActive as z };
+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 };

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-N2ua11te.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-N2ua11te.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-5TuxCRtX.js';
+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';
 
 /**
  * Invoke a no-argument function as a microtask, using queueMicrotask or Promise.resolve().then()
@@ -35,61 +35,23 @@ declare function getJob<T = unknown>(): Job<T>;
  */
 declare function nativePromise<T>(job: Job<T>): Promise<T>;
 /**
- * Return a new {@link Job}.  If *either* a parent parameter or stop function
- * are given, the new job is linked to the parent.
+ * This function is deprecated.  Please move to using `.start()` instead, as
+ * shown:
  *
- * @remarks You should generally use `start()`, `parent.start()` or
- * `root.start()` instead of this, unless you're creating a special kind of job
- * that needs a custom stop function.
+ * | Old | New |
+ * | --- | --- |
+ * | `makeJob()`<br>`makeJob(null/undefined)` | `root.start()` |
+ * | `makeJob(parent)` | `parent.start()` |
  *
- * @param parent The parent job to which the new job should be attached.
- * Defaults to the currently-active job if none given (assuming a stop parameter
- * is provided).
- *
- * @param stop The function to call to destroy the nested job.  Defaults to the
- * {@link Job.end} method of the new job if none is given (assuming a parent
- * parameter is provided).
- *
- * @returns A new job.  The job is a child job if any arguments are given, or
- * a detached (parentless) job otherwise.
- *
- * @category Jobs
- * @function
- */
-declare const makeJob: <T>(parent?: Job, stop?: CleanupFn) => Job<T>;
-/**
- * @deprecated Use {@link root} instead.  (Including uses of
- * `.asyncCatch()` to set the default async error handling policy.)
- *
- * ---
- * A special {@link Job} with no parents, that can be used to create standalone
- * jobs.  detached.start() returns a new detached job, detached.run() can be
- * used to run code that expects to create a child job, and detached.bind() can
- * wrap a function to work without a parent job.
- *
- * (Note that such `detached` child jobs *must* exit themselves or be stopped
- * explicitly from outside, or else they may "run" forever, never running their
- * cleanup callbacks.  Unlike other jobs, they don't end when their parent does
- * because the `detached` job never "ends".)
- *
- * The detached job has a few special features and limitations:
- *
- * - It can't be ended, thrown, return()ed, etc. -- you'll get an error
- *
- * - It can't have any cleanup functions added: no do, must, onError, etc., and
- *   thus also can't have any native promise, abort signal, etc. used.  You can
- *   call its release() method, but nothing will actually be registered and the
- *   returned callback is a no-op.
- *
- * - Unhandled errors from jobs without parents (and errors from *any* job's
- *   cleanup functions) are sent to the detached job for handling.  This means
- *   whatever you set as the detached job's .{@link Job.asyncCatch asyncCatch}()
- *   handler will receive them.  (Its default is Promise.reject, causing an
- *   unhandled promise rejection.)
+ * If for some reason you are currently using a custom `stop` function and need
+ * to keep it for backward compatibility, you can use `.restart()` on the new
+ * job to remove the default stop function from its parent, then replace it with
+ * `.must(parent.release(stop))`.
  *
+ * @deprecated
  * @category Jobs
  */
-declare const detached: Job<unknown>;
+declare function makeJob<T>(parent?: Job, stop?: CleanupFn): Job<T>;
 /**
  * The "main" job of the program or bundle, which all other jobs should be a
  * child of.  This provides a single point of configuration and cleanup, as one
@@ -713,4 +675,4 @@ declare function task<T, A extends any[], C, D extends {
     value?: (this: C, ...args: A) => StartObj<T>;
 }>(clsOrProto: any, name: string | symbol, desc: D): D;
 
-export { AnyFunction, Backpressure, CleanupFn, DisposeFn, type Emitter, Job, type MockSource, OptionalCleanup, Sink, Source, StartFn, StartObj, Stream, Transformer, Yielding, abortSignal, concat, concatAll, concatMap, defer, detached, emitter, empty, filter, fromAsyncIterable, fromDomEvent, fromIterable, fromPromise, fromSubscribe, fromValue, getJob, interval, isJobActive, lazy, makeJob, map, merge, mergeAll, mergeMap, mockSource, must, nativePromise, never, newRoot, restarting, root, share, skip, skipUntil, skipWhile, slack, sleep, start, switchAll, switchMap, take, takeUntil, takeWhile, task, timeout, to };
+export { AnyFunction, Backpressure, CleanupFn, DisposeFn, type Emitter, Job, type MockSource, OptionalCleanup, Sink, Source, StartFn, StartObj, Stream, Transformer, Yielding, abortSignal, concat, concatAll, concatMap, defer, emitter, empty, filter, fromAsyncIterable, fromDomEvent, fromIterable, fromPromise, fromSubscribe, fromValue, getJob, interval, isJobActive, lazy, makeJob, map, merge, mergeAll, mergeMap, mockSource, must, nativePromise, never, newRoot, restarting, root, share, skip, skipUntil, skipWhile, slack, sleep, start, switchAll, switchMap, take, takeUntil, takeWhile, task, timeout, to };

package/dist/mod.mjs

@@ -1,8 +1,7 @@
-import { d as defer, i as isFunction } from './utils-cyEhnyp7.mjs';
-import { r as resolver, a as rejecter, b as resolve, m as must, s as start, g as getJob, n as noop, c as root, i as isCancel, d as isUnhandled, e as markHandled, f as isError, h as fulfillPromise, j as restarting, k as currentCell, l as isValue } from './jobutils-Dvu-e99o.mjs';
-export { u as CancelError, C as CancelResult, E as ErrorResult, V as ValueResult, B as abortSignal, x as detached, q as getResult, p as isHandled, z as isJobActive, w as makeJob, v as nativePromise, y as newRoot, t as propagateResult, o as reject, D as task, A as timeout } from './jobutils-Dvu-e99o.mjs';
-import { I as IsStream, b as backpressure, t as throttle, c as connect, a as callOrWait, m as mustBeSourceOrSignal } from './call-or-wait-EzXJX5Dq.mjs';
-export { d as compose, i as into, p as pipe } from './call-or-wait-EzXJX5Dq.mjs';
+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';
 
 function* to(p) {
   return yield (res) => Promise.resolve(p).then(resolver(res), rejecter(res));
@@ -138,7 +137,7 @@ function mockSource() {
   };
   emit.end = () => outlet?.return();
   emit.throw = (e) => outlet?.throw(e);
-  emit.ready = (cb) => ready(cb);
+  emit.ready = (cb) => ready?.(cb) || false;
   return emit;
 }
 function never() {
@@ -250,10 +249,11 @@ function* each(src) {
     if (waiter)
       throw new Error("Multiple `yield next` in loop");
     yielded = true;
-    if (conn.result()) {
+    const res = conn.result();
+    if (res) {
       result.value = void 0;
       result.done = true;
-      fulfillPromise(resolver(r), rejecter(r), conn.result());
+      fulfillPromise(resolver(r), rejecter(r), res);
     } else {
       waiter = r;
       t.resume();

package/dist/shared.d.ts

@@ -1,4 +1,7 @@
-import { Y as Yielding } from './types-N2ua11te.js';
+import { Y as Yielding } from './types-pElgImr7.js';
+
+/** @inline */
+type CallSite = TemplateStringsArray;
 
 /**
  * Tools for sharing tasks, values, services, etc., especially across job
@@ -37,6 +40,8 @@ import { Y as Yielding } from './types-N2ua11te.js';
  * saved service value throw a TypeError after the root job ends.  (Note that
  * 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
  */
 declare function service<T>(factory: () => T): () => T;
 /**
@@ -46,56 +51,10 @@ declare function service<T>(factory: () => T): () => T;
  * than to check its `typeof`) will result in a TypeError.
  *
  * Note: your runtime environment must support `Proxy.revocable()`.
+ *
+ * @category Resources
  */
 declare function expiring<T extends object>(obj: T): T;
-/**
- * Wrap a generator, generator function, or generator method to run in parallel
- * and have a result that can be waited on in parallel as well.
- *
- * Normally, when you `yield *` to a generator in a job function, you're
- * *pausing* the current function until that generator is finished.  And
- * normally, this is what you *want*, because you're not trying to do things in
- * parallel.  But if you *do* want to do things in parallel, you need `fork`.
- *
- * Generators also can't normally be *waited on* in parallel either: if multiple
- * jobs try to wait on an unfinished generator, the most likely result is an
- * error or data corruption. (Because the extra `yield *` operations will make
- * the generator think it's received data it was waiting for, causing all kinds
- * of havoc.)
- *
- * So if you want a generator to either *run* in parallel or be *waited on* in
- * parallel (or both), you need to `fork` it: either on the consuming side by
- * wrapping a generator with `fork()`, or on the producing side by wrapping a
- * generator function (or decorating a generator method).
- *
- * When called with a generator, `fork` returns a wrapped generator; when called
- * with a function, it returns a wrapped version of the function that will fork
- * its results.  And when used as a decorator (`@fork`, compatible with both
- * TC39 and legacy decorator protocols), it wraps a method to fork its result as
- * well.
- *
- * It is safe to call `fork()` more than once on the same generator, or to
- * `fork()` an already-forked generator: the result will always be the same as
- * the original fork.
- *
- * @remarks Note that while you can *also* make a generator run or be waitable
- * in parallel using e.g. `start()`, the critical difference is in when resource
- * cleanup happens. If you `start()` the generator (or wrap the generator
- * function with `task`), its resources will be cleaned up when the generator
- * function exits.
- *
- * With `yield*`, however (with or without `fork`), the resources are cleaned up
- * when the original *calling* job ends.  And this is what you want when the
- * generator's return value is some kind of resource using other active
- * resources (such as event listeners rules, etc.) that need to *remain* active
- * for the caller.
- *
- * (If you're familiar with the Effection framework, you may recognize this as
- * the difference between "actions" and "resources": in Uneventful we use
- * `start()` or `task()` for generators that return the result of an action, and
- * `fork` for generators that return a resource that will be owned by the
- * calling job.)
- */
 declare function fork<T>(gen: Yielding<T>): Yielding<T>;
 declare function fork<T, F extends (...args: any[]) => Yielding<T>>(genFunc: F): F;
 /** @hidden TC39 decorator */
@@ -106,5 +65,83 @@ 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.
+ *
+ */
+declare function $<T>(factory: Factory<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.
+ *
+ * @remarks
+ * Lazy constants are somewhat similar in concept to a React `useMemo()`, but
+ * also *very* different. React requires hooks to always be invoked in the same
+ * order to match them up with their targets, but lazy constants do not need
+ * this: they're tied to the line of code where they're called, and you can
+ * branch, loop, skip, or call them out of order with no consequence.  (They'll
+ * just always return the same value each time if running in the same signal -
+ * even in a loop or called in another function with different arguments, and
+ * they don't support dependencies because you can use signals instead.)
+ *
+ * (Also unlike React hooks, they can also be used in nested functions, as long
+ * as those functions are only invoked from within a relevant signal.
+ * Conversely, because they're keyed to a specific code location, you can't just
+ * 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!)
+ */
+declare function $(callSite: CallSite): <T>(factory: Factory<T>) => T;
+/**
+ * Utilities for manipulating the singleton cache (e.g. for testing)
+ *
+ * @category Singletons & Lazy Constants
+ * @namespace
+ * @experimental
+ */
+declare const $cache: {
+    /**
+     * Set the cached singleton instance for a given factory.  (e.g. for
+     * testing)
+     *
+     * All subsequent calls to `$(factory)` will return the given result, until
+     * manually set again, or reset via {@link $cache.unset}.
+     */
+    set<T>(factory: Factory<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;
+    /**
+     * Replace the implementation for a given factory, such that future calls to
+     * `$(factory)` will call or construct the replacement instead.
+     *
+     * 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
+     * {@link $cache.unset}() to ensure a future call is actually executed.)
+     */
+    replace<T>(factory: Factory<T>, replacement?: Factory<T>): void;
+};
 
-export { expiring, fork, service };
+export { $, $cache, expiring, fork, service };

package/dist/shared.mjs

@@ -1,5 +1,6 @@
-import { c as root, m as must, s as start, n as noop } from './jobutils-Dvu-e99o.mjs';
-import { a as isGeneratorFunction, b as decorateMethod, i as isFunction, c as apply, s as setMap } from './utils-cyEhnyp7.mjs';
+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';
 
 function service(factory) {
   let known = false, value = void 0;
@@ -48,5 +49,52 @@ function fork(genOrFunc, ...args) {
   }
 }
 const forks = /* @__PURE__ */ new WeakMap();
+const constants = /* @__PURE__ */ new WeakMap(), factories = /* @__PURE__ */ new WeakMap();
+function $(key) {
+  if (isFunction(key)) {
+    return constants.has(key) ? constants.get(key) : setMap(
+      constants,
+      key,
+      callOrConstruct(factories.has(key) ? factories.get(key) : key)
+    );
+  }
+  return perSignal(callOrConstruct, key, "$``() ");
+}
+function callOrConstruct(f) {
+  return isClass(f) ? new f() : f();
+}
+const $cache = {
+  /**
+   * Set the cached singleton instance for a given factory.  (e.g. for
+   * testing)
+   *
+   * All subsequent calls to `$(factory)` will return the given result, until
+   * manually set again, or reset via {@link $cache.unset}.
+   */
+  set(factory, result) {
+    constants.set(factory, 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);
+  },
+  /**
+   * Replace the implementation for a given factory, such that future calls to
+   * `$(factory)` will call or construct the replacement instead.
+   *
+   * 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
+   * {@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);
+  }
+};
 
-export { expiring, fork, service };
+export { $, $cache, expiring, fork, service };