TypeScriptToLua

https://typescripttolua.github.io/docs/
Admin
TypeScriptToLua (TSTL) is a transpiler that allows developers to write Lua code using TypeScript,...
Tokens:33,787
Snippets:274
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install TypeScriptToLua and TypeScript

Source: https://typescripttolua.github.io/docs/getting-started

Installs the latest version of TypeScriptToLua and TypeScript as development dependencies in your project using npm. This ensures reproducible builds and prevents version conflicts.

```bash
npm install --save-dev typescript-to-lua typescript
```

--------------------------------

### Plugin Setup with beforeTransform

Source: https://typescripttolua.github.io/docs/api/plugins

This TypeScript example demonstrates a plugin that uses the `beforeTransform` hook. This function is executed after the TypeScript program and options are gathered but before any Lua transformation begins, allowing for setup operations.

```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

class Plugin implements tstl.Plugin {
  public beforeTransform(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost) {
    console.log("Starting transformation of program", program, "with options", options);
  }
}

const plugin = new Plugin();
export default plugin;
```

--------------------------------

### Run npm Build Script

Source: https://typescripttolua.github.io/docs/getting-started

Executes the 'build' script defined in package.json, which runs the tstl command to compile the TypeScript project to Lua.

```bash
npm run build
```

--------------------------------

### Build Project with tstl CLI

Source: https://typescripttolua.github.io/docs/getting-started

Builds the TypeScript project into Lua using the TypeScriptToLua command-line interface (tstl). This command is typically run via npx to use the locally installed version.

```bash
npx tstl
```

--------------------------------

### Configure npm Scripts for Building and Watching

Source: https://typescripttolua.github.io/docs/getting-started

Defines npm scripts in package.json for building the project ('build') and building with watch mode ('dev'). This allows running tstl commands conveniently using npm.

```json
{
  "private": true,
  "scripts": {
    "build": "tstl",
    "dev": "tstl --watch"
  },
  "devDependencies": {
    "typescript-to-lua": "..."
  }
}
```

--------------------------------

### Install TypeScriptToLua using npm

Source: https://typescripttolua.github.io/docs/index

This command installs the 'typescript-to-lua' package as a development dependency using npm. It is a prerequisite for using the TypeScriptToLua compiler.

```bash
$ npm install -D typescript typescript-to-lua
```

--------------------------------

### Publishing TypeScript Declarations via npm

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Provides a step-by-step guide on how to publish TypeScript declaration files as an npm package. This allows other developers to easily install and use your project's type definitions, enhancing interoperability and developer experience.

```bash
npm init  
npm login               # Need npm account  
npm publish --dry-run   # Show what files will be published  
npm version 0.0.1       # Update the version in package.json when --dry-run seems good  
npm publish             # Publish to npm (only if you're 100% sure)  
```

```bash
npm install <declarations> --save-dev  
```

```json
{
  "compilerOptions": {
    "types": ["declarations"]
  }
}
```

--------------------------------

### Run npm Development Script (Watch Mode)

Source: https://typescripttolua.github.io/docs/getting-started

Executes the 'dev' script defined in package.json, which runs tstl in watch mode. This command compiles the TypeScript project to Lua and continues to monitor for file changes, recompiling automatically.

```bash
npm run dev
```

--------------------------------

### TypeScript Project File Inclusion Examples

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Illustrates how TypeScript's `tsconfig.json` file determines which files are included in a project, based on `rootDir` and `types` compiler options. It shows examples of file structures and how different configurations affect the included files.

```json
{
  "compilerOptions": {
    "rootDir": "src"
  }
}
```

```text
  node_modules/  
+ src/main.ts  
+ src/actors/Player.ts  
+ global.ts  
  tsconfig.json  
```

```json
{
  "compilerOptions": {
    "rootDir": "src",
    "types": ["lua-types/jit"]
  }
}
```

```text
+ node_modules/lua-types/jit.d.ts  
+ src/main.ts  
+ src/actors/Player.ts  
+ global.ts  
  tsconfig.json  
```

--------------------------------

### Basic tsconfig.json Configuration for TypeScriptToLua

Source: https://typescripttolua.github.io/docs/getting-started

Configures the TypeScript compiler and TypeScriptToLua settings. It specifies the target ECMAScript version, libraries, module resolution, strict type checking, and the target Lua version for the output.

```json
{
  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["ESNext"],
    "moduleResolution": "Node",
    "types": [],
    "strict": true
  },
  "tstl": {
    "luaTarget": "JIT"
  }
}
```

--------------------------------

### Lua Table Operations Output Example

Source: https://typescripttolua.github.io/docs/advanced/language-extensions

This Lua code demonstrates the output generated from the TypeScript `LuaTable` operations. It shows how `set`, `get`, and `length` calls in TypeScript are translated into direct Lua table assignments, access, and length operations.

```lua
tbl = {}

tbl.foo = "bar"
print(tbl.foo)

objectKey = {}
tbl[objectKey] = "baz"
print(tbl[objectKey])

tbl[1] = "bah"
print(#tbl)
```

--------------------------------

### Configuring Environmental Declarations with tsconfig.json

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

This example shows how to configure the 'lib' option in tsconfig.json to control which global type declarations are included. This is useful for excluding unsupported browser built-ins.

```json
{
  "compilerOptions": {
    "lib": ["esnext"]
  }
}
```

--------------------------------

