typenative 0.5.0 → 0.6.0

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.
Files changed (144) hide show
  1. package/.github/workflows/ci.yml +2 -2
  2. package/.github/workflows/npm-publish-github-packages.yml +2 -2
  3. package/CHANGELOG.md +271 -1
  4. package/CONTRIBUTION.md +2 -1
  5. package/README.md +15 -7
  6. package/bin/cli.js +1 -0
  7. package/bin/index.js +62 -3
  8. package/bin/main.js +1 -0
  9. package/bin/node/core.js +41 -0
  10. package/bin/node/events.js +15 -10
  11. package/bin/node/process.js +13 -0
  12. package/bin/node/punycode.js +2 -2
  13. package/bin/node/timers.js +4 -2
  14. package/bin/node/url.js +1 -1
  15. package/bin/parse-node.js +2 -2
  16. package/bin/regex_vm.js +2057 -0
  17. package/bin/transpiler.js +17225 -4830
  18. package/bin/typecheck-node.js +2 -1
  19. package/bin/version.js +1 -1
  20. package/conformance.md +57 -15
  21. package/examples/README.md +46 -23
  22. package/examples/angular-templates/README.md +139 -0
  23. package/examples/angular-templates/bench.mjs +173 -0
  24. package/examples/angular-templates/dom-type-globals.d.ts +21 -0
  25. package/examples/angular-templates/dom-type-stubs.ts +21 -0
  26. package/examples/angular-templates/main.ts +135 -0
  27. package/examples/angular-templates/parity.mjs +157 -0
  28. package/examples/angular-templates/run-node.mjs +69 -0
  29. package/examples/angular-templates/vendor/angular/compiler/LICENSE +21 -0
  30. package/examples/desktop-notes/README.md +11 -13
  31. package/examples/dupe-finder/README.md +7 -5
  32. package/examples/fibonacci/README.md +7 -7
  33. package/examples/hello-world/README.md +6 -6
  34. package/examples/json-server/README.md +19 -18
  35. package/examples/mandelbrot-png/README.md +11 -13
  36. package/examples/marked-cli/README.md +38 -37
  37. package/examples/openai-chat/README.md +148 -0
  38. package/examples/openai-chat/bench.mjs +175 -0
  39. package/examples/openai-chat/main.ts +488 -0
  40. package/examples/react-compiler/README.md +170 -0
  41. package/examples/react-compiler/bench.mjs +181 -0
  42. package/examples/react-compiler/main.ts +158 -0
  43. package/examples/react-compiler/parity.mjs +362 -0
  44. package/examples/react-compiler/run-node.mjs +88 -0
  45. package/examples/react-compiler/vendor/babel/LICENSE +22 -0
  46. package/examples/react-compiler/vendor/babel/helper-globals/data/builtin-lower.json +15 -0
  47. package/examples/react-compiler/vendor/babel/helper-globals/data/builtin-upper.json +51 -0
  48. package/examples/react-compiler/vendor/charcodes/package.json +25 -0
  49. package/examples/react-compiler/vendor/invariant/LICENSE +21 -0
  50. package/examples/react-compiler/vendor/invariant/invariant.cjs +51 -0
  51. package/examples/react-compiler/vendor/invariant/invariant.d.cts +11 -0
  52. package/examples/react-compiler/vendor/invariant/types/LICENSE +21 -0
  53. package/examples/react-compiler/vendor/jridgewell/gen-mapping/LICENSE +19 -0
  54. package/examples/react-compiler/vendor/jridgewell/resolve-uri/LICENSE +19 -0
  55. package/examples/react-compiler/vendor/jridgewell/sourcemap-codec/LICENSE +19 -0
  56. package/examples/react-compiler/vendor/jridgewell/trace-mapping/LICENSE +19 -0
  57. package/examples/react-compiler/vendor/js-tokens/LICENSE +21 -0
  58. package/examples/react-compiler/vendor/js-tokens/index.cjs +23 -0
  59. package/examples/react-compiler/vendor/js-tokens/index.d.cts +13 -0
  60. package/examples/react-compiler/vendor/jsesc/LICENSE-MIT.txt +20 -0
  61. package/examples/react-compiler/vendor/jsesc/jsesc.cjs +337 -0
  62. package/examples/react-compiler/vendor/jsesc/jsesc.d.cts +384 -0
  63. package/examples/react-compiler/vendor/jsesc/types/LICENSE +21 -0
  64. package/examples/react-compiler/vendor/picocolors/LICENSE +15 -0
  65. package/examples/react-compiler/vendor/picocolors/picocolors.cjs +75 -0
  66. package/examples/react-compiler/vendor/picocolors/picocolors.d.cts +5 -0
  67. package/examples/react-compiler/vendor/picocolors/types.d.ts +51 -0
  68. package/examples/react-compiler/vendor/react-compiler/LICENSE +21 -0
  69. package/examples/react-compiler/vendor/stubs/babel-core.ts +31 -0
  70. package/examples/react-compiler/vendor/stubs/debug.ts +18 -0
  71. package/examples/react-compiler/vendor/stubs/js-tokens.d.ts +13 -0
  72. package/examples/react-compiler/vendor/stubs/pretty-format.ts +18 -0
  73. package/examples/react-compiler/vendor/zod/LICENSE +21 -0
  74. package/examples/react-compiler/vendor/zod-validation-error/LICENSE +9 -0
  75. package/examples/react-compiler/vendor/zod-validation-error/lib/utils/NonEmptyArray.ts +5 -0
  76. package/examples/react-compiler/vendor/zod-validation-error/lib/utils/joinPath.ts +49 -0
  77. package/examples/react-compiler/vendor/zod-validation-error/lib/utils/joinValues.ts +48 -0
  78. package/examples/react-compiler/vendor/zod-validation-error/lib/utils/stringify.ts +50 -0
  79. package/examples/react-compiler/vendor/zod-validation-error/lib/utils/titleCase.ts +6 -0
  80. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/MessageBuilder.ts +126 -0
  81. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/ValidationError.ts +39 -0
  82. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/custom.ts +12 -0
  83. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/errorMap.ts +78 -0
  84. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/index.ts +2 -0
  85. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidElement.ts +12 -0
  86. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidKey.ts +12 -0
  87. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidStringFormat.ts +131 -0
  88. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidType.ts +54 -0
  89. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidUnion.ts +12 -0
  90. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/invalidValue.ts +40 -0
  91. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/notMultipleOf.ts +12 -0
  92. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/tooBig.ts +76 -0
  93. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/tooSmall.ts +76 -0
  94. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/types.ts +27 -0
  95. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/errorMap/unrecognizedKeys.ts +27 -0
  96. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/fromError.ts +13 -0
  97. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/fromZodError.ts +61 -0
  98. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/fromZodIssue.ts +38 -0
  99. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/index.ts +20 -0
  100. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/isValidationError.ts +5 -0
  101. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/isValidationErrorLike.ts +8 -0
  102. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/isZodErrorLike.ts +11 -0
  103. package/examples/react-compiler/vendor/zod-validation-error/lib/v4/toValidationError.ts +20 -0
  104. package/examples/react-compiler/vendor.mjs +688 -0
  105. package/examples/todo-cli/README.md +9 -9
  106. package/examples/yaml-cli/README.md +38 -28
  107. package/package.json +8 -5
  108. package/performance/README.md +195 -0
  109. package/performance/any-dynamic.ts +21 -0
  110. package/performance/any-record-view.ts +20 -0
  111. package/performance/arr-hof.ts +21 -0
  112. package/performance/arr-push-index.ts +15 -0
  113. package/performance/arr-sort.ts +21 -0
  114. package/performance/async-await.ts +24 -0
  115. package/performance/class-dispatch.ts +52 -0
  116. package/performance/events-emit.ts +27 -0
  117. package/performance/exc-throw-rare.ts +25 -0
  118. package/performance/exc-try-catch.ts +26 -0
  119. package/performance/fn-closures.ts +29 -0
  120. package/performance/fn-recursion-tree.ts +31 -0
  121. package/performance/gen-for-of.ts +46 -0
  122. package/performance/json-roundtrip.ts +27 -0
  123. package/performance/map-delete.ts +24 -0
  124. package/performance/map-string-keys.ts +22 -0
  125. package/performance/num-arith-loop.ts +14 -0
  126. package/performance/num-bitwise.ts +21 -0
  127. package/performance/num-mod-int.ts +16 -0
  128. package/performance/num-to-string.ts +16 -0
  129. package/performance/obj-alloc.ts +32 -0
  130. package/performance/regex-exec.ts +29 -0
  131. package/performance/regex-site.ts +28 -0
  132. package/performance/set-ops.ts +20 -0
  133. package/performance/str-char-scan.ts +35 -0
  134. package/performance/str-concat-plus.ts +18 -0
  135. package/performance/str-concat.ts +24 -0
  136. package/performance/str-short-scan.ts +26 -0
  137. package/performance/str-split-join.ts +23 -0
  138. package/performance/str-template.ts +16 -0
  139. package/performance/union-switch.ts +57 -0
  140. package/tsparser/check.go +2 -1
  141. package/tsparser/main.go +1 -0
  142. package/types/typenative-npm.d.ts +3 -2
  143. package/types/typenative.d.ts +42 -12
  144. package/ROUND2-HANDOFF.md +0 -200
