@osdlc/yaml-splice 0.0.1-stage → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- 2f3fc7c: A malformed edit is now refused as the new `EditErrorCode` `InvalidEdit`, and an error that is not a refusal is passed through instead of being reported as `InvalidResult`.
+  
+  - `InvalidEdit`: a `Set` with no `value` (or `value: undefined`), an unknown tag, or a `Set` value nested more than 124 levels deep (the JSON decoder's recursion limit). These were reported as `InvalidResult`, which says the edit would damage the document, when the edit itself was bad.
+  - **Breaking:** `editYaml` rethrows any error without a known code unchanged. Before, it wrapped it in `EditError('InvalidResult', …)`. A Rust panic in the WebAssembly module (`RuntimeError: unreachable`) now reaches the caller as a `RuntimeError`, so a crashed module no longer looks like a normal refusal. Code that catches only `EditError` now sees these errors propagate.
+
+## 0.1.4
+
+### Patch Changes
+
+- fa792c7: The first release on npm. Versions 0.1.0 to 0.1.3 were used only during development and were never published. It edits top-level fields of a YAML mapping in place, on bytes: set, remove or rename a field, and every byte outside the edited span stays as it was, including comments, key order, quoting, a BOM and line endings. It runs the `yaml-splice` Rust crate through WebAssembly, so it has no runtime dependencies and no native code.
+  
+  - `editYaml(source, edits)` applies a batch of `FieldEdit`s (`Set`, `Remove`, `Rename`) in order and returns an `EditOutcome` (`bytes` and `changed`). The batch is atomic: a refused edit throws an `EditError` with an `EditErrorCode` and, where known, an `EditSpan`, and nothing is returned.
+  - Keys match case-insensitively.
+  
+  Fixed since the last development version:
+  
+  - `Set` on a quoted value with a comment after it (`title: 'Draft'  # note`) no longer deletes the comment.
+  - `Set` on a block scalar (`|` or `>`) no longer joins the next key onto the new value's line, and `Remove` on one no longer deletes the next line too.
+  - A comment indented less than a block scalar is kept: `Set` no longer joins it onto the new value's line, and `Remove` no longer deletes it.
+  - An empty block scalar (`a: |`, also with a tag or an anchor) can now be set and removed. Both were refused.
+  - When a new value is written as a block, the old value's trailing comment moves to the block's header line instead of becoming part of the value.
+  - A keep-chomped (`|+`) value keeps its trailing line breaks: setting `"kept\n\n"` no longer writes `"kept\n"`.
+  - `editYaml` checks each edit against what it asked for. It throws `EditError('InvalidResult', …)` when an edit would change the value or order of a key it does not address, or when the addressed key would not read back as set, removed or renamed. Before, it returned that document. A `.nan` value in another key no longer counts as a change.
+  
+  All seven exports are stable. Node.js 22 or later and Bun; no browser or bundler build yet. Shipped as compiled JavaScript with type declarations. Tested on Linux and macOS. Licensed `MIT OR Apache-2.0`.
+
 ## History before the first public release
 
 These versions were developed in a private repository before the package moved here, and

package/README.md

@@ -40,6 +40,8 @@ ESM only. Node.js 22 or later, or Bun.
 ## Quick start
 
 ```ts
+import assert from 'node:assert/strict'
+
 import { editYaml } from '@osdlc/yaml-splice'
 
 const source = new TextEncoder().encode("title: 'Draft'  # shown in the header\nstatus: draft\n")
@@ -49,8 +51,8 @@ const out = editYaml(source, [
   { Rename: { from: 'title', to: 'name' } },
 ])
 
-new TextDecoder().decode(out.bytes) // "name: 'Draft'  # shown in the header\nstatus: done\n"
-out.changed // true
+assert.equal(new TextDecoder().decode(out.bytes), "name: 'Draft'  # shown in the header\nstatus: done\n")
+assert.equal(out.changed, true)
 ```
 
 More in `examples/`: setting values, removing and renaming in one batch, and
@@ -70,10 +72,13 @@ handling refusals.
 - `EditError` is the refusal. Its `code` (an `EditErrorCode`) says why, and
   `name` is the same code. `span`, an `EditSpan`, is the byte range
   `[start, end)` in the input that the refusal is about, when there is one.
-- `EditErrorCode` is one of `InvalidUtf8`, `MalformedYaml`,
+- `EditErrorCode` is one of `InvalidEdit`, `InvalidUtf8`, `MalformedYaml`,
   `UnsupportedDocument`, `RootNotMapping`, `AmbiguousKey`, `MissingKey`,
   `KeyConflict`, `UnrenderableValue` and `InvalidResult`. A minor release may
   add a code, so give a `switch` over it a `default` branch.
+- Any other error `editYaml` throws is not a refusal and is passed through
+  as is. A `RuntimeError` from the WebAssembly module means it crashed; do
+  not keep calling it as if the edit had been refused.
 - `EditSpan` is `{ start, end }`, in bytes. `RootNotMapping`, `AmbiguousKey`
   and `KeyConflict` always carry one; `MalformedYaml` and
   `UnsupportedDocument` carry one when the parser knows the location.
@@ -94,6 +99,11 @@ Each export has TSDoc in the source. Your editor shows it.
   byte zero.
 - `NaN` and `±Infinity` anywhere in a `Set` value are refused as
   `UnrenderableValue` before any byte is written.
+- An edit the editor cannot read is refused as `InvalidEdit`: a `Set` with
+  no `value` (or `value: undefined`), an unknown tag, or a `Set` value
+  nested more than 124 levels deep. The last is the JSON decoder's recursion
+  limit (serde_json's 128 levels, less the levels the edit list itself
+  takes).
 - Each edit is checked against what it asked for: the addressed key must read
   back as set, removed or renamed, and no other key may change value or
   order. If not, the batch is refused as `InvalidResult` instead of returning
@@ -138,6 +148,8 @@ The experimental exports:
 | An edit that changes no value returns the input bytes | `tests/index.test.ts`, "a semantic no-op …" |
 | Non-finite numbers are refused before any write | `tests/index.test.ts`, "a non-finite number in a Set value" |
 | `EditErrorCode` lists every refusal the crate has | `tests/index.test.ts`, "EditErrorCode" |
+| A malformed or too-deeply nested edit is `InvalidEdit` | `tests/index.test.ts`, "an edit the editor cannot read" |
+| An error that is not a refusal is passed through | `tests/index.test.ts`, "an error that is not a refusal" |
 
 ## Runtimes and platforms
 

package/dist/index.d.ts

@@ -35,11 +35,12 @@ export interface EditOutcome {
     readonly changed: boolean;
 }
 /**
- * Why an edit was refused: one code per variant of the crate's `EditError`.
- * A minor release may add a code, so a `switch` over it needs a `default`
- * branch.
+ * Why an edit was refused: one code per variant of the crate's `EditError`,
+ * plus `InvalidEdit` for an edit the editor could not read: a missing `value`,
+ * an unknown tag, or a `Set` value nested more than 124 levels deep. A minor
+ * release may add a code, so a `switch` over it needs a `default` branch.
  */
-export type EditErrorCode = 'InvalidUtf8' | 'MalformedYaml' | 'UnsupportedDocument' | 'RootNotMapping' | 'AmbiguousKey' | 'MissingKey' | 'KeyConflict' | 'UnrenderableValue' | 'InvalidResult';
+export type EditErrorCode = 'InvalidEdit' | 'InvalidUtf8' | 'MalformedYaml' | 'UnsupportedDocument' | 'RootNotMapping' | 'AmbiguousKey' | 'MissingKey' | 'KeyConflict' | 'UnrenderableValue' | 'InvalidResult';
 /**
  * A byte span `[start, end)` into the input. `RootNotMapping`, `AmbiguousKey`
  * and `KeyConflict` always carry one; `MalformedYaml` and `UnsupportedDocument`
@@ -50,7 +51,7 @@ export interface EditSpan {
     readonly end: number;
 }
 /**
- * A typed, structured refusal from the Rust core. `name`/`code` is the variant
+ * A typed refusal of an edit batch. `name`/`code` is the variant
  * and `span` carries the byte range where one is known. Thrown by
  * {@link editYaml} in place of the raw bindgen error.
  */

package/dist/index.js

@@ -14,7 +14,7 @@
  */
 import { editYaml as editYamlWasm, } from './wasm/yaml_splice_wasm.js';
 /**
- * A typed, structured refusal from the Rust core. `name`/`code` is the variant
+ * A typed refusal of an edit batch. `name`/`code` is the variant
  * and `span` carries the byte range where one is known. Thrown by
  * {@link editYaml} in place of the raw bindgen error.
  */
@@ -34,17 +34,20 @@ export class EditError extends Error {
             this.span = span;
     }
 }
