@data-vegle/rbxts-go 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +181 -2
- package/README.rbxtsgo.md +169 -0
- package/THIRD_PARTY_NOTICES.md +745 -0
- package/cli/cli.go +454 -0
- package/compile/compile.go +388 -0
- package/compile/declarations.go +221 -0
- package/compile/incremental.go +349 -0
- package/compile/times.go +9 -0
- package/docs/plugin-api.md +243 -0
- package/go.mod +20 -0
- package/go.sum +24 -0
- package/internal/difftest/difftest.go +530 -0
- package/internal/plugintest/plugintest.go +181 -0
- package/luau/create.go +351 -0
- package/luau/doc.go +71 -0
- package/luau/globals.go +178 -0
- package/luau/jsnum.go +188 -0
- package/luau/kinds.go +128 -0
- package/luau/list.go +227 -0
- package/luau/nodes.go +479 -0
- package/luau/operators.go +46 -0
- package/luau/render.go +134 -0
- package/luau/render_expressions.go +264 -0
- package/luau/render_fields.go +81 -0
- package/luau/render_indexable.go +81 -0
- package/luau/render_state.go +134 -0
- package/luau/render_statements.go +235 -0
- package/luau/render_util.go +296 -0
- package/luau/solve_temp_ids.go +212 -0
- package/luau/typeguards.go +175 -0
- package/luau/util.go +184 -0
- package/luau/visit.go +138 -0
- package/npm/index.d.ts +3 -0
- package/npm/rbxts-go.sh +187 -0
- package/package.json +45 -5
- package/patches/typescript/0001-checker-exports.patch +40 -0
- package/patches/typescript/0002-iterable-arity.patch +15 -0
- package/patches/typescript/0003-context-sensitive-this.patch +15 -0
- package/patches/typescript/0004-printer-keep-parse-tree-parentheses.patch +26 -0
- package/pluginapi/host.go +31 -0
- package/pluginapi/pluginapi.go +153 -0
- package/plugins/LICENSE-rbxts-transformer-setget +18 -0
- package/plugins/apply.go +342 -0
- package/plugins/config.go +431 -0
- package/plugins/fallback.go +84 -0
- package/plugins/fixemit.go +60 -0
- package/plugins/native.go +271 -0
- package/plugins/session.go +236 -0
- package/plugins/setget.go +478 -0
- package/project/copy.go +333 -0
- package/project/include/Promise.lua +2068 -0
- package/project/include/RuntimeLib.lua +260 -0
- package/project/nodepath/nodepath.go +917 -0
- package/project/pathtranslator/pathtranslator.go +214 -0
- package/project/project.go +498 -0
- package/project/rojoresolver/json.go +248 -0
- package/project/rojoresolver/rojoresolver.go +559 -0
- package/project/shared/constants.go +83 -0
- package/project/shared/diagnostic.go +238 -0
- package/project/shared/diagnostics.go +388 -0
- package/project/shared/elapsed.go +14 -0
- package/project/shared/eol_other.go +6 -0
- package/project/shared/eol_windows.go +4 -0
- package/project/shared/kleur.go +40 -0
- package/project/shared/util.go +183 -0
- package/scripts/build-with-plugins.sh +130 -0
- package/scripts/setup-third-party.sh +75 -0
- package/transformer/add_index_diagnostics.go +21 -0
- package/transformer/add_one_if_array_type.go +15 -0
- package/transformer/array_binding_pattern_contains_hoists.go +25 -0
- package/transformer/assert_never.go +24 -0
- package/transformer/assignment.go +64 -0
- package/transformer/call_macros.go +70 -0
- package/transformer/check_variable_hoist.go +125 -0
- package/transformer/clean_module_name.go +28 -0
- package/transformer/constructor_macros.go +122 -0
- package/transformer/convert_to_indexable_expression.go +12 -0
- package/transformer/create_binary_from_operator.go +86 -0
- package/transformer/create_continue_statements.go +68 -0
- package/transformer/create_get_service.go +15 -0
- package/transformer/create_hoist_declaration.go +27 -0
- package/transformer/create_import_expression.go +220 -0
- package/transformer/create_string_from_literal.go +195 -0
- package/transformer/create_truthiness_checks.go +63 -0
- package/transformer/create_type_check.go +9 -0
- package/transformer/ensure_transform_order.go +53 -0
- package/transformer/expression_chain.go +27 -0
- package/transformer/expression_might_mutate.go +60 -0
- package/transformer/find_constructor.go +15 -0
- package/transformer/fixup_whitespace_and_decode_entities.go +377 -0
- package/transformer/get_accessor_for_binding_type.go +160 -0
- package/transformer/get_add_iterable_to_array_builder.go +363 -0
- package/transformer/get_assignable_value.go +15 -0
- package/transformer/get_constant_value_literal.go +20 -0
- package/transformer/get_declared_variables.go +34 -0
- package/transformer/get_extends_node.go +23 -0
- package/transformer/get_flags.go +21 -0
- package/transformer/get_kind_name.go +18 -0
- package/transformer/get_original_symbol_of_node.go +16 -0
- package/transformer/get_source_file_from_module_specifier.go +68 -0
- package/transformer/get_statements.go +12 -0
- package/transformer/has_multiple_definitions.go +18 -0
- package/transformer/hoist_functions_past_final_statement.go +43 -0
- package/transformer/identifier_macros.go +17 -0
- package/transformer/is_blocked_by_try_statement.go +19 -0
- package/transformer/is_method.go +104 -0
- package/transformer/is_symbol_mutable.go +26 -0
- package/transformer/is_symbol_of_value.go +11 -0
- package/transformer/is_used_as_statement.go +25 -0
- package/transformer/is_valid_method_index_without_call.go +36 -0
- package/transformer/macro_manager.go +92 -0
- package/transformer/object_accessor.go +32 -0
- package/transformer/offset.go +58 -0
- package/transformer/pointer.go +53 -0
- package/transformer/property_call_macros.go +1035 -0
- package/transformer/state.go +606 -0
- package/transformer/transform_array_assignment_pattern.go +65 -0
- package/transformer/transform_array_binding_pattern.go +49 -0
- package/transformer/transform_array_literal_expression.go +97 -0
- package/transformer/transform_await_expression.go +12 -0
- package/transformer/transform_binary_expression.go +221 -0
- package/transformer/transform_binding_name.go +25 -0
- package/transformer/transform_block.go +14 -0
- package/transformer/transform_boolean_literal.go +13 -0
- package/transformer/transform_break_statement.go +26 -0
- package/transformer/transform_call_expression.go +266 -0
- package/transformer/transform_class_constructor.go +125 -0
- package/transformer/transform_class_declaration.go +12 -0
- package/transformer/transform_class_expression.go +14 -0
- package/transformer/transform_class_like_declaration.go +355 -0
- package/transformer/transform_conditional_expression.go +70 -0
- package/transformer/transform_continue_statement.go +30 -0
- package/transformer/transform_decorators.go +253 -0
- package/transformer/transform_delete_expression.go +17 -0
- package/transformer/transform_do_statement.go +39 -0
- package/transformer/transform_element_access_expression.go +114 -0
- package/transformer/transform_entity_name.go +21 -0
- package/transformer/transform_enum_declaration.go +135 -0
- package/transformer/transform_export_assignment.go +57 -0
- package/transformer/transform_export_declaration.go +150 -0
- package/transformer/transform_expression.go +120 -0
- package/transformer/transform_expression_statement.go +71 -0
- package/transformer/transform_for_of_statement.go +461 -0
- package/transformer/transform_for_statement.go +599 -0
- package/transformer/transform_function_declaration.go +84 -0
- package/transformer/transform_function_expression.go +48 -0
- package/transformer/transform_identifier.go +194 -0
- package/transformer/transform_if_statement.go +44 -0
- package/transformer/transform_import_declaration.go +146 -0
- package/transformer/transform_import_equals_declaration.go +46 -0
- package/transformer/transform_import_expression.go +36 -0
- package/transformer/transform_initializer.go +22 -0
- package/transformer/transform_interpolated_string_part.go +12 -0
- package/transformer/transform_jsx.go +41 -0
- package/transformer/transform_jsx_attributes.go +110 -0
- package/transformer/transform_jsx_children.go +50 -0
- package/transformer/transform_jsx_element.go +14 -0
- package/transformer/transform_jsx_expression.go +20 -0
- package/transformer/transform_jsx_fragment.go +42 -0
- package/transformer/transform_jsx_self_closing_element.go +13 -0
- package/transformer/transform_jsx_tag_name.go +53 -0
- package/transformer/transform_logical.go +160 -0
- package/transformer/transform_logical_or_coalescing_assignment_expression.go +103 -0
- package/transformer/transform_method_declaration.go +102 -0
- package/transformer/transform_module_declaration.go +143 -0
- package/transformer/transform_new_expression.go +27 -0
- package/transformer/transform_no_substitution_template_literal.go +16 -0
- package/transformer/transform_numeric_literal.go +15 -0
- package/transformer/transform_object_assignment_pattern.go +86 -0
- package/transformer/transform_object_binding_pattern.go +49 -0
- package/transformer/transform_object_literal_expression.go +107 -0
- package/transformer/transform_omitted_expression.go +9 -0
- package/transformer/transform_optional_chain.go +312 -0
- package/transformer/transform_parameters.go +124 -0
- package/transformer/transform_parenthesized_expression.go +17 -0
- package/transformer/transform_property_access_expression.go +37 -0
- package/transformer/transform_property_declaration.go +33 -0
- package/transformer/transform_property_name.go +20 -0
- package/transformer/transform_return_statement.go +83 -0
- package/transformer/transform_source_file.go +230 -0
- package/transformer/transform_spread_element.go +35 -0
- package/transformer/transform_statement.go +84 -0
- package/transformer/transform_statement_list.go +90 -0
- package/transformer/transform_string_literal.go +22 -0
- package/transformer/transform_super_keyword.go +9 -0
- package/transformer/transform_switch_statement.go +145 -0
- package/transformer/transform_tagged_template_expression.go +34 -0
- package/transformer/transform_template_expression.go +35 -0
- package/transformer/transform_this_expression.go +33 -0
- package/transformer/transform_throw_statement.go +18 -0
- package/transformer/transform_try_statement.go +192 -0
- package/transformer/transform_type_expression.go +12 -0
- package/transformer/transform_unary_expression.go +79 -0
- package/transformer/transform_variable_statement.go +178 -0
- package/transformer/transform_void_expression.go +13 -0
- package/transformer/transform_while_statement.go +34 -0
- package/transformer/transform_writable.go +69 -0
- package/transformer/transform_yield_expression.go +56 -0
- package/transformer/type_guards.go +30 -0
- package/transformer/types.go +381 -0
- package/transformer/validate_identifier.go +17 -0
- package/transformer/validate_method_assignment.go +106 -0
- package/transformer/validate_not_any.go +37 -0
- package/transformer/wrap_expression_statement.go +20 -0
- package/transformer/wrap_return_if_lua_tuple.go +63 -0
- package/transformer/wrap_statements_as_generator.go +22 -0
- package/tsbridge/affected.go +141 -0
- package/tsbridge/config.go +71 -0
- package/tsbridge/diagnostics.go +128 -0
- package/tsbridge/doc.go +16 -0
- package/tsbridge/macros.go +207 -0
- package/tsbridge/macrospec.go +30 -0
- package/tsbridge/pool.go +142 -0
- package/tsbridge/project.go +137 -0
- package/tsbridge/reprint.go +120 -0
- package/tsbridge/update.go +128 -0
- package/watch/poll.go +126 -0
- package/watch/session.go +651 -0
- package/watch/watch.go +180 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 plasma-node
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,182 @@
|
|
|
1
|
-
#
|
|
1
|
+
# rbxts-go
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A faster and lighter build of [rbxtsgo](https://github.com/plasma-node/rbxtsgo), the Go port of the
|
|
4
|
+
[roblox-ts](https://roblox-ts.com) compiler (TypeScript to Luau), with a benchmark of the two:
|
|
5
|
+
|
|
6
|
+
- **rbxtsgo**: the original Go compiler, at commit `9b32f3b`.
|
|
7
|
+
- **rbxts-go**: this repository. rbxtsgo's code, copied from that commit, then optimised. Same output, less time,
|
|
8
|
+
less memory.
|
|
9
|
+
|
|
10
|
+
Layout: the Go compiler is at the root, as in rbxtsgo (its own README is kept as
|
|
11
|
+
[README.rbxtsgo.md](README.rbxtsgo.md)). `bench/` has the benchmark script, its project list and the results.
|
|
12
|
+
|
|
13
|
+
## Use it in a project (npm)
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm install -D @data-vegle/rbxts-go
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
That one dev dependency brings the launcher (`rbxtsc` and `rbxts-go`), `@rbxts/types`, `@rbxts/compiler-types` and
|
|
20
|
+
TypeScript 7.1, so a project lists none of them itself.
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"scripts": {
|
|
25
|
+
"postinstall": "rbxts-go setup",
|
|
26
|
+
"build": "rbxtsc",
|
|
27
|
+
"watch": "rbxtsc -w",
|
|
28
|
+
"typecheck": "rbxts-go typecheck"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `rbxtsc [flags]` compiles the project (`-w`, `-p`, `--rojo`, `--type`, as roblox-ts).
|
|
34
|
+
- `rbxts-go together "<command>" [flags]` compiles and runs another command next to it, for a watcher that works on
|
|
35
|
+
the output, such as darklua. Both stop together.
|
|
36
|
+
- `rbxts-go typecheck [flags]` runs stock TypeScript 7 with `--noEmit`.
|
|
37
|
+
- `rbxts-go setup` patches `@rbxts/compiler-types` in `node_modules` so that TypeScript 7 (the editor, `typecheck`)
|
|
38
|
+
accepts `for ... of` over roblox-ts types. The compile commands do it too.
|
|
39
|
+
- `rbxts-go compiler [--force]` builds the compiler without compiling anything.
|
|
40
|
+
|
|
41
|
+
The compiler is built on your machine, because native plugins are compiled into it: the first `rbxtsc` fetches the
|
|
42
|
+
TypeScript 7 sources once per user (`~/.cache/rbxts-go`), then builds `node_modules/.cache/rbxts-go/rbxtsc` in a few
|
|
43
|
+
seconds. It is rebuilt when rbxts-go or a plugin changes. This needs **Go 1.27 and git**.
|
|
44
|
+
|
|
45
|
+
Plugins are found by themselves: an installed package (or the project) that has a file `rbxts-go-plugin` at its root
|
|
46
|
+
is a plugin, and the file holds the folder of its Go module (`transformer`). `@data-vegle/godawork` and
|
|
47
|
+
`@data-vegle/network` are plugins. See [docs/plugin-api.md](docs/plugin-api.md) to write one.
|
|
48
|
+
|
|
49
|
+
The tsconfig is written for TypeScript 7: `"module": "preserve"`, `"moduleResolution": "bundler"`, `"types": ["*"]`,
|
|
50
|
+
`"paths"` instead of `baseUrl`, no `downlevelIteration`.
|
|
51
|
+
|
|
52
|
+
## Benchmark: rbxtsgo against rbxts-go
|
|
53
|
+
|
|
54
|
+
Full builds on an Apple M5 Pro (18 logical CPUs, macOS 26.6), measured on 2026-11-20. The output folder is deleted
|
|
55
|
+
before every run. 3 warm-up runs, then 20 timed runs per compiler, in rotation. Both use the same TypeScript 7.1
|
|
56
|
+
commit and 4 type checkers, and both wrote byte-identical files on both projects.
|
|
57
|
+
|
|
58
|
+
### Wall time (median, with range)
|
|
59
|
+
|
|
60
|
+
| Project | rbxtsgo (Go) | rbxts-go (optimised Go) |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| Dragon Arena: 874 files, about 130k lines | 477 ms (464 to 500) | **400 ms** (394 to 431) |
|
|
63
|
+
| against rbxtsgo | | **16% faster** |
|
|
64
|
+
| rbxtsgo fixtures: 11 files | 30.4 ms (28.3 to 37.4) | **26.9 ms** (25.3 to 34.3) |
|
|
65
|
+
| against rbxtsgo | | **12% faster** |
|
|
66
|
+
|
|
67
|
+
### Time per phase on Dragon Arena (ms, median of 7 `--verbose` runs)
|
|
68
|
+
|
|
69
|
+
| Phase | rbxtsgo (Go) | rbxts-go (optimised Go) | What it is |
|
|
70
|
+
|---|---|---|---|
|
|
71
|
+
| program | 39 | **35** | parse the config, create the TypeScript program |
|
|
72
|
+
| copy | 13 | 19 | clean the output folder, copy include and other files |
|
|
73
|
+
| check | 220 | **189** | type-check every file |
|
|
74
|
+
| lower | 112 | **86** | TypeScript AST to Luau AST to text |
|
|
75
|
+
| write | 65 | **39** | write 874 files |
|
|
76
|
+
|
|
77
|
+
In rbxts-go, type checking starts in the background before `copy`, so `copy` shares the machine with it and `check`
|
|
78
|
+
only counts the time left to wait.
|
|
79
|
+
|
|
80
|
+
### Peak memory
|
|
81
|
+
|
|
82
|
+
| Project | rbxtsgo (Go) | rbxts-go (optimised Go) |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| Dragon Arena | 703 MB | **621 MB** (12% less) |
|
|
85
|
+
| rbxtsgo fixtures | 54 MB | 55 MB |
|
|
86
|
+
|
|
87
|
+
### Binary size
|
|
88
|
+
|
|
89
|
+
| | rbxtsgo (Go) | rbxts-go (optimised Go) |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| macOS arm64 | 29.5 MB | **21.6 MB** |
|
|
92
|
+
|
|
93
|
+
rbxtsgo is the plain `go build` from its README. rbxts-go is built with `-trimpath -ldflags="-s -w"`, which is all of
|
|
94
|
+
the difference.
|
|
95
|
+
|
|
96
|
+
### Features
|
|
97
|
+
|
|
98
|
+
| | rbxtsgo (Go) | rbxts-go (optimised Go) |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| Full build | yes | yes, same output |
|
|
101
|
+
| Watch mode | yes | yes |
|
|
102
|
+
| Incremental builds | yes | yes |
|
|
103
|
+
| Built-in setget transformer | yes | yes |
|
|
104
|
+
| Other transformer plugins (Flamework...) | handed to the JS compiler | handed to the JS compiler |
|
|
105
|
+
| Declaration emit (`.d.ts`) | yes | yes |
|
|
106
|
+
| Processes | 1 | 1 |
|
|
107
|
+
| Run on | Windows x64 (per its README), macOS here | macOS only |
|
|
108
|
+
|
|
109
|
+
### Reading the numbers
|
|
110
|
+
|
|
111
|
+
- rbxts-go is faster and lighter, and it keeps every feature of rbxtsgo, because it is rbxtsgo with five changes
|
|
112
|
+
(next section).
|
|
113
|
+
- `program` and `check` are TypeScript's Go code in both, and they are about half of a build. Nothing here changes
|
|
114
|
+
TypeScript itself.
|
|
115
|
+
- Only full builds without incremental state are measured. Watch mode and incremental builds of rbxts-go were not
|
|
116
|
+
timed; the background type check is off for them.
|
|
117
|
+
- Dragon Arena was compiled with its transformer plugins turned off, because neither compiler runs them natively.
|
|
118
|
+
The output measures compiler speed and is not a runnable game.
|
|
119
|
+
|
|
120
|
+
Method, limits and how to rerun: [bench/RESULTS.md](bench/RESULTS.md). Raw numbers:
|
|
121
|
+
[bench/results/results.json](bench/results/results.json).
|
|
122
|
+
|
|
123
|
+
## What rbxts-go changes
|
|
124
|
+
|
|
125
|
+
A profile of rbxtsgo on Dragon Arena showed that about 40% of its CPU time went to growing the heap (memory system
|
|
126
|
+
calls) and 25% to garbage collection, and that 16% of everything it allocated came from its own path functions. The
|
|
127
|
+
changes follow from that. None changes what is written: on both benchmark projects the output files are
|
|
128
|
+
byte-identical to rbxtsgo's, and on rbxtsgo's `upstream-tests` corpus the printed errors are identical too.
|
|
129
|
+
|
|
130
|
+
1. **Path functions that allocate nothing in the common case** (`project/nodepath`). `Resolve` and `Normalize` return
|
|
131
|
+
a path that is already absolute and normalized as it is, `Join` builds its string once, and the "is this file
|
|
132
|
+
inside that folder" test no longer builds a relative path to look at its first two characters. A randomized test
|
|
133
|
+
checks the shortcuts against the general code on 200,000 paths.
|
|
134
|
+
2. **A cache for "is this a Roblox type"** (`transformer/types.go`). The answer depends only on the file a type is
|
|
135
|
+
declared in, and it was recomputed, with a path join, for every declaration of every type that reached the check.
|
|
136
|
+
3. **Type checking starts in the background** (`tsbridge.Project.Precheck`), while the build cleans the output folder,
|
|
137
|
+
copies files and reads the Rojo project. Only for builds that check the whole program: not with setget, and not
|
|
138
|
+
with incremental state.
|
|
139
|
+
4. **Output files are written by several goroutines** (`compile.WriteResults`), with the same result and error order
|
|
140
|
+
as the sequential loop.
|
|
141
|
+
5. **Fewer garbage collections in a one-shot build** (`GOGC` 150, in `cli`). Nearly everything a build
|
|
142
|
+
allocates lives until the process exits, so collections find little to free. Watch mode keeps Go's default, and
|
|
143
|
+
setting `GOGC` wins over this.
|
|
144
|
+
|
|
145
|
+
Also new: `--memprofile <file>` writes a heap profile, next to the existing `--cpuprofile`.
|
|
146
|
+
|
|
147
|
+
Also new: **native plugins**. A transformer plugin written in Go, as its own module, can be compiled into the compiler
|
|
148
|
+
and then runs in place of the JavaScript transformer of the same name in `compilerOptions.plugins`, so the build no
|
|
149
|
+
longer goes to the JS compiler. [docs/plugin-api.md](docs/plugin-api.md) is the contract for plugin authors, and
|
|
150
|
+
`scripts/build-with-plugins.sh -o <output> <plugin folder>...` builds a compiler with plugins. A build with no plugin
|
|
151
|
+
is unchanged.
|
|
152
|
+
|
|
153
|
+
Tests: `go test ./...` gives the same results as the original on this Mac. Every package passes except three tests
|
|
154
|
+
that fail the same way in the untouched rbxtsgo here (`TestDifferential`, `TestWorkerCounts`,
|
|
155
|
+
`TestResolutionMatchesNode`: macOS temp-folder paths and a corpus that is not fully set up). Not run: Windows and
|
|
156
|
+
Linux.
|
|
157
|
+
|
|
158
|
+
## Build
|
|
159
|
+
|
|
160
|
+
Needs Go 1.27, git and bash.
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
bash scripts/setup-third-party.sh # clones TypeScript 7.1 at a pinned commit and applies patches/typescript/
|
|
164
|
+
go build -trimpath -ldflags="-s -w" -o bin/rbxts-go ./cmd/rbxtsgo
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Use
|
|
168
|
+
|
|
169
|
+
Same flags as rbxtsgo and `rbxtsc build`, before `build`. See [README.rbxtsgo.md](README.rbxtsgo.md) for all of them,
|
|
170
|
+
for setget, and for installing it as `rbxtsc`.
|
|
171
|
+
|
|
172
|
+
```sh
|
|
173
|
+
rbxts-go -p . # build the project in the current folder
|
|
174
|
+
rbxts-go -p . -w # watch mode
|
|
175
|
+
rbxts-go -p . --verbose # with phase timings
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Licence
|
|
179
|
+
|
|
180
|
+
MIT, as rbxtsgo: see [LICENSE](LICENSE). rbxts-go is rbxtsgo with changes, rbxtsgo is a port of roblox-ts and its
|
|
181
|
+
libraries, and both are built on TypeScript. Their licence texts are in
|
|
182
|
+
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# rbxtsgo
|
|
2
|
+
|
|
3
|
+
**A much faster [roblox-ts](https://roblox-ts.com) compiler.** rbxtsgo is written in Go, on top of TypeScript 7's Go compiler. It produces the same Luau as `rbxtsc` 3.0.0, works with your existing `@rbxts/*` packages and tsconfig, and installs as a drop-in `rbxtsc`.
|
|
4
|
+
|
|
5
|
+
| On a production Roblox game | roblox-ts 3.0.0 | rbxtsgo | |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| **Save a file in watch mode** | 3.6 s | **87 ms** | ~40x faster |
|
|
8
|
+
| **Save a widely imported file in watch mode** | 10.2 s | **317 ms** | ~32x faster |
|
|
9
|
+
| **Full build** | 13.1 s | **0.92 s** | ~14x faster |
|
|
10
|
+
| **Peak memory, full build** | ~630 MB | **~335 MB** | ~47% less |
|
|
11
|
+
|
|
12
|
+
The compiled Luau from that game is byte-for-byte identical to what `roblox-ts` writes.
|
|
13
|
+
|
|
14
|
+
> **Early development.** It's new and has only been run on Windows x64. It hasn't had long-term use, so keep your project in git, check your own output, and playtest before relying on it. Please [open an issue](https://github.com/plasma-node/rbxtsgo/issues) if something breaks or the output differs.
|
|
15
|
+
|
|
16
|
+
## Why use it
|
|
17
|
+
|
|
18
|
+
- **Saves feel instant.** Watch mode rebuilds in milliseconds, so your game is synced by the time you've switched windows.
|
|
19
|
+
- **Same output.** Luau is compared byte for byte against the real JS compiler. Differences are the exception, and they're [listed](docs/known-differences.md).
|
|
20
|
+
- **No migration.** Your tsconfig, packages and scripts stay as they are, including settings TypeScript 7 removed, like `baseUrl` and `moduleResolution: Node`.
|
|
21
|
+
- **Real incremental builds.** A build with no changes takes a fraction of a second, and tests compare incremental output against a clean build after every edit.
|
|
22
|
+
- **Setget built in.** [`rbxts-transformer-setget`](https://github.com/wAD4444/rbxts-transformer-setget) runs natively with no package needed, and **errors point at the correct line** in your source, which the JS plugin can't do.
|
|
23
|
+
- **Build times shown.** Each build tells you how long it took.
|
|
24
|
+
- **Crashes fixed.** Some cases that crash the JS compiler or make it write invalid Luau are fixed. Other known bugs have optional fixes behind [`--fix-emit`](docs/fix-emit.md).
|
|
25
|
+
|
|
26
|
+
## Benchmarks
|
|
27
|
+
|
|
28
|
+
Medians of 5 to 15 runs on one Windows 11 desktop (22 logical CPUs), comparing `roblox-ts` 3.0.0 on Node 20 with rbxtsgo. Machine speed varied between runs and these aren't lab conditions, so treat them as approximate and try your own project.
|
|
29
|
+
|
|
30
|
+
### A production Roblox game
|
|
31
|
+
|
|
32
|
+
A couple hundred TypeScript files, with React UI, setget and a wide set of `@rbxts` packages.
|
|
33
|
+
|
|
34
|
+
| | roblox-ts 3.0.0 | rbxtsgo | Faster by |
|
|
35
|
+
|---|---|---|---|
|
|
36
|
+
| Watch: save, rarely imported file | 3.6 s | **87 ms** | ~40x |
|
|
37
|
+
| Watch: save, widely imported file | 10.2 s | **317 ms** | ~32x |
|
|
38
|
+
| Full cold build | 13.1 s | **0.92 s** | ~14x |
|
|
39
|
+
| Incremental: no changes | 5.4 s | **0.25 s** | ~22x |
|
|
40
|
+
| Incremental: edit a rarely imported file | 5.1 s | **0.43 s** | ~12x |
|
|
41
|
+
| Incremental: edit a widely imported file | 8.2 s | **0.65 s** | ~13x |
|
|
42
|
+
| Peak memory, full build | ~630 MB | **~335 MB** | ~47% less |
|
|
43
|
+
|
|
44
|
+
The watch figures for roblox-ts come from an earlier run than the rest. This project is closed source, so these numbers can't be reproduced. The next ones can.
|
|
45
|
+
|
|
46
|
+
### [littensy/slither](https://github.com/littensy/slither) (public, MIT)
|
|
47
|
+
|
|
48
|
+
An open-source game at commit [`56545f1`](https://github.com/littensy/slither/tree/56545f14df4d25d3df7e71fbaeff7b21cf8798a7): 256 TypeScript files, about 12k lines. All 258 output files were byte-identical to JS.
|
|
49
|
+
|
|
50
|
+
| | roblox-ts 3.0.0 | rbxtsgo | Faster by |
|
|
51
|
+
|---|---|---|---|
|
|
52
|
+
| Watch: save, rarely imported file | 3.87 s | **91 ms** | ~42x |
|
|
53
|
+
| Watch: save, widely imported file (41 importers) | 4.12 s | **210 ms** | ~20x |
|
|
54
|
+
| Full cold build | 7.06 s | **0.81 s** | ~9x |
|
|
55
|
+
| Incremental: no changes | 3.81 s | **0.32 s** | ~12x |
|
|
56
|
+
| Incremental: edit a rarely imported file | 4.07 s | **0.49 s** | ~8x |
|
|
57
|
+
| Incremental: edit a widely imported file | 6.51 s | **0.71 s** | ~9x |
|
|
58
|
+
| Peak memory, full build | 259 MB | **222 MB** | ~14% less |
|
|
59
|
+
|
|
60
|
+
Smaller projects have less to gain: on the 10-line [rbxts-rs/template](https://github.com/rbxts-rs/template) at `e446ad9`, a cold build is 1.47 s against 0.13 s, which is mostly Node's startup time. roblox-ts can't read that template's TypeScript 7-style config, so its time is from the same source under a classic config.
|
|
61
|
+
|
|
62
|
+
**Not faster:** projects using a transformer plugin other than setget, such as Flamework. Those builds are handed to the JS compiler, so they run at JS speed.
|
|
63
|
+
|
|
64
|
+
## Install
|
|
65
|
+
|
|
66
|
+
### With Aftman or Rokit
|
|
67
|
+
|
|
68
|
+
Add it under the name `rbxtsc`, so your scripts and editor keep working. In `aftman.toml`:
|
|
69
|
+
|
|
70
|
+
```toml
|
|
71
|
+
[tools]
|
|
72
|
+
rbxtsc = "plasma-node/rbxtsgo@0.1.1"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Then:
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
aftman install
|
|
79
|
+
npm uninstall roblox-ts
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Removing the package matters, because a local `roblox-ts` takes priority over the tool. Keep it if your project uses a transformer plugin other than setget, since those builds need the JS compiler. In that case, `rbxtsc` stays the JS one, and you run rbxtsgo by installing it under another name.
|
|
83
|
+
|
|
84
|
+
- **Don't run `npx rbxtsc`.** Without a local install, `npx` downloads an unrelated placeholder package with that name. Run `rbxtsc` directly, and update any `npx rbxtsc` in your scripts.
|
|
85
|
+
- **"Being used by another process" during install:** a running tool such as `rojo` is holding its file. Stop it, and run the install again.
|
|
86
|
+
- **To go back to JS:** remove the line from `aftman.toml`, then run `npm install -D roblox-ts@3.0.0`.
|
|
87
|
+
|
|
88
|
+
Aftman's install has been run on Windows x64. Rokit reads `aftman.toml` too, but hasn't been tried, and neither has macOS or Linux, though binaries are built for them.
|
|
89
|
+
|
|
90
|
+
**VS Code:** the [roblox-ts extension](https://github.com/roblox-ts/vscode-roblox-ts)'s start button uses a local `roblox-ts` if there is one, and otherwise runs `rbxtsc -w` from your `PATH`, so it should pick this up. That's from reading its source. It hasn't been tested, including whether its stop button stops the process on Windows. If it doesn't work, run `rbxtsc -w` in a terminal.
|
|
91
|
+
|
|
92
|
+
### From source
|
|
93
|
+
|
|
94
|
+
You need Go (the version in `go.mod`), `git`, and a bash shell (Git Bash on Windows).
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
git clone https://github.com/plasma-node/rbxtsgo.git
|
|
98
|
+
cd rbxtsgo
|
|
99
|
+
bash scripts/setup-third-party.sh # clones TypeScript 7.1 at a pinned commit and applies patches/typescript/
|
|
100
|
+
go build -o rbxtsgo ./cmd/rbxtsgo # rbxtsgo.exe on Windows
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Use
|
|
104
|
+
|
|
105
|
+
It takes the flags of `rbxtsc build`, and flags go before `build`:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
rbxtsc -p . # build the project in the current folder
|
|
109
|
+
rbxtsc -p . -w # watch mode
|
|
110
|
+
rbxtsc --help # all flags
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Extra flags: `--checkers N` sets the number of type checkers, `--setget` turns on the built-in setget transformer, and `--fix-emit` turns on the optional fixes.
|
|
114
|
+
|
|
115
|
+
### Setget
|
|
116
|
+
|
|
117
|
+
Existing `rbxts-transformer-setget` entries in `plugins` keep working, with or without the package installed. Or, without a plugin entry, add this at the top level of `tsconfig.json`, next to `compilerOptions`:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
"rbxtsgo": { "setget": true }
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The default method prefix is `__`, the same as the plugin's 2.0.0 release. See [docs/setget.md](docs/setget.md).
|
|
124
|
+
|
|
125
|
+
## Compatibility
|
|
126
|
+
|
|
127
|
+
- **Reference:** `roblox-ts@3.0.0`, which uses TypeScript 5.5.3. Expected output comes from running the real JS compiler, never from editing test results by hand.
|
|
128
|
+
- **Test corpus:** roblox-ts's own test sources, plus cases written for this project. 186 of 188 Luau files are byte-identical, and the other 2 are cases where JS's output fails to parse. All 460 of roblox-ts's runtime tests pass on rbxtsgo's output under Lune.
|
|
129
|
+
- **Real code:** 9 public projects and about 40 popular packages, including `@rbxts/react`, `vide`, `charm`, `reflex` and `profile-store`, came out byte-identical. The exception is `.d.ts` output, below. Two of those projects went through the JS fallback.
|
|
130
|
+
- **Config:** tsconfigs written for `rbxtsc` work unchanged. TypeScript 7-style configs (`module: preserve`, `moduleResolution: bundler`) are accepted too. See [docs/config-normalization.md](docs/config-normalization.md).
|
|
131
|
+
- **Parallelism:** worker counts don't change output.
|
|
132
|
+
|
|
133
|
+
### Known differences
|
|
134
|
+
|
|
135
|
+
- **Error text:** 230 of 243 diagnostics comparisons match. TypeScript 7 words some errors differently, and sometimes reports them on a different line. The code is rejected on both sides, so Luau isn't affected.
|
|
136
|
+
- **Declaration files:** `.d.ts` output is printed slightly differently, which matters only if you publish packages.
|
|
137
|
+
- **Your editor:** VS Code still uses its own TypeScript for squiggles, so it won't get faster and may occasionally disagree with the build.
|
|
138
|
+
|
|
139
|
+
The full list is in [docs/known-differences.md](docs/known-differences.md).
|
|
140
|
+
|
|
141
|
+
### Not done yet
|
|
142
|
+
|
|
143
|
+
- Only the build command and its flags exist. A few parts of `rbxtsc` aren't ported, such as `VirtualProject`.
|
|
144
|
+
- `roblox-ts` 3.1 isn't released yet. When it is, rbxtsgo will need work to match its output.
|
|
145
|
+
- Some bugs remain, for example `new.target` crashes, as it does in roblox-ts.
|
|
146
|
+
- Concurrency hasn't been checked with Go's race detector. Deterministic output is shown by repeated runs at different worker counts.
|
|
147
|
+
- macOS and Linux test data doesn't exist yet, so some tests skip there.
|
|
148
|
+
|
|
149
|
+
## Related projects
|
|
150
|
+
|
|
151
|
+
[rbxts-rs](https://github.com/rbxts-rs/rbxts-rs) is a separate native rewrite of roblox-ts, in Rust. It requires tsconfig changes, and it supports Flamework natively through its own plugin system, which rbxtsgo doesn't. It's worth a look if that's what you need.
|
|
152
|
+
|
|
153
|
+
## Development
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
bash scripts/setup-third-party.sh
|
|
157
|
+
go build ./...
|
|
158
|
+
go test ./...
|
|
159
|
+
bash scripts/setup-diff-corpus.sh # needs node and npm: installs roblox-ts@3.0.0 and the corpus dependencies into .scratch/
|
|
160
|
+
bash scripts/scoreboard.sh # the differential scoreboard
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Some tests skip themselves when their dependencies aren't installed. [docs/](docs/README.md) has the design notes, and [testdata/differential/README.md](testdata/differential/README.md) describes the differential harness.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT. See [LICENSE](LICENSE).
|
|
168
|
+
|
|
169
|
+
rbxtsgo is a port of roblox-ts and its libraries, and is built on TypeScript. Their license texts are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|