uneventful 0.0.4 → 0.0.6

package/dist/types-N2ua11te.d.ts

@@ -0,0 +1,966 @@
+/**
+ * Resolve a {@link Request} with a value.
+ *
+ * (For a curried version, see {@link resolver}.)
+ *
+ * @category Requests and Results
+ */
+declare function resolve<T>(request: Request<T>, val: T): void;
+/**
+ * Reject a {@link Request} with a reason.
+ *
+ * (For a curried version, see {@link rejecter}.)
+ *
+ * @category Requests and Results
+ */
+declare function reject(request: Request<any>, reason: any): void;
+/**
+ * Create a callback that will resolve the given {@link Request} with a value.
+ *
+ * @category Requests and Results
+ */
+declare function resolver<T>(request: Request<T>): (val: T) => void;
+/**
+ * Create a callback that will reject the given {@link Request} with a reason.
+ *
+ * @category Requests and Results
+ */
+declare function rejecter(request: Request<any>): (err: any) => void;
+/**
+ * A function that does nothing and returns void.
+ *
+ * @category Stream Consumers
+ */
+declare function noop(): void;
+/**
+ * An {@link ErrorResult} that hasn't yet been "handled" (by being passed to an
+ * error-specific handler, converted to a promise, given to {@link markHandled},
+ * etc.)
+ *
+ * @category Types and Interfaces
+ */
+type UnhandledError = {
+    op: "throw";
+    val: undefined;
+    err: any;
+};
+/**
+ * An {@link ErrorResult} that has been marked "handled" (by being passed to an
+ * error-specific handler, converted to a promise, given to {@link markHandled},
+ * etc.)
+ *
+ * @category Types and Interfaces
+ */
+type HandledError = {
+    op: "throw";
+    val: null;
+    err: any;
+};
+/**
+ * A result passed to a job's cleanup callbacks, or supplied by its
+ * .{@link Job.result result}() method.
+ *
+ * You can inspect a JobResult using functions like {@link isCancel}(),
+ * {@link isError}(), and {@link isValue}().  {@link getResult}() can be used to
+ * unwrap the value or throw the error.
+ *
+ * @category Types and Interfaces
+ */
+type JobResult<T> = ValueResult<T> | ErrorResult | CancelResult;
+/**
+ * A {@link JobResult} that indicates the job was canceled by its creator (via
+ * end() or restart()).
+ *
+ * @category Types and Interfaces
+ */
+type CancelResult = {
+    op: "cancel";
+    val: undefined;
+    err: undefined;
+};
+/**
+ * The {@link JobResult} used to indicate a canceled job.
+ *
+ * @category Requests and Results
+ */
+declare const CancelResult: Readonly<CancelResult>;
+/**
+ * A {@link JobResult} that indicates the job was ended via a return() value.
+ *
+ * @category Types and Interfaces
+ */
+type ValueResult<T> = {
+    op: "next";
+    val: T;
+    err: undefined;
+};
+/**
+ * Create a {@link ValueResult} from a value
+ *
+ * @category Requests and Results
+ */
+declare function ValueResult<T>(val: T): ValueResult<T>;
+/**
+ * A {@link JobResult} that indicates the job was ended via a throw() or other
+ * error.
+ *
+ * @category Types and Interfaces
+ */
+type ErrorResult = UnhandledError | HandledError;
+/**
+ * Create an {@link ErrorResult} from an error
+ *
+ * @category Requests and Results
+ */
+declare function ErrorResult(err: any): UnhandledError;
+/**
+ * Returns true if the given result is a {@link CancelResult}.
+ *
+ * @category Requests and Results
+ */
+declare function isCancel(res: JobResult<any> | undefined): res is CancelResult;
+/**
+ * Returns true if the given result is a {@link ValueResult}.
+ *
+ * @category Requests and Results
+ */
+declare function isValue<T>(res: JobResult<T> | undefined): res is ValueResult<T>;
+/**
+ * Returns true if the given result is a {@link ErrorResult}.
+ *
+ * @category Requests and Results
+ */
+declare function isError(res: JobResult<any> | undefined): res is ErrorResult;
+/**
+ * Returns true if the given result is an {@link UnhandledError}.
+ *
+ * @category Requests and Results
+ */
+declare function isUnhandled(res: JobResult<any> | undefined): res is UnhandledError;
+/**
+ * Returns true if the given result is a {@link HandledError} (an
+ * {@link ErrorResult} that has been touched by {@link markHandled}).
+ *
+ * @category Requests and Results
+ */
+declare function isHandled(res: JobResult<any> | undefined): res is HandledError;
+/**
+ * Return the error of an {@link ErrorResult} and mark it as handled. The
+ * {@link ErrorResult} is mutated in-place to become a {@link HandledError}.
+ *
+ * @category Requests and Results
+ */
+declare function markHandled(res: ErrorResult): any;
+/**
+ * Get the return value from a {@link JobResult}, throwing an appropriate error
+ * if the result isn't a {@link ValueResult}.
+ *
+ * @param res The job result you want to unwrap.  Must not be undefined!
+ *
+ * @returns The value if the result is a {@link ValueResult}, or a thrown error
+ * if it's an {@link ErrorResult}.  A {@link CancelError} is thrown if the job
+ * was canceled, or the error in the result is thrown.
+ *
+ * If the result is an error, it is marked as handled.
+ *
+ * @category Jobs
+ */
+declare function getResult<T>(res: JobResult<T>): T;
+/**
+ * Fulfill a Promise from a {@link JobResult}
+ *
+ * If the result is a {@link CancelResult}, the promise is rejected with a
+ * {@link CancelError}.  Otherwise it is resolved or rejected according to the
+ * state of the result.
+ *
+ * @param resolve A value-taking function (first arg to `new Promise` callback)
+ *
+ * @param reject An error-taking function (second arg to `new Promise` callback)
+ *
+ * @param res The job result you want to settle the promise with.  An error will
+ * be thrown if it's undefined.
+ *
+ * If the result is an error, it is marked as handled.
+ *
+ * @category Requests and Results
+ */
+declare function fulfillPromise<T>(resolve: (v: T) => void, reject: (e: any) => void, res: JobResult<T>): void;
+/**
+ * Propagate a {@link JobResult} to another job
+ *
+ * If the result is a {@link CancelResult}, the job will throw with a
+ * {@link CancelError}.  Otherwise it is resolved or rejected according to the
+ * state of the result.
+ *
+ * @param job The job to terminate.  If it's already ended, nothing changes: the
+ * result is not propagated and the error (if any) is not marked as handled.
+ *
+ * @param res The job result you want to settle the job with.  An error will be
+ * thrown if it's undefined.  If the result is an error, it is marked as
+ * handled.
+ *
+ * @category Requests and Results
+ */
+declare function propagateResult<T>(job: Job<T>, res: JobResult<T>): void;
+/**
+ * Error thrown when waiting for a result from a job that is canceled.
+ *
+ * If you `await`, `yield *`, `.then()`, `.catch()`, {@link getResult}() or
+ * otherwise wait on the result of a job that is canceled, this is the type
+ * of error you'll get.
+ *
+ * @category Errors
+ */
+declare class CancelError extends Error {
+}
+
+/**
+ * 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 connection 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 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).
+ *
+ * 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
+ */
+interface Source<T> {
+    /** Subscribe sink to receive values */
+    (sink: Sink<T>, conn?: Connection, inlet?: Throttle | Inlet): typeof IsStream;
+}
+/**
+ * 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 Types and Interfaces
+ */
+type Stream<T> = Source<T> | SignalSource<T>;
+/**
+ * The call signatures implemented by signals.  (They can be used as sources, or
+ * called with no arguments to return a value.)
+ *
+ * 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 Types and Interfaces
+*/
+type SignalSource<T> = Source<T> & {
+    /** A signal object can be called to get its current value */
+    (): 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 Stream}.
+ *
+ * @category Types and Interfaces
+ */
+type Sink<T> = (val: T) => void;
+/**
+ * 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 Types and Interfaces
+ */
+type Transformer<T, V = T> = (input: Stream<T>) => Source<V>;
+/**
+ * Subscribe a sink to a stream, returning a nested job. (Shorthand for
+ * .{@link Job.connect connect}(...) on the active job.)
+ *
+ * @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
+ *
+ * @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: Stream<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))
+ * ```
+ *
+ * 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
+ * is passed to the next function in turn, until all provided functions have
+ * been called with the result of the previous function.  The return value is
+ * the last result, or the original value if no functions were given.
+ *
+ * The underlying implementation of pipe() works with any number of arguments,
+ * but due to TypeScript limitations we only have typing defined for a max of 9
+ * functions (10 arguments total).  If you need more than 9 functions, you can
+ * stack some of them with {@link compose}(), e.g.:
+ *
+ * ```typescript
+ * pipe(
+ *     aStream,
+ *     compose(op1, op2, ...),
+ *     compose(op10, op11, ...),
+ *     compose(op19, ...),
+ *     ...
+ * )
+ * ```
+ *
+ * @category Stream Operators
+ */
+declare function pipe<A, B, C, D, E, F, G, H, I, J>(input: A, ...fns: Chain9<A, J, B, C, D, E, F, G, H, I>): J;
+declare function pipe<A, B, C, D, E, F, G, H, I>(input: A, ...fns: Chain8<A, I, B, C, D, E, F, G, H>): I;
+declare function pipe<A, B, C, D, E, F, G, H>(input: A, ...fns: Chain7<A, H, B, C, D, E, F, G>): H;
+declare function pipe<A, B, C, D, E, F, G>(input: A, ...fns: Chain6<A, G, B, C, D, E, F>): G;
+declare function pipe<A, B, C, D, E, F>(input: A, ...fns: Chain5<A, F, B, C, D, E>): F;
+declare function pipe<A, B, C, D, E>(input: A, ...fns: Chain4<A, E, B, C, D>): E;
+declare function pipe<A, B, C, D>(input: A, ...fns: Chain3<A, D, B, C>): D;
+declare function pipe<A, B, C>(input: A, ...fns: Chain2<A, C, B>): C;
+declare function pipe<A, B>(input: A, ...fns: Chain1<A, B>): B;
+declare function pipe<A>(input: A): A;
+declare function pipe(input: any, ...fns: Array<(v: any) => any>): any;
+/**
+ * Compose a series of single-argument functions/operators in application order.
+ * (This is basically a deferred version of {@link pipe}().)  For example:
+ *
+ * ```ts
+ * const func = compose(skip(1), take(2), map(x => x*2));
+ * const stream_4_6 = func(fromIterable([1,2,3,4])); // stream that outputs 4, 6
+ * ```
+ *
+ * As with `pipe()`, the declared typings only support composing up to 9
+ * functions at once; if you need more you'll need to nest calls to `compose()`
+ * (i.e. passing the result of a `compose()` as an argument to another
+ * `compose()` call.)
+ *
+ * @returns A function taking the same type as the first input function,
+ * returning the same type as the last input function.
+ *
+ * @category Stream Operators
+ */
+declare function compose<A, B, C, D, E, F, G, H, I, J>(...fns: Chain9<A, J, B, C, D, E, F, G, H, I>): (a: A) => J;
+declare function compose<A, B, C, D, E, F, G, H, I>(...fns: Chain8<A, I, B, C, D, E, F, G, H>): (a: A) => I;
+declare function compose<A, B, C, D, E, F, G, H>(...fns: Chain7<A, H, B, C, D, E, F, G>): (a: A) => H;
+declare function compose<A, B, C, D, E, F, G>(...fns: Chain6<A, G, B, C, D, E, F>): (a: A) => G;
+declare function compose<A, B, C, D, E, F>(...fns: Chain5<A, F, B, C, D, E>): (a: A) => F;
+declare function compose<A, B, C, D, E>(...fns: Chain4<A, E, B, C, D>): (a: A) => E;
+declare function compose<A, B, C, D>(...fns: Chain3<A, D, B, C>): (a: A) => D;
+declare function compose<A, B, C>(...fns: Chain2<A, C, B>): (a: A) => C;
+declare function compose<A, B>(...fns: Chain1<A, B>): (a: A) => B;
+declare function compose<A>(): (a: A) => A;
+type Chain1<A, R> = [(v: A) => R];
+type Chain2<A, R, B> = [...Chain1<A, B>, ...Chain1<B, R>];
+type Chain3<A, R, B, C> = [...Chain1<A, B>, ...Chain2<B, R, C>];
+type Chain4<A, R, B, C, D> = [...Chain1<A, B>, ...Chain3<B, R, C, D>];
+type Chain5<A, R, B, C, D, E> = [...Chain1<A, B>, ...Chain4<B, R, C, D, E>];
+type Chain6<A, R, B, C, D, E, F> = [...Chain1<A, B>, ...Chain5<B, R, C, D, E, F>];
+type Chain7<A, R, B, C, D, E, F, G> = [...Chain1<A, B>, ...Chain6<B, R, C, D, E, F, G>];
+type Chain8<A, R, B, C, D, E, F, G, H> = [...Chain1<A, B>, ...Chain7<B, R, C, D, E, F, G, H>];
+type Chain9<A, R, B, C, D, E, F, G, H, I> = [...Chain1<A, B>, ...Chain8<B, R, C, D, E, F, G, H, I>];
+/**
+ * Pass subscriber into a stream (or any arguments into any other function).
+ *
+ * This utility is mainly here for uses like:
+ *
+ * - `pipe(src, into(sink))`,
+ * - `pipe(src, into(sink, conn))`,
+ * - `pipe(src, into(restarting(sink)))`, etc.
+ *
+ * but can also be used for argument currying generally.
+ *
+ * @param args The arguments to pass to the stream (or other function)
+ *
+ * @returns a function that takes another function and calls it with the given args.
+ *
+ * @category Stream Consumers
+ */
+declare function into<In extends any[], Out>(...args: In): (src: (...args: In) => Out) => Out;
+
+/**
+ * An undefined or null value
+ *
+ * @category Types and Interfaces
+ */
+type Nothing = undefined | null | void;
+/**
+ * A function without a `this`
+ *
+ * @category Types and Interfaces
+ */
+type PlainFunction = (this: void, ...args: any[]) => any;
+/**
+ * Any function
+ *
+ * @category Types and Interfaces
+ */
+type AnyFunction = (...args: any[]) => any;
+/**
+ * A cleanup function is a callback invoked when a job is ended or restarted.
+ * It receives a result that indicates whether the job ended itself with a return
+ * value or error, or was canceled/restarted by its creator.
+ *
+ * @category Types and Interfaces
+ */
+type CleanupFn<T = unknown> = (res: JobResult<T>) => unknown;
+/**
+ * A function that can be called to dispose of something or unsubscribe
+ * something.  It's called without arguments and returns void.
+ *
+ * @category Types and Interfaces
+ */
+type DisposeFn = () => void;
+/**
+ * An optional cleanup parameter or return.
+ *
+ * @category Types and Interfaces
+ */
+type OptionalCleanup<T = unknown> = CleanupFn<T> | Nothing;
+/**
+ * An asynchronous start function is called immediately in the new job and must
+ * return a {@link StartObj}, such as a job, generator, or promise.  If a job or
+ * promise is returned, it will be awaited and its result used to asynchronously
+ * set the result of the returned job.
+ *
+ * If a generator is returned, it will be run asynchronously, in the context of
+ * the newly-started job.  Any result it returns or error it throws will be
+ * treated as the result of the job.  If the job is canceled, the iterator's
+ * `.return()` method will be called to abort it (thereby running any
+ * try-finally clauses in the generator), and the result of the call will be
+ * otherwise ignored.
+ *
+ * @template T The type the job will end up returning
+ * @template This The type of `this` the function accepts, if using two-argument
+ * start().  Defaults to void (for one-argument start()).
+ *
+ * @category Types and Interfaces
+ */
+type AsyncStart<T, This = void> = (this: This, job: Job<T>) => StartObj<T>;
+/**
+ * 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
+ * start().  Defaults to void (for one-argument start()).
+ *
+ * @category Types and Interfaces
+ */
+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.
+ *
+ * @template T The type the job will end up returning
+ * @template This The type of `this` the function accepts, if using two-argument
+ * start().  Defaults to void (for one-argument start()).
+ *
+ * @category Types and Interfaces
+ */
+type StartFn<T, This = void> = AsyncStart<T, This> | SyncStart<T, This>;
+/**
+ * An object that can be passed as a single argument to {@link start}() or a
+ * job's {@link Job.start .start}() method, such as a job, generator, or
+ * promise.
+ *
+ * @category Types and Interfaces
+ */
+type StartObj<T> = Yielding<T> | Promise<T> | PromiseLike<T>;
+/**
+ * A cancellable asynchronous operation with automatic resource cleanup.
+ *
+ * You can add cleanup callbacks to a job via {@link must}() or its
+ * .{@link must}() method.  When the job is ended or canceled, the callbacks
+ * are (synchronously) run in reverse order -- a bit like a delayed and
+ * distributed collection of `finally` blocks.
+ *
+ * Jobs implement the Promise interface (then, catch, and finally) so they can
+ * be passed to Promise-using APIs or awaited by async functions.  They also
+ * implement {@link Yielding}, so you can await their results from a
+ * {@link start}() using `yield *`.  They also have
+ * {@link Job.return \.return()} and {@link Job.throw \.throw()} methods so
+ * you can end a job with a result or error.
+ *
+ * Most jobs, however, are not intended to produce results, and are merely
+ * canceled (using {@link Job.end \.end()} or
+ * {@link Job.restart \.restart()}).
+ *
+ * Jobs can be created using {@link start}(), {@link detached}.start(), and
+ * {@link makeJob}().
+ *
+ * @category Types and Interfaces
+ */
+interface Job<T = any> extends Yielding<T>, Promise<T> {
+    /**
+     * The result of the job (canceled, returned value, or error), or
+     * undefined if the job isn't finished.
+     *
+     * @category Obtaining Results
+     */
+    result(): JobResult<T> | undefined;
+    /**
+     * Add a cleanup callback to be run when the job is ended or restarted.
+     * (Non-function values are ignored.)  If the job has already ended, the
+     * callback will be invoked asynchronously in the next microtask. Cleanup
+     * functions are run in LIFO order, after any {@link Job.release}()
+     * callbacks (including those of the job's children), but before any
+     * {@link Job.do}() callbacks are run for the same job.
+     *
+     * Generally speaking, this method is used within a job to arrange for used
+     * resources to be cleaned up or to undo other state that was only supposed
+     * to be active while the job was running.
+     *
+     * @category Resource Tracking
+     */
+    must(cleanup?: OptionalCleanup): this;
+    /**
+     * Create a mutual-cleanup link with a resource that might be stopped or
+     * terminated in some way before the job ends. (Like a child process, a
+     * server connection, etc.)
+     *
+     * If a job uses a lot of such resources, using {@link Job.must} callbacks
+     * to trigger each one would result in an ever growing number of callbacks
+     * (and uncollectable reference to the no-longer-usable resources).  So this
+     * method lets you *remove* a cleanup function when it's no longer needed:
+     * when the resource is closed or finished, invoking the callback returned
+     * by this method will remove the cleanup callback from the job, allowing
+     * the resource to be freed before the job ends, without accumulating an
+     * endless number of callbacks in the job.  (Uneventful also uses this
+     * mechanism internally to link child jobs to their parents.)
+     *
+     * 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 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
+     * that their job is canceled.
+     *
+     * This means, however, that release callbacks must do **only** simple
+     * actions that **can't** result in arbitrary code being synchronously run.
+     * (Some safe examples would be setting flags, cancelling event
+     * subscriptions, removing things from internal queues, etc.)  Synchronously
+     * triggering events or other callbacks, however, runs the risk of that code
+     * doing things it wouldn't have done if it knew its job were canceled.
+     *
+     * Note that if you still need such actions to happen, your release callback
+     * can always add a new {@link Job.must}() or {@link Job.do}() callback at
+     * that point, and the callback will then get done during a later phase of
+     * job cleanup, without losing the benefits of the mutual-cleanup process.
+     *
+     * @param cleanup A cleanup callback.  It will receive a {@link JobResult},
+     * and its return value is ignored.
+     *
+     * @returns A callback that should be used to remove the passed-in cleanup
+     * callback from the job, if the resource is disposed of before the job
+     * ends.
+     *
+     * @category Resource Tracking
+     */
+    release(cleanup: CleanupFn): DisposeFn;
+    /**
+     * Start a nested job using the given function (or {@link Yielding},
+     * promise, etc.). (Like {@link start}(), but using a specific job as the
+     * parent, rather than whatever job is active.  Zero, one, and two arguments
+     * are supported, just as with start().)
+     *
+     * @category Execution Control
+     */
+    start<T>(init?: StartFn<T> | StartObj<T>): Job<T>;
+    start<T, This>(thisArg: This, fn: StartFn<T, This>): Job<T>;
+    /**
+     * Start a nested job that will end when the given stream does
+     *
+     * 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 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: 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,
+     * {@link start} will create child jobs of it, etc.  (Note: signal
+     * dependency tracking is disabled for the duration of the call, as if it
+     * had been wrapped with {@link peek}().)
+     *
+     * @param fn The function to call
+     * @param args The arguments to call it with, if any
+     * @returns The result of calling fn(...args)
+     *
+     * @category Execution Control
+     */
+    run<F extends PlainFunction>(fn: F, ...args: Parameters<F>): ReturnType<F>;
+    /**
+     * Wrap a function so this job will be active when it's called.
+     *
+     * @param fn The function to wrap
+     *
+     * @returns A function with the same signature(s), but will have this job
+     * active when called.  (Note: signal dependency tracking will be disabled
+     * for the duration of the call, as if it had been wrapped with
+     * {@link peek}().)
+     *
+     * @remarks Note that if the supplied function has any custom properties,
+     * they will *not* be available on the returned function at runtime, even
+     * 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 is a function with all the same overloads, but none of the
+     * properties").
+     *
+     * @category Execution Control
+     */
+    bind<F extends (...args: any[]) => any>(fn: F): F;
+    /**
+     * Release all resources held by the job.
+     *
+     * Arrange for all cleanup functions and result consumers added to the job
+     * (via release, must, do, etc.) be called in the appropriate order.  When
+     * the call to end() returns, all child jobs will have been notified of
+     * their cancellation.  (But not all of their cleanups or result consumers
+     * may have run yet, in the event that another job's end() is in progress
+     * when this method is called.)
+     *
+     * If any callbacks throw exceptions, they're converted to unhandled promise
+     * rejections (so that all of them will be called, even if one throws an
+     * error).
+     *
+     * Note: this method is a bound function, so you can pass it as a callback
+     * to another job, event source, etc.
+     *
+     * @category Execution Control
+     */
+    readonly end: () => void;
+    /**
+     * Invoke a callback with the result of a job.  Similar to
+     * {@link Job.must}(), except that `do` callbacks run in FIFO order after
+     * all {@link Job.must}() and {@link Job.release}() callbacks are done for
+     * the same job.
+     *
+     * These callbacks are used internally to implement promises, and should
+     * generally be used when you want to perform actions based on the *result*
+     * of a job.  (Whereas {@link Job.must}() callbacks are intended to clean up
+     * resources used by the job itself, and {@link Job.release}() callbacks are
+     * used to notify other activities (such as child jobs) that they are being
+     * canceled.)
+     *
+     * @remarks The .{@link Job.onError onError}(),  .{@link Job.onError onValue}(),
+     * and .{@link Job.onError onCancel}() provide shortcuts for creating `do`
+     * callbacks that only run under specific end conditions.
+     *
+     * @category Obtaining Results
+     */
+    do(action: (res?: JobResult<T>) => unknown): this;
+    /**
+     * Invoke a callback if the job ends with an error.
+     *
+     * This is shorthand for a .{@link Job.do do}() callback that checks for an
+     * error and marks it handled, so it uses the same relative order and runs
+     * in the same group as other .do callbacks.
+     *
+     * @param cb A callback that will receive the error
+     *
+     * @category Obtaining Results
+     */
+    onError(cb: (err: any) => unknown): this;
+    /**
+     * Invoke a callback if the job ends with a return() value.
+     *
+     * This is shorthand for a .{@link Job.do do}() callback that checks for a
+     * value result, so it uses the same relative order and runs in the same
+     * group as other .do callbacks.
+     *
+     * @param cb A callback that will receive the value
+     *
+     * @category Obtaining Results
+     */
+    onValue(cb: (val: T) => unknown): this;
+    /**
+     * Invoke a callback if the job ends with an cancellation or
+     * .{@link Job.restart restart}().
+     *
+     * This is shorthand for a .{@link Job.do do}() callback that checks for an
+     * error and marks it handled, so it uses the same relative order and runs
+     * in the same group as other .do callbacks.
+     *
+     * @param cb A callback that will receive the error
+     *
+     * @category Obtaining Results
+     */
+    onCancel(cb: () => unknown): this;
+    /**
+     * Restart this job - works just like .{@link Job.end end}(), except that
+     * the job isn't ended, so cleanup callbacks can be added again and won't be
+     * invoked until the next restart or the job is ended.  Note that the job's
+     * startup code will *not* be rerun: this just runs an early cleanup and
+     * then "uncancels" the job, changing its {@link Job.result result}() from
+     * {@link CancelResult} back to undefined.  It's up to you to do any needed
+     * re-initialization.
+     *
+     * Unlinke .{@link Job.end end}(), restart() guarantees that *all* cleanups
+     * and result consumers for the target job will have completed running when
+     * it returns.
+     *
+     * @see The {@link restarting} wrapper can be used to make a function that
+     * runs over and over in the same job, restarting each time.
+     *
+     * @category Execution Control
+     */
+    restart(): this;
+    /**
+     * Informs a job of an unhandled error from one of its children.
+     *
+     * If the job has an .{@link Job.asyncCatch asyncCatch}() handler set, it
+     * will be called with the error, otherwise the job will end with the
+     * supplied error.  If the error then isn't handled by a listener on the
+     * job, the error will cascade to an asyncThrow on the job's parent, until
+     * the {@link detached} job and its asyncCatch handler is reached. (Which
+     * defaults to creating an unhandled promise rejection.)
+     *
+     * Note: application code should not normally need to call this method
+     * directly, as it's automatically invoked on a job's parent if the job
+     * fails with no error listeners.  (That is, if a job result isn't awaited
+     * by anything and has no onError handlers, and the job throws, then the
+     * error is automatically asyncThrow()n to the job's parent.)
+     *
+     * @param err The error thrown by the child job
+     *
+     * @category Handling Errors
+     */
+    asyncThrow(err: any): this;
+    /**
+     * Set up a callback to receive unhandled errors from child jobs.
+     *
+     * Setting an async-catch handler allows you to create robust parent jobs
+     * that log or report errors and restart either a single job or an entire
+     * group of them, in the event that a child job malfunctions in a way that's
+     * not caught elsewhere.
+     *
+     * @param handler Either an error-receiving callback, or null.  If null,
+     * asyncThrow()n errors for the job will be passed to the job's throw()
+     * method instead.  If a callback is given, it's called with `this` bound to
+     * the relevant job instance.
+     *
+     * @category Handling Errors
+     */
+    asyncCatch(handler: ((this: Job, err: any) => unknown) | null): this;
+    /**
+     * End the job with a thrown error, passing an {@link ErrorResult} to the
+     * cleanup callbacks.  (Throws an error if the job is already ended or is
+     * currently restarting.)  Provides the same execution and ordering
+     * guarantees as .{@link Job.end end}().
+     *
+     * Note: since this immediately ends the job with an error, it should only
+     * be called by the job when it is no longer able to continue.  If you want
+     * to notify a job about an error in a *different* job, you may want to use
+     * .{@link Job.asyncThrow asyncThrow}() instead.
+     *
+     * @category Producing Results
+     */
+    throw(err: any): this;
+    /**
+     * End the job with a return value, passing a {@link ValueResult} to the
+     * cleanup callbacks.  (Throws an error if the job is already ended or is
+     * currently restarting.)  Provides the same execution and ordering
+     * guarantees as .{@link Job.end end}().
+     *
+     * @category Producing Results
+     */
+    return(val: T): this;
+}
+/**
+ * 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.
+ *
+ * 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);
+
+export { type AnyFunction as A, type Backpressure as B, type CleanupFn as C, type DisposeFn as D, ErrorResult as E, backpressure as F, type Throttle as G, type HandledError as H, type Inlet as I, type Job as J, type Connection as K, type SignalSource as L, IsStream as M, type Nothing as N, type OptionalCleanup as O, type PlainFunction as P, connect as Q, type Request as R, type Source as S, type Transformer as T, type UnhandledError as U, ValueResult as V, throttle as W, pipe as X, type Yielding as Y, compose as Z, into as _, type Stream as a, type Sink as b, type StartFn as c, type StartObj as d, type AsyncStart as e, type SyncStart as f, type JobIterator as g, type Suspend as h, type RecalcSource as i, reject as j, resolver as k, rejecter as l, CancelResult as m, noop as n, type JobResult as o, isCancel as p, isValue as q, resolve as r, isError as s, isUnhandled as t, isHandled as u, markHandled as v, getResult as w, fulfillPromise as x, propagateResult as y, CancelError as z };