uneventful 0.0.5 → 0.0.7

package/dist/signals.d.ts

@@ -0,0 +1,470 @@
+import { A as AnyFunction, D as DisposeFn, O as OptionalCleanup, 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-kEzJo6Hc.js';
+
+/**
+ * A decorator function that supports both TC39 and "legacy" decorator protocols
+ *
+ * @template F the type of method this decorator can decorate.  If the method
+ * doesn't conform to this type, compile-time type checks will fail.
+ *
+ * @category Types and Interfaces
+ */
+type GenericMethodDecorator<F extends AnyFunction> = {
+    /** TC39 Method Decorator @hidden */
+    (fn: F, ctx?: {
+        kind: "method";
+    }): F;
+    /** Legacy Method Decorator @hidden */
+    (proto: object, name: string | symbol, desc?: {
+        value?: F;
+    }): void;
+};
+/**
+ * The interface provided by {@link rule}, and other {@link rule.factory}()
+ * functions.
+*
+* @category Types and Interfaces
+*/
+interface RuleFactory {
+    /**
+     * @inheritdoc rule factory tied to a specific scheduler.  See {@link rule} for
+     * more details.
+     */
+    (fn: (stop: DisposeFn) => OptionalCleanup): DisposeFn;
+    /**
+     * A function that will stop the currently-executing rule.  (Accessing this
+     * attribute will throw an error if no rule is currently running.)
+     *
+     * Note: this returns the stop for the current rule regardless of its
+     * scheduler, so you can access `rule.stop` even if the rule was created
+     * with a different scheduler.
+     */
+    readonly stop: DisposeFn;
+    /**
+     * Observe a condition and apply an action.
+     *
+     * For a given {@link RuleFactory} `r` (such as `rule`), `r.if(condition,
+     * action)` is roughly equivalent to `r(() => { if (condition()) return
+     * action(); })`, except that the rule is *only* rerun if the `action`'s
+     * dependencies change, *or* the **truthiness** of `condition()` changes. It
+     * will *not* be re-run if only the dependencies of `condition()` have
+     * changed, without affecting its truthiness.
+     *
+     * This behavior can be important for rules that nest other rules, have
+     * cleanups, fire off tasks, etc., as it may be wasteful to constantly tear
+     * them down and set them back up if the enabling condition is a calculation
+     * with frequently-changing dependencies.
+     *
+     * @remarks This is just a shortcut for wrapping `condition` as a signal
+     * that converts it to boolean. So if you already *have* a boolean signal,
+     * you can get the same effect with just `if (condition()) { ... }`.
+     */
+    if(condition: () => any, action: () => OptionalCleanup): DisposeFn;
+    /**
+     * Decorate a method or function to behave as a rule, e.g.
+     *
+     * ```ts
+     * const animate = rule.factory(requestAnimationFrame);
+     *
+     * class Draggable {
+     *     ⁣@animate.method
+     *     trackPosition(handleTop: number, handleLeft: number) {
+     *         const {clientX, clientY} = lastMouseEvent();
+     *         this.element.style.top  = `${clientY - handleTop}px`;
+     *         this.element.style.left = `${clientX - handleLeft}px`;
+     *     }
+     * }
+     *
+     * // Start running the method in an animation frame for every change to
+     * // lastMouseEvent, until the current job ends:
+     * someDraggable.trackPosition(top, left);
+     * ```
+     * or:
+     * ```ts
+     * const logger = rule.method((formatString, signal) => { log(formatString, signal()); });
+     * ```
+     *
+     * Each time it's (explicitly) called, the decorated method will start a new
+     * rule, which will repeatedly run the method body (with the original
+     * arguments and `this`) whenever its dependencies change, according to the
+     * schedule defined by the rule factory.  (So e.g. `@rule.method` will
+     * update on the microtask after a change, etc.)
+     *
+     * The decorated method will always return a {@link DisposeFn} to let you
+     * explicitly stop the rule before the current job end.  But if the original
+     * method body doesn't return a dispose function of its own, TypeScript will
+     * consider the method to return void, unless you explicitly declare its
+     * return type to be `DisposeFn | void`.
+     *
+     * Also note that since rule methods can accept arbitrary parameters, they
+     * do not receive a `stop` parameter, and must therefore use {@link
+     * RuleFactory.stop rule.stop}() if they wish to terminate themselves.
+     */
+    readonly method: GenericMethodDecorator<(...args: any[]) => OptionalCleanup>;
+    /**
+     * Return a rule factory for the given scheduling function, that you can
+     * then use to make rules that run in a specific time frame.
+     *
+     * ```ts
+     * // `animate` will now create rules that run during animation fames
+     * const animate = rule.factory(requestAnimationFrame);
+     *
+     * animate(() => {
+     *     // ... do stuff in an animation frame when signals used here change
+     * })
+     * ```
+     *
+     * (In addition to being callable, the returned function is also a
+     * {@link RuleFactory}, and thus has a `.method` decorator, `.if()` method,
+     * and so on.)
+     *
+     * @param scheduleFn A single-argument scheduling function (such as
+     * requestAnimationFrame, setImmediate, or queueMicrotask).  The rule
+     * scheduler will call it from time to time with a single callback.  The
+     * scheduling function should then arrange for that callback to be invoked
+     * *once* at some future point, when it is the desired time for all pending
+     * rules on that scheduler to run.
+     *
+     * @returns A {@link RuleFactory}, like {@link rule}.  If called with the
+     * same scheduling function more than once, it returns the same factory.
+     *
+     */
+    factory(scheduleFn: SchedulerFn): RuleFactory;
+    /**
+     * 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}() or
+     * its stop parameter.
+     */
+    detached(fn: (stop: DisposeFn) => OptionalCleanup): DisposeFn;
+    /**
+     * Change the scheduler used for the currently-executing rule.  Throws an
+     * error if no rule is running.
+     *
+     * @param scheduleFn Optional: The {@link SchedulerFn scheduling function}
+     * to use; the default microtask scheduler will be used if none is given or
+     * the given value is falsy.
+     *
+     * @remarks It's best to only use scheduling functions that were created
+     * *outside* the current rule, otherwise you'll be creating a new scheduling
+     * queue object on every run of the rule.  (These will get garbage collected
+     * with the scheduling functions, but you'll be creating more memory
+     * pressure and using more GC time if the rule runs frequently.)
+     */
+    setScheduler(scheduleFn?: SchedulerFn): void;
+}
+/**
+ * Subscribe a function to run every time certain values change.
+ *
+ * The function is run asynchronously, first after being created, then again
+ * after there are changes in any of the values or cached functions it read
+ * during its previous run.
+ *
+ * The created subscription is tied to the currently-active job (which may be
+ * another rule).  So when that job is ended or restarted, the rule will be
+ * terminated automatically.  You can also terminate it early by calling the
+ * "stop" function that is both passed to the rule function and returned by
+ * `rule()`.
+ *
+ * Note: this function will throw an error if called without an active job. If
+ * you need a standalone rule, use {@link RuleFactory.detached rule.detached}().
+ *
+ * @param fn The function that will be run each time its dependencies change.
+ * The function will be run in a restarted job each time, with any resources
+ * used by the previous run being cleaned up.  The function is passed a single
+ * argument: a function that can be called to terminate the rule.   The function
+ * should return a cleanup function or void.
+ *
+ * @returns A function that can be called to terminate the rule.
+ *
+ * @category Signals
+ */
+declare const rule: ((action: (stop: DisposeFn) => OptionalCleanup) => DisposeFn) & RuleFactory;
+/**
+ * Synchronously run any pending rules tied to a specific schedule.
+ *
+ * (Note: "pending" rules are ones with at least one changed ancestor
+ * dependency; this doesn't mean they will actually *do* anything, since
+ * intermediate cached() function results might end up unchanged.)
+ *
+ * You should normally only need to call this when you need to *force*
+ * side-effects to occur within a specific *synchronous* timeframe, e.g. if
+ * rules need to be able to cancel a synchronous event or continue an IndexedDB
+ * transaction.  (Otherwise, this is really only useful for testing.)
+ *
+ * @param scheduleFn The {@link SchedulerFn scheduler} used to create the rule
+ * factory you wish to run pending rules for.  If not given, the default
+ * {@link rule}() factory is targeted.
+ *
+ * @category Signals
+ */
+declare function runRules(scheduleFn?: SchedulerFn): void;
+/**
+ * A single-argument scheduling function (such as requestAnimationFrame,
+ * setImmediate, or queueMicrotask).  The rule scheduler will call it from time
+ * to time with a single callback.  The scheduling function should then arrange
+ * for that callback to be invoked *once* at some future point, when it is the
+ * desired time for all pending rules on that scheduler to run.
+ *
+ * @category Types and Interfaces
+ */
+type SchedulerFn = (cb: () => unknown) => unknown;
+
+/**
+ * Error indicating a rule has attempted to write a value it indirectly
+ * depends on, or which has already been read by another rule in the current
+ * batch. (Also thrown when a cached function attempts to write a value at all,
+ * directly or indirectly.)
+ *
+ * @category Errors
+ */
+declare class WriteConflict extends Error {
+}
+/**
+ * Error indicating a rule has attempted to write a value it directly depends
+ * on, or a cached function has called itself, directly or indirectly.
+ *
+ * @category Errors
+ */
+declare class CircularDependency extends Error {
+}
+
+/**
+ * The Signals API for uneventful.
+ *
+ * @module uneventful/signals
+ */
+
+/**
+ * An observable value, as a zero-argument callable with extra methods.
+ *
+ * In addition to being callable, signals also offer a `.value` getter, and
+ * implement the standard JS methods `.toString()`, `.valueOf()`, and
+ * `.toJSON()` in such a way that they reflect the signal's contents rather than
+ * the signal itself.
+ *
+ * Signals also implement the {@link Source} interface, and can thus be
+ * subscribed to.  Subscribers receive the current value first, and then any
+ * changes thereafter.  They can be waited on by {@link until}(), in which case
+ * the calling job resumes when the signal's value is truthy.
+ *
+ * You can also transform a signal to a {@link Writable} by calling its
+ * .{@link Signal.withSet withSet}() method, or create a writable value using
+ * {@link value}().
+ *
+ * @category Types and Interfaces
+ */
+interface Signal<T> extends SignalSource<T>, UntilMethod<T> {
+    /**
+     * The current value
+     *
+     * @category Reading
+     */
+    readonly value: T;
+    /** Current value @hidden */
+    valueOf(): T;
+    /** Current value as a string @hidden */
+    toString(): string;
+    /** The current value @hidden */
+    toJSON(): T;
+    /**
+     * Get the signal's current value, without adding the signal as a dependency
+     *
+     * (This is exactly equivalent to calling {@link peek}(signal), and exists
+     * here mainly for interop with other signal frameworks.)
+     *
+     *  @category Reading */
+    peek(): T;
+    /** Get a read-only version of this signal @category Reading */
+    asReadonly(): Signal<T>;
+    /** New writable signal with a custom setter @category Writing */
+    withSet(set: (v: T) => unknown): Writable<T>;
+    /** @hidden */
+    "uneventful.until"(): Yielding<T>;
+}
+/**
+ * A {@link Signal} with a {@link Writable.set | .set()} method and writable
+ * {@link Writable.value | .value} property.
+ *
+ * @category Types and Interfaces
+ */
+interface Writable<T> extends Signal<T> {
+    /**
+     * Set the current value.  (Note: this is a bound method so it can be used
+     * as a callback.)
+     *
+     * @category Writing
+     */
+    readonly set: (val: T) => void;
+    get value(): T;
+    /** Set the current value */
+    set value(val: T);
+}
+/**
+ * A writable signal that can be set to either a value or an expression.
+ *
+ * Like a spreadsheet cell, a configurable signal can contain either a value or
+ * a formula.  If you .set() a value or change the .value property of the
+ * signal, the formula is cleared.  Conversely, if you set a formula with
+ * .setf(), then the value is calculated using that formula from then on, until
+ * another formula is set, or the value is changed directly again.
+ *
+ * @category Types and Interfaces
+ */
+interface Configurable<T> extends Writable<T> {
+    /**
+     * Set a formula that will be used to calculate the signal's value. If it
+     * uses the value of other signals, this signal's value will be recalculated
+     * when they change.
+     *
+     * @category Writing
+     */
+    setf(expr: () => T): this;
+}
+/**
+ * Create a {@link Configurable} signal with the given inital value
+ *
+ * @category Signals
+ */
+declare function value<T>(val?: T): Configurable<T>;
+/**
+ * Create a cached version of a function.  The returned callable is also a
+ * {@link Signal}.
+ *
+ * Note: If the supplied function has a non-zero `.length` (i.e., it explicitly
+ * takes arguments), it is assumed to be a {@link Source}, and the second
+ * calling signature below will apply, even if TypeScript doesn't see it that
+ * way!)
+ *
+ * @category Signals
+ */
+declare function cached<T>(compute: () => T): Signal<T>;
+/**
+ * If the supplied function has a non-zero `.length` (i.e., it explicitly takes
+ * arguments), it is assumed to be a {@link Source}, and the second argument is
+ * a default value for the created signal to use as default value until the
+ * source produces a value.
+ *
+ * The source will be subscribed *only* while the signal is subscribed as a
+ * stream, or observed (directly or indirectly) by a rule.  While subscribed,
+ * the signal will update itself with the most recent value produced by the
+ * source, triggering rules or events as appropriate if the value changes.  When
+ * the signal is once again unobserved (or if the source ends without an error),
+ * its value will revert to the supplied default.
+ *
+ * If the source ends *with* an error, however, then the cached function will
+ * throw that error whenever called, until/unless it becomes unobserved again.
+ * (And thus reverts to the default value once more.)
+ *
+ * @param source A {@link Source} providing data which will become this signal's
+ * value
+ * @param defaultVal The value to use when the signal is unobserved or waiting for
+ * the first item from the source.
+ */
+declare function cached<T>(source: Source<T>, defaultVal?: T): Signal<T>;
+declare function cached<T extends Signal<any>>(signal: T): T;
+/**
+ * Call a function without creating a dependency on any signals it reads.  (Like
+ * {@link Signal.peek}, but for any function with any arguments.)
+ *
+ * You can also pass in any arguments the function takes, and the function's
+ * return value is returned.
+ *
+ * (Note: Typed overloads are not supported: TypeScript will use the function's
+ * *last* overload for argument-typing purposes.  If you need to call a function
+ * with a specific overload, wrap the function with {@link action}() instead, and
+ * then TypeScript will be able to detect which overload you're using.)
+ *
+ * @returns The result of calling `fn(..args)`
+ *
+ * @category Signals
+ */
+declare function peek<F extends PlainFunction>(fn: F, ...args: Parameters<F>): ReturnType<F>;
+/**
+ * Wrap a function (or decorate a method) so that signals it reads are not added
+ * as dependencies to the current rule (if any).  (Basically, it's shorthand for
+ * wrapping the function or method body in a giant call to {@link peek}().)
+ *
+ * So, instead of writing an action function like this:
+ *
+ * ```ts
+ * function outer(arg1, arg2) {
+ *     return peek(() => {
+ *         // reactive values used here will not be added to the running rule
+ *     })
+ * }
+ * ```
+ * you can just write this:
+ * ```ts
+ * const outer = action((arg1, arg2) => {
+ *     // reactive values used here will not be added to the running rule
+ * });
+ * ```
+ * or this:
+ * ```ts
+ * class Something {
+ *     ⁣⁣@action  // auto-detects TC39 or legacy decorators
+ *     someMethod(arg1) {
+ *         // reactive values used here will not be added to the running rule
+ *     }
+ * }
+ * ```
+ *
+ * @param fn The function to wrap.  It can take any arguments or return value,
+ * and overloads are supported.  However, any non-standard properties the
+ * function may have had will *not* be present on the wrapped function, even if
+ * TypeScript will act as if they are!
+ *
+ * @returns A wrapped version of the function that passes through its arguments
+ * to the original function, while running with dependency tracking suppressed
+ * (as with {@link peek}()).
+ *
+ * @category Signals
+ */
+declare function action<F extends AnyFunction>(fn: F): F;
+/** @hidden TC39 Decorator protocol */
+declare function action<F extends AnyFunction>(fn: F, ctx: {
+    kind: "method";
+}): F;
+/** @hidden Legacy Decorator protocol */
+declare function action<F extends AnyFunction, D extends {
+    value?: F;
+}>(clsOrProto: any, name: string | symbol, desc: D): D;
+/**
+ * Wait for and return the next truthy value (or error) from a data source (when
+ * processed with `yield *` within a {@link Job}).
+ *
+ * This differs from {@link next}() in that it waits for the next "truthy" value
+ * (i.e., not null, false, zero, empty string, etc.), and when used with signals
+ * or a signal-using function, it can resume *immediately* if the result is
+ * already truthy.  (It also supports zero-argument signal-using functions,
+ * automatically wrapping them with {@link cached}(), as the common use case for
+ * until() is to wait for an arbitrary condition to be satisfied.)
+ *
+ * @param source The source to wait on, which can be:
+ * - An object with an `"uneventful.until"` method returning a {@link Yielding}
+ *   (in which case the result will be the the result of calling that method)
+ * - A {@link Signal}, or a zero-argument function returning a value based on
+ *   signals (in which case the job resumes as soon as the result is truthy,
+ *   perhaps immediately)
+ * - A {@link Source} (in which case the job resumes on the next truthy value
+ *   it produces
+ *
+ * (Note: if the supplied source is a function with a non-zero `.length`, it is
+ * assumed to be a {@link Source}.)
+ *
+ * @returns a Yieldable that when processed with `yield *` in a job, will return
+ * the triggered event, or signal value.  An error is thrown if event stream
+ * throws or closes early, or the signal throws.
+ *
+ * @category Signals
+ * @category Scheduling
+ */
+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, until, value };