uneventful 0.0.11 → 0.0.13

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-N2ua11te.js';
-import { U as UntilMethod } from './sinks-5TuxCRtX.js';
+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';
 
 /**
  * A decorator function that supports both TC39 and "legacy" decorator protocols
@@ -10,11 +10,11 @@ import { U as UntilMethod } from './sinks-5TuxCRtX.js';
  * @category Types and Interfaces
  */
 type GenericMethodDecorator<F extends AnyFunction> = {
-    /** TC39 Method Decorator @hidden */
+    /** TC39 Method Decorator */
     (fn: F, ctx?: {
         kind: "method";
     }): F;
-    /** Legacy Method Decorator @hidden */
+    /** Legacy Method Decorator */
     (proto: object, name: string | symbol, desc?: {
         value?: F;
     }): void;
@@ -130,20 +130,6 @@ interface RuleFactory {
      *
      */
     factory(scheduleFn: SchedulerFn): RuleFactory;
-    /**
-     * @deprecated Use {@link RuleFactory.root} instead
-     *
-     * ---
-     * Create a "detached" or standalone rule, that is not attached to any job.
-     *
-     * `r.detached(fn)` is shorthand for calling `detached.run(r, fn)`.  (Where
-     * `r` is a {@link RuleFactory} such as `rule`.)
-     *
-     * Note that since the created rule isn't attached to a job, it *must* be
-     * explicitly stopped, either by calling the returned disposal function or
-     * by the rule function arranging to stop itself via {@link rule.stop}().
-     */
-    detached(fn: () => OptionalCleanup): DisposeFn;
     /**
      * Create a standalone rule, not attached to the current job.
      *
@@ -194,7 +180,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 +200,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 +232,132 @@ declare class WriteConflict extends Error {
  */
 declare class CircularDependency extends Error {
 }
+
+/** @inline */
+type Get<V> = () => V;
+/** @inline */
+type GetFactory<O extends WeakKey, V = void> = (obj: O) => Get<V>;
+/** @inline */
+type Method<O extends WeakKey, V = void> = (this: O) => V;
+/** @inline */
+type DeferredFn = {
+    <Result>(compute: () => Result): Signal<Result>;
+    <Instance extends WeakKey, Result>(factory: GetFactory<Instance, Result>): (obj: Instance) => Result;
+};
+/** @inline */
+type DeferredFx = {
+    (compute: () => void): Get<void>;
+    <Instance extends WeakKey>(factory: GetFactory<Instance, void>): (obj: Instance) => void;
+};
 /**
- * Keep an expression's old value unless there's a semantic change
+ * Create a signal that computes a value based on other signals.  (Can also be
+ * used as a method decorator via `@fn`, with either TC39 or "Legacy"
+ * decorators.)
  *
- * 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.
+ * @param compute The function that will be called to compute the result, if the
+ * signals it used in its last invocation have changed since then.
  *
- * 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.)
+ * @returns A signal that returns a cached value or recomputes it as necessary,
+ * and will be tracked as a dependency for other signals, rules, or effects,
+ * when they use it in their calculations.
  *
- * 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.
+ * @template Result The type of value the created signal will provide.
  *
- * @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 none
+ */
+declare function fn<Result>(compute: Get<Result>): Signal<Result>;
+/**
+ * Create a parameterized reactive function that tracks separate dependencies
+ * and caching state for each object it's called on.
+ *
+ * @returns a one-argument reactive function that is shorthand for looking up
+ * and returning the value of a cached signal customized for the given argument.
+ *
+ * That is, given `rf = fn(a => () => a.bar)`, calling `rf(foo)` is equivalent
+ * to calling `fn(() => foo.bar)()`, except that each `foo` gets its own `fn(()
+ * => foo.bar)` signal cached, so that dependencies can be properly tracked
+ * per instance.
+ *
+ * @param factory A function that will be called with each new instance passed
+ * to the one-argument reactive function.  It must return a zero-argument
+ * function, customized to compute the value for the instance it was given.
+ *
+ * @template Instance The type of object the created function will be used with
+ * @template Result The type of result the created function will return
  *
- * @category Reactive Values
  */
-declare function unchangedIf<T>(newVal: T, equals?: (v1: T, v2: T) => boolean): T;
+declare function fn<Instance extends WeakKey, Result>(factory: GetFactory<Instance, Result>): (obj: Instance) => Result;
+/** @hidden support for ```fn``()``` */
+declare function fn(t: TemplateStringsArray): DeferredFn;
+/** @hidden TC39 decorator */
+declare function fn<Instance extends WeakKey, Result>(f: Method<Instance, Result>, ctx: {
+    kind: "method";
+}): Method<Instance, Result>;
+/** @hidden "Legacy"/"TypeScript Experimental" Decorator */
+declare function fn<Instance extends WeakKey, Result, D extends {
+    value?: Method<Instance, Result>;
+}>(clsOrProto: any, name: string | symbol, desc: D): D;
+/**
+ * Create a reactive effect (void signal) that runs when observed by a rule
+ * (directly or via other reactive functions).  (Can also be used as a method
+ * decorator via `@fx`, with either TC39 or "Legacy" decorators.)
+ *
+ * @remarks Note that reactive effects do not actually execute unless they are
+ * "in use", i.e. either directly invoked from an active job or called
+ * indirectly from a rule or effect that is itself in use.
+ *
+ * @param effect The function that will be called to start (or restart) the
+ * effect, if the reactive values it used during its last run have changed since
+ * then.
+ *
+ * The effect function is run in a job that will restart if its dependencies
+ * change, and when the effect is no longer in use.  (So you can use e.g.
+ * {@link must}() to define rollback actions, and any jobs, subscriptions, etc.
+ * you start inside the effect function will likewise be terminated when the
+ * effect becomes unobserved or its dependencies change.)
+ *
+ * @returns a zero-argument reactive function that can be called from any rule,
+ * job, or other observed reactive functions, to start or continue the effect.
+ *
+ * Multiple calls from the same or different observers do not restart the
+ * effect; only dependency changes will restart it.  If it loses all observers
+ * (i.e. fails to be called by any of them, or all the calling jobs end), the
+ * effect will stop until it's in use again.
+ *
+ * @category none
+ */
+declare function fx(effect: Get<void>): Get<void>;
+/**
+ * Create a parameterized reactive effect that tracks separate dependencies,
+ * jobs, and caching state for each object it's called on.
+ *
+ * @returns a one-argument reactive effect that is shorthand for looking up and
+ * calling a cached, zero-argument reactive effect customized for the given
+ * argument.
+ *
+ * That is, given `rx = fx(a => () => a.bar())`, calling `rx(foo)` is equivalent
+ * to calling `fx(() => foo.bar())()`, except that each `foo` gets its own
+ * `fx(() => foo.bar())` instance cached, so that dependencies can be properly
+ * tracked per instance.
+ *
+ * @param factory A function that will be called with each new instance passed
+ * to the returned effect function.  It must return a zero-argument effect
+ * function, customized to apply the effect to the instance it was given.
+ *
+ * @template Instance The type of object the effect will be applied to
+ *
+ */
+declare function fx<Instance extends WeakKey>(factory: GetFactory<Instance>): (ob: Instance) => void;
+/** @hidden support for ```fx``()``` */
+declare function fx(t: TemplateStringsArray): DeferredFx;
+/** @hidden TC39 decorator */
+declare function fx<Instance extends WeakKey>(method: Method<Instance>, ctx: {
+    kind: "method";
+}): Method<Instance>;
+/** @hidden "Legacy"/"TypeScript Experimental" Decorator */
+declare function fx<Instance extends WeakKey, D extends {
+    value?: Method<Instance>;
+}>(clsOrProto: any, name: string | symbol, desc: D): D;
 
 /**
  * The Signals API for uneventful.
@@ -377,7 +461,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 +473,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 +514,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 +556,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 +567,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 +670,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, fn, fx, peek, rule, runRules, stabilizer, stable, stableArray, stableJSON, unchangedIf, until, value };