-const ERROR_CODES = new Set([
-    'InvalidUtf8',
-    'MalformedYaml',
-    'UnsupportedDocument',
-    'RootNotMapping',
-    'AmbiguousKey',
-    'MissingKey',
-    'KeyConflict',
-    'UnrenderableValue',
-    'InvalidResult',
-]);
+// Every code, so the type check fails when a code is missing here.
+const ERROR_CODE_TABLE = {
+    InvalidEdit: true,
+    InvalidUtf8: true,
+    MalformedYaml: true,
+    UnsupportedDocument: true,
+    RootNotMapping: true,
+    AmbiguousKey: true,
+    MissingKey: true,
+    KeyConflict: true,
+    UnrenderableValue: true,
+    InvalidResult: true,
+};
+const ERROR_CODES = new Set(Object.keys(ERROR_CODE_TABLE));
 /**
  * Edit `source` (raw UTF-8 YAML bytes) with an ordered batch of `edits`,
  * returning new bytes plus a `changed` flag, or throwing a typed
@@ -67,7 +70,7 @@ export function editYaml(source, edits) {
         result = editYamlWasm(source, editsJson);
     }
     catch (raw) {
-        throw toEditError(raw);
+        throw isRefusal(raw) ? toEditError(raw) : raw;
     }
     // Read both fields into a plain object, THEN free the handle. The glue's
     // `bytes` getter returns an owned copy (`.slice()`), so it survives `free()`.
@@ -106,16 +109,25 @@ function assertFiniteValue(value, key) {
             assertFiniteValue(item, key);
     }
 }
-/** Map a thrown bindgen `Error` (`.name` = variant, `.span`) to `EditError`. */
+/**
+ * The `.name` the wasm gives a crate `EditError` variant it has no name for
+ * (the crate's enum is `#[non_exhaustive]`). Still a refusal: reported as
+ * `InvalidResult`, as before 0.2.0.
+ */
+const UNNAMED_REFUSAL = 'EditError';
+/**
+ * Whether a thrown value is one of the wasm side's refusals: an `Error` whose
+ * `name` is a known code, or {@link UNNAMED_REFUSAL}. Anything else, such as a
+ * Rust panic (`RuntimeError: unreachable`), is rethrown as is: it means the
+ * module is broken, not that the edit was refused.
+ */
+function isRefusal(raw) {
+    return raw instanceof Error && (ERROR_CODES.has(raw.name) || raw.name === UNNAMED_REFUSAL);
+}
+/** Map a bindgen refusal (`.name` = code, `.span`) to `EditError`. */
 function toEditError(raw) {
-    if (raw instanceof Error) {
-        const code = ERROR_CODES.has(raw.name)
-            ? raw.name
-            : 'InvalidResult';
-        const span = readSpan(raw.span);
-        return new EditError(code, raw.message, span);
-    }
-    return new EditError('InvalidResult', String(raw));
+    const code = ERROR_CODES.has(raw.name) ? raw.name : 'InvalidResult';
+    return new EditError(code, raw.message, readSpan(raw.span));
 }
 function readSpan(span) {
     if (span !== null &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/yaml-splice",
-  "version": "0.0.1-stage",
+  "version": "0.2.0",
   "description": "Edit top-level fields of a YAML mapping in place, on bytes: set, remove or rename a field, and every byte outside the edited span stays as it was, including comments, key order, quoting, a BOM and line endings. The yaml-splice Rust crate, built to WebAssembly. Node.js and Bun.",
   "license": "MIT OR Apache-2.0",
   "author": "sksizer",