quilt-wasm 0.4.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 +128 -17
- package/package.json +7 -4
- package/quilt_runtime.js +666 -0
- package/quilt_wasm.d.ts +97 -190
- package/quilt_wasm.js +6 -672
- package/quilt_wasm_raw.d.ts +66 -0
- package/quilt_wasm_raw.js +382 -0
- package/quilt_wasm_raw_bg.wasm +0 -0
- package/quilt_wasm_bg.wasm +0 -0
package/README.md
CHANGED
|
@@ -1,9 +1,16 @@
|
|
|
1
1
|
# quilt-wasm
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
module (`quilt-python/`): the same `QTerm` builder, `qlift`/`qlift_html`,
|
|
6
|
-
`coparse` serializer
|
|
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
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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 `
|
|
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: `
|
|
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
|
-
##
|
|
80
|
+
## Tests
|
|
47
81
|
|
|
48
82
|
```sh
|
|
49
|
-
|
|
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 —
|
|
63
|
-
| `qlift`, `qlift_html` | same; lift `number`/`string`/`boolean
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
a
|
|
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": "
|
|
8
|
-
"version": "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
|
-
"
|
|
15
|
+
"quilt_runtime.js",
|
|
16
|
+
"quilt_wasm.d.ts",
|
|
16
17
|
"quilt_wasm.js",
|
|
17
|
-
"
|
|
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",
|