@@ -61,24 +61,24 @@ Reproduce with `node bench.mjs [n=35] [runs=15]`. The script compiles
61
61
  reports two numbers per run: the program's own in-process compute time
62
62
  (parsed from its output) and the total wall time including process startup.
63
63
 
64
- **Environment:** Windows 11 Pro, AMD Ryzen 5 5500U, Node v24.19.0, Go 1.26.0,
65
- TypeNative 0.4.0, default (non-`--release`) build.
64
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600, Node v26.13.0, Go 1.27.4,
65
+ TypeNative 0.5.0 (unreleased changes), default (non-`--release`) build.
66
66
 
67
67
  Compute time, `fib(35)` over 15 runs (measured in-program):
68
68
 
69
69
  | Runtime | min | median | mean | max |
70
70
  |------------|-----------|-----------|-----------|-----------|
71
- | Node.js | 93.53 ms | 94.81 ms | 96.43 ms | 101.84 ms |
72
- | TypeNative | 42.61 ms | 50.16 ms | 49.57 ms | 54.02 ms |
71
+ | Node.js | 72.86 ms | 73.81 ms | 73.89 ms | 75.60 ms |
72
+ | TypeNative | 33.94 ms | 36.37 ms | 37.32 ms | 48.15 ms |
73
73
 
74
74
  Total wall time per run, including startup (spawn to exit):
75
75
 
76
76
  | Runtime | min | median | mean | max |
77
77
  |------------|-----------|-----------|-----------|-----------|
