@defold-typescript/types 0.59.0 → 0.60.0

package/dist/cli-runtime.js

@@ -7672,12 +7672,20 @@ function slotList(value) {
     return value.filter(isRecord3);
   return isRecord3(value) ? [value] : [];
 }
+function slotName(item) {
+  return stringOr3(item.name, "").replace(REQUIRED_SUFFIX, "");
+}
+function isBracketed(item) {
+  return BRACKETED_NAME.test(slotName(item));
+}
 function isFunctionName(name) {
   return name !== "None" && FUNCTION_NAME.test(name);
 }
 function mapSlot(item) {
+  const name = slotName(item);
+  const bracketed = BRACKETED_NAME.exec(name);
   const slot = {
-    name: stringOr3(item.name, "").replace(REQUIRED_SUFFIX, ""),
+    name: bracketed ? (bracketed[1] ?? "").trim() : name,
     doc: stringOr3(item.desc, ""),
     types: splitTypeTokens2(item.type)
   };
@@ -7688,18 +7696,15 @@ function mapSlot(item) {
   ];
   if (nested.length > 0)
     slot.fields = nested.map(mapSlot);
-  if (item.optional === true)
+  if (item.optional === true || bracketed)
     slot.is_optional = "True";
   return slot;
 }
+function callSlots(raw) {
+  return slotList(raw).filter((item) => stringOr3(item.name, "") !== "self");
+}
 function mapParameters(raw) {
-  const out = [];
-  for (const item of slotList(raw)) {
-    if (stringOr3(item.name, "") === "self")
-      continue;
-    out.push(mapSlot(item));
-  }
-  return out;
+  return callSlots(raw).map(mapSlot);
 }
 function escapeHtml(text) {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -7750,17 +7755,27 @@ function scriptApiToRefDoc(parsed) {
   const members = Array.isArray(table.members) ? table.members : [];
   const elements = [];
   const fnElement = (name, member) => {
+    const raw = callSlots(member.parameters ?? member.params ?? member.members);
+    const parameters = raw.map(mapSlot);
     const element = {
       type: "FUNCTION",
       name,
       description: stringOr3(member.desc, ""),
-      parameters: mapParameters(member.parameters ?? member.params ?? member.members),
+      parameters,
       returnvalues: mapParameters(member.returns ?? member.return)
     };
     const examples = examplesHtml(member.examples);
     if (examples !== "")
       element.examples = examples;
-    return element;
+    const omissible = new Set(raw.flatMap((item, index) => isBracketed(item) && parameters.slice(index + 1).some((p) => p.is_optional === undefined) ? [index] : []));
+    if (omissible.size === 0)
+      return [element];
+    const { examples: _examples, ...withoutExamples } = element;
+    const omitted = {
+      ...withoutExamples,
+      parameters: parameters.filter((_, index) => !omissible.has(index))
+    };
+    return [omitted, element];
   };
   const constantElement = (name, member) => ({
     type: "CONSTANT",
@@ -7775,7 +7790,7 @@ function scriptApiToRefDoc(parsed) {
     if (member.type === "function") {
       if (!isFunctionName(stringOr3(member.name, "")))
         continue;
-      elements.push(fnElement(`${namespace}.${stringOr3(member.name, "")}`, member));
+      elements.push(...fnElement(`${namespace}.${stringOr3(member.name, "")}`, member));
       continue;
     }
     if (isScalar(member)) {
@@ -7793,7 +7808,7 @@ function scriptApiToRefDoc(parsed) {
         const name = `${namespace}.${sub}.${stringOr3(subMember.name, "")}`;
         if (subMember.type === "function") {
           if (isFunctionName(stringOr3(subMember.name, "")))
-            elements.push(fnElement(name, subMember));
+            elements.push(...fnElement(name, subMember));
         } else if (isScalar(subMember)) {
           elements.push(constantElement(name, subMember));
         }
@@ -7809,10 +7824,11 @@ function scriptApiToRefDoc(parsed) {
 function parseScriptApi(yamlText) {
   return scriptApiToRefDoc(parse(yamlText));
 }
-var TYPE_TOKEN_ALIASES, REQUIRED_SUFFIX, FUNCTION_NAME, FENCED_BLOCK;
+var TYPE_TOKEN_ALIASES, REQUIRED_SUFFIX, BRACKETED_NAME, FUNCTION_NAME, FENCED_BLOCK;
 var init_script_api = __esm(() => {
   TYPE_TOKEN_ALIASES = new Map([["enum", "constant"]]);
   REQUIRED_SUFFIX = /\s*\(required\)$/i;
+  BRACKETED_NAME = /^\[([^[\]]+)\]$/;
   FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
   FENCED_BLOCK = /^```([\w+#.-]*)[^\n]*\n([\s\S]*?)^```[ \t]*$/gm;
 });
@@ -8891,7 +8907,7 @@ var init_regen = __esm(async () => {
       extraModules: ["../../src/editor-overloads", "../../src/editor-vm-globals"],
       factory: "defineEditorScript",
       extraExports: ["defineEditorCommand"],
-      extraTypeExports: ["EditorCommandQuery", "EditorNode"],
+      extraTypeExports: ["EditorCommand", "EditorCommandQuery", "EditorNode", "EditorScriptModule"],
       factoryFrom: "../../src/editor",
       propertyTypes: false,
       jit: false

package/dist/src/index.d.ts

@@ -3,8 +3,7 @@ export type { ApiFunction, ApiModule, ApiParameter, ApiVariable, SkipOverloadRul
 export { parseDefoldApiDoc, withholdOverloads } from "./api-doc";
 export { DEFOLD_TYPE_MAP, type Hash, type Matrix4, type Quaternion, type Url, type Vector, type Vector3, type Vector4, } from "./core-types";
 export { type DocCommentParts, type ExampleSegment, type ExampleSegmentation, examplesHtmlToMarkdown, htmlToCodeText, htmlToDocText, renderDocComment, segmentExampleRegions, splitExampleSources, } from "./doc-comment";
-export { defineEditorScript, type EditorCommand, type EditorScriptModule, } from "./editor";
-export { type EmitOptions, emitDeclarations, emitSymbolSignatures, firstSlotAlternativeOf, routeTypeDeclarations, type SlotType, type SlotTypes, type SymbolSignature, TS_IDENTIFIER, TS_RESERVED_NAMES, } from "./emit-dts";
+export { type EmitOptions, emitDeclarations, emitSymbolSignatures, firstSlotAlternativeOf, isFunctionTypeText, routeTypeDeclarations, type SlotType, type SlotTypes, type SymbolSignature, TS_IDENTIFIER, TS_RESERVED_NAMES, } from "./emit-dts";
 export { ENGINE_TYPE_NAME_OVERRIDES, engineTypeName } from "./engine-type-name";
 export { hashExampleSource, lookupExampleSegments, lookupExampleTranslations, lookupTranslation, proseLuaFences, type Translation, type TranslationStore, translateProseFences, } from "./example-store";
 export { type EngineIndexBaseRow, engineIndexBaseRows, engineIndexBaseTable, } from "./index-base-table";

package/generated/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../src/editor-overloads";
 import "../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../src/editor";

package/generated/versions/defold-1.13.0/kinds/editor-script.d.ts

@@ -10,4 +10,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/generated/versions/defold-1.13.1/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/generated/versions/defold-1.13.2/kinds/editor-script.d.ts

@@ -11,4 +11,4 @@ import "../../../../src/editor-overloads";
 import "../../../../src/editor-vm-globals";
 
 export { defineEditorScript, defineEditorCommand } from "../../../../src/editor";
-export type { EditorCommandQuery, EditorNode } from "../../../../src/editor";
+export type { EditorCommand, EditorCommandQuery, EditorNode, EditorScriptModule } from "../../../../src/editor";

package/package.json

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

package/scripts/regen.ts

@@ -1145,7 +1145,7 @@ export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
     extraModules: ["../../src/editor-overloads", "../../src/editor-vm-globals"],
     factory: "defineEditorScript",
     extraExports: ["defineEditorCommand"],
-    extraTypeExports: ["EditorCommandQuery", "EditorNode"],
+    extraTypeExports: ["EditorCommand", "EditorCommandQuery", "EditorNode", "EditorScriptModule"],
     factoryFrom: "../../src/editor",
     propertyTypes: false,
     jit: false,

package/src/emit-dts.ts

@@ -6503,7 +6503,7 @@ function parameterType(
   return added.length === 0 ? kept : `${kept} | ${added.join(" | ")}`;
 }
 
-function isFunctionTypeText(ts: string): boolean {
+export function isFunctionTypeText(ts: string): boolean {
   let depth = 0;
   for (let i = 0; i < ts.length - 1; i++) {
     const c = ts[i];

package/src/index.ts

@@ -50,16 +50,12 @@ export {
   segmentExampleRegions,
   splitExampleSources,
 } from "./doc-comment";
-export {
-  defineEditorScript,
-  type EditorCommand,
-  type EditorScriptModule,
-} from "./editor";
 export {
   type EmitOptions,
   emitDeclarations,
   emitSymbolSignatures,
   firstSlotAlternativeOf,
+  isFunctionTypeText,
   routeTypeDeclarations,
   type SlotType,
   type SlotTypes,

package/src/script-api.ts

@@ -71,6 +71,18 @@ function slotList(value: unknown): Record<string, unknown>[] {
 // every slot is already required unless flagged optional, so the suffix is noise.
 const REQUIRED_SUFFIX = /\s*\(required\)$/i;
 
+// Upstream writes an omissible slot in call-syntax brackets (`[options]`), the
+// same convention its own `desc` prose uses for an optional argument.
+const BRACKETED_NAME = /^\[([^[\]]+)\]$/;
+
+function slotName(item: Record<string, unknown>): string {
+  return stringOr(item.name, "").replace(REQUIRED_SUFFIX, "");
+}
+
+function isBracketed(item: Record<string, unknown>): boolean {
+  return BRACKETED_NAME.test(slotName(item));
+}
+
 // Generators emit placeholder or C-signature names (`None`, `int JoinRandomRoom`)
 // that cannot form a Lua member access, so no page or declaration can carry them.
 const FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -80,8 +92,10 @@ function isFunctionName(name: string): boolean {
 }
 
 function mapSlot(item: Record<string, unknown>): RefDocParameter {
+  const name = slotName(item);
+  const bracketed = BRACKETED_NAME.exec(name);
   const slot: RefDocParameter = {
-    name: stringOr(item.name, "").replace(REQUIRED_SUFFIX, ""),
+    name: bracketed ? (bracketed[1] ?? "").trim() : name,
     doc: stringOr(item.desc, ""),
     types: splitTypeTokens(item.type),
   };
@@ -94,19 +108,18 @@ function mapSlot(item: Record<string, unknown>): RefDocParameter {
     ...slotList(item.members),
   ];
   if (nested.length > 0) slot.fields = nested.map(mapSlot);
-  if (item.optional === true) slot.is_optional = "True";
+  if (item.optional === true || bracketed) slot.is_optional = "True";
   return slot;
 }
 
+// The script_api lists the implicit `self` the engine passes; the emitter
+// stamps @noSelfInFile, so generated signatures must not declare it.
+function callSlots(raw: unknown): Record<string, unknown>[] {
+  return slotList(raw).filter((item) => stringOr(item.name, "") !== "self");
+}
+
 function mapParameters(raw: unknown): RefDocParameter[] {
-  const out: RefDocParameter[] = [];
-  for (const item of slotList(raw)) {
-    // The script_api lists the implicit `self` the engine passes; the emitter
-    // stamps @noSelfInFile, so generated signatures must not declare it.
-    if (stringOr(item.name, "") === "self") continue;
-    out.push(mapSlot(item));
-  }
-  return out;
+  return callSlots(raw).map(mapSlot);
 }
 
 function escapeHtml(text: string): string {
@@ -166,7 +179,11 @@ function isScalar(member: Record<string, unknown>): boolean {
  * present of `parameters:`, `params:` or `members:` and its returns from
  * `returns:` or `return:`, any slot list may be a single mapping, a table slot's
  * `members:` nest like `fields:`, a `(REQUIRED)` name suffix is dropped, and a
- * function named `None` or not a Lua identifier is skipped.
+ * function named `None` or not a Lua identifier is skipped. A slot or field
+ * named in brackets (`[options]`) takes the bare name and `is_optional`, and a
+ * function with such a slot before a slot that is not optional is also
+ * converted, first and without its examples, as a form that leaves out every
+ * such bracketed slot.
  */
 export function scriptApiToRefDoc(parsed: unknown): RefDoc {
   if (!Array.isArray(parsed)) {
@@ -188,17 +205,35 @@ 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>): RefDocFunctionElement => {
+  const fnElement = (name: string, member: Record<string, unknown>): RefDocFunctionElement[] => {
+    const raw = callSlots(member.parameters ?? member.params ?? member.members);
+    const parameters = raw.map(mapSlot);
     const element: RefDocFunctionElement = {
       type: "FUNCTION",
       name,
       description: stringOr(member.desc, ""),
-      parameters: mapParameters(member.parameters ?? member.params ?? member.members),
+      parameters,
       returnvalues: mapParameters(member.returns ?? member.return),
     };
     const examples = examplesHtml(member.examples);
     if (examples !== "") element.examples = examples;
-    return element;
+    // A bracketed slot a required one follows can only be left out by a call
+    // that skips it, so that call gets its own form; an explicit
+    // `optional: true` slot reads as passable-nil instead and gets none.
+    const omissible = new Set(
+      raw.flatMap((item, index) =>
+        isBracketed(item) && parameters.slice(index + 1).some((p) => p.is_optional === undefined)
+          ? [index]
+          : [],
+      ),
+    );
+    if (omissible.size === 0) return [element];
+    const { examples: _examples, ...withoutExamples } = element;
+    const omitted: RefDocFunctionElement = {
+      ...withoutExamples,
+      parameters: parameters.filter((_, index) => !omissible.has(index)),
+    };
+    return [omitted, element];
   };
   const constantElement = (
     name: string,
@@ -214,7 +249,7 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
     if (!isRecord(member)) continue;
     if (member.type === "function") {
       if (!isFunctionName(stringOr(member.name, ""))) continue;
-      elements.push(fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
+      elements.push(...fnElement(`${namespace}.${stringOr(member.name, "")}`, member));
       continue;
     }
     if (isScalar(member)) {
@@ -233,7 +268,7 @@ export function scriptApiToRefDoc(parsed: unknown): RefDoc {
         const name = `${namespace}.${sub}.${stringOr(subMember.name, "")}`;
         if (subMember.type === "function") {
           if (isFunctionName(stringOr(subMember.name, "")))
-            elements.push(fnElement(name, subMember));
+            elements.push(...fnElement(name, subMember));
         } else if (isScalar(subMember)) {
           elements.push(constantElement(name, subMember));
         }