uneventful 0.0.2 → 0.0.4

package/dist/mod.d.ts

@@ -222,507 +222,168 @@ declare class CancelError extends Error {
 }
 
 /**
- * The result type returned from calls to {@link Each}.next()
+ * A backpressure controller: returns true if downstream is ready to accept
+ * data.
  *
- * @category Types and Interfaces
- */
-type EachResult<T> = {
-    /** The value provided by the source being iterated */
-    item: T;
-    /**
-     * A suspend callback that must be `yield`-ed before the next call to the
-     * iterator's .next() method. (That is, you must `yield next` it exactly once
-     * per loop pass.  See {@link each}() for more details.)
-     */
-    next: Suspend<void>;
-};
-/**
- * The iterable returned by `yield *` {@link each}()
+ * @param cb (optional) - a callback to run when the downstream consumer wishes
+ * to resume event production (i.e., when a sink calls
+ * {@link Throttle.resume}()).  The callback is automatically unregistered when
+ * invoked, so the producer must re-register it after each call if it wishes to
+ * keep being called.
  *
  * @category Types and Interfaces
  */
-type Each<T> = IterableIterator<EachResult<T>>;
+type Backpressure = (cb?: () => any) => boolean;
 /**
- * Asynchronously iterate over an event source
- *
- * Usage:
- *
- * ```ts
- * for (const {item: event, next} of yield *each(mouseMove)) {
- *     console.log(event.clientX, event.clientY);
- *     yield next;  // required exactly once per iteration, even/w continue!
- * }
- * ```
- *
- * each(eventSource) yield-returns an iterator of `{item, next}` pairs.  The
- * item is the data supplied by the event source, and `next` is a
- * {@link Suspend}\<void\> that advances the iterator to the next item.  It
- * *must* be yielded exactly once per loop iteration.  If you use `continue` to
- * shortcut the loop body, you must `yield next` *before* doing so.
- *
- * The for-loop will end if the source ends, errors, or is canceled.  The source
- * is paused while the loop body is running, and resumed when the `yield next`
- * happens.  If events arrive anyway (e.g. because the source doesn't support
- * pausing), they will be ignored unless you pipe the source through the
- * {@link slack}() operator to provide a buffer. If the for-loop is exited
- * early for any reason (or the iterator's `.return()` is called), the source is
- * unsubscribed and the iteration ended.
+ * Create a backpressure control function for the given connection
  *
- * @category Stream Consumers
+ * @category Stream Producers
  */
-declare function each<T>(src: Source<T>): Yielding<Each<T>>;
+declare function backpressure(inlet?: Inlet): Backpressure;
 /**
- * An object that can be waited on with `yield *until()`.
+ * Control backpressure for listening streams.  This interface is the API
+ * internal to the implementation of {@link backpressure}().  Unless you're
+ * implementing a backpressurable stream yourself, see the {@link Throttle}
+ * interface instead.
  *
  * @category Types and Interfaces
  */
-type Waitable<T> = UntilMethod<T> | Source<T> | Promise<T> | PromiseLike<T>;
+interface Inlet {
+    /** Is the main connection open?  (i.e. is the creating job not closed yet?) */
+    isOpen(): boolean;
+    /** Is the conduit currently ready to receive data? */
+    isReady(): boolean;
+    /**
+     * Register a callback to produce more data when the inlet is resumed
+     * (The callback is unregistered if the supplied job ends.)
+     */
+    onReady(cb: () => any, job: Job): this;
+}
 /**
- * An object that can be waited on with `yield *until()`, by calling its
- * "uneventful.until" method.
+ * Control backpressure for listening streams
+ *
+ * Obtain instances via {@link throttle}(), then pass them into the appropriate
+ * stream-consuming API.  (e.g. {@link connect}).
  *
  * @category Types and Interfaces
  */
