@defold-typescript/transpiler 0.39.0 → 0.40.0

package/dist/array-index-option-lowering.d.ts

@@ -0,0 +1,6 @@
+import { type Plugin } from "typescript-to-lua";
+export declare const ONE_BASED_INDEX_OPTION_APIS: ReadonlySet<string>;
+export declare const INDEX_OPTION_VARIABLE_MESSAGE = "`options.index` is zero-based and is converted to Defold's 1-based index only in an object literal written at the call; pass the options inline.";
+export declare const INDEX_OPTION_SPREAD_MESSAGE = "A spread carrying `index` cannot be converted to Defold's 1-based index; write `index` explicitly after the spread.";
+export declare const INDEX_OPTION_UNDEFINED_MESSAGE = "`options.index` may be undefined here, so it cannot be converted to Defold's 1-based index; pass a number, or leave `index` out.";
+export declare const arrayIndexOptionLoweringPlugin: Plugin;

package/dist/index.js

@@ -2058,16 +2058,179 @@ function computeOutputRel(rel, config, kind) {
   return baseRel.replace(/\.ts$/, SCRIPT_SUFFIX_BY_KIND[kind]);
 }
 // src/program-diagnostics.ts
-import * as ts8 from "typescript";
+import * as ts9 from "typescript";
 import * as tstl from "typescript-to-lua";
 
