@defold-typescript/types 0.58.0 → 0.59.0

package/hsm/builder.d.ts

@@ -0,0 +1,194 @@
+// Generated from packages/hsm/src/builder.ts by `bun run --cwd packages/transpiler declarations`; do not edit.
+import { type AfterRule, type AlwaysConfig, type EventObject, type Machine, type MachineSkeleton, type MoveAction, type PrivateCtxConfig, type RunAction, type StateHook, type TaskStart, type TransitionConfig, type TreePath, type UnhandledHook, type UpdateHook, type WithPrivate } from "./index";
+type Delay<Ctx> = number | ((ctx: Readonly<Ctx>) => number);
+type EventGuard<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> = NonNullable<TransitionConfig<Ctx, E, V, P, Tag, P>["when"]>;
+type TimerGuard<Ctx, E extends EventObject, P extends string, Tag extends string> = NonNullable<AfterRule<Ctx, P, E, Tag, P>["when"]>;
+type AlwaysGuard<Ctx, E extends EventObject, P extends string, Tag extends string> = NonNullable<AlwaysConfig<Ctx, P, E, Tag, P>["when"]>;
+/**
+ * Adds behavior to a machine whose structure is a skeleton, returned by the second `buildMachine`
+ * call. `P` is the union of the skeleton's state paths, and every path a statement takes is one
+ * of them.
+ * @noSelf
+ */
+export interface MachineBuilder<Ctx, E extends EventObject, P extends string, Tag extends string = never, Priv = never> {
+    /**
+     * The builder of the state at the full path `path`, such as `/on/bright`. A path the skeleton
+     * lacks throws.
+     */
+    readonly state: (path: P) => StateBuilder<WithPrivate<Ctx, Priv>, E, P, Tag>;
+    /** The builder of the root, whose rules take an event no state below it takes. */
+    readonly root: StateBuilder<WithPrivate<Ctx, Priv>, E, P, Tag>;
+    /**
+     * Writes the statements onto the skeleton's own state objects, in list form, and passes the
+     * skeleton and the key to `defineMachine`, returning its machine. It throws, naming the state,
+     * on a rule left without its ending, and a second call throws.
+     */
+    readonly build: () => Machine<Ctx, E, P, Tag>;
+}
+/**
+ * Adds behavior to one state. Each `on`, `after`, `every` and `always` call adds one entry, in
+ * call order. A state's `on`, `every` and `always` entries are tried in that order, and its
+ * `after` timers in delay order, call order breaking ties. `enter`, `exit`, `update`, `task` and
+ * `unhandled` each take one function: a second call on the same state throws. Every call throws
+ * after `build()`.
+ * @noSelf
+ */
+export interface StateBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Adds a rule for events of type `type`, whose `when` and `run` see that variant. End it with
+     * `to`, `run` or `ignore`.
+     */
+    readonly on: <K extends E["type"]>(type: K) => EventRuleBuilder<Ctx, E, Extract<E, {
+        type: K;
+    }>, P, Tag>;
+    /**
+     * Adds a timer that fires once `delay` seconds of game time have passed in the state: a number,
+     * or a function of the context read each time the state is entered. A state's timers are tried
+     * in delay order, call order breaking ties. End it with `to` or `run`.
+     */
+    readonly after: (delay: Delay<Ctx>) => TimerRuleBuilder<Ctx, E, P, Tag>;
+    /**
+     * Adds functions run each time `delay` seconds of game time pass in the state: a number, or a
+     * function of the context read each time the state is entered. End it with `run`.
+     */
+    readonly every: (delay: Delay<Ctx>) => RunBuilder<Ctx, E, P, Tag>;
+    /** Adds a rule taken right after any move that leaves the state active. End it with `to`. */
+    readonly always: () => AlwaysRuleBuilder<Ctx, E, P, Tag>;
+    /** Sets the function run each time the state is entered. */
+    readonly enter: (hook: StateHook<Ctx, E, Tag, P>) => void;
+    /** Sets the function run each time the state is left. */
+    readonly exit: (hook: StateHook<Ctx, E, Tag, P>) => void;
+    /**
+     * Sets the function run on every `update(dt)` while the state is active, which returns a full
+     * path to move there, or `undefined` to stay.
+     */
+    readonly update: (hook: UpdateHook<Ctx, E, P, Tag, P>) => void;
+    /** Sets the work started on each entry; see `TaskStart`. */
+    readonly task: (start: TaskStart<Ctx, E, Tag, P>) => void;
+    /** Sets the function run when the machine drops an event while the state is active. */
+    readonly unhandled: (hook: UnhandledHook<Ctx, E, Tag, P>) => void;
+    /** Adds tag names that hold while the state is active, read with `hasTag`. */
+    readonly tags: (...names: Tag[]) => void;
+}
+/**
+ * The rule an `on` call added, before its ending. `build()` throws on a rule left without `to`,
+ * `run` or `ignore`.
+ * @noSelf
+ */
+export interface EventRuleBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /**
+     * Takes the rule only when `guard` returns `true`. It reads `ctx` and `event` and changes
+     * neither.
+     */
+    readonly when: (guard: EventGuard<Ctx, E, V, P, Tag>) => GuardedEventRuleBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => EventRunBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with functions run in order, with no move: no state exits or enters. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+    /**
+     * Ends the rule with nothing to do: the state takes the event, so it stops there and no rule
+     * of a parent sees it.
+     */
+    readonly ignore: () => void;
+}
+/**
+ * An `on` rule after its `when`, before its ending.
+ * @noSelf
+ */
+export interface GuardedEventRuleBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => EventRunBuilder<Ctx, E, V, P, Tag>;
+    /** Ends the rule with functions run in order, with no move: no state exits or enters. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+}
+/**
+ * An `on` rule after its `to`.
+ * @noSelf
+ */
+export interface EventRunBuilder<Ctx, E extends EventObject, V extends E, P extends string, Tag extends string> {
+    /** Adds functions run in order during the move, after the `exit` hooks and before `enter`. */
+    readonly run: (...actions: MoveAction<Ctx, E, V, Tag, P>[]) => void;
+}
+/**
+ * The timer an `after` call added, before its ending. `build()` throws on a timer left without
+ * `to` or `run`.
+ * @noSelf
+ */
+export interface TimerRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Fires the timer only when `guard` returns `true`, checked once the delay has passed and then
+     * on every `update` call until it passes. It reads `ctx` and changes nothing.
+     */
+    readonly when: (guard: TimerGuard<Ctx, E, P, Tag>) => GuardedTimerRuleBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with functions run in order when it fires, with no move. */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * An `after` timer after its `when`, before its ending.
+ * @noSelf
+ */
+export interface GuardedTimerRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Ends the timer with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+    /** Ends the timer with functions run in order when it fires, with no move. */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * An `every` entry, or an `after` timer or `always` rule after its `to`.
+ * @noSelf
+ */
+export interface RunBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /**
+     * Adds functions run in order: each time the delay passes for an `every` entry, and during the
+     * move for a timer or an `always` rule.
+     */
+    readonly run: (...actions: RunAction<Ctx, E, Tag, P>[]) => void;
+}
+/**
+ * The rule an `always` call added, before its `to`. `build()` throws on a rule left without one.
+ * @noSelf
+ */
+export interface AlwaysRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Takes the rule only when `guard` returns `true`. It reads `ctx` and changes nothing. */
+    readonly when: (guard: AlwaysGuard<Ctx, E, P, Tag>) => GuardedAlwaysRuleBuilder<Ctx, E, P, Tag>;
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+}
+/**
+ * An `always` rule after its `when`, before its `to`.
+ * @noSelf
+ */
+export interface GuardedAlwaysRuleBuilder<Ctx, E extends EventObject, P extends string, Tag extends string> {
+    /** Ends the rule with the full path of the state to move to. */
+    readonly to: (path: P) => RunBuilder<Ctx, E, P, Tag>;
+}
+/**
+ * Defines a machine as a skeleton plus statements, in three steps. `buildMachine<Ctx, E>()` fixes
+ * the context and event types and takes an optional hot reload key, as `defineMachine` does; a
+ * third type argument is the union of tag names. The second call takes the skeleton: the root's
+ * `initial` and `states`, an optional `privateCtx`, and on each state only `initial`, `states`,
+ * `type` and `restoreDepth`. It returns a `MachineBuilder`, whose `state(path)` and `root` add
+ * behavior one statement at a time, and whose `build()` defines the machine.
+ *
+ * @example
+ * ```ts
+ * type LampEvent = { type: "TOGGLE" } | { type: "DIM" };
+ *
+ * const m = buildMachine<object, LampEvent>("lamp")({
+ *   initial: "/off",
+ *   states: {
+ *     off: {},
+ *     on: { initial: "/on/bright", states: { bright: {}, dim: {} } },
+ *   },
+ * });
+ * m.state("/off").on("TOGGLE").to("/on");
+ * m.state("/on").on("TOGGLE").to("/off");
+ * m.state("/on/bright").on("DIM").to("/on/dim");
+ *
+ * export const lamp = m.build();
+ * ```
+ */
+export declare function buildMachine<Ctx, E extends EventObject, Tag extends string = never>(key?: string): <T, Priv extends object = never>(skeleton: MachineSkeleton<T> & PrivateCtxConfig<Ctx, Priv>) => MachineBuilder<Ctx, E, TreePath<T>, Tag, Priv>;
+export {};

