@norskvideo/moq-json 0.1.2 → 0.1.4

package/index.d.ts

@@ -1,17 +1,27 @@
 /**
- * JSON publishing over MoQ tracks, in two modes:
+ * JSON publishing over MoQ tracks, in three modes:
  *
  * - {@link Snapshot}: **lossy**. One JSON value updated over time; a consumer only gets the most
  *   recent value. Intermediate updates are collapsed and older groups are dropped.
  * - {@link Stream}: **lossless**. An ordered append-log of self-contained records; every record
  *   is preserved and delivered in order, nothing is ever superseded.
+ * - {@link Window}: a **bounded** run of records, appended to the back and dropped from the front,
+ *   that a reader can join at any point.
  *
  * Pick {@link Snapshot} when consumers care about "what is the value now" (a catalog, a status
- * document) and {@link Stream} when they care about every record (an event log, a media timeline).
+ * document), {@link Stream} when they care about every record of an unbounded log, and
+ * {@link Window} when the publisher retires old records and a late reader should start from what is
+ * still retained (a media timeline).
+ *
+ * Each mode comes in two layers. `Producer`/`Consumer` own a track and manage its groups.
+ * `Encoder`/`Decoder` are the same logic without the track: values in, frame payloads out (and
+ * back), with the encoder saying where the group boundaries fall. Reach for the codec layer when
+ * something else already owns the track.
  *
  * @module
  */
 export { type Diff, deepEqual, diff, merge } from "./diff";
 export * as Snapshot from "./snapshot/index";
-export * as Stream from "./stream";
+export * as Stream from "./stream/index";
+export * as Window from "./window/index";
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC"}

package/index.js

@@ -1,20 +1,31 @@
 /* @ts-self-types="./index.d.ts" */
 /**
- * JSON publishing over MoQ tracks, in two modes:
+ * JSON publishing over MoQ tracks, in three modes:
  *
  * - {@link Snapshot}: **lossy**. One JSON value updated over time; a consumer only gets the most
  *   recent value. Intermediate updates are collapsed and older groups are dropped.
  * - {@link Stream}: **lossless**. An ordered append-log of self-contained records; every record
  *   is preserved and delivered in order, nothing is ever superseded.
+ * - {@link Window}: a **bounded** run of records, appended to the back and dropped from the front,
+ *   that a reader can join at any point.
  *
  * Pick {@link Snapshot} when consumers care about "what is the value now" (a catalog, a status
- * document) and {@link Stream} when they care about every record (an event log, a media timeline).
+ * document), {@link Stream} when they care about every record of an unbounded log, and
+ * {@link Window} when the publisher retires old records and a late reader should start from what is
+ * still retained (a media timeline).
+ *
+ * Each mode comes in two layers. `Producer`/`Consumer` own a track and manage its groups.
+ * `Encoder`/`Decoder` are the same logic without the track: values in, frame payloads out (and
+ * back), with the encoder saying where the group boundaries fall. Reach for the codec layer when
+ * something else already owns the track.
  *
  * @module
  */
 export { deepEqual, diff, merge } from "./diff.js";
 import * as Snapshot_1 from "./snapshot/index.js";
 export { Snapshot_1 as Snapshot };
-import * as Stream_1 from "./stream.js";
+import * as Stream_1 from "./stream/index.js";
 export { Stream_1 as Stream };