-interface UntilMethod<T> {
-    "uneventful.until"(): Yielding<T>;
+interface Throttle extends Inlet {
+    /** Set inlet status to "paused". */
+    pause(): void;
+    /**
+     * Un-pause, and iterate backpressure-able sources' onReady callbacks to
+     * resume sending immediately.  (i.e., synchronously!)
+     */
+    resume(): void;
 }
 /**
- * Wait for and return next value (or error) from a data source when processed
- * with `yield *` within a {@link Job}.
- *
- * @param source A {@link Waitable} data source, which can be any of:
- * - A {@link Signal} (in which case the job will resume when the value is
- *   truthy - perhaps immediately!)
- * - A {@link Source}
- * - A promise, or promise-like object with a `.then()` method
- * - An object with an `"uneventful.until"` method returning a {@link Yielding}
- *   (in which case the result will be the the result of that method)
- *
- * @returns a Yieldable that when processed with `yield *` in a job, will return
- * the triggered event, promise resolution, or signal value.  An error is thrown
- * if the promise rejects or the event stream throws or closes early, or the
- * signal throws.
+ * A Connection is a job that returns void when the connected stream ends
+ * itself.  If the stream doesn't end itself (e.g. it's an event listener), the
+ * job will never return, and only end with a cancel or throw.
  *
- * @category Scheduling
+ * @category Types and Interfaces
  */
-declare function until<T>(source: Waitable<T>): Yielding<T>;
-
+type Connection = Job<void>;
 /**
- * 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 inidirectly.)
+ * A Source is a function that can be called to arrange for data to be
+ * produced and sent to a {@link Sink} function for consumption, until the
+ * associated {@link Connection} is closed (either by the source or the sink,
+ * e.g. if the sink doesn't want more data or the source has no more to send).
  *
- * @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.
+ * If the source is a backpressurable stream, it can use the (optional) supplied
+ * inlet (usually a {@link throttle}()) to rate-limit its output.
  *
- * @category Errors
- */
-declare class CircularDependency extends Error {
-}
-/**
- * A queue for rules to run during a particular kind of period, such as
- * microtasks or animation frames.  (Can only be obtained or created via
- * {@link RuleScheduler.for}().)
+ * A producer function *must* return the special {@link IsStream} value, so
+ * TypeScript can tell what functions are usable as sources.  (Otherwise any
+ * void function with no arguments would appear to be usable as a source!)
  *
- * @category Signals
+ * @category Types and Interfaces
  */
-declare class RuleScheduler {
-    /**
-     * Run all pending rules on this scheduler.
-     *
-     * This is a bound method
-     *
-     * (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.)
-     */
-    flush: () => void;
-    /**
-     * Create an {@link RuleScheduler} from a callback-taking function, that
-     * you can then use to make rules that run in a specific time frame.
-     *
-     * ```ts
-     * // frame.rule will now create rules that run during animation fames
-     * const animate = RuleScheduler.for(requestAnimationFrame).rule;
-     *
-     * animate(() => {
-     *     // ... do stuff in an animation frame when signals used here change
-     * })
-     * ```
-     *
-     * Returns the default scheduler if no arguments are given.  If called with
-     * the same function more than once, it returns the same scheduler instance.
-     *
-     * @param scheduleFn A single-argument scheduling function (like
-     * requestAnimationFrame, setImmediate, or queueMicrotask).  The 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.
-     */
-    static for(scheduleFn?: (cb: () => unknown) => unknown): RuleScheduler;
-    protected constructor(_scheduleFn?: (cb: () => unknown) => unknown);
-    /**
-     * @inheritdoc rule tied to a specific scheduler.  See {@link rule} for
-     * more details.
-     *
-     * @remarks The rule will only run during its matching
-     * {@link RuleScheduler.flush}().
-     *
-     * This is a bound method, so you can use it independently of the scheduler
-     * it came from.
-     */
-    rule: (fn: (stop: DisposeFn) => OptionalCleanup) => DisposeFn;
+interface Source<T> {
+    /** Subscribe sink to receive values */
+    (sink: Sink<T>, conn?: Connection, inlet?: Throttle | Inlet): typeof IsStream;
 }
 /**
- * Subscribe a function to run every time certain values change.
- *
- * @remarks
- * 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 detached}.run to wrap the
- * call to rule.
- *
- * @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.
+ * An uneventful stream is either a {@link Source} or a {@link SignalSource}.
+ * (Signals actually implement the {@link Source} interface as an overload, but
+ * TypeScript gets confused about that sometimes, so we generally declare our
+ * stream *inputs* as `Stream<T>` and our stream *outputs* as {@link Source}, so
+ * that TypeScript knows what's what.
  *
- * @category Signals
+ * @category Types and Interfaces
  */
-declare const rule: (fn: (stop: DisposeFn) => OptionalCleanup) => DisposeFn;
+type Stream<T> = Source<T> | SignalSource<T>;
 /**
- * Synchronously run pending rules from the default scheduler.
- *
- * @remarks Equivalent to calling
- * {@link RuleScheduler.for}(defer).{@link RuleScheduler.flush flush}().
+ * The call signatures implemented by signals.  (They can be used as sources, or
+ * called with no arguments to return a value.)
  *
- * Note that you should normally only need to call this when you need
- * 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.  (You can also define rules to run in a specific
- * timeframe by creating a {@link RuleScheduler} for them, via
- * {@link RuleScheduler.for}.)
+ * This type is needed because TypeScript won't infer the overloads of
+ * {@link Signal} correctly otherwise. (Specifically, it won't allow it to be
+ * used as a zero-agument function.)
  *
- * @category Signals
- */
-declare const runRules: () => void;
-
-interface Signal<T> {
-    /**
-     * A signal object implements the {@link Producer} interface, even if it's
-     * not directly recognized as one by TypeScript.
-     */
-    (sink: Sink<T>, conn?: Connection, inlet?: Inlet): typeof IsStream;
+ * @category Types and Interfaces
+*/
+type SignalSource<T> = Source<T> & {
     /** A signal object can be called to get its current value */
     (): T;
-}
+};
 /**
- * An observable value, as a zero-argument callable with extra methods.
- *
- * Note: this class is not directly instantiable - use {@link cached}() or call
- * {@link readonly |.readonly()} on an existing signal instead.
+ * A specially-typed string used to verify that a function supports uneventful's
+ * streaming protocol.  Return it from a function to implement the
+ * {@link Source} type.
  *
  * @category Types and Interfaces
  */
-declare class Signal<T> extends Function implements UntilMethod<T> {
-    /** The current value */
-    get value(): T;
-    /** The current value */
-    valueOf(): T;
-    /** The current value, as a string */
-    toString(): string;
-    /** The current value */
-    toJSON(): T;
-    /** Get the signal's current value, without adding the signal as a dependency */
-    peek(): T;
-    /** Get a read-only version of this signal */
-    readonly(): Signal<T>;
-    /** New writable signal with a custom setter */
-    withSet(set: (v: T) => unknown): Writable<T>;
-    "uneventful.until"(): Yielding<T>;
-    protected constructor();
-}
-interface Writable<T> {
-    /** Set the current value.  (Note: this is a bound method so it can be used as a callback.) */
-    set(val: T): void;
-}
+declare const IsStream: "uneventful/is-stream";
 /**
- * A {@link Signal} with a {@link Writable.set | .set()} method and writable
- * {@link Writable.value | .value} property.
- *
- * Note: this class is not directly instantiable - use {@link value}() or call
- * {@link Signal.withSet | .withSet()} on an existing signal instead.
+ * A `Sink` is a function that receives data from a {@link Stream}.
  *
  * @category Types and Interfaces
  */
-declare class Writable<T> extends Signal<T> {
-    get value(): T;
-    set value(val: T);
-    readonly(): Signal<T>;
-}
+type Sink<T> = (val: T) => void;
 /**
- * Create a {@link Writable} signal with the given inital value
+ * A `Transformer` is a function that takes one stream and returns another,
+ * possibly one that produces data of a different type.  Most operator functions
+ * return a transformer, allowing them to be combined via {@link pipe}().
  *
- * @category Signals
+ * @category Types and Interfaces
  */
-declare function value<T>(val?: T): Writable<T>;
+type Transformer<T, V = T> = (input: Stream<T>) => Source<V>;
 /**
- * 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!)
+ * Subscribe a sink to a stream, returning a nested job. (Shorthand for
+ * {@link getJob}().{@link Job.connect connect}(...).)
  *
- * @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.
+ * @param src An event source or signal
+ * @param sink A callback that will receive the events
+ * @param inlet Optional - a {@link throttle}() to control backpressure
  *
- * 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, it will revert to the supplied inital
- * value.
+ * @returns A job that can be aborted to end the subscription, and which will
+ * end naturally (with a void return or error) if the stream ends itself.
  *
- * @param source A {@link Source} providing data which will become this signal's value
- * @param initVal The value to use when the signal is unobserved or waiting for the
- * first item from the source.
+ * @category Stream Consumers
  */
-declare function cached<T>(source: Source<T>, initVal?: T): Signal<T>;
-declare function cached<T extends Signal<any>>(signal: T): T;
+declare function connect<T>(src: Stream<T>, sink: Sink<T>, inlet?: Throttle | Inlet): Connection;
 /**
- * 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.
+ * Create a backpressure controller for a stream.  Pass it to one or more
+ * sources you're connecting to, and if they support backpressure they'll
+ * respond when you call its .pause() and .resume() methods.
  *
- * @returns The result of calling `fn(..args)`
+ * @param job - Optional: a job that controls readiness.  (The throttle will
+ * pause indefinitely when the job ends.)  Defaults to the currently-active job,
+ * but unlike most such defaults, it won't throw if no job is active.
  *
- * @category Signals
+ * @category Stream Consumers
  */
-declare function noDeps<F extends PlainFunction>(fn: F, ...args: Parameters<F>): ReturnType<F>;
+declare function throttle(job?: Job): Throttle;
 /**
- * Arrange for the current signal or rule to recalculate on demand
+ * Pipe a stream (or anything else) through a series of single-argument
+ * functions/operators
  *
- * This lets you interop with systems that have a way to query a value and
- * subscribe to changes to it, but not directly produce a signal.  (Such as
- * querying the DOM state and using a MutationObserver.)
+ * e.g. the following creates a stream that outputs 4 and then 6:
  *
- * By calling this with a {@link Source} or {@link RecalcSource}, you arrange
- * for it to be subscribed, if and when the call occurs in a rule or a cached
- * function that's in use by a rule (directly or indirectly).  When the source
- * emits a value, the signal machinery will invalidate the caching of the
- * function or rule, forcing a recalculation and subsequent rule reruns, if
- * applicable.
- *
- * Note: you should generally only call the 1-argument version of this function
- * with "static" sources - i.e. ones that won't change on every call. Otherwise,
- * you will end up creating new signals each time, subscribing and unsubscribing
- * on every call to recalcWhen().
- *
- * If the source needs to reference some object, it's best to use the 2-argument
- * version (i.e. `changesWhen(someObj, factory)`, where `factory` is a function
- * that takes `someObj` and returns a suitable {@link RecalcSource}.)
- *
- * @remarks
- * recalcWhen is specifically designed so that using it does not pull in any
- * part of Uneventful's signals framework, in the event a program doesn't
- * already use it.  This means you can use it in library code to provide signal
- * compatibility, without adding bundle bloat to code that doesn't use signals.
- *
- * @category Signals
- */
-declare function recalcWhen(src: RecalcSource): void;
-/**
- * Two-argument variant of recalcWhen
- *
- * In certain circumstances, you may wish to use recalcWhen with a source
- * related to some object.  You could call recalcWhen with a closure, but that
- * would create and discard signals on every call.  So this 2-argument version
- * lets you avoid that by allowing the use of an arbitrary object as a key,
- * along with a factory function to turn the key into a {@link RecalcSource}.
- *
- * @param key an object to be used as a key
- *
- * @param factory a function that will be called with the key to obtain a
- * {@link RecalcSource}.  Note that this factory function must also be a static
- * function, not a closure, or the same memory thrash issue will occur.
- */
-declare function recalcWhen<T extends WeakKey>(key: T, factory: (key: T) => RecalcSource): void;
-
-/**
- * A backpressure controller: returns true if downstream is ready to accept
- * data.
- *
- * @param cb (optional) - a callback to run when the downstream consumer wishes
- * to resume event production (i.e., when a sink calls
- * {@link Throttle.resume}()).  The callback is automatically unregistered when
- * invoked, so the producer must re-register it after each call if it wishes to
- * keep being called.
- *
- * @category Types and Interfaces
- */
-type Backpressure = (cb?: () => any) => boolean;
-/**
- * Create a backpressure control function for the given connection
- *
- * @category Stream Producers
- */
-declare function backpressure(inlet?: Inlet): Backpressure;
-/**
- * Control backpressure for listening streams.  This interface is the API
- * internal to the implementation of {@link backpressure}().  Unless you're
- * implementing a backpressurable stream yourself, see the {@link Throttle}
- * interface instead.
- *
- * @category Types and Interfaces
- */
-interface Inlet {
-    /** Is the main connection open?  (i.e. is the creating job not closed yet?) */
-    isOpen(): boolean;
-    /** Is the conduit currently ready to receive data? */
-    isReady(): boolean;
-    /**
-     * Register a callback to produce more data when the inlet is resumed
-     * (The callback is unregistered if the supplied job ends.)
-     */
-    onReady(cb: () => any, job: Job): this;
-}
-/**
- * Control backpressure for listening streams
- *
- * Obtain instances via {@link throttle}(), then pass them into the appropriate
- * stream-consuming API.  (e.g. {@link connect}).
- *
- * @category Types and Interfaces
- */
-interface Throttle extends Inlet {
-    /** Set inlet status to "paused". */
-    pause(): void;
-    /**
-     * Un-pause, and iterate backpressure-able sources' onReady callbacks to
-     * resume sending immediately.  (i.e., synchronously!)
-     */
-    resume(): void;
-}
-/**
- * A Connection is a job that returns void when the connected stream ends
- * itself.  If the stream doesn't end itself (e.g. it's an event listener), the
- * job will never return, and only end with a cancel or throw.
- *
- * @category Types and Interfaces
- */
-type Connection = Job<void>;
-/**
- * A Producer is a function that can be called to arrange for data to be
- * produced and sent to a {@link Sink} function for consumption, until the
- * associated {@link Connection} is closed (either by the source or the sink,
- * e.g. if the sink doesn't want more data or the source has no more to send).
- *
- * If the source is a backpressurable stream, it can use the (optional) supplied
- * inlet (usually a {@link throttle}()) to rate-limit its output.
- *
- * A producer function *must* return the special {@link IsStream} value, so
- * TypeScript can tell what functions are usable as sources.  (Otherwise any
- * void function with no arguments would appear to be usable as a source!)
- *
- * @category Types and Interfaces
- */
-type Producer<T> = (sink: Sink<T>, conn?: Connection, inlet?: Throttle | Inlet) => typeof IsStream;
-/**
- * A Source is either a {@link Producer} or a {@link Signal}.  (Signals actually
- * implement the {@link Producer} interface as an overload, but TypeScript gets
- * confused about that sometimes, so we generally declare our stream *inputs* as
- * `Source<T>` and our stream *outputs* as {@link Producer}, so that TypeScript
- * knows what's what.
- *
- * @category Types and Interfaces
- */
-type Source<T> = Producer<T> | Signal<T> | Writable<T>;
-/**
- * A specially-typed string used to verify that a function supports uneventful's
- * streaming protocol.  Return it from a function to implement the
- * {@link Source} type.
- *
- * @category Types and Interfaces
- */
-declare const IsStream: "uneventful/is-stream";
-/**
- * A `Sink` is a function that receives data from a {@link Source}.
- *
- * @category Types and Interfaces
- */
-type Sink<T> = (val: T) => void;
-/**
- * A `Transformer` is a function that takes one source and returns another,
- * possibly one that produces data of a different type.  Most operator functions
- * return a transformer, allowing them to be combined via {@link pipe}().
- *
- * @category Types and Interfaces
- */
-type Transformer<T, V = T> = (input: Source<T>) => Producer<V>;
-/**
- * Subscribe a sink to a source, returning a nested job. (Shorthand for
- * {@link getJob}().{@link Job.connect connect}(...).)
- *
- * @param src An event source or finite data stream
- * @param sink A callback that will receive the events
- * @param inlet Optional - a {@link throttle}() to control backpressure
- *
- * @returns A job that can be aborted to end the subscription, and which will
- * end naturally (with a void return or error) if the stream ends itself.
- *
- * @category Stream Consumers
- */
-declare function connect<T>(src: Source<T>, sink: Sink<T>, inlet?: Throttle | Inlet): Connection;
-/**
- * Create a backpressure controller for a stream.  Pass it to one or more
- * sources you're connecting to, and if they support backpressure they'll
- * respond when you call its .pause() and .resume() methods.
- *
- * @param job - Optional: a job that controls readiness.  (The throttle will
- * pause indefinitely when the job ends.)  Defaults to the currently-active job,
- * but unlike most such defaults, it won't throw if no job is active.
- *
- * @category Stream Consumers
- */
-declare function throttle(job?: Job): Throttle;
-/**
- * Pipe a stream (or anything else) through a series of single-argument
- * functions/operators
- *
- * e.g. the following creates a stream that outputs 4 and then 6:
- *
- * ```ts
- * pipe(fromIterable([1,2,3,4]), skip(1), take(2), map(x => x*2))
- * ```
+ * ```ts
+ * pipe(fromIterable([1,2,3,4]), skip(1), take(2), map(x => x*2))
+ * ```
  *
  * The first argument to pipe() can be any value, but all other arguments must
  * be functions.  The value is passed to the first function, and then the result
@@ -875,8 +536,8 @@ type OptionalCleanup<T = any> = CleanupFn<T> | Nothing;
  */
 type AsyncStart<T, This = void> = (this: This, job: Job<T>) => StartObj<T>;
 /**
- * A synchronous start function returns void. It runs immediately and gets
- * passed the newly created job as its first argument.
+ * A synchronous start function returns void or a {@link CleanupFn}. It runs
+ * immediately and gets passed the newly created job as its first argument.
  *
  * @template T The type the job will end up returning
  * @template This The type of `this` the function accepts, if using two-argument
@@ -884,7 +545,7 @@ type AsyncStart<T, This = void> = (this: This, job: Job<T>) => StartObj<T>;
  *
  * @category Types and Interfaces
  */
-type SyncStart<T, This = void> = (this: This, job: Job<T>) => void;
+type SyncStart<T, This = void> = (this: This, job: Job<T>) => OptionalCleanup;
 /**
  * A synchronous or asynchronous initializing function for use with the
  * {@link start}() function or a job's {@link Job.start .start}() method.
@@ -969,7 +630,7 @@ interface Job<T = any> extends Yielding<T>, Promise<T> {
      * In order to ensure that all such "child" jobs, resources, and activities
      * are marked as canceled *before* any side effects (such as events,
      * callbacks or I/O operations) can occur, Uneventful prioritizes *all*
-     * release callbacks to run before *any* other callbacks of any kind.  since
+     * release callbacks to run before *any* other callbacks of any kind.  Since
      * release callbacks are used for child jobs, this means that the entire job
      * subtree is notified immediately of cancellation, before any other actions
      * are taken.  This ensures that no "stray" operations can continue, unaware
@@ -1013,15 +674,15 @@ interface Job<T = any> extends Yielding<T>, Promise<T> {
      * This is basically shorthand for `start<void>(job => void src(sink, job,
      * inlet))` -- i.e. a quick way to subscribe to a finite and/or pausable stream.
      *
-     * @param src An event source or finite data stream
-     * @param sink A callback that will receive the events
+     * @param src An event source or signal
+     * @param sink A callback that will receive the events or values
      * @param inlet Optional - a {@link throttle}() to control backpressure
      * @returns A job that can be aborted to end the subscription, and which will
      * end naturally (with a void return or error) if the stream ends itself.
      *
      * @category Execution Control
      */
-    connect<T>(src: Source<T>, sink: Sink<T>, inlet?: Throttle | Inlet): Connection;
+    connect<T>(src: Stream<T>, sink: Sink<T>, inlet?: Throttle | Inlet): Connection;
     /**
      * Invoke a function with this job as the active one, so that calling the
      * global {@link must} function will add cleanup callbacks to it,
@@ -1048,7 +709,7 @@ interface Job<T = any> extends Yielding<T>, Promise<T> {
      * though TypeScript will act as if they are present at compile time.  This
      * is because the only way to copy all overloads of a function signature is
      * to copy the exact type (as TypeScript has no way to generically say,
-     * "this a function with all the same overloads, but none of the
+     * "this is a function with all the same overloads, but none of the
      * properties").
      *
      * @category Execution Control
@@ -1214,192 +875,782 @@ interface Job<T = any> extends Yielding<T>, Promise<T> {
 /**
  * A pausable computation that ultimately produces a value of type T.
  *
- * An item of this type can be used to either create a job of type T, or awaited
- * in a job via `yield *` to obtain the value.
+ * An item of this type can be used to either create a job of type T, or awaited
+ * in a job via `yield *` to obtain the value.
+ *
+ * Any generator function that ultimately returns a value, implicitly returns a
+ * Yielding of that type, but it's best to *explicitly* declare this so that
+ * TypeScript can properly type check your yield expressions.  (e.g. `function
+ * *(): Yielding<number> {}` for a generator function that ultimately returns a
+ * number.)
+ *
+ * Generator functions implementing this type should only ever `yield *` to
+ * things that are of Yielding type, such as a {@link Job}, {@link to}() or
+ * other generators declared Yielding.
+ *
+ * @yields {@link Suspend}\<any>
+ * @returns T
+ *
+ *
+ * @category Types and Interfaces
+ */
+type Yielding<T> = {
+    /**
+     * An iterator suitable for use with `yield *` (in a job generator) to
+     * obtain a result.
+     *
+     * @category Obtaining Results
+     */
+    [Symbol.iterator](): JobIterator<T>;
+};
+/**
+ * An iterator yielding {@link Suspend} callbacks.  (An implementation detail of
+ * the {@link Yielding} type.)
+ *
+ * @category Types and Interfaces
+ */
+type JobIterator<T> = Generator<Suspend<any>, T, any>;
+/**
+ * An asynchronous operation that can be waited on by a {@link Job}.
+ *
+ * When a {@link JobIterator} yields a Suspend, the job invokes it with a
+ * {@link Request}.  The Suspend function should arrange for the request to be
+ * settled (via {@link resolve} or {@link reject}).
+ *
+ * Note: If the request is not settled, **the job will be suspended until
+ * cancelled by outside forces**.  (Such as its enclosing job ending, or
+ * explicit throw()/return() calls on the job instance.)
+ *
+ * Also note that any subjobs the Suspend function creates (or cleanup callbacks
+ * it registers) **will not be cleaned up until the *calling* job ends**.  So
+ * any resources that won't be needed once the job is resumed should be
+ * explicitly disposed of -- in which case you should probably just `yield *` to
+ * a {@link start}(), instead of yielding a Suspend!
+ *
+ * @category Types and Interfaces
+ */
+type Suspend<T> = (request: Request<T>) => void;
+/**
+ * A request for a value (or error) to be returned asynchronously.
+ *
+ * A request is like the inverse of a Promise: instead of waiting for it to
+ * settle, you settle it by passing it to {@link resolve}() or {@link reject}().
+ * Like a promise, it can only be settled once: resolving or rejecting it after
+ * it's already resolved or rejected has no effect.
+ *
+ * Settling a request will cause the requesting job (or other code) to resume
+ * immediately, running up to its next suspension or termination.  (Unless it's
+ * settled while the requesting job is already on the call stack, in which case
+ * the job will be resumed later.)
+ *
+ * (Note: do not call a Request directly, unless you want your code to maybe
+ * break in future.  Use resolve or reject (or {@link resolver}() or
+ * {@link rejecter}()), as 1) they'll shield you from future changes to this
+ * protocol and 2) they have better type checking anyway.)
+ *
+ * @category Types and Interfaces
+ */
+interface Request<T> {
+    (op: "next", val: T, err?: any): void;
+    (op: "throw", val: undefined | null, err: any): void;
+    (op: "next" | "throw", val?: T | undefined | null, err?: any): void;
+}
+/**
+ * A subscribable function used to trigger signal recalculations
+ *
+ * It must accept a callback, and should arrange (via {@link must}()) to
+ * unsubscribe when its calling job ends.  Once subscribed, it should
+ * invoke the callback to trigger recalculation of the signal(s) that
+ * were targeted via {@link recalcWhen}.
+ *
+ * @category Types and Interfaces
+ */
+type RecalcSource = ((cb: () => void) => unknown);
+
+/**
+ * Is the given value a function?
+ *
+ * @category Types and Interfaces
+ */
+declare function isFunction(f: any): f is Function;
+/**
+ * Return the currently-active Job, or throw an error if none is active.
+ *
+ * (You can check if a job is active first using {@link isJobActive}().)
+ *
+ * @category Jobs
+ */
+declare function getJob<T = unknown>(): Job<T>;
+/**
+ * Obtain a native promise for a job
+ *
+ * While jobs have the same interface as native promises, there are occasionally
+ * reasons to just use one directly.  (Like when Uneventful uses this function
+ * to implement jobs' promise methods!)
+ *
+ * @param job Optional: the job to get a native promise for.  If none is given,
+ * the active job is used.
+ *
+ * @returns A {@link Promise} that resolves or rejects according to whether the
+ * job returns or throws.  If the job is canceled, the promise is rejected with
+ * a {@link CancelError}.
+ *
+ * @category Jobs
+ */
+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.
+ *
+ * @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 linked/nested if any arguments are given,
+ * or a detached (parentless) job otherwise.
+ *
+ * @category Jobs
+ */
+declare const makeJob: <T, R = unknown>(parent?: Job<R>, stop?: CleanupFn<R>) => Job<T>;
+/**
+ * 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 in all cases, a child job of `detached` *must* be stopped
+ * explicitly, or it may "run" forever, never running its cleanup callbacks.)
+ *
+ * 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.)
+ *
+ * @category Jobs
+ */
+declare const detached: Job<unknown>;
+
+/**
+ * Convert a (possible) promise to something you can `yield *to()` in a job
+ *
+ * Much like `await valueOrPromiseLike` in an async function, using `yield
+ * *to(valueOrPromiseLike)` in a {@link Job}'s generator function will return
+ * the value or the result of the promise/promise-like object.
+ *
+ * @category Scheduling
+ */
+declare function to<T>(p: Promise<T> | PromiseLike<T> | T): Yielding<T>;
+/**
+ * Pause the job for the specified time in ms, e.g. `yield *sleep(1000)` to wait
+ * one second.
+ *
+ * @category Scheduling
+ */
+declare function sleep(ms: number): Yielding<void>;
+
+/**
+ * The result type returned from calls to {@link Each}.next()
+ *
+ * @category Types and Interfaces
+ */
+type EachResult<T> = {
+    /** The value provided by the source being iterated */
+    item: T;
+    /**
+     * A suspend callback that must be `yield`-ed before the next call to the
+     * iterator's .next() method. (That is, you must `yield next` it exactly once
+     * per loop pass.  See {@link each}() for more details.)
+     */
+    next: Suspend<void>;
+};
+/**
+ * The iterable returned by `yield *` {@link each}()
+ *
+ * @category Types and Interfaces
+ */
+type Each<T> = IterableIterator<EachResult<T>>;
+/**
+ * Asynchronously iterate over an event source
+ *
+ * Usage:
+ *
+ * ```ts
+ * for (const {item: event, next} of yield *each(mouseMove)) {
+ *     console.log(event.clientX, event.clientY);
+ *     yield next;  // required exactly once per iteration, even/w continue!
+ * }
+ * ```
+ *
+ * each(eventSource) yield-returns an iterator of `{item, next}` pairs.  The
+ * item is the data supplied by the event source, and `next` is a
+ * {@link Suspend}\<void\> that advances the iterator to the next item.  It
+ * *must* be yielded exactly once per loop iteration.  If you use `continue` to
+ * shortcut the loop body, you must `yield next` *before* doing so.
+ *
+ * The for-loop will end if the source ends, errors, or is canceled.  The source
+ * is paused while the loop body is running, and resumed when the `yield next`
+ * happens.  If events arrive anyway (e.g. because the source doesn't support
+ * pausing), they will be ignored unless you pipe the source through the
+ * {@link slack}() operator to provide a buffer. If the for-loop is exited
+ * early for any reason (or the iterator's `.return()` is called), the source is
+ * unsubscribed and the iteration ended.
+ *
+ * @category Stream Consumers
+ */
+declare function each<T>(src: Stream<T>): Yielding<Each<T>>;
+/**
+ * An object that can be waited on with `yield *until()`, by calling its
+ * "uneventful.until" method.  (This mostly exists to allow Signals to optimize
+ * their until() implementation, but is also open for extensions.)
+ *
+ * @category Types and Interfaces
+ */
+interface UntilMethod<T> {
+    /** Return an async op to resume once a truthy value is available */
+    "uneventful.until"(): Yielding<T>;
+}
+/**
+ * An object that can be waited on with `yield *next()`, by calling its
+ * "uneventful.next" method.  (This mostly exists to allow Signals to optimize
+ * their next() implementation, but is also open for extensions.)
+ *
+ * @category Types and Interfaces
+ */
+interface NextMethod<T> {
+    /** Return an async op to resume with the "next" (i.e. not current) value produced */
+    "uneventful.next"(): Yielding<T>;
+}
+/**
+ * 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>;
+/**
+ * Wait for and return the next value (or error) from a data source (when
+ * processed with `yield *` within a {@link Job}).
+ *
+ * This differs from {@link until}() in that it waits for the *next* value
+ * (truthy or not!), and it never resumes immediately for signals, but instead
+ * waits for the signal to *change*.  (Also, it does not support zero-argument
+ * functions, unless you wrap them with {@link cached}() first.)
+ *
+ * @param source The source to wait on, which can be:
+ * - An object with an `"uneventful.next"` method returning a {@link Yielding}
+ *   (in which case the result will be the the result of calling that method)
+ * - A {@link Signal} or {@link Source} (in which case the job resumes on the
+ *   next 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 Stream Consumers
+ * @category Scheduling
+ */
+declare function next<T>(source: NextMethod<T> | Stream<T>): Yielding<T>;
+/**
+ * Run a {@link restarting}() callback for each value produced by a source.
+ *
+ * With each event that occurs, any previous callback run is cleaned up before
+ * the new one begins.  (And the last run is cleaned up when the connection or
+ * job ends.)
+ *
+ * This function is almost the exact opposite of {@link each}(), in that the
+ * stream is never paused (unless you do so manually via a throttle or inlet),
+ * and if the "loop body" (callback job) is still running when a new value
+ * arrives, forEach() restarts the job instead of dropping the value.
+ *
+ * @param src An event source (i.e. a {@link Source} or {@link Signal})
+ * @param sink A callback that receives values from the source
+ * @param inlet An optional throttle or inlet that will be used to pause the
+ * source (if it's a signal or supports backpressure)
+ * @returns a {@link Connection} that can be used to detect the stream
+ * end/error, or ended to close it early.
+ *
+ * @category Stream Consumers
+ */
+declare function forEach<T>(src: Stream<T>, sink: Sink<T>, inlet?: Inlet): Connection;
+/**
+ * When called without a source, return a callback suitable for use w/{@link pipe}().
+ * e.g.:
+ *
+ * ```ts
+ * pipe(someSource, ..., forEach(v => { doSomething(v); }), optionalInlet));
+ * ```
+ *
+ */
+declare function forEach<T>(sink: Sink<T>, inlet?: Inlet): (src: Stream<T>) => Connection;
+
+/**
+ * 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;
+    /**
+     * Stop the currently-executing rule, or throw an error if no rule is
+     * currently running.
+     */
+    stop(): void;
+    /**
+     * Observe a condition and apply an action.
+     *
+     * This is roughly equivalent to `rule(() => { 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.
+     */
+    if(condition: () => any, action: () => OptionalCleanup): DisposeFn;
+    /**
+     * Decorate a method 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);
+     * ```
+     *
+     * 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: (cb: () => unknown) => unknown): RuleFactory;
+}
+/**
+ * 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 detached}.run to wrap the
+ * call to rule.
+ *
+ * @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.
  *
- * Any generator function that ultimately returns a value, implicitly returns a
- * Yielding of that type, but it's best to *explicitly* declare this so that
- * TypeScript can properly type check your yield expressions.  (e.g. `function
- * *(): Yielding<number> {}` for a generator function that ultimately returns a
- * number.)
+ * (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.)
  *
- * Generator functions implementing this type should only ever `yield *` to
- * things that are of Yielding type, such as a {@link Job}, {@link to}() or
- * other generators declared Yielding.
+ * 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.)
  *
- * @yields {@link Suspend}\<any>
- * @returns T
+ * @param scheduleFn The 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?: (cb: () => unknown) => unknown): void;
+
+/**
+ * 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 inidirectly.)
  *
- * @category Types and Interfaces
+ * @category Errors
  */
-type Yielding<T> = {
-    /**
-     * An iterator suitable for use with `yield *` (in a job generator) to
-     * obtain a result.
-     *
-     * @category Obtaining Results
-     */
-    [Symbol.iterator](): JobIterator<T>;
-};
+declare class WriteConflict extends Error {
+}
 /**
- * An iterator yielding {@link Suspend} callbacks.  (An implementation detail of
- * the {@link Yielding} type.)
+ * 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 Types and Interfaces
+ * @category Errors
  */
-type JobIterator<T> = Generator<Suspend<any>, T, any>;
+declare class CircularDependency extends Error {
+}
+
 /**
- * An asynchronous operation that can be waited on by a {@link Job}.
+ * An observable value, as a zero-argument callable with extra methods.
  *
- * When a {@link JobIterator} yields a Suspend, the job invokes it with a
- * {@link Request}.  The Suspend function should arrange for the request to be
- * settled (via {@link resolve} or {@link reject}).
+ * 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.
  *
- * Note: If the request is not settled, **the job will be suspended until
- * cancelled by outside forces**.  (Such as its enclosing job ending, or
- * explicit throw()/return() calls on the job instance.)
+ * 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.
  *
- * Also note that any subjobs the Suspend function creates (or cleanup callbacks
- * it registers) **will not be called until the *calling* job ends**.  So any
- * resources that won't be needed once the job is resumed should be explicitly
- * disposed of -- in which case you should probably just `yield *` to a
- * {@link start}(), instead of yielding a Suspend!
+ * 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
  */
-type Suspend<T> = (request: Request<T>) => void;
+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 request for a value (or error) to be returned asynchronously.
- *
- * A request is like the inverse of a Promise: instead of waiting for it to
- * settle, you settle it by passing it to {@link resolve}() or {@link reject}().
- * Like a promise, it can only be settled once: resolving or rejecting it after
- * it's already resolved or rejected has no effect.
- *
- * Settling a request will cause the requesting job (or other code) to resume
- * immediately, running up to its next suspension or termination.  (Unless it's
- * settled while the requesting job is already on the call stack, in which case
- * the job will be resumed later.)
- *
- * (Note: do not call a Request directly, unless you want your code to maybe
- * break in future.  Use resolve or reject (or {@link resolver}() or
- * {@link rejecter}()), as 1) they'll shield you from future changes to this
- * protocol and 2) they have better type checking anyway.)
+ * A {@link Signal} with a {@link Writable.set | .set()} method and writable
+ * {@link Writable.value | .value} property.
  *
  * @category Types and Interfaces
  */
