@quillmark/wasm 0.79.0 → 0.81.0-rc.1

package/README.md

@@ -67,6 +67,31 @@ 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 tag. 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.
+
+### `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` tag, or a
+malformed payload. The restored document has no parse-time `warnings`.
+
 ### `doc.equals(other)`
 Structural equality between two `Document` handles. Compares `main` and
 `cards` by value; parse-time `warnings` are intentionally excluded.

package/bundler/wasm.d.ts

@@ -93,14 +93,14 @@ export interface QuillFieldUi {
     multiline?: boolean;
 }
 
-/** UI layout hints for a card (main or named card type). */
+/** UI layout hints for a card (main or named card kind). */
 export interface QuillCardUi {
     title?: string;
 }
 
-/** Body namespace for a card (main or named card type). */
+/** Body namespace for a card (main or named card kind). */
 export interface QuillCardBody {
-    /** When false, consumers must not accept or store body content for this card type. Defaults to true. */
+    /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
     /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
     example?: string;
@@ -119,7 +119,7 @@ export interface QuillFieldSchema {
     items?: QuillFieldSchema;
 }
 
-/** Schema entry for the main card or a named card type. */
+/** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
     description?: string;
     fields: Record<string, QuillFieldSchema>;
@@ -130,13 +130,13 @@ export interface QuillCardSchema {
 /**
  * Document schema returned by `Quill.schema`. Includes optional `ui` keys.
  *
- * `main.fields.QUILL` and `card_types[name].fields.CARD` are required
+ * `main.fields.QUILL` and `card_kinds[name].fields.CARD` are required
  * sentinels with `const` values telling consumers what to write.
  */
 export interface QuillSchema {
     main: QuillCardSchema;
-    /** Present only when the quill declares at least one named card type. */
-    card_types?: Record<string, QuillCardSchema>;
+    /** Present only when the quill declares at least one named card kind. */
+    card_kinds?: Record<string, QuillCardSchema>;
 }
 
 /**
@@ -280,6 +280,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.
      *
@@ -393,6 +409,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
+     * tag. 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.
      *
@@ -459,15 +494,15 @@ export class Quill {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * A blank form for a card of the given type — no document values supplied.
+     * A blank form for a card of the given kind — no document values supplied.
      *
-     * Returns `null` if `cardType` is not declared in this quill's schema.
+     * Returns `null` if `cardKind` is not declared in this quill's schema.
      * Otherwise returns a plain JS object shaped like a single entry in
      * [`Form::cards`].
      *
      * [`Form::cards`]: quillmark::form::Form::cards
      */
-    blankCard(card_type: string): FormCard | null;
+    blankCard(card_kind: string): FormCard | null;
     /**
      * A blank form for the main card — no document values supplied.
      *

package/bundler/wasm_bg.js

@@ -78,6 +78,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.
      *
@@ -394,6 +428,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
+     * tag. 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.
      *
@@ -523,20 +600,20 @@ export class Quill {
         }
     }
     /**
-     * A blank form for a card of the given type — no document values supplied.
+     * A blank form for a card of the given kind — no document values supplied.
      *
-     * Returns `null` if `cardType` is not declared in this quill's schema.
+     * Returns `null` if `cardKind` is not declared in this quill's schema.
      * Otherwise returns a plain JS object shaped like a single entry in
      * [`Form::cards`].
      *
      * [`Form::cards`]: quillmark::form::Form::cards
-     * @param {string} card_type
+     * @param {string} card_kind
      * @returns {FormCard | null}
      */
-    blankCard(card_type) {
+    blankCard(card_kind) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(card_type, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr0 = passStringToWasm0(card_kind, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len0 = WASM_VECTOR_LEN;
             wasm.quill_blankCard(retptr, this.__wbg_ptr, ptr0, len0);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);

package/bundler/wasm_bg.wasm.d.ts

@@ -9,6 +9,7 @@ export const document_cardCount: (a: number) => number;
 export const document_cards: (a: number) => number;
 export const document_clone: (a: number) => number;
 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;
@@ -23,6 +24,7 @@ export const document_setCardTag: (a: number, b: number, c: number, d: number, e
 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_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;

package/package.json

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