@defold-typescript/types 0.22.0 → 0.24.0

package/package.json

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

package/scripts/regen.ts

@@ -9,7 +9,7 @@ import {
   parseMessagesDoc,
 } from "../src/emit-messages";
 import type { TranslationStore } from "../src/example-store";
-import { wrapAsAmbientGlobal } from "../src/publish-dts";
+import { wrapAsAmbientGlobal, wrapAsModule } from "../src/publish-dts";
 import {
   type DocSourceProvenance,
   type DownloadRefDoc,
@@ -90,6 +90,7 @@ export interface ModuleManifestEntry {
   readonly outFile: string;
   readonly skipFunctions?: readonly string[];
   readonly importsFrom?: string;
+  readonly moduleId?: string;
   readonly sourceProvenance?: DocSourceProvenance;
 }
 
@@ -239,11 +240,10 @@ export function generateModuleDeclaration(
     options,
   );
   const emitted = emitDeclarations(module, { knownConstantFqns, translations });
-  const contents = wrapAsAmbientGlobal({
-    namespace: module.namespace,
-    emitted,
-    importsFrom: entry.importsFrom ?? "../src/core-types",
-  });
+  const importsFrom = entry.importsFrom ?? "../src/core-types";
+  const contents = entry.moduleId
+    ? wrapAsModule({ namespace: module.namespace, emitted, importsFrom, moduleId: entry.moduleId })
+    : wrapAsAmbientGlobal({ namespace: module.namespace, emitted, importsFrom });
   return { contents, dropped };
 }
 

package/scripts/signature-store-fs.ts

@@ -22,6 +22,8 @@ export const PACKAGE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signature
 export const BASE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "base.json");
 export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "socket.json");
 export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
+export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
+export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/src/api-doc.ts

