@defold-typescript/types 0.9.0 → 0.10.0

package/index.d.ts

@@ -34,6 +34,7 @@ import "./generated/push";
 import "./generated/render";
 import "./generated/resource";
 import "./generated/socket";
+import "./src/socket-types";
 import "./generated/sound";
 import "./generated/sprite";
 import "./generated/sys";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,9 @@
     "./core-types": {
       "types": "./src/core-types.ts"
     },
+    "./lifecycle": {
+      "types": "./src/lifecycle.ts"
+    },
     "./timers": {
       "types": "./src/timers.d.ts"
     },

package/scripts/fidelity-audit.ts

@@ -4,6 +4,7 @@ import {
   ARBITRARY_TABLE_SLOTS,
   applyNestedFieldCurations,
   buildTableDocResolver,
+  HANDLE_METHOD_LOCAL,
   HOMOGENEOUS_ARRAY_SLOTS,
   MAPPING_TABLE_SLOTS,
   type NestedMapping,
@@ -76,6 +77,26 @@ function trailingOptionalCutoff(params: readonly Record<string, unknown>[]): num
   return cutoff;
 }
 
+// Colon `<receiver>:<method>` FUNCTION elements are emitted as method-bearing
+// interfaces (see emit-dts collectHandleMethodGroups). Before that recovery they
+// emitted nothing yet were never counted as a droppedMembers loss — a blind spot
+// that let `socket` read `droppedMembers: 0` over an incomplete surface. Count
+// them honestly: with emission on, only a malformed colon name (non-identifier
+// segment) is still a loss; with emission off, every colon method is dropped.
+export function countDroppedHandleMethods(doc: unknown, namespace: string, emit = true): number {
+  const prefix = `${namespace}.`;
+  let dropped = 0;
+  for (const element of elementsOf(doc)) {
+    if (element.type !== "FUNCTION" || typeof element.name !== "string") continue;
+    const local = element.name.startsWith(prefix)
+      ? element.name.slice(prefix.length)
+      : element.name;
+    if (!local.includes(":")) continue;
+    if (!emit || !HANDLE_METHOD_LOCAL.test(local)) dropped += 1;
+  }
+  return dropped;
+}
+
 function auditEntry(
   entry: ModuleManifestEntry,
   knownConstantFqns: ReadonlySet<string>,
@@ -356,9 +377,11 @@ function auditEntry(
     unknownTokens: [...unknown].sort(),
     recordTables,
     multiReturn,
-    droppedMembers: generateModuleDeclaration(entry, {
-      knownConstantFqns: NO_KNOWN_CONSTANTS,
-    }).dropped.filter((name) => !OVERLOAD_COVERED_SKIPS.has(name)).length,
+    droppedMembers:
+      generateModuleDeclaration(entry, {
+        knownConstantFqns: NO_KNOWN_CONSTANTS,
+      }).dropped.filter((name) => !OVERLOAD_COVERED_SKIPS.has(name)).length +
+      countDroppedHandleMethods(entry.doc, entry.namespace),
     optionalAsRequired,
   };
 }

package/scripts/materialize-version.ts

@@ -4,10 +4,33 @@ import {
   type ApiTarget,
   generateModuleDeclaration,
   generateVersionIndex,
+  KIND_MODULE_MANIFEST,
+  LUA_STDLIB_REFERENCES,
   type ResolveTargetOptions,
   resolveTargetModules,
 } from "./regen";
 