-interface Request<T> {
-    (op: "next", val: T, err?: any): void;
-    (op: "throw", val: undefined | null, err: any): void;
-    (op: "next" | "throw", val?: T | undefined | null, err?: any): void;
+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 subscribable function used to trigger signal recalculations
+ * A writable signal that can be set to either a value or an expression.
  *
- * It must accept a callback, and should arrange (via {@link must}()) to
- * unsubscribe when its calling job ends.  Once subscribed, it should
- * invoke the callback to trigger recalculation of the signal(s) that
- * were targeted via {@link recalcWhen}.
+ * 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
  */
-type RecalcSource = ((cb: () => void) => unknown);
-
+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;
+}
 /**
- * Is the given value a function?
+ * Create a {@link Configurable} signal with the given inital value
  *
- * @category Types and Interfaces
+ * @category Signals
  */
-declare function isFunction(f: any): f is Function;
+declare function value<T>(val?: T): Configurable<T>;
 /**
- * Return the currently-active Job, or throw an error if none is active.
+ * Create a cached version of a function.  The returned callable is also a
+ * {@link Signal}.
  *
- * (You can check if a job is active first using {@link isJobActive}().)
+ * 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 Jobs
+ * @category Signals
  */
-declare function getJob<T = unknown>(): Job<T>;
+declare function cached<T>(compute: () => T): Signal<T>;
 /**
- * Obtain a native promise for a job
- *
- * While jobs have the same interface as native promises, there are occasionally
- * reasons to just use one directly.  (Like when Uneventful uses this function
- * to implement jobs' promise methods!)
+ * 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.
  *
- * @param job Optional: the job to get a native promise for.  If none is given,
- * the active job is used.
+ * 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.
  *
- * @returns A {@link Promise} that resolves or rejects according to whether the
- * job returns or throws.  If the job is canceled, the promise is rejected with
- * a {@link CancelError}.
+ * 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.)
  *
- * @category Jobs
+ * @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 nativePromise<T>(job?: Job<T>): Promise<T>;
+declare function cached<T>(source: Source<T>, defaultVal?: T): Signal<T>;
+declare function cached<T extends Signal<any>>(signal: T): T;
 /**
- * Return a new {@link Job}.  If *either* a parent parameter or stop function
- * are given, the new job is linked to the parent.
+ * Call a function without creating a dependency on any signals it reads.  (Like
+ * {@link Signal.peek}, but for any function with any arguments.)
  *
- * @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).
+ * You can also pass in any arguments the function takes, and the function's
+ * return value is returned.
  *
- * @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).
+ * (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 A new job.  The job is linked/nested if any arguments are given,
- * or a detached (parentless) job otherwise.
+ * @returns The result of calling `fn(..args)`
  *
- * @category Jobs
+ * @category Signals
  */
