@defold-typescript/types 0.46.0 → 0.48.0

package/hsm/index.d.ts

@@ -134,6 +134,21 @@ export interface AlwaysConfig<Ctx, To extends string = string> {
  * whose `when` is missing or passes is taken.
  */
 export type AlwaysSpec<Ctx, To extends string = string> = To | AlwaysConfig<Ctx, To> | RuleList<AlwaysConfig<Ctx, To>>;
+/**
+ * One entry of the list form of `after`: a `delay` and the `to` its timer leads to.
+ * @noSelf
+ */
+export interface AfterConfig<Ctx, To extends string = string> {
+    /**
+     * The delay in seconds of game time: a number, or a function of the context that returns one.
+     * A function is read once each time the state is entered, after its `enter` hook, and again on
+     * a hot reload, so the delay is fixed for that stay. A result that is not a non-negative number
+     * throws, naming the state.
+     */
+    readonly delay: number | ((ctx: Ctx) => number);
+    /** The full path of the state to move to when the delay has passed. */
+    readonly to: To;
+}
 /**
  * A state's rules by event `type`. Only the machine's event types are keys, and each rule's
  * `when` and `run` see the event variant its key names.
@@ -212,13 +227,17 @@ interface StateBase<Ctx, E extends EventObject, T, Self extends string, To exten
      */
     readonly on?: NoInfer<OnConfig<Ctx, E, To>>;
     /**
-     * Targets by delay in seconds of game time. The delay is counted by `update(dt)` while the
-     * state is active, from zero on each entry. One `update` call fires at most one timer, and
-     * none when an `update` hook moved the machine.
+     * Timers, in one of two forms: targets by delay in seconds of game time, such as
+     * `{ 2: "/idle" }`, or a list of `AfterConfig` entries, such as
+     * `[{ delay: (ctx) => ctx.patrolFor, to: "/rest" }]`, whose `delay` is a number or a function
+     * of the context. A delay function is read once each time the state is entered, after its
+     * `enter` hook, and again on a hot reload. The delay is counted by `update(dt)` while the state
+     * is active, from zero on each entry. One `update` call fires at most one timer, and none when
+     * an `update` hook moved the machine.
      */
     readonly after?: NoInfer<{
         readonly [seconds: number]: To;
-    }>;
+    } | readonly AfterConfig<Ctx, To>[]>;
     /**
      * Targets taken right after any move that leaves this state active; the first whose `when` is
      * missing or passes wins. It is checked after a move only: not after a rule with no `to`, and
@@ -296,12 +315,120 @@ export type MachineConfig<Ctx, E extends EventObject> = CompoundState<Ctx, E, un
         readonly [name: string]: StateConfig<Ctx, E>;
     };
 };
+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
  * when that call runs, and a mistake throws, naming the state path. With a key, a later
  * definition under it puts its states into the machine already built, so every running instance
  * sees the edit; without one, each call builds a separate machine.
+ *
+ * The root config may hold `privateCtx`, for a machine that keeps fields of its own, such as a
+ * counter, a heat level or a list it builds up. Every hook, `when`, `run`, `task` and `update`
+ * then sees those fields beside `Ctx`, while `start` takes only `Ctx` and the instance it returns
+ * shows only `Ctx` in its `ctx`. A machine without fields of its own leaves `privateCtx` out.
  */