78
- | Node.js | 197.57 ms | 203.96 ms | 209.96 ms | 227.60 ms |
79
- | TypeNative | 63.76 ms | 65.49 ms | 66.83 ms | 78.75 ms |
78
+ | Node.js | 129.75 ms | 134.23 ms | 135.53 ms | 144.45 ms |
79
+ | TypeNative | 42.45 ms | 45.12 ms | 53.19 ms | 153.97 ms |
80
80
 
81
- **TypeNative computes 1.9x faster** and finishes the whole run **3.1x
81
+ **TypeNative computes 2.0x faster** and finishes the whole run **3.0x
82
82
  faster**. The recursive calls, arithmetic, and number boxing all compile
83
83
  ahead of time to native machine code via Go, while V8 must tier up through
84
84
  its JIT before it reaches comparable speed — and never reaches it here, since
@@ -47,16 +47,16 @@ the TypeNative CLI, then times **complete process runs** (spawn to exit) of
47
47
  the same program under both runtimes. Since the program does no work, the
48
48
  numbers are almost entirely startup time.
49
49
 
50
- **Environment:** Windows 11 Pro, AMD Ryzen 5 5500U, Node v24.19.0, Go 1.26.0,
51
- TypeNative 0.4.0, default (non-`--release`) build.
50
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600, Node v26.13.0, Go 1.27.4,
51
+ TypeNative 0.5.0 (unreleased changes), default (non-`--release`) build.
52
52
 
53
53
  | Runtime | min | median | mean | max |
54
54
  |------------|------------|------------|------------|------------|
55
- | Node.js | 97.07 ms | 103.45 ms | 104.51 ms | 125.91 ms |
56
- | TypeNative | 12.95 ms | 14.72 ms | 15.18 ms | 25.11 ms |
55
+ | Node.js | 54.40 ms | 62.40 ms | 62.86 ms | 78.77 ms |
56
+ | TypeNative | 6.42 ms | 7.38 ms | 10.98 ms | 112.02 ms |
57
57
 
58
- **TypeNative starts 7.0x faster** (median). The compiled binary is a
59
- self-contained 2.4 MB executable: there is no runtime to boot, no module
58
+ **TypeNative starts 8.5x faster** (median). The compiled binary is a
59
+ self-contained 2.7 MB executable: there is no runtime to boot, no module
60
60
  system to initialize, and no JIT to warm up, so process-to-output latency is
61
61
  an order of magnitude lower. For CLI tools that are invoked frequently, this
62
62
  is the difference users notice.
@@ -100,28 +100,29 @@ response) and `POST /todos` (10,000 requests).
100
100
  The load generator is built to stay out of the way, like `wrk` or
101
101
  `autocannon`: 8 worker threads × 2 raw keep-alive sockets send prebuilt
102
102
  request bytes and read each response just far enough to find its end. A
103
- plain `node:http` client tops out around 8–11k req/s on this machine, so
103
+ plain `node:http` client would cap out far below either server, so
104
104
  with it both servers would simply tie at the client's limit.
105
105
 
106
- **Environment:** Windows 11 Pro, AMD Ryzen 5 5500U, Node v24.19.0, Go 1.26.0,
107
- TypeNative 0.4.0, default (non-`--release`) build, client and server on the
108
- same machine. Re-run variation is about ±10%; across runs TypeNative was
109
- 1.2–1.3x Node on GET and 1.2–1.4x on POST.
106
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600, Node v26.13.0, Go 1.27.4,
107
+ TypeNative 0.5.0 (unreleased changes), default (non-`--release`) build, client
108
+ and server on the same machine. Re-run variation is about ±20%; across runs
109
+ TypeNative was 0.7x Node on GET and 0.8–0.9x on POST.
110
110
 
111
111
  | Runtime | Endpoint | req/s | p50 (ms) | p99 (ms) |
112
112
  |------------|-------------|-------:|---------:|---------:|
113
- | Node.js | GET /todos | 13379 | 1.02 | 3.03 |
114
- | TypeNative | GET /todos | 17794 | 0.66 | 1.87 |
115
- | Node.js | POST /todos | 15405 | 0.94 | 2.17 |
116
- | TypeNative | POST /todos | 19581 | 0.60 | 2.32 |
117
-
118
- **TypeNative serves ~1.3x more requests per second**, with lower median
119
- latency on both routes. JavaScript still runs one thing at a time, as in
120
- Node, but the compiled server spreads everything around it — socket reads
121
- and writes, HTTP parsing — across Go's `net/http` goroutines, and runs the
122
- handler right on the request's goroutine whenever the event loop is free.
123
-
124
- On top of that, the binary starts in ~15 ms instead of ~100 ms and is a
125
- single 9.7 MB executable with zero dependencies — `scp` it to a server and
113
+ | Node.js | GET /todos | 60034 | 0.24 | 0.69 |
114
+ | TypeNative | GET /todos | 44334 | 0.27 | 0.64 |
115
+ | Node.js | POST /todos | 66687 | 0.21 | 0.44 |
116
+ | TypeNative | POST /todos | 57707 | 0.20 | 0.63 |
117
+
118
+ **Node serves ~1.2–1.4x more requests per second here**, with similar
119
+ median latency on both routes. The compiled server spreads socket reads and
120
+ writes and HTTP parsing across Go's `net/http` goroutines, and runs the
121
+ handler right on the request's goroutine whenever the event loop is free,
122
+ but JavaScript still runs one thing at a time, and at 45–65k req/s the cost
123
+ of handing each request to that one thread outweighs the parallel I/O.
124
+
125
+ On top of that, the binary starts in ~7 ms instead of ~60 ms and is a
126
+ single 11.4 MB executable with zero dependencies — `scp` it to a server and
126
127
  run it, no Node install, no `node_modules` — and CPU-heavy work inside a