-declare const makeJob: <T, R = unknown>(parent?: Job<R>, stop?: CleanupFn<R>) => Job<T>;
+declare function peek<F extends PlainFunction>(fn: F, ...args: Parameters<F>): ReturnType<F>;
 /**
- * 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.
+ * Arrange for the current signal or rule to recalculate on demand
  *
- * (Note that in all cases, a child job of `detached` *must* be stopped
- * explicitly, or it may "run" forever, never running its cleanup callbacks.)
+ * This lets you interop with systems that have a way to query a value and
+ * subscribe to changes to it, but not directly produce a signal.  (Such as
+ * querying the DOM state and using a MutationObserver.)
  *
- * The detached job has a few special features and limitations:
+ * By calling this with a {@link Source} or {@link RecalcSource}, you arrange
+ * for it to be subscribed, if and when the call occurs in a rule or a cached
+ * function that's in use by a rule (directly or indirectly).  When the source
+ * emits a value, the signal machinery will invalidate the caching of the
+ * function or rule, forcing a recalculation and subsequent rule reruns, if
+ * applicable.
  *
- * - It can't be ended, thrown, return()ed, etc. -- you'll get an error
+ * Note: you should generally only call the 1-argument version of this function
+ * with "static" sources - i.e. ones that won't change on every call. Otherwise,
+ * you will end up creating new signals each time, subscribing and unsubscribing
+ * on every call to recalcWhen().
  *
- * - 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.
+ * If the source needs to reference some object, it's best to use the 2-argument
+ * version (i.e. `recalcWhen(someObj, factory)`, where `factory` is a function
+ * that takes `someObj` and returns a suitable {@link RecalcSource}.)
  *
- * - 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.)
+ * @remarks
+ * recalcWhen is specifically designed so that using it does not pull in any
+ * part of Uneventful's signals framework, in the event a program doesn't
+ * already use it.  This means you can use it in library code to provide signal
+ * compatibility, without adding bundle bloat to code that doesn't use signals.
  *
- * @category Jobs
+ * @category Signals
  */
