js: design record for the JavaScript back end (step 1 of #63)

orion commented

2026-10-29 18:49:23 +00:00

Collaborator

Context

Step 1 of #63 (backend: JavaScript). The JavaScript back end is too large for one PR, so it starts with its design record, as #410 did for the native bodies, #413 for the collections and #459 for foreign functions. Everything up to the typed IR is shared, the kernel of natives is closed (docs/design/NATIVES.md, groups K1 to K8) and the two open technical questions are decided (docs/design/JAVASCRIPT-AND-PHP.md sections 2a and 2b, landed with #417). What is missing is the mapping from the IR to JavaScript text and the slicing of the work, so that the implementation steps of #63 can each be one PR.

What

A new design record docs/design/JAVASCRIPT-BACKEND.md (with its entry in docs/design/index.md and a link from JAVASCRIPT-AND-PHP.md and docs/ROADMAP.md milestone 9), specifying and justifying, from the existing back ends (compiler/src/backend/c, compiler/src/backend/bytecode) and the IR (compiler/src/ir):

Module layout and driver: where the back end lives (compiler/src/backend/javascript/), the flag (torb build --target js or the existing --target mechanism, whichever docs/tooling/torb-build.md allows), output shape (ES modules, one file per module or one bundle), how main and test are run under Node in CI (.forgejo/actions/node exists).
IR to JavaScript, construct by construct: functions and calls, structs and enums (layouts and niches are hints and are ignored), closures and captures, generics (monomorphized and dictionary passing, as in the other back ends), traits and dynamic dispatch, strings (TorbScript strings are UTF-8 bytes with byteAt and sliceBytes; JavaScript's are UTF-16: the representation and its cost), Buffer/Array storage (typed arrays or plain arrays per element type), panics and main's exit code.
The kernel groups K1 to K8 each mapped to a JavaScript implementation: K1/K2/K7 by the Int rules of section 2a (the runtime functions, which natives are number-only), K3 bit-exact libm (state which Math functions V8 answers bit for bit and which need a TorbScript or table-driven implementation, with a test plan), K6 via DataView.
Memory: reference counting only for types that may hold a Close object (DESTRUCTORS.md section 2a), copy on write for var paths on host-collected memory, and how isSame is answered.
Tasks as promises (section 2): async functions versus a state machine, cancellation, runToEnd() in a browser, structured concurrency and the Close order.
The slices of #63 in order, each one PR-sized, with the acceptance test of each (first slice: integers, functions, structs and print running a first conformance program under Node; then the remaining language, the kernel, tasks, the conformance subset per the capability table of 2b), and which slices touch natives or the seed (the two-commit rule applies to those).

Acceptance criteria

docs/design/JAVASCRIPT-BACKEND.md exists with sections 1 to 6 above, each decision with its reasoning; the record names the first implementation slice precisely enough to be filed as the next issue.
Facts about V8/Node behaviour that the decisions rest on (UTF-16 versus UTF-8 cost, Math determinism, promise ordering) are measured or cited, with the Node version.
docs/design/index.md, JAVASCRIPT-AND-PHP.md (status line, section 1 pointer) and ROADMAP milestone 9 link the record; skills/ is regenerated if the repo's docs check asks for it.
Docs only, one docs(design) Conventional Commit. Seed: untouched (no syntax change, no native, no driver flag, no std name).

Source

Specification: docs/design/JAVASCRIPT-AND-PHP.md (sections 1, 2, 2a, 2b), docs/design/NATIVES.md, docs/ARCHITECTURE.md "Back Ends", docs/design/DESTRUCTORS.md section 2a, docs/design/CONCURRENCY.md.
Parent: #63. Independent of #62 (the PHP version does not affect this record).

## Context Step 1 of #63 (backend: JavaScript). The JavaScript back end is too large for one PR, so it starts with its design record, as #410 did for the native bodies, #413 for the collections and #459 for foreign functions. Everything up to the typed IR is shared, the kernel of natives is closed (`docs/design/NATIVES.md`, groups K1 to K8) and the two open technical questions are decided (`docs/design/JAVASCRIPT-AND-PHP.md` sections 2a and 2b, landed with #417). What is missing is the mapping from the IR to JavaScript text and the slicing of the work, so that the implementation steps of #63 can each be one PR. ## What A new design record `docs/design/JAVASCRIPT-BACKEND.md` (with its entry in `docs/design/index.md` and a link from `JAVASCRIPT-AND-PHP.md` and `docs/ROADMAP.md` milestone 9), specifying and justifying, from the existing back ends (`compiler/src/backend/c`, `compiler/src/backend/bytecode`) and the IR (`compiler/src/ir`): 1. **Module layout and driver:** where the back end lives (`compiler/src/backend/javascript/`), the flag (`torb build --target js` or the existing `--target` mechanism, whichever `docs/tooling/torb-build.md` allows), output shape (ES modules, one file per module or one bundle), how `main` and `test` are run under Node in CI (`.forgejo/actions/node` exists). 2. **IR to JavaScript, construct by construct:** functions and calls, structs and enums (layouts and niches are hints and are ignored), closures and captures, generics (monomorphized and dictionary passing, as in the other back ends), traits and dynamic dispatch, strings (TorbScript strings are UTF-8 bytes with `byteAt` and `sliceBytes`; JavaScript's are UTF-16: the representation and its cost), `Buffer`/`Array` storage (typed arrays or plain arrays per element type), panics and `main`'s exit code. 3. **The kernel groups K1 to K8** each mapped to a JavaScript implementation: K1/K2/K7 by the `Int` rules of section 2a (the runtime functions, which natives are `number`-only), K3 bit-exact libm (state which `Math` functions V8 answers bit for bit and which need a TorbScript or table-driven implementation, with a test plan), K6 via `DataView`. 4. **Memory:** reference counting only for types that may hold a `Close` object (DESTRUCTORS.md section 2a), copy on write for `var` paths on host-collected memory, and how `isSame` is answered. 5. **Tasks as promises** (section 2): `async` functions versus a state machine, cancellation, `runToEnd()` in a browser, structured concurrency and the `Close` order. 6. **The slices of #63** in order, each one PR-sized, with the acceptance test of each (first slice: integers, functions, structs and `print` running a first conformance program under Node; then the remaining language, the kernel, tasks, the conformance subset per the capability table of 2b), and which slices touch natives or the seed (the two-commit rule applies to those). ## Acceptance criteria - [ ] `docs/design/JAVASCRIPT-BACKEND.md` exists with sections 1 to 6 above, each decision with its reasoning; the record names the first implementation slice precisely enough to be filed as the next issue. - [ ] Facts about V8/Node behaviour that the decisions rest on (UTF-16 versus UTF-8 cost, `Math` determinism, promise ordering) are measured or cited, with the Node version. - [ ] `docs/design/index.md`, `JAVASCRIPT-AND-PHP.md` (status line, section 1 pointer) and ROADMAP milestone 9 link the record; `skills/` is regenerated if the repo's docs check asks for it. - [ ] Docs only, one `docs(design)` Conventional Commit. **Seed: untouched** (no syntax change, no native, no driver flag, no std name). ## Source - Specification: `docs/design/JAVASCRIPT-AND-PHP.md` (sections 1, 2, 2a, 2b), `docs/design/NATIVES.md`, `docs/ARCHITECTURE.md` "Back Ends", `docs/design/DESTRUCTORS.md` section 2a, `docs/design/CONCURRENCY.md`. - Parent: #63. Independent of #62 (the PHP version does not affect this record).

orion added this to the Milestone 9: JavaScript and PHP milestone

2026-10-29 18:49:23 +00:00

orion added the

loop

ready

labels

2026-10-29 18:49:23 +00:00

orion referenced this issue

2026-10-29 18:49:32 +00:00

backend: JavaScript #63

orion commented

2026-10-29 19:56:30 +00:00