@menapo/machine 0.0.0-stage → 0.1.0

package/dist/machine-BstWHtWL.d.ts

@@ -0,0 +1,335 @@
+import { E as Payload, N as Unnamed, S as NamesOf, T as PathOf, _ as InstanceOf, b as MachineConfig, h as Implementations, i as AnyMachine, k as StartOptions, n as AnyEvent, r as AnyEvents, v as LeafOf, y as Machine } from "./types-Bk8svtO6.js";
+//#region src/core/store.d.ts
+/**
+ * Context, props and derived values share one shape: values in an array
+ * (`v`; a derived value's read bits and value, in pairs), the mask of
+ * changed fields and the instance.
+ */
+interface Store {
+  v: unknown[];
+  m: number;
+  /** The instance, for bindable props and derived values. */
+  readonly i: unknown;
+}
+type StoreClass = (new (values: unknown[], instance: unknown) => Store) & {
+  /** Context's only: the defaults with the fields `start` was given (`start(m, { context })`). */
+  s?(machine: {
+    readonly df?: readonly unknown[];
+    readonly nm: readonly string[];
+    readonly name: string;
+  }, given?: object): unknown[];
+};
+/**
+ * Context (`writable`) or props, over `this.v[k]`. Context is written by
+ * actions only (D5: anywhere else throws in dev); props are the owner's,
+ * and only bindable ones (which `bindable` redefines) can be written.
+ */
+declare function storeClass(names: readonly string[], first: number, writable: boolean): StoreClass;
+/**
+ * The derived values' class: each getter returns the cached value while no
+ * field it read has changed, else recomputes it with its reads recorded.
+ * A value computed while a field it read is changed but not yet told is
+ * recomputed on every read until the notification forgets it.
+ */
+declare function derivedClass(names: readonly string[], fns: readonly ((view: never) => unknown)[]): StoreClass;
+//#endregion
+//#region src/core/instance.d.ts
+type Owner = Readonly<Record<string, unknown>>;
+declare class Interpreter {
+  readonly M: Tables;
+  /** The active leaf; unset until started. */
+  s: State;
+  readonly context: Store;
+  readonly props: Store;
+  event: AnyEvent;
+  /**
+   * The last notification's change mask, for framework glue: bit 0 is the
+   * state, then one bit per context field and per prop, in declaration
+   * order (fields past the 31st share the last bit). Internal: `changed`
+   * names it. Set by the constructor.
+   */
+  mask: number;
+  /** IDLE, BUSY or STOPPED. */
+  b: number;
+  /** STATE_BIT once the state changed in this event. */
+  d: number;
+  /** Events sent while busy. */
+  q: AnyEvent[] | undefined;
+  l: ((instance: Interpreter) => void)[] | undefined;
+  /** What runs while a state is active: `[state, cleanup or timer, …]` (`effects.ts`). */
+  r: unknown[] | undefined;
+  /** States entered in this event whose timers and effects start once it settles. */
+  x: State[] | undefined;
+  /** The owner's props: the shared frozen empty object until an owner gives some (only read or replaced). */
+  o: Owner;
+  /** Owner props to take once the event being handled is done. */
+  n: Owner | undefined;
+  /** A move waiting for the owner (`bindable`): the rule's target and the event that asked. */
+  p: {
+    readonly to: State;
+    readonly event: AnyEvent;
+    readonly b?: unknown;
+  } | undefined;
+  /** `send` and `is`, bound on first use so they can be destructured. */
+  sf: ((event: string | AnyEvent, payload?: object) => void) | undefined;
+  wf: ((state: string) => boolean) | undefined;
+  /** Derived values and `done`, made on first read. */
+  dq: Store | undefined;
+  dn: Promise<void> | undefined;
+  constructor(machine: Tables, context?: object, owner?: Owner);
+  get state(): string;
+  get send(): (event: string | AnyEvent, payload?: object) => void;
+  get is(): (state: string) => boolean;
+  get derived(): Store;
+  /**
+   * Each part's id and element (`ids.content`, `el.content`): a component's
+   * (`parts/component.ts`). An instance `start` made renders nothing, so
+   * every part's id and element reads `undefined`, as the types say.
+   */
+  get ids(): object;
+  get el(): object;
+  get changed(): string[];
+  get done(): Promise<void>;
+  within(path: string): boolean;
+  /** Bits changed in the event being handled and not yet told. */
+  live(): number;
+  subscribe(listener: (instance: Interpreter) => void): () => void;
+  dispatch(event: string | AnyEvent, payload?: object): void;
+  /**
+   * Handles one thing from idle (an event's rules; else, before start, the
+   * initial state; else the owner props in `n`), then runs to completion.
+   * After a throw in user code the queue is dropped and the instance accepts
+   * events again.
+   */
+  go(rules: readonly Rule[] | undefined, event: AnyEvent): void;
+  /** Takes the first rule whose guard passes; true if one did and nothing waits for the owner. */
+  take(rules: readonly Rule[], event: AnyEvent): boolean;
+  /**
+   * Exits up to the nearest common ancestor strictly above the target, runs
+   * the rule's actions, enters down to the target's leaf. A target the
+   * machine is in is exited and entered again, so its timers restart.
+   */
+  move(to: State, actions: readonly Fn[] | undefined): void;
+  /** Enters every state below `from` down to `to`, outermost first; timers and effects start once the event settles. */
+  enter(from: State | undefined, to: State): void;
+  /** Stops what state `at` runs, latest first, then runs its exit actions. */
+  exit(at: State): void;
+  /**
+   * Sets the timers and starts the effects of states entered in this event
+   * that are still active. The glue's subclass defers it until the
+   * framework has committed the DOM, and never runs it on a server (D13).
+   */
+  activate(states: readonly State[]): void;
+  /**
+   * Runs to completion: `always` rules, queued events, owner props that
+   * arrived meanwhile and new states' effects, then one notification;
+   * again while listeners send.
+   */
+  settle(): void;
+  setProps(owner: Owner): void;
+  stop(): void;
+}
+/**
+ * Creates and starts an instance (PLAN §4.1, §4.8): enters the initial
+ * state, runs its entry actions, starts its effects and timers.
+ */
+declare const start: <M extends AnyMachine>(machine: M, options?: StartOptions<M>) => InstanceOf<M>;
+//#endregion
+//#region src/core/machine.d.ts
+/** A guard, action or effect as the interpreter calls it. */
+type Fn = (view: Interpreter) => unknown;
+type List = readonly Fn[] | undefined;
+/** A normalised transition: no target stays in the state and runs only the actions. */
+interface Rule {
+  readonly to: State | undefined;
+  readonly if: Fn | undefined;
+  readonly do: List;
+  /**
+   * Set by opt-in features on rules they route themselves (DevTools shows
+   * them): the history state a rule targets, or the rules a parallel
+   * machine's timer stands for.
+   */
+  readonly h?: State;
+  readonly w?: readonly Rule[];
+}
+/** What a state does with an event: the shared event object for sends without data, and the rules. */
+interface Handler {
+  /** The shared event object, for sends without data. */
+  readonly ev: AnyEvent;
+  readonly ru: readonly Rule[];
+}
+/**
+ * A state, normalised. Its keys are short because they ship in every
+ * bundle, the interpreter's and, for a compiled machine, its tables (PLAN
+ * §5.6): the minifier keeps property names.
+ */
+interface State {
+  /** Depth-first index; the machine's root is -1. */
+  readonly i: number;
+  readonly path: string;
+  /** The parent; the root has none. */
+  readonly up: State | undefined;
+  /** A top-level final state: the machine stops there and handles nothing. */
+  readonly fi: boolean;
+  /** The leaf entering this state settles in. */
+  lf: State;
+  /** Entry, exit and effect lists. */
+  en: List;
+  ex: List;
+  ef: List;
+  /** `after` timers: delay and rules. */
+  af: readonly (readonly [number, readonly Rule[]])[] | undefined;
+  /** Its eventless rules (`always`), then its ancestors'. */
+  al: readonly Rule[] | undefined;
+  /** D20: event name → what this state does with it, ancestors folded in. */
+  on: ReadonlyMap<string, Handler>;
+  /**
+   * Set only on a parallel configuration (`src/features/chart.ts`), which
+   * stands in for the leaf: every active state, in document order. Parts and
+   * DevTools read it; the core never needs it.
+   */
+  readonly a?: readonly State[];
+}
+/**
+ * What a state's `type` holds besides `"final"`: the marker of an opt-in
+ * feature (`parallel`, `history()`), which that feature's module reads. It
+ * carries the feature itself (`f`), which the normaliser calls when it meets
+ * the mark: importing a feature does nothing, so a bundle that re-exports
+ * every feature (a packed entry) still ships only the ones its machines mark.
+ */
+interface Mark {
+  readonly kind: "parallel" | "history";
+  readonly deep?: boolean;
+  readonly f: Feature;
+}
+/**
+ * The strategy `bindable` plugs in (D9). The core calls it only for a
+ * machine that declares a bindable prop, so apps that never import
+ * `bindable` do not ship controlled values.
+ */
+interface Control {
+  /** Records a bindable prop and defines its accessor on the props prototype. */
+  bind(machine: Tables, prop: number, name: string, bindable: object, proto: object): void;
+  /** The leaf to start in, given the owner's props. */
+  initial(instance: Interpreter, leaf: State): State;
+  /** True when `rule` would change a controlled value: its actions ran, the move waits for the owner. */
+  hold(instance: Interpreter, rule: Rule): boolean;
+  /** After a move from leaf `from`: tells the owner of uncontrolled values it changed. */
+  moved(instance: Interpreter, from: State): void;
+  /** After new owner props: moves the owner granted or made, and `changed` events. */
+  own(instance: Interpreter, previous: Readonly<Record<string, unknown>>): void;
+}
+/**
+ * The normalised machine: what `start` runs. Short keys, as {@link State}'s;
+ * a compiled machine leaves out the optional ones it does not use, which
+ * only the code of the features that use them reads.
+ */
+interface Tables {
+  /** Every state, depth first. */
+  readonly ss: readonly State[];
+  /** The leaf a started instance enters. */
+  readonly i0: State;
+  /** Context: the defaults, the store class. */
+  readonly df?: readonly unknown[];
+  readonly C?: StoreClass | undefined;
+  /** Props: names, defaults, the store class. */
+  readonly pn: readonly string[];
+  readonly pd?: unknown[];
+  readonly Q?: StoreClass | undefined;
+  /** The indices of props that are not bindable: owner props set them directly. */
+  readonly pl?: number[];
+  /** Context fields then props: bit `n + 1` belongs to `nm[n]`. */
+  readonly nm: readonly string[];
+  /** Derived values' store class. */
+  readonly D?: StoreClass | undefined;
+  /** `bindable`'s {@link Control}, when a prop is bindable. */
+  k: Control | undefined;
+  /** {@link Control}'s own records of the bindable props. */
+  readonly bd?: unknown[];
+  /** Dev only: the machine's name, for messages. */
+  readonly name: string;
+  /** Dev only: every event some state handles, for the unhandled-event warning. */
+  readonly handled: Set<string>;
+  /**
+   * The config as written (a compiled machine keeps `name`, `parts`,
+   * `expose` and its named implementations): `src/parts/` reads `parts`,
+   * `expose` and `name` from it when the glue renders the machine, and
+   * `provide` hands {@link r} a copy with its replacements.
+   */
+  readonly c: RawMachine;
+  /** Makes the tables again from a config: the normaliser, or a compiled machine's own maker (M7). */
+  readonly r: (config: RawMachine) => Tables;
+  /** What starts and stops states' timers and effects (`effects.ts`): set when a state has some. */
+  readonly A?: ((instance: Interpreter, states: readonly State[]) => void) | undefined;
+  readonly X?: ((instance: Interpreter, at?: State) => void) | undefined;
+  /** What takes the owner's props (`props.ts`): set when the machine declares props. */
+  readonly P?: ((instance: Interpreter, owner: Readonly<Record<string, unknown>>, queue?: boolean) => void) | undefined;
+}
+type Raw = Readonly<Record<string, unknown>>;
+/** A function, or the name of one in `actions`, `guards` or `effects` (D8). */
+type RawFn = Fn | string;
+type RawFns = RawFn | readonly RawFn[];
+type RawRule = {
+  readonly to?: string;
+  readonly if?: RawFn;
+  readonly do?: RawFns;
+};
+type RawTransitions = string | Fn | RawRule | readonly (string | Fn | RawRule)[];
+interface RawState {
+  readonly initial?: string;
+  readonly states?: Readonly<Record<string, RawState>>;
+  readonly on?: Readonly<Record<string, RawTransitions>>;
+  readonly entry?: RawFns;
+  readonly exit?: RawFns;
+  readonly effect?: RawFns;
+  readonly after?: Readonly<Record<string, RawTransitions>>;
+  readonly always?: RawTransitions;
+  readonly type?: "final" | Mark;
+  /** A parallel state's: taken once every region is in a final state. */
+  readonly done?: RawTransitions;
+}
+interface RawMachine extends RawState {
+  readonly name?: string;
+  readonly context?: Raw;
+  readonly props?: Raw;
+  readonly events?: Raw;
+  readonly derived?: Readonly<Record<string, Fn>>;
+  readonly actions?: Readonly<Record<string, Fn>>;
+  readonly guards?: Readonly<Record<string, Fn>>;
+  readonly effects?: Readonly<Record<string, Fn>>;
+  readonly parts?: Raw;
+  readonly expose?: Fn;
+}
+/** The normaliser's own target resolution, for features that normalise transitions of their own. */
+type Rules = (transitions: RawTransitions, from: State) => Rule[];
+/**
+ * What an opt-in feature does to a machine whose config marks it: adds to
+ * the tables once they are normalised, from the raw config, data only
+ * (fields on states and rules) so the plugin's compilation can emit it with
+ * the tables (M7); then, unless {@link wiring} is off, makes its runtime of
+ * them (selection rules, timers it routes), as a compiled machine does when
+ * it is loaded. Called for each state that carries its mark: it does its
+ * work on the first call.
+ */
+type Feature = (tables: Tables, raws: readonly RawState[], rules: Rules) => void;
+/**
+ * Defines a machine (PLAN §4.1): states, transitions, context, props and
+ * events in one object, normalised once into tables. Context, props,
+ * events, derived values, named implementations and the state tree are
+ * inferred from it.
+ */
+declare const defineMachine: <C extends object = {}, PC extends object = {}, E extends object = AnyEvents, DC extends object = {}, A extends object = Unnamed, G extends object = Unnamed, F extends object = Unnamed, S = unknown, const PS extends object = {}, X extends object = {}, PN extends string = never, Q = unknown>(config: MachineConfig<C, PC, E, DC, A, G, F, S, PS, X, PN, Q>) => Machine<C, PC, E, DC, PathOf<S, Q>, LeafOf<S, Q>, {
+  readonly actions: NamesOf<A>;
+  readonly guards: NamesOf<G>;
+  readonly effects: NamesOf<F>;
+}, PS, X>;
+/**
+ * The machine with some of its named `actions`, `guards` and `effects`
+ * replaced (D8), for tests or reuse; `machine` itself is unchanged. Each
+ * function is typed from the machine, as the ones it replaces.
+ */
+declare function provide<M extends AnyMachine>(machine: M, implementations: Implementations<M>): M;
+/** Declares an event's data in `events` (D7): `ADD: payload<{ by: number }>()`. */
+declare const payload: <T extends object>() => Payload<T>;
+//#endregion
+export { provide as a, derivedClass as c, payload as i, storeClass as l, Tables as n, Interpreter as o, defineMachine as r, start as s, State as t };