-declare const detached: Job<unknown>;
-
+declare function recalcWhen(src: RecalcSource): void;
 /**
- * Convert a promise to something you can `yield *to()` in a job
+ * Two-argument variant of recalcWhen
  *
- * Much like `await valueOrPromiseLike` in an async function, using `yield
- * *to(valueOrPromiseLike)` in a {@link Job}'s generator function will return
- * the value or the result of the promise/promise-like object.
+ * In certain circumstances, you may wish to use recalcWhen with a source
+ * related to some object.  You could call recalcWhen with a closure, but that
+ * would create and discard signals on every call.  So this 2-argument version
+ * lets you avoid that by allowing the use of an arbitrary object as a key,
+ * along with a factory function to turn the key into a {@link RecalcSource}.
  *
- * @category Scheduling
+ * @param key an object to be used as a key
+ *
+ * @param factory a function that will be called with the key to obtain a
+ * {@link RecalcSource}.  (Note that this factory function must also be a static
+ * function, not a closure, or the same memory thrash issue will occur!)
  */
-declare function to<T>(p: Promise<T> | PromiseLike<T> | T): Yielding<T>;
+declare function recalcWhen<T extends WeakKey>(key: T, factory: (key: T) => RecalcSource): void;
 /**
- * Pause the job for the specified time in ms, e.g. `yield *sleep(1000)` to wait
- * one second.
+ * 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}().)
  *
- * @category Scheduling
+ * 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 sleep(ms: number): Yielding<void>;
+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;
 
 /**
  * A function that emits events, with a .source they're emitted from
@@ -1412,7 +1663,7 @@ interface Emitter<T> {
     /** Call the emitter to emit events on its .source */
     (val: T): void;
     /** An event source that receives the events */