### TypeScriptToLua tsconfig.json Configuration Example

Source: https://typescripttolua.github.io/docs/configuration

This JSON configuration file demonstrates how to set up TypeScriptToLua. It includes the optional schema for autocompletion and hints, standard tsconfig options, and a 'tstl' object for custom TypeScriptToLua transpilation settings.

```json
{
  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
  "compilerOptions": {
    "target": "ESNext"
  },
  "tstl": {
    "luaTarget": "universal",
    "buildMode": "library",
    "luaLibImport": "require",
    "sourceMapTraceback": true
  }
}
```

--------------------------------

### Install Lua Package from npm - Shell

Source: https://typescripttolua.github.io/docs/external-code

Commands to install a Lua package from npm using different package managers (npm, yarn, pnpm). This assumes the package is compatible with tstl.

```shell
# If you use npm:  
npm install foo --save  

# If you use yarn:  
yarn add foo  

# If you use pnpm:  
pnpm add foo  

```

--------------------------------

### Transpile with Custom Emit Options and Plugins

Source: https://typescripttolua.github.io/docs/api/overview

An example showcasing the advanced usage of the Transpiler class. It covers parsing tsconfig.json, creating a TypeScript program, handling source files in memory, and utilizing custom plugins during the transpilation process.

```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

// Parse existing tsconfig.json
const configFileName = path.resolve(__dirname, "tsconfig.json");
const parsedCommandLine = tstl.parseConfigFileWithSystem(configFileName);
if (parsedCommandLine.errors.length > 0) {
  parsedCommandLine.errors.forEach(reportDiagnostic);
  return;
}

// Set tstl-specific configuration options
parsedCommandLine.options.luaTarget = tstl.LuaTarget.Lua54;

// Create a TS program to feed to the transpiler
const program = ts.createProgram(parsedCommandLine.fileNames, parsedCommandLine.options);

// Create in-memory source file
const extraSourceFile = ts.createSourceFile("my-source-file.ts", "// my ts code");

const emitResults: Record<string, string> = {};

// Call the Typescript-to-Lua transpiler with emit options
const { diagnostics: transpileDiagnostics } = new tstl.Transpiler().transpile({
  program, // Provide the program to transpile, including compiler options!
  sourceFiles: [extraSourceFile],
  writeFile(fileName, data) {
    emitResults[fileName] = data; // Instead of writing to file, emit files to this object in memory
  },
  plugins: [
    // We can even provide plugins directly
    {
      beforeTransform(program, CompilerOptions, emitHost) {
        console.log("before transforming plugin hook!");
      },
      afterPrint(program, options, emitHost, result) {
        console.log("after printing plugin hook!");
      },
    },
  ],
});

// Use TS to report all diagnostics to console
const reportDiagnostic = tstl.createDiagnosticReporter(true);
const diagnostics = ts.sortAndDeduplicateDiagnostics([...ts.getPreEmitDiagnostics(program), ...transpileDiagnostics]);
diagnostics.forEach(reportDiagnostic);
```

--------------------------------

### Using Transformers in TypeScriptToLua Configuration

Source: https://typescripttolua.github.io/docs/configuration

This example shows how to configure transformers within the tsconfig.json file for TypeScriptToLua. Transformers allow modification of the compilation process, and this configuration specifies a transformer plugin to be used.

```json
{
  "compilerOptions": {
    "plugins": [
      { "transform": "dota-lua-types/transformer" }
    ]
  }
}
```

--------------------------------

### Import Lua Package from npm - TypeScript

Source: https://typescripttolua.github.io/docs/external-code

Example of importing a function from a Lua package installed via npm. Assumes the package includes necessary .d.ts files for tstl to resolve.

```typescript
import { someFunction } from "foo";  

someFunction();  

```

--------------------------------

### Lua Global Functions Example

Source: https://typescripttolua.github.io/docs/assigning-global-variables

Example of global functions defined in Lua for event handling. These are expected to be called by the host engine.

```lua
function OnStart()
    -- start event handling code
end

function OnStateChange(newState)
    -- state change event handler code
end

```

--------------------------------

### Declaring Globally Available Modules (utf8.d.ts)

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

This example shows how to declare a globally available module using 'declare module'. It defines the 'codepoint' function within the 'utf8' module, which can be imported in TypeScript.

```typescript
declare module "utf8" {  
  /**  
   * @noSelf  
   */  
  export function codepoint(): void;  
}  

```

--------------------------------

### Declaration Merging Example: Function and Table

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

This demonstrates declaration merging in TypeScript, where a function and a namespace are combined. It shows how to define a function and then add methods to its associated namespace, as seen with the 'assert' example.

```typescript
declare function assert(value: any, errorDescription?: string): void;
declare namespace assert {
  export function isEqual(): void;
}
```

```typescript
assert.isEqual();
assert();
```

--------------------------------

### JavaScript Object Key Example

Source: https://typescripttolua.github.io/docs/caveats

Demonstrates how JavaScript handles object keys with undefined and null values, and how iterating over Object.keys() includes them. This contrasts with Lua's behavior where assigning nil deletes the key.

```typescript
const foo = {};
foo.someProp1 = 123;
foo.someProp2 = undefined;
foo.someProp3 = null;
for (const key of Object.keys(foo)) {
  console.log(key);
}

```

--------------------------------

### Using Helper Function to Register Event Handlers

Source: https://typescripttolua.github.io/docs/assigning-global-variables