+import * as Window_1 from "./window/index.js";
+export { Window_1 as Window };
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAa,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;4BACpC,qBAAqB;uBAAnC,QAAQ;0BACI,aAAa;qBAAzB,MAAM","sourcesContent":["/**\n * JSON publishing over MoQ tracks, in two modes:\n *\n * - {@link Snapshot}: **lossy**. One JSON value updated over time; a consumer only gets the most\n *   recent value. Intermediate updates are collapsed and older groups are dropped.\n * - {@link Stream}: **lossless**. An ordered append-log of self-contained records; every record\n *   is preserved and delivered in order, nothing is ever superseded.\n *\n * Pick {@link Snapshot} when consumers care about \"what is the value now\" (a catalog, a status\n * document) and {@link Stream} when they care about every record (an event log, a media timeline).\n *\n * @module\n */\n\nexport { type Diff, deepEqual, diff, merge } from \"./diff.ts\";\nexport * as Snapshot from \"./snapshot/index.ts\";\nexport * as Stream from \"./stream.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAa,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;4BACpC,qBAAqB;uBAAnC,QAAQ;0BACI,mBAAmB;qBAA/B,MAAM;0BACM,mBAAmB;qBAA/B,MAAM","sourcesContent":["/**\n * JSON publishing over MoQ tracks, in three modes:\n *\n * - {@link Snapshot}: **lossy**. One JSON value updated over time; a consumer only gets the most\n *   recent value. Intermediate updates are collapsed and older groups are dropped.\n * - {@link Stream}: **lossless**. An ordered append-log of self-contained records; every record\n *   is preserved and delivered in order, nothing is ever superseded.\n * - {@link Window}: a **bounded** run of records, appended to the back and dropped from the front,\n *   that a reader can join at any point.\n *\n * Pick {@link Snapshot} when consumers care about \"what is the value now\" (a catalog, a status\n * document), {@link Stream} when they care about every record of an unbounded log, and\n * {@link Window} when the publisher retires old records and a late reader should start from what is\n * still retained (a media timeline).\n *\n * Each mode comes in two layers. `Producer`/`Consumer` own a track and manage its groups.\n * `Encoder`/`Decoder` are the same logic without the track: values in, frame payloads out (and\n * back), with the encoder saying where the group boundaries fall. Reach for the codec layer when\n * something else already owns the track.\n *\n * @module\n */\n\nexport { type Diff, deepEqual, diff, merge } from \"./diff.ts\";\nexport * as Snapshot from \"./snapshot/index.ts\";\nexport * as Stream from \"./stream/index.ts\";\nexport * as Window from \"./window/index.ts\";\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@norskvideo/moq-json",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "JSON publishing over MoQ tracks: snapshot/delta (RFC 7396 merge patch) objects, or append-log NDJSON streams.",
   "license": "(MIT OR Apache-2.0)",
   "repository": "github:moq-dev/moq",
@@ -13,11 +13,12 @@
     }
   },
   "dependencies": {
-    "@norskvideo/moq-flate": "^0.1.2",
-    "@norskvideo/moq-net": "^0.1.2",
-    "@norskvideo/moq-signals": "^0.1.2"
+    "@norskvideo/moq-flate": "^0.1.4",
+    "@norskvideo/moq-net": "^0.1.4",
+    "@norskvideo/moq-signals": "^0.1.4"
   },
   "peerDependencies": {
-    "zod": "^4.0.0"
+    "@zod/mini": "^4.5.0",
+    "zod": "^4.5.0"
   }
 }

package/snapshot/consumer.d.ts

@@ -1,15 +1,17 @@
 import type * as Moq from "@norskvideo/moq-net";