127
128
  handler runs ~2x faster (see the [fibonacci example](../fibonacci/README.md)).
@@ -4,7 +4,7 @@ Renders the Mandelbrot set and writes it as a PNG. The PNG encoder is about
4
4
  40 lines of TypeScript on top of `node:zlib` (`deflateSync` for the pixel
5
5
  data, `crc32` for the chunk checksums). The program needs no image library,
6
6
  no native addon such as `sharp` or `canvas`, and no `node_modules`: the
7
- compiled binary is a single 3.3 MB file.
7
+ compiled binary is a single 4.2 MB file.
8
8
 
9
9
  Demonstrates: a tight floating-point loop, a function returning a tuple that
10
10
  the caller destructures, `Uint8Array` / `DataView` big-endian writes,
@@ -46,20 +46,18 @@ script compiles `main.ts`, times **complete process runs** (spawn to exit) of
46
46
  both runtimes rendering the same image, then decodes both PNGs (checking every
47
47
  chunk CRC) and compares the pixels.
48
48
 
49
- **Environment:** Windows 11 Pro, AMD Ryzen 5 5500U, Node v24.19.0, Go 1.26.0,
50
- TypeNative 0.4.1, default (non-`--release`) build.
49
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600, Node v26.13.0, Go 1.27.4,
50
+ TypeNative 0.5.0 (unreleased changes), default (non-`--release`) build.
51
51
 
52
52
  | Runtime | min | median | mean | max |
53
53
  |------------|-----------|-----------|-----------|-----------|
54
- | Node.js | 678.34 ms | 744.01 ms | 769.12 ms | 918.37 ms |
55
- | TypeNative | 591.29 ms | 596.63 ms | 599.53 ms | 623.04 ms |
56
-
57
- **TypeNative is 1.2x faster end to end** (median), and its run-to-run spread
58
- is much tighter (32 ms vs 240 ms). There's no JIT warm-up and no GC pauses
59
- from a large heap. The render loop itself takes about the same time in both
60
- runtimes (~530 ms). V8 compiles a tight float loop like the escape-time
61
- iteration into machine code about as good as Go's. The difference comes from
62
- startup (~100 ms) and slightly faster deflate. For recursion and
54
+ | Node.js | 499.84 ms | 513.64 ms | 508.85 ms | 518.01 ms |
55
+ | TypeNative | 449.83 ms | 452.28 ms | 466.67 ms | 599.75 ms |
56
+
57
+ **TypeNative is 1.1x faster end to end** (median). There's no JIT warm-up.
58
+ The render loop itself takes about the same time in both runtimes. V8 compiles a tight float loop like the escape-time
59
+ iteration into machine code about as good as Go's. The difference is mostly
60
+ Node's startup. For recursion and
63
61
  call-heavy code the compute gap is larger (see [fibonacci](../fibonacci/),
64
- 1.9x). This example's main advantage is distribution: one dependency-free
62
+ 2.0x). This example's main advantage is distribution: one dependency-free
65
63
  binary that writes images.
@@ -92,68 +92,69 @@ checks that the two HTML outputs are identical:
92
92
  emphasis, links and code spans, lists, tables, code fences and block quotes,
93
93
  from a fixed-seed generator, so every machine gets the same input).
94
94
 
95
- **Environment:** Linux 6.18 container, 4 vCPUs of an Intel Xeon @ 2.10GHz,
96
- Node v24.22.1, Go 1.26.0, TypeNative 0.4.2 (unreleased changes), default
97
- (non-`--release`) build. The binary is 6.3 MB.
95
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600 (6 cores, 12 threads),
96
+ Node v26.13.0, Go 1.27.4, TypeNative 0.5.0 (unreleased changes), default
97
+ (non-`--release`) build. The binary is 6.5 MB.
98
98
 
99
99
  (a) `marked < README.md` (3.5 KB), 30 runs each:
100
100
 
101
101
  | Runtime | min | median | mean | max |
102
102
  | ---------- | --------- | --------- | --------- | --------- |
103
- | Node.js | 129.00 ms | 148.15 ms | 148.71 ms | 191.32 ms |
104
- | TypeNative | 18.04 ms | 19.46 ms | 19.71 ms | 25.27 ms |
103
+ | Node.js | 112.27 ms | 118.78 ms | 119.48 ms | 128.69 ms |
104
+ | TypeNative | 13.10 ms | 14.12 ms | 20.74 ms | 210.83 ms |
105
105
 
106
106
  (b) `marked < generated.md` (10.0 MB, 114,893 lines), 5 runs each:
107
107
 
108
- | Runtime | min | median | mean | max | MB/s (median) |
109
- | ---------- | --------- | --------- | --------- | --------- | ------------- |
110
- | Node.js | 1,969 ms | 2,053 ms | 2,056 ms | 2,164 ms | 4.87 |
111
- | TypeNative | 10,378 ms | 10,573 ms | 10,685 ms | 11,006 ms | 0.95 |
108
+ | Runtime | min | median | mean | max | MB/s (median) |
109
+ | ---------- | -------- | -------- | -------- | -------- | ------------- |
110
+ | Node.js | 1,187 ms | 1,197 ms | 1,197 ms | 1,206 ms | 8.35 |
111
+ | TypeNative | 1,880 ms | 1,890 ms | 1,909 ms | 1,968 ms | 5.29 |
112
112
 
