@defold-typescript/types 0.21.1 → 0.23.0

package/index.d.ts

@@ -87,6 +87,11 @@ export {
   htmlToDocText,
   renderDocComment,
 } from "./src/doc-comment";
+export {
+  defineEditorScript,
+  type EditorCommand,
+  type EditorScriptModule,
+} from "./src/editor";
 export {
   type EmitOptions,
   emitDeclarations,

package/package.json

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

@@ -0,0 +1,75 @@
+// Editor scripts are loaded by the Defold *editor*, not the runtime engine: the
+// editor `require`s the emitted chunk and reads the hooks table it returns. That
+// makes them a fourth, disjoint script kind — lowered to a chunk-level
+// `return <hooks table>` rather than the runtime kinds' flat top-level globals.
+//
+// This is the keystone surface only. The full typed `editor.*` global
+// (`get`/`transact`/`command` + the editor-VM `http`/`json`/`zip`) and the
+// per-kind API walls are a later slice, so a command's `run`/`active` receive a
+// loosely-typed opts bag for now.
+
+/**
+ * A single command an editor script contributes: a label, the editor UI
+ * locations it appears in (e.g. `"Edit"`, `"Assets"`, `"Outline"`, `"View"`),
+ * and optional `active`/`run` hooks the editor calls with a command-context bag.
+ */
+export interface EditorCommand {
+  /** Menu/label text shown for the command. */
+  label: string;
+  /** Editor UI locations the command is offered in. */
+  locations: string[];
+  /**
+   * Declares the command's context arguments; the editor passes the resolved
+   * values to `active`/`run`. Loosely typed until the `editor.*` slice lands.
+   */
+  query?: Record<string, unknown>;
+  /**
+   * Called to decide whether the command is currently enabled. Omit to always
+   * enable. The opts bag is loosely typed until the `editor.*` slice lands.
+   */
+  active?: (opts: Record<string, unknown>) => boolean;
+  /**
+   * Called when the command is invoked. The opts bag is loosely typed until the
+   * `editor.*` slice lands.
+   */
+  run?: (opts: Record<string, unknown>) => void;
+}
+
+/**
+ * The hooks table an editor script returns. Every hook is optional; the editor
+ * calls the ones present. Only the keystone hooks are typed here.
+ */
+export interface EditorScriptModule {
+  /** Returns the commands this script contributes to the editor. */
+  get_commands?: () => EditorCommand[];
+  /** Returns language-server descriptors this script contributes. */
+  get_language_servers?: () => unknown[];
+}
+
+/**
+ * Type an editor script's hooks table. At runtime this is an identity function —
+ * it returns `module` unchanged; its only job is typing. The transpiler's
+ * `editor-script-erasure` pass rewrites the top-level `export default
+ * defineEditorScript({...})` into a chunk-level `return { ... }` (the shape the
+ * editor loads) and erases this import — zero runtime cost.
+ *
+ * @param module - the editor-script hooks table to type and return.
+ * @returns the same `module` object, now typed (identity at runtime).
+ * @example
+ * ```ts
+ * export default defineEditorScript({
+ *   get_commands: () => [
+ *     { label: "Say Hi", locations: ["Edit"], run: () => print("hi") },
+ *   ],
+ * });
+ * ```
+ */
+export function defineEditorScript<T extends EditorScriptModule>(
+  // Intersecting the non-module keys with `never` rejects an unknown hook key on
+  // a fresh object literal, while the `T` return keeps the call an identity over
+  // its exact argument type (a bare `<T extends ...>` would silently absorb the
+  // extra key into `T` and accept it).
+  module: T & Record<Exclude<keyof T, keyof EditorScriptModule>, never>,
+): T {
+  return module;
+}

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

@@ -37,6 +37,11 @@ export {
   htmlToDocText,
   renderDocComment,
 } from "./doc-comment";
+export {
+  defineEditorScript,
+  type EditorCommand,
+  type EditorScriptModule,
+} from "./editor";
 export {
   type EmitOptions,
   emitDeclarations,
@@ -75,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, "") },