@quillmark/wasm 0.80.0 → 0.81.0-rc.2

package/README.md

@@ -67,6 +67,86 @@ byte-equal to the original source — YAML quoting, key ordering, and
 whitespace are normalised. Use `equals` (not string comparison) to test
 semantic equality.
 
+### `doc.toJson()`
+Serialize the document to a versioned storage DTO — a JSON **string**
+carrying a `schema` version. Use this (not `toMarkdown`) to persist a
+document across a process restart or crate upgrade: the wire format is
+frozen per `schema` version, whereas Markdown syntax evolves. Parse-time
+`warnings` are not part of the DTO.
+
+The string is produced inside the module by `serde_json`; the JS `JSON`
+global is not involved. It is standard JSON text, so callers may
+`JSON.parse` it to inspect it — but it is intended as an opaque blob you
+persist and hand back.
+
+`toJson()` is **deterministic**: a `Document` that is `equals` to another
+serializes to a byte-identical string — across repeated calls, and across
+any crate upgrade that keeps the same `schema` version (every release does until
+the `Document` model changes; see [Storage compatibility](#storage-compatibility-across-versions)).
+Field order is fixed and object key order is preserved, so content hashes
+and string-equality dirty-checks over the output are stable.
+
+### `Document.fromJson(json)`
+Reconstruct a `Document` from a storage DTO string produced by `toJson`.
+Round-trips losslessly:
+
+```ts
+const stored = doc.toJson();        // persist this string
+const restored = Document.fromJson(stored);
+restored.equals(doc);               // true
+```
+
+Throws a JS `Error` on malformed JSON, an unknown `schema` version, or a
+malformed payload. The restored document has no parse-time `warnings`.
+
+### `Document.tryFromJson(json)`
+Like `fromJson`, but returns `undefined` instead of throwing when `json` is
+not a valid storage DTO. Use it to branch on format without a heuristic or
+`try`/`catch` as control flow:
+
+```ts
+// "JSON canonical, Markdown fallback" — no exceptions, no string sniffing
+const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+```
+
+`undefined` means only "not a storage DTO"; `fromMarkdown` still throws on
+genuinely malformed Markdown.
+
+### Storage compatibility across versions
+
+The `schema` value (`quillmark/document@0.81.0`) is the **model version**,
+not the running crate version. It is a hand-set constant, bumped only when
+the `Document` model itself changes — so every `0.81.x` patch release reads
+and writes that same value.
+
+- **Upgrading is safe.** A newer build always reads documents written by an
+  older one. Each schema version's wire format is frozen and never changes;
+  when the model does change, the new build ships a migration that converts
+  old payloads on `fromJson`. A document you commit as your canonical
+  on-disk format keeps loading across crate upgrades — there is no need to
+  pin old wasm to read old data.
+- **Downgrading is not.** `fromJson` rejects an *unknown* (i.e. newer)
+  `schema` version rather than guessing at a format it predates. Don't feed
+  documents written by a newer build back into an older one.
+
+To detect a version mismatch before parsing, use the static accessors:
+
+```ts
+const v = Document.schemaVersionOf(blob); // undefined | string
+if (v && v !== Document.currentSchemaVersion()) {
+  // payload is from a build with a different model version
+}
+```
+
+`schemaVersionOf` does not validate the payload — it only reads the
+`schema` field, returning `undefined` for non-JSON, non-objects, or
+payloads that don't carry one. Use it to distinguish "wrong version" from
+"corrupt" when `fromJson` throws.
+
+In short: persist the `toJson` string, upgrade freely, never downgrade. The
+full design — including how migrations are added — is in
+`prose/canon/DOCUMENT_STORAGE.md`.
+
 ### `doc.equals(other)`
 Structural equality between two `Document` handles. Compares `main` and
 `cards` by value; parse-time `warnings` are intentionally excluded.
@@ -193,8 +273,11 @@ compilation failures. The same shape applies to every throw site:
 The wasm bindings are built with `--weak-refs`, so dropped `Document`,
 `Quill`, and `RenderSession` handles are reclaimed by `FinalizationRegistry`
 without manual `.free()` discipline. `.free()` is still emitted as an eager
-teardown hook for callers that want deterministic release. Requires
-Node 14.6+ / current evergreen browsers (all supported targets).
+teardown hook for callers that want deterministic release.
+
+The package requires Node 24+ (`engines: { node: ">=24" }`) and current
+evergreen browsers; `--weak-refs` itself only needs Node 14.6+, but the
+published package floor is 24.
 
 For environments where `using` (the [explicit resource management][erm]
 proposal) hasn't landed, use an explicit `try` / `finally`:

package/bundler/wasm.d.ts

@@ -269,6 +269,14 @@ export class Document {
      * history of either handle.
      */
     clone(): Document;
+    /**
+     * Schema version this build writes via [`toJson`](Document::to_json).
+     *
+     * Compare a payload's [`schemaVersionOf`](Document::schema_version_of)
+     * against this to detect mismatches before calling
+     * [`fromJson`](Document::from_json).
+     */
+    static currentSchemaVersion(): string;
     /**
      * Structural equality against another `Document`.
      *
@@ -280,6 +288,22 @@ export class Document {
      * `Document` and compare instead of re-parsing on every keystroke.
      */
     equals(other: Document): boolean;
+    /**
+     * Reconstruct a `Document` from its versioned storage DTO string.
+     *
+     * `json` must be a string produced by [`toJson`](Document::to_json) —
+     * the versioned storage DTO. Parsing and schema dispatch happen inside
+     * the module via `serde_json`; the JS `JSON` global is not involved.
+     * Unknown `schema` tags are rejected.
+     *
+     * The reconstructed document carries no parse-time warnings — the DTO
+     * describes content, not source text — so `.warnings` is always empty.
+     *
+     * Throws a JS `Error` if `json` is not a valid storage DTO (malformed
+     * JSON, unknown `schema`, missing fields, or an unparseable quill
+     * reference).
+     */
+    static fromJson(json: string): Document;
     /**
      * Parse markdown into a typed Document.
      *
@@ -348,6 +372,27 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     replaceBody(body: string): void;
+    /**
+     * Read the schema version from a raw storage DTO string without
+     * performing a full parse, or `undefined`.
+     *
+     * Returns the `schema` field as-is — including unknown future versions
+     * that `fromJson` would reject. Use this to distinguish "this build is
+     * too old for the payload" from "the payload is corrupt" when
+     * [`fromJson`](Document::from_json) throws:
+     *
+     * ```js
+     * const v = Document.schemaVersionOf(blob);
+     * if (v === undefined) {
+     *   // not a stored DTO at all — try fromMarkdown
+     * } else if (v !== Document.currentSchemaVersion()) {
+     *   // newer (or older unmigrated) schema — prompt the user to upgrade
+     * } else {
+     *   doc = Document.fromJson(blob);
+     * }
+     * ```
+     */
+    static schemaVersionOf(json: string): string | undefined;
     /**
      * Replace the tag of the composable card at `index`.
      *
@@ -393,6 +438,25 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     setQuillRef(ref_str: string): void;
+    /**
+     * Serialize this document to a versioned storage DTO string.
+     *
+     * Returns the document as a JSON string carrying a `schema` version
+     * field. The string is produced inside the module via `serde_json` and
+     * round-trips losslessly back to an equal `Document` via
+     * [`fromJson`](Document::from_json) — the JS `JSON` global is not
+     * involved in either direction.
+     *
+     * Use this — not [`toMarkdown`](Document::to_markdown) — to persist a
+     * document across a process restart or crate upgrade; the wire format
+     * is frozen per `schema` version, whereas Markdown syntax evolves.
+     * Parse-time `warnings` are not part of the DTO.
+     *
+     * The result is standard JSON text, so callers that want to inspect it
+     * may `JSON.parse` it — but treating it as an opaque blob is the
+     * intended use.
+     */
+    toJson(): string;
     /**
      * Emit canonical Quillmark Markdown.
      *
@@ -401,6 +465,21 @@ export class Document {
      * produces a `Document` equal to `self` by value and by type.
      */
     toMarkdown(): string;
+    /**
+     * Reconstruct a `Document` from a storage DTO string, or `undefined`.
+     *
+     * Like [`fromJson`](Document::from_json), but returns `undefined`
+     * instead of throwing when `json` is not a valid storage DTO. Use this
+     * to detect format and fall back without exceptions as control flow:
+     *
+     * ```js
+     * const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+     * ```
+     *
+     * `undefined` only ever means "not a storage DTO" — `fromMarkdown`
+     * still throws on genuinely malformed markdown.
+     */
+    static tryFromJson(json: string): Document | undefined;
     /**
      * Replace the body of the card at `index`.
      *

package/bundler/wasm_bg.js

@@ -61,6 +61,30 @@ export class Document {
         const ret = wasm.document_clone(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * Schema version this build writes via [`toJson`](Document::to_json).
+     *
+     * Compare a payload's [`schemaVersionOf`](Document::schema_version_of)
+     * against this to detect mismatches before calling
+     * [`fromJson`](Document::from_json).
+     * @returns {string}
+     */
+    static currentSchemaVersion() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_currentSchemaVersion(retptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * Structural equality against another `Document`.
      *
@@ -78,6 +102,40 @@ export class Document {
         const ret = wasm.document_equals(this.__wbg_ptr, other.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+     * Reconstruct a `Document` from its versioned storage DTO string.
+     *
+     * `json` must be a string produced by [`toJson`](Document::to_json) —
+     * the versioned storage DTO. Parsing and schema dispatch happen inside
+     * the module via `serde_json`; the JS `JSON` global is not involved.
+     * Unknown `schema` tags are rejected.
+     *
+     * The reconstructed document carries no parse-time warnings — the DTO
+     * describes content, not source text — so `.warnings` is always empty.
+     *
+     * Throws a JS `Error` if `json` is not a valid storage DTO (malformed
+     * JSON, unknown `schema`, missing fields, or an unparseable quill
+     * reference).
+     * @param {string} json
+     * @returns {Document}
+     */
+    static fromJson(json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_fromJson(retptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return Document.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Parse markdown into a typed Document.
      *
@@ -286,6 +344,46 @@ export class Document {
         const len0 = WASM_VECTOR_LEN;
         wasm.document_replaceBody(this.__wbg_ptr, ptr0, len0);
     }
+    /**
+     * Read the schema version from a raw storage DTO string without
+     * performing a full parse, or `undefined`.
+     *
+     * Returns the `schema` field as-is — including unknown future versions
+     * that `fromJson` would reject. Use this to distinguish "this build is
+     * too old for the payload" from "the payload is corrupt" when
+     * [`fromJson`](Document::from_json) throws:
+     *
+     * ```js
+     * const v = Document.schemaVersionOf(blob);
+     * if (v === undefined) {
+     *   // not a stored DTO at all — try fromMarkdown
+     * } else if (v !== Document.currentSchemaVersion()) {
+     *   // newer (or older unmigrated) schema — prompt the user to upgrade
+     * } else {
+     *   doc = Document.fromJson(blob);
+     * }
+     * ```
+     * @param {string} json
+     * @returns {string | undefined}
+     */
+    static schemaVersionOf(json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_schemaVersionOf(retptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            let v2;
+            if (r0 !== 0) {
+                v2 = getStringFromWasm0(r0, r1).slice();
+                wasm.__wbindgen_export4(r0, r1 * 1, 1);
+            }
+            return v2;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Replace the tag of the composable card at `index`.
      *
@@ -394,6 +492,49 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Serialize this document to a versioned storage DTO string.
+     *
+     * Returns the document as a JSON string carrying a `schema` version
+     * field. The string is produced inside the module via `serde_json` and
+     * round-trips losslessly back to an equal `Document` via
+     * [`fromJson`](Document::from_json) — the JS `JSON` global is not
+     * involved in either direction.
+     *
+     * Use this — not [`toMarkdown`](Document::to_markdown) — to persist a
+     * document across a process restart or crate upgrade; the wire format
+     * is frozen per `schema` version, whereas Markdown syntax evolves.
+     * Parse-time `warnings` are not part of the DTO.
+     *
+     * The result is standard JSON text, so callers that want to inspect it
+     * may `JSON.parse` it — but treating it as an opaque blob is the
+     * intended use.
+     * @returns {string}
+     */
+    toJson() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_toJson(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Emit canonical Quillmark Markdown.
      *
@@ -418,6 +559,28 @@ export class Document {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Reconstruct a `Document` from a storage DTO string, or `undefined`.
+     *
+     * Like [`fromJson`](Document::from_json), but returns `undefined`
+     * instead of throwing when `json` is not a valid storage DTO. Use this
+     * to detect format and fall back without exceptions as control flow:
+     *
+     * ```js
+     * const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+     * ```
+     *
+     * `undefined` only ever means "not a storage DTO" — `fromMarkdown`
+     * still throws on genuinely malformed markdown.
+     * @param {string} json
+     * @returns {Document | undefined}
+     */
+    static tryFromJson(json) {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_tryFromJson(ptr0, len0);
+        return ret === 0 ? undefined : Document.__wrap(ret);
+    }
     /**
      * Replace the body of the card at `index`.
      *

package/bundler/wasm_bg.wasm.d.ts

@@ -8,7 +8,9 @@ export const __wbg_rendersession_free: (a: number, b: number) => void;
 export const document_cardCount: (a: number) => number;
 export const document_cards: (a: number) => number;
 export const document_clone: (a: number) => number;
+export const document_currentSchemaVersion: (a: number) => void;
 export const document_equals: (a: number, b: number) => number;
+export const document_fromJson: (a: number, b: number, c: number) => void;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
 export const document_insertCard: (a: number, b: number, c: number, d: number) => void;
 export const document_main: (a: number) => number;
@@ -19,11 +21,14 @@ export const document_removeCard: (a: number, b: number) => number;
 export const document_removeCardField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_removeField: (a: number, b: number, c: number, d: number) => void;
 export const document_replaceBody: (a: number, b: number, c: number) => void;
+export const document_schemaVersionOf: (a: number, b: number, c: number) => void;
 export const document_setCardTag: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setFill: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setQuillRef: (a: number, b: number, c: number, d: number) => void;
+export const document_toJson: (a: number, b: number) => void;
 export const document_toMarkdown: (a: number, b: number) => void;
+export const document_tryFromJson: (a: number, b: number) => number;
 export const document_updateCardBody: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_updateCardField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_warnings: (a: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.80.0",
+  "version": "0.81.0-rc.2",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",