diff --git a/doc/manual/souce/components.md b/doc/manual/souce/components.md index e01dbbf..83f50b3 100644 --- a/doc/manual/souce/components.md +++ b/doc/manual/souce/components.md @@ -30,10 +30,13 @@ Important paths: ```text crates/decodal-wasm/ -site/decodal-site/src/wasm/ +packages/decodal-wasm/ ``` -The generated files in `site/decodal-site/src/wasm/` are committed so the site can build without requiring every consumer to run `wasm-pack` first. +The npm package is `decodal-wasm`. +The JSR package is `@hare/decodal-wasm`. + +The generated files in `packages/decodal-wasm/` are committed so the site can build without requiring every consumer to run `wasm-pack` first. The WebAssembly package is for execution, not syntax highlighting. ## Web editor components diff --git a/doc/manual/souce/development.md b/doc/manual/souce/development.md index 736fe6f..514920a 100644 --- a/doc/manual/souce/development.md +++ b/doc/manual/souce/development.md @@ -25,7 +25,7 @@ cargo run -q -p decodal-cli --features regex -- examples/regex/main.dcdl The primary crates.io package is `decodal`, which contains the embeddable library. `decodal-derive` provides optional derive macros for Rust struct integration and is published only when the derive crate changes. Workspace support crates such as `decodal-cli` and the Rust source crate `decodal-wasm` are not published to crates.io. -The generated WebAssembly package under `site/decodal-site/src/wasm/` is published to npm and JSR. +The generated WebAssembly package under `packages/decodal-wasm/` is published to npm and JSR. The project is dual licensed as `MIT OR Apache-2.0`. ```sh @@ -72,6 +72,8 @@ site/decodal-site/src/lib/docs.js site/decodal-site/src/lib/highlight.js packages/decodal-codemirror/src/decodal.js packages/decodal-codemirror/src/decodal-parser.js +packages/decodal-wasm/decodal_wasm.js +packages/decodal-wasm/decodal_wasm_bg.wasm crates/decodal-wasm/src/lib.rs ``` @@ -87,7 +89,7 @@ npm run build `npm run build:wasm` writes generated files into: ```text -site/decodal-site/src/wasm/ +packages/decodal-wasm/ ``` These generated files are committed so the site can be built without requiring every consumer to regenerate the wasm package first. @@ -95,7 +97,7 @@ These generated files are committed so the site can be built without requiring e Publish the generated WebAssembly package from its package directory: ```sh -cd site/decodal-site/src/wasm +cd packages/decodal-wasm npm publish npx jsr publish ``` diff --git a/packages/decodal-wasm/.gitignore b/packages/decodal-wasm/.gitignore new file mode 100644 index 0000000..da002a4 --- /dev/null +++ b/packages/decodal-wasm/.gitignore @@ -0,0 +1 @@ +# wasm-pack output is committed for the browser runtime package. diff --git a/packages/decodal-wasm/README.md b/packages/decodal-wasm/README.md new file mode 100644 index 0000000..7a33125 --- /dev/null +++ b/packages/decodal-wasm/README.md @@ -0,0 +1,39 @@ +# decodal-wasm + +WebAssembly runtime package for Decodal. + +This package exposes the Decodal evaluator to browsers and other JavaScript runtimes that can load WebAssembly modules. +It is generated from the Rust crate in `crates/decodal-wasm` with `wasm-pack` and is used by the official playground. + +Use `decodal-codemirror` separately when you need CodeMirror 6 language support. + +## Install + +```sh +npm install decodal-wasm +``` + +JSR: + +```sh +deno add jsr:@hare/decodal-wasm +``` + +## Usage + +```js +import init, { evaluateProject } from 'decodal-wasm'; + +await init(); + +const result = evaluateProject(JSON.stringify({ + entry: 'main.dcdl', + files: { + 'main.dcdl': 'Server = { port = Int default 8080; };', + }, +})); + +console.log(JSON.parse(result)); +``` + +The exported functions return JSON strings so callers can handle diagnostics and successful results without depending on Rust data structures. diff --git a/site/decodal-site/src/wasm/decodal_wasm.d.ts b/packages/decodal-wasm/decodal_wasm.d.ts similarity index 100% rename from site/decodal-site/src/wasm/decodal_wasm.d.ts rename to packages/decodal-wasm/decodal_wasm.d.ts diff --git a/site/decodal-site/src/wasm/decodal_wasm.js b/packages/decodal-wasm/decodal_wasm.js similarity index 100% rename from site/decodal-site/src/wasm/decodal_wasm.js rename to packages/decodal-wasm/decodal_wasm.js diff --git a/site/decodal-site/src/wasm/decodal_wasm_bg.wasm b/packages/decodal-wasm/decodal_wasm_bg.wasm similarity index 100% rename from site/decodal-site/src/wasm/decodal_wasm_bg.wasm rename to packages/decodal-wasm/decodal_wasm_bg.wasm diff --git a/site/decodal-site/src/wasm/decodal_wasm_bg.wasm.d.ts b/packages/decodal-wasm/decodal_wasm_bg.wasm.d.ts similarity index 100% rename from site/decodal-site/src/wasm/decodal_wasm_bg.wasm.d.ts rename to packages/decodal-wasm/decodal_wasm_bg.wasm.d.ts diff --git a/site/decodal-site/src/wasm/jsr.json b/packages/decodal-wasm/jsr.json similarity index 100% rename from site/decodal-site/src/wasm/jsr.json rename to packages/decodal-wasm/jsr.json diff --git a/site/decodal-site/src/wasm/package.json b/packages/decodal-wasm/package.json similarity index 100% rename from site/decodal-site/src/wasm/package.json rename to packages/decodal-wasm/package.json diff --git a/site/decodal-site/package-lock.json b/site/decodal-site/package-lock.json index cd9fdc8..6abbea4 100644 --- a/site/decodal-site/package-lock.json +++ b/site/decodal-site/package-lock.json @@ -16,6 +16,7 @@ "astro": "^4.16.18", "codemirror": "^6.0.2", "decodal-codemirror": "file:../../packages/decodal-codemirror", + "decodal-wasm": "file:../../packages/decodal-wasm", "marked": "^12.0.2" }, "devDependencies": { @@ -32,6 +33,10 @@ "@lezer/lr": "^1.4.10" } }, + "../../packages/decodal-wasm": { + "version": "0.1.2", + "license": "MIT OR Apache-2.0" + }, "node_modules/@astrojs/check": { "version": "0.9.9", "resolved": "https://registry.npmjs.org/@astrojs/check/-/check-0.9.9.tgz", @@ -3250,6 +3255,10 @@ "resolved": "../../packages/decodal-codemirror", "link": true }, + "node_modules/decodal-wasm": { + "resolved": "../../packages/decodal-wasm", + "link": true + }, "node_modules/decode-named-character-reference": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", diff --git a/site/decodal-site/package.json b/site/decodal-site/package.json index 0127f54..ac74f41 100644 --- a/site/decodal-site/package.json +++ b/site/decodal-site/package.json @@ -7,7 +7,7 @@ "dev": "astro dev --host 0.0.0.0", "build": "astro build", "preview": "astro preview --host 0.0.0.0", - "build:wasm": "wasm-pack build ../../crates/decodal-wasm --target web --out-dir ../../site/decodal-site/src/wasm --release", + "build:wasm": "wasm-pack build ../../crates/decodal-wasm --target web --out-dir ../../packages/decodal-wasm --release && node scripts/prepare-wasm-package.mjs", "deploy": "npm run build && node scripts/deploy-pages.mjs", "deploy:wasm": "npm run build:wasm && npm run deploy" }, @@ -20,6 +20,7 @@ "astro": "^4.16.18", "codemirror": "^6.0.2", "decodal-codemirror": "file:../../packages/decodal-codemirror", + "decodal-wasm": "file:../../packages/decodal-wasm", "marked": "^12.0.2" }, "devDependencies": { diff --git a/site/decodal-site/scripts/prepare-wasm-package.mjs b/site/decodal-site/scripts/prepare-wasm-package.mjs new file mode 100644 index 0000000..250aae1 --- /dev/null +++ b/site/decodal-site/scripts/prepare-wasm-package.mjs @@ -0,0 +1,53 @@ +import { writeFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +const packageDir = resolve(import.meta.dirname, '../../../packages/decodal-wasm'); + +writeFileSync( + resolve(packageDir, '.gitignore'), + '# wasm-pack output is committed for the browser runtime package.\n', +); + +writeFileSync( + resolve(packageDir, 'README.md'), + `# decodal-wasm + +WebAssembly runtime package for Decodal. + +This package exposes the Decodal evaluator to browsers and other JavaScript runtimes that can load WebAssembly modules. +It is generated from the Rust crate in \`crates/decodal-wasm\` with \`wasm-pack\` and is used by the official playground. + +Use \`decodal-codemirror\` separately when you need CodeMirror 6 language support. + +## Install + +\`\`\`sh +npm install decodal-wasm +\`\`\` + +JSR: + +\`\`\`sh +deno add jsr:@hare/decodal-wasm +\`\`\` + +## Usage + +\`\`\`js +import init, { evaluateProject } from 'decodal-wasm'; + +await init(); + +const result = evaluateProject(JSON.stringify({ + entry: 'main.dcdl', + files: { + 'main.dcdl': 'Server = { port = Int default 8080; };', + }, +})); + +console.log(JSON.parse(result)); +\`\`\` + +The exported functions return JSON strings so callers can handle diagnostics and successful results without depending on Rust data structures. +`, +); diff --git a/site/decodal-site/src/scripts/playground.js b/site/decodal-site/src/scripts/playground.js index bf9196b..40c3447 100644 --- a/site/decodal-site/src/scripts/playground.js +++ b/site/decodal-site/src/scripts/playground.js @@ -1,4 +1,4 @@ -import init, { evaluateProject } from '../wasm/decodal_wasm.js'; +import init, { evaluateProject } from 'decodal-wasm'; import { EditorView, basicSetup } from 'codemirror'; import { keymap } from '@codemirror/view'; import { decodal } from 'decodal-codemirror'; diff --git a/site/decodal-site/src/wasm/.gitignore b/site/decodal-site/src/wasm/.gitignore deleted file mode 100644 index 0607fb3..0000000 --- a/site/decodal-site/src/wasm/.gitignore +++ /dev/null @@ -1 +0,0 @@ -# wasm-pack output is committed for the playground build. diff --git a/site/decodal-site/src/wasm/README.md b/site/decodal-site/src/wasm/README.md deleted file mode 100644 index fc36662..0000000 --- a/site/decodal-site/src/wasm/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# Decodal - -Decodal is a small deterministic DSL for describing, composing, validating, and materializing structured data. - -It is designed around a lightweight Rust library: - -- host-supplied imports through `SourceLoader` -- no filesystem access in the library core -- concrete and abstract values with constraints and defaults -- deterministic expression evaluation -- optional regex support behind a Cargo feature -- browser playground support through WebAssembly - -## Library crate - -Embedded hosts should depend on `decodal` and provide imports with a `SourceLoader`. - -```toml -[dependencies] -decodal = "0.1" -``` - -## Derive support - -For embedded Rust applications, Decodal can generate a schema and typed decoder from a Rust struct with the `derive` feature. - -```toml -[dependencies] -decodal = { version = "0.1", features = ["derive"] } -``` - -```rust -use decodal::{Decodal, DecodalDecode, DecodalSchema, Engine}; - -#[derive(Decodal)] -struct Service { - name: String, - #[decodal(gt = 443, default = 8443)] - port: i64, - #[decodal(rename = "feature.enable", default = true)] - feature_enabled: bool, -} -``` - -The derive implements: - -- `DecodalSchema`, which produces a host schema for `Engine::bind_global` -- `DecodalDecode`, which converts materialized `Data` into the Rust struct - -## CLI - -A standalone CLI is kept in this repository as the `decodal-cli` workspace package. -It builds a `decodal` binary, but it is not the primary crates.io package. - -Run a Decodal file from the repository: - -```sh -cargo run -q -p decodal-cli -- examples/advanced/main.dcdl -``` - -Enable optional regex support when needed: - -```sh -cargo run -q -p decodal-cli --features regex -- examples/regex/main.dcdl -``` - -## Web playground - -The static documentation site and browser playground live under: - -```text -site/decodal-site/ -``` - -## License - -Licensed under either of: - -- Apache License, Version 2.0 -- MIT license - -at your option.