Example of using the `registerEventHandler` helper function to assign functions to global scope in TypeScript.

```typescript
registerEventHandler("OnStart", () => {
  // start event handling code
});
registerEventHandler("OnStateChanged", (newState: State) => {
  // state change event handler code
});

```

--------------------------------

### Log Emitted Files with afterEmit in TypeScript

Source: https://typescripttolua.github.io/docs/api/plugins

The `afterEmit` function is executed after all output files have been written to disk. This hook is useful for post-processing the generated Lua code, such as logging emitted file names. This example logs the output path of each emitted file.

```typescript
import * as ts from "typescript";  
import * as tstl from "typescript-to-lua";  
  
const plugin: tstl.Plugin = {  
  afterEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[]) {  
    for (const emittedFile of result) {  
      console.log(`Emitted file ${emittedFile.outputPath}`);  
    }
  },
};

export default plugin;  

```

--------------------------------

### Modify Output Files with beforeEmit in TypeScript

Source: https://typescripttolua.github.io/docs/api/plugins

The `beforeEmit` function allows plugins to modify the generated Lua code before it's written to disk. It receives the program, compiler options, emit host, and a list of files to be emitted. This example adds a comment to the beginning of each output file.

```typescript
import * as ts from "typescript";  
import * as tstl from "typescript-to-lua";  
  
const plugin: tstl.Plugin = {  
  beforeEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[]) {  
    // Add a comment to the start of all output files  
    for (const file of result) {  
      file.code = "-- Comment added by beforeEmit plugin\n" + file.code;  
    }
  },
};

export default plugin;  

```

--------------------------------

### Using Decorator to Register Class Methods

Source: https://typescripttolua.github.io/docs/assigning-global-variables

Example of using the `@registerEventHandler` decorator on class methods to automatically register them as global functions.

```typescript
class EventHandlers {
  @registerEventHandler
  public OnStart() {
    // start event handling code
  }
  @registerEventHandler
  public OnStateChanged(newState: State) {
    // state change event handler code
  }
}

```

--------------------------------

### Safe Array Operations Example

Source: https://typescripttolua.github.io/docs/caveats

Illustrates safe array operations in TypeScript that have consistent behavior between JavaScript and Lua when transpiled by TypeScriptToLua. These operations include push, pop, and splice.

```typescript
const myArray = [1, 2, 3];
myArray.push(4);
myArray.pop();
myArray.splice(1, 1);
// myArray.length == 2

```

--------------------------------

### Initialize and Emit with Transpiler

Source: https://typescripttolua.github.io/docs/api/overview

Demonstrates how to create an instance of the Transpiler class and use its emit method. It shows basic usage and how to provide a custom emitHost for custom file I/O operations.

```typescript
import * as tstl from "typescript-to-lua";

const { emitSkipped, diagnostics } = new tstl.Transpiler().emit(emitOptions);

// Provide a custom emitHost for custom reading/writing of files:
const { emitSkipped, diagnostics } = new tstl.Transpiler(customEmitHost).emit(emitOptions);
```

--------------------------------

### Using @registerClass Decorator (TypeScript)

Source: https://typescripttolua.github.io/docs/assigning-global-variables

This TypeScript example shows how to apply the `@registerClass` decorator to a class. When the class `EventHandlers` is defined with this decorator, it gets automatically registered in the global scope under its own name.

```typescript
@registerClass  
class EventHandlers {  
  public OnStart() {  
    // start event handling code  
  }  
  public OnStateChanged(newState: State) {  
    // state change event handler code  
  }  
}
```

--------------------------------

### Transpiler Class Usage

Source: https://typescripttolua.github.io/docs/api/overview

Demonstrates basic instantiation and usage of the Transpiler class to emit transpiled code.

```APIDOC
## Transpiler Class

### Description
The `Transpiler` class creates an instance of the tstl transpiler that is used to implement the high-level API. The transpiler allows passing a raw tstl program object and providing different transpilation parameters, such as the EmitHost object to be used to read/write files.

### Method
`new tstl.Transpiler([customEmitHost])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import * as tstl from "typescript-to-lua";

// Basic usage
const { emitSkipped, diagnostics } = new tstl.Transpiler().emit(emitOptions);

// Usage with a custom emitHost
const { emitSkipped, diagnostics } = new tstl.Transpiler(customEmitHost).emit(emitOptions);
```

### Response
#### Success Response (200)
Returns an object containing `emitSkipped` (boolean) and `diagnostics` (ts.Diagnostic[]).

#### Response Example
```json
{
  "emitSkipped": false,
  "diagnostics": [
    // ... ts.Diagnostic objects
  ]
}
```
```

--------------------------------

### Transpiler Emit Method Options

Source: https://typescripttolua.github.io/docs/api/overview

Details the options available for customizing the transpilation process via the `emit` method.

```APIDOC
## Transpiler.emit(emitOptions)

### Description
This method accepts an options object to customize the transpilation behavior.

### Method
`emit(emitOptions: TranspileOptions): EmitResult`

### Endpoint
N/A (Class method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`emitOptions` (object) - Options to customize transpilation:
- **program** (ts.Program) - The TypeScript program to transpile. `compilerOptions` are part of this program.
- **sourceFiles** (ts.SourceFile[]) - _Optional_ A collection of `SourceFile`s to transpile. Defaults to `program.getSourceFiles()`.
- **customTransformers** (ts.CustomTransformers) - _Optional_ List of extra TypeScript transformers.
- **plugins** (tstl.Plugin[]) - _Optional_ List of TypeScriptToLua plugins.
- **writeFile** (ts.WriteFileCallback) - _Optional_ A callback function to use for emitting the final file result, instead of writing to disk.

### Request Example
```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

