etassia 0.0.0-stage → 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 +94 -2
- package/dist/etassia.wasm +0 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +77 -0
- package/package.json +21 -4
package/README.md
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
-
#
|
|
1
|
+
# etassia
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
18
|
+
|
|
19
|
+
```ts
|
|
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
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
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.
|
|
Binary file
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** Thrown when the Rust runtime has no renderer for this diagram type or construct; use the Ruby fallback. */
|
|
2
|
+
export declare class UnportedError extends Error {
|
|
3
|
+
name: string;
|
|
4
|
+
}
|
|
5
|
+
/** Thrown when the source is invalid (parse error, undetectable type, bad encoding). */
|
|
6
|
+
export declare class EtassiaError extends Error {
|
|
7
|
+
readonly errorClass: string;
|
|
8
|
+
readonly line: number;
|
|
9
|
+
readonly col: number;
|
|
10
|
+
constructor(message: string, errorClass: string, line: number, col: number);
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Render a Mermaid diagram to SVG. The SVG is produced entirely by the Rust
|
|
14
|
+
* runtime (no JS-side reformatting). Throws UnportedError when the Ruby
|
|
15
|
+
* fallback must be used, EtassiaError for invalid input.
|
|
16
|
+
*/
|
|
17
|
+
export declare function render(source: string): string;
|
|
18
|
+
/** Detect the diagram type name of `source`. Throws EtassiaError when undetectable. */
|
|
19
|
+
export declare function detect(source: string): string;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
/** Thrown when the Rust runtime has no renderer for this diagram type or construct; use the Ruby fallback. */
|
|
3
|
+
export class UnportedError extends Error {
|
|
4
|
+
name = "UnportedError";
|
|
5
|
+
}
|
|
6
|
+
/** Thrown when the source is invalid (parse error, undetectable type, bad encoding). */
|
|
7
|
+
export class EtassiaError extends Error {
|
|
8
|
+
errorClass;
|
|
9
|
+
line;
|
|
10
|
+
col;
|
|
11
|
+
constructor(message, errorClass, line, col) {
|
|
12
|
+
super(message);
|
|
13
|
+
this.errorClass = errorClass;
|
|
14
|
+
this.line = line;
|
|
15
|
+
this.col = col;
|
|
16
|
+
this.name = "EtassiaError";
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
// The wasm keeps wasm-bindgen import stubs from parsanol's getrandom dependency
|
|
20
|
+
// (hash seeding). In this unprocessed module getRandomValues receives a plain
|
|
21
|
+
// (ptr, len) pair into linear memory, so it is filled here; every other stub is
|
|
22
|
+
// unreachable on the render path and throws if called.
|
|
23
|
+
let memory;
|
|
24
|
+
const imports = new Proxy({}, {
|
|
25
|
+
get: (_t, mod) => new Proxy({}, {
|
|
26
|
+
get: (_u, name) => {
|
|
27
|
+
if (name.startsWith("__wbg_getRandomValues_")) {
|
|
28
|
+
return (ptr, len) => {
|
|
29
|
+
globalThis.crypto.getRandomValues(new Uint8Array(memory.buffer, ptr, len));
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
return () => {
|
|
33
|
+
throw new Error(`unexpected wasm import ${mod}.${name}`);
|
|
34
|
+
};
|
|
35
|
+
},
|
|
36
|
+
}),
|
|
37
|
+
});
|
|
38
|
+
let instance;
|
|
39
|
+
function wasm() {
|
|
40
|
+
if (!instance) {
|
|
41
|
+
instance = new WebAssembly.Instance(new WebAssembly.Module(readFileSync(new URL("./etassia.wasm", import.meta.url))), imports).exports;
|
|
42
|
+
memory = instance.memory;
|
|
43
|
+
}
|
|
44
|
+
return instance;
|
|
45
|
+
}
|
|
46
|
+
function call(fn, source) {
|
|
47
|
+
const w = wasm();
|
|
48
|
+
const bytes = new TextEncoder().encode(source);
|
|
49
|
+
const ptr = w.etassia_alloc(bytes.length);
|
|
50
|
+
new Uint8Array(w.memory.buffer, ptr, bytes.length).set(bytes);
|
|
51
|
+
let status;
|
|
52
|
+
try {
|
|
53
|
+
status = w[fn](ptr, bytes.length);
|
|
54
|
+
}
|
|
55
|
+
finally {
|
|
56
|
+
w.etassia_dealloc(ptr, bytes.length);
|
|
57
|
+
}
|
|
58
|
+
const out = new TextDecoder().decode(new Uint8Array(w.memory.buffer, w.etassia_result_ptr(), w.etassia_result_len()));
|
|
59
|
+
if (status === 0)
|
|
60
|
+
return out;
|
|
61
|
+
const e = JSON.parse(out);
|
|
62
|
+
if (e.class === "Unported")
|
|
63
|
+
throw new UnportedError(e.message);
|
|
64
|
+
throw new EtassiaError(e.message, e.class, e.line, e.col);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Render a Mermaid diagram to SVG. The SVG is produced entirely by the Rust
|
|
68
|
+
* runtime (no JS-side reformatting). Throws UnportedError when the Ruby
|
|
69
|
+
* fallback must be used, EtassiaError for invalid input.
|
|
70
|
+
*/
|
|
71
|
+
export function render(source) {
|
|
72
|
+
return call("etassia_render", source);
|
|
73
|
+
}
|
|
74
|
+
/** Detect the diagram type name of `source`. Throws EtassiaError when undetectable. */
|
|
75
|
+
export function detect(source) {
|
|
76
|
+
return call("etassia_detect", source);
|
|
77
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "etassia",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
}
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "TypeScript binding for the Etassia Rust runtime (etassia-core compiled to WebAssembly)",
|
|
5
|
+
"license": "BSD-2-Clause",
|
|
6
|
+
"repository": { "type": "git", "url": "git+https://github.com/etassia/etassia-ts.git" },
|
|
7
|
+
"type": "module",
|
|
8
|
+
"main": "dist/index.js",
|
|
9
|
+
"types": "dist/index.d.ts",
|
|
10
|
+
"exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
|
|
11
|
+
"files": ["dist"],
|
|
12
|
+
"engines": { "node": ">=20" },
|
|
13
|
+
"scripts": {
|
|
14
|
+
"build:wasm": "node scripts/build-wasm.mjs",
|
|
15
|
+
"build": "npm run build:wasm && tsc -p tsconfig.json",
|
|
16
|
+
"test": "npm run build && node --test test/golden.test.mjs",
|
|
17
|
+
"prepublishOnly": "npm run build"
|
|
18
|
+
},
|
|
19
|
+
"devDependencies": {
|
|
20
|
+
"@types/node": "^22.0.0",
|
|
21
|
+
"typescript": "^5.6.0"
|
|
22
|
+
}
|
|
23
|
+
}
|