@sebastienrousseau/noyalib-wasm 0.0.45 → 0.0.46

package/README.md

@@ -1,377 +1,218 @@
 <!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
 
 <p align="center">
-  <img src="https://cloudcdn.pro/noyalib/v1/logos/noyalib.svg" alt="Noyalib logo" width="128" />
+  <img src="https://cloudcdn.pro/noyalib/v1/logos/noyalib.svg" alt="noyalib-wasm logo" width="128" />
 </p>
 
 <h1 align="center">noyalib-wasm</h1>
 
 <p align="center">
-  <strong><code>wasm-bindgen</code> wrapper around noyalib —
-  pure-Rust YAML 1.2, zero <code>unsafe</code>, ~338 KB after
-  LTO. Runs in browsers, Node, Cloudflare Workers, Deno, and
-  any other WASM-capable host.</strong>
+  Browser and JavaScript bindings for YAML 1.2 parsing and lossless editing.
 </p>
 
 <p align="center">
   <a href="https://github.com/sebastienrousseau/noyalib-wasm/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/noyalib-wasm/ci.yml?style=for-the-badge&logo=github" alt="Build" /></a>
-  <a href="https://www.npmjs.com/package/@sebastienrousseau/noyalib-wasm"><img src="https://img.shields.io/npm/v/@sebastienrousseau/noyalib-wasm?style=for-the-badge&color=fc8d62&logo=npm" alt="npm" /></a>
-  <a href="https://docs.rs/noyalib-wasm"><img src="https://img.shields.io/badge/docs.rs-noyalib--wasm-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" alt="Docs.rs" /></a>
-  <a href="https://bundlephobia.com/package/@sebastienrousseau/noyalib-wasm"><img src="https://img.shields.io/bundlephobia/minzip/@sebastienrousseau/noyalib-wasm?style=for-the-badge&color=informational" alt="Bundle size" /></a>
+  <a href="https://www.npmjs.com/package/@sebastienrousseau/noyalib-wasm"><img src="https://img.shields.io/npm/v/@sebastienrousseau/noyalib-wasm?style=for-the-badge&color=fc8d62&logo=npm" alt="Registry" /></a>
+  <a href="https://docs.rs/noyalib-wasm"><img src="https://img.shields.io/badge/docs.rs-noyalib--wasm-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" alt="Docs" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/noyalib-wasm"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/noyalib-wasm?style=for-the-badge&label=OpenSSF%20Scorecard&logo=openssf" alt="OpenSSF Scorecard" /></a>
-  <a href="https://www.bestpractices.dev/projects/14494"><img src="https://img.shields.io/cii/level/14494?style=for-the-badge&label=OpenSSF%20Best%20Practices&logo=openssf" alt="OpenSSF Best Practices" /></a>
+  <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" /></a>
+  <a href="https://github.com/sebastienrousseau/noyalib-wasm/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/MSRV-1.86.0-93450a.svg?style=for-the-badge&logo=rust" alt="MSRV 1.86.0" /></a>
 </p>
 
 ---
 
 ## Contents
 
