@expressive/steps 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @expressive/steps
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Multi-step processes as Expressive Models. Extend `Steps` and every method is a step: a step schedules the next by calling it, fields carry data between them. `run()` takes the arguments, schedules, waits for the run with `await this`, and returns the result. Each step is atomic and registers its own reset, so a failure unwinds what committed. Runs repeat, queue and park on waits answered from outside; status is reactive on `this.then`.
+
+In-process only for now - no durable persistence.
+
+```bash
+npm install @expressive/steps @expressive/mvc
+```
+
+```ts
+import { Steps } from '@expressive/steps';
+
+class SubmitOrder extends Steps {
+  cart!: Cart;
+  charge?: Charge = undefined;
+  tracking = '';
+
+  async run() {
+    this.reserve();
+
+    await this;
+
+    return { orderId: this.charge!.id, tracking: this.tracking };
+  }
+
+  protected async reserve() {
+    const hold = await inventory.hold(this.cart.items);
+
+    this.then.on({ reset: () => inventory.release(hold) });
+    this.pay();
+  }
+
+  protected async pay() {
+    this.charge = await stripe.charge(this.cart.total);
+    this.then.on({ reset: () => stripe.refund(this.charge!.id) });
+
+    this.then(this.ship(this.charge.id), this.receipt(this.charge.receiptUrl));
+  }
+
+  protected async ship(chargeId: string) {
+    this.tracking = (await courier.book(this.cart, chargeId)).id;
+  }
+
+  protected async receipt(url: string) {
+    await mail.send(this.cart.email, url);
+  }
+}
+
+const order = SubmitOrder.new({ cart });
+
+order.then.status;                     // 'idle' - reactive, like any field
+const { orderId } = await order;       // runs run(), typed by its return
+```
+
+A failed `courier.book` unwinds newest first: `refund`, then `release`, then every taken-back step's fields restored.
+
+Reference: [docs/](docs/README.md), and the `steps` page of the Expressive skill ([skills/steps.md](../../skills/steps.md)).

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { Model } from "@expressive/mvc";
+
+//#region src/steps.d.ts
+declare namespace Steps {
+  type Status = 'idle' | 'running' | 'waiting' | 'stopped' | 'aborted' | 'failed';
+  /** What `run` returns - the run's result. */
+  type Result<T> = T extends {
+    run(...args: any[]): infer R;
+  } ? Awaited<R> : unknown;
+  /** A planned item: a step, a parallel group (`group`), or a wait (`answers`). */
+  interface Node {
+    id: string;
+    key: string;
+    /** Arguments - a duration wait's milliseconds. */
+    args: unknown[];
+    group?: Node[];
+    /** Keys of the steps which may answer this wait - none for a duration. */
+    answers?: string[];
+    /** Steps raced against the answers - cancelled once one answers. */
+    race?: Node;
+    /** Caught by `.catch()`: a step given the error (its key), `then` for a function, or `true` for none. */
+    rescue?: string | true;
+  }
+  /** What a step call inside a step returns - inert, not awaitable. */
+  type Token = Readonly<Node>;
+  interface Entry {
+    id: string;
+    key: string;
+    args: unknown[];
+    next: Node[];
+    /** Fields the step wrote, collections changed in place included. */
+    wrote: string[];
+    /** Handlers the step registered with `then.on()`, by outcome, in order: a step method given uncalled or steps called for one (by key), or `then` for a function. */
+    on?: { [K in keyof On]?: Node[] };
+    /** Taken back by an unwind - resets run, fields restored; `'failed'` when a handler threw. */
+    unwound?: true | 'failed';
+    /** Id of the wait this step answered. */
+    wake?: string;
+    /** How many times `then.retry()` replayed the step, when past its first run. */
+    retried?: number;
+    /** What the step threw - a caught failure, or one which kept its writes. */
+    error?: unknown;
+    /** Collections changed in a way no restore can undo - the unwind stops here. */
+    irreversible?: string[];
+    /** The step called `then.commit()` - not retried, restored or undone; the unwind stops here. */
+    committed?: true;
+    /** The unwind stopped at this entry; it and every entry before it stay applied. */
+    halted?: true;
+    /** An `end` the runtime added - the plan drained without one. */
+    implicit?: true;
+  }
+  interface Wait {
+    id: string;
+    /** Key of the step which opened the wait. */
+    step: string;
+    /** Arguments of the step which opened the wait. */
+    args: unknown[];
+    /** Keys of the steps which may answer it. */
+    answers: string[];
+    /** When a duration wait closes, in epoch milliseconds. */
+    until?: number;
+  }
+  /** A `then.on` handler: a function, given the error, or nothing on cancellation; or for a durable run, a step method uncalled - given the same - or steps called for it. */
+  type Handler = {
+    handler(reason?: unknown): unknown;
+  }['handler'] | Promise<void> | readonly Promise<void>[];
+  /** Handlers for the outcomes of a step's subtree - `this.then.on({ ... })`. */
+  interface On {
+    /** The step is taken back - a failure leaving its subtree, `abort()`, a lost race: reset its effects. Fields are restored after it. */
+    reset?: Handler;
+    /**
+     * A failure below, no `.catch` closer to it took it - for recovery. Returning recovers - the failed part
+     * of the subtree unwinds, the step's own effects stay, steps it schedules replace the rest; throwing
+     * passes it on.
+     */
+    catch?: Handler;
+    /**
+     * The subtree ended without completing, before `reset` - given the error of a failure no `catch`
+     * recovered; nothing for a cancellation (`abort()`, `stop()`, a lost race). `then.status` tells which.
+     */
+    abort?: Handler;
+    /** The subtree ended, any way - a finally over it, last. */
+    close?: Handler;
+  }
+  /** Why a run or subtree ended: `abort()`, or a lost race. */
+  type Aborted = InstanceType<typeof Steps.Aborted>;
+  /** Why a run or subtree ended: `stop()`. */
+  type Stopped = InstanceType<typeof Steps.Stopped>;
+  interface Snapshot {
+    status: Status;
+    active: string | undefined;
+    queue: unknown[][];
+    waiting: Wait[];
+    runs: number;
+    error: unknown;
+  }
+  interface Controller<T extends Model = Model> {
+    /**
+     * Inside a step: park this point in the plan for a duration - units summed. The next step in
+     * sequence runs once it passes.
+     */
+    <This>(this: This, duration: {
+      ms?: number;
+      sec?: number;
+      min?: number;
+      hr?: number;
+      day?: number;
+    }): Promise<void>;
+    /**
+     * Inside a step: call `each` per item - a function issuing a step, or a step itself -
+     * and run the tokens as one parallel group.
+     */
+    <I, This>(this: This, items: Iterable<I>, each: (item: I, index: number) => unknown): Promise<void>;
+    /**
+     * Inside a step: park this point in the plan until a call to one of these steps answers it - from
+     * outside, or from a step called beside them (see below). The next step in sequence runs once the
+     * answer, and all it schedules, is done.
+     */
+    <This>(this: This, ...steps: ((...args: any[]) => unknown)[]): Promise<void>;
+    /**
+     * Inside a step: run these tokens as one parallel group at this point in the plan.
+     * The next step in sequence runs once every member, and all it schedules, is done.
+     *
+     * Beside steps uncalled - `this.then(this.allow, this.deny, this.timeout(call))` - each called step
+     * is a racer, started when the plan reaches the wait. Once a call answers, the racers which did not
+     * make it lose: signals aborted, what they scheduled dropped, gates released; a step in flight
+     * settles, then each losing branch unwinds - resets run, fields restored. The winner keeps all it did.
+     */
+    <This>(this: This, ...steps: unknown[]): Promise<void>;
+    /** The instance this controller runs. */
+    readonly self: T;
+    readonly status: Steps.Status;
+    /** Key of a step in flight - the latest invoked, with a group in flight. */
+    readonly active: string | undefined;
+    /** Arguments of each `run()` waiting for the active run to finish. */
+    readonly queue: readonly unknown[][];
+    /** Open waits, oldest first. */
+    readonly waiting: readonly Steps.Wait[];
+    /** Runs finished - ended, failed, stopped or aborted. */
+    readonly runs: number;
+    readonly error: unknown;
+    /** A plain snapshot of status, active, queue, waiting, runs and error. */
+    get(): Steps.Snapshot;
+    /**
+     * End the run - inside a step, where the plan reaches it; from outside, now. Pending steps are
+     * discarded and steps in flight settle first; `run`, awaiting the plan, then returns the result.
+     */
+    end(): void;
+    /**
+     * Inside a step: a gate at this point in the plan - queue FIFO for one of `max` slots; what this
+     * step schedules after it runs holding the slot, until done. A function taking `$` - the instance's
+     * tracking proxy - is re-read when anything it read through `$` changes, other Models included; one
+     * taking nothing, when a slot frees and when the instance updates. `0` pauses. `key` shares the
+     * queue: an object across groups and instances, any other value across this instance. Default: the
+     * enclosing group's, else the instance's.
+     */
+    only(max: number | (($: T) => number), key?: unknown): void;
+    /**
+     * Halt, keeping what was done: discard pending steps and queued runs; in-flight steps settle and
+     * commit. `reason` - the `cause` of the `'Stopped'` error the run and queue reject with, and its
+     * message when a string.
+     */
+    stop(reason?: unknown): void;
+    /**
+     * Halt and unwind, as a failure would - status `'aborted'`; the run's resets run, newest first, and
+     * fields are restored. The run and queue reject with a `Steps.Aborted`, `reason` as for `stop`.
+     * A reset which throws fails the run: its error, given the `Steps.Aborted` as `cause`.
+     */
+    abort(reason?: unknown): void;
+    /** Inside a step: a point of no return - the step is not caught, restored or undone, and the unwind stops here. */
+    commit(): void;
+    /** Inside a step: handlers for the outcomes of this step and all it schedules, deepest step first. */
+    on(handlers: Steps.On): void;
+    /** Inside a `.catch` handler: restore the caught branch's fields now; writes after it stand. */
+    restore(): void;
+    /**
+     * Inside a step: its `AbortSignal` - aborted on `stop()` or `abort()`, an outside `end`, a failure
+     * elsewhere, a race lost, and once the step settles. A step rejecting with its reason is not a failure.
+     */
+    readonly signal: AbortSignal;
+    /** Inside a step: how many times `then.retry()` replayed it - 0 on a first run. In a handler, the failed one's. */
+    readonly retried: number;
+    /**
+     * Inside a `.catch` handler: schedule what the catch is attached to again - the failed step, or the
+     * whole group - with its recorded args, still caught by the same handler. The handler holds the policy:
+     * `if (this.then.retried >= 3) throw error; this.then.retry();`. Backoff belongs in the retried step.
+     */
+    retry(): void;
+  }
+  interface Thenable<T extends Model = Model> {
+    /** Idle, calls `run()` - rejecting if it takes arguments; then settles once the active run and every queued one have, with the last one's result. */
+    <R1 = Steps.Result<T>, R2 = never>(onfulfilled?: ((value: Steps.Result<T>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    then: Steps.Runner<T>;
+  }
+  /**
+   * The controller, and a thenable - so the instance with it as `then`. Awaiting it joins the
+   * active run; idle, it calls `run()`, or rejects if `run` takes arguments.
+   */
+  type Runner<T extends Model = Model> = Controller<T> & Thenable<T>;
+}
+/**
+ * A runnable Model: its methods are steps, `run()` starts a run and awaiting the instance joins
+ * it, resolving with what `run` returns. The members below are the contract - each optional.
+ */
+declare class Aborted extends Error {
+  name: string;
+}
+declare class Stopped extends Error {
+  name: string;
+}
+declare class Steps extends Model {
+  /** Why a run or subtree ended: `abort()`, or a lost race. */
+  static readonly Aborted: typeof Aborted;
+  /** Why a run or subtree ended: `stop()`. */
+  static readonly Stopped: typeof Stopped;
+  /** The controller - status, journal, queue, waits; awaiting the instance awaits it. */
+  readonly then: Steps.Runner<this>;
+  constructor(...args: Model.Args);
+  /**
+   * The entry, `async`: starts a run, or queues one while a run is active. Its return is the run's result.
+   * It takes arguments and calls steps; `await this` inside it waits for the run, then it returns.
+   */
+  run?(...args: any[]): Promise<unknown>;
+  /** Before each step, once per step. */
+  protected before?(step: string, args: unknown[]): void;
+  /** After each step commits, once per step. */
+  protected after?(step: string, entry: Steps.Entry): void;
+}
+//#endregion
+export { Steps };
+//# sourceMappingURL=index.d.ts.map