// ... (setup program and other options)

const emitResults: Record<string, string> = {};

const { diagnostics } = new tstl.Transpiler().transpile({
  program,
  sourceFiles: [extraSourceFile],
  writeFile(fileName, data) {
    emitResults[fileName] = data;
  },
  plugins: [
    // ... plugin configuration
  ],
});
```

### Response
#### Success Response (200)
Returns an object containing `emitSkipped` (boolean) and `diagnostics` (ts.Diagnostic[]).

#### Response Example
```json
{
  "emitSkipped": false,
  "diagnostics": [
    // ... ts.Diagnostic objects
  ]
}
```
```

--------------------------------

### Run TypeScriptToLua Compiler

Source: https://typescripttolua.github.io/docs/index

This command executes the TypeScriptToLua compiler using npx. It is used to transpile TypeScript code into Lua code.

```bash
$ npx tstl
```

--------------------------------

### Configure Plugins in tsconfig.json

Source: https://typescripttolua.github.io/docs/api/plugins

This JSON configuration shows how to specify plugins for TypeScriptToLua in the `tsconfig.json` file. It demonstrates loading plugins from local JavaScript or TypeScript files, or from npm packages.

```json
{
  "tstl": {
    "luaPlugins": [
      { "name": "./plugin1.js" },
      { "name": "./plugin2.ts" },
      { "name": "tstl-plugin-3" }
    ]
  }
}
```

--------------------------------

### Package Configuration for npm Publishing (package.json)

Source: https://typescripttolua.github.io/docs/publishing-modules

Configures the package.json file for publishing a library to npm. It specifies which files to include, the main entry point, and type definitions.

```json
{
  "files": [
    "dist/**/*.lua",
    "dist/**/*.d.ts"
  ],
  "types": "./dist/index.d.ts",
  "main": "./dist/index"
}
```

--------------------------------

### Modify String Literal Transformation

Source: https://typescripttolua.github.io/docs/api/plugins

This TypeScript example shows a plugin that modifies the transformation of `StringLiteral` nodes. It uses `context.superTransformExpression` to call the default transformer and then changes the string value to 'bar'.

```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const plugin: tstl.Plugin = {
  visitors: {
    [ts.SyntaxKind.StringLiteral]: (node, context) => {
      const result = context.superTransformExpression(node);

      if (tstl.isStringLiteral(result)) {
        result.value = "bar";
      }

      return result;
    },
  },
};

export default plugin;
```

--------------------------------

### TranspileFiles API

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles a collection of TypeScript files to Lua, with optional compiler options.

```APIDOC
## TranspileFiles

### Description
Transpile a collection of TypeScript files to Lua.

### Method
POST

### Endpoint
/transpileFiles

### Parameters
#### Request Body
- **fileNames** (string[]) - Required - An array of file paths to the TypeScript files to be transpiled.
- **options** (tstl.CompilerOptions) - Optional - CompilerOptions to use.

### Request Example
```json
{
  "fileNames": ["file1.ts", "file2.ts"],
  "options": {
    "luaTarget": "Lua53"
  }
}
```

### Response
#### Success Response (200)
- **diagnostics** (object[]) - An array of diagnostic messages.
- **emitResult** (object) - The result of the emit operation.

#### Response Example
```json
{
  "diagnostics": [],
  "emitResult": {
    "emitSkipped": false,
    "emittedFiles": ["file1.lua", "file2.lua"]
  }
}
```
```

--------------------------------

### Declaring Namespace Functions (table.d.ts)

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

This example demonstrates how to declare functions within a namespace using 'declare namespace'. The '@noSelf' annotation indicates that the function should not be bound to the namespace table itself when called in Lua.

```typescript
declare namespace table {  
  /**  
   * @noSelf  
   */  
  export function insert(table: object, item: any): number;  
}  

```

--------------------------------

### beforeEmit Hook

Source: https://typescripttolua.github.io/docs/api/plugins

The `beforeEmit` function is called after the input program has been translated to Lua, after external dependencies have been resolved and included, and after bundling (if configured). This hook allows for modifications to the generated Lua code before it's written to disk.

```APIDOC
## `beforeEmit` Hook

### Description
Called after Lua translation, dependency resolution, and bundling. Allows modification of the generated Lua code before emission.

### Method
`beforeEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[])`

### Parameters
- `program` (ts.Program) - The TypeScript program.
- `options` (tstl.CompilerOptions) - The TypeScript-to-Lua compiler options.
- `emitHost` (tstl.EmitHost) - The emit host interface.
- `result` (tstl.EmitFile[]) - An array of objects representing the files to be emitted, each with a `code` property that can be modified.

### Request Example
```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const plugin: tstl.Plugin = {
  beforeEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[]) {
    // Add a comment to the start of all output files
    for (const file of result) {
      file.code = "-- Comment added by beforeEmit plugin\n" + file.code;
    }
  },
};

export default plugin;
```

### Response
This hook modifies the `result` array in place. No explicit return value is expected for success.
```

--------------------------------