-    source: Producer<T>;
+    source: Source<T>;
     /** Close all current subscribers' connections */
     end: () => void;
     /** Close all current subscribers' connections with an error */
@@ -1435,7 +1686,7 @@ declare function emitter<T>(): Emitter<T>;
  *
  * @category Stream Producers
  */
-declare function empty(): Producer<never>;
+declare function empty(): Source<never>;
 /**
  * Convert an async iterable to an event source
  *
@@ -1445,7 +1696,7 @@ declare function empty(): Producer<never>;
  *
  * @category Stream Producers
  */
-declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): Producer<T>;
+declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): Source<T>;
 /**
  * Create an event source from an element, window, or other event target
  *
@@ -1461,10 +1712,10 @@ declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): Producer<T>;
  *
  * @category Stream Producers
  */
-declare function fromDomEvent<T extends HTMLElement, K extends keyof HTMLElementEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Producer<HTMLElementEventMap[K]>;
-declare function fromDomEvent<T extends Window, K extends keyof WindowEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Producer<WindowEventMap[K]>;
-declare function fromDomEvent<T extends Document, K extends keyof DocumentEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Producer<DocumentEventMap[K]>;
-declare function fromDomEvent<T extends Event>(target: EventTarget, type: string, options?: boolean | AddEventListenerOptions): Producer<T>;
+declare function fromDomEvent<T extends HTMLElement, K extends keyof HTMLElementEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Source<HTMLElementEventMap[K]>;
+declare function fromDomEvent<T extends Window, K extends keyof WindowEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Source<WindowEventMap[K]>;
+declare function fromDomEvent<T extends Document, K extends keyof DocumentEventMap>(target: T, type: K, options?: boolean | AddEventListenerOptions): Source<DocumentEventMap[K]>;
+declare function fromDomEvent<T extends Event>(target: EventTarget, type: string, options?: boolean | AddEventListenerOptions): Source<T>;
 /**
  * Convert an iterable to a synchronous event source
  *
@@ -1474,7 +1725,7 @@ declare function fromDomEvent<T extends Event>(target: EventTarget, type: string
  *
  * @category Stream Producers
  */
