@defold-typescript/types 0.5.4 → 0.5.5

package/package.json

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

package/scripts/example-store-io.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { TranslationStore } from "../src/example-store";
+
+// Build-time only: lives under `scripts/` (never reachable from the shipped
+// `src/index.ts` graph) so its `node:fs` import cannot leak into a consumer's
+// typecheck. `src/example-store.ts` stays pure for exactly that reason.
+const TRANSLATIONS_PATH = resolve(import.meta.dir, "..", "examples", "translations.json");
+
+export function loadTranslations(path: string = TRANSLATIONS_PATH): TranslationStore {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return {};
+  }
+  return JSON.parse(raw) as TranslationStore;
+}

package/scripts/regen.ts

@@ -4,8 +4,10 @@ import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
 import { parseDefoldApiDoc } from "../src/api-doc";
 import { emitDeclarations } from "../src/emit-dts";
 import { emitBuiltinMessages, parseMessagesDoc } from "../src/emit-messages";
+import type { TranslationStore } from "../src/example-store";
 import { wrapAsAmbientGlobal } from "../src/publish-dts";
 import { type DownloadRefDoc, refDocCacheDir, resolveRefDoc } from "./doc-source";
+import { loadTranslations } from "./example-store-io";
 import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
 
 export interface ApiTargetModule {
@@ -159,6 +161,7 @@ export function collectConstantFqns(
 
 export interface GenerateOptions {
   knownConstantFqns?: ReadonlySet<string>;
+  translations?: TranslationStore;
 }
 
 export function generateModuleDeclaration(
@@ -178,7 +181,8 @@ export function generateModuleDeclaration(
     return true;
   });
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
-  const emitted = emitDeclarations(module, { knownConstantFqns });
+  const translations = options?.translations ?? loadTranslations();
+  const emitted = emitDeclarations(module, { knownConstantFqns, translations });
   const contents = wrapAsAmbientGlobal({
     namespace: module.namespace,
     emitted,

package/src/doc-comment.ts

@@ -73,6 +73,7 @@ export interface DocCommentParts {
   params?: { name: string; doc: string }[];
   returns?: string;
   example?: string;
+  exampleLang?: "lua" | "ts";
 }
 
 /**
@@ -115,7 +116,7 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   }
   if (example !== "") {
     lines.push(" * @example");
-    lines.push(" * ```lua");
+    lines.push(` * \`\`\`${parts.exampleLang ?? "lua"}`);
     for (const line of example.split("\n")) {
       lines.push(line === "" ? " *" : ` * ${line}`);
     }

package/src/emit-dts.ts

@@ -13,6 +13,8 @@ import {
   htmlToDocText,
   renderDocComment,
 } from "./doc-comment";
+import type { TranslationStore } from "./example-store";
+import { hashExampleSource, lookupTranslation } from "./example-store";
 
 export interface EmitOptions {
   mapType?: (defoldType: string) => string;
@@ -21,6 +23,12 @@ export interface EmitOptions {
   // brands to the same FQN-keyed type its owning module's `const` emits,
   // instead of widening to `unknown`.
   knownConstantFqns?: ReadonlySet<string>;
+  // Hand-authored TypeScript `@example` translations keyed by element FQN.
+  // Defaults to an empty store (every example stays on its Lua fallback,
+  // byte-identical output); the build layer (`regen`) passes the loaded
+  // `examples/translations.json`. Loading lives in `scripts/example-store-io.ts`
+  // so this module stays node-free for downstream consumers.
+  translations?: TranslationStore;
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -427,6 +435,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
 
   const constantFqns = new Set(module.constants.map((c) => c.name));
   const knownConstantFqns = options?.knownConstantFqns;
+  const translations = options?.translations ?? {};
   const baseMapType = options?.mapType ?? defaultMapType;
   const mapType = (token: string): string =>
     constantFqns.has(token) || knownConstantFqns?.has(token)
@@ -502,7 +511,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   for (const fn of functions) {
     const reserved = TS_RESERVED_NAMES.has(fn.name);
     const emitName = aliasName(fn.name, aliases);
-    for (const docLine of functionDocLines(fn.original)) lines.push(docLine);
+    for (const docLine of functionDocLines(fn.original, translations)) lines.push(docLine);
     const line = emitFunction(fn, emitName, mapType, resolver);
     lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
   }
@@ -614,18 +623,23 @@ function emitFunction(
 // fallback applies to non-identifier names, matching `emitParameter`) so the tag
 // resolves on hover; a single documented return becomes `@returns`. Returns `[]`
 // for a fully-undocumented function, leaving its emission byte-identical.
-function functionDocLines(fn: ApiFunction): string[] {
+function functionDocLines(fn: ApiFunction, translations: TranslationStore): string[] {
   const params = fn.parameters.map((p, index) => ({
     name: TS_IDENTIFIER.test(p.name) ? p.name : `arg${index}`,
     doc: htmlToDocText(p.doc),
   }));
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
-  const example = htmlToCodeText(fn.examples ?? "");
+  const lua = htmlToCodeText(fn.examples ?? "");
+  // A hand-authored TS translation pinned to this exact Lua flips the fence to
+  // ```ts; any hash mismatch (or absent translation) keeps the Lua fallback.
+  const ts = lua === "" ? null : lookupTranslation(translations, fn.name, hashExampleSource(lua));
+  const exampleParts: Pick<DocCommentParts, "example" | "exampleLang"> =
+    ts !== null ? { example: ts, exampleLang: "ts" } : lua !== "" ? { example: lua } : {};
   const parts: DocCommentParts = {
     summary: htmlToDocText(summaryFor(fn.brief, fn.description)),
     params,
     ...(onlyReturn ? { returns: htmlToDocText(onlyReturn.doc) } : {}),
-    ...(example !== "" ? { example } : {}),
+    ...exampleParts,
   };
   return indentDocLines(parts, INDENT);
 }
@@ -646,7 +660,7 @@ function indentDocLines(parts: DocCommentParts, indent: string): string[] {
 // Prefer the full `description`; fall back to the one-line `brief` when prose is
 // absent. Shared by every documented member kind so the summary source is
 // consistent across functions, constants, variables, and properties.
-function summaryFor(brief: string, description: string): string {
+export function summaryFor(brief: string, description: string): string {
   return description.trim() !== "" ? description : brief;
 }
 

package/src/example-store.ts

@@ -0,0 +1,44 @@
+// A hand-authored TypeScript translation of one element's ref-doc `@example`,
+// pinned by a hash of the exact source Lua it replaces. A ref-doc re-pin that
+// changes the source Lua flips the hash, so a stale translation stops matching
+// (drift guard) and the emit falls back to the Lua body.
+export interface Translation {
+  sourceHash: string;
+  ts: string;
+}
+
+export type TranslationStore = Record<string, Translation>;
+
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const U64_MASK = 0xffffffffffffffffn;
+
+// A pure, dependency-free FNV-1a 64-bit hash over the source's UTF-16 code
+// units, returned as zero-padded hex. Deliberately node- and Bun-free: this
+// module is reachable from `index.ts` (via `emit-dts`), so a `node:crypto` or
+// ambient-`Bun` reference here would fail type-checking in every downstream
+// consumer that compiles the shipped `src/` graph.
+//
+// The input is the already-normalized post-`htmlToCodeText` string (per-line
+// trailing whitespace and surrounding blank lines stripped), so the hash is
+// independent of trailing whitespace in the original ref-doc HTML.
+export function hashExampleSource(source: string): string {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < source.length; i++) {
+    hash = ((hash ^ BigInt(source.charCodeAt(i))) * FNV_PRIME) & U64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// Return the stored TypeScript body only when the FQN exists and its pinned
+// `sourceHash` matches the source we are about to emit; any mismatch returns
+// `null` so the caller keeps the Lua fallback.
+export function lookupTranslation(
+  store: TranslationStore,
+  fqn: string,
+  sourceHash: string,
+): string | null {
+  const entry = store[fqn];
+  if (!entry || entry.sourceHash !== sourceHash) return null;
+  return entry.ts;
+}

package/src/go-overloads.d.ts

@@ -9,6 +9,21 @@ declare global {
       keys?: Record<string | number, unknown>;
     }
 
+    /**
+     * gets a named property of the specified game object or component
+     *
+     * @param url - url of the game object or component having the property
+     * @param property - id of the property to retrieve
+     * @param options - optional options table
+     * - index number index into array property (1 based)
+     * - key hash name of internal property
+     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * @returns the value of the specified property
+     * @example
+     * ```ts
+     * const position = go.get("#sprite", "position");
+     * ```
+     */
     function get<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,
@@ -19,6 +34,21 @@ declare global {
       property: string | Hash,
       options?: GoPropertyOptions,
     ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">;
+    /**
+     * sets a named property of the specified game object or component, or a material constant
+     *
+     * @param url - url of the game object or component having the property
+     * @param property - id of the property to set
+     * @param value - the value to set
+     * @param options - optional options table
+     * - index integer index into array property (1 based)
+     * - key hash name of internal property
+     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * @example
+     * ```ts
+     * go.set("#sprite", "tint", vmath.vector4(1, 0, 0, 1));
+     * ```
+     */
     function set<K extends keyof go.properties>(
       url: string | Hash | Url,
       property: K,

package/src/message-dispatch.d.ts

@@ -10,6 +10,27 @@ declare global {
   // The transpiler lowers the call to a flat `message_id == hash("...")`
   // if/elseif chain (message-dispatch-lowering.ts), keeping this package free of
   // runtime Lua.
+  /**
+   * Discriminated-union dispatcher for `on_message`: takes a record of per-message
+   * handlers keyed by builtin message id, each receiving its `BuiltinMessages`
+   * payload already narrowed, and returns the `on_message` handler that routes to
+   * them. Reads as `on_message: onMessage<Self>({ ... })`; `self` threads via the
+   * explicit type argument, mirroring `defineScript<Self>`. The transpiler lowers
+   * it to a flat `if/elseif message_id == hash("...")` chain.
+   *
+   * @param handlers - a partial map from builtin message id to its handler; each handler's `message` is narrowed to that id's payload.
+   * @returns the `on_message` lifecycle handler that dispatches to the matching entry.
+   * @example
+   * ```ts
+   * defineScript({
+   *   on_message: onMessage({
+   *     contact_point_response(self, message, sender) {
+   *       print(message.other_group);
+   *     },
+   *   }),
+   * });
+   * ```
+   */
   function onMessage<TSelf = Record<never, never>>(
     handlers: Partial<{
       [K in BuiltinMessageId]: (self: TSelf, message: BuiltinMessages[K], sender: Url) => void;

package/src/message-guard.d.ts

@@ -8,6 +8,25 @@ declare global {
   // untyped `message` record narrow to its `BuiltinMessages` payload. The
   // transpiler lowers the call to `message_id == hash("...")`
   // (message-guard-lowering.ts), keeping this package free of runtime Lua.
+  /**
+   * Type guard for an `on_message` handler: narrows the untyped `message` record
+   * to its `BuiltinMessages` payload when `message_id` matches a known builtin
+   * message id. The engine delivers `message_id` as a pre-hashed `Hash`, so this
+   * guard re-introduces the literal a discriminated union would otherwise need.
+   *
+   * @param message_id - the hashed message id `on_message` received.
+   * @param message - the untyped message record `on_message` received.
+   * @param expected - the builtin message id to test against (e.g. `"contact_point_response"`).
+   * @returns `true` when `message_id` matches `expected`, narrowing `message` to that payload.
+   * @example
+   * ```ts
+   * function on_message(this: void, message_id: Hash, message: object, sender: Url) {
+   *   if (isMessage(message_id, message, "contact_point_response")) {
+   *     print(message.other_group);
+   *   }
+   * }
+   * ```
+   */
   function isMessage<K extends BuiltinMessageId>(
     message_id: Hash,
     message: Record<string | number, unknown>,

package/src/msg-overloads.d.ts

@@ -7,6 +7,26 @@ type MsgPostPayload<K> = K extends BuiltinMessageId
 
 declare global {
   namespace msg {
+    /**
+     * Post a message to a receiving URL. The most common case is to send messages
+     * to a component. If the component part of the receiver is omitted, the message
+     * is broadcast to all components in the game object.
+     * The following receiver shorthands are available:
+     * - `"."` the current game object
+     * - `"#"` the current component
+     * There is a 2 kilobyte limit to the message parameter table size.
+     *
+     * @param receiver - The receiver must be a string in URL-format, a URL object or a hashed string.
+     * @param message_id - The id must be a string or a hashed string.
+     * @param message - a lua table with message parameters to send.
+     * @example
+     * ```ts
+     * msg.post("#collisionobject", "apply_force", {
+     *   force: vmath.vector3(0, 1000, 0),
+     *   position: go.get_world_position(),
+     * });
+     * ```
+     */
     function post<K extends string>(
       receiver: string | Url | Hash,
       message_id: K,