### TranspileProject API

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles a TypeScript project to Lua, using a tsconfig.json file and optional extended compiler options.

```APIDOC
## TranspileProject

### Description
Transpile a TypeScript project to Lua.

### Method
POST

### Endpoint
/transpileProject

### Parameters
#### Request Body
- **tsConfigPath** (string) - Required - The file path to a TypeScript project's `tsconfig.json` file.
- **extendedOptions** (tstl.CompilerOptions) - Optional - The tsConfig already contains options, this extends those options.

### Request Example
```json
{
  "tsConfigPath": "tsconfig.json",
  "extendedOptions": {
    "luaTarget": "Lua53"
  }
}
```

### Response
#### Success Response (200)
- **diagnostics** (object[]) - An array of diagnostic messages.
- **emitResult** (object) - The result of the emit operation.

#### Response Example
```json
{
  "diagnostics": [],
  "emitResult": {
    "emitSkipped": false,
    "emittedFiles": ["file1.lua", "file2.lua"]
  }
}
```
```

--------------------------------

### Exporting Members from a Module (lib.d.ts)

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

The 'export' keyword is used to indicate that a member is available for external use. This example shows how to declare an exported variable 'x' from a hypothetical 'lib.lua' file, making it importable in TypeScript.

```typescript
export let x: number;  

```

--------------------------------

### Define and Use Image Interface in TypeScript

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Defines an 'Image' interface with methods to get dimensions and flags. The interface supports merging declarations. It's used to declare a global 'image' variable and access its methods.

```typescript
interface Image {  
  /** @tupleReturn */  
  getDimensions(): [number, number];  
}  
  
// This interface merges with its previous declaration  
/** @noSelf */  
interface Image {  
  getFlags(): object;  
}

declare let image: Image;  
let [w, h] = image.getDimensions(); // local w, h = image:getDimensions()  
let o = image.getFlags();  
```

--------------------------------

### Simulate Lua Classes with Tables and Metatables (TypeScript)

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Demonstrates simulating Lua classes using tables and metatables in TypeScript. It covers two patterns: one with a static 'new' method for construction and another with a callable table acting as a constructor.

```typescript
Box = {}
Box.__index = Box

function Box.new(value)
    local self = {}
    setmetatable(self, Box)
    self._value = value
    return self
end

function Box:get()
    return self._value
end

interface Box {
  get(): string;
}

interface BoxConstructor {
  new: (this: void, value: string) => Box;
}

declare var Box: BoxConstructor;

// Usage
const box = Box.new("foo");
box.get();
```

```typescript
Box = {}

local instance
function Box:getInstance()
    if instance then return instance end
    instance = Box("instance")
    return instance
end

setmetatable(Box, {
    __call = function(_, value)
        return { get = function() return value end }
    end
})

interface Box {
  get(): string;
}

interface BoxConstructor {
  (this: void, value: string): Box;
  getInstance(): Box;
}

declare var Box: BoxConstructor;

// Usage
const box = Box("foo");
box.get();
Box.getInstance().get();
```

--------------------------------

### Importing and Using Global Modules in TypeScript (main.ts)

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

This snippet demonstrates importing the 'utf8' module and calling its 'codepoint' function. The import statement is equivalent to `local utf8 = require("utf8");` in Lua.

```typescript
import * as utf8 from "utf8"; // equiv to `local utf8 = require("utf8");  
utf8.codepoint();  

```

--------------------------------

### TypeScript Functions with 'noImplicitSelf' Compiler Option

Source: https://typescripttolua.github.io/docs/the-self-parameter

Provides examples of TypeScript functions and class methods compiled to Lua with the 'noImplicitSelf' option enabled. It shows how regular functions and arrow functions behave differently regarding the 'self' parameter.

```typescript
function f() {}  
function f2(this: any) {}  
const a = () => {};  
class C {  
  method() {}  
}  
```

```lua
function f() end  
function f2(self) end  
local a = function() end  
  
local C = __TS__Class()  
function C:method(self) end -- still has self  
```

--------------------------------

### Standalone Custom Getters and Setters for LuaTable in TypeScript

Source: https://typescripttolua.github.io/docs/advanced/language-extensions

Provides an example of using standalone LuaTableGet and LuaTableSet functions in TypeScript for accessing and modifying Lua table values with non-string keys. This approach is useful when methods are not directly available on the table object.

```typescript
declare const idGet: LuaTableGet<IdDictionary, Id, string>;
declare const idSet: LuaTableSet<IdDictionary, Id, string>;
idSet(dict, id, "bar");
console.log(idGet(dict, id));
```

--------------------------------

### Configure Build Tasks with npm Scripts

Source: https://typescripttolua.github.io/docs/editor-support

Defines npm scripts for building and watching TypeScriptToLua projects. The 'build' script compiles the project, while 'dev' compiles and watches for changes. These scripts are essential for integrating with editor build systems.

```json
{
  "scripts": {
    "build": "tstl",
    "dev": "tstl --watch"
  }
}
```

--------------------------------

### Array Initialization and Filling in TypeScript to Lua

Source: https://typescripttolua.github.io/docs/caveats

Shows an alternative to the unsupported `new Array(length)` constructor in TypeScript-to-Lua. It utilizes `Array.prototype.fill` to create an array of a specific size with a default value.

```typescript
// const myNewArray = new Array(5); - new Array is not supported by typescript-to-lua

// Instead, use:

const myNewArray2 = ([] as number[]).fill(0, 0, 5); // Using this will create an array with 5 0's
```

--------------------------------

### Customize Module Resolution with moduleResolution in TypeScript

Source: https://typescripttolua.github.io/docs/api/plugins

The `moduleResolution` function allows plugins to intercept and modify how TypeScript-to-Lua resolves module dependencies. If the function returns a string, that string is used as the module identifier. If it returns `undefined`, tstl's default resolution is used. This example resolves the module 'foo' to 'bar'.

```typescript
import * as tstl from "typescript-to-lua";  
  
const plugin: tstl.Plugin = {  
  moduleResolution(  
    moduleIdentifier: string,  
    requiringFile: string,  
    options: tstl.CompilerOptions,  
    emitHost: tstl.EmitHost,  
  ) {  
    // If "foo" is required, resolve it as 'bar.lua'  
    if (moduleIdentifier === "foo") {  
      return "bar";  
    }
  },
};

export default plugin;  

```

--------------------------------

### Using Custom Global Name Decorator (TypeScript)

Source: https://typescripttolua.github.io/docs/assigning-global-variables

This TypeScript example demonstrates using the `@registerClass("CustomGlobalName")` decorator to register a class with a specific, custom global name. The `EventHandlers` class will be accessible globally via `globalThis["CustomGlobalName"]`.

```typescript
@registerClass("CustomGlobalName")  
class EventHandlers {  
  public OnStart() {  
    // start event handling code  
  }  
  public OnStateChanged(newState: State) {  
    // state change event handler code  
  }  
}
```

--------------------------------

### TranspileVirtualProject API

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles a virtual TypeScript project (files in memory) to Lua, with optional compiler options.

```APIDOC
## TranspileVirtualProject

### Description
Transpile a virtual project to Lua. A virtual project is a record (like an object literal for example) where keys are file names, and values are the contents of these files. This can be used to transpile a collection of files without having these files physically on disk.

### Method
POST

### Endpoint
/transpileVirtualProject

### Parameters
#### Request Body
- **files** (Record<string, string>) - Required - A record of fileName keys and fileContent values.
- **options** (tstl.CompilerOptions) - Optional - CompilerOptions to use.

### Request Example
```json
{
  "files": {
    "file1.ts": "const foo = \"bar\";",
    "file2.ts": "const bar = \"baz\";"
  },
  "options": {
    "luaTarget": "Lua53"
  }
}
```

### Response
#### Success Response (200)
- **diagnostics** (object[]) - An array of diagnostic messages.
- **transpiledFiles** (Record<string, string>) - A record of transpiled file names and their Lua content.

#### Response Example
```json
{
  "diagnostics": [],
  "transpiledFiles": {
    "file1.lua": "local foo = \"bar\"",
    "file2.lua": "local bar = \"baz\""
  }
}
```
```

--------------------------------

### Handle Lua Table Operations with LuaTable Type

Source: https://typescripttolua.github.io/docs/advanced/language-extensions

The LuaTable type in TypeScript provides a way to directly create and manipulate Lua tables, especially useful when keys are not strings. Methods like `get`, `set`, `has`, and `delete` on LuaTable instances are transpiled into their corresponding Lua table access syntax (e.g., `table[key]`, `table[key] = value`).

```typescript
const typedLuaTable = new LuaTable<KeyType, ValueType>();
const untypedLuaTable = new LuaTable(); // Same as LuaTable<AnyNotNil, any>

const tbl = new LuaTable();

tbl.set("foo", "bar");
console.log(tbl.get("foo"));

const objectKey = {};
tbl.set(objectKey, "baz");
console.log(tbl.get(objectKey));

tbl.set(1, "bah");
console.log(tbl.length());
```

--------------------------------

### Debugging TypeScript Declarations with tsc

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Shows how to use the TypeScript compiler (`tsc`) to list all files included by a `tsconfig.json` file. This command is useful for debugging declaration file issues and understanding which files are being processed by the type checker.

```bash
tsc -p tsconfig.json --noEmit --listFiles  
```

--------------------------------

### Keyword Workarounds for Lua Functions in TypeScript

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Explains how to handle Lua functions whose names are keywords in TypeScript (e.g., 'new', 'try'). It shows the incorrect approach using 'declare namespace' and the correct approach using a direct object declaration for the parent. This ensures proper syntax and avoids conflicts.

```typescript
// ❌  
declare namespace table {  
  export function new: () => any;  
}  

// ✔  
declare let table: {  
  new: () => any;  
};  
```

```typescript
// ❌  
declare module "creator" {  
  export function new: () => any;  
}  

// ✔  
declare module "creator" {  
  let exports: {  
    new: () => any;  
  };  
  export = exports;  
}  
```

--------------------------------

### Declaring and Assigning Global Variables in TypeScript

Source: https://typescripttolua.github.io/docs/assigning-global-variables

Demonstrates how to declare global variables using 'declare var' and then assign values to them in TypeScript, ensuring they are accessible globally.

```typescript
declare var OnStart: (this: void) => void;
declare var OnStateChanged: (this: void, newState: State) => void;

OnStart = () => {
  // start event handling code
};
OnStateChanged = (newState: State) => {
  // state change event handler code
};

```

--------------------------------

### LuaPrinter Class

Source: https://typescripttolua.github.io/docs/api/printer

The LuaPrinter class is responsible for converting Lua Abstract Syntax Trees (AST) into a string representation, including source map generation. It follows the visitor pattern to process different nodes within the AST.

```APIDOC
## Class: LuaPrinter