+export { KIND_MODULE_MANIFEST } from "./regen";
+
+export interface RenderMaterializedKindIndexOptions {
+  readonly kind: string;
+  readonly universalModules: readonly string[];
+  readonly restrictedModule: string | null;
+}
+
+// Render one per-kind subpath for the materialized surface, mirroring
+// `generateKindIndex` but re-exporting the factory from the installed
+// `@defold-typescript/types/lifecycle` subpath (the materialized surface has no
+// relative `src/lifecycle` to reach). Pure: returns a string, no FS.
+export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOptions): string {
+  const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === opts.kind);
+  if (!entry) throw new Error(`unknown script kind: ${opts.kind}`);
+  const universal = [...new Set(["engine-globals", ...opts.universalModules])].sort();
+  const lines = universal.map((mod) => `import "../${mod}";`);
+  if (opts.restrictedModule) lines.push(`import "../${opts.restrictedModule}";`);
+  return `${LUA_STDLIB_REFERENCES}${lines.join("\n")}\n\nexport { ${entry.factory} } from "@defold-typescript/types/lifecycle";\nexport type { ScriptProperties, ScriptProperty } from "@defold-typescript/types/lifecycle";\n`;
+}
+
 export interface MaterializeVersionedSurfaceOptions {
   readonly destDir: string;
   readonly resolveOpts?: ResolveTargetOptions;

package/scripts/regen.ts

@@ -230,7 +230,7 @@ export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
 // The Lua standard library rides every per-kind subpath the same as the full
 // entrypoint. Triple-slash directives must precede the first statement, so they
 // lead the generated kind index.
-const LUA_STDLIB_REFERENCES =
+export const LUA_STDLIB_REFERENCES =
   '/// <reference types="lua-types/5.1" />\n/// <reference types="lua-types/special/jit-only" />\n';
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [

package/src/core-types.ts

@@ -123,15 +123,20 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   constant: 'Opaque<"constant">',
   constant_buffer: 'Opaque<"constant_buffer">',
   buffer: 'Opaque<"buffer">',
-  bufferstream: 'Opaque<"bufferstream">',
+  bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
   userdata: 'Opaque<"userdata">',
   resource: 'Opaque<"resource">',
   b2World: 'Opaque<"b2World">',
   b2Body: 'Opaque<"b2Body">',
   b2BodyType:
     '(number & { readonly __brand: "b2d.body.B2_DYNAMIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_KINEMATIC_BODY" }) | (number & { readonly __brand: "b2d.body.B2_STATIC_BODY" })',
-  client: 'Opaque<"client">',
-  master: 'Opaque<"master">',
-  unconnected: 'Opaque<"unconnected">',
+  // socket handle types resolve to the method-bearing `interface <receiver>`
+  // emitted inside `namespace socket`, not opaque brands — the documented
+  // colon methods (`client:send`, …) make each handle structurally distinct.
+  client: "client",
+  connected: "connected",
+  master: "master",
+  server: "server",
+  unconnected: "unconnected",
   any: "unknown",
 } as const;

package/src/emit-dts.ts

@@ -180,6 +180,14 @@ export const MAPPING_TABLE_SLOTS: ReadonlyMap<string, { key: string; value: stri
   ["gui.get_layouts", { key: "hash", value: "vector3" }],
 ]);
 
+// FQN-keyed return-type overrides for functions whose doc `returnvalues` are
+// empty yet the engine returns a value. `gui.get`'s doc lists no return, but it
+// yields the property value (a vmath.vector4 or a number); `unknown` is the
+// honest, ts-defold-matching shape. Per-FQN, not a blanket "empty returnvalues
+// -> unknown" rule: `gui.set` also has empty returnvalues and `void` is correct
+// there.
+export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([["gui.get", "unknown"]]);
+
 // Element names whose `table` slot is a prose-only `array/list/table of <T>` shape
 // the field-list parser cannot read, but whose element type a human curated from
 // the doc. The value is a single element token (`T[]`) or a token list when the
@@ -219,7 +227,7 @@ export type TableSlotCuration =
   | { kind: "object"; fields: readonly TableField[] }
   | { kind: "array-object"; fields: readonly TableField[] };
 
-const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const;
+export const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const;
 
 export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map([
   ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
@@ -866,6 +874,42 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
         : a.name.localeCompare(b.name),
     );
 
+  // One-level nested functions (`socket.dns.toip`) fail the flat-identifier test
+  // in `prepareFunction` above (the stripped `dns.toip` has a dot), so they are
+  // absent from `functions`. Re-collect them grouped by their single leading
+  // segment, re-stripping against `<namespace>.<segment>.` so the emitted
+  // identifier is the final segment. Only exactly-one-dot, both-sides-identifier
+  // locals qualify; deeper nesting and non-identifier segments stay dropped.
+  const nestedFunctionLocal = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
+  const nestedGroups = new Map<string, PreparedFunction[]>();
+  for (const fn of module.functions) {
+    const local = stripPrefix(fn.name, prefix);
+    if (!nestedFunctionLocal.test(local)) continue;
+    const segment = local.slice(0, local.indexOf("."));
+    const prepared = prepareFunction(fn, `${module.namespace}.${segment}.`);
+    if (prepared === null) continue;
+    const group = nestedGroups.get(segment) ?? [];
+    group.push(prepared);
+    nestedGroups.set(segment, group);
+  }
+  for (const group of nestedGroups.values()) {
+    group.sort((a, b) =>
+      a.name === b.name
+        ? a.original.parameters.length - b.original.parameters.length
+        : a.name.localeCompare(b.name),
+    );
+  }
+  const nestedSegments = [...nestedGroups.keys()].sort((a, b) => a.localeCompare(b));
+
+  // Colon methods (`client:send`) are FUNCTION elements named `<receiver>:<method>`
+  // and are NOT namespace-prefixed, so they fail the flat-identifier test in
+  // prepareFunction (the colon) and are absent from `functions`. A returned handle
+  // is defined entirely by these methods; emit each receiver as a method-bearing
+  // interface, the same non-flat recovery the dns nested-namespace pass does one
+  // container shape shallower.
+  const handleGroups = collectHandleMethodGroups(module);
+  const handleReceivers = [...handleGroups.keys()].sort((a, b) => a.localeCompare(b));
+
   const resolver = buildTableDocResolver(
     module.functions.map((fn) => ({
       name: fn.name,
@@ -891,8 +935,23 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
   lines.push(`declare namespace ${module.namespace} {`);
 
   for (const t of typedefs) {
+    // A typedef that also has colon methods is emitted as a method-bearing
+    // interface below, not an opaque brand alias.
+    if (handleGroups.has(t.name)) continue;
     lines.push(`${INDENT}${decl}type ${t.name} = Opaque<"${t.name}">;`);
   }
+  const handleIndent = `${INDENT}${INDENT}`;
+  for (const receiver of handleReceivers) {
+    const group = handleGroups.get(receiver) ?? [];
+    lines.push(`${INDENT}${decl}interface ${receiver} {`);
+    for (const fn of group) {
+      for (const docLine of functionDocLines(fn.original, translations, handleIndent)) {
+        lines.push(docLine);
+      }
+      lines.push(`${handleIndent}${emitMethod(fn, mapType, resolver)}`);
+    }
+    lines.push(`${INDENT}}`);
+  }
   for (const c of constants) {
     for (const docLine of summaryDocLines(c.original.brief, c.original.description, INDENT)) {
       lines.push(docLine);
@@ -926,6 +985,19 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
     lines.push(`${INDENT}export { ${alias.internal} as ${alias.public} };`);
   }
 
+  const nestedIndent = `${INDENT}${INDENT}`;
+  for (const segment of nestedSegments) {
+    const group = nestedGroups.get(segment) ?? [];
+    lines.push(`${INDENT}${decl}namespace ${segment} {`);
+    for (const fn of group) {
+      for (const docLine of functionDocLines(fn.original, translations, nestedIndent)) {
+        lines.push(docLine);
+      }
+      lines.push(`${nestedIndent}${decl}${emitFunction(fn, fn.name, mapType, resolver)}`);
+    }
+    lines.push(`${INDENT}}`);
+  }
+
   if (module.properties.length > 0) {
     const members = [...module.properties].sort((a, b) => a.name.localeCompare(b.name));
     lines.push(`${INDENT}${decl}interface properties {`);
@@ -964,6 +1036,37 @@ function prepareFunction(fn: ApiFunction, prefix: string): PreparedFunction | nu
   return { name: stripped, original: fn };
 }
 
+// A `<receiver>:<method>` handle method, both segments bare identifiers. Deeper
+// shapes and non-identifier segments do not match and stay dropped.
+export const HANDLE_METHOD_LOCAL = /^[A-Za-z_$][\w$]*:[A-Za-z_$][\w$]*$/;
+
+// Group a module's colon-method FUNCTION elements (`client:send`) by their
+// receiver segment, each method prepared so its emitted name is the final
+// segment. Receivers (and the methods within each) are returned unsorted; the
+// emitter sorts for a stable surface. A non-identifier segment yields no group.
+export function collectHandleMethodGroups(module: ApiModule): Map<string, PreparedFunction[]> {
+  const prefix = `${module.namespace}.`;
+  const groups = new Map<string, PreparedFunction[]>();
+  for (const fn of module.functions) {
+    const local = stripPrefix(fn.name, prefix);
+    if (!HANDLE_METHOD_LOCAL.test(local)) continue;
+    const receiver = local.slice(0, local.indexOf(":"));
+    const prepared = prepareFunction(fn, fn.name.slice(0, fn.name.lastIndexOf(":") + 1));
+    if (prepared === null) continue;
+    const group = groups.get(receiver) ?? [];
+    group.push(prepared);
+    groups.set(receiver, group);
+  }
+  for (const group of groups.values()) {
+    group.sort((a, b) =>
+      a.name === b.name
+        ? a.original.parameters.length - b.original.parameters.length
+        : a.name.localeCompare(b.name),
+    );
+  }
+  return groups;
+}
+
 function prepareConstant(c: ApiConstant, prefix: string): PreparedConstant | null {
   const stripped = stripPrefix(c.name, prefix);
   if (!TS_IDENTIFIER.test(stripped)) return null;
@@ -1007,7 +1110,7 @@ function emitVariable(
   return `const ${name}: ${ts};`;
 }
 
-function emitFunction(
+function memberSignature(
   prepared: PreparedFunction,
   name: string,
   mapType: (t: string) => string,
@@ -1020,7 +1123,27 @@ function emitFunction(
     .map((p, i) => emitParameter(p, i, i >= cutoff, mapType, resolver, elementName))
     .join(", ");
   const ret = emitReturn(prepared.original.returnValues, mapType, resolver, elementName);
-  return `function ${name}(${params}): ${ret.type};${ret.trailing}`;
+  return `${name}(${params}): ${ret.type};${ret.trailing}`;
+}
+
+function emitFunction(
+  prepared: PreparedFunction,
+  name: string,
+  mapType: (t: string) => string,
+  resolver: TableDocResolver,
+): string {
+  return `function ${memberSignature(prepared, name, mapType, resolver)}`;
+}
+
+// A colon-method member of a handle interface: identical signature machinery to a
+// free function, but without the `function` keyword. `@noSelfInFile` means the
+// member carries no `self` parameter.
+function emitMethod(
+  prepared: PreparedFunction,
+  mapType: (t: string) => string,
+  resolver: TableDocResolver,
+): string {
+  return memberSignature(prepared, prepared.name, mapType, resolver);
 }
 
 // Build the indented JSDoc lines for a function from its ref-doc prose. The
@@ -1029,7 +1152,11 @@ 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, translations: TranslationStore): string[] {
+function functionDocLines(
+  fn: ApiFunction,
+  translations: TranslationStore,
+  indent: string = INDENT,
+): string[] {
   const params = fn.parameters.map((p, index) => ({
     name: safeParamName(p.name, index),
     doc: htmlToDocText(p.doc),
@@ -1047,7 +1174,7 @@ function functionDocLines(fn: ApiFunction, translations: TranslationStore): stri
     ...(onlyReturn ? { returns: htmlToDocText(onlyReturn.doc) } : {}),
     ...exampleParts,
   };
-  return indentDocLines(parts, INDENT);
+  return indentDocLines(parts, indent);
 }
 
 // Summary-only doc lines for a member that carries no params or returns
@@ -1116,6 +1243,8 @@ function emitReturn(
   resolver: TableDocResolver,
   elementName: string,
 ): { type: string; trailing: string } {
+  const override = RETURN_TYPE_OVERRIDES.get(elementName);
+  if (override !== undefined) return { type: override, trailing: "" };
   if (returnValues.length === 0) return { type: "void", trailing: "" };
   if (returnValues.length > 1) {
     // Defold multi-returns are positional and always present; each slot maps