{"id":18591763,"url":"https://github.com/cheatoid/tstl-extensions","last_synced_at":"2025-05-16T09:35:39.446Z","repository":{"id":65815706,"uuid":"600504650","full_name":"Cheatoid/TSTL-extensions","owner":"Cheatoid","description":"Plugin for TSTL which provides various low-level extensions","archived":false,"fork":false,"pushed_at":"2023-03-20T05:10:49.000Z","size":74,"stargazers_count":1,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-27T17:03:44.709Z","etag":null,"topics":["lua","tstl","tstl-extension","tstl-plugin","typescript","typescript-to-lua"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@cheatoid/tstl-extensions","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cheatoid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-11T17:43:55.000Z","updated_at":"2024-08-23T05:07:49.000Z","dependencies_parsed_at":"2025-02-17T20:41:18.518Z","dependency_job_id":null,"html_url":"https://github.com/Cheatoid/TSTL-extensions","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cheatoid%2FTSTL-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cheatoid%2FTSTL-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cheatoid%2FTSTL-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cheatoid%2FTSTL-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cheatoid","download_url":"https://codeload.github.com/Cheatoid/TSTL-extensions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254505245,"owners_count":22082162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","tstl","tstl-extension","tstl-plugin","typescript","typescript-to-lua"],"created_at":"2024-11-07T01:04:37.210Z","updated_at":"2025-05-16T09:35:39.440Z","avatar_url":"https://github.com/Cheatoid.png","language":"TypeScript","readme":"# TSTL Extensions\n[![npm (scoped)](https://img.shields.io/npm/v/@cheatoid/tstl-extensions?style=for-the-badge)](https://www.npmjs.com/package/@cheatoid/tstl-extensions)\n\nPlugin for [TSTL](https://github.com/TypeScriptToLua/TypeScriptToLua) which provides various low-level extensions.\n\n## 🛠 Installation\n1. Get the latest package from npm:\n    ```shell\n    npm install -D @cheatoid/tstl-extensions\n    # or\n    yarn add -D @cheatoid/tstl-extensions\n    ```\n2. Edit your `tsconfig.json` file accordingly to enable the plugin:\n    ```diff\n    {\n      \"compilerOptions\": {\n        \"types\": [\n    +     \"@typescript-to-lua/language-extensions\",\n    +     \"@cheatoid/tstl-extensions\",\n        ]\n      },\n      \"tstl\": {\n        \"luaPlugins\": [\n    +     { \"name\": \"@cheatoid/tstl-extensions/index.js\" },\n        ]\n      }\n    }\n    ```\n\n## ✨ Features\n\nNote: This plugin exposes most of low-level functionality via special functions which are prefixed with double-underscore (`__`).\n\n### ***`continue` support***\nIf your target Lua environment supports `continue` statement (such as Garry's Mod Lua)...  \nDue to specific nature of this feature, you must explicitly opt-in by modifying your `tsconfig.json` file by appending the following:\n```diff\n{\n  \"tstl\": {\n    \"luaPlugins\": [\n      {\n        \"name\": \"@cheatoid/tstl-extensions/index.js\",\n+       \"hasContinue\": true\n      }\n    ]\n  }\n}\n```\nWith this change applied, you can use `continue` in your TS code and it will emit a `continue` statement in Lua.\n\n\n### ***`goto` \u0026 label support***\nOnly usable if your target Lua environment supports `goto` and labels (such as Lua 5.2+ or JIT)...  \nThe following table is hopefully self-explanatory:\n|    **TypeScript**    |    **Lua**     |\n| :------------------: | :------------: |\n| `__goto(\"MyLabel\")`  | `goto MyLabel` |\n| `__label(\"MyLabel\")` | `::MyLabel::`  |\n\n\n### ***Efficient swapping***\nThis allows you to swap two values [without a temporary variable](https://typescripttolua.github.io/play/#code/MYewdgzgLgBAhgJwTAvDA2gIgGYEsHSYA0MmEApqGACaYC6A3AFDqILoAMdJb6AjHTqoMvATySdBDGAHoZMKAE8ADrmBwANjAgB3OMqbKEuMFAAUUOACMN5AHRV15tiUykAlO4ZA):  \nThe following table is hopefully self-explanatory:\n|      **TypeScript**      |              **Lua**              |\n| :----------------------: | :-------------------------------: |\n| `__swap(arr[0], arr[1])` | `arr[1], arr[2] = arr[2], arr[1]` |\n\n\n### ***`unsafe_cast`***\nThis is useful in-place replacement for `as any` casting, because it allows to \"find all references\" quickly.  \nFor example, instead of writing `foo as any as TheFoo` (or `\u003cTheFoo\u003e\u003cany\u003efoo`), you can instead do `unsafe_cast\u003cTheFoo\u003e(foo)`.\n\n\n### ***`next` iterator support***\nCall `__next` using for-of loop, you may optionally want to specify a starting index.  \nExample usage:\n```ts\nfor (const [k, v] of __next(_G)) {\n    print(k, v);\n}\n```\nTranspiles to:\n```lua\nfor k, v in next, _G do\n    print(k, v)\nend\n```\n\n\n### ***Aggressive inlining***\nFunction calls have certain performance overhead. This feature allows to inline the body of the given function in-place, which can be beneficial in hot-path for high-performance code. It mostly just works, but consider it as experimental.  \nCurrently there is a drawback in the implementation, the target function must be defined in the same file where you want to inline it.  \nSimple example:\n```ts\nfunction InlineExample(name: string) {\n    print(`Hello, ${name}`);\n    print(\"The code to be inlined goes here\");\n}\nconst john = \"John\";\n__inline(InlineExample, john);\n__inline(InlineExample, \"Moon\");\n```\nTranspiles to:\n```lua\nlocal john = \"John\"\ndo\n    local name = john\n    print(\"Hello, \" .. name)\n    print(\"The code to be inlined goes here\")\nend\ndo\n    local name = \"Moon\"\n    print(\"Hello, \" .. name)\n    print(\"The code to be inlined goes here\")\nend\n```\n\n\n### ***Top-level return***\nThis feature allows you to bypass TypeScript limitation - ts(1108) error.  \nYou should only consider this as a last resort option (hint: try using export assignment `export = ...`), or if you want to bail out from a script.  \nSimply call `__return`, you may optionally pass additional arguments to be returned at call site.\n\n\n### ***And more...***\n*I am just tired to go over all of them... I hope there is a little bit of something for everyone to enjoy.* :P\n\n\n## 📜 History\nThis plugin was initially published at GitHub Gist ([here](https://gist.github.com/ea4573c6bd1992fc4940090543ec9380)), which is **outdated** as of now, perhaps you may still find something interesting down in the comments.\n\n\n## 👏 Credits\nSpecial thanks to [TypeScriptToLua](https://typescripttolua.github.io) developers and contributors for their awesome project.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheatoid%2Ftstl-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheatoid%2Ftstl-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheatoid%2Ftstl-extensions/lists"}