Skip to main content

Crate noyalib_wasm

Crate noyalib_wasm 

Source
Expand description

noyalib WASM bindings.

Exposes YAML parse/serialize and the lossless Document API to JavaScript via wasm-bindgen.

The pure-Rust logic lives in core so it is reachable from cargo test on the rlib side; the bindings in this module are the thin JsValue conversion shells.

§Cargo features

  • wasm-opt (optional, off by default) — enables a post-build pass that re-runs Binaryen’s wasm-opt -O3 -s on the produced .wasm to shrink the bundle (~17% smaller on noyalib-wasm). Pulls in no extra Rust dependencies; it is a build-script feature only. Disable for fastest dev builds.

Optional noyalib features pulled in by a downstream wasm-pack consumer (schema, parallel …) compile against the wasm32-unknown-unknown target only when their dep tree is WASM-clean — parallel (rayon) requires --target wasm32-wasip1-threads, not the default browser target. The canonical noyalib feature matrix lives in crates/noyalib/src/lib.rs.

§MSRV

Rust 1.85.0 stable. The wasm-bindgen 0.2 ecosystem pulls helpers floored at 1.85; the core noyalib library still builds on 1.75. See workspace POLICIES.md.

§Panics

Public bindings do not panic on well-formed input. Rust-side parse / serialise errors are converted to JsError values that JavaScript receives as a thrown Error; the bindings never unwrap user-supplied data. The remaining sources of panic on the WebAssembly instance are environmental, not logic, and are documented here for completeness:

  • WASM linear-memory exhaustion (OOM). Allocating a Vec or String larger than the host’s WASM memory limit aborts the instance. Browsers default to a 4 GiB cap on wasm32-unknown-unknown. Bound noyalib resource use ahead of time via ParserConfig::strict() or explicit max_* budgets to fail with a structured Error::Budget instead of an OOM abort.
  • Stack overflow. Pathologically deep YAML (>4096 nested nodes by default) is rejected with Error::RecursionLimitExceeded long before the WASM stack overflows; deliberately misconfigured max_depth may overflow the host stack.
  • Host abort on panic = abort. Every release build uses panic = abort (per Cargo.toml), so any logic-level panic terminates the WebAssembly instance with no chance of catch_unwind. console_error_panic_hook is wired in examples/ so debug builds surface a JS-readable trace before the abort.

§Errors

Every fallible binding returns Result<JsValue, JsError>; the JsError carries the Rust-side Display text from noyalib::Error. JavaScript callers handle these as standard thrown errors — try { … } catch (e) { e.message }.

§Concurrency

WebAssembly is single-threaded on browsers (without shared-memory + --enable-experimental-features). The bindings hold no internal state outside the WasmDocument handle; multi-document workloads simply construct multiple handles. Web Workers hosting independent WASM instances are the recommended way to parallelise on the browser.

§Platform support

Builds against every wasm-pack target: bundler (Webpack / Rollup / esbuild / Vite), web (native ES module), nodejs (CommonJS), deno, no-modules (plain global). CI verifies the wasm32-unknown-unknown target each PR via wasm-pack test --node. Cloudflare Workers, Deno, and Bun consume the bundler target via their own packaging step; see crates/noyalib-wasm/doc/bundling.md.

§Performance

Release bundle size: ~338 KB raw, ~140 KB gzip. With the optional wasm-opt post-build pass (--features wasm-opt): ~280 KB raw, ~115 KB gzip. Tree-shaking-friendly: the WasmDocument API and the plain parse / stringify API are independent modules; bundlers drop whichever your code does not import.

§Security

#![forbid(unsafe_code)]. No unsafe outside wasm-bindgen’s own bridge. No network I/O. No filesystem access (browsers sandbox WASM by default; Node and Deno hosts can grant fs access to the host process, but this crate’s bindings do not expose it). Resource-limit gates are inherited from noyalib’s ParserConfig defaults. Full posture: SECURITY.md.

§API stability and SemVer

Pre-1.0 (0.0.x): the JavaScript-facing API (parse, stringify, WasmDocument shape, JSON shape of returned values) is stable within a 0.0.x line — bug fixes only. Adding a new method or option is allowed within a 0.0.x bump; removing or renaming an exported binding, or changing the JSON shape of a returned object, is held to a 0.x bump (e.g. 0.0.x → 0.1.0). The Rust library surface (WasmDocument, core::*) is covered by the workspace SemVer policy in POLICIES.md. cargo-semver-checks runs in CI on every PR.

§Documentation

Modules§

core
Pure-Rust core for the noyalib WASM bindings.

Structs§

WasmDocument
A YAML document with byte-faithful source preservation and path-targeted edits.

Functions§

get_path
Get a value at a dotted path from a YAML string. Bound on the JS side as getPath(yaml, path) per JS naming conventions.
merge
Merge two YAML documents.
parse
Parse a YAML string and return a JS object.
stringify
Serialize a JS object to a YAML string.
validate_json
Validate YAML against the JSON-compatible schema. Bound on the JS side as validateJson(yaml) per JS naming conventions.