etassia 0.1.0 → 0.1.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/README.md +90 -10
- package/dist/etassia.wasm +0 -0
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,15 +1,95 @@
|
|
|
1
|
-
# etassia
|
|
1
|
+
# etassia
|
|
2
2
|
|
|
3
|
-
TypeScript binding for the Etassia
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
The npm package `etassia` is the TypeScript binding for the Etassia diagram
|
|
4
|
+
engine: a Mermaid-syntax diagram source is rendered to SVG by the Rust runtime
|
|
5
|
+
(`crates/etassia-wasm` on the `wasm32-unknown-unknown` target), which ships
|
|
6
|
+
inside the package as WebAssembly. All rendering, including number formatting,
|
|
7
|
+
happens in Rust; JavaScript only moves bytes. The package is a single
|
|
8
|
+
platform-independent artifact, because the same `.wasm` binary serves every
|
|
9
|
+
operating system and processor architecture that Node.js 20 or newer supports.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install etassia
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
6
18
|
|
|
7
19
|
```ts
|
|
8
|
-
import { render, detect, UnportedError, EtassiaError } from "etassia
|
|
9
|
-
|
|
10
|
-
|
|
20
|
+
import { render, detect, UnportedError, EtassiaError } from "etassia";
|
|
21
|
+
|
|
22
|
+
try {
|
|
23
|
+
const svg = render("pie\n \"a\": 1\n"); // SVG bytes, produced entirely by the Rust runtime
|
|
24
|
+
} catch (e) {
|
|
25
|
+
if (e instanceof UnportedError) {
|
|
26
|
+
// The runtime has no renderer for this diagram type; use the Ruby fallback.
|
|
27
|
+
} else if (e instanceof EtassiaError) {
|
|
28
|
+
// The source is invalid: errorClass, line and col describe the failure.
|
|
29
|
+
}
|
|
30
|
+
}
|
|
11
31
|
```
|
|
12
32
|
|
|
13
|
-
`
|
|
14
|
-
|
|
15
|
-
|
|
33
|
+
`detect(source)` returns the diagram type name and throws `EtassiaError` when
|
|
34
|
+
the type is undetectable.
|
|
35
|
+
|
|
36
|
+
## Engine pinning and releases
|
|
37
|
+
|
|
38
|
+
Every release of this package vendors the engine built from one exact
|
|
39
|
+
etassia-rs commit. The commit is recorded in `etassia-rs-version.txt` at the
|
|
40
|
+
repository root, and the `etassia-rs` git submodule is pinned to the same
|
|
41
|
+
commit. The ride ritual is that the package version and the pin move together
|
|
42
|
+
in one commit: an engine update is a version bump plus the new pin, and no
|
|
43
|
+
release ships a wasm binary whose provenance is not the recorded commit. At
|
|
44
|
+
build time, `scripts/build-wasm.mjs` reads the pin and fetches the engine
|
|
45
|
+
source for that commit from codeload.github.com into `tmp/engine`; a local
|
|
46
|
+
etassia-rs checkout is used instead when the `ETASSIA_ENGINE_DIR` environment
|
|
47
|
+
variable names it. The golden corpus that the tests and the smoke check render
|
|
48
|
+
against comes from the same submodule, so the corpus and the engine are pinned
|
|
49
|
+
together.
|
|
50
|
+
|
|
51
|
+
Releases are cut by pushing a tag of the form `etassia-ts-v<version>`, where
|
|
52
|
+
the version equals the `version` field of `package.json`, and the release
|
|
53
|
+
workflow fails when the two differ. Publication to npm uses Trusted Publishing
|
|
54
|
+
(OIDC), which signs the published tarball with provenance that npm verifies
|
|
55
|
+
against this repository and this workflow file.
|
|
56
|
+
|
|
57
|
+
## Development
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
npm ci
|
|
61
|
+
npm run build # fetches the pinned engine, builds crates/etassia-wasm, compiles src/ to dist/
|
|
62
|
+
npm test # renders the whole golden corpus through the wasm build and byte-compares it with Ruby
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`npm test` requires the `wasm32-unknown-unknown` Rust target; the build script
|
|
66
|
+
installs it through rustup when rustup is available. When `ETASSIA_ENGINE_DIR`
|
|
67
|
+
points at a local etassia-rs checkout, the build compiles that checkout instead
|
|
68
|
+
of the pin, which is the workflow for engine development.
|
|
69
|
+
|
|
70
|
+
The installed tarball is smoked separately from the build: `npm pack` produces
|
|
71
|
+
the tarball, the tarball is installed into a clean project, and
|
|
72
|
+
`scripts/smoke_installed_npm.mjs` renders one golden case and compares the
|
|
73
|
+
result byte for byte with the Ruby-rendered reference.
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
mkdir -p pkg && npm pack --pack-destination pkg
|
|
77
|
+
# in a clean project, with the tarball and the two golden files copied in:
|
|
78
|
+
npm install --no-audit --no-fund ./etassia-*.tgz
|
|
79
|
+
node scripts/smoke_installed_npm.mjs \
|
|
80
|
+
etassia-rs/golden/pie/pie_spec-0b1f3197.mmd \
|
|
81
|
+
etassia-rs/golden/pie/pie_spec-0b1f3197.svg
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## WebAssembly notes
|
|
85
|
+
|
|
86
|
+
The shipped `dist/etassia.wasm` is the raw cdylib output of
|
|
87
|
+
`crates/etassia-wasm`; the package does not run the wasm-bindgen command-line
|
|
88
|
+
tool and does not generate glue code. `src/index.ts` instantiates the module
|
|
89
|
+
directly and supplies the one import that the binary declares on the render
|
|
90
|
+
path, the `__wbg_getRandomValues_*` stub that fills the entropy request of the
|
|
91
|
+
getrandom dependency, which seeds hash generators; every other stub throws when
|
|
92
|
+
called, which keeps an unexpected import visible instead of silent. Rendering
|
|
93
|
+
allocates the source in linear memory, calls `etassia_render` or
|
|
94
|
+
`etassia_detect`, and reads the result back through the result pointer; the
|
|
95
|
+
source allocation is released even when the call fails.
|
package/dist/etassia.wasm
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "etassia",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "TypeScript binding for the Etassia Rust runtime (etassia-core compiled to WebAssembly)",
|
|
5
5
|
"license": "BSD-2-Clause",
|
|
6
|
-
"repository": { "type": "git", "url": "git+https://github.com/etassia/etassia-
|
|
6
|
+
"repository": { "type": "git", "url": "git+https://github.com/etassia/etassia-ts.git" },
|
|
7
7
|
"type": "module",
|
|
8
8
|
"main": "dist/index.js",
|
|
9
9
|
"types": "dist/index.d.ts",
|
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
"scripts": {
|
|
14
14
|
"build:wasm": "node scripts/build-wasm.mjs",
|
|
15
15
|
"build": "npm run build:wasm && tsc -p tsconfig.json",
|
|
16
|
-
"test": "npm run build && node --test test/golden.test.mjs"
|
|
16
|
+
"test": "npm run build && node --test test/golden.test.mjs",
|
|
17
|
+
"prepublishOnly": "npm run build"
|
|
17
18
|
},
|
|
18
19
|
"devDependencies": {
|
|
19
20
|
"@types/node": "^22.0.0",
|