### Description
Converts Lua AST to a string with source map support. Implements the visitor pattern.

### Methods

- **constructor(options: CompilerOptions, emitHost: EmitHost, fileName: string)**: Initializes a new instance of the LuaPrinter class.
- **print(block: lua.Block, luaLibFeatures: Set<LuaLibFeature>): PrintResult**: Prints a Lua block to a string with source map.
- **printStatement(statement: lua.Statement): SourceNode**: Prints a single Lua statement.
- **printDoStatement(statement: lua.DoStatement): SourceNode**: Prints a 'do...end' statement.
- **printVariableDeclarationStatement(statement: lua.VariableDeclarationStatement): SourceNode**: Prints a variable declaration statement.
- **printVariableAssignmentStatement(statement: lua.AssignmentStatement): SourceNode**: Prints a variable assignment statement.
- **printIfStatement(statement: lua.IfStatement, isElseIf?: boolean): SourceNode**: Prints an if-elseif-else statement.
- **printWhileStatement(statement: lua.WhileStatement): SourceNode**: Prints a while loop statement.
- **printRepeatStatement(statement: lua.RepeatStatement): SourceNode**: Prints a repeat-until statement.
- **printForStatement(statement: lua.ForStatement): SourceNode**: Prints a numeric for loop statement.
- **printForInStatement(statement: lua.ForInStatement): SourceNode**: Prints a generic for loop statement.
- **printGotoStatement(statement: lua.GotoStatement): SourceNode**: Prints a goto statement.
- **printLabelStatement(statement: lua.LabelStatement): SourceNode**: Prints a label statement.
- **printReturnStatement(statement: lua.ReturnStatement): SourceNode**: Prints a return statement.
- **printBreakStatement(statement: lua.BreakStatement): SourceNode**: Prints a break statement.
- **printExpressionStatement(statement: lua.ExpressionStatement): SourceNode**: Prints an expression statement.
- **printExpression(expression: lua.Expression): SourceNode**: Prints a Lua expression.
- **printStringLiteral(expression: lua.StringLiteral): SourceNode**: Prints a string literal.
- **printNumericLiteral(expression: lua.NumericLiteral): SourceNode**: Prints a numeric literal.
- **printNilLiteral(expression: lua.NilLiteral): SourceNode**: Prints a nil literal.
- **printDotsLiteral(expression: lua.DotsLiteral): SourceNode**: Prints the dots literal (...).
- **printBooleanLiteral(expression: lua.BooleanLiteral): SourceNode**: Prints a boolean literal.
- **printFunctionExpression(expression: lua.FunctionExpression): SourceNode**: Prints a function expression.
- **printFunctionDefinition(statement: lua.FunctionDefinition): SourceNode**: Prints a function definition.
- **printTableFieldExpression(expression: lua.TableFieldExpression): SourceNode**: Prints a table field expression.
- **printTableExpression(expression: lua.TableExpression): SourceNode**: Prints a table expression.
- **printUnaryExpression(expression: lua.UnaryExpression): SourceNode**: Prints a unary expression.
- **printBinaryExpression(expression: lua.BinaryExpression): SourceNode**: Prints a binary expression.
- **printCallExpression(expression: lua.CallExpression): SourceNode**: Prints a function call expression.
- **printMethodCallExpression(expression: lua.MethodCallExpression): SourceNode**: Prints a method call expression.
- **printIdentifier(expression: lua.Identifier): SourceNode**: Prints an identifier.
- **printTableIndexExpression(expression: lua.TableIndexExpression): SourceNode**: Prints a table index expression.
- **printOperator(kind: lua.Operator): SourceNode**: Prints a Lua operator.

### Protected Methods

- **pushIndent()**: Increases the indentation level.
- **popIndent()**: Decreases the indentation level.
- **indent(input?: SourceChunk): SourceChunk**: Indents the given input.
- **createSourceNode(node: lua.Node, chunks: SourceChunk | SourceChunk[], name?: string): SourceNode**: Creates a SourceNode from AST node and chunks.
- **concatNodes(...chunks: SourceChunk[]): SourceNode**: Concatenates multiple SourceChunks into a single SourceNode.
- **printBlock(block: lua.Block): SourceNode**: Prints a Lua block.
- **printStatementArray(statements: lua.Statement[]): SourceChunk[]**: Prints an array of Lua statements.
- **isStatementEmpty(statement: lua.Statement): boolean**: Checks if a statement is empty.
- **joinChunks(separator: string, chunks: SourceChunk[]): SourceChunk[]**: Joins an array of SourceChunks with a separator.
- **printExpressionList(expressions: lua.Expression[]): SourceChunk[]**: Prints a list of Lua expressions.
```

--------------------------------

### TranspileString API

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles a string containing TypeScript source code to Lua, with optional compiler options.

```APIDOC
## TranspileString

### Description
Transpile a string containing TypeScript source code to Lua.

### Method
POST

### Endpoint
/transpileString

### Parameters
#### Request Body
- **source** (string) - Required - The TypeScript source code to transpile.
- **options** (tstl.CompilerOptions) - Optional - CompilerOptions to use.

### Request Example
```json
{
  "source": "const foo = \"bar\";",
  "options": {
    "luaTarget": "Lua53"
  }
}
```