-declare function fromIterable<T>(iterable: Iterable<T>): Producer<T>;
+declare function fromIterable<T>(iterable: Iterable<T>): Source<T>;
 /**
  * Convert a Promise to an event source
  *
@@ -1486,7 +1737,7 @@ declare function fromIterable<T>(iterable: Iterable<T>): Producer<T>;
  *
  * @category Stream Producers
  */
-declare function fromPromise<T>(promise: Promise<T> | PromiseLike<T> | T): Producer<T>;
+declare function fromPromise<T>(promise: Promise<T> | PromiseLike<T> | T): Source<T>;
 /**
  * Create an event source from an arbitrary subscribe/unsubscribe function
  *
@@ -1500,20 +1751,20 @@ declare function fromPromise<T>(promise: Promise<T> | PromiseLike<T> | T): Produ
  *
  * @category Stream Producers
  */
-declare function fromSubscribe<T>(subscribe: (cb: (val: T) => void) => DisposeFn): Producer<T>;
+declare function fromSubscribe<T>(subscribe: (cb: (val: T) => void) => DisposeFn): Source<T>;
 /**
  * Create a source that emits a single given value
  *
  * @category Stream Producers
  */
-declare function fromValue<T>(val: T): Producer<T>;
+declare function fromValue<T>(val: T): Source<T>;
 /**
  * Create an event source that issues a number every `ms` milliseconds (starting
  * with 0 after the first interval passes).
  *
  * @category Stream Producers
  */
-declare function interval(ms: number): Producer<number>;
+declare function interval(ms: number): Source<number>;
 /**
  * Create a dynamic source that is created each time it's subscribed
  *
@@ -1524,7 +1775,7 @@ declare function interval(ms: number): Producer<number>;
  *
  * @category Stream Producers
  */
-declare function lazy<T>(factory: () => Source<T>): Producer<T>;
+declare function lazy<T>(factory: () => Stream<T>): Source<T>;
 /**
  * An {@link Emitter} with a ready() method, that only supports a single active
  * subscriber.  (Useful for testing stream operators and sinks.)
@@ -1549,7 +1800,7 @@ declare function mockSource<T>(): MockSource<T>;
  *
  * @category Stream Producers
  */
-declare function never(): Producer<never>;
+declare function never(): Source<never>;
 /**
  * Wrap a source to allow multiple subscribers to the same underlying stream
  *
@@ -1571,7 +1822,7 @@ declare function never(): Producer<never>;
  *
  * @category Stream Operators
  */
-declare function share<T>(source: Source<T>): Producer<T>;
+declare function share<T>(source: Stream<T>): Source<T>;
 
 /**
  * Output multiple streams' contents in order (from an array/iterable of stream
@@ -1586,7 +1837,7 @@ declare function share<T>(source: Source<T>): Producer<T>;
  *
  * @category Stream Operators
  */
-declare function concat<T>(sources: Source<T>[] | Iterable<Source<T>>): Producer<T>;
+declare function concat<T>(sources: Stream<T>[] | Iterable<Stream<T>>): Source<T>;
 /**
  * Flatten a source of sources by emitting their contents in series
  *
@@ -1600,7 +1851,7 @@ declare function concat<T>(sources: Source<T>[] | Iterable<Source<T>>): Producer
  *
  * @category Stream Operators
  */
-declare function concatAll<T>(sources: Source<Source<T>>): Producer<T>;
+declare function concatAll<T>(sources: Stream<Stream<T>>): Source<T>;
 /**
  * Map each value of a stream to a substream, then concatenate the resulting
  * substreams
@@ -1612,7 +1863,7 @@ declare function concatAll<T>(sources: Source<Source<T>>): Producer<T>;
  *
  * @category Stream Operators
  */
-declare function concatMap<T, R>(mapper: (v: T, idx: number) => Source<R>): Transformer<T, R>;
+declare function concatMap<T, R>(mapper: (v: T, idx: number) => Stream<R>): Transformer<T, R>;
 /**
  * Create a subset of a stream, based on a filter function (like Array.filter)
  *
@@ -1645,7 +1896,7 @@ declare function map<T, R>(mapper: (v: T, idx: number) => R): Transformer<T, R>;
  *
  * @category Stream Operators
  */
-declare function merge<T>(sources: Source<T>[] | Iterable<Source<T>>): Producer<T>;
+declare function merge<T>(sources: Stream<T>[] | Iterable<Stream<T>>): Source<T>;
 /**
  * Create an event source by merging sources from a stream of event sources
  *
@@ -1654,7 +1905,7 @@ declare function merge<T>(sources: Source<T>[] | Iterable<Source<T>>): Producer<
  *
  * @category Stream Operators
  */
-declare function mergeAll<T>(sources: Source<Source<T>>): Producer<T>;
+declare function mergeAll<T>(sources: Stream<Stream<T>>): Source<T>;
 /**
  * Create an event source by merging sources created by mapping events to sources
  *
@@ -1665,7 +1916,7 @@ declare function mergeAll<T>(sources: Source<Source<T>>): Producer<T>;
  *
  * @category Stream Operators
  */
-declare function mergeMap<T, R>(mapper: (v: T, idx: number) => Source<R>): Transformer<T, R>;
+declare function mergeMap<T, R>(mapper: (v: T, idx: number) => Stream<R>): Transformer<T, R>;
 /**
  * Skip the first N items from a source
  *
@@ -1682,7 +1933,7 @@ declare function skip<T>(n: number): Transformer<T>;
  *
  * @category Stream Operators
  */
-declare function skipUntil<T>(notifier: Source<any>): Transformer<T>;
+declare function skipUntil<T>(notifier: Stream<any>): Transformer<T>;
 /**
  * Skip items from a stream until a given condition is false, then output all
  * remaining items.  The condition function is not called again once it returns
@@ -1724,7 +1975,7 @@ declare function slack<T>(size: number, dropped?: Sink<T>): Transformer<T>;
  *
  * @category Stream Operators
  */
