@ao-tools/tstl-ao

TSTL-AO

This package contains ambient/global type declarations for AO processes. It's used together with TypeScript-to-Lua to compile TypeScript to Lua code that can run on AOS.

This allows autocompletion for globals and modules of AOS and Lua's standard library. If you export your types, you can also use them in your client to get end-to-end type safety.

Installation

Install this package and its peer dependencies:

npm i -D @ao-tools/tstl-ao typescript typescript-to-lua lua-types @typescript-to-lua/language-extensions

• typescript and typescript-to-lua for compilation
• lua-types contains type definitions for the Lua standard library.
• @typescript-to-lua/language-extensions enables to type Lua constructs that don't map directly to TypeScript.

Setup

Create a tsconfig.json file with the following content:

{
  "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json",
  "include": ["path/to/process.ts"],
  "compilerOptions": {
    "strict": true,
    "target": "ESNext",
    "lib": ["ESNext"],
    "moduleResolution": "Node",
    "types": [
      "lua-types/5.3",
      "@typescript-to-lua/language-extensions",
      "@ao-tools/tstl-ao"
    ]
  },
  "tstl": {
    "luaTarget": "5.3",
    "luaBundleEntry": "path/to/process.ts",
    "luaBundle": "path/to/build/process.lua",
    "luaLibImport": "require-minimal",
    "noHeader": true
  }
}

include and luaBundleEntry must at least contain the path to your process entry file.

luaBundle contains the file path where TSTL saves the Lua bundle.

luaLibImport is the setting that controls built-in JavaScript APIs like string.split or Object.keys. require-minimal is the most robust setting that allows the use of those APIs without importing all of TSTL's JavaScript shims.

If you don't want to use any of those APIs, you can set this to none and save some space by using the built-in AOS modules instead.

If you only use very few of those APIs you can use inline.

Caveats

Lua isn't JavaScript, so there is no 100% compat. These are the differences you might encounter.

Different comparison results

• "" == true
• NaN == true
• 0 == true
• null === undefined (Note: tripple equals!)

Using === an !== resolves all but the last difference.

undefined and null deletes array and object items

a.x = null and a.x = undefined are equivalent to delete a.x

No RegExp

TSTL doesn't shim JavaScript regular expressions. Use string.find() instead.

No for ... in array iterations

You can't iterate an array with for ... in, use for ... of, .forEach, or .map instead.

Unstable sorting

The table.sort function is not stable.

Local variable limit

You can only declare 200 variable per function.

Variable JSON encoding

The json.encode function will encode both, an empty array and an empty object to an empty array.

Co-routines yield without await

Calling ao.send().receive() will stop the execution of the following lines of code until the target process replies.

Consider const x = ao.send().receive() to work similar to const x = await ao.send().

Example

The following code uses built-in modules of AOS, defines a type and sets up an info handler.

File: backend/process.ts

import * as Crypto from ".crypto"
import * as Json from "json"

export type InfoResponse = {
  Id: string
  Name: string
  Owner: string
  MemoryUsage: number
  PseudoRandom: number
  Time: number
}

Handlers.add("example-handler", "Info", (message) => {
  const info: InfoResponse = {
    // AOS global variables
    Id: ao.id,
    Name: Name,
    Owner: Owner,
    // AOS module function
    PseudoRandom: Crypto.random(0, 100),
    // Lua standard library function
    MemoryUsage: collectgarbage("count"),
    Time: os.time(),
  }

  message.reply({
    // AOS module function
    Data: Json.encode(info),
  })
})

You an use the InfoResponse type when parsing the messge data on a client.

File: frontend/client.ts

import * as aoconnect from "@permaweb/aoconnect"
import type { InfoResponse } from "../backend/process.ts"

const result = await aoconnect.dryrun({
  process: "<PROCESS_ID>"
  tags: [{name: "Action", value: "Info"}]
})

const response: InfoResponse = JSON.parse(result.Messages.pop().Data)