113
- **Per call, TypeNative is 7.6x faster** (19 ms vs 148 ms, median). Node's
113
+ **Per call, TypeNative is 8.4x faster** (14 ms vs 119 ms, median). Node's
114
114
  cost here is mostly startup: it loads and type-strips the 13 TypeScript files
115
115
  and compiles marked's regexes on every run. That's what you feel when a docs
116
116
  build or a hook renders one file per process.
117
117
 
118
- **On bulk throughput, TypeNative is 5.2x slower.** On a long input V8's JIT
119
- and its regex engine (Irregexp compiles hot patterns to machine code) run
118
+ **On bulk throughput, TypeNative is 1.6x slower.** On a long input V8's JIT
119
+ and its regex engine (Irregexp compiles hot patterns to machine code) still run
120
120
  marked faster than the compiled Go does. In a profile of the native run on
121
- 1 MB, lexing takes half the CPU and TypeNative's backtracking regex engine
122
- about a third of it: marked's patterns use lookarounds and backreferences, so
123
- most of them can't run on Go's RE2, and the backtracker interprets them node
124
- by node. Garbage collection takes about a third more on the other cores (each
125
- token is an object, each match a few strings). Both costs grow linearly with
126
- the input, while Node's head start is fixed, so the native binary finishes
127
- first up to about 150–200 KB of markdown per process:
121
+ 10 MB, about 30% of the main thread is TypeNative's regex VM, which interprets
122
+ marked's patterns where Irregexp runs them as machine code, and allocation is
123
+ about 15%: each token is an object and each match a few strings. Garbage
124
+ collection runs on other cores and hardly affects the wall clock. Both costs
125
+ grow linearly with the input, while Node's head start is fixed, so the native
126
+ binary finishes first up to about 1–1.5 MB of markdown per process:
128
127
 
129
128
  | Input | Node.js | TypeNative |
130
129
  | ------ | ------- | ---------- |
131
- | 16 KB | 153 ms | 37 ms |
132
- | 64 KB | 167 ms | 96 ms |
133
- | 128 KB | 182 ms | 149 ms |
134
- | 256 KB | 215 ms | 287 ms |
135
- | 1 MB | 377 ms | 1,051 ms |
130
+ | 512 KB | 162 ms | 100 ms |
131
+ | 1 MB | 203 ms | 186 ms |
132
+ | 2 MB | 294 ms | 359 ms |
136
133
 
137
134
  (Medians of 5 full process runs each, same generator.)
138
135
 
139
- The ReDoS inputs show the same split. The 28 of them take 3.4 s natively in
140
- total and 4.1 s under Node, but the worst one, 10,000 underscores
141
- (`quadratic_emstrong_delim`), takes 1.4 s natively against Node's 0.25 s. Each
142
- underscore restarts a pattern that scans the rest of the run, so the work is
143
- quadratic in both engines and the backtracker's constant factor shows.
136
+ The ReDoS inputs now favor the native binary: all of them together take 4.7 s
137
+ natively and 13 s under Node, though most of Node's time there is starting up
138
+ once per input. The slowest native case, `quadratic_inline_masking`, takes
139
+ 0.7 s against Node's 0.9 s.
144
140
 
145
141
  Getting here fixed performance bugs in TypeNative's runtime and compiler, all
146
142
  general:
147
143
 
148
- - The backtracking engine converted the whole input to runes on every match
149
- attempt, making a lexer that matches at each position quadratic. It now
150
- works on byte offsets.
151
- - A greedy repeat of one character class no longer allocates, and ASCII is
152
- tested against a table, which took the worst ReDoS input from 6.3 s to 1.4 s.
153
- - A regex whose match must start with certain bytes skips ahead to them, and
154
- an anchored one fails at once, instead of RE2 scanning the rest of a long
155
- input on every call.
144
+ - Every regex now runs on one engine, a backtracking VM with JS semantics, in
145
+ place of Go's RE2 for simple patterns and a closure-based matcher for the
146
+ rest. A match allocates only its result. First-byte sets, literal prefixes
147
+ and anchors reject most calls without running anything, which matters here
148
+ because 83% of marked's 1.5 million regex calls per MB miss. RE2 remains as a
149
+ fallback: a pattern it can run that exhausts the VM's step budget switches to
150
+ it, so those patterns keep their linear-time guarantee.
151
+ - Regex literals are compiled once, however many times they're evaluated.
152
+ - `a += b` on a long string held as any is amortized: the string is extended
153
+ in place when it ends where its buffer's written part ends. It used to copy
154
+ on every append, which made the worst ReDoS input take over 10 s.
156
155
  - Strings built with `+=` in a loop are `strings.Builder`s, so rendering a
157
156
  long document is linear.
157
+ - Short ASCII strings need no code-point index, and slices of a long non-ASCII
158
+ string share its index instead of rebuilding it.
158
159
  - Type inference is memoized per query. marked's
159
160
  `edit(re).replace(…).replace(…)…` chains took exponential time to compile.
