@defold-typescript/types 0.23.0 → 0.24.0

package/package.json

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

package/scripts/signature-store-fs.ts

@@ -22,6 +22,8 @@ export const PACKAGE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signature
 export const BASE_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "base.json");
 export const SOCKET_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "socket.json");
 export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "vmath.json");
+export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
+export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/src/api-doc.ts

@@ -20,12 +20,16 @@ export interface ApiTypedef {
   name: string;
   functions?: ApiFunction[];
   properties?: ApiVariable[];
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiConstant {
   name: string;
   brief: string;
   description: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
 }
 
 export interface ApiFunction {
@@ -41,6 +45,27 @@ export interface ApiFunction {
    * library functions; engine ref-docs carry no `generics`, so it stays absent.
    */
   generics?: string;
+  /**
+   * Present exactly when the source carried a `@deprecated` tag; `""` for a bare
+   * tag. Absence is the only encoding of "not deprecated", so a bare tag stays
+   * distinguishable from an untagged symbol.
+   */
+  deprecated?: string;
+  /**
+   * Present exactly when the source declared the symbol as an ambient global —
+   * outside the library's `declare module` block — so it is reachable without
+   * the module import. Absence is the only encoding of "module member"; the key
+   * is never written as `false`.
+   */
+  global?: true;
+  /**
+   * Present exactly when this symbol's prose was imported from the upstream
+   * source rather than written in the declaration — the authored/forked library
+   * lane lowers upstream's own LuaDoc summary for a member its fork documents
+   * nowhere. Absence is the only encoding of first-party prose, so every engine
+   * and hand-authored symbol reads as before.
+   */
+  docSource?: "upstream";
 }
 
 export interface ApiParameter {
@@ -67,6 +92,30 @@ export interface ApiVariable {
   brief: string;
   description: string;
   types: string[];
+  /**
+   * True for an optional member of a typedef shape (`clear?: boolean`). Set only
+   * when the element carries `is_optional: "True"`, so a module-level engine
+   * ref-doc VARIABLE — which never carries the key — leaves it absent.
+   */
+  isOptional?: boolean;
+  /** See {@link ApiFunction.deprecated}. */
+  deprecated?: string;
+  /** See {@link ApiFunction.global}. */
+  global?: true;
+  /** See {@link ApiFunction.docSource}. */
+  docSource?: "upstream";
+}
+
+/** The `{ global }` key to spread onto a parsed element, empty for a module member. */
+function globalKey(element: Record<string, unknown>): { global?: true } {
+  return element.global === true ? { global: true } : {};
+}
+
+/** The `{ docSource }` key to spread onto a parsed element, empty for first-party
+ * prose. Only the one recognised value yields a key: an unknown provenance would
+ * otherwise reach a page with no marker the render layer knows how to draw. */
+function docSourceKey(element: Record<string, unknown>): { docSource?: "upstream" } {
+  return element.docSource === "upstream" ? { docSource: "upstream" } : {};
 }
 
 export function parseDefoldApiDoc(input: unknown): ApiModule {
@@ -119,6 +168,7 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...globalKey(element),
   };
 }
 
@@ -145,6 +195,7 @@ function parseConstant(element: Record<string, unknown>): ApiConstant {
     name: stringOr(element.name, ""),
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
+    ...globalKey(element),
   };
 }
 
@@ -157,6 +208,9 @@ function parseFunction(element: Record<string, unknown>): ApiFunction {
     returnValues: parseParameterList(element.returnvalues),
     examples: stringOr(element.examples, ""),
     ...(typeof element.generics === "string" ? { generics: element.generics } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 
@@ -166,6 +220,10 @@ function parseVariable(element: Record<string, unknown>): ApiVariable {
     brief: stringOr(element.brief, ""),
     description: stringOr(element.description, ""),
     types: parseStringArray(element.types),
+    ...(element.is_optional === "True" ? { isOptional: true } : {}),
+    ...(typeof element.deprecated === "string" ? { deprecated: element.deprecated } : {}),
+    ...globalKey(element),
+    ...docSourceKey(element),
   };
 }
 

package/src/core-types.ts

@@ -188,6 +188,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   vector4: "Vector4",
   quaternion: "Quaternion",
   matrix4: "Matrix4",
+  // Authored-README shorthand for `vmath.matrix4`; absent from every engine
+  // ref-doc, which a core-types.test.ts guard keeps true as releases import.
+  matrix: "Matrix4",
   "vmath.vector3": "Vector3",
   "vmath.vector4": "Vector4",
   "vmath.matrix4": "Matrix4",

package/src/doc-comment.ts

@@ -107,6 +107,10 @@ export function examplesHtmlToMarkdown(html: string): string {
 
 export interface DocCommentParts {
   summary: string;
+  // Present exactly when the source carried a deprecation tag; `""` is the bare
+  // form and still renders, so this is tested against `undefined` rather than for
+  // truthiness the way the other optional parts are.
+  deprecated?: string;
   params?: { name: string; doc: string }[];
   returns?: string;
   example?: string;
@@ -122,8 +126,15 @@ export function renderDocComment(parts: DocCommentParts): string[] {
   const params = (parts.params ?? []).filter((p) => p.doc.trim() !== "");
   const returns = parts.returns?.trim() ? parts.returns : "";
   const example = parts.example?.trim() ? parts.example : "";
-
-  if (summaryLines.length === 0 && params.length === 0 && returns === "" && example === "") {
+  const deprecated = parts.deprecated;
+
+  if (
+    summaryLines.length === 0 &&
+    params.length === 0 &&
+    returns === "" &&
+    example === "" &&
+    deprecated === undefined
+  ) {
     return [];
   }
 
@@ -132,11 +143,18 @@ export function renderDocComment(parts: DocCommentParts): string[] {
     lines.push(line === "" ? " *" : ` * ${line}`);
   }
 
-  const hasTags = params.length > 0 || returns !== "" || example !== "";
+  const hasTags = deprecated !== undefined || params.length > 0 || returns !== "" || example !== "";
   if (summaryLines.length > 0 && hasTags) {
     lines.push(" *");
   }
 
+  if (deprecated !== undefined) {
+    const [first, ...rest] = deprecated.split("\n");
+    lines.push(first === "" ? " * @deprecated" : ` * @deprecated ${first}`);
+    for (const line of rest) {
+      lines.push(line === "" ? " *" : ` * ${line}`);
+    }
+  }
   for (const param of params) {
     const [first, ...rest] = param.doc.split("\n");
     lines.push(` * @param ${param.name} - ${first}`);

package/src/library-signature.ts

@@ -29,7 +29,15 @@ 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(", ")}]>`;
+/**
+ * Wrap `>1` mapped return tokens in the `LuaMultiReturn<[...]>` tuple form. With
+ * `restTail`, the last element renders as a rest element — the shape a LuaLS
+ * multi-return whose final value is a bare vararg (`fun(): T, ...`) calls for.
+ */
+export function luaMultiReturn(mapped: readonly string[], restTail = false): string {
+  const elements =
+    restTail && mapped.length > 0
+      ? [...mapped.slice(0, -1), `...${varargElementType(mapped[mapped.length - 1] as string)}`]
+      : mapped;
+  return `LuaMultiReturn<[${elements.join(", ")}]>`;
 }

package/src/script-api.ts

@@ -27,6 +27,17 @@ function stringOr(value: unknown, fallback: string): string {
   return typeof value === "string" ? value : fallback;
 }
 
+// A `.script_api` `type:` may spell a union inline (`string | nil`), where the
+// core ref-doc format carries one token per alternative. Splitting here keeps the
+// downstream emitter and fidelity resolver working in single tokens.
+function splitTypeTokens(type: unknown): string[] {
+  if (typeof type !== "string") return [];
+  return type
+    .split("|")
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+}
+
 function mapParameters(raw: unknown): RefDocParameter[] {
   if (!Array.isArray(raw)) return [];
   const out: RefDocParameter[] = [];
@@ -36,11 +47,10 @@ function mapParameters(raw: unknown): RefDocParameter[] {
     // The script_api lists the implicit `self` the engine passes; the emitter
     // stamps @noSelfInFile, so generated signatures must not declare it.
     if (name === "self") continue;
-    const type = item.type;
     out.push({
       name,
       doc: stringOr(item.desc, ""),
-      types: typeof type === "string" ? [type] : [],
+      types: splitTypeTokens(item.type),
     });
   }
   return out;