@@ -20,12 +20,16 @@ export interface ApiTypedef {
   name: string;
   functions?: ApiFunction[];
   properties?: ApiVariable[];
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiConstant {
   name: string;
   brief: string;
   description: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiFunction {
@@ -41,6 +45,27 @@ export interface ApiFunction {
    * library functions; engine ref-docs carry no `generics`, so it stays absent.
    */
   generics?: string;
+  /**
+   * Present exactly when the source carried a `@deprecated` tag; `""` for a bare
+   * tag. Absence is the only encoding of "not deprecated", so a bare tag stays
+   * distinguishable from an untagged symbol.
+   */
+  deprecated?: string;
+  /**
+   * Present exactly when the source declared the symbol as an ambient global —
+   * outside the library's `declare module` block — so it is reachable without
+   * the module import. Absence is the only encoding of "module member"; the key
+   * is never written as `false`.
+   */
+  global?: true;
+  /**
+   * Present exactly when this symbol's prose was imported from the upstream
+   * source rather than written in the declaration — the authored/forked library
+   * lane lowers upstream's own LuaDoc summary for a member its fork documents
+   * nowhere. Absence is the only encoding of first-party prose, so every engine
+   * and hand-authored symbol reads as before.
+   */
+  docSource?: "upstream";
 }
 
 export interface ApiParameter {
@@ -67,6 +92,30 @@ export interface ApiVariable {
   brief: string;
   description: string;
   types: string[];
+  /**
+   * True for an optional member of a typedef shape (`clear?: boolean`). Set only
+   * when the element carries `is_optional: "True"`, so a module-level engine
+   * ref-doc VARIABLE — which never carries the key — leaves it absent.
+   */
+  isOptional?: boolean;
+  /** See {@link ApiFunction.deprecated}. */
+  deprecated?: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
+  /** See {@link ApiFunction.docSource}. */
+  docSource?: "upstream";
+}
+
+/** The `{ global }` key to spread onto a parsed element, empty for a module member. */
+function globalKey(element: Record<string, unknown>): { global?: true } {
+  return element.global === true ? { global: true } : {};
+}
+
+/** The `{ docSource }` key to spread onto a parsed element, empty for first-party
+ * prose. Only the one recognised value yields a key: an unknown provenance would
+ * otherwise reach a page with no marker the render layer knows how to draw. */
+function docSourceKey(element: Record<string, unknown>): { docSource?: "upstream" } {
+  return element.docSource === "upstream" ? { docSource: "upstream" } : {};
 }
 
 export function parseDefoldApiDoc(input: unknown): ApiModule {
@@ -119,6 +168,7 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...globalKey(element),
   };
 }
 
@@ -145,6 +195,7 @@ function parseConstant(element: Record<string, unknown>): ApiConstant {
     name: stringOr(element.name, ""),
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
+    ...globalKey(element),
   };
 }
 
@@ -157,6 +208,9 @@ function parseFunction(element: Record<string, unknown>): ApiFunction {
     returnValues: parseParameterList(element.returnvalues),
     examples: stringOr(element.examples, ""),
     ...(typeof element.generics === "string" ? { generics: element.generics } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 
@@ -166,6 +220,10 @@ function parseVariable(element: Record<string, unknown>): ApiVariable {
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
     types: parseStringArray(element.types),
+    ...(element.is_optional === "True" ? { isOptional: true } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 

package/src/core-types.ts

@@ -188,6 +188,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   vector4: "Vector4",
   quaternion: "Quaternion",
   matrix4: "Matrix4",
+  // Authored-README shorthand for `vmath.matrix4`; absent from every engine
+  // ref-doc, which a core-types.test.ts guard keeps true as releases import.
+  matrix: "Matrix4",
   "vmath.vector3": "Vector3",
   "vmath.vector4": "Vector4",
   "vmath.matrix4": "Matrix4",

package/src/doc-comment.ts

@@ -107,6 +107,10 @@ export function examplesHtmlToMarkdown(html: string): string {
 
 export interface DocCommentParts {
   summary: string;
+  // Present exactly when the source carried a deprecation tag; `""` is the bare
+  // form and still renders, so this is tested against `undefined` rather than for
+  // truthiness the way the other optional parts are.
+  deprecated?: string;
   params?: { name: string; doc: string }[];
   returns?: string;
   example?: string;
@@ -122,8 +126,15 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   const params = (parts.params ?? []).filter((p) => p.doc.trim() !== "");
   const returns = parts.returns?.trim() ? parts.returns : "";
   const example = parts.example?.trim() ? parts.example : "";
-
-  if (summaryLines.length === 0 && params.length === 0 && returns === "" && example === "") {
+  const deprecated = parts.deprecated;
+
+  if (
+    summaryLines.length === 0 &&
+    params.length === 0 &&
+    returns === "" &&
+    example === "" &&
+    deprecated === undefined
+  ) {
     return [];
   }
 
@@ -132,11 +143,18 @@ export function renderDocComment(parts: DocCommentParts): string[] {
     lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
-  const hasTags = params.length > 0 || returns !== "" || example !== "";
+  const hasTags = deprecated !== undefined || params.length > 0 || returns !== "" || example !== "";
   if (summaryLines.length > 0 && hasTags) {
     lines.push(" *");
   }
 
+  if (deprecated !== undefined) {
+    const [first, ...rest] = deprecated.split("\n");
+    lines.push(first === "" ? " * @deprecated" : ` * @deprecated ${first}`);
+    for (const line of rest) {
+      lines.push(line === "" ? " *" : ` * ${line}`);
+    }
+  }
   for (const param of params) {
     const [first, ...rest] = param.doc.split("\n");
     lines.push(` * @param ${param.name} - ${first}`);

package/src/emit-dts.ts

@@ -1565,12 +1565,25 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   const nestedIndent = `${INDENT}${INDENT}`;
   for (const segment of nestedSegments) {
     const group = nestedGroups.get(segment) ?? [];
+    // A reserved-name function inside a nested namespace gets the same recovery as
+    // a top-level one: emitted un-exported as `_<name>` and re-exported under the
+    // reserved name. The alias switches this namespace out of implicit-export mode,
+    // so its siblings then need an explicit `export` to stay reachable.
+    const segmentAliases: { internal: string; public: string }[] = [];
+    const segmentDecl = group.some((fn) => TS_RESERVED_NAMES.has(fn.name)) ? "export " : "";
     lines.push(`${INDENT}${decl}namespace ${segment} {`);
     for (const fn of group) {
+      const reserved = TS_RESERVED_NAMES.has(fn.name);
+      const emitName = aliasName(fn.name, segmentAliases);
       for (const docLine of functionDocLines(fn.original, translations, nestedIndent)) {
         lines.push(docLine);
       }
-      lines.push(`${nestedIndent}${decl}${emitFunction(fn, fn.name, mapType, resolver)}`);
+      lines.push(
+        `${nestedIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver)}`,
+      );
+    }
+    for (const alias of [...segmentAliases].sort((a, b) => a.public.localeCompare(b.public))) {
+      lines.push(`${nestedIndent}export { ${alias.internal} as ${alias.public} };`);
     }
     lines.push(`${INDENT}}`);
   }

package/src/index.ts

@@ -80,7 +80,12 @@ export {
   type ScriptPropertiesOf,
   type ScriptProperty,
 } from "./lifecycle";
-export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";
+export {
+  type ModuleWrapOptions,
+  type WrapOptions,
+  wrapAsAmbientGlobal,
+  wrapAsModule,
+} from "./publish-dts";
 export {
   lookupSignature,
   type SignatureOverride,

package/src/library-signature.ts

@@ -29,7 +29,15 @@ export function varargElementType(mapped: string): string {
   return needsArrayParens(mapped) ? `(${mapped})[]` : `${mapped}[]`;
 }
 
-/** Wrap `>1` mapped return tokens in the `LuaMultiReturn<[...]>` tuple form. */
-export function luaMultiReturn(mapped: readonly string[]): string {
-  return `LuaMultiReturn<[${mapped.join(", ")}]>`;
+/**
+ * Wrap `>1` mapped return tokens in the `LuaMultiReturn<[...]>` tuple form. With
+ * `restTail`, the last element renders as a rest element — the shape a LuaLS
+ * multi-return whose final value is a bare vararg (`fun(): T, ...`) calls for.
+ */
+export function luaMultiReturn(mapped: readonly string[], restTail = false): string {
+  const elements =
+    restTail && mapped.length > 0
+      ? [...mapped.slice(0, -1), `...${varargElementType(mapped[mapped.length - 1] as string)}`]
+      : mapped;
+  return `LuaMultiReturn<[${elements.join(", ")}]>`;
 }

package/src/publish-dts.ts

@@ -16,18 +16,46 @@ export interface WrapOptions {
   importsFrom: string;
 }
 
-export function wrapAsAmbientGlobal(opts: WrapOptions): string {
-  const used = collectEngineTypes(opts.emitted);
+export interface ModuleWrapOptions extends WrapOptions {
+  moduleId: string;
+}
+
+// The engine-type import line plus the emitted body with its leading
+// `declare namespace` rewritten to `topKeyword` and every line indented two
+// spaces — the shared shape both the ambient-global and importable-module wraps
+// place inside their envelope.
+function prepareWrapBody(
+  emitted: string,
+  importsFrom: string,
+  topKeyword: string,
+): { importLine: string; indented: string } {
+  const used = collectEngineTypes(emitted);
   const importLine =
-    used.length === 0 ? "" : `import type { ${used.join(", ")} } from "${opts.importsFrom}";\n\n`;
-  const inner = opts.emitted.replace(/(^|\n)declare\s+namespace\s+/, "$1namespace ").trimEnd();
+    used.length === 0 ? "" : `import type { ${used.join(", ")} } from "${importsFrom}";\n\n`;
+  const inner = emitted.replace(/(^|\n)declare\s+namespace\s+/, `$1${topKeyword} `).trimEnd();
   const indented = inner
     .split("\n")
     .map((l) => (l.length === 0 ? l : `  ${l}`))
     .join("\n");
+  return { importLine, indented };
+}
+
+export function wrapAsAmbientGlobal(opts: WrapOptions): string {
+  const { importLine, indented } = prepareWrapBody(opts.emitted, opts.importsFrom, "namespace");
   return `/** @noSelfInFile */\n${importLine}declare global {\n${indented}\n}\n\nexport {};\n`;
 }
 
+export function wrapAsModule(opts: ModuleWrapOptions): string {
+  // ambient-globals-only: the module form references engine handles (`Hash`,
+  // `Vector3`, ...) as ambient globals and emits no top-level import. A top-level
+  // `import type` would make the `.d.ts` a module, demoting `declare module
+  // '<id>'` to an augmentation of an unresolvable specifier that a consumer
+  // `import` cannot resolve (`TS2307`). `importsFrom` stays in the signature for
+  // caller symmetry but is unused here; `wrapAsAmbientGlobal` still imports it.
+  const { indented } = prepareWrapBody(opts.emitted, opts.importsFrom, "export namespace");
+  return `/** @noSelfInFile */\n/** @noResolution */\ndeclare module '${opts.moduleId}' {\n${indented}\n}\n`;
+}
+
 function collectEngineTypes(emitted: string): EngineType[] {
   return ENGINE_TYPES.filter((t) => new RegExp(`\\b${t}\\b`).test(emitted));
 }

package/src/script-api.ts

@@ -27,6 +27,17 @@ function stringOr(value: unknown, fallback: string): string {
   return typeof value === "string" ? value : fallback;
 }
 
+// A `.script_api` `type:` may spell a union inline (`string | nil`), where the
+// core ref-doc format carries one token per alternative. Splitting here keeps the
+// downstream emitter and fidelity resolver working in single tokens.
+function splitTypeTokens(type: unknown): string[] {
+  if (typeof type !== "string") return [];
+  return type
+    .split("|")
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+}
+
 function mapParameters(raw: unknown): RefDocParameter[] {
   if (!Array.isArray(raw)) return [];
   const out: RefDocParameter[] = [];
@@ -36,11 +47,10 @@ function mapParameters(raw: unknown): RefDocParameter[] {
     // The script_api lists the implicit `self` the engine passes; the emitter
     // stamps @noSelfInFile, so generated signatures must not declare it.
     if (name === "self") continue;
-    const type = item.type;
     out.push({
       name,
       doc: stringOr(item.desc, ""),
-      types: typeof type === "string" ? [type] : [],
+      types: splitTypeTokens(item.type),
     });
   }
   return out;
@@ -73,15 +83,31 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
   }
   const members = Array.isArray(table.members) ? table.members : [];
   const elements: RefDocElement[] = [];
+  const fnElement = (name: string, member: Record<string, unknown>): RefDocElement => ({
+    type: "FUNCTION",
+    name,
+    description: stringOr(member.desc, ""),
+    parameters: mapParameters(member.parameters),
+    returnvalues: mapParameters(member.returns),
+  });
   for (const member of members) {
-    if (!isRecord(member) || member.type !== "function") continue;
-    elements.push({
-      type: "FUNCTION",
-      name: `${namespace}.${stringOr(member.name, "")}`,
-      description: stringOr(member.desc, ""),
-      parameters: mapParameters(member.parameters),
-      returnvalues: mapParameters(member.returns),
-    });
+    if (!isRecord(member)) continue;
+    if (member.type === "function") {
+      elements.push(fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
+      continue;
+    }
+    if (member.type === "table") {
+      const sub = stringOr(member.name, "");
+      // A nameless sub-namespace can't form a valid dotted name; skip it.
+      if (sub.length === 0) continue;
+      const subMembers = Array.isArray(member.members) ? member.members : [];
+      for (const subMember of subMembers) {
+        // Recurse exactly one level: a `type: table` nested here is 2nd-level,
+        // whose functions the emitter's one-dot pass would silently drop.
+        if (!isRecord(subMember) || subMember.type !== "function") continue;
+        elements.push(fnElement(`${namespace}.${sub}.${stringOr(subMember.name, "")}`, subMember));
+      }
+    }
   }
   const doc: RefDoc = {
     info: { namespace, brief: stringOr(table.desc, ""), description: stringOr(table.desc, "") },