@@ -0,0 +1,148 @@
1
+ # OpenAI-compatible chat CLI
2
+
3
+ A terminal chat client for any OpenAI-compatible API. Answers **stream into
4
+ the terminal token by token** while the model is still writing them. It works
5
+ with the free OpenRouter API out of the box — no payment, just a key from
6
+ [openrouter.ai/keys](https://openrouter.ai/keys) — and with OpenAI, Ollama,
7
+ LM Studio, vLLM, or any other server that speaks `/v1/chat/completions`.
8
+
9
+ Demonstrates: WHATWG `fetch` with a **streaming response body**
10
+ (`response.body.getReader()` read in a loop), hand-parsed server-sent events
11
+ (`data:` lines, comments, `[DONE]`), `TextDecoder` with `{ stream: true }`,
12
+ `AbortController` + `setTimeout` as a request timeout, `node:readline/promises`
13
+ driven by `for await`, `JSON.parse` on each chunk, `process.env` / `argv`
14
+ handling, and writing deltas to `process.stdout` the moment they arrive — all
15
+ in one dependency-free file that runs unchanged under Node and as a compiled
16
+ binary.
17
+
18
+ ## Usage
19
+
20
+ ```sh
21
+ openai-chat # interactive multi-turn REPL
22
+ openai-chat "Explain SSE in one sentence" # one question, streamed answer, exit
23
+ openai-chat --model google/gemma-4-31b-it:free
24
+ openai-chat --system "Answer in as few words as possible"
25
+ ```
26
+
27
+ In the REPL each message sees the whole conversation. Slash commands:
28
+ `/exit` (or Ctrl+D) quits, `/clear` resets the conversation,
29
+ `/system <text>` sets or replaces the system prompt. Ctrl+C aborts the answer
30
+ in flight without killing the session.
31
+
32
+ | Option | Meaning | Default |
33
+ |--------|---------|---------|
34
+ | `--model <id>` | Model id | provider default (`google/gemma-4-31b-it:free` on OpenRouter, `gpt-4o-mini` on OpenAI) |
35
+ | `--base-url <url>` | API root | `https://openrouter.ai/api/v1`, or `https://api.openai.com/v1` when only `OPENAI_API_KEY` is set |
36
+ | `--api-key <key>` | API key | `OPENROUTER_API_KEY`, else `OPENAI_API_KEY` |
37
+ | `--system <prompt>` | System prompt | none |
38
+ | `--max-tokens <n>` | Cap on generated tokens | provider default |
39
+
40
+ Other OpenAI-compatible servers, no account needed:
41
+
42
+ ```sh
43
+ ollama serve # then:
44
+ openai-chat --base-url http://127.0.0.1:11434/v1 --api-key ollama --model llama3.2
45
+ ```
46
+
47
+ A one-shot run keeps stdout clean — only the answer goes to stdout, the
48
+ token/time stats go to stderr — so piping works:
49
+
50
+ ```sh
51
+ openai-chat "write a haiku about go channels" | tee haiku.txt
52
+ ```
53
+
54
+ ## Run it
55
+
56
+ Get a free OpenRouter key, then:
57
+
58
+ ```sh
59
+ # sh
60
+ export OPENROUTER_API_KEY=sk-or-...
61
+ node main.ts "hello!" # under Node.js 24+
62
+ ```
63
+
64
+ ```sh
65
+ # with TypeNative, build one binary and run it
66
+ npx typenative --source main.ts --output dist/openai-chat.exe --release
67
+ ./dist/openai-chat.exe
68
+ ```
69
+
70
+ From a checkout of this repository:
71
+
72
+ ```sh
73
+ node bin/cli.js --source examples/openai-chat/main.ts --output dist/openai-chat.exe
74
+ ```
75
+
76
+ ## How the streaming works
77
+
78
+ `streamChat` POSTs the conversation with `stream: true` and
79
+ `stream_options: { include_usage: true }`. The response body is a
80
+ server-sent-event stream, read incrementally:
81
+
82
+ ```ts
83
+ const reader = response.body.getReader();
84
+ const decoder = new TextDecoder();
85
+ while (!finished) {
86
+ const { value, done } = await reader.read();
87
+ if (done) break;
88
+ buffer += decoder.decode(value, { stream: true }); // don't split UTF-8 mid-character
89
+ // ... peel off complete lines, collect `data:` lines, dispatch on blank lines
90
+ }
91
+ ```
92
+
93
+ One SSE event is one or more `data:` lines ended by a blank line; the line
94
+ `data: [DONE]` ends the stream, and `: OPENROUTER PROCESSING` comment lines
95
+ (the provider's keep-alive) are ignored. Each event's JSON carries a
96
+ `choices[0].delta.content` fragment, which is printed as it arrives. A
97
+ malformed frame is skipped, not fatal. Errors surface the provider's own
98
+ message (`HTTP 401: No auth credentials found`), connection failures get a
99
+ friendly hint, and every request is bounded by an `AbortController` timeout.
100
+
101
+ ## Benchmark: Node.js vs TypeNative
102
+
103
+ Reproduce with `node bench.mjs [runs=30]`. A real API call spends its time
104
+ waiting on the model, which would hide any client-side difference, so the
105
+ bench stands up a local mock API (plain `node:http`) that answers
106
+ `POST /v1/chat/completions` with a deterministic 46-chunk event stream sent
107
+ with pauses between chunks — the same shape OpenRouter and OpenAI return.
108
+ First both runtimes answer the same question once and their stdout is
109
+ compared byte for byte (**parity: identical, and equal to the streamed
110
+ answer**). Then it times full process runs (spawn to exit) of the one-shot
111
+ client, which covers startup, the HTTP round trip, and parsing the stream as
112
+ it arrives.
113
+
114
+ **Environment:** Windows 11 Pro, AMD Ryzen 5 7600, Node v26.13.0, Go 1.27.4,
115
+ TypeNative 0.5.0 (unreleased changes), default (non-`--release`) build.
116
+
117
+ | Runtime | min | median | mean | max |
118
+ |------------|-----------|-----------|-----------|-----------|
119
+ | Node.js | 775.24 ms | 780.34 ms | 782.11 ms | 796.46 ms |
120
+ | TypeNative | 698.90 ms | 715.82 ms | 712.61 ms | 722.34 ms |
121
+
122
+ **TypeNative is 1.1x faster per answer** (median). The ratio looks small
123
+ because both runtimes spend most of each run waiting for the mock's paced
124
+ chunks — that part is identical by construction. The client-side share
125
+ (startup, connect, first byte) is where they differ: about 65 ms of the
126
+ median run, mostly Node's ~60 ms startup. For an interactive chat session
127
+ the numbers that matter are the first token and memory, and the binary starts
128
+ about 8x faster and holds a fraction of Node's idle memory.
129
+
130
+ ## Notes for your own streaming clients
131
+
132
+ Two TypeScript patterns that look natural but hit transpiler sharp edges
133
+ while writing this example (both are avoided above; TypeNative 0.4.1):
134
+
135
+ - `continue`/`break` out of a loop from inside a `catch` block does not
136
+ compile (`continue is not in a loop`) — the catch is emitted as its own Go
137
+ function. Set a flag in the catch and act on it after.
138
+ - `return` inside a `catch` block sets the return value but **falls through**
139
+ to the statements after the try/catch, unlike Node. Assign a result
140
+ variable instead:
141
+
142
+ ```ts
143
+ try { throw new Error('boom'); } catch { return 42; }
144
+ console.error('reached in Go, skipped in Node');
145
+ ```
146
+
147
+ Streaming itself needs no special support: `fetch`, reader loops, async
148
+ iteration over readline, and `AbortController` all behave as under Node.
@@ -0,0 +1,175 @@
1
+ // One-shot latency benchmark: Node.js vs TypeNative for the chat client.
2
+ //
3
+ // A chat request spends most of its time waiting on the model, so this bench
4
+ // measures what a client actually adds: process startup, opening the HTTPS
5
+ // connection, and parsing the SSE stream as it arrives. A local mock server
6
+ // (plain node:http) stands in for the API: it answers POST
7
+ // /v1/chat/completions with a deterministic event stream of ~45 chunks sent
8
+ // with pauses between them, exactly the shape OpenRouter and OpenAI return.
9
+ //
10
+ // First both runtimes answer the same question once and their stdout is
11
+ // compared byte for byte (parity). Then N full process runs (spawn to exit)
12
+ // of the one-shot client are timed against the mock.
13
+ //
14
+ // Usage: node bench.mjs [runs=30]
15
+
16
+ import { spawn, spawnSync } from 'node:child_process';
17
+ import http from 'node:http';
18
+ import fs from 'node:fs';
19
+ import path from 'node:path';
20
+ import { fileURLToPath } from 'node:url';
21
+
22
+ const here = path.dirname(fileURLToPath(import.meta.url));
23
+ const repoRoot = path.resolve(here, '..', '..');
24
+ const cli = path.join(repoRoot, 'bin', 'cli.js');
25
+ const runs = Number(process.argv[2] ?? '30') || 30;
26
+ const exeName = process.platform === 'win32' ? 'openai-chat.exe' : 'openai-chat';
27
+ const exePath = path.join(here, 'dist', exeName);
28
+
29
+ // The deterministic answer the mock streams, one chunk per word
30
+ const words = [
31
+ 'Server-sent', 'events', 'are', 'just', 'a', 'long', 'HTTP', 'response:', 'the', 'server',
32
+ 'keeps', 'the', 'connection', 'open', 'and', 'writes', '"data:"', 'lines', 'separated', 'by',
33
+ 'blank', 'lines.', 'A', 'chat', 'client', 'reads', 'each', 'event', 'as', 'it', 'arrives,',
34
+ 'pulls', 'the', 'text', 'delta', 'out', 'of', 'its', 'JSON,', 'and', 'prints', 'it', 'immediately.',
35
+ ];
36
+ const expectedAnswer = words.join(' ');
37
+ const expectedUsage = { prompt_tokens: 11, completion_tokens: words.length, total_tokens: 11 + words.length };
38
+
39
+ const chunkJson = (delta, extra = {}) =>
40
+ JSON.stringify({
41
+ id: 'chatcmpl-bench',
42
+ object: 'chat.completion.chunk',
43
+ created: 1700000000,
44
+ model: 'bench-model',
45
+ choices: [{ index: 0, delta, finish_reason: null }],
46
+ ...extra,
47
+ });
48
+
49
+ function startMockServer() {
50
+ const server = http.createServer((req, res) => {
51
+ if (req.method !== 'POST' || !req.url.endsWith('/chat/completions')) {
52
+ res.writeHead(404, { 'content-type': 'application/json' });
53
+ res.end(JSON.stringify({ error: { message: 'not found' } }));
54
+ return;
55
+ }
56
+ if (req.headers.authorization !== 'Bearer bench-key') {
57
+ res.writeHead(401, { 'content-type': 'application/json' });
58
+ res.end(JSON.stringify({ error: { message: 'Invalid API key' } }));
59
+ return;
60
+ }
61
+ req.resume();
62
+ res.writeHead(200, { 'content-type': 'text/event-stream' });
63
+ // The keep-alive comment real providers send while the model warms up
64
+ res.write(': OPENROUTER PROCESSING\n\n');
65
+ const events = [
66
+ `data: ${chunkJson({ role: 'assistant' })}\n\n`,
67
+ ...words.map((word, i) => `data: ${chunkJson({ content: word + (i < words.length - 1 ? ' ' : '') })}\n\n`),
68
+ `data: ${chunkJson({}, { choices: [{ index: 0, delta: {}, finish_reason: 'stop' }], usage: expectedUsage })}\n\n`,
69
+ 'data: [DONE]\n\n',
70
+ ];
71
+ let i = 0;
72
+ const tick = () => {
73
+ if (i < events.length) {
74
+ res.write(events[i++]);
75
+ setTimeout(tick, 4);
76
+ } else {
77
+ res.end();
78
+ }
79
+ };
80
+ tick();
81
+ });
82
+ return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));
83
+ }
84
+
85
+ function stats(samples) {
86
+ const sorted = [...samples].sort((a, b) => a - b);
87
+ const mean = samples.reduce((sum, x) => sum + x, 0) / samples.length;
88
+ return { min: sorted[0], median: sorted[Math.floor(sorted.length / 2)], mean, max: sorted[sorted.length - 1] };
89
+ }
90
+
91
+ function fmt(ms) {
92
+ return `${ms.toFixed(2)} ms`.padStart(11);
93
+ }
94
+
95
+ // Async spawn on purpose: the mock API lives in this process's event loop,
96
+ // and spawnSync would block the loop so the server could never answer.
97
+ function oneShot(command, args) {
98
+ return new Promise((resolve) => {
99
+ const child = spawn(command, args, {
100
+ cwd: here,
101
+ stdio: ['ignore', 'pipe', 'pipe'],
102
+ env: { ...process.env, OPENROUTER_API_KEY: '', OPENAI_API_KEY: '' },
103
+ });
104
+ let stdout = '';
105
+ let stderr = '';
106
+ child.stdout.on('data', (chunk) => {
107
+ stdout += chunk;
108
+ });
109
+ child.stderr.on('data', (chunk) => {
110
+ stderr += chunk;
111
+ });
112
+ child.on('exit', (code) => resolve({ status: code, stdout, stderr }));
113
+ });
114
+ }
115
+
116
+ // 1. Compile the client to a native binary.
117
+ fs.mkdirSync(path.join(here, 'dist'), { recursive: true });
118
+ console.log('Compiling main.ts to a native binary with TypeNative...');
119
+ const build = spawnSync(process.execPath, [cli, '--source', 'main.ts', '--output', path.join('dist', exeName)], {
120
+ cwd: here,
121
+ stdio: 'inherit',
122
+ });
123
+ if (build.status !== 0) process.exit(build.status ?? 1);
124
+
125
+ // 2. Start the mock API and check both runtimes produce identical output.
126
+ const server = await startMockServer();
127
+ const port = server.address().port;
128
+ const mockBase = `http://127.0.0.1:${port}/v1`;
129
+ const question = 'What are server-sent events?';
130
+ const args = ['--api-key', 'bench-key', '--base-url', mockBase, question];
131
+
132
+ try {
133
+ console.log('\nChecking parity (same question, byte-for-byte stdout)...');
134
+ const nodeRun = await oneShot(process.execPath, ['main.ts', ...args]);
135
+ const nativeRun = await oneShot(exePath, args);
136
+ for (const [name, run] of [['Node.js', nodeRun], ['TypeNative', nativeRun]]) {
137
+ if (run.status !== 0) {
138
+ console.error(`${name} run failed (exit ${run.status}):\n${run.stderr}`);
139
+ process.exit(1);
140
+ }
141
+ if (run.stdout !== `${expectedAnswer}\n`) {
142
+ console.error(`${name} stdout does not match the expected answer:\n"${run.stdout}"`);
143
+ process.exit(1);
144
+ }
145
+ }
146
+ console.log('parity: Node.js and TypeNative stdout identical, matches the streamed answer.');
147
+
148
+ // 3. Time full one-shot runs (spawn -> exit) under both runtimes.
149
+ console.log(`\nTiming ${runs} full one-shot runs of each runtime...\n`);
150
+ const timeRuns = async (command, argv) => {
151
+ const samples = [];
152
+ for (let i = 0; i < runs + 2; i++) {
153
+ const t0 = performance.now();
154
+ const result = await oneShot(command, argv);
155
+ const elapsed = performance.now() - t0;
156
+ if (result.status !== 0) {
157
+ console.error(`run failed: ${command} ${argv.join(' ')}\n${result.stderr}`);
158
+ process.exit(1);
159
+ }
160
+ if (i >= 2) samples.push(elapsed); // first two are warmup
161
+ }
162
+ return stats(samples);
163
+ };
164
+ const nodeStats = await timeRuns(process.execPath, ['main.ts', ...args]);
165
+ const nativeStats = await timeRuns(exePath, args);
166
+
167
+ console.log(`\`openai-chat "<question>"\` against a local SSE server, ${runs} runs (full process: spawn -> exit):\n`);
168
+ console.log('| Runtime | min | median | mean | max |');
169
+ console.log('|------------|-------------|-------------|-------------|-------------|');
170
+ console.log(`| Node.js |${fmt(nodeStats.min)} |${fmt(nodeStats.median)} |${fmt(nodeStats.mean)} |${fmt(nodeStats.max)} |`);
171
+ console.log(`| TypeNative |${fmt(nativeStats.min)} |${fmt(nativeStats.median)} |${fmt(nativeStats.mean)} |${fmt(nativeStats.max)} |`);
172
+ console.log(`\nTypeNative is ${(nodeStats.median / nativeStats.median).toFixed(1)}x faster per answer (median).\n`);
173
+ } finally {
174
+ server.close();
175
+ }