quilt-wasm 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.
package/README.md CHANGED
@@ -1,9 +1,16 @@
1
1
  # quilt-wasm
2
2
 
3
- WebAssembly bindings for Quilt's core IR — the **browser runtime** that expanded
4
- `.ts.quilt` programs target. It is the JS/WASM analog of the `quilt` Python
5
- module (`quilt-python/`): the same `QTerm` builder, `qlift`/`qlift_html`, and
6
- `coparse` serializer, exposed to JavaScript via `wasm-bindgen`.
3
+ Quilt's core IR for JavaScript — the runtime that expanded `.ts.quilt` programs
4
+ target, in a browser and under Node alike. It is the JS analog of the `quilt`
5
+ Python module (`quilt-python/`): the same `QTerm` builder, `qlift`/`qlift_html`,
6
+ and `coparse` serializer.
7
+
8
+ The builder and `coparse` are plain JavaScript (`js/runtime.js`): a term is an
9
+ ordinary object the garbage collector owns. The wasm-bindgen crate (`src/`) is
10
+ only the edges that need Rust — `qlift` of an already-built term, whose output
11
+ comes from the generated tables in `quilt::langs::typescript::ops`, and the
12
+ numbers JavaScript would print in exponent form. Those cross once per call, the
13
+ term sent as a flat buffer (issue #306). See [Performance](#performance).
7
14
 
8
15
  Like `nanobots-codegen`, it depends on `quilt` with
9
16
  `default-features = false, features = ["rust"]`, so it uses only the
@@ -15,18 +22,45 @@ tracked separately as Phase 2 of issue #43.)
15
22
 
16
23
  ```sh
17
24
  # from the repo root
18
- wasm-pack build quilt-wasm --target web # for the browser demos (ESM)
19
- wasm-pack build quilt-wasm --target nodejs # for Node (CommonJS) + tests
25
+ bin/build-ts # for `quilt run` and the tests (= bin/build-wasm nodejs pkg)
26
+ bin/build-wasm web pkg-web # for the browser demos and `quilt notebook --serve` (ESM)
27
+ bin/build-wasm web pkg # the npm package
20
28
  ```
21
29
 
22
- The artifact lands in `quilt-wasm/pkg/` (git-ignored).
30
+ `bin/build-wasm` runs `wasm-pack build --out-name quilt_wasm_raw`, then
31
+ `js/assemble.mjs`, which writes the package entry `quilt_wasm.js` (the runtime,
32
+ bound to the wasm), its `.d.ts`, and `quilt_runtime.js` beside wasm-pack's
33
+ output, and points `package.json` at them. A bare `wasm-pack build` is *not*
34
+ the package: it has only the edge functions.
35
+
36
+ The artifact lands in `quilt-wasm/pkg/` (git-ignored); `examples/web/build.mjs`
37
+ puts its `web` build in `pkg-web/`, so the two never clobber each other.
38
+
39
+ ## `node/` — the Node runtime
40
+
41
+ `quilt run foo.ts.quilt` binds the bare `quilt` import to `node/index.mjs`, which
42
+ re-exports everything below and adds the one operator the wasm runtime cannot
43
+ provide by itself: `↓` (reduce). Reduce has to *re-expand* — a generated stage's
44
+ `coparse()` is still Quilt source — and the expander is not in this crate, so
45
+ `node/` shells out to the `quilt` binary (`$QUILT`), exactly as quilt-python's
46
+ `expand()` does. It is the CLI twin of `examples/web/quilt-rt.js`, which does the
47
+ same job in-page against the WASI expander. See issue #153.
48
+
49
+ ```sh
50
+ bin/build-ts && bin/test-ts # build + run the ↓ tests and .ts.quilt examples
51
+ ```
52
+
53
+ Beyond `↓` it exports `expand(src, chain)` (Quilt source → TypeScript, via the
54
+ binary), `reduce(term)`, and a default export that is a no-op `init()` — so a
55
+ program written against the browser's `--target web` build, which awaits one,
56
+ also runs under `quilt run`.
23
57
 
24
58
  ## Releasing to npm
25
59
 
26
60
  Published to npm as [`quilt-wasm`](https://www.npmjs.com/package/quilt-wasm) — the
27
61
  same bare specifier expanded `.ts.quilt` programs import. The `publish-npm` job
28
62
  in `.github/workflows/ci.yml` runs on every `v*` tag (after the check matrix
29
- passes): it does `wasm-pack build quilt-wasm --target web` and `npm publish`es
63
+ passes): it does `bin/build-wasm web pkg` and `npm publish`es
30
64
  the resulting `pkg/`. The package version tracks the workspace version in
31
65
  `Cargo.toml`.
32
66
 
@@ -35,7 +69,7 @@ Auth is **npm Trusted Publishing (OIDC)** — no secret to manage; GitHub's
35
69
  setup, because npm can only attach a trusted publisher to a package that already
36
70
  exists:
37
71
 
38
- 1. Publish the first version manually: `wasm-pack build quilt-wasm --target web`,
72
+ 1. Publish the first version manually: `bin/build-wasm web pkg`,
39
73
  then `npm login` and `npm publish` from `quilt-wasm/pkg/`.
40
74
  2. On npmjs.com → the package → **Settings → Trusted Publisher**, add a GitHub
41
75
  Actions publisher for repo `QuiltLang/quilt`, workflow `ci.yml`.
@@ -43,11 +77,17 @@ exists:
43
77
  After that every `v*` tag publishes with no token. A version already on npm is a
44
78
  no-op, not a failure.
45
79
 
46
- ## Smoke test
80
+ ## Tests
47
81
 
48
82
  ```sh
49
- wasm-pack build quilt-wasm --target nodejs
50
- node quilt-wasm/test/smoke.cjs
83
+ bin/build-ts
84
+ node quilt-wasm/test/smoke.cjs # the builder API
85
+ node quilt-wasm/test/memory.cjs # expansion costs no wasm memory (bin/test-ts)
86
+ node quilt-wasm/test/differential.cjs # JS coparse/lifts = the Rust QTerm's (bin/test-ts)
87
+ node quilt-wasm/test/corpus.mjs # the shared runtime corpus (bin/test-runtimes)
88
+ node quilt-wasm/test/bench.cjs [other/pkg] # timings against a string template; not a gate
89
+ cargo test -p quilt-wasm --lib # the flat encoding
90
+ QUILT=bin/quilt node quilt-wasm/test/reduce.mjs # `↓`, in node/ (bin/test-ts)
51
91
  ```
52
92
 
53
93
  ## API
@@ -57,12 +97,83 @@ Mirrors the Python runtime one-for-one where the ABIs allow:
57
97
  | Python runtime | quilt-wasm |
58
98
  | --------------------- | ------------------------------------------- |
59
99
  | `tb(tag)` + `.c/.w/.n/.p/.x/.e/.b` | same fluent `WasmBuilder` |
100
+ | (none) | `.t(child)`: the same as `.c`; what expanded code spells (see Memory) |
60
101
  | `leaf/sym/quote/unquote/name` | same free functions |
61
102
  | `cmd/write/push` | same free functions |
62
- | `NL`, `POP`, `HOLE` (constants) | `NL()`, `POP()`, `HOLE()` (functions — wasm-bindgen can't export struct-valued constants) |
63
- | `qlift`, `qlift_html` | same; lift `number`/`string`/`boolean` (no `QTerm` pass-through yet) |
103
+ | `NL`, `POP`, `HOLE` (constants) | `NL()`, `POP()`, `HOLE()` (**functions** — see below) |
104
+ | `qlift`, `qlift_html` | same; lift `number`/`string`/`boolean`, and a `QTerm` |
105
+ | `qlift_text(v, dialect?)`, `qlift_text_in_quotes(v, dialect?)` | same, plus arrays; a dialect is a plain object (`string`, `in_quotes`, `boolean`, `float`, `list_open`, `list_sep`, `list_close`), not a `TextDialect` subclass, and there is no built-in `Raw` — `{ string: (s) => s, in_quotes: (s) => s }` is one |
64
106
  | `term.coparse()` | `term.coparse()` / `term.toString()` |
107
+ | `reduce(term)` / `term.↓` | `node/` only: `reduce(term)` / `term.reduce()` |
108
+ | `expand(src, lang)` | `node/` only: `expand(src, chain)` |
109
+
110
+ A term is immutable once built, so it can be spliced any number of times and
111
+ kept. A builder's methods append to it and return it, so chain in one
112
+ expression or reassign (`b = b.e(x)`), as you would in Rust.
113
+
114
+ ## Memory
115
+
116
+ Terms are plain JavaScript objects, freed by the garbage collector like any
117
+ other, whether a quote built them or the program keeps them in a variable.
118
+ Nothing is held in wasm memory between calls. `free()` and `using` still work,
119
+ as no-ops, for code written when a term was a wasm handle and had to be freed
120
+ (#297); `.t(child)` is from then too.
121
+
122
+ `test/memory.cjs` checks that repeated expansion, and holding the results,
123
+ costs no wasm memory.
124
+
125
+ ## Performance
126
+
127
+ Until #306 a term was a wasm-bindgen wrapper around a Rust `Arc<QTerm>`. Every
128
+ builder call crossed into wasm, allocated a wrapper, and registered it with a
129
+ `FinalizationRegistry`, so most of an expansion's time went to the boundary,
130
+ not to building. `test/bench.cjs` builds the page from the issue — 150 items of
131
+ `html↖<li><b>↙↑(t)↘</b> ↙↑(b)↘</li>↗`, about 3000 terms — and compares it with
132
+ a string template that produces the same text:
133
+
134
+ | | ms per page |
135
+ | --- | ---: |
136
+ | wasm-bindgen terms (before #306) | ~17 |
137
+ | JavaScript terms, `coparse` in JavaScript | ~0.25 |
138
+ | JavaScript terms, `coparse` in wasm (one crossing) | ~2.3 |
139
+ | string template | ~0.07 |
140
+
141
+ (Node 22, Apple silicon; run it for your own numbers.) The third row is the
142
+ other design #306 weighed: building in JavaScript and crossing once to coparse
143
+ in Rust. Copying the tree across costs more than writing it, so `coparse` is in
144
+ JavaScript, held to the Rust one by `test/differential.cjs` and the corpus.
145
+
146
+ ## Divergences from the Python runtime
147
+
148
+ One, deliberate. The shared corpus (`conformance/runtime/cases.json`) drives all
149
+ three runtimes through the same cases, so a change to it shows up as a test
150
+ failure rather than as something a user discovers.
151
+
152
+ ### `NL`/`POP`/`HOLE` are functions here, constants in Python
153
+
154
+ ```js
155
+ cmd(NL()) // quilt-wasm
156
+ [cmd(write("[")), HOLE(), cmd(write("]"))]
157
+ ```
158
+
159
+ ```python
160
+ cmd(NL) # quilt-python
161
+ [cmd(write("[")), HOLE, cmd(write("]"))]
162
+ ```
65
163
 
66
- Builder and term methods that take `self`/a child by value **consume** the JS
67
- object (wasm-bindgen move semantics), so chain in one expression and don't reuse
68
- a spliced term.
164
+ Generated code is always correct for its own target — `TypeScriptMetaLanguage`
165
+ and `PythonMetaLanguage` each emit their runtime's spelling — so this costs
166
+ readers, not programs: porting a metaprogram between the two hosts means
167
+ adding or dropping the parens.
168
+
169
+ Issue #167 kept the functions for two reasons, both about wasm-bindgen: it
170
+ cannot export a module-scope constant, and it *moved* each element of a
171
+ `quote(..)`'s cmds out of its JS wrapper, so a shared `HOLE` would have been
172
+ freed by its first use. Neither holds since #306 — the package entry is
173
+ hand-written JavaScript, and `NL()`, `POP()` and `HOLE()` return shared
174
+ immutable values — but the TypeScript meta still emits the calls, and changing
175
+ that is a change to every expansion, so they stay functions for now.
176
+
177
+ Move semantics, the other divergence the wasm-bindgen classes had (a term
178
+ passed by value was consumed), went with them: nothing here consumes its
179
+ argument.
package/package.json CHANGED
@@ -4,17 +4,20 @@
4
4
  "collaborators": [
5
5
  "Alexander Varga <varga.alex@gmail.com>"
6
6
  ],
7
- "description": "WebAssembly runtime for Quilt's core IR — the browser/Node target of expanded `.ts.quilt` programs (QTerm builder, qlift/qlift_html, coparse) via wasm-bindgen.",
8
- "version": "0.5.0",
7
+ "description": "Quilt's core IR for JavaScript, with WebAssembly at the edges — the browser/Node target of expanded `.ts.quilt` programs (QTerm builder, qlift/qlift_html, coparse).",
8
+ "version": "0.6.0",
9
9
  "license": "MIT OR Apache-2.0",
10
10
  "repository": {
11
11
  "type": "git",
12
12
  "url": "https://github.com/QuiltLang/quilt"
13
13
  },
14
14
  "files": [
15
- "quilt_wasm_bg.wasm",
15
+ "quilt_runtime.js",
16
+ "quilt_wasm.d.ts",
16
17
  "quilt_wasm.js",
17
- "quilt_wasm.d.ts"
18
+ "quilt_wasm_raw.d.ts",
19
+ "quilt_wasm_raw.js",
20
+ "quilt_wasm_raw_bg.wasm"
18
21
  ],
19
22
  "main": "quilt_wasm.js",
20
23
  "types": "quilt_wasm.d.ts",