@defold-typescript/types 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.22.0",
+  "version": "0.23.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/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/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

@@ -73,15 +73,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, "") },