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 CHANGED
@@ -1,3 +1,95 @@
1
- # Temporary Holding Version
1
+ # etassia
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
@@ -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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }