uneventful 0.0.11 → 0.0.12

package/dist/ext.d.ts

@@ -16,7 +16,7 @@ import { P as PlainFunction } from './types-N2ua11te.js';
  * @module uneventful/ext
  *
  * @experimental
- *
+ * @disableGroups
  * @summary Tools for extending objects with extra state and behavior, without
  * directly modifying them.
  */
@@ -107,16 +107,12 @@ declare namespace Ext {
     /**
      * Get the type of extension that will be returned by the static API.
      *
-     * Defaults to the subclass instance type, but can be overridden by `declare
-     * readonly __type__: OtherType` in a subclass, so long as the
-     * {@link Ext.__new__ `__new__()`} method is also overridden to return that
-     * type.
+     * Defaults to the subclass instance type, but can be changed by overriding
+     * {@link Ext.__new__ `__new__()`} to return a different type.
      */
     type Type<T extends Ext.Class> = InstanceType<T> extends {
-        __type__: infer R;
+        __new__(ob: any): infer R;
     } ? (unknown extends R ? InstanceType<T> : R) : InstanceType<T>;
-    /** The type of weakmap passed to {@link Ext.__new__ `__new__()`} */
-    type Map<Class extends Ext.Class> = WeakMap<Ext.Target<Class>, any>;
     /**
      * The type constraint for static generics in the API; you probably won't use this directly.
      */
@@ -160,28 +156,13 @@ declare abstract class Ext<Target extends WeakKey = WeakKey> {
      */
     readonly of: Target;
     /**
-     * A "virtual" property you can override in subclasses to change the static
-     * interface's return type.  For example, if a subclass does `declare readonly __type__:
-     * Promise<this>`, and overrides `__new__`() to return a promise, then the
-     * static APIs for the subclass (like `.for()`) will return promises instead
-     * of instances. (See the {@link __new__ `__new__`} method for more
-     * details.)
-     *
-     * Note: this property is not actually set by any code, so you can't do anything
-     * other than declare it.  It's just a hack to work around TypeScript's limited
-     * type parameterization for static generics.
-     *
-     * @category Lifecycle Hooks
-     */
-    readonly __type__: unknown;
-    /**
-     * @deprecated Use .for() instead!
+     * @deprecated Use `.for()` or `prototype.__inst__()` instead!
      *
-     * Never directly call the constructor of an Ext subclass except from the
-     * {@link __new__ `__new__()`} method - otherwise you run the risk of having
-     * multiple instances for the same target.  (And it may accept invalid
-     * parameter values if you've redefined the type of the {@link Ext.of `of`}
-     * property in a sub-subclass.)
+     * Never directly call the constructor of an Ext subclass.  If you're
+     * creating an instance in {@link __new__ `__new__()`}, use the
+     * {@link __inst__ `__inst__()`} method instead.  Otherwise,
+     * you should use the .for or .get methods, as they are properly typed
+     * and won't create multiple instances for the same target.
      */
     constructor(of: Target);
     /**
@@ -215,21 +196,15 @@ declare abstract class Ext<Target extends WeakKey = WeakKey> {
      * behavior, e.g. to execute the constructor within a job, or create a
      * promise for an extension instance to be asynchronously initiaized, etc.
      *
-     * If you will be creating something other than an instance of the subclass,
-     * you must also redeclare the type of the {@link __type__ `__type__`}
-     * property.  For example:
+     * For example:
      *
      * ```ts
-     * class AsyncExt extends Ext {
-     *     declare readonly __type__: Job<this>
-     *
+     * class AsyncExt extends Ext<SomeType> {
      *     // simulate slow initialization
      *     *setup() { yield *sleep(100); return this; }
      *
-     *     static __new__<Class extends typeof AsyncExt>(
-     *         tgt: Ext.Target<Class>, map: Ext.Map<Class>
-     *     ) {
-     *         const ext = new this(tgt);
+     *     __new__(tgt: SomeType): Job<this> {
+     *         const ext = this.__inst__(tgt);
      *         map.set(tgt, root.start(ext.setup()) as Ext.Type<Class>);
      *     }
      * }
@@ -239,13 +214,25 @@ declare abstract class Ext<Target extends WeakKey = WeakKey> {
      * extension whose `setup()` has finished. (And subclasses of `AsyncExt`
      * will share the same behavior, while being subtyped appropriately.)
      *
-     * (Note: your `__new__` method *must* store what it created in the supplied
-     * map for the given target, and the value it sets must conform to the
-     * declared `__type__`, which is *not* checked for you by TypeScript!)
+     * @remarks Note that while this is technically an instance method, it's
+     * actually called with the class *prototype*, so you should not use any
+     * properties or methods of `this` other than `__inst__`.  Think of it
+     * as a function that's just on the class as a convenient way of configuring
+     * it.
+     *
+     * @category Lifecycle Hooks
+     */
+    __new__<C extends Ext>(this: C, tgt: C["of"]): unknown;
+    /**
+     * Given a target, create an extension instance.
+     *
+     * You do not need to override this, nor should you: it's just a type-safe
+     * way to construct an extension instance, since an Ext subclass's
+     * constructor may accept a wider type than the class actually requires.
      *
      * @category Lifecycle Hooks
      */
-    static __new__<Class extends Ext.Class>(this: Class, tgt: Ext.Target<Class>, map: Ext.Map<Class>): void;
+    __inst__<T extends Ext>(this: T, tgt: T["of"]): T;
     /**
      * This method is called by {@link delete}() if it finds an existing
      * extension for the target. You can override it in a subclass to do any

package/dist/ext.mjs

@@ -9,13 +9,13 @@ function method(factory, map = /* @__PURE__ */ new WeakMap()) {
 const classMap = /* @__PURE__ */ ext((cls) => /* @__PURE__ */ new WeakMap());
 class Ext {
   /**
-   * @deprecated Use .for() instead!
+   * @deprecated Use `.for()` or `prototype.__inst__()` instead!
    *
-   * Never directly call the constructor of an Ext subclass except from the
-   * {@link __new__ `__new__()`} method - otherwise you run the risk of having
-   * multiple instances for the same target.  (And it may accept invalid
-   * parameter values if you've redefined the type of the {@link Ext.of `of`}
-   * property in a sub-subclass.)
+   * Never directly call the constructor of an Ext subclass.  If you're
+   * creating an instance in {@link __new__ `__new__()`}, use the
+   * {@link __inst__ `__inst__()`} method instead.  Otherwise,
+   * you should use the .for or .get methods, as they are properly typed
+   * and won't create multiple instances for the same target.
    */
   constructor(of) {
     this.of = of;
@@ -26,7 +26,7 @@ class Ext {
    */
   static for(tgt) {
     const map = classMap(this);
-    return map.get(tgt) ?? (this.__new__(tgt, map), map.get(tgt));
+    return map.get(tgt) ?? setMap(map, tgt, this.prototype.__new__(tgt));
   }
   /**
    * Get the current extension instance for the given target, or `undefined`
@@ -64,21 +64,15 @@ class Ext {
    * behavior, e.g. to execute the constructor within a job, or create a
    * promise for an extension instance to be asynchronously initiaized, etc.
    *
-   * If you will be creating something other than an instance of the subclass,
-   * you must also redeclare the type of the {@link __type__ `__type__`}
-   * property.  For example:
+   * For example:
    *
    * ```ts
-   * class AsyncExt extends Ext {
-   *     declare readonly __type__: Job<this>
-   *
+   * class AsyncExt extends Ext<SomeType> {
    *     // simulate slow initialization
    *     *setup() { yield *sleep(100); return this; }
    *
-   *     static __new__<Class extends typeof AsyncExt>(
-   *         tgt: Ext.Target<Class>, map: Ext.Map<Class>
-   *     ) {
-   *         const ext = new this(tgt);
+   *     __new__(tgt: SomeType): Job<this> {
+   *         const ext = this.__inst__(tgt);
    *         map.set(tgt, root.start(ext.setup()) as Ext.Type<Class>);
    *     }
    * }
@@ -88,14 +82,28 @@ class Ext {
    * extension whose `setup()` has finished. (And subclasses of `AsyncExt`
    * will share the same behavior, while being subtyped appropriately.)
    *
-   * (Note: your `__new__` method *must* store what it created in the supplied
-   * map for the given target, and the value it sets must conform to the
-   * declared `__type__`, which is *not* checked for you by TypeScript!)
+   * @remarks Note that while this is technically an instance method, it's
+   * actually called with the class *prototype*, so you should not use any
+   * properties or methods of `this` other than `__inst__`.  Think of it
+   * as a function that's just on the class as a convenient way of configuring
+   * it.
+   *
+   * @category Lifecycle Hooks
+   */
+  __new__(tgt) {
+    return this.__inst__(tgt);
+  }
+  /**
+   * Given a target, create an extension instance.
+   *
+   * You do not need to override this, nor should you: it's just a type-safe
+   * way to construct an extension instance, since an Ext subclass's
+   * constructor may accept a wider type than the class actually requires.
    *
    * @category Lifecycle Hooks
    */
-  static __new__(tgt, map) {
-    map.set(tgt, new this(tgt, map));
+  __inst__(tgt) {
+    return new this.constructor(tgt);
   }
   /**
    * This method is called by {@link delete}() if it finds an existing

package/dist/shared.d.ts

@@ -5,6 +5,7 @@ import { Y as Yielding } from './types-N2ua11te.js';
  * boundaries.
  *
  * @module uneventful/shared
+ * @disableGroups
  */
 
 /**

package/dist/signals.d.ts

@@ -194,7 +194,7 @@ interface RuleFactory {
  *
  * @returns A function that can be called to terminate the rule.
  *
- * @category Reactive Behaviors
+ * @category none
  * @function
  */
 declare const rule: ((fn: () => OptionalCleanup) => DisposeFn) & RuleFactory;
@@ -214,7 +214,7 @@ declare const rule: ((fn: () => OptionalCleanup) => DisposeFn) & RuleFactory;
  * factory you wish to run pending rules for.  If not given, the default
  * {@link rule}() factory is targeted.
  *
- * @category Reactive Behaviors
+ * @category Scheduling
  */
 declare function runRules(scheduleFn?: SchedulerFn): void;
 /**
@@ -246,34 +246,6 @@ declare class WriteConflict extends Error {
  */
 declare class CircularDependency extends Error {
 }
-/**
- * Keep an expression's old value unless there's a semantic change
- *
- * By default, reactive values (i.e. {@link cached}(), or {@link value}() with a
- * {@link Configurable.setf setf}()) are considered to have "changed" (and thus
- * trigger recalculation of their dependents) when they are different according
- * to `===` comparison.
- *
- * This works well for primitive values, but for arrays and objects it's not
- * always ideal, because two arrays can have the exact same elements and still
- * be different according to `===`.  So this function lets you substitute a
- * different comparison function (like a deep-equal or shallow-equal) instead.
- * (The default is {@link arrayEq}() if no compare function is supplied.)
- *
- * Specifically, if your reactive expression returns `unchangedIf(newVal,
- * compare)`, then the expression's previous value will be kept if the compare
- * function returns true when called with the old and new values. Otherwise, the
- * new value will be used.
- *
- * @remarks
- * - If the reactive expression's last "value" was an error, the new value is
- *   returned
- * - An error will be thrown if this function is called outside a reactive
- *   expression or from within a {@link peek}() call or {@link action} wrapper.
- *
- * @category Reactive Values
- */
-declare function unchangedIf<T>(newVal: T, equals?: (v1: T, v2: T) => boolean): T;
 
 /**
  * The Signals API for uneventful.
@@ -377,7 +349,7 @@ interface Configurable<T> extends Writable<T> {
 /**
  * Create a {@link Configurable} signal with the given inital value
  *
- * @category Reactive Values
+ * @category none
  */
 declare function value<T>(val?: T): Configurable<T>;
 /**
@@ -389,7 +361,7 @@ declare function value<T>(val?: T): Configurable<T>;
  * calling signature below will apply, even if TypeScript doesn't see it that
  * way!)
  *
- * @category Reactive Values
+ * @category none
  */
 declare function cached<T>(compute: () => T): Signal<T>;
 /**
@@ -430,7 +402,7 @@ declare function cached<T extends Signal<any>>(signal: T): T;
  *
  * @returns The result of calling `fn(..args)`
  *
- * @category Reactive Values
+ * @category Dependency Tracking
  */
 declare function peek<F extends PlainFunction>(fn: F, ...args: Parameters<F>): ReturnType<F>;
 /**
@@ -472,7 +444,7 @@ declare function peek<F extends PlainFunction>(fn: F, ...args: Parameters<F>): R
  * to the original function, while running with dependency tracking suppressed
  * (as with {@link peek}()).
  *
- * @category Reactive Behaviors
+ * @category Dependency Tracking
  */
 declare function action<F extends AnyFunction>(fn: F): F;
 /** @hidden TC39 Decorator protocol */
@@ -483,6 +455,78 @@ declare function action<F extends AnyFunction>(fn: F, ctx: {
 declare function action<F extends AnyFunction, D extends {
     value?: F;
 }>(clsOrProto: any, name: string | symbol, desc: D): D;
+/**
+ * Keep an expression's old value unless there's a semantic change
+ *
+ * By default, reactive values (i.e. {@link cached}(), or {@link value}() with a
+ * {@link Configurable.setf setf}()) are considered to have "changed" (and thus
+ * trigger recalculation of their dependents) when they are different according
+ * to `===` comparison.
+ *
+ * This works well for primitive values, but for arrays and objects it's not
+ * always ideal, because two arrays can have the exact same elements and still
+ * be different according to `===`.  So this function lets you substitute a
+ * different comparison function (like a deep-equal or shallow-equal) instead.
+ *
+ * Specifically, if your reactive expression returns `stable(compare, newVal)`,
+ * then the expression's previous value will be kept if the `compare` function
+ * returns true when called with the old and new values. Otherwise, the new
+ * value will be used.
+ *
+ * @remarks
+ * - If the reactive expression's last "value" was an error, the new value is
+ *   returned.
+ * - An error will be thrown if this function is called outside a reactive
+ *   expression or from within a {@link peek}() call or {@link action} wrapper.
+ * - You can use the {@link stabilizer}() function to create custom functions
+ *   similar to {@link stableJSON}. or {@link stableArray}().
+ *
+ * @category Dependency Tracking
+ */
+declare function stable<T>(equals: (v1: T, v2: T) => boolean, newVal: T): T;
+/**
+ * @deprecated This is {@link stable}() but with swapped arguments.  Please switch
+ * to using stable(), stableArray(), or a stabilizer(), as this function will be removed
+ * in a future release.
+ *
+ * @hidden
+ */
+declare function unchangedIf<T>(newVal: T, equals?: (v1: T, v2: T) => boolean): T;
+/**
+ * Create a shorthand version of {@link stable}(), pre-bound to a specific comparison
+ * function.
+ *
+ * @param equals The comparison function to use
+ * @template T The type of value the comparison function works on
+ *
+ * @category Dependency Tracking
+ */
+declare function stabilizer<T>(equals: <T>(v1: T, v2: T) => boolean): <R extends T>(newVal: R) => R;
+/**
+ * Keep an expression's old value if the new value is an array with the same
+ * contents.
+ *
+ * (Shorthand for {@link stable}({@link arrayEq}, ...).)
+ *
+ * @function
+ * @category Dependency Tracking
+ */
+declare const stableArray: <R extends unknown[]>(newVal: R) => R;
+/**
+ * Keep an expression's old value if its JSON string is the same as the new one.
+ *
+ * (Shorthand for {@link stable}() with a JSON-string comparison function.)
+ *
+ * Note that JSON string comparison is slow and memory intensive for more
+ * complex data structures, is order-sensitive for object keys, and doesn't
+ * support maps or sets.  If you need any of those things, you should probably
+ * use a {@link stabilizer}() based on
+ * [fast-equals](https://github.com/planttheidea/fast-equals) instead.
+ *
+ * @function
+ * @category Dependency Tracking
+ */
+declare const stableJSON: <R extends any>(newVal: R) => R;
 /**
  * Wait for and return the next truthy value (or error) from a data source (when
  * processed with `yield *` within a {@link Job}).
@@ -514,4 +558,4 @@ declare function action<F extends AnyFunction, D extends {
  */
 declare function until<T>(source: UntilMethod<T> | Stream<T> | (() => T)): Yielding<T>;
 
-export { CircularDependency, type Configurable, type GenericMethodDecorator, type RuleFactory, type SchedulerFn, type Signal, type Writable, WriteConflict, action, cached, peek, rule, runRules, unchangedIf, until, value };
+export { CircularDependency, type Configurable, type GenericMethodDecorator, type RuleFactory, type SchedulerFn, type Signal, type Writable, WriteConflict, action, cached, peek, rule, runRules, stabilizer, stable, stableArray, stableJSON, unchangedIf, until, value };

package/dist/signals.mjs

@@ -1,6 +1,6 @@
 import { F as pushCtx, G as popCtx, w as makeJob, c as root, f as isError, e as markHandled, g as getJob, x as detached, k as currentCell, o as reject, b as resolve } from './jobutils-Dvu-e99o.mjs';
 import { b as backpressure, I as IsStream, a as callOrWait } from './call-or-wait-EzXJX5Dq.mjs';
-import { e as batch, f as arrayEq, d as defer, c as apply, s as setMap, C as CallableObject } from './utils-cyEhnyp7.mjs';
+import { e as batch, d as defer, c as apply, s as setMap, C as CallableObject, f as arrayEq } from './utils-cyEhnyp7.mjs';
 
 const ruleQueues = /* @__PURE__ */ new WeakMap();
 function ruleQueue(scheduleFn = defer) {
@@ -478,6 +478,9 @@ class Cell {
       this.flags &= ~8 /* Peeking */;
     }
   }
+  unchangedIf(newVal, equals) {
+    return this.flags & 16 /* Error */ || !equals(this.value, newVal) ? newVal : this.value;
+  }
   recalcWhen(fnOrKey, fn) {
     if (this.flags & 8 /* Peeking */)
       return;
@@ -514,13 +517,12 @@ class Cell {
     return stop;
   }
 }
-function unchangedIf(newVal, equals = arrayEq) {
-  const cell = currentCell;
-  if (cell) {
-    return cell.flags & 16 /* Error */ || !equals(cell.value, newVal) ? newVal : cell.value;
-  } else {
-    throw new Error("unchangedIf() must be called from a reactive expression");
-  }
+function getCell(f = "") {
+  if (!currentCell || currentCell.flags & 8 /* Peeking */)
+    throw new Error(
+      `${f}must be called from a reactive expression`
+    );
+  return currentCell;
 }
 
 class RF extends CallableObject {
@@ -685,6 +687,17 @@ function action(fn, _ctx, desc) {
     return currentCell ? currentCell.peek(fn, this, args) : apply(fn, this, args);
   };
 }
+function stable(equals, newVal) {
+  return getCell("stabilizers ").unchangedIf(newVal, equals);
+}
+function unchangedIf(newVal, equals = arrayEq) {
+  return stable(equals, newVal);
+}
+function stabilizer(equals) {
+  return stable.bind(null, equals);
+}
+const stableArray = /* @__PURE__ */ stabilizer(arrayEq);
+const stableJSON = /* @__PURE__ */ stabilizer((a, b) => JSON.stringify(a) === JSON.stringify(b));
 function until(source) {
   return callOrWait(source, "uneventful.until", waitTruthy, recache);
 }
@@ -695,4 +708,4 @@ function waitTruthy(job, v) {
   v && job.return(v);
 }
 
-export { CircularDependency, ConfigurableImpl, SignalImpl, WritableImpl, WriteConflict, action, cached, peek, rule, runRules, unchangedIf, until, value };
+export { CircularDependency, ConfigurableImpl, SignalImpl, WritableImpl, WriteConflict, action, cached, peek, rule, runRules, stabilizer, stable, stableArray, stableJSON, unchangedIf, until, value };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "uneventful",
-    "version": "0.0.11",
+    "version": "0.0.12",
     "description": "Declarative, event-driven reactivity: signals, streams, structured concurrency, and easy resource cleanup",
     "keywords": [
         "signals",
@@ -93,7 +93,7 @@
         "ts-expect": "^1.3.0",
         "ts-node": "^10.9.1",
         "tsx": "^4.6.1",
-        "typedoc": "0.28.1",
+        "typedoc": "0.28.2",
         "typescript": "^5.4.5"
     }
 }