@defold-typescript/transpiler 0.46.0 → 0.48.0

package/dist/hsm/index.ts

@@ -168,6 +168,22 @@ export type AlwaysSpec<Ctx, To extends string = string> =
   | 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.
@@ -304,11 +320,15 @@ 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 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
@@ -415,6 +435,8 @@ interface Transition<Ctx, E extends EventObject> {
   readonly run: readonly MoveAction<Ctx, E>[];
 }
 
+type Delay<Ctx> = number | ((ctx: Ctx) => number);
+
 interface Compiled<Ctx, E extends EventObject> {
   count: number;
   readonly configs: StateConfig<Ctx, E>[];
@@ -431,6 +453,10 @@ interface Compiled<Ctx, E extends EventObject> {
   readonly transitions: Transition<Ctx, E>[][];
   readonly afterDelays: number[][];
   readonly afterTargets: number[][];
+  // Set only for a state whose after list holds a delay function: its entries in list order,
+  // for each instance to sort once the function is read.
+  readonly afterListDelays: (Delay<Ctx>[] | undefined)[];
+  readonly afterListTargets: (number[] | undefined)[];
   readonly always: Transition<Ctx, E>[][];
   readonly pathIndex: { [path: string]: number };
 }
@@ -763,6 +789,25 @@ function parseDelay(key: string | number): number {
   return delay;
 }
 
+// NaN fails the comparison, so it is rejected with the negative numbers.
+function checkDelay(path: string, delay: unknown, written: unknown): void {
+  if (typeof delay !== "number" || !(delay >= 0)) {
+    throw `hsm: state "${describePath(path)}" has an after delay "${written}" that is not a non-negative number`;
+  }
+}
+
+// Keeps the delays ascending; timers with one delay stay in the order they were added.
+function insertTimer(delays: number[], targets: number[], delay: number, target: number): void {
+  let slot = delays.length;
+  while (slot > 0 && (delays[slot - 1] as number) > delay) {
+    delays[slot] = delays[slot - 1] as number;
+    targets[slot] = targets[slot - 1] as number;
+    slot--;
+  }
+  delays[slot] = delay;
+  targets[slot] = target;
+}
+
 function compileAfter<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, index: number): void {
   const delays: number[] = [];
   const targets: number[] = [];
@@ -773,20 +818,39 @@ function compileAfter<Ctx, E extends EventObject>(compiled: Compiled<Ctx, E>, in
     return;
   }
   const path = compiled.paths[index] as string;
-  for (const key in after) {
-    const delay = parseDelay(key);
-    if (!(delay >= 0)) {
-      throw `hsm: state "${describePath(path)}" has an after delay "${key}" that is not a non-negative number`;
+  // Read as an array type: the transpiler shifts an index to Lua's base 1 only on an array.
+  const list = after as readonly AfterConfig<Ctx>[];
+  if (typeof list[0] !== "object") {
+    const byDelay = after as { readonly [seconds: number]: string };
+    for (const key in byDelay) {
+      const delay = parseDelay(key);
+      checkDelay(path, delay, key);
+      const target = resolveTarget(compiled, index, byDelay[key as unknown as number] as string);
+      insertTimer(delays, targets, delay, target);
     }
-    const target = resolveTarget(compiled, index, after[key as unknown as number] as string);
-    let slot = delays.length;
-    while (slot > 0 && (delays[slot - 1] as number) > delay) {
-      delays[slot] = delays[slot - 1] as number;
-      targets[slot] = targets[slot - 1] as number;
-      slot--;
+    return;
+  }
+  const listDelays: Delay<Ctx>[] = [];
+  const listTargets: number[] = [];
+  let perInstance = false;
+  for (let i = 0; i < list.length; i++) {
+    const entry = list[i] as AfterConfig<Ctx>;
+    const delay = entry.delay;
+    if (typeof delay === "function") {
+      perInstance = true;
+    } else {
+      checkDelay(path, delay, delay);
     }
-    delays[slot] = delay;
-    targets[slot] = target;
+    listDelays[i] = delay;
+    listTargets[i] = resolveTarget(compiled, index, entry.to);
+  }
+  if (perInstance) {
+    compiled.afterListDelays[index] = listDelays;
+    compiled.afterListTargets[index] = listTargets;
+    return;
+  }
+  for (let i = 0; i < listDelays.length; i++) {
+    insertTimer(delays, targets, listDelays[i] as number, listTargets[i] as number);
   }
 }
 
@@ -807,6 +871,8 @@ function compile<Ctx, E extends EventObject>(config: MachineConfig<Ctx, E>): Com
     transitions: [],
     afterDelays: [],
     afterTargets: [],
+    afterListDelays: [],
+    afterListTargets: [],
     always: [],
     pathIndex: {},
   };
@@ -865,6 +931,23 @@ interface Registered<Ctx, E extends EventObject> {
 
 const registered: { [key: string]: Registered<unknown, EventObject> } = {};
 
+// Adds the fields the root's privateCtx returns to ctx; the factory receives target. With
+// onlyMissing, a field ctx already has keeps its value: a hot reload adds new private fields and
+// leaves the old ones alone.
+function fillPrivate(
+  target: { [name: string]: unknown },
+  root: unknown,
+  onlyMissing: boolean,
+): void {
+  const factory = (root as PrivateCtxConfig<unknown, object>).privateCtx;
+  const fields = (factory?.(target) || {}) as { [name: string]: unknown };
+  for (const name in fields) {
+    if (!onlyMissing || target[name] === undefined) {
+      target[name] = fields[name];
+    }
+  }
+}
+
 function createMachine<Ctx, E extends EventObject>(
   definition: Definition<Ctx, E>,
 ): Machine<Ctx, E> {
@@ -883,11 +966,16 @@ function createMachine<Ctx, E extends EventObject>(
     let transitions = compiled.transitions;
     let afterDelays = compiled.afterDelays;
     let afterTargets = compiled.afterTargets;
+    let afterListDelays = compiled.afterListDelays;
+    let afterListTargets = compiled.afterListTargets;
     let always = compiled.always;
     const activeChild: number[] = [];
     const isActive: boolean[] = [];
     const elapsed: number[] = [];
     const fired: number[] = [];
+    // The sorted timers of a state whose after list holds a delay function, read on each entry.
+    const ownDelays: (number[] | undefined)[] = [];
+    const ownTargets: (number[] | undefined)[] = [];
     const entryId: number[] = [];
     const cleanup: ((() => void) | undefined)[] = [];
     // Keyed by path, not index, so a remembered child outlives a rebind's recompilation.
@@ -921,10 +1009,32 @@ function createMachine<Ctx, E extends EventObject>(
       isActive[state] = false;
       elapsed[state] = 0;
       fired[state] = 0;
+      ownDelays[state] = undefined;
+      ownTargets[state] = undefined;
       entryId[state] = 0;
       cleanup[state] = undefined;
     }
 
+    function readDelays(state: number): void {
+      const list = afterListDelays[state];
+      if (list === undefined) {
+        return;
+      }
+      const listTargets = afterListTargets[state] as number[];
+      const delays: number[] = [];
+      const targets: number[] = [];
+      for (let i = 0; i < list.length; i++) {
+        let delay = list[i] as Delay<Ctx>;
+        if (typeof delay === "function") {
+          delay = delay(ctx);
+          checkDelay(paths[state] as string, delay, delay);
+        }
+        insertTimer(delays, targets, delay, listTargets[i] as number);
+      }
+      ownDelays[state] = delays;
+      ownTargets[state] = targets;
+    }
+
     function growSlots(): void {
       while (slotCount < compiled.count) {
         clearSlot(slotCount);
@@ -979,7 +1089,10 @@ function createMachine<Ctx, E extends EventObject>(
       transitions = compiled.transitions;
       afterDelays = compiled.afterDelays;
       afterTargets = compiled.afterTargets;
+      afterListDelays = compiled.afterListDelays;
+      afterListTargets = compiled.afterListTargets;
       always = compiled.always;
+      fillPrivate(ctx as never, configs[ROOT], true);
       growSlots();
       const dropped: number[] = [];
       for (let i = 0; i < order.length; i++) {
@@ -1002,6 +1115,7 @@ function createMachine<Ctx, E extends EventObject>(
         fired[state] = keptFired[i] as number;
         entryId[state] = keptEntryId[i] as number;
         cleanup[state] = keptCleanup[i];
+        readDelays(state);
       }
       for (let i = dropped.length - 1; i >= 0; i--) {
         const run = keptCleanup[dropped[i] as number];
@@ -1104,6 +1218,7 @@ function createMachine<Ctx, E extends EventObject>(
       if (hook !== undefined) {
         hook(ctx, instance);
       }
+      readDelays(state);
       const task = config.task;
       if (task !== undefined) {
         // A path, not an index, so a finish held across a rebind still finds its entry.
@@ -1501,17 +1616,12 @@ function createMachine<Ctx, E extends EventObject>(
       if (child !== NO_STATE && fireTimers(child)) {
         return true;
       }
-      const delays = afterDelays[state] as number[];
+      const delays = ownDelays[state] || (afterDelays[state] as number[]);
       const next = fired[state] as number;
       if (next < delays.length && (delays[next] as number) <= (elapsed[state] as number)) {
         fired[state] = next + 1;
-        transition(
-          state,
-          (afterTargets[state] as number[])[next] as number,
-          undefined,
-          undefined,
-          "after",
-        );
+        const targets = ownTargets[state] || (afterTargets[state] as number[]);
+        transition(state, targets[next] as number, undefined, undefined, "after");
         return true;
       }
       return false;
@@ -1553,6 +1663,7 @@ function createMachine<Ctx, E extends EventObject>(
     }
 
     busy = true;
+    fillPrivate(ctx as never, configs[ROOT], false);
     enterState(ROOT);
     enterDefaults(ROOT, 0);
     refreshLeaves();
@@ -1585,6 +1696,11 @@ function define<Ctx, E extends EventObject>(
   return machine;
 }
 
+// Ctx for a config without privateCtx, Ctx & Priv for one with it. The tuple test keeps the
+// context whole while Priv has no inference yet, so a generic helper in a slot, such as
+// `sequence`, still takes its ctx from the slot.
+type WithPrivate<Ctx, Priv> = [Priv] extends [never] ? Ctx : Ctx & Priv;
+
 // Ctx and E are given explicitly and the config is inferred, so the config takes a second call.
 // A key makes a later definition under it (a hot-reloaded module re-running) rebind live instances.
 /**
@@ -1593,9 +1709,117 @@ function define<Ctx, E extends EventObject>(
  * 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 function defineMachine<Ctx, E extends EventObject>(
   key?: string,
-): <T>(config: RootState<Ctx, E, T>) => Machine<Ctx, E, TreePath<T>> {
+): <T, Priv extends object = never>(
+  config: RootState<WithPrivate<Ctx, Priv>, E, T> & PrivateCtxConfig<Ctx, Priv>,
+) => Machine<Ctx, E, TreePath<T>> {
   return ((config: MachineConfig<Ctx, E>) => define(key, config)) as never;
 }
+
+/**
+ * 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 };
+}

package/dist/index.js

@@ -3666,6 +3666,7 @@ function transpileVirtual(files, companionEmit, overrides = {}) {
     sourceMap: true,
     lib: ["lib.es2022.d.ts"],
     skipLibCheck: true,
+    resolvePackageJsonImports: false,
     noImplicitSelf: true,
     luaPlugins: [
       { plugin: lifecycleErasurePlugin },
@@ -3745,6 +3746,7 @@ function compilerOptions(companionEmit) {
     sourceMap: true,
     lib: ["lib.es2022.d.ts"],
     skipLibCheck: true,
+    resolvePackageJsonImports: false,
     noImplicitSelf: true,
     luaPlugins: [
       { plugin: lifecycleErasurePlugin },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.46.0",
+    "@defold-typescript/types": "0.48.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript": "6.0.2",
     "typescript-to-lua": "^1.36.0"

package/src/session.ts

@@ -35,6 +35,13 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
     // Don't cross-check the seeded ambient .d.ts surface against itself; only user
     // files matter (mirrors transpileProject and the editor's skipLibCheck).
     skipLibCheck: true,
+    // TypeScript turns this on under its default `bundler` resolution. With it on,
+    // an error that has to name a module-declared type the file does not import
+    // (`Url`, `Hash`, `Vector3`) throws inside the checker, which builds a module
+    // specifier from an undefined base path and the virtual host's empty current
+    // directory. The virtual host reads every `package.json` as empty, so no `#`
+    // import resolves with the option on or off.
+    resolvePackageJsonImports: false,
     // Defold scripts are not OO: free helper functions never receive a context,
     // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
     noImplicitSelf: true,

package/src/transpile.ts

@@ -341,6 +341,13 @@ function transpileVirtual(
       // Don't cross-check the seeded ambient .d.ts surface against itself; we only
       // care about diagnostics on user files (mirrors the editor's skipLibCheck).
       skipLibCheck: true,
+      // TypeScript turns this on under its default `bundler` resolution. With it on,
+      // an error that has to name a module-declared type the file does not import
+      // (`Url`, `Hash`, `Vector3`) throws inside the checker, which builds a module
+      // specifier from an undefined base path and the virtual host's empty current
+      // directory. The virtual host reads every `package.json` as empty, so no `#`
+      // import resolves with the option on or off.
+      resolvePackageJsonImports: false,
       // Defold scripts are not OO: free helper functions never receive a context,
       // so suppress TSTL's implicit `self` parameter and the `_G` call-site filler.
       noImplicitSelf: true,