### Response
#### Success Response (200)
- **diagnostics** (object[]) - An array of diagnostic messages.
- **file** (string) - The transpiled Lua code.

#### Response Example
```json
{
  "diagnostics": [],
  "file": "local foo = \"bar\""
}
```
```

--------------------------------

### Transpile TypeScript Files to Lua

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles an array of TypeScript files into Lua code. It takes an array of file paths and optional compiler options. The result includes diagnostics and the emit result.

```typescript
import * as tstl from "typescript-to-lua";

const result = tstl.transpileFiles(["file1.ts", "file2.ts"], { luaTarget: tstl.LuaTarget.Lua53 });
console.log(result.diagnostics);
console.log(result.emitResult);

```

--------------------------------

### Transpile TypeScript Project to Lua

Source: https://typescripttolua.github.io/docs/api/overview

Transpiles an entire TypeScript project, defined by a tsconfig.json file, into Lua code. It requires the path to the tsconfig.json file and accepts optional extended compiler options. The output contains diagnostics and the emit result.

```typescript
import * as tstl from "typescript-to-lua";

const result = tstl.transpileProject("tsconfig.json", { luaTarget: tstl.LuaTarget.Lua53 });
console.log(result.diagnostics);
console.log(result.emitResult);

```

--------------------------------

### Configure VS Code Build Task for Development

Source: https://typescripttolua.github.io/docs/editor-support

Sets up a Visual Studio Code build task to run the 'dev' npm script, which enables watch mode for TypeScriptToLua compilation. This task is configured to run in the background and is set as the default build task.

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "dev",
      "problemMatcher": "$tsc-watch",
      "isBackground": true,
      "presentation": { "reveal": "never" },
      "group": { "kind": "build", "isDefault": true }
    }
  ]
}
```

--------------------------------

### Handling Lua Local Variable Limit with Barrel Files in TypeScript

Source: https://typescripttolua.github.io/docs/caveats

Presents a solution to overcome Lua's local variable limit (200) when transpiling large TypeScript projects. It demonstrates using a barrel file to consolidate imports and reduce the number of local variables generated.

```typescript
import { Feature1 } from "./features/Feature1";
import { Feature2 } from "./features/Feature2";
import { Feature3 } from "./features/Feature3";
...
import { Feature101 } from "./features/Feature101";

const FEATURE_CLASSES = [
  Feature1,
  Feature2,
  Feature3,
  ...,
  Feature101,
];

for (const featureClass of FEATURE_CLASSES) {
  new featureClass();
}
```

```typescript
export { Feature1 } from "./features/Feature1";
export { Feature2 } from "./features/Feature1";
export { Feature3 } from "./features/Feature1";
...
export { Feature101 } from "./features/Feature101";
```

```typescript
import * as fc from "./featureClasses.ts";

const FEATURE_CLASSES = [
  fc.Feature1,
  fc.Feature2,
  fc.Feature3,
  ...,
  fc.Feature101,
];

for (const featureClass of FEATURE_CLASSES) {
  new featureClass();
}
```

--------------------------------

### afterEmit Hook

Source: https://typescripttolua.github.io/docs/api/plugins

The `afterEmit` function is called after all output files have been written to disk. This hook is useful for post-processing the generated Lua code, such as minification or other transformations.

```APIDOC
## `afterEmit` Hook

### Description
Called after all output files have been written to disk. Useful for post-processing the generated Lua code.

### Method
`afterEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[])`

### Parameters
- `program` (ts.Program) - The TypeScript program.
- `options` (tstl.CompilerOptions) - The TypeScript-to-Lua compiler options.
- `emitHost` (tstl.EmitHost) - The emit host interface.
- `result` (tstl.EmitFile[]) - An array of objects representing the files that were emitted.

### Request Example
```typescript
import * as ts from "typescript";
import * as tstl from "typescript-to-lua";

const plugin: tstl.Plugin = {
  afterEmit(program: ts.Program, options: tstl.CompilerOptions, emitHost: tstl.EmitHost, result: tstl.EmitFile[]) {
    for (const emittedFile of result) {
      console.log(`Emitted file ${emittedFile.outputPath}`);
    }
  },
};

export default plugin;
```

### Response
This hook does not modify the output. It is primarily for side effects like logging or triggering other processes.
```

--------------------------------

### Import and Export Declarations in TypeScript for Lua

Source: https://typescripttolua.github.io/docs/advanced/writing-declarations

Illustrates how to use `import` and `export` statements within TypeScript declaration files (`.d.ts`) to manage and share type definitions across different files and modules. This is crucial for organizing large projects and ensuring all necessary declarations are available.

```typescript
import "./lib";  
// All global declarations in lib will be included with this file  

export { Player } from "./Entities";  
// The Player declaration is re-exported from this file  
```

```typescript
declare module "mymodule" {  
  import * as types from "types";  
  export function getType(): types.Type;  
}  
```

--------------------------------

### Iterate LuaMap and LuaSet using for...of in TypeScript

Source: https://typescripttolua.github.io/docs/advanced/language-extensions

Shows how to iterate over LuaMap and LuaSet instances in TypeScript using for...of loops. These loops transpile to Lua's pairs() for iteration, offering a concise way to access elements.

```typescript
const luaMap = new LuaMap();
for (const [key, value] of luaMap) {
}

const luaSet = new LuaSet();
for (const value of luaSet) {
}
```
Tokens:
Raw