@defold-typescript/types 0.20.7 → 0.21.0

package/index.d.ts

@@ -81,14 +81,30 @@ export {
   type Vector3,
   type Vector4,
 } from "./src/core-types";
-export { examplesHtmlToMarkdown, htmlToCodeText, htmlToDocText } from "./src/doc-comment";
-export { type EmitOptions, emitDeclarations } from "./src/emit-dts";
+export {
+  examplesHtmlToMarkdown,
+  htmlToCodeText,
+  htmlToDocText,
+  renderDocComment,
+} from "./src/doc-comment";
+export {
+  type EmitOptions,
+  emitDeclarations,
+  TS_IDENTIFIER,
+  TS_RESERVED_NAMES,
+} from "./src/emit-dts";
 export {
   hashExampleSource,
   lookupTranslation,
   type Translation,
   type TranslationStore,
 } from "./src/example-store";
+export {
+  hasTopLevelUnion,
+  luaMultiReturn,
+  needsArrayParens,
+  varargElementType,
+} from "./src/library-signature";
 export {
   defineGuiScript,
   defineRenderScript,

package/package.json

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

package/src/api-doc.ts

@@ -35,6 +35,12 @@ export interface ApiFunction {
   parameters: ApiParameter[];
   returnValues: ApiParameter[];
   examples?: string;
+  /**
+   * A pre-rendered generic-parameter clause (`<T extends druid_widget>`) inserted
+   * between the name and the `(` at render time. Present only on LuaLS-lowered
+   * library functions; engine ref-docs carry no `generics`, so it stays absent.
+   */
+  generics?: string;
 }
 
 export interface ApiParameter {
@@ -42,6 +48,13 @@ export interface ApiParameter {
   doc: string;
   types: string[];
   isOptional: boolean;
+  /**
+   * True for a `...` variadic parameter. `parseParameterList` always sets it
+   * (`false` when the ref-doc omits `is_vararg`, so engine docs read as before);
+   * optional on the interface so hand-built engine `ApiParameter` literals need
+   * not spell out `false`.
+   */
+  isVararg?: boolean;
   /**
    * Per-member docs for an object-literal type, extracted as a tree alongside
    * the flat `types` token (never inside it). Absent for plain-typed params.
@@ -143,6 +156,7 @@ function parseFunction(element: Record<string, unknown>): ApiFunction {
     parameters: parseParameterList(element.parameters),
     returnValues: parseParameterList(element.returnvalues),
     examples: stringOr(element.examples, ""),
+    ...(typeof element.generics === "string" ? { generics: element.generics } : {}),
   };
 }
 
@@ -183,6 +197,7 @@ function parseParameterList(raw: unknown): ApiParameter[] {
       doc: stringOr(item.doc, ""),
       types: parseStringArray(item.types),
       isOptional: item.is_optional === "True",
+      isVararg: item.is_vararg === "True",
       ...(Array.isArray(item.fields) ? { fields: parseParameterList(item.fields) } : {}),
     });
   }

package/src/index.ts

@@ -42,6 +42,8 @@ export {
   emitDeclarations,
   emitSymbolSignatures,
   type SymbolSignature,
+  TS_IDENTIFIER,
+  TS_RESERVED_NAMES,
 } from "./emit-dts";
 export {
   hashExampleSource,
@@ -49,6 +51,12 @@ export {
   type Translation,
   type TranslationStore,
 } from "./example-store";
+export {
+  hasTopLevelUnion,
+  luaMultiReturn,
+  needsArrayParens,
+  varargElementType,
+} from "./library-signature";
 export {
   defineGuiScript,
   defineRenderScript,

package/src/library-signature.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure string helpers for rendering variadic parameters and multi-value returns
+ * the way the library `.d.ts` emitter does. Shared by the emitter
+ * (`packages/library-types`) and the docs-site renderer (`packages/docs-site`),
+ * which both depend on `@defold-typescript/types`, so a library `/api` signature
+ * cannot drift from the shipped `generated/<ns>.d.ts` for these two shapes — the
+ * same anti-drift move the type/name/generic primitives already use.
+ */
+
+/** True when a top-level `|` (a union) appears in a mapped type, honoring bracket depth. */
+export function hasTopLevelUnion(ts: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < ts.length; i++) {
+    const c = ts[i];
+    if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c === "|") return true;
+  }
+  return false;
+}
+
+/** An array element needs parentheses when it is a union, a function, or an object. */
+export function needsArrayParens(ts: string): boolean {
+  return hasTopLevelUnion(ts) || ts.includes("=>") || ts.startsWith("{");
+}
+
+/** A vararg's element type arrayified: `string` -> `string[]`, `a | b` -> `(a | b)[]`. */
+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(", ")}]>`;
+}