-- [Install](#install) — npm, build from source
-- [Requirements](#requirements) — toolchain floor, platforms, the core pin
-- [Quick Start](#quick-start) — parse, edit, validate
-- [Why this approach?](#why-this-approach) — vs `js-yaml`
-- [Surface](#surface) — exported APIs
-- [Bundle size](#bundle-size) — what you ship to users
-- [Targets](#targets) — every wasm-pack flavour
-- [Provenance](#provenance) — npm + cosign
-- [Examples](#examples) — Node + browser demos
-- [When not to use noyalib-wasm](#when-not-to-use-noyalib-wasm)
-- [Documentation](#documentation)
-- [License](#license)
+**Getting started**
 
----
+- [Install](#install) — npm-compatible package managers and source builds
+- [Requirements](#requirements) — toolchain floor, runtimes
+- [Quick Start](#quick-start) — parse, inspect, and edit YAML
 
-## Install
+**The noyalib-wasm ecosystem**
 
-```sh
-npm install @sebastienrousseau/noyalib-wasm
-# or
-pnpm add @sebastienrousseau/noyalib-wasm
-# or
-yarn add @sebastienrousseau/noyalib-wasm
-```
+- [The noyalib-wasm ecosystem](#the-noyalib-wasm-ecosystem) — bindings and companion tools
 
-Or build from source against any wasm-pack target:
+**Library reference**
 
-```sh
-git clone https://github.com/sebastienrousseau/noyalib-wasm
-cd noyalib-wasm
-wasm-pack build --release --target bundler
-```
+- [Capabilities at a glance](#capabilities-at-a-glance) — the current surface by theme
+- [Ecosystem comparison](#ecosystem-comparison) — short matrix; full table at [`docs/COMPARISON.md`](docs/COMPARISON.md)
+- [Benchmarks](#benchmarks) — harness and bundle measurements; full table at [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)
+- [Features](#features) — JavaScript exports
+- [Configuration](#configuration) — wasm-pack targets and build modes
+- [Examples](#examples) — browser and Node examples
 
-> **Split from the monorepo since v0.0.12.** Prior versions
-> shipped from `sebastienrousseau/noyalib/crates/noyalib-wasm/`.
-> From v0.0.12 onward `noyalib-wasm` lives here as its own crate,
-> released in strict lockstep with the parent
-> [`noyalib`](https://github.com/sebastienrousseau/noyalib) at
-> the same version. See
-> [ADR-0005](https://github.com/sebastienrousseau/noyalib/blob/main/docs/adr/0005-workspace-split.md)
-> for the rationale and rollback recipe.
+**Operational**
 
----
+- [When not to use noyalib-wasm](#when-not-to-use-noyalib-wasm) — limitations
+- [Development](#development) — make targets, WASM tests, CI
+- [Security](#security) — guarantees and compliance
+- [Documentation](#documentation) — all reference docs
+- [Stability guarantees](#stability-guarantees) — JavaScript API, SemVer, and toolchain discipline
+- [License](#license)
 
-## Requirements
+---
 
-- **Rust 1.86.0 or newer** to build from source: `rust-version` in
-  the manifest, enforced by the `msrv-core` CI job on every push.
-- **Any tier-1 platform.** CI runs the tests on Linux, macOS, and
-  Windows with the stable, beta, and nightly toolchains; stable is the
-  gate, beta and nightly are early warning.
-- **The matching core.** This crate pins `noyalib` at the identical
-  `=0.0.X` and releases in lockstep with it; Cargo resolves that pin
-  for you.
-- **For the bundle**: `wasm-pack` and a JavaScript runtime that loads
-  WebAssembly (browsers, Node.js 18+, Deno, Bun, Cloudflare Workers).
-  `cargo test` needs neither; the pure-Rust core is tested natively.
+## Install
 
-## Quick Start
+### As a JavaScript library
 
-```js
-import init, {
-  parse,
-  stringify,
-  validateJson,
-  getPath,
-  merge,
-  WasmDocument,
-} from "@sebastienrousseau/noyalib-wasm";
-
-await init();          // load the WASM blob
-
-// Plain parse / stringify — like js-yaml. Mappings come back as
-// plain JS Objects (not `Map`), so dotted property access works.
-const obj = parse("host: api.example.com\nport: 8080\n");
-console.log(obj.host); // "api.example.com"
-const yaml = stringify(obj);
-
-// Indexed read without going through `parse`.
-const port = getPath("host: api.example.com\nport: 8080\n", "port"); // 8080
-
-// JSON-compatible YAML 1.2 schema check.
-validateJson("a: 1\nb: [2, 3]\n"); // true
-
-// Lossless CST edit — comments + indentation preserved.
-const doc = new WasmDocument(source);
-doc.set("server.port", "9090");
-fs.writeFileSync("config.yaml", doc.toString());
+```bash
+npm install @sebastienrousseau/noyalib-wasm@0.0.46
 ```
 
----
-
-## Why this approach?
-
-[`js-yaml`](https://github.com/nodeca/js-yaml) is the de-facto
-JS YAML parser, and it's good — but it makes two tradeoffs that
-hurt for editor and tooling workloads:
-
-1. **`js-yaml` discards comments by spec.** It implements the
-   YAML data model, which excludes comments. Round-tripping a
-   document through `parse` → `dump` strips every `#` line.
-   noyalib's `Document` API runs through a lossless CST that
-   reproduces the source byte-for-byte; only the surgically
-   touched span changes on a `set`.
-
-2. **`js-yaml` follows YAML 1.1 by default.** That's the
-   "Norway problem": `country: NO` parses as `country: false`,
-   silently rewriting the country code. noyalib defaults to
-   YAML 1.2 strict semantics; only `true` / `false` are
-   booleans.
-
-### Custom YAML tags
-
-`parse(yaml)` surfaces YAML tags as plain JS object keys:
-`!Color '#ff8800'` deserialises into `{ "!Color": "#ff8800" }`.
-This matches the serde-bridge convention every other
-`serde-wasm-bindgen` consumer uses (the `Value::Tagged` variant
-serialises as a single-entry map for cross-format interop).
-Round-tripping via `stringify` does **not** restore the
-YAML-tag prefix — the JS object's tag-as-key shape becomes a
-quoted mapping key in the emitted YAML.
-
-For editor / tooling workloads where the YAML-tag wire form
-must survive a parse → emit cycle, use the `WasmDocument`
-class instead. Its `set` / `setValue` are surgical edits
-through the CST, so untouched tag prefixes round-trip
-verbatim:
+`pnpm add` and `yarn add` work with the same package. To build from source:
 
-```js
-const doc = new WasmDocument("color: !Color '#ff8800'\n");
-doc.set("color", "!Color '#00aaff'");           // tag survives
-console.log(doc.toString());                    // "color: !Color '#00aaff'\n"
+```bash
+wasm-pack build --release --target bundler
 ```
 
-Other differences worth knowing about:
-
-- **JSON Schema 2020-12 validation built in.** Same engine as
-  the `noyavalidate` CLI ships.
-- **Pure-Rust, zero `unsafe`.** Every byte of the parser,
-  scanner, formatter, and CST is checked at compile time by the
-  workspace `#![forbid(unsafe_code)]` lint.
-- **~338 KB bundle.** That's roughly the same size as `js-yaml`
-  minified + gzipped, with the lossless-CST surface and YAML
-  1.2 semantics baked in.
-
----
+## Requirements
 
-## Surface
+- Rust **1.86.0 or newer** and `wasm-pack` when building from source.
+- A WebAssembly-capable browser, Node.js, Deno, Bun, or edge runtime.
+- The crate pins `noyalib` at exactly `=0.0.46` under the lockstep contract.
 
-All exports are camelCase, matching JS conventions.
+| Surface | Minimum | Enforcement |
+| :--- | :---: | :--- |
+| Rust crate | Rust 1.86.0 | manifest and MSRV CI |
+| JavaScript package | WebAssembly runtime | Node and browser CI |
 
-### Free functions
+## Quick Start
 
-| Export | What it does |
-|---|---|
-| `parse(yaml: string): any` | Parse a YAML document into a JS value. Mappings become plain Objects; sequences become Arrays; scalars become numbers / strings / booleans / null. Mirrors `js-yaml`'s `load`. |
-| `stringify(value: any): string` | Serialise a JS value back to YAML. |
-| `validateJson(yaml: string): boolean` | Validate that the document conforms to the YAML 1.2 JSON-compatible schema (only types JSON allows: null / bool / number / string / array / object). Returns `true` / `false`; structural JSON Schema 2020-12 validation is on the `noyavalidate` CLI roadmap. |
-| `getPath(yaml: string, path: string): any` | Indexed read without going through `parse`. Dotted paths (`"server.host"`); returns `null` if missing. |
-| `merge(base: string, override: string): string` | Deep-merge two YAML documents. Delegates to `noyalib::Value::merge`. |
+```js
+import init, { parse, getPath, WasmDocument } from "@sebastienrousseau/noyalib-wasm";
 
-### `WasmDocument` class — lossless CST
+await init();
 
-Construct with `new WasmDocument(yaml)`. Every method preserves
-comments and formatting around untouched spans byte-faithfully.
+const value = parse("host: api.example.com\nport: 8080\n");
+const port = getPath("port: 8080\n", "port");
 
-| Method | What it does |
-|---|---|
-| `toString(): string` | Re-emit. Byte-identical to the parsed source if no edits were made. |
-| `get(path: string): any` | Parsed value at a dotted path. Returns `null` if missing. |
-| `getSource(path: string): string \| null` | Raw source fragment at a dotted path (no re-quoting / canonicalisation). |
-| `set(path: string, fragment: string): void` | Surgically rewrite a value at a dotted path. The fragment is a YAML-shaped string (`"9090"`, `"[1,2,3]"`, …). |
-| `setValue(path: string, value: any): void` | Same as `set` but accepts a JS value instead of a YAML fragment. |
-| `spanAt(path: string): { start: number, end: number } \| null` | Byte range of the value at a dotted path. |
-| `commentsAt(path: string): { before: string[], inline: string \| null }` | Comments associated with the node at a path. |
-| `replaceSpan(start: number, end: number, replacement: string): void` | Primitive byte replacement. |
+const document = new WasmDocument("# service\nport: 8080\n");
+document.set("port", "9090");
+console.log(document.toString());
+```
 
-Every function is `async` only via `init()` — once the WASM
-blob is loaded, individual calls are synchronous.
+## The noyalib-wasm ecosystem
 
----
+| Component | Purpose |
+| :--- | :--- |
+| `noyalib-wasm` | JavaScript and WebAssembly API |
+| [`noyalib`](https://github.com/sebastienrousseau/noyalib) | Rust parser and lossless CST engine |
+| [`noya-cli`](https://github.com/sebastienrousseau/noya-cli) | Native command-line formatting and validation |
+| npm package | Provenance-attested browser and runtime distribution |
 
-## Bundle size
+## Capabilities at a glance
 
-| Build | Size (raw) | Size (gzip) |
-|---|---|---|
-| Default (`wasm-pack build --release --target bundler`) | ~338 KB | ~140 KB |
-| `--features wasm-opt` (post-build pass) | ~280 KB | ~115 KB |
+| Area | Capability | Status |
+| :--- | :--- | :--- |
+| Data model | `parse` and `stringify` | Stable |
+| Indexed access | `getPath` and `merge` | Stable |
+| Validation | JSON-compatible YAML check | Stable |
+| Lossless CST | `WasmDocument` reads and surgical edits | Stable |
+| Targets | bundler, web, nodejs, deno, and no-modules | Supported |
 
-Tree-shaking-friendly — the `Document` API and the plain
-`parse` / `stringify` API are independent modules; bundlers
-drop whichever your code does not import.
+## Ecosystem comparison
 
-For comparison: `js-yaml` 4.x lands around ~50 KB minified +
-~12 KB gzipped, but does not provide lossless-CST or schema
-validation.
+| Project | YAML 1.2 | Preserves untouched source | Browser-ready |
+| :--- | :---: | :---: | :---: |
+| **noyalib-wasm** | Yes | Yes, through `WasmDocument` | Yes |
+| `js-yaml` | Configurable | No | Yes |
+| Native `noyalib` | Yes | Yes | Requires a Rust host |
 
----
+See [`docs/COMPARISON.md`](docs/COMPARISON.md) for scope and caveats.
 
-## Targets
+## Benchmarks
 
-`wasm-pack build` supports every target wasm-bindgen does:
+The repository measures calls across the real JavaScript-to-WASM boundary and
+tracks release bundle size. Measurements are descriptive, not CI pass/fail
+thresholds.
 
-```sh
-wasm-pack build --target bundler    # webpack, rollup, esbuild
-wasm-pack build --target web        # native ES module via <script type="module">
-wasm-pack build --target nodejs     # commonjs Node import
-wasm-pack build --target deno       # Deno-native module
-wasm-pack build --target no-modules # plain global, no module loader
+```bash
+wasm-pack build --release --target nodejs
+node benches/bench.js
 ```
 
-Cloudflare Workers and edge runtimes generally consume the
-`bundler` target via their packaging step.
+See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) for the recorded method.
 
----
+## Features
 
-## Provenance
+- `parse`, `stringify`, `validateJson`, `getPath`, and `merge` free functions.
+- `WasmDocument` lossless reads, source spans, comments, and surgical edits.
+- JavaScript-native values through `serde-wasm-bindgen`.
+- npm provenance and release supply-chain metadata.
+- Browser, server, edge, and no-module build targets.
 
-Every release on npm carries an
-[npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements)
-linking the published bundle to the GitHub Actions run that
-produced it. Verify via:
+## Configuration
 
-```sh
-npm view @sebastienrousseau/noyalib-wasm provenance
-```
+| Command | Target |
+| :--- | :--- |
+| `wasm-pack build --target bundler` | Vite, Webpack, Rollup, and esbuild |
+| `wasm-pack build --target web` | Native browser ES modules |
+| `wasm-pack build --target nodejs` | Node.js CommonJS |
+| `wasm-pack build --target deno` | Deno-native module |
+| `wasm-pack build --target no-modules` | Global browser binding |
 
-GitHub Releases ship the crate archive and a CycloneDX SBOM,
-each with a sigstore bundle and checksums. A standalone signed
-`.wasm` artefact is not attached to releases; the npm package
-(with its provenance attestation, above) is the distribution
-channel for the compiled bundle. Verify a release artefact:
-
-```sh
-cosign verify-blob \
-  --certificate-identity-regexp 'https://github.com/sebastienrousseau/noyalib-wasm/' \
-  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
-  --bundle <artefact>.bundle \
-  <artefact>
-```
+The release profile leaves `wasm-opt` to the packaging pipeline so one build
+step owns the final artifact transformation.
 
-Full cookbook: [`pkg/VERIFY.md`](https://github.com/sebastienrousseau/noyalib/blob/main/pkg/VERIFY.md).
+## Examples
 
----
+- [`node-stringify.js`](examples/node-stringify.js): parse and stringify.
+- [`cst-edit.js`](examples/cst-edit.js): comment-preserving edit.
+- [`paths-and-spans.js`](examples/paths-and-spans.js): indexed access and spans.
+- [`browser/index.html`](examples/browser/index.html): browser editor.
 
-## Examples
+## When not to use noyalib-wasm
 
-Browser + Node demos under
-[`crates/noyalib-wasm/examples/`](examples/):
+- Use a smaller JavaScript-only parser when comments and source-preserving edits
+  do not matter.
+- Use native `noyalib` for streaming or memory-sensitive server workloads.
+- `validateJson` checks JSON round-trip compatibility; it is not a JSON Schema
+  validator. Use `noyavalidate` or the core schema feature for that purpose.
 
-| Path | Target | What it shows |
-|---|---|---|
-| [`node-stringify.js`](examples/node-stringify.js) | Node | `parse` + `stringify` round-trip. |
-| [`cst-edit.js`](examples/cst-edit.js) | Node | Lossless CST edit; comments + whitespace preserved. |
-| [`paths-and-spans.js`](examples/paths-and-spans.js) | Node | `getPath`, `merge`, `getSource`, `spanAt`, `replaceSpan`, `setValue`, `commentsAt`. |
-| [`json-compat.js`](examples/json-compat.js) | Node | `validateJson` — refuse YAML that JSON cannot represent (NaN / Infinity). |
-| [`browser/index.html`](examples/browser/index.html) | Browser | Live in-page YAML editor with a parsed-JSON pane. |
-| [`benches/bench.js`](benches/bench.js) | Node | Throughput measured across the real JS↔wasm boundary. |
+The [detailed README reference](docs/README-REFERENCE.md) retains API tables,
+bundle detail, target notes, and provenance commands.
 
-> The wasm build ships **no JSON Schema engine**. `validateJson` only
-> checks JSON round-trip safety. For JSON Schema 2020-12 use
-> `noyavalidate --schema`, or the `noyalib` crate's `validate-schema`
-> feature.
+## Development
 
 ```bash
-# Node:
-wasm-pack build --release --target nodejs crates/noyalib-wasm
-node crates/noyalib-wasm/examples/cst-edit.js
-node crates/noyalib-wasm/examples/json-compat.js
-
-# Browser:
-wasm-pack build --release --target web crates/noyalib-wasm
-cd crates/noyalib-wasm/examples/browser
-python3 -m http.server     # or any static-file server
+make
+make test
+make clippy
+make fmt
+wasm-pack test --node
 ```
 
----
-
-## When not to use noyalib-wasm
-
-- **You only ever consume YAML in Node and don't care about
-  comment-preserving edits or YAML 1.2 strictness.** `js-yaml`
-  is smaller (~50 KB minified) and the de-facto standard;
-  reach for it first.
-- **You need a streaming parser for multi-GB documents.** The
-  WASM bindings always read the full document into memory.
-  For TB-scale streaming workloads, drive the noyalib library
-  directly from a Rust process and pipe results out.
-
----
+CI checks native and WebAssembly builds, Node integration, rustdoc, dependency
+policy, the shared YAML suite, and package provenance. See
+[`DEVELOPMENT.md`](DEVELOPMENT.md).
 
-## Compatibility
+## Security
 
-**MSRV: Rust 1.86.0** stable — a deliberate policy choice: one floor across the whole lockstep set,
-with headroom for the dependency tree. No current dependency *requires*
-1.86 — this crate still compiles on 1.85. The whole lockstep set,
-including the core `noyalib` library, shares this floor. CI verifies the floor on every PR via
-the `Per-crate MSRV` workflow job. The bump policy lives in
-[`docs/POLICIES.md`](https://github.com/sebastienrousseau/noyalib/blob/main/docs/POLICIES.md#1-msrv-minimum-supported-rust-version).
-
-**Tier-1 WASM targets** (CI-verified each PR via
-`wasm-pack test --node`): `wasm32-unknown-unknown` produced
-under every `wasm-pack` mode — `bundler` (Webpack, Rollup,
-esbuild, Vite), `web` (native ES module), `nodejs` (CJS),
-`deno`, `no-modules`. Cloudflare Workers, Deno, and Bun
-consume the `bundler` target.
-
----
+Report vulnerabilities through [`SECURITY.md`](SECURITY.md). The Rust crate
+forbids `unsafe` code and treats YAML and JavaScript values as untrusted input.
+Published npm artifacts carry provenance linking them to the release workflow.
 
 ## Documentation
 
-The four entry points, identical across every repo in the family:
-
-- **[User Manual](https://sebastienrousseau.github.io/noyalib-wasm/manual/)** — this crate's rendered book: its guides, architecture, and release notes; the family manual for the core library is at [https://sebastienrousseau.github.io/noyalib/manual/](https://sebastienrousseau.github.io/noyalib/manual/)
-- **[API reference](https://docs.rs/noyalib-wasm)** — rustdoc on docs.rs
-- **[Developer docs](DEVELOPMENT.md)** — this repo's dev entry point, pointing at the family guide
-- **[Ecosystem map](https://github.com/sebastienrousseau/noyalib/blob/main/docs/ECOSYSTEM.md)** — the six crates, the lockstep model, the scorecard
-
-- **Engineering policies** (MSRV, SemVer, security, performance, concurrency, platform support, feature flags):
-  [`docs/POLICIES.md`](https://github.com/sebastienrousseau/noyalib/blob/main/docs/POLICIES.md)
-- **Security policy**:
-  [`SECURITY.md`](https://github.com/sebastienrousseau/noyalib/blob/main/SECURITY.md)
-- **JS API reference**:
-  [`docs/js-api.md`](docs/js-api.md)
-- **Bundling (Vite, Webpack, Next.js, Cloudflare Workers, Deno, Bun)**:
-  [`docs/bundling.md`](docs/bundling.md)
-- **npm package**:
-  <https://www.npmjs.com/package/@sebastienrousseau/noyalib-wasm>
-- **API reference (rustdoc)**: <https://docs.rs/noyalib-wasm>
-- **Workspace README**:
-  <https://github.com/sebastienrousseau/noyalib#readme>
-
----
+- [User Manual](https://sebastienrousseau.github.io/noyalib-wasm/manual/)
+- [Rust API reference](https://docs.rs/noyalib-wasm)
+- [JavaScript API](docs/js-api.md)
+- [Bundling guide](docs/bundling.md)
+- [Developer documentation](DEVELOPMENT.md)
+- [Engineering policies](docs/POLICIES.md)
+- [Compliance grade](docs/COMPLIANCE-GRADE.md)
+- [Detailed README reference](docs/README-REFERENCE.md)
 
-## Conformance
+## Stability guarantees
 
-Every push runs the official [yaml-test-suite](https://github.com/yaml/yaml-test-suite)
-through this crate's own JSON model, from the same vendored suite and the same
-core commit as the `noyalib` core: 382 of 382 single-document cases (the 24
-multi-document cases are outside `parse`, which is single-document). The core
-itself passes 406 of 406 with no skip list. A two-document configuration that
-uses most of YAML at once (`tests/fixtures/ultra-complex/`) is also parsed to
-exactly its expected JSON, natively and in Node. Details and the family table:
-[noyalib.com/conformance](https://noyalib.com/conformance/).
+- During `0.0.x`, the patch component is the breaking-change axis.
+- Exported JavaScript names, argument shapes, and return shapes are public API.
+- Untouched bytes remain stable when using the lossless `WasmDocument` surface.
+- The MSRV may rise only on the breaking axis with a changelog explanation.
 
 ## License
 
-Dual-licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
-or [MIT](https://opensource.org/licenses/MIT), at your option.
+Licensed under either [Apache License 2.0](LICENSE-APACHE) or
+[MIT](LICENSE-MIT), at your option.

package/noyalib_wasm.d.ts

@@ -18,10 +18,6 @@ export class WasmDocument {
      * conventions.
      */
     commentsAt(path: string): any;
-    /**
-     * Get the parsed value at a dotted path.
-     */
-    get(path: string): any;
     /**
      * Get the raw source fragment at a dotted path.
      *
@@ -29,6 +25,10 @@ export class WasmDocument {
      * conventions.
      */
     getSource(path: string): any;
+    /**
+     * Get the parsed value at a dotted path.
+     */
+    get(path: string): any;
     /**
      * Parse a YAML string into a lossless Document.
      */
@@ -40,10 +40,6 @@ export class WasmDocument {
      * per JS naming conventions.
      */
     replaceSpan(start: number, end: number, replacement: string): void;
-    /**
-     * Set a value at a dotted path using a YAML fragment string.
-     */
-    set(path: string, fragment: string): void;
     /**
      * Set a value at a dotted path using a JS object.
      *
@@ -51,6 +47,10 @@ export class WasmDocument {
      * conventions.
      */
     setValue(path: string, value: any): void;
+    /**
+     * Set a value at a dotted path using a YAML fragment string.
+     */
+    set(path: string, fragment: string): void;
     /**
      * Get the byte range `{ start, end }` for the value at a dotted path.
      *

package/noyalib_wasm_bg.js

@@ -33,20 +33,6 @@ export class WasmDocument {
         }
         return takeFromExternrefTable0(ret[0]);
     }
-    /**
-     * Get the parsed value at a dotted path.
-     * @param {string} path
-     * @returns {any}
-     */
-    get(path) {
-        const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.wasmdocument_get(this.__wbg_ptr, ptr0, len0);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
-        }
-        return takeFromExternrefTable0(ret[0]);
-    }
     /**
      * Get the raw source fragment at a dotted path.
      *
@@ -61,6 +47,20 @@ export class WasmDocument {
         const ret = wasm.wasmdocument_getSource(this.__wbg_ptr, ptr0, len0);
         return ret;
     }
+    /**
+     * Get the parsed value at a dotted path.
+     * @param {string} path
+     * @returns {any}
+     */
+    get(path) {
+        const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdocument_get(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * Parse a YAML string into a lossless Document.
      * @param {string} yaml
@@ -94,32 +94,32 @@ export class WasmDocument {
         }
     }
     /**
-     * Set a value at a dotted path using a YAML fragment string.
+     * Set a value at a dotted path using a JS object.
+     *
+     * Bound on the JS side as `setValue(path, value)` per JS naming
+     * conventions.
      * @param {string} path
-     * @param {string} fragment
+     * @param {any} value
      */
-    set(path, fragment) {
+    setValue(path, value) {
         const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ptr1 = passStringToWasm0(fragment, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-        const len1 = WASM_VECTOR_LEN;
-        const ret = wasm.wasmdocument_set(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        const ret = wasm.wasmdocument_setValue(this.__wbg_ptr, ptr0, len0, value);
         if (ret[1]) {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
     /**
-     * Set a value at a dotted path using a JS object.
-     *
-     * Bound on the JS side as `setValue(path, value)` per JS naming
-     * conventions.
+     * Set a value at a dotted path using a YAML fragment string.
      * @param {string} path
-     * @param {any} value
+     * @param {string} fragment
      */
-    setValue(path, value) {
+    set(path, fragment) {
         const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.wasmdocument_setValue(this.__wbg_ptr, ptr0, len0, value);
+        const ptr1 = passStringToWasm0(fragment, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdocument_set(this.__wbg_ptr, ptr0, len0, ptr1, len1);
         if (ret[1]) {
             throw takeFromExternrefTable0(ret[0]);
         }
@@ -285,7 +285,7 @@ export function validateJson(yaml) {
     }
     return ret[0] !== 0;
 }
-export function __wbg_Error_408e67f47ca7b58b(arg0, arg1) {
+export function __wbg_Error_67e7344beaa85059(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return ret;
 }
@@ -296,60 +296,60 @@ export function __wbg_String_8564e559799eccda(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_bigint_get_as_i64_c4ecf48528083721(arg0, arg1) {
+export function __wbg___wbindgen_bigint_get_as_i64_b482365c149396c8(arg0, arg1) {
     const v = arg1;
     const ret = typeof(v) === 'bigint' ? v : undefined;
     getDataViewMemory0().setBigInt64(arg0 + 8 * 1, isLikeNone(ret) ? BigInt(0) : ret, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
 }
-export function __wbg___wbindgen_boolean_get_c9c83ebd41b34df3(arg0) {
+export function __wbg___wbindgen_boolean_get_7a12af2b3f899c5a(arg0) {
     const v = arg0;
     const ret = typeof(v) === 'boolean' ? v : undefined;
     return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
 }
-export function __wbg___wbindgen_debug_string_a57024b9c6e4a48b(arg0, arg1) {
+export function __wbg___wbindgen_debug_string_0e68cf47c9cbd9b0(arg0, arg1) {
     const ret = debugString(arg1);
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len1 = WASM_VECTOR_LEN;
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_in_ac983077f137f2e6(arg0, arg1) {
+export function __wbg___wbindgen_in_50072d4d6e45c193(arg0, arg1) {
     const ret = arg0 in arg1;
     return ret;
 }
-export function __wbg___wbindgen_is_bigint_8ffbbef442139384(arg0) {
+export function __wbg___wbindgen_is_bigint_60fc0336cb14f5d7(arg0) {
     const ret = typeof(arg0) === 'bigint';
     return ret;
 }
-export function __wbg___wbindgen_is_function_5e4570eb24ffa122(arg0) {
+export function __wbg___wbindgen_is_function_fcda5e3902d732fe(arg0) {
     const ret = typeof(arg0) === 'function';
     return ret;
 }
-export function __wbg___wbindgen_is_object_a2790eb24c211ea0(arg0) {
+export function __wbg___wbindgen_is_object_edb6b15aa3afe12e(arg0) {
     const val = arg0;
     const ret = typeof(val) === 'object' && val !== null;
     return ret;
 }
-export function __wbg___wbindgen_is_string_e6f02f0ea5f20a32(arg0) {
+export function __wbg___wbindgen_is_string_c4f7cb494a2a21f1(arg0) {
     const ret = typeof(arg0) === 'string';
     return ret;
 }
-export function __wbg___wbindgen_jsval_eq_0a18949a61670320(arg0, arg1) {
+export function __wbg___wbindgen_jsval_eq_9fdcd3c0a860dd3b(arg0, arg1) {
     const ret = arg0 === arg1;
     return ret;
 }
-export function __wbg___wbindgen_jsval_loose_eq_acf2776254a8d832(arg0, arg1) {
+export function __wbg___wbindgen_jsval_loose_eq_3c30021c243b64cd(arg0, arg1) {
     const ret = arg0 == arg1;
     return ret;
 }
-export function __wbg___wbindgen_number_get_136b9679cab35cfb(arg0, arg1) {
+export function __wbg___wbindgen_number_get_1dc732b810cb937c(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'number' ? obj : undefined;
     getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
 }
-export function __wbg___wbindgen_string_get_d154f1e671052120(arg0, arg1) {
+export function __wbg___wbindgen_string_get_92ab86bb19cbc12f(arg0, arg1) {
     const obj = arg1;
     const ret = typeof(obj) === 'string' ? obj : undefined;
     var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -357,34 +357,34 @@ export function __wbg___wbindgen_string_get_d154f1e671052120(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_throw_bb96b2010945f0bc(arg0, arg1) {
+export function __wbg___wbindgen_throw_5d9e815e6fdf150f(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_call_1c5886ab9c57d1c7() { return handleError(function (arg0, arg1) {
+export function __wbg_call_269c5566fbede3eb() { return handleError(function (arg0, arg1) {
     const ret = arg0.call(arg1);
     return ret;
 }, arguments); }
-export function __wbg_done_669171204c3dcae2(arg0) {
+export function __wbg_done_cffed884d87aa22e(arg0) {
     const ret = arg0.done;
     return ret;
 }
-export function __wbg_entries_7774d489e1da5f4f(arg0) {
+export function __wbg_entries_972a87586902cf87(arg0) {
     const ret = Object.entries(arg0);
     return ret;
 }
-export function __wbg_get_c0c8f8d7da0c03dd(arg0, arg1) {
-    const ret = arg0[arg1 >>> 0];
-    return ret;
-}
-export function __wbg_get_d173c0308df22d37() { return handleError(function (arg0, arg1) {
+export function __wbg_get_6cf5a4d4d8ad3c5a() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
 }, arguments); }
-export function __wbg_get_unchecked_e20b893aeafc3fca(arg0, arg1) {
+export function __wbg_get_b1f0ab13c737f856(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
-export function __wbg_instanceof_ArrayBuffer_993d02d2d254cad1(arg0) {
+export function __wbg_get_unchecked_363572bdd397d473(arg0, arg1) {
+    const ret = arg0[arg1 >>> 0];
+    return ret;
+}
+export function __wbg_instanceof_ArrayBuffer_d4ff01f8247925ae(arg0) {
     let result;
     try {
         result = arg0 instanceof ArrayBuffer;
@@ -394,7 +394,7 @@ export function __wbg_instanceof_ArrayBuffer_993d02d2d254cad1(arg0) {
     const ret = result;
     return ret;
 }
-export function __wbg_instanceof_Map_9a4d6ead180ae3a9(arg0) {
+export function __wbg_instanceof_Map_1ff6a2b54c899f0d(arg0) {
     let result;
     try {
         result = arg0 instanceof Map;
@@ -404,7 +404,7 @@ export function __wbg_instanceof_Map_9a4d6ead180ae3a9(arg0) {
     const ret = result;
     return ret;
 }
-export function __wbg_instanceof_Uint8Array_f935dbb0aa7cdeed(arg0) {
+export function __wbg_instanceof_Uint8Array_598adc0fef426aa8(arg0) {
     let result;
     try {
         result = arg0 instanceof Uint8Array;
@@ -414,83 +414,83 @@ export function __wbg_instanceof_Uint8Array_f935dbb0aa7cdeed(arg0) {
     const ret = result;
     return ret;
 }
-export function __wbg_isArray_6339f732981044bf(arg0) {
+export function __wbg_isArray_5674713bb7b79043(arg0) {
     const ret = Array.isArray(arg0);
     return ret;
 }
-export function __wbg_isSafeInteger_f3d6cd19ccfe4512(arg0) {
+export function __wbg_isSafeInteger_8f51c743827d1ec5(arg0) {
     const ret = Number.isSafeInteger(arg0);
     return ret;
 }
-export function __wbg_iterator_5cebbb86e33c6dd6() {
+export function __wbg_iterator_22ddeb808cf55a6f() {
     const ret = Symbol.iterator;
     return ret;
 }
-export function __wbg_length_36bd29c6848c2144(arg0) {
+export function __wbg_length_31bdaf014f5fbde2(arg0) {
     const ret = arg0.length;
     return ret;
 }
-export function __wbg_length_ecfa2c63d3d0d82c(arg0) {
+export function __wbg_length_4e1adc0d42e23620(arg0) {
     const ret = arg0.length;
     return ret;
 }
-export function __wbg_new_116be93542d39019() {
-    const ret = new Array();
-    return ret;
-}
-export function __wbg_new_77cc4f4f472aeb81(arg0) {
+export function __wbg_new_1da3429bc3c4541c(arg0) {
     const ret = new Uint8Array(arg0);
     return ret;
 }
-export function __wbg_new_cdf041679ded4c5f() {
+export function __wbg_new_8d36e20aa758e411() {
     const ret = new Map();
     return ret;
 }
-export function __wbg_new_ebe3e0f6837f0879() {
+export function __wbg_new_bebc3f4757acf305() {
     const ret = new Object();
     return ret;
 }
-export function __wbg_next_42cf16ee0dafc9e2() { return handleError(function (arg0) {
-    const ret = arg0.next();
+export function __wbg_new_ffa92086ea89f79c() {
+    const ret = new Array();
     return ret;
-}, arguments); }
-export function __wbg_next_8f26b64fa5e9f64b(arg0) {
+}
+export function __wbg_next_95053e306b1c3aed(arg0) {
     const ret = arg0.next;
     return ret;
 }
-export function __wbg_prototypesetcall_de8e0d9553586985(arg0, arg1, arg2) {
+export function __wbg_next_f31ecb8646d2c605() { return handleError(function (arg0) {
+    const ret = arg0.next();
+    return ret;
+}, arguments); }
+export function __wbg_prototypesetcall_ae9f5e7459250748(arg0, arg1, arg2) {
     Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
 }
-export function __wbg_set_014226dfeca53178(arg0, arg1, arg2) {
-    const ret = arg0.set(arg1, arg2);
-    return ret;
+export function __wbg_set_13d25b81ab403f5e(arg0, arg1, arg2) {
+    arg0[arg1 >>> 0] = arg2;
 }
 export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
     arg0[arg1] = arg2;
 }
-export function __wbg_set_a80955eb93b145c6(arg0, arg1, arg2) {
-    arg0[arg1 >>> 0] = arg2;
+export function __wbg_set_bf6dde4923b9b059(arg0, arg1, arg2) {
+    const ret = arg0.set(arg1, arg2);
+    return ret;
 }
-export function __wbg_value_1e2369fab29b420e(arg0) {
+export function __wbg_value_c227f843d21da141(arg0) {
     const ret = arg0.value;
     return ret;
 }
-export function __wbindgen_cast_0000000000000001(arg0) {
+export function __wbindgen_generic_0000000000000001(arg0) {
     // Cast intrinsic for `F64 -> Externref`.
     const ret = arg0;
     return ret;
 }
-export function __wbindgen_cast_0000000000000002(arg0) {
+export function __wbindgen_generic_0000000000000002(arg0) {
     // Cast intrinsic for `I64 -> Externref`.
     const ret = arg0;
     return ret;
 }
-export function __wbindgen_cast_0000000000000003(arg0, arg1) {
+export function __wbindgen_generic_0000000000000003(arg0, arg1) {
     // Cast intrinsic for `Ref(String) -> Externref`.
     const ret = getStringFromWasm0(arg0, arg1);
     return ret;
 }
-export function __wbindgen_cast_0000000000000004(arg0) {
+export function __wbindgen_generic_0000000000000004(arg0) {
     // Cast intrinsic for `U64 -> Externref`.
     const ret = BigInt.asUintN(64, arg0);
     return ret;

package/package.json

@@ -5,7 +5,7 @@
     "Sebastien Rousseau <sebastian.rousseau@gmail.com>"
   ],
   "description": "WebAssembly (wasm-bindgen) bindings for the noyalib YAML library — browser-ready parse / serialise / lossless edit",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",