-export declare function defineMachine<Ctx, E extends EventObject>(key?: string): <T>(config: RootState<Ctx, E, T>) => Machine<Ctx, E, TreePath<T>>;
+export declare function defineMachine<Ctx, E extends EventObject>(key?: string): <T, Priv extends object = never>(config: RootState<WithPrivate<Ctx, Priv>, E, T> & PrivateCtxConfig<Ctx, Priv>) => Machine<Ctx, E, TreePath<T>>;
+/**
+ * The optional key a `defineMachine` root config takes beside `initial` and `states`.
+ * @noSelf
+ */
+export interface PrivateCtxConfig<Ctx, Priv> {
+    /**
+     * Builds the fields only the machine uses. It runs once per `start`, before the root's `enter`
+     * hook, so every instance gets fresh fields of its own; a value written straight into the
+     * config would be one array or table shared by every instance. It receives the object passed
+     * to `start`, typed `Ctx`, so a private field can start from a field of `Ctx`:
+     * `privateCtx: (ctx: TurretOptions) => ({ heat: ctx.startHeat })`. Give `ctx` its type; without
+     * one TypeScript can type a hook before it knows the private fields, and that hook reports the
+     * field as missing.
+     *
+     * The fields are added to the object passed to `start`, which stays the instance's `ctx`, so
+     * restarting with `start(old.ctx)` keeps the public fields and builds the private ones fresh.
+     * A hot reload under the machine's key adds the fields a new factory introduces and leaves
+     * every field that already holds a value alone. A private field may not share a name with a
+     * field of `Ctx`.
+     *
+     * The fields are hidden from callers by type only. At run time `ctx` is one table, and hooks,
+     * `hsm-view` and a debugger see every field.
+     *
+     * There are two ways to type the fields.
+     *
+     * @example
+     * **Inferred.** For a few fields, write them inline and let TypeScript infer their types. Add
+     * `as` where the inferred type is wrong: an empty array is `never[]` until it reads
+     * `[] as Hash[]`, and a field holding one of several strings is any `string` until it reads
+     * `"cool" as "cool" | "hot"`.
+     *
+     * ```ts
+     * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+     *
+     * export const turret = defineMachine<{ readonly fireRate: number }, TurretEvent>("turret")({
+     *   privateCtx: () => ({ heat: 0, targets: [] as Hash[] }),
+     *   initial: "/idle",
+     *   states: {
+     *     idle: { on: { SPOTTED: "/firing" } },
+     *     firing: {
+     *       enter: (ctx) => {
+     *         ctx.heat += 1 / ctx.fireRate;
+     *       },
+     *       on: { LOST: "/idle" },
+     *     },
+     *   },
+     * });
+     *
+     * const gun = turret.start({ fireRate: 2 }); // gun.ctx shows fireRate only
+     * ```
+     *
+     * @example
+     * **A named type.** For more fields, or when a helper outside the config needs the whole
+     * context, declare the fields as an interface and make it the factory's return type. The
+     * fields need no `as`, a misspelled or unknown field is a compile error, and the whole context
+     * is `TurretOptions & TurretPrivate`. `satisfies TurretPrivate` does not do this: it checks the
+     * object but keeps its narrow types, so an empty array stays `never[]`.
+     *
+     * ```ts
+     * interface TurretOptions {
+     *   readonly fireRate: number;
+     * }
+     *
+     * interface TurretPrivate {
+     *   heat: number;
+     *   mode: "cool" | "hot";
+     * }
+     *
+     * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+     *
+     * const overheated = (ctx: TurretOptions & TurretPrivate) => ctx.heat > ctx.fireRate;
+     *
+     * export const turret = defineMachine<TurretOptions, TurretEvent>("turret")({
+     *   privateCtx: (): TurretPrivate => ({ heat: 0, mode: "cool" }),
+     *   initial: "/idle",
+     *   states: {
+     *     idle: { on: { SPOTTED: "/firing" } },
+     *     firing: {
+     *       enter: (ctx) => {
+     *         ctx.heat += 1 / ctx.fireRate;
+     *       },
+     *       always: { to: "/cooling", when: overheated },
+     *       on: { LOST: "/idle" },
+     *     },
+     *     cooling: {
+     *       enter: (ctx) => {
+     *         ctx.mode = "hot";
+     *       },
+     *       exit: (ctx) => {
+     *         ctx.heat = 0;
+     *         ctx.mode = "cool";
+     *       },
+     *       after: { 2: "/idle" },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    readonly privateCtx?: (ctx: Ctx) => Priv & {
+        readonly [K in keyof Ctx & keyof Priv]: never;
+    };
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {