@defold-typescript/types 0.8.4 → 0.10.0

package/src/doc-comment.ts

@@ -29,18 +29,20 @@ export function htmlToDocText(html: string): string {
     .replace(/<li>/gi, "\n- ")
     .replace(/<\/li>/gi, "")
     .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
     .replace(/<\/?pre>/gi, "\n")
     .replace(/<[^>]+>/g, "");
 
   text = decodeEntities(text);
 
-  // Collapse horizontal whitespace runs, trim around newlines, drop blank
-  // runs, then trim the whole string — preserving single newlines from lists
-  // and `<br>`.
+  // Collapse horizontal whitespace runs, trim around newlines, fold runaway
+  // blank runs to one blank line, then trim the whole string — preserving
+  // single newlines from lists and `<br>`, and the paragraph-break blank line
+  // from `</p>`.
   text = text
     .replace(/[ \t]+/g, " ")
     .replace(/ *\n */g, "\n")
-    .replace(/\n{2,}/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
     .trim();
 
   // A literal `*/` would close the JSDoc comment early; escape it.
@@ -68,6 +70,41 @@ export function htmlToCodeText(html: string): string {
   return collapsed.split("*/").join("*\\/");
 }
 
+/**
+ * Convert a ref-doc `examples` HTML fragment — prose interleaved with one or
+ * more `<div class="codehilite">…</div>` syntax-highlight blocks — into Markdown:
+ * prose runs become `htmlToDocText`, each highlight block becomes a ` ```lua `
+ * fence via `htmlToCodeText`. A fragment with no `codehilite` block is wrapped
+ * whole as a single ` ```lua ` fence (back-compat for plain-code examples).
+ * Returns `""` for empty / whitespace-only input.
+ */
+export function examplesHtmlToMarkdown(html: string): string {
+  if (html.trim() === "") return "";
+
+  const parts: string[] = [];
+  const blocks = /<div class="codehilite">([\s\S]*?)<\/div>/gi;
+  let lastIndex = 0;
+  let matched = false;
+  for (let match = blocks.exec(html); match !== null; match = blocks.exec(html)) {
+    matched = true;
+    const prose = htmlToDocText(html.slice(lastIndex, match.index));
+    if (prose !== "") parts.push(prose);
+    const code = htmlToCodeText(match[1] ?? "");
+    if (code !== "") parts.push(`\`\`\`lua\n${code}\n\`\`\``);
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (!matched) {
+    const code = htmlToCodeText(html);
+    return code === "" ? "" : `\`\`\`lua\n${code}\n\`\`\``;
+  }
+
+  const trailing = htmlToDocText(html.slice(lastIndex));
+  if (trailing !== "") parts.push(trailing);
+
+  return parts.join("\n\n");
+}
+
 export interface DocCommentParts {
   summary: string;
   params?: { name: string; doc: string }[];
@@ -92,7 +129,7 @@ export function renderDocComment(parts: DocCommentParts): string[] {
 
   const lines = ["/**"];
   for (const line of summaryLines) {
-    lines.push(` * ${line}`);
+    lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
   const hasTags = params.length > 0 || returns !== "" || example !== "";

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

package/src/engine-globals.d.ts

@@ -4,6 +4,8 @@ import type * as Core from "./core-types";
 declare global {
   type Hash = Core.Hash;
   function hash(s: string): Core.Hash;
+  function hash_to_hex(h: Core.Hash): string;
+  function pprint(v: unknown): void;
   type Opaque<Name extends string> = Core.Opaque<Name>;
   type Url = Core.Url;
   type Vector = Core.Vector;

package/src/example-store.ts

@@ -7,7 +7,10 @@ export interface Translation {
   ts: string;
 }
 
-export type TranslationStore = Record<string, Translation>;
+// An FQN maps to one translation per distinct example body it carries: an
+// overloaded element (same name, differing `@example` source) contributes one
+// array entry per body, each pinned by its own `sourceHash`.
+export type TranslationStore = Record<string, Translation[]>;
 
 const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
 const FNV_PRIME = 0x100000001b3n;
@@ -30,15 +33,16 @@ export function hashExampleSource(source: string): string {
   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.
+// Return the stored TypeScript body only when the FQN exists and one of its
+// pinned `sourceHash`es 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;
+  const entries = store[fqn];
+  if (!entries) return null;
+  const match = entries.find((entry) => entry.sourceHash === sourceHash);
+  return match ? match.ts : null;
 }

package/src/index.ts

@@ -10,8 +10,20 @@ export {
   type Vector3,
   type Vector4,
 } from "./core-types";
-export { type DocCommentParts, htmlToDocText, renderDocComment } from "./doc-comment";
+export {
+  type DocCommentParts,
+  examplesHtmlToMarkdown,
+  htmlToCodeText,
+  htmlToDocText,
+  renderDocComment,
+} from "./doc-comment";
 export { type EmitOptions, emitDeclarations } from "./emit-dts";
+export {
+  hashExampleSource,
+  lookupTranslation,
+  type Translation,
+  type TranslationStore,
+} from "./example-store";
 export {
   defineGuiScript,
   defineRenderScript,
@@ -30,3 +42,8 @@ export {
   type ScriptProperty,
 } from "./lifecycle";
 export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";
+export {
+  lookupSignature,
+  type SignatureOverride,
+  type SignatureStore,
+} from "./signature-store";