-declare function switchAll<T>(sources: Source<Source<T>>): Producer<T>;
+declare function switchAll<T>(sources: Stream<Stream<T>>): Source<T>;
 /**
  * Map each value of a stream to a substream, then output the resulting
  * substreams until a new value arrives.
@@ -1736,7 +1987,7 @@ declare function switchAll<T>(sources: Source<Source<T>>): Producer<T>;
  *
  * @category Stream Operators
  */
-declare function switchMap<T, R>(mapper: (v: T, idx: number) => Source<R>): Transformer<T, R>;
+declare function switchMap<T, R>(mapper: (v: T, idx: number) => Stream<R>): Transformer<T, R>;
 /**
  * Take the first N items from a source
  *
@@ -1753,7 +2004,7 @@ declare function take<T>(n: number): Transformer<T>;
  *
  * @category Stream Operators
  */
-declare function takeUntil<T>(notifier: Source<any>): Transformer<T>;
+declare function takeUntil<T>(notifier: Stream<any>): Transformer<T>;
 /**
  * Take items from a stream until a given condition is false, then close the
  * output.  The condition function is not called again after it returns false.
@@ -1790,7 +2041,7 @@ declare function must<T>(cleanup?: OptionalCleanup<T>): Job<T>;
  *   generator or job), a promise, or void.  A returned iterator or promise will
  *   be treated as if the method was called with that to begin with; a returned
  *   job will be awaited and its result transferred to the new job
- *   asynchronously.
+ *   asynchronously.  A returned function will be added to the job via `must()`.
  *
  * - When called with one argument that's a {@link Yielding} iterator (such as a
  *   generator or an existing job): it's attached to the new job and executed
@@ -1812,7 +2063,7 @@ declare function must<T>(cleanup?: OptionalCleanup<T>): Job<T>;
  *   *(this) {...}));`) in order to correctly infer types inside a generator
  *   function.)
  *
- * In any of the above cases, if a supplied function throws an error when
+ * In any of the above cases, if a supplied function throws an error while
  * starting, the new job will be ended, and the error synchronously re-thrown.
  *
  * @returns the created {@link Job}
@@ -1891,5 +2142,68 @@ declare function abortSignal(job?: Job): AbortSignal;
  */
 declare function restarting<F extends AnyFunction>(task: F): F;
 declare function restarting(): (task: () => OptionalCleanup<never>) => void;
+/**
+ * Wrap an argument-taking function so it will run in (and returns) a new Job
+ * when called.
+ *
+ * This lets you avoid the common pattern of needing to write your functions or
+ * methods like this:
+ *
+ * ```ts
+ * function outer(arg1, arg2) {
+ *     return start(function*() {
+ *         // ...
+ *     })
+ * }
+ * ```
+ * and instead write them like this:
+ * ```ts
+ * const outer = task(function *(arg1, arg2) {
+ *     // ...
+ * });
+ * ```
+ * or this:
+ * ```ts
+ * class Something {
+ *     ⁣⁣@task  // auto-detects TC39 or legacy decorators
+ *     *someMethod(arg1): Yielding<SomeResultType> {
+ *         // ...
+ *     }
+ * }
+ * ```
+ *
+ * Important: if the wrapped function or method has overloads, the resulting
+ * function type will be based on the **last** overload, because TypeScript (at
+ * least as of 5.x) is still not very good at dealing with higher order
+ * generics, especially if overloads are involved.
+ *
+ * Also note that TypeScript doesn't allow decorators to change the calling
+ * signature or return type of a method, so even though the above method will
+ * return a {@link Job}, TypeScript will only see it as a {@link Yielding}.
+ *
+ * This is fine if all you're going to do is `yield *` it to wait for the
+ * result, but if you need to use any job-specific methods on it, you'll have to
+ * pass it through {@link start} to have TypeScript treat it as an actual job.
+ * (Luckily, start() has a fast path to return the original job if it's passed a
+ * job, so you won't actually create a new job by doing this.)
+ *
+ * @param fn The function to wrap. A function returning a generator or
+ * promise-like object (i.e., a {@link StartObj}).
+ *
+ * @returns A wrapped version of the function that passes through its arguments
+ * to the original function, while running it in a new job.  (The wrapper also
+ * returns the job.)
+ *
+ * @category Jobs
+ */
+declare function task<T, A extends any[], C>(fn: (this: C, ...args: A) => StartObj<T>): (this: C, ...args: A) => Job<T>;
+/** @hidden TC39 Decorator protocol */
+declare function task<T, A extends any[], C>(fn: (this: C, ...args: A) => StartObj<T>, ctx: {
+    kind: "method";
+}): (this: C, ...args: A) => Job<T>;
+/** @hidden Legacy Decorator protocol */
+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 { type AnyFunction, type AsyncStart, type Backpressure, CancelError, CancelResult, CircularDependency, type CleanupFn, type Connection, type DisposeFn, type Each, type EachResult, type Emitter, ErrorResult, type HandledError, type Inlet, IsStream, type Job, type JobIterator, type JobResult, type MockSource, type Nothing, type OptionalCleanup, type PlainFunction, type Producer, type RecalcSource, type Request, RuleScheduler, Signal, type Sink, type Source, type StartFn, type StartObj, type Suspend, type SyncStart, type Throttle, type Transformer, type UnhandledError, type UntilMethod, ValueResult, type Waitable, Writable, WriteConflict, type Yielding, abortSignal, backpressure, cached, compose, concat, concatAll, concatMap, connect, defer, detached, each, emitter, empty, filter, fromAsyncIterable, fromDomEvent, fromIterable, fromPromise, fromSubscribe, fromValue, fulfillPromise, getJob, getResult, interval, into, isCancel, isError, isFunction, isHandled, isJobActive, isUnhandled, isValue, lazy, makeJob, map, markHandled, merge, mergeAll, mergeMap, mockSource, must, nativePromise, never, noDeps, noop, pipe, propagateResult, recalcWhen, reject, rejecter, resolve, resolver, restarting, rule, runRules, share, skip, skipUntil, skipWhile, slack, sleep, start, switchAll, switchMap, take, takeUntil, takeWhile, throttle, timeout, to, until, value };
+export { type AnyFunction, type AsyncStart, type Backpressure, CancelError, CancelResult, CircularDependency, type CleanupFn, type Configurable, type Connection, type DisposeFn, type Each, type EachResult, type Emitter, ErrorResult, type GenericMethodDecorator, type HandledError, type Inlet, IsStream, type Job, type JobIterator, type JobResult, type MockSource, type NextMethod, type Nothing, type OptionalCleanup, type PlainFunction, type RecalcSource, type Request, type RuleFactory, type Signal, type SignalSource, type Sink, type Source, type StartFn, type StartObj, type Stream, type Suspend, type SyncStart, type Throttle, type Transformer, type UnhandledError, type UntilMethod, ValueResult, type Writable, WriteConflict, type Yielding, abortSignal, action, backpressure, cached, compose, concat, concatAll, concatMap, connect, defer, detached, each, emitter, empty, filter, forEach, fromAsyncIterable, fromDomEvent, fromIterable, fromPromise, fromSubscribe, fromValue, fulfillPromise, getJob, getResult, interval, into, isCancel, isError, isFunction, isHandled, isJobActive, isUnhandled, isValue, lazy, makeJob, map, markHandled, merge, mergeAll, mergeMap, mockSource, must, nativePromise, never, next, noop, peek, pipe, propagateResult, recalcWhen, reject, rejecter, resolve, resolver, restarting, rule, runRules, share, skip, skipUntil, skipWhile, slack, sleep, start, switchAll, switchMap, take, takeUntil, takeWhile, task, throttle, timeout, to, until, value };