package/hsm/index.d.ts

@@ -345,7 +345,12 @@ type NextCount = [never, 2, 3, 4, 5, 6];
 type TreePathsBelow<T, D extends number> = {
     [K in keyof T & string]: K | `${K}/${D extends 1 ? keyof T[K] extends never ? never : string : TreePathsBelow<T[K], PathDepth[D]>}`;
 }[keyof T & string];
-type TreePath<T> = `/${TreePathsBelow<T, 4>}`;
+/**
+ * The union of the state paths of the tree `T`, each with its leading `/`: `T` holds one key per
+ * state name, and a leaf is `unknown`. Paths are spelled out four levels deep; below that, any
+ * string under a fourth-level path is accepted.
+ */
+export type TreePath<T> = `/${TreePathsBelow<T, 4>}`;
 type TreeOf<C> = C extends {
     readonly states: infer Children;
 } ? {
@@ -515,7 +520,87 @@ export type MachineConfig<Ctx, E extends EventObject, Tag extends string = never
         readonly [name: string]: StateConfig<Ctx, E, Tag>;
     };
 };
-type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
+interface SkeletonBehavior {
+    /** Not taken in a skeleton: add tags with the state builder's `tags`. */
+    readonly tags?: never;
+    /** Not taken in a skeleton: add rules with the state builder's `on`. */
+    readonly on?: never;
+    /** Not taken in a skeleton: add timers with the state builder's `after`. */
+    readonly after?: never;
+    /** Not taken in a skeleton: add repeated runs with the state builder's `every`. */
+    readonly every?: never;
+    /** Not taken in a skeleton: add rules with the state builder's `always`. */
+    readonly always?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `enter`. */
+    readonly enter?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `exit`. */
+    readonly exit?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `update`. */
+    readonly update?: never;
+    /** Not taken in a skeleton: add the task with the state builder's `task`. */
+    readonly task?: never;
+    /** Not taken in a skeleton: add the hook with the state builder's `unhandled`. */
+    readonly unhandled?: never;
+}
+interface SkeletonState<T, Self extends string> extends SkeletonBehavior {
+    /** Child states, by name. A name is non-empty and contains no `/`. */
+    readonly states?: {
+        readonly [K in keyof T]: SkeletonNode<T[K], `${Self}/${K & string}`>;
+    };
+}
+interface CompoundSkeleton<T, Self extends string> extends SkeletonState<T, Self> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     */
+    readonly type?: never;
+    /**
+     * The full path of the child entered with this state, such as `/on/bright` inside `on`.
+     * Required when `states` is set, unless the state is parallel. Not taken on a leaf.
+     */
+    readonly initial?: NoInfer<unknown extends T ? never : `${Self}/${keyof T & string}`>;
+    /**
+     * Makes the state remember which child was active when it was last left, and enter it again
+     * instead of `initial`; see `restoreDepth` on a state config. Not taken on a leaf.
+     */
+    readonly restoreDepth?: NoInfer<unknown extends T ? never : TreeDepth<T, 4> | "all">;
+}
+interface ParallelSkeleton<T, Self extends string> extends SkeletonState<T, Self> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     */
+    readonly type: "parallel";
+    /** Not taken on a parallel state: every child is entered. */
+    readonly initial?: never;
+    /** Not taken on a parallel state: only a compound state resumes a child. */
+    readonly restoreDepth?: never;
+}
+type SkeletonNode<T, Self extends string> = CompoundSkeleton<T, Self> | ParallelSkeleton<T, Self>;
+/**
+ * The skeleton `buildMachine` takes: the structure of a machine with no behavior. The root holds
+ * `initial` and `states`, and each state only `initial`, `states`, `type` and `restoreDepth`, each
+ * checked as in a `defineMachine` config. `T` is the state tree read from the `states` keys, and
+ * fixes the paths every statement takes.
+ */
+export type MachineSkeleton<T> = SkeletonBehavior & {
+    /** The full path of the child entered at `start`, such as `/idle`. */
+    readonly initial: NoInfer<`/${keyof T & string}`>;
+    /** The machine's states, by name. A name is non-empty and contains no `/`. */
+    readonly states: {
+        readonly [K in keyof T]: SkeletonNode<T[K], `/${K & string}`>;
+    };
+    /** Not allowed on the root: put the regions in a child state. */
+    readonly type?: never;
+    /**
+     * Makes every state the count reaches remember its last child; see `restoreDepth` on a state
+     * config.
+     */
+    readonly restoreDepth?: NoInfer<TreeDepth<T, 4> | "all">;
+};
+/**
+ * The context a machine's hooks see: `Ctx` for a machine without `privateCtx`, and `Ctx & Priv`
+ * for one whose `privateCtx` returns `Priv`.
+ */
+export type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
 /**
  * Defines a machine in two calls: `defineMachine<Ctx, E>()` fixes the context and event types and
  * takes an optional hot-reload key, and the second call takes the config. The config is checked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,9 @@
     "./hsm/async": {
       "types": "./hsm/async.d.ts"
     },
+    "./hsm/builder": {
+      "types": "./hsm/builder.d.ts"
+    },
     "./hsm/debug": {
       "types": "./hsm/debug.d.ts"
     },