-// src/message-guard-lowering.ts
+// src/array-index-option-lowering.ts
 import * as ts5 from "typescript";
 import {
   createBinaryExpression as createBinaryExpression3,
+  createNumericLiteral,
+  getOriginalPos,
+  isCallExpression as isCallExpression3,
+  isNumericLiteral as isNumericLiteral3,
+  isStringLiteral as isStringLiteral5,
+  isTableExpression,
+  SyntaxKind as SyntaxKind7,
+  setNodePosition
+} from "typescript-to-lua";
+var ONE_BASED_INDEX_OPTION_APIS = new Set([
+  "go.get",
+  "go.set",
+  "gui.get",
+  "gui.set"
+]);
+var INDEX_OPTION_VARIABLE_MESSAGE = "`options.index` is zero-based and is converted to Defold's 1-based index only in an object literal written at the call; pass the options inline.";
+var INDEX_OPTION_SPREAD_MESSAGE = "A spread carrying `index` cannot be converted to Defold's 1-based index; write `index` explicitly after the spread.";
+var INDEX_OPTION_UNDEFINED_MESSAGE = "`options.index` may be undefined here, so it cannot be converted to Defold's 1-based index; pass a number, or leave `index` out.";
+var OPTIONS_PARAMETER = "options";
+var INDEX_KEY = "index";
+var loweredLiterals = new WeakSet;
+function oneBasedApi(declaration, checker) {
+  let node = declaration;
+  while (node !== undefined && !ts5.isFunctionDeclaration(node))
+    node = node.parent;
+  if (node?.name === undefined)
+    return false;
+  const symbol = checker.getSymbolAtLocation(node.name);
+  if (symbol === undefined)
+    return false;
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") && ONE_BASED_INDEX_OPTION_APIS.has(fqn.slice("global.".length));
+}
+function optionsArgument(call, checker) {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (declaration === undefined || !ts5.isFunctionLike(declaration))
+    return;
+  if (!oneBasedApi(declaration, checker))
+    return;
+  const index = declaration.parameters.findIndex((parameter) => parameter.dotDotDotToken === undefined && ts5.isIdentifier(parameter.name) && parameter.name.text === OPTIONS_PARAMETER);
+  return index === -1 ? undefined : call.arguments[index];
+}
+function unwrap(expression) {
+  let current = expression;
+  while (ts5.isParenthesizedExpression(current) || ts5.isAsExpression(current) || ts5.isSatisfiesExpression(current) || ts5.isNonNullExpression(current) || ts5.isTypeAssertionExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+function someConstituent(type, predicate) {
+  return type.isUnion() ? type.types.some(predicate) : predicate(type);
+}
+function carriesIndex(type) {
+  return someConstituent(type, (t) => t.getProperty(INDEX_KEY) !== undefined);
+}
+function admitsUndefined(type) {
+  return someConstituent(type, (t) => (t.flags & (ts5.TypeFlags.Undefined | ts5.TypeFlags.Void)) !== 0);
+}
+function propertyName(property, checker) {
+  const name = property.name;
+  if (name === undefined)
+    return;
+  if (ts5.isIdentifier(name) || ts5.isStringLiteral(name) || ts5.isNumericLiteral(name)) {
+    return name.text;
+  }
+  if (ts5.isComputedPropertyName(name)) {
+    const type = checker.getTypeAtLocation(name.expression);
+    if (type.isStringLiteral())
+      return type.value;
+  }
+  return;
+}
+function indexValueType(property, checker) {
+  if (ts5.isPropertyAssignment(property))
+    return checker.getTypeAtLocation(property.initializer);
+  if (ts5.isShorthandPropertyAssignment(property))
+    return checker.getTypeAtLocation(property.name);
+  return;
+}
+function rejection(node, messageText) {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts5.DiagnosticCategory.Error,
+    code: 0,
+    messageText
+  };
+}
+function rejectOptions(options, checker) {
+  const literal = unwrap(options);
+  if (!ts5.isObjectLiteralExpression(literal)) {
+    return carriesIndex(checker.getTypeAtLocation(literal)) ? rejection(options, INDEX_OPTION_VARIABLE_MESSAGE) : undefined;
+  }
+  let uncoveredSpread;
+  let explicitIndex;
+  for (const property of literal.properties) {
+    if (ts5.isSpreadAssignment(property)) {
+      if (carriesIndex(checker.getTypeAtLocation(property.expression)))
+        uncoveredSpread = property;
+    } else if (propertyName(property, checker) === INDEX_KEY) {
+      uncoveredSpread = undefined;
+      explicitIndex = property;
+    }
+  }
+  if (uncoveredSpread !== undefined)
+    return rejection(uncoveredSpread, INDEX_OPTION_SPREAD_MESSAGE);
+  const valueType = explicitIndex && indexValueType(explicitIndex, checker);
+  if (explicitIndex !== undefined && valueType !== undefined && admitsUndefined(valueType)) {
+    return rejection(explicitIndex, INDEX_OPTION_UNDEFINED_MESSAGE);
+  }
+  return;
+}
+function plusOne(value) {
+  if (isNumericLiteral3(value)) {
+    return setNodePosition(createNumericLiteral(value.value + 1), getOriginalPos(value));
+  }
+  return setNodePosition(createBinaryExpression3(value, createNumericLiteral(1), SyntaxKind7.AdditionOperator), getOriginalPos(value));
+}
+function offsetEffectiveIndexField(tables) {
+  for (const field of tables.flatMap((table) => table.fields).reverse()) {
+    if (field.key !== undefined && isStringLiteral5(field.key) && field.key.value === INDEX_KEY) {
+      field.value = plusOne(field.value);
+      return;
+    }
+  }
+}
+var arrayIndexOptionLoweringPlugin = {
+  visitors: {
+    [ts5.SyntaxKind.CallExpression]: (node, context) => {
+      const options = optionsArgument(node, context.checker);
+      if (options !== undefined) {
+        const diagnostic = rejectOptions(options, context.checker);
+        if (diagnostic !== undefined) {
+          context.diagnostics.push(diagnostic);
+        } else {
+          const literal = unwrap(options);
+          if (ts5.isObjectLiteralExpression(literal))
+            loweredLiterals.add(literal);
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    [ts5.SyntaxKind.ObjectLiteralExpression]: (node, context) => {
+      const result = context.superTransformExpression(node);
+      if (!loweredLiterals.has(node))
+        return result;
+      if (isTableExpression(result)) {
+        offsetEffectiveIndexField([result]);
+      } else if (isCallExpression3(result)) {
+        offsetEffectiveIndexField(result.params.filter(isTableExpression));
+      }
+      return result;
+    }
+  }
+};
+
+// src/message-guard-lowering.ts
+import * as ts6 from "typescript";
+import {
+  createBinaryExpression as createBinaryExpression4,
   createCallExpression as createCallExpression3,
   createIdentifier as createIdentifier3,
-  SyntaxKind as SyntaxKind7
+  SyntaxKind as SyntaxKind9
 } from "typescript-to-lua";
 var GUARD_MODULE = "@defold-typescript/types";
 var GUARD_NAME = "isMessage";
@@ -2076,7 +2239,7 @@ function resolvesToGuardExport(callee, checker) {
   if (symbol === undefined) {
     return false;
   }
-  if (symbol.flags & ts5.SymbolFlags.Alias) {
+  if (symbol.flags & ts6.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
   if (symbol.getName() !== GUARD_NAME) {
@@ -2090,12 +2253,12 @@ function resolvesToGuardExport(callee, checker) {
 }
 var messageGuardLoweringPlugin = {
   visitors: {
-    [ts5.SyntaxKind.CallExpression]: (node, context) => {
+    [ts6.SyntaxKind.CallExpression]: (node, context) => {
       const [messageIdArg, , expectedArg] = node.arguments;
       if (node.arguments.length === 3 && messageIdArg !== undefined && expectedArg !== undefined && resolvesToGuardExport(node.expression, context.checker)) {
         const messageId = context.transformExpression(messageIdArg);
         const expected = context.transformExpression(expectedArg);
-        return createBinaryExpression3(messageId, createCallExpression3(createIdentifier3("hash"), [expected]), SyntaxKind7.EqualityOperator, node);
+        return createBinaryExpression4(messageId, createCallExpression3(createIdentifier3("hash"), [expected]), SyntaxKind9.EqualityOperator, node);
       }
       return context.superTransformExpression(node);
     }
@@ -2103,34 +2266,34 @@ var messageGuardLoweringPlugin = {
 };
 
 // src/timers-lowering.ts
-import * as ts6 from "typescript";
+import * as ts7 from "typescript";
 import { LuaLibFeature } from "typescript-to-lua";
 function isTimersSpecifier(node) {
-  return ts6.isStringLiteral(node) && node.text === TIMERS_MODULE_SPECIFIER;
+  return ts7.isStringLiteral(node) && node.text === TIMERS_MODULE_SPECIFIER;
 }
 function importsTimersModule(sourceFile) {
-  return sourceFile.statements.some((statement) => ts6.isImportDeclaration(statement) && isTimersSpecifier(statement.moduleSpecifier));
+  return sourceFile.statements.some((statement) => ts7.isImportDeclaration(statement) && isTimersSpecifier(statement.moduleSpecifier));
 }
 var TIMERS_REQUIRE_PATH = `@NoResolution:${TIMERS_REQUIRE_NAME}`;
 var timersLoweringPlugin = {
   visitors: {
-    [ts6.SyntaxKind.ImportDeclaration]: (node, context) => {
+    [ts7.SyntaxKind.ImportDeclaration]: (node, context) => {
       if (!isTimersSpecifier(node.moduleSpecifier)) {
         return context.superTransformStatements(node);
       }
       context.usedLuaLibFeatures.add(LuaLibFeature.Promise);
       context.usedLuaLibFeatures.add(LuaLibFeature.New);
-      const rewritten = ts6.factory.updateImportDeclaration(node, node.modifiers, node.importClause, ts6.factory.createStringLiteral(TIMERS_REQUIRE_PATH), node.attributes);
+      const rewritten = ts7.factory.updateImportDeclaration(node, node.modifiers, node.importClause, ts7.factory.createStringLiteral(TIMERS_REQUIRE_PATH), node.attributes);
       return context.superTransformStatements(rewritten);
     }
   }
 };
 
 // src/window-event-guard-lowering.ts
-import * as ts7 from "typescript";
+import * as ts8 from "typescript";
 import {
-  createBinaryExpression as createBinaryExpression4,
-  SyntaxKind as SyntaxKind10
+  createBinaryExpression as createBinaryExpression5,
+  SyntaxKind as SyntaxKind12
 } from "typescript-to-lua";
 var GUARD_MODULE2 = "@defold-typescript/types";
 var GUARD_NAME2 = "isWindowEvent";
@@ -2139,7 +2302,7 @@ function resolvesToGuardExport2(callee, checker) {
   if (symbol === undefined) {
     return false;
   }
-  if (symbol.flags & ts7.SymbolFlags.Alias) {
+  if (symbol.flags & ts8.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
   if (symbol.getName() !== GUARD_NAME2) {
@@ -2153,12 +2316,12 @@ function resolvesToGuardExport2(callee, checker) {
 }
 var windowEventGuardLoweringPlugin = {
   visitors: {
-    [ts7.SyntaxKind.CallExpression]: (node, context) => {
+    [ts8.SyntaxKind.CallExpression]: (node, context) => {
       const [eventArg, , expectedArg] = node.arguments;
       if (node.arguments.length === 3 && eventArg !== undefined && expectedArg !== undefined && resolvesToGuardExport2(node.expression, context.checker)) {
         const event = context.transformExpression(eventArg);
         const expected = context.transformExpression(expectedArg);
-        return createBinaryExpression4(event, expected, SyntaxKind10.EqualityOperator, node);
+        return createBinaryExpression5(event, expected, SyntaxKind12.EqualityOperator, node);
       }
       return context.superTransformExpression(node);
     }
@@ -2171,14 +2334,15 @@ var LUA_PLUGINS = [
   messageGuardLoweringPlugin,
   windowEventGuardLoweringPlugin,
   messageDispatchLoweringPlugin,
-  timersLoweringPlugin
+  timersLoweringPlugin,
+  arrayIndexOptionLoweringPlugin
 ];
 var noopWriteFile = () => {};
 function isAmbient(fileName) {
   return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
 }
 function getProgramDiagnostics(program, sourceFile) {
-  const { diagnostics } = tstl.getProgramTranspileResult(ts8.sys, noopWriteFile, {
+  const { diagnostics } = tstl.getProgramTranspileResult(ts9.sys, noopWriteFile, {
     program,
     plugins: LUA_PLUGINS,
     ...sourceFile ? { sourceFiles: [sourceFile] } : {}
@@ -2749,11 +2913,11 @@ function relativeAddressesFrom(index, context) {
 import { readFileSync as readFileSync2 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import * as path3 from "node:path";
-import * as ts12 from "typescript";
+import * as ts13 from "typescript";
 import * as tstl3 from "typescript-to-lua";
 
 // src/companion-emit.ts
-import * as ts9 from "typescript";
+import * as ts10 from "typescript";
 import {
   createAssignmentStatement as createAssignmentStatement2,
   createCallExpression as createCallExpression4,
@@ -2766,18 +2930,18 @@ import {
   createTableIndexExpression as createTableIndexExpression2,
   createVariableDeclarationStatement as createVariableDeclarationStatement3,
   isBlock as isBlock3,
-  isCallExpression as isCallExpression4,
+  isCallExpression as isCallExpression5,
   isDoStatement,
   isForInStatement as isForInStatement2,
   isForStatement,
   isFunctionDefinition,
   isFunctionExpression as isFunctionExpression4,
-  isIdentifier as isIdentifier4,
+  isIdentifier as isIdentifier5,
   isMethodCallExpression,
   isRepeatStatement,
   isReturnStatement as isReturnStatement2,
-  isStringLiteral as isStringLiteral6,
-  isTableExpression,
+  isStringLiteral as isStringLiteral8,
+  isTableExpression as isTableExpression2,
   isVariableDeclarationStatement,
   LuaPrinter
 } from "typescript-to-lua";
@@ -2787,8 +2951,8 @@ function exportsIdentifier() {
 }
 function isRuntimeScriptSource(sourceFile, checker) {
   return sourceFile.statements.some((statement) => {
-    const expression = ts9.isExpressionStatement(statement) ? statement.expression : ts9.isExportAssignment(statement) && !statement.isExportEquals ? statement.expression : undefined;
-    return expression !== undefined && ts9.isCallExpression(expression) && resolvesToFactoryExport(expression.expression, checker);
+    const expression = ts10.isExpressionStatement(statement) ? statement.expression : ts10.isExportAssignment(statement) && !statement.isExportEquals ? statement.expression : undefined;
+    return expression !== undefined && ts10.isCallExpression(expression) && resolvesToFactoryExport(expression.expression, checker);
   });
 }
 function planFor(sourceFile, checker) {
@@ -2849,7 +3013,7 @@ function freeNames(statements) {
     if (node === undefined) {
       return;
     }
-    if (isIdentifier4(node)) {
+    if (isIdentifier5(node)) {
       if (!isBound(node.text)) {
         free.add(node.text);
       }
@@ -2940,11 +3104,11 @@ function freeNames(statements) {
 function resolvedRequirePaths(sourceFile, checker) {
   const paths = new Map;
   for (const statement of sourceFile.statements) {
-    const specifier = ts9.isImportDeclaration(statement) || ts9.isExportDeclaration(statement) ? statement.moduleSpecifier : undefined;
-    if (specifier === undefined || !ts9.isStringLiteral(specifier)) {
+    const specifier = ts10.isImportDeclaration(statement) || ts10.isExportDeclaration(statement) ? statement.moduleSpecifier : undefined;
+    if (specifier === undefined || !ts10.isStringLiteral(specifier)) {
       continue;
     }
-    const target = checker.getSymbolAtLocation(specifier)?.declarations?.find((declaration) => ts9.isSourceFile(declaration));
+    const target = checker.getSymbolAtLocation(specifier)?.declarations?.find((declaration) => ts10.isSourceFile(declaration));
     if (target === undefined || target.isDeclarationFile) {
       continue;
     }
@@ -2955,14 +3119,14 @@ function resolvedRequirePaths(sourceFile, checker) {
 function resolveMovedRequires(statements, paths) {
   for (const statement of statements) {
     forEachLuaNode(statement, (node) => {
-      if (!isCallExpression4(node) || !isIdentifier4(node.expression)) {
+      if (!isCallExpression5(node) || !isIdentifier5(node.expression)) {
         return;
       }
       if (node.expression.text !== "require" || node.params.length !== 1) {
         return;
       }
       const [argument] = node.params;
-      if (argument === undefined || !isStringLiteral6(argument)) {
+      if (argument === undefined || !isStringLiteral8(argument)) {
         return;
       }
       const resolved = paths.get(argument.value);
@@ -2978,14 +3142,14 @@ function withResolvedRequire(statement, paths) {
   }
   const name = statement.left[0];
   const [value] = statement.right ?? [];
-  if (name === undefined || value === undefined || !isCallExpression4(value)) {
+  if (name === undefined || value === undefined || !isCallExpression5(value)) {
     return statement;
   }
-  if (!isIdentifier4(value.expression) || value.expression.text !== "require") {
+  if (!isIdentifier5(value.expression) || value.expression.text !== "require") {
     return statement;
   }
   const [argument] = value.params;
-  if (argument === undefined || !isStringLiteral6(argument)) {
+  if (argument === undefined || !isStringLiteral8(argument)) {
     return statement;
   }
   const resolved = paths.get(argument.value);
@@ -3021,7 +3185,7 @@ function copiedPrelude(halves, importBindings) {
 function namesIdentifier(statement, names) {
   let found = false;
   forEachLuaNode(statement, (node) => {
-    if (isIdentifier4(node) && names.has(node.text)) {
+    if (isIdentifier5(node) && names.has(node.text)) {
       found = true;
     }
   });
@@ -3032,14 +3196,14 @@ function isExportsTableInit(statement) {
     return false;
   }
   const [single] = statement.right ?? [];
-  return statement.left[0]?.text === EXPORTS_NAME && single !== undefined && isTableExpression(single);
+  return statement.left[0]?.text === EXPORTS_NAME && single !== undefined && isTableExpression2(single);
 }
 function isExportsReturn(statement) {
   if (!isReturnStatement2(statement) || statement.expressions.length !== 1) {
     return false;
   }
   const [single] = statement.expressions;
-  return single !== undefined && isIdentifier4(single) && single.text === EXPORTS_NAME;
+  return single !== undefined && isIdentifier5(single) && single.text === EXPORTS_NAME;
 }
 function isHoistedNameDeclaration(statement) {
   return isVariableDeclarationStatement(statement) && statement.right === undefined;
@@ -3108,11 +3272,11 @@ function createCompanionEmitPlugin() {
     return statements;
   }
   const visitors = {
-    [ts9.SyntaxKind.VariableStatement]: capture,
-    [ts9.SyntaxKind.FunctionDeclaration]: capture,
-    [ts9.SyntaxKind.ClassDeclaration]: capture,
-    [ts9.SyntaxKind.EnumDeclaration]: capture,
-    [ts9.SyntaxKind.ExportDeclaration]: capture
+    [ts10.SyntaxKind.VariableStatement]: capture,
+    [ts10.SyntaxKind.FunctionDeclaration]: capture,
+    [ts10.SyntaxKind.ClassDeclaration]: capture,
+    [ts10.SyntaxKind.EnumDeclaration]: capture,
+    [ts10.SyntaxKind.ExportDeclaration]: capture
   };
   let configuredNoResolvePaths = [];
   const plugin = {
@@ -3181,7 +3345,7 @@ function emitCompanion(program, emitHost, file, sourceFile, plan, owned, compani
 }
 
 // src/editor-script-erasure.ts
-import * as ts10 from "typescript";
+import * as ts11 from "typescript";
 import {
   createReturnStatement as createReturnStatement3
 } from "typescript-to-lua";
@@ -3201,7 +3365,7 @@ function resolveEditorFactoryExport(callee, checker) {
   if (symbol === undefined) {
     return;
   }
-  if (symbol.flags & ts10.SymbolFlags.Alias) {
+  if (symbol.flags & ts11.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
   const name = symbol.getName();
@@ -3215,7 +3379,7 @@ function resolveEditorFactoryExport(callee, checker) {
   return declaration.getSourceFile().fileName.includes(EDITOR_FACTORY_MODULE) ? name : undefined;
 }
 function lowerEditorFactoryCall(expression, context) {
-  if (!ts10.isCallExpression(expression)) {
+  if (!ts11.isCallExpression(expression)) {
     return;
   }
   if (resolveEditorFactoryExport(expression.expression, context.checker) !== EDITOR_SCRIPT_FACTORY_NAME) {
@@ -3228,7 +3392,7 @@ function lowerEditorFactoryCall(expression, context) {
   return [createReturnStatement3([context.transformExpression(module)])];
 }
 function isEditorFactoryOnlyImport(node) {
-  if (!ts10.isStringLiteral(node.moduleSpecifier) || !EDITOR_FACTORY_SPECIFIERS.has(node.moduleSpecifier.text)) {
+  if (!ts11.isStringLiteral(node.moduleSpecifier) || !EDITOR_FACTORY_SPECIFIERS.has(node.moduleSpecifier.text)) {
     return false;
   }
   const clause = node.importClause;
@@ -3239,7 +3403,7 @@ function isEditorFactoryOnlyImport(node) {
     return false;
   }
   const bindings = clause.namedBindings;
-  if (bindings === undefined || !ts10.isNamedImports(bindings)) {
+  if (bindings === undefined || !ts11.isNamedImports(bindings)) {
     return false;
   }
   const runtime = bindings.elements.filter((element) => !element.isTypeOnly);
@@ -3250,7 +3414,7 @@ function isEditorFactoryOnlyImport(node) {
 }
 var editorScriptErasurePlugin = {
   visitors: {
-    [ts10.SyntaxKind.ExportAssignment]: (node, context) => {
+    [ts11.SyntaxKind.ExportAssignment]: (node, context) => {
       if (!node.isExportEquals) {
         const lowered = lowerEditorFactoryCall(node.expression, context);
         if (lowered !== undefined) {
@@ -3259,14 +3423,14 @@ var editorScriptErasurePlugin = {
       }
       return context.superTransformStatements(node);
     },
-    [ts10.SyntaxKind.CallExpression]: (node, context) => {
+    [ts11.SyntaxKind.CallExpression]: (node, context) => {
       const command = node.arguments[0];
       if (command !== undefined && resolveEditorFactoryExport(node.expression, context.checker) === EDITOR_COMMAND_FACTORY_NAME) {
         return context.transformExpression(command);
       }
       return context.superTransformExpression(node);
     },
-    [ts10.SyntaxKind.ImportDeclaration]: (node, context) => isEditorFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
+    [ts11.SyntaxKind.ImportDeclaration]: (node, context) => isEditorFactoryOnlyImport(node) ? [] : context.superTransformStatements(node)
   }
 };
 
@@ -3277,17 +3441,17 @@ import * as path2 from "node:path";
 import * as tstl2 from "typescript-to-lua";
 
 // src/go-property-direct-call.ts
-import * as ts11 from "typescript";
+import * as ts12 from "typescript";
 var GO_PROPERTY_DIRECT_CALL_MESSAGE = "`go.property` called directly is deprecated; declare the property in `defineScript({ properties })` so it types onto `self` (the transpiler emits the registration for you).";
 function findDirectGoPropertyCalls(sourceFile) {
   const calls = [];
   const visit = (node) => {
-    if (ts11.isCallExpression(node) && ts11.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts11.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
+    if (ts12.isCallExpression(node) && ts12.isPropertyAccessExpression(node.expression) && node.expression.name.text === "property" && ts12.isIdentifier(node.expression.expression) && node.expression.expression.text === "go") {
       calls.push(node);
     }
-    ts11.forEachChild(node, visit);
+    ts12.forEachChild(node, visit);
   };
-  ts11.forEachChild(sourceFile, visit);
+  ts12.forEachChild(sourceFile, visit);
   return calls;
 }
 
@@ -3467,6 +3631,7 @@ function transpileProject(input) {
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: arrayIndexOptionLoweringPlugin },
       { plugin: companionEmit.plugin }
     ]
   });
@@ -3497,6 +3662,7 @@ function compilerOptions(companionEmit) {
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: arrayIndexOptionLoweringPlugin },
       { plugin: companionEmit.plugin }
     ]
   };
@@ -3539,7 +3705,7 @@ function createTranspileSession() {
       if (cached) {
         return cached;
       }
-      const created = ts12.createSourceFile(fileName, content, ts12.ScriptTarget.Latest, false);
+      const created = ts13.createSourceFile(fileName, content, ts13.ScriptTarget.Latest, false);
       sourceFileCache.set(normalized, created);
       return created;
     }
@@ -3558,7 +3724,7 @@ function createTranspileSession() {
         return cached;
       }
       const fileContent = readFileSync2(filePath, "utf8");
-      const created = ts12.createSourceFile(filePath, fileContent, ts12.ScriptTarget.Latest, false);
+      const created = ts13.createSourceFile(filePath, fileContent, ts13.ScriptTarget.Latest, false);
       libCache.set(fileName, created);
       return created;
     }
@@ -3571,10 +3737,10 @@ function createTranspileSession() {
     return AMBIENT_FILES[normalized];
   }
   const host = {
-    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts12.sys.fileExists(fileName),
+    fileExists: (fileName) => mergedContent(normalizeSlashes(fileName)) !== undefined || ts13.sys.fileExists(fileName),
     getCanonicalFileName: (fileName) => fileName,
     getCurrentDirectory: () => "",
-    getDefaultLibFileName: ts12.getDefaultLibFileName,
+    getDefaultLibFileName: ts13.getDefaultLibFileName,
     readFile: () => "",
     getNewLine: () => `
 `,
@@ -3596,15 +3762,15 @@ function createTranspileSession() {
     const userKeys = new Set(userFiles.keys());
     const rootNames = [...Object.keys(AMBIENT_FILES).map(normalizeSlashes), ...userKeys];
     const companionEmit = createCompanionEmitPlugin();
-    program = ts12.createProgram(rootNames, compilerOptions(companionEmit), host, program);
-    const preEmitDiagnostics = ts12.getPreEmitDiagnostics(program);
+    program = ts13.createProgram(rootNames, compilerOptions(companionEmit), host, program);
+    const preEmitDiagnostics = ts13.getPreEmitDiagnostics(program);
     const collector = createOutputCollector();
     const { diagnostics: transpileDiagnostics } = new tstl3.Transpiler().emit({
       program,
       writeFile: collector.writeFile
     });
     const diagnostics = [
-      ...ts12.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
+      ...ts13.sortAndDeduplicateDiagnostics([...preEmitDiagnostics, ...transpileDiagnostics])
     ];
     return collectOutputs(collector.files, diagnostics, userKeys, companionEmit.companions);
   }
@@ -3614,7 +3780,7 @@ function createTranspileSession() {
   };
 }
 // src/url-address-slots.ts
-import * as ts13 from "typescript";
+import * as ts14 from "typescript";
 var ADDRESS_CLASSES = {
   "game-object": true,
   component: true,
@@ -3633,7 +3799,7 @@ function isFragmentCaret(slot, position) {
   return slot.fragmentStart !== -1 && position >= slot.fragmentStart;
 }
 function tableKey(checker, callee) {
-  const symbol = checker.getSymbolAtLocation(ts13.isIdentifier(callee) ? callee : callee.name);
+  const symbol = checker.getSymbolAtLocation(ts14.isIdentifier(callee) ? callee : callee.name);
   if (!symbol)
     return;
   const fqn = checker.getFullyQualifiedName(symbol);
@@ -3641,43 +3807,43 @@ function tableKey(checker, callee) {
 }
 function parameterName(checker, call, index) {
   const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (!declaration || !ts13.isFunctionLike(declaration))
+  if (!declaration || !ts14.isFunctionLike(declaration))
     return;
   const parameter = declaration.parameters[index];
-  if (!parameter || parameter.dotDotDotToken || !ts13.isIdentifier(parameter.name))
+  if (!parameter || parameter.dotDotDotToken || !ts14.isIdentifier(parameter.name))
     return;
   return parameter.name.text;
 }
 var EQUALITY_OPERATORS = new Set([
-  ts13.SyntaxKind.EqualsEqualsEqualsToken,
-  ts13.SyntaxKind.ExclamationEqualsEqualsToken,
-  ts13.SyntaxKind.EqualsEqualsToken,
-  ts13.SyntaxKind.ExclamationEqualsToken
+  ts14.SyntaxKind.EqualsEqualsEqualsToken,
+  ts14.SyntaxKind.ExclamationEqualsEqualsToken,
+  ts14.SyntaxKind.EqualsEqualsToken,
+  ts14.SyntaxKind.ExclamationEqualsToken
 ]);
 function comparisonSatisfied(checker, entry, call) {
   if (entry.comparedParameter === undefined)
     return true;
   let node = call;
-  while (ts13.isParenthesizedExpression(node.parent))
+  while (ts14.isParenthesizedExpression(node.parent))
     node = node.parent;
   const comparison = node.parent;
-  if (!ts13.isBinaryExpression(comparison))
+  if (!ts14.isBinaryExpression(comparison))
     return false;
   if (!EQUALITY_OPERATORS.has(comparison.operatorToken.kind))
     return false;
   const other = comparison.left === node ? comparison.right : comparison.left;
   const symbol = checker.getSymbolAtLocation(other);
-  return (symbol?.declarations ?? []).some((declaration) => ts13.isParameter(declaration) && ts13.isIdentifier(declaration.name) && declaration.name.text === entry.comparedParameter);
+  return (symbol?.declarations ?? []).some((declaration) => ts14.isParameter(declaration) && ts14.isIdentifier(declaration.name) && declaration.name.text === entry.comparedParameter);
 }
 function classifiedEntryOfArgument(checker, table, argument) {
   const call = argument.parent;
-  if (!ts13.isCallExpression(call))
+  if (!ts14.isCallExpression(call))
     return;
   const argumentIndex = call.arguments.indexOf(argument);
   if (argumentIndex === -1)
     return;
   const callee = call.expression;
-  if (!ts13.isPropertyAccessExpression(callee) && !ts13.isIdentifier(callee))
+  if (!ts14.isPropertyAccessExpression(callee) && !ts14.isIdentifier(callee))
     return;
   const fqn = tableKey(checker, callee);
   if (fqn === undefined)
@@ -3694,10 +3860,10 @@ function classifiedEntryOfArgument(checker, table, argument) {
 }
 function slotThroughHashedCall(checker, table, literal) {
   const call = literal.parent;
-  if (!ts13.isCallExpression(call))
+  if (!ts14.isCallExpression(call))
     return;
   const callee = call.expression;
-  if (!ts13.isPropertyAccessExpression(callee) && !ts13.isIdentifier(callee))
+  if (!ts14.isPropertyAccessExpression(callee) && !ts14.isIdentifier(callee))
     return;
   if (tableKey(checker, callee) !== "hash")
     return;
@@ -3715,24 +3881,24 @@ function addressTextOf(checker, entry, call) {
   if (entry.addressParameter === undefined)
     return;
   const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (!declaration || !ts13.isFunctionLike(declaration))
+  if (!declaration || !ts14.isFunctionLike(declaration))
     return;
-  const index = declaration.parameters.findIndex((parameter) => !parameter.dotDotDotToken && ts13.isIdentifier(parameter.name) && parameter.name.text === entry.addressParameter);
+  const index = declaration.parameters.findIndex((parameter) => !parameter.dotDotDotToken && ts14.isIdentifier(parameter.name) && parameter.name.text === entry.addressParameter);
   if (index === -1)
     return;
   const argument = call.arguments[index];
-  return argument && ts13.isStringLiteralLike(argument) ? argument.text : undefined;
+  return argument && ts14.isStringLiteralLike(argument) ? argument.text : undefined;
 }
 function innermostLiteralAt(sourceFile, position) {
   let found;
   const visit = (node) => {
     if (position < node.getStart(sourceFile) || position > node.getEnd())
       return;
-    if (ts13.isStringLiteralLike(node))
+    if (ts14.isStringLiteralLike(node))
       found = node;
-    ts13.forEachChild(node, visit);
+    ts14.forEachChild(node, visit);
   };
-  ts13.forEachChild(sourceFile, visit);
+  ts14.forEachChild(sourceFile, visit);
   return found;
 }
 function resolveClassifiedSlotAtPosition(input) {
@@ -3766,23 +3932,23 @@ function resolveClassifiedSlotAtPosition(input) {
   };
 }
 // src/url-cross-world-address.ts
-import * as ts15 from "typescript";
+import * as ts16 from "typescript";
 
 // src/url-address-literals.ts
-import * as ts14 from "typescript";
+import * as ts15 from "typescript";
 function isAmbient2(fileName) {
   return /[\\/]node_modules[\\/]/.test(fileName) || /(^|[\\/])lib\.[^\\/]*\.d\.ts$/.test(fileName);
 }
 function referenceTargetSymbol(type) {
-  if ((type.flags & ts14.TypeFlags.Object) === 0)
+  if ((type.flags & ts15.TypeFlags.Object) === 0)
     return;
-  if ((type.objectFlags & ts14.ObjectFlags.Reference) === 0)
+  if ((type.objectFlags & ts15.ObjectFlags.Reference) === 0)
     return;
   return type.target.symbol;
 }
 function ambientHashAliasTargets(checker, anchor) {
   const targets = new Set;
-  for (const symbol of checker.getSymbolsInScope(anchor, ts14.SymbolFlags.Type)) {
+  for (const symbol of checker.getSymbolsInScope(anchor, ts15.SymbolFlags.Type)) {
     if (symbol.name !== "Hash")
       continue;
     const target = referenceTargetSymbol(checker.getDeclaredTypeOfSymbol(symbol));
@@ -3798,7 +3964,7 @@ function canonicalHashSymbols(checker, program) {
   if (!anchor)
     return canonical;
   const aliased = ambientHashAliasTargets(checker, anchor);
-  for (const symbol of checker.getSymbolsInScope(anchor, ts14.SymbolFlags.Function)) {
+  for (const symbol of checker.getSymbolsInScope(anchor, ts15.SymbolFlags.Function)) {
     if (symbol.name !== "hash")
       continue;
     const declaration = symbol.declarations?.[0];
@@ -3820,7 +3986,7 @@ function hashedSourceOfType(checker, type, canonical) {
   return source?.isStringLiteral() ? source.value : undefined;
 }
 function staticAddressTextOf(checker, node, canonical) {
-  return ts14.isStringLiteralLike(node) ? node.text : hashedSourceOfType(checker, checker.getTypeAtLocation(node), canonical);
+  return ts15.isStringLiteralLike(node) ? node.text : hashedSourceOfType(checker, checker.getTypeAtLocation(node), canonical);
 }
 
 // src/url-cross-world-address.ts
@@ -3844,7 +4010,7 @@ function checkCrossWorldAddresses(input) {
     if (worlds.length === 0)
       continue;
     const visit = (node) => {
-      if (ts15.isExpression(node)) {
+      if (ts16.isExpression(node)) {
         const entry = addressEntryOfArgument(checker, table, node);
         if (entry !== undefined && slotRejectsForeignSocket(entry)) {
           const address = staticAddressTextOf(checker, node, canonical);
@@ -3861,14 +4027,14 @@ function checkCrossWorldAddresses(input) {
           }
         }
       }
-      ts15.forEachChild(node, visit);
+      ts16.forEachChild(node, visit);
     };
-    ts15.forEachChild(sourceFile, visit);
+    ts16.forEachChild(sourceFile, visit);
   }
   return findings;
 }
 // src/url-fragment-reachability.ts
-import * as ts16 from "typescript";
+import * as ts17 from "typescript";
 function pathOfKey(key) {
   const socket = socketOfAddress(key);
   return socket === undefined ? key : key.slice(socket.length + 1);
@@ -3913,7 +4079,7 @@ function checkUrlFragmentReachability(input) {
     if (isAmbient2(sourceFile.fileName))
       continue;
     const visit = (node) => {
-      if (ts16.isExpression(node) && isAddressClass(addressClassOfArgument(checker, table, node))) {
+      if (ts17.isExpression(node) && isAddressClass(addressClassOfArgument(checker, table, node))) {
         const text = staticAddressTextOf(checker, node, canonical);
         if (text !== undefined) {
           const hash = text.indexOf("#");
@@ -3932,9 +4098,9 @@ function checkUrlFragmentReachability(input) {
           }
         }
       }
-      ts16.forEachChild(node, visit);
+      ts17.forEachChild(node, visit);
     };
-    ts16.forEachChild(sourceFile, visit);
+    ts17.forEachChild(sourceFile, visit);
   }
   return { kind: "checked", findings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.39.0",
+    "@defold-typescript/types": "0.40.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript-to-lua": "^1.36.0"
   }

package/src/array-index-option-lowering.ts

@@ -0,0 +1,212 @@
+import * as ts from "typescript";
+import {
+  createBinaryExpression,
+  createNumericLiteral,
+  type Expression,
+  getOriginalPos,
+  isCallExpression,
+  isNumericLiteral,
+  isStringLiteral,
+  isTableExpression,
+  type Plugin,
+  SyntaxKind,
+  setNodePosition,
+  type TableExpression,
+} from "typescript-to-lua";
+
+// The Defold functions whose `options.index` upstream documents as "index into
+// array property (1 based)". TypeScript authors it zero-based; the lowering
+// adds the one Lua expects.
+export const ONE_BASED_INDEX_OPTION_APIS: ReadonlySet<string> = new Set([
+  "go.get",
+  "go.set",
+  "gui.get",
+  "gui.set",
+]);
+
+export const INDEX_OPTION_VARIABLE_MESSAGE =
+  "`options.index` is zero-based and is converted to Defold's 1-based index only in an object literal written at the call; pass the options inline.";
+export const INDEX_OPTION_SPREAD_MESSAGE =
+  "A spread carrying `index` cannot be converted to Defold's 1-based index; write `index` explicitly after the spread.";
+export const INDEX_OPTION_UNDEFINED_MESSAGE =
+  "`options.index` may be undefined here, so it cannot be converted to Defold's 1-based index; pass a number, or leave `index` out.";
+
+const OPTIONS_PARAMETER = "options";
+const INDEX_KEY = "index";
+
+const loweredLiterals = new WeakSet<ts.Node>();
+
+// Keyed like `tableKey` in url-address-slots.ts: only a symbol declared in an
+// ambient `declare global` block carries the `global.` prefix, so a project's
+// own `go` or `gui` never matches. Walking up from the signature declaration
+// reaches `go.get<P>()` from the function type its curried inner call resolves to.
+function oneBasedApi(declaration: ts.Declaration, checker: ts.TypeChecker): boolean {
+  let node: ts.Node | undefined = declaration;
+  while (node !== undefined && !ts.isFunctionDeclaration(node)) node = node.parent;
+  if (node?.name === undefined) return false;
+  const symbol = checker.getSymbolAtLocation(node.name);
+  if (symbol === undefined) return false;
+  const fqn = checker.getFullyQualifiedName(symbol);
+  return fqn.startsWith("global.") && ONE_BASED_INDEX_OPTION_APIS.has(fqn.slice("global.".length));
+}
+
+function optionsArgument(
+  call: ts.CallExpression,
+  checker: ts.TypeChecker,
+): ts.Expression | undefined {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (declaration === undefined || !ts.isFunctionLike(declaration)) return undefined;
+  if (!oneBasedApi(declaration, checker)) return undefined;
+  const index = declaration.parameters.findIndex(
+    (parameter) =>
+      parameter.dotDotDotToken === undefined &&
+      ts.isIdentifier(parameter.name) &&
+      parameter.name.text === OPTIONS_PARAMETER,
+  );
+  return index === -1 ? undefined : call.arguments[index];
+}
+
+function unwrap(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isTypeAssertionExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function someConstituent(type: ts.Type, predicate: (type: ts.Type) => boolean): boolean {
+  return type.isUnion() ? type.types.some(predicate) : predicate(type);
+}
+
+function carriesIndex(type: ts.Type): boolean {
+  return someConstituent(type, (t) => t.getProperty(INDEX_KEY) !== undefined);
+}
+
+function admitsUndefined(type: ts.Type): boolean {
+  return someConstituent(
+    type,
+    (t) => (t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0,
+  );
+}
+
+function propertyName(
+  property: ts.ObjectLiteralElementLike,
+  checker: ts.TypeChecker,
+): string | undefined {
+  const name = property.name;
+  if (name === undefined) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+    return name.text;
+  }
+  if (ts.isComputedPropertyName(name)) {
+    const type = checker.getTypeAtLocation(name.expression);
+    if (type.isStringLiteral()) return type.value;
+  }
+  return undefined;
+}
+
+function indexValueType(
+  property: ts.ObjectLiteralElementLike,
+  checker: ts.TypeChecker,
+): ts.Type | undefined {
+  if (ts.isPropertyAssignment(property)) return checker.getTypeAtLocation(property.initializer);
+  if (ts.isShorthandPropertyAssignment(property)) return checker.getTypeAtLocation(property.name);
+  return undefined;
+}
+
+function rejection(node: ts.Node, messageText: string): ts.Diagnostic {
+  const file = node.getSourceFile();
+  const start = node.getStart(file);
+  return {
+    file,
+    start,
+    length: node.getEnd() - start,
+    category: ts.DiagnosticCategory.Error,
+    code: 0,
+    messageText,
+  };
+}
+
+// The first reason `options` cannot be lowered, or `undefined` when it can.
+function rejectOptions(options: ts.Expression, checker: ts.TypeChecker): ts.Diagnostic | undefined {
+  const literal = unwrap(options);
+  if (!ts.isObjectLiteralExpression(literal)) {
+    return carriesIndex(checker.getTypeAtLocation(literal))
+      ? rejection(options, INDEX_OPTION_VARIABLE_MESSAGE)
+      : undefined;
+  }
+  let uncoveredSpread: ts.SpreadAssignment | undefined;
+  let explicitIndex: ts.ObjectLiteralElementLike | undefined;
+  for (const property of literal.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      if (carriesIndex(checker.getTypeAtLocation(property.expression))) uncoveredSpread = property;
+    } else if (propertyName(property, checker) === INDEX_KEY) {
+      uncoveredSpread = undefined;
+      explicitIndex = property;
+    }
+  }
+  if (uncoveredSpread !== undefined) return rejection(uncoveredSpread, INDEX_OPTION_SPREAD_MESSAGE);
+  const valueType = explicitIndex && indexValueType(explicitIndex, checker);
+  if (explicitIndex !== undefined && valueType !== undefined && admitsUndefined(valueType)) {
+    return rejection(explicitIndex, INDEX_OPTION_UNDEFINED_MESSAGE);
+  }
+  return undefined;
+}
+
+function plusOne(value: Expression): Expression {
+  if (isNumericLiteral(value)) {
+    return setNodePosition(createNumericLiteral(value.value + 1), getOriginalPos(value));
+  }
+  return setNodePosition(
+    createBinaryExpression(value, createNumericLiteral(1), SyntaxKind.AdditionOperator),
+    getOriginalPos(value),
+  );
+}
+
+// `rejectOptions` guarantees the last `index` field is the effective one: a
+// spread carrying `index` after it is rejected. Every earlier one is shadowed
+// and keeps its source value.
+function offsetEffectiveIndexField(tables: readonly TableExpression[]): void {
+  for (const field of tables.flatMap((table) => table.fields).reverse()) {
+    if (field.key !== undefined && isStringLiteral(field.key) && field.key.value === INDEX_KEY) {
+      field.value = plusOne(field.value);
+      return;
+    }
+  }
+}
+
+export const arrayIndexOptionLoweringPlugin: Plugin = {
+  visitors: {
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      const options = optionsArgument(node, context.checker);
+      if (options !== undefined) {
+        const diagnostic = rejectOptions(options, context.checker);
+        if (diagnostic !== undefined) {
+          context.diagnostics.push(diagnostic);
+        } else {
+          const literal = unwrap(options);
+          if (ts.isObjectLiteralExpression(literal)) loweredLiterals.add(literal);
+        }
+      }
+      return context.superTransformExpression(node);
+    },
+    // A spread lowers the literal to `__TS__ObjectAssign({}, base, {index = …})`,
+    // so the table carrying `index` can sit one call deep.
+    [ts.SyntaxKind.ObjectLiteralExpression]: (node, context): Expression => {
+      const result = context.superTransformExpression(node);
+      if (!loweredLiterals.has(node)) return result;
+      if (isTableExpression(result)) {
+        offsetEffectiveIndexField([result]);
+      } else if (isCallExpression(result)) {
+        offsetEffectiveIndexField(result.params.filter(isTableExpression));
+      }
+      return result;
+    },
+  },
+};

package/src/program-diagnostics.ts

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
+import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
 import { messageDispatchLoweringPlugin } from "./message-dispatch-lowering";
 import { messageGuardLoweringPlugin } from "./message-guard-lowering";
@@ -14,6 +15,7 @@ const LUA_PLUGINS: tstl.Plugin[] = [
   windowEventGuardLoweringPlugin,
   messageDispatchLoweringPlugin,
   timersLoweringPlugin,
+  arrayIndexOptionLoweringPlugin,
 ];
 
 const noopWriteFile: ts.WriteFileCallback = () => {};

package/src/session.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
+import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { type CompanionEmitter, createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import { lifecycleErasurePlugin } from "./lifecycle-erasure";
@@ -43,6 +44,7 @@ function compilerOptions(companionEmit: CompanionEmitter): tstl.CompilerOptions
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: arrayIndexOptionLoweringPlugin },
       { plugin: companionEmit.plugin },
     ],
   };

package/src/transpile.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import type * as ts from "typescript";
 import * as tstl from "typescript-to-lua";
+import { arrayIndexOptionLoweringPlugin } from "./array-index-option-lowering";
 import { createCompanionEmitPlugin } from "./companion-emit";
 import { editorScriptErasurePlugin } from "./editor-script-erasure";
 import {
@@ -321,6 +322,7 @@ export function transpileProject(input: TranspileProjectInput): TranspileProject
       { plugin: windowEventGuardLoweringPlugin },
       { plugin: messageDispatchLoweringPlugin },
       { plugin: timersLoweringPlugin },
+      { plugin: arrayIndexOptionLoweringPlugin },
       { plugin: companionEmit.plugin },
     ],
   });