-import type { Config } from "./producer";
+import type { Config } from "./encoder";
 /**
  * Consumes a JSON value from a track, reconstructing it from snapshots and deltas.
  *
- * Reads each group's snapshot (frame 0) and applies the following frames as merge patches. A live
- * consumer yields each update as it arrives; a consumer that has fallen behind (or just joined)
- * collapses the buffered backlog and yields only the latest value. See {@link next}.
+ * A {@link Decoder} that owns its track: it reads groups, routes each frame by its position, and
+ * yields the reconstructed value. A live consumer yields each update as it arrives; a consumer that
+ * has fallen behind (or just joined) collapses the buffered backlog and yields only the latest
+ * value. See {@link next}. When something else already owns the track, use the {@link Decoder}
+ * directly.
  */
 export declare class Consumer<T> {
     #private;
-    constructor(track: Moq.Track, config?: Config<T>);
+    constructor(track: Moq.Track.Subscriber, config?: Config<T>);
     /**
      * Get the next reconstructed value, or `undefined` once the track ends.
      *

package/snapshot/consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../src/snapshot/consumer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;GAMG;AACH,qBAAa,QAAQ,CAAC,CAAC;;IAYtB,YAAY,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAM,EAInD;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA+BnC;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAMhD;CAoBD"}
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../src/snapshot/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;GAQG;AACH,qBAAa,QAAQ,CAAC,CAAC;;IAOtB,YAAY,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAM,EAG9D;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAwCnC;IAEM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAMhD;CAWD"}

package/snapshot/consumer.js

@@ -1,27 +1,22 @@
 /* @ts-self-types="./consumer.d.ts" */
-import { Decoder } from "@norskvideo/moq-flate";
-import { merge } from "../diff.js";
+import { Decoder } from "./decoder.js";
 /**
  * Consumes a JSON value from a track, reconstructing it from snapshots and deltas.
  *
- * Reads each group's snapshot (frame 0) and applies the following frames as merge patches. A live
- * consumer yields each update as it arrives; a consumer that has fallen behind (or just joined)
- * collapses the buffered backlog and yields only the latest value. See {@link next}.
+ * A {@link Decoder} that owns its track: it reads groups, routes each frame by its position, and
+ * yields the reconstructed value. A live consumer yields each update as it arrives; a consumer that
+ * has fallen behind (or just joined) collapses the buffered backlog and yields only the latest
+ * value. See {@link next}. When something else already owns the track, use the {@link Decoder}
+ * directly.
  */
 export class Consumer {
     #track;
-    #schema;
-    // Whether frames are `deflate-raw` compressed. Must match the producer's {@link Config.compression}.
-    #decompress;
-    #group;
-    // Per-group DEFLATE decoder, built lazily on the first frame of a group and reset at each boundary.
     #decoder;
-    #current;
+    #group;
     #framesRead = 0;
     constructor(track, config = {}) {
         this.#track = track;
-        this.#schema = config.schema;
-        this.#decompress = config.compression ?? false;
+        this.#decoder = new Decoder(config);
     }
     /**
      * Get the next reconstructed value, or `undefined` once the track ends.
@@ -36,31 +31,40 @@ export class Consumer {
         for (;;) {
             if (!this.#group) {
                 // Advance to the next group with a higher sequence number (skipping late arrivals).
-                this.#group = await this.#track.nextGroupOrdered();
+                this.#group = await this.#track.nextGroup();
                 if (!this.#group)
                     return undefined;
-                this.#current = undefined;
+                // The next frame is the new group's snapshot, which also restarts the decoder's window.
                 this.#framesRead = 0;
-                // Each group is its own compressed stream, so start a fresh decoder.
-                this.#decoder = undefined;
             }
-            // Drain every frame already buffered, keeping only the latest reconstructed value.
-            let value;
+            // Drain every frame already buffered, keeping only the latest reconstructed value: a late
+            // joiner (or any consumer that fell behind) catches up to the head in one step.
             let advanced = false;
             for (let frame = this.#group.tryReadFrame(); frame !== undefined; frame = this.#group.tryReadFrame()) {
-                value = this.#apply(frame);
+                this.#apply(frame.payload);
                 advanced = true;
             }
             if (advanced)
-                return value;
+                return this.#decoder.decode();
             // Nothing buffered: block for the next frame (or the group's end).
-            const frame = await this.#group.readFrame();
+            let frame;
+            try {
+                frame = await this.#group.readFrame();
+            }
+            catch {
+                // The group was reset or we fell behind its eviction window. Resync from
+                // the next group, which begins with a fresh snapshot (frame 0), so no
+                // partial state is presented.
+                this.#group = undefined;
+                continue;
+            }
             if (frame === undefined) {
                 // The group is exhausted; advance to the next one.
                 this.#group = undefined;
                 continue;
             }
-            return this.#apply(frame);
+            this.#apply(frame.payload);
+            return this.#decoder.decode();
         }
     }
     async *[Symbol.asyncIterator]() {
@@ -71,23 +75,15 @@ export class Consumer {
             yield value;
         }
     }
-    // Frame 0 of a group is a snapshot, the rest are merge patches. When compressed, frames share one
-    // per-group DEFLATE stream, so they decode in order through a decoder built on the group's first frame.
-    #apply(frame) {
-        let payload = frame;
-        if (this.#decompress) {
-            this.#decoder ??= new Decoder();
-            payload = this.#decoder.frame(frame);
-        }
-        const parsed = JSON.parse(new TextDecoder().decode(payload));
+    // Frame 0 of a group is a snapshot, the rest are merge patches.
+    #apply(payload) {
         if (this.#framesRead === 0) {
-            this.#current = parsed;
+            this.#decoder.snapshot(payload);
         }
         else {
-            this.#current = merge(this.#current, parsed);
+            this.#decoder.delta(payload);
         }
         this.#framesRead += 1;
-        return this.#schema ? this.#schema.parse(this.#current) : this.#current;
     }
 }
 //# sourceMappingURL=consumer.js.map

package/snapshot/consumer.js.map

@@ -1 +1 @@
-{"version":3,"file":"consumer.js","sourceRoot":"","sources":["../../src/snapshot/consumer.ts"],"names":[],"mappings":"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","sourcesContent":["import { Decoder } from \"@moq/flate\";\nimport type * as Moq from \"@moq/net\";\nimport type * as z from \"zod/mini\";\nimport { merge } from \"../diff.ts\";\nimport type { Config } from \"./producer.ts\";\n\n/**\n * Consumes a JSON value from a track, reconstructing it from snapshots and deltas.\n *\n * Reads each group's snapshot (frame 0) and applies the following frames as merge patches. A live\n * consumer yields each update as it arrives; a consumer that has fallen behind (or just joined)\n * collapses the buffered backlog and yields only the latest value. See {@link next}.\n */\nexport class Consumer<T> {\n\t#track: Moq.Track;\n\t#schema?: z.ZodMiniType<T>;\n\t// Whether frames are `deflate-raw` compressed. Must match the producer's {@link Config.compression}.\n\t#decompress: boolean;\n\n\t#group?: Moq.Group;\n\t// Per-group DEFLATE decoder, built lazily on the first frame of a group and reset at each boundary.\n\t#decoder?: Decoder;\n\t#current?: unknown;\n\t#framesRead = 0;\n\n\tconstructor(track: Moq.Track, config: Config<T> = {}) {\n\t\tthis.#track = track;\n\t\tthis.#schema = config.schema;\n\t\tthis.#decompress = config.compression ?? false;\n\t}\n\n\t/**\n\t * Get the next reconstructed value, or `undefined` once the track ends.\n\t *\n\t * Applies every frame already buffered in the group but yields only the latest reconstructed\n\t * value: the intermediate reconstructions are stale, so a late joiner (or any consumer that has\n\t * fallen behind) catches up to the head in one step instead of replaying every superseded state.\n\t * Frames are still decoded in order (the DEFLATE window and merge patches are sequential); only\n\t * the per-frame yield is skipped.\n\t */\n\tasync next(): Promise<T | undefined> {\n\t\tfor (;;) {\n\t\t\tif (!this.#group) {\n\t\t\t\t// Advance to the next group with a higher sequence number (skipping late arrivals).\n\t\t\t\tthis.#group = await this.#track.nextGroupOrdered();\n\t\t\t\tif (!this.#group) return undefined;\n\t\t\t\tthis.#current = undefined;\n\t\t\t\tthis.#framesRead = 0;\n\t\t\t\t// Each group is its own compressed stream, so start a fresh decoder.\n\t\t\t\tthis.#decoder = undefined;\n\t\t\t}\n\n\t\t\t// Drain every frame already buffered, keeping only the latest reconstructed value.\n\t\t\tlet value: T | undefined;\n\t\t\tlet advanced = false;\n\t\t\tfor (let frame = this.#group.tryReadFrame(); frame !== undefined; frame = this.#group.tryReadFrame()) {\n\t\t\t\tvalue = this.#apply(frame);\n\t\t\t\tadvanced = true;\n\t\t\t}\n\t\t\tif (advanced) return value;\n\n\t\t\t// Nothing buffered: block for the next frame (or the group's end).\n\t\t\tconst frame = await this.#group.readFrame();\n\t\t\tif (frame === undefined) {\n\t\t\t\t// The group is exhausted; advance to the next one.\n\t\t\t\tthis.#group = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\treturn this.#apply(frame);\n\t\t}\n\t}\n\n\tasync *[Symbol.asyncIterator](): AsyncIterator<T> {\n\t\tfor (;;) {\n\t\t\tconst value = await this.next();\n\t\t\tif (value === undefined) return;\n\t\t\tyield value;\n\t\t}\n\t}\n\n\t// Frame 0 of a group is a snapshot, the rest are merge patches. When compressed, frames share one\n\t// per-group DEFLATE stream, so they decode in order through a decoder built on the group's first frame.\n\t#apply(frame: Uint8Array): T {\n\t\tlet payload = frame;\n\t\tif (this.#decompress) {\n\t\t\tthis.#decoder ??= new Decoder();\n\t\t\tpayload = this.#decoder.frame(frame);\n\t\t}\n\t\tconst parsed = JSON.parse(new TextDecoder().decode(payload));\n\t\tif (this.#framesRead === 0) {\n\t\t\tthis.#current = parsed;\n\t\t} else {\n\t\t\tthis.#current = merge(this.#current, parsed);\n\t\t}\n\t\tthis.#framesRead += 1;\n\n\t\treturn this.#schema ? this.#schema.parse(this.#current) : (this.#current as T);\n\t}\n}\n"]}
+{"version":3,"file":"consumer.js","sourceRoot":"","sources":["../../src/snapshot/consumer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAQ;IACpB,MAAM,CAAuB;IAC7B,QAAQ,CAAa;IAErB,MAAM,CAAsB;IAC5B,WAAW,GAAG,CAAC,CAAC;IAEhB,YAAY,KAA2B,EAAE,MAAM,GAAc,EAAE;QAC9D,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI;QACT,SAAS,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBAClB,oFAAoF;gBACpF,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC5C,IAAI,CAAC,IAAI,CAAC,MAAM;oBAAE,OAAO,SAAS,CAAC;gBACnC,wFAAwF;gBACxF,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;YACtB,CAAC;YAED,0FAA0F;YAC1F,gFAAgF;YAChF,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,KAAK,KAAK,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC;gBACtG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC3B,QAAQ,GAAG,IAAI,CAAC;YACjB,CAAC;YACD,IAAI,QAAQ;gBAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAE5C,mEAAmE;YACnE,IAAI,KAAkC,CAAC;YACvC,IAAI,CAAC;gBACJ,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACR,yEAAyE;gBACzE,sEAAsE;gBACtE,8BAA8B;gBAC9B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,SAAS;YACV,CAAC;YAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,mDAAmD;gBACnD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,SAAS;YACV,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC/B,CAAC;IACF,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC5B,SAAS,CAAC;YACT,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,OAAmB;QACzB,IAAI,IAAI,CAAC,WAAW,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;IACvB,CAAC;CACD","sourcesContent":["import type * as Moq from \"@moq/net\";\n\nimport { Decoder } from \"./decoder.ts\";\nimport type { Config } from \"./encoder.ts\";\n\n/**\n * Consumes a JSON value from a track, reconstructing it from snapshots and deltas.\n *\n * A {@link Decoder} that owns its track: it reads groups, routes each frame by its position, and\n * yields the reconstructed value. A live consumer yields each update as it arrives; a consumer that\n * has fallen behind (or just joined) collapses the buffered backlog and yields only the latest\n * value. See {@link next}. When something else already owns the track, use the {@link Decoder}\n * directly.\n */\nexport class Consumer<T> {\n\t#track: Moq.Track.Subscriber;\n\t#decoder: Decoder<T>;\n\n\t#group?: Moq.Group.Consumer;\n\t#framesRead = 0;\n\n\tconstructor(track: Moq.Track.Subscriber, config: Config<T> = {}) {\n\t\tthis.#track = track;\n\t\tthis.#decoder = new Decoder(config);\n\t}\n\n\t/**\n\t * Get the next reconstructed value, or `undefined` once the track ends.\n\t *\n\t * Applies every frame already buffered in the group but yields only the latest reconstructed\n\t * value: the intermediate reconstructions are stale, so a late joiner (or any consumer that has\n\t * fallen behind) catches up to the head in one step instead of replaying every superseded state.\n\t * Frames are still decoded in order (the DEFLATE window and merge patches are sequential); only\n\t * the per-frame yield is skipped.\n\t */\n\tasync next(): Promise<T | undefined> {\n\t\tfor (;;) {\n\t\t\tif (!this.#group) {\n\t\t\t\t// Advance to the next group with a higher sequence number (skipping late arrivals).\n\t\t\t\tthis.#group = await this.#track.nextGroup();\n\t\t\t\tif (!this.#group) return undefined;\n\t\t\t\t// The next frame is the new group's snapshot, which also restarts the decoder's window.\n\t\t\t\tthis.#framesRead = 0;\n\t\t\t}\n\n\t\t\t// Drain every frame already buffered, keeping only the latest reconstructed value: a late\n\t\t\t// joiner (or any consumer that fell behind) catches up to the head in one step.\n\t\t\tlet advanced = false;\n\t\t\tfor (let frame = this.#group.tryReadFrame(); frame !== undefined; frame = this.#group.tryReadFrame()) {\n\t\t\t\tthis.#apply(frame.payload);\n\t\t\t\tadvanced = true;\n\t\t\t}\n\t\t\tif (advanced) return this.#decoder.decode();\n\n\t\t\t// Nothing buffered: block for the next frame (or the group's end).\n\t\t\tlet frame: Moq.Group.Frame | undefined;\n\t\t\ttry {\n\t\t\t\tframe = await this.#group.readFrame();\n\t\t\t} catch {\n\t\t\t\t// The group was reset or we fell behind its eviction window. Resync from\n\t\t\t\t// the next group, which begins with a fresh snapshot (frame 0), so no\n\t\t\t\t// partial state is presented.\n\t\t\t\tthis.#group = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (frame === undefined) {\n\t\t\t\t// The group is exhausted; advance to the next one.\n\t\t\t\tthis.#group = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tthis.#apply(frame.payload);\n\t\t\treturn this.#decoder.decode();\n\t\t}\n\t}\n\n\tasync *[Symbol.asyncIterator](): AsyncIterator<T> {\n\t\tfor (;;) {\n\t\t\tconst value = await this.next();\n\t\t\tif (value === undefined) return;\n\t\t\tyield value;\n\t\t}\n\t}\n\n\t// Frame 0 of a group is a snapshot, the rest are merge patches.\n\t#apply(payload: Uint8Array): void {\n\t\tif (this.#framesRead === 0) {\n\t\t\tthis.#decoder.snapshot(payload);\n\t\t} else {\n\t\t\tthis.#decoder.delta(payload);\n\t\t}\n\t\tthis.#framesRead += 1;\n\t}\n}\n"]}

package/snapshot/decoder.d.ts

@@ -0,0 +1,46 @@
+import type { Config } from "./encoder";
+/**
+ * Reconstructs a JSON value from the snapshot and delta frames of a group.
+ *
+ * The track-free core of {@link Consumer}, and the mirror of {@link Encoder}. The caller reads
+ * frames from wherever it likes and routes each one by its position in the group: the first frame of
+ * every group is a {@link snapshot}, the rest are {@link delta}s.
+ *
+ * Applying and materializing are separate on purpose. Frames must be applied in order (the merge
+ * patches and the DEFLATE window are both sequential), but a consumer catching up on a backlog only
+ * wants the value at the head, so it applies every frame and calls {@link decode} once. A caller
+ * that wants a value per frame just calls it every time.
+ */
+export declare class Decoder<T> {
+    #private;
+    constructor(config?: Config<T>);
+    /**
+     * Apply a group's first frame: a full snapshot that replaces the current value.
+     *
+     * Also starts the group's DEFLATE window, so this must be called at every group boundary, not
+     * only the first.
+     */
+    snapshot(payload: Uint8Array): void;
+    /**
+     * Apply one of a group's later frames: an RFC 7396 merge patch against the current value.
+     *
+     * Throws when no snapshot has been applied yet, since a patch has nothing to apply to.
+     */
+    delta(payload: Uint8Array): void;
+    /**
+     * A copy of the reconstructed value as raw JSON, or `undefined` before the first snapshot.
+     *
+     * Copied rather than shared: it is the base every later {@link delta} merges into, so a caller
+     * mutating it would change fields no frame ever carried.
+     */
+    get value(): unknown;
+    /**
+     * Materialize the reconstructed value, or `undefined` before the first snapshot.
+     *
+     * The result is the caller's own copy, for the same reason as {@link value}. (A schema already
+     * produces a fresh object, so it only needs cloning without one. The Rust decoder deserializes a
+     * fresh `T` every call and never exposes its internal state at all.)
+     */
+    decode(): T | undefined;
+}
+//# sourceMappingURL=decoder.d.ts.map

package/snapshot/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/snapshot/decoder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,qBAAa,OAAO,CAAC,CAAC;;IAUrB,YAAY,MAAM,GAAE,MAAM,CAAC,CAAC,CAAM,EAGjC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAIlC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAG/B;IAED;;;;;OAKG;IACH,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED;;;;;;OAMG;IACH,MAAM,IAAI,CAAC,GAAG,SAAS,CAGtB;CAOD"}

package/snapshot/decoder.js

@@ -0,0 +1,76 @@
+/* @ts-self-types="./decoder.d.ts" */
+import { Decoder as Flate } from "@norskvideo/moq-flate";
+import { merge } from "../diff.js";
+/**
+ * Reconstructs a JSON value from the snapshot and delta frames of a group.
+ *
+ * The track-free core of {@link Consumer}, and the mirror of {@link Encoder}. The caller reads
+ * frames from wherever it likes and routes each one by its position in the group: the first frame of
+ * every group is a {@link snapshot}, the rest are {@link delta}s.
+ *
+ * Applying and materializing are separate on purpose. Frames must be applied in order (the merge
+ * patches and the DEFLATE window are both sequential), but a consumer catching up on a backlog only
+ * wants the value at the head, so it applies every frame and calls {@link decode} once. A caller
+ * that wants a value per frame just calls it every time.
+ */
+export class Decoder {
+    #schema;
+    // Whether frames are `deflate-raw` compressed. Must match the encoder's {@link Config.compression}.
+    #decompress;
+    // The current group's DEFLATE window, rebuilt at each snapshot.
+    #flate;
+    // The reconstructed value, `undefined` until the first snapshot.
+    #current;
+    constructor(config = {}) {
+        this.#schema = config.schema;
+        this.#decompress = config.compression ?? false;
+    }
+    /**
+     * Apply a group's first frame: a full snapshot that replaces the current value.
+     *
+     * Also starts the group's DEFLATE window, so this must be called at every group boundary, not
+     * only the first.
+     */
+    snapshot(payload) {
+        // Each group is its own compressed stream, so the window starts cold here.
+        this.#flate = this.#decompress ? new Flate() : undefined;
+        this.#current = this.#parse(payload);
+    }
+    /**
+     * Apply one of a group's later frames: an RFC 7396 merge patch against the current value.
+     *
+     * Throws when no snapshot has been applied yet, since a patch has nothing to apply to.
+     */
+    delta(payload) {
+        if (this.#current === undefined)
+            throw new Error("delta before snapshot");
+        this.#current = merge(this.#current, this.#parse(payload));
+    }
+    /**
+     * A copy of the reconstructed value as raw JSON, or `undefined` before the first snapshot.
+     *
+     * Copied rather than shared: it is the base every later {@link delta} merges into, so a caller
+     * mutating it would change fields no frame ever carried.
+     */
+    get value() {
+        return this.#current === undefined ? undefined : structuredClone(this.#current);
+    }
+    /**
+     * Materialize the reconstructed value, or `undefined` before the first snapshot.
+     *
+     * The result is the caller's own copy, for the same reason as {@link value}. (A schema already
+     * produces a fresh object, so it only needs cloning without one. The Rust decoder deserializes a
+     * fresh `T` every call and never exposes its internal state at all.)
+     */
+    decode() {
+        if (this.#current === undefined)
+            return undefined;
+        return this.#schema ? this.#schema.parse(this.#current) : structuredClone(this.#current);
+    }
+    // Decompress a frame against the group's window when compressing, then parse it as JSON.
+    #parse(payload) {
+        const plain = this.#flate ? this.#flate.frame(payload) : payload;
+        return JSON.parse(new TextDecoder().decode(plain));
+    }
+}
+//# sourceMappingURL=decoder.js.map

package/snapshot/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../../src/snapshot/decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,OAAO;IACnB,OAAO,CAAuB;IAC9B,oGAAoG;IACpG,WAAW,CAAU;IAErB,gEAAgE;IAChE,MAAM,CAAS;IACf,iEAAiE;IACjE,QAAQ,CAAW;IAEnB,YAAY,MAAM,GAAc,EAAE;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,KAAK,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,OAAmB;QAC3B,2EAA2E;QAC3E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAmB;QACxB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC1E,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;OAKG;IACH,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IAED;;;;;;OAMG;IACH,MAAM;QACL,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAO,CAAC;IACjG,CAAC;IAED,yFAAyF;IACzF,MAAM,CAAC,OAAmB;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QACjE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;CACD","sourcesContent":["import { Decoder as Flate } from \"@moq/flate\";\n\nimport { merge } from \"../diff.ts\";\nimport type { Config } from \"./encoder.ts\";\n\n/**\n * Reconstructs a JSON value from the snapshot and delta frames of a group.\n *\n * The track-free core of {@link Consumer}, and the mirror of {@link Encoder}. The caller reads\n * frames from wherever it likes and routes each one by its position in the group: the first frame of\n * every group is a {@link snapshot}, the rest are {@link delta}s.\n *\n * Applying and materializing are separate on purpose. Frames must be applied in order (the merge\n * patches and the DEFLATE window are both sequential), but a consumer catching up on a backlog only\n * wants the value at the head, so it applies every frame and calls {@link decode} once. A caller\n * that wants a value per frame just calls it every time.\n */\nexport class Decoder<T> {\n\t#schema?: Config<T>[\"schema\"];\n\t// Whether frames are `deflate-raw` compressed. Must match the encoder's {@link Config.compression}.\n\t#decompress: boolean;\n\n\t// The current group's DEFLATE window, rebuilt at each snapshot.\n\t#flate?: Flate;\n\t// The reconstructed value, `undefined` until the first snapshot.\n\t#current?: unknown;\n\n\tconstructor(config: Config<T> = {}) {\n\t\tthis.#schema = config.schema;\n\t\tthis.#decompress = config.compression ?? false;\n\t}\n\n\t/**\n\t * Apply a group's first frame: a full snapshot that replaces the current value.\n\t *\n\t * Also starts the group's DEFLATE window, so this must be called at every group boundary, not\n\t * only the first.\n\t */\n\tsnapshot(payload: Uint8Array): void {\n\t\t// Each group is its own compressed stream, so the window starts cold here.\n\t\tthis.#flate = this.#decompress ? new Flate() : undefined;\n\t\tthis.#current = this.#parse(payload);\n\t}\n\n\t/**\n\t * Apply one of a group's later frames: an RFC 7396 merge patch against the current value.\n\t *\n\t * Throws when no snapshot has been applied yet, since a patch has nothing to apply to.\n\t */\n\tdelta(payload: Uint8Array): void {\n\t\tif (this.#current === undefined) throw new Error(\"delta before snapshot\");\n\t\tthis.#current = merge(this.#current, this.#parse(payload));\n\t}\n\n\t/**\n\t * A copy of the reconstructed value as raw JSON, or `undefined` before the first snapshot.\n\t *\n\t * Copied rather than shared: it is the base every later {@link delta} merges into, so a caller\n\t * mutating it would change fields no frame ever carried.\n\t */\n\tget value(): unknown {\n\t\treturn this.#current === undefined ? undefined : structuredClone(this.#current);\n\t}\n\n\t/**\n\t * Materialize the reconstructed value, or `undefined` before the first snapshot.\n\t *\n\t * The result is the caller's own copy, for the same reason as {@link value}. (A schema already\n\t * produces a fresh object, so it only needs cloning without one. The Rust decoder deserializes a\n\t * fresh `T` every call and never exposes its internal state at all.)\n\t */\n\tdecode(): T | undefined {\n\t\tif (this.#current === undefined) return undefined;\n\t\treturn this.#schema ? this.#schema.parse(this.#current) : (structuredClone(this.#current) as T);\n\t}\n\n\t// Decompress a frame against the group's window when compressing, then parse it as JSON.\n\t#parse(payload: Uint8Array): unknown {\n\t\tconst plain = this.#flate ? this.#flate.frame(payload) : payload;\n\t\treturn JSON.parse(new TextDecoder().decode(plain));\n\t}\n}\n"]}

package/snapshot/encoder.d.ts

@@ -0,0 +1,96 @@
+import type * as z from "@zod/mini";
+export declare const DEFAULT_DELTA_RATIO = 8;
+/** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */
+export interface Config<T> {
+    deltaRatio?: number;
+    schema?: z.ZodMiniType<T>;
+    initial?: T;
+    compression?: boolean;
+}
+/** One encoded frame, and the group boundary it implies. */
+export interface Encoded {
+    /** The frame payload, `deflate-raw` compressed when {@link Config.compression} is set. */
+    payload: Uint8Array;
+    /**
+     * Whether this frame is a full snapshot, which must open a new group.
+     *
+     * `true` means the caller writes it as the first frame of a fresh group; `false` means it is a
+     * merge patch that must be appended to the group the last snapshot opened.
+     *
+     * The encoder decides this, never the caller: a value that sets a field to JSON null, or whose
+     * root isn't an object, cannot be expressed as a merge patch at all, and the delta budget and
+     * frame cap force a snapshot independently of what the caller wanted.
+     */
+    keyframe: boolean;
+}
+/**
+ * An encoded frame the caller has not yet acknowledged writing, returned by {@link Encoder.update}.
+ *
+ * Write the frame, then {@link commit}. A frame that is never committed never reached the wire, so
+ * the encoder resynchronizes on the next {@link Encoder.update}: it starts a fresh snapshot rather
+ * than emitting deltas against a baseline no consumer received.
+ *
+ * This is a recovery, not a rollback. Producing a delta payload advances the group's DEFLATE window
+ * and that can't be undone, so a snapshot is the only sound way back. Forgetting to commit a frame
+ * that *was* written is therefore merely wasteful (one redundant snapshot), never incorrect.
+ */
+export interface Pending extends Encoded {
+    /**
+     * Acknowledge that the frame reached the wire, keeping the encoder's state.
+     *
+     * Only call this once the write has actually succeeded. Committing a frame that failed to write
+     * is the one thing that corrupts the stream.
+     */
+    commit(): void;
+}
+/**
+ * Encodes a JSON value into frame payloads, choosing snapshots and deltas automatically.
+ *
+ * The track-free core of {@link Producer}: it decides *what bytes go in a frame* and *where the
+ * group boundaries fall*, and leaves writing them to the caller. Reach for it when something else
+ * already owns the track.
+ *
+ * Frames must reach the wire in the order they were encoded, and a frame with
+ * {@link Encoded.keyframe} set must open a new group: both the merge patches and the group-scoped
+ * DEFLATE window depend on it. {@link update} hands back a {@link Pending} rather than a bare
+ * {@link Encoded} so a frame that never reaches the wire can't silently desync the encoder: leave it
+ * uncommitted and the next update resynchronizes with a fresh snapshot.
+ *
+ * (The Rust `moq-json` encoder does the same thing through `Drop`, so it resynchronizes the moment
+ * the frame is discarded. JavaScript has no destructor, so the check happens on the next update
+ * instead. The resulting stream is identical either way.)
+ *
+ * If the caller closes a group for its own reasons, call
+ * {@link reset} so the next value is encoded as a snapshot.
+ */
+export declare class Encoder<T> {
+    #private;
+    constructor(config?: Config<T>);
+    /**
+     * A copy of the last encoded value, or `undefined` before the first snapshot.
+     *
+     * Copied rather than shared: the baseline is what the next delta is diffed against, so a caller
+     * mutating it in place would make a later change look unchanged and never reach consumers.
+     */
+    get value(): T | undefined;
+    /**
+     * Force the next {@link update} to emit a full snapshot, even for an unchanged value.
+     *
+     * Call this whenever the caller closes the current group behind the encoder's back. Without it
+     * the next value may be encoded as a delta against a DEFLATE window and a baseline that the new
+     * group doesn't carry.
+     *
+     * {@link value} survives: the snapshot republishes it in full anyway, and it is what a caller
+     * editing in place starts from.
+     */
+    reset(): void;
+    /**
+     * Encode a new value, as a snapshot or a delta.
+     *
+     * Returns `undefined` when the value is unchanged from the last one encoded, so nothing needs to
+     * be written. Otherwise the frame comes back as a {@link Pending} the caller writes and then
+     * commits; leaving one uncommitted resynchronizes the encoder here, on the next call.
+     */
+    update(value: T): Pending | undefined;
+}
+//# sourceMappingURL=encoder.d.ts.map

package/snapshot/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/snapshot/encoder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,CAAC,MAAM,WAAW,CAAC;AAUpC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,oFAAoF;AACpF,MAAM,WAAW,MAAM,CAAC,CAAC;IAcxB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAI1B,OAAO,CAAC,EAAE,CAAC,CAAC;IAMZ,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,OAAO;IACvB,0FAA0F;IAC1F,OAAO,EAAE,UAAU,CAAC;IAEpB;;;;;;;;;OASG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACvC;;;;;OAKG;IACH,MAAM,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,OAAO,CAAC,CAAC;;IAkCrB,YAAY,MAAM,GAAE,MAAM,CAAC,CAAC,CAAM,EAGjC;IAED;;;;;OAKG;IACH,IAAI,KAAK,IAAI,CAAC,GAAG,SAAS,CAEzB;IAED;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAOZ;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,GAAG,SAAS,CAuCpC;CAsED"}