uneventful 0.0.12 → 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.
      *
@@ -247,6 +233,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;
+};
+/**
+ * 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.)
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @template Result The type of value the created signal will provide.
+ *
+ * @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
+ *
+ */
+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.
  *
@@ -558,4 +670,4 @@ declare const stableJSON: <R extends any>(newVal: R) => R;
  */
 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, stabilizer, stable, stableArray, stableJSON, 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 };