@norskvideo/moq-json 0.1.2 → 0.1.4

package/stream/encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.js","sourceRoot":"","sources":["../../src/stream/encoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,YAAY,CAAC;AAoC9C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,OAAO;IACnB,SAAS,CAAU;IACnB,mEAAmE;IACnE,MAAM,CAAS;IAEf,8FAA8F;IAC9F,0FAA0F;IAC1F,SAAS,GAAG,KAAK,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,GAAG,KAAK,CAAC;IACjB,iGAAiG;IACjG,gFAAgF;IAChF,WAAW,GAAG,CAAC,CAAC;IAEhB,YAAY,MAAM,GAAmB,EAAE;QACtC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,WAAW,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACJ,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACvD,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAQ;QACd,+FAA+F;QAC/F,sDAAsD;QACtD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QAC3D,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACvF,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,0FAA0F;YAC1F,iFAAiF;YACjF,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACxD,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAE/D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,UAAU,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC;QAEtC,OAAO;YACN,OAAO;YACP,MAAM,EAAE,GAAG,EAAE;gBACZ,uFAAuF;gBACvF,2FAA2F;gBAC3F,0DAA0D;gBAC1D,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU;oBAAE,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YAC5D,CAAC;SACD,CAAC;IACH,CAAC;CACD","sourcesContent":["import { Encoder as Flate } from \"@moq/flate\";\n\n/** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */\nexport interface ProducerConfig {\n\t/**\n\t * Compress the group as one sync-flushed `deflate-raw` stream, so each record reuses the earlier\n\t * ones as context and shrinks sharply. A {@link Decoder} reading the frames must set the same\n\t * flag. Defaults to `false`.\n\t */\n\tcompression?: boolean;\n}\n\n/**\n * An encoded record the caller has not yet acknowledged writing, returned by {@link Encoder.encode}.\n *\n * Write the {@link payload}, then {@link commit}.\n *\n * A record that is never committed never reached the wire. With compression on that is\n * unrecoverable within the group: the window is ahead of what the consumer holds, and a log has no\n * keyframe to resynchronize on the way `Snapshot` does. So the encoder throws on the next\n * {@link Encoder.encode} until the caller rolls a new group and calls {@link Encoder.reset}. Without\n * compression each record stands alone, so a dropped one leaves a gap in the log but nothing\n * undecodable, and encoding continues.\n */\nexport interface Pending {\n\t/** The frame payload to write. */\n\tpayload: Uint8Array;\n\n\t/**\n\t * Acknowledge that the record reached the wire, keeping the encoder's window.\n\t *\n\t * Only call this once the write has actually succeeded.\n\t */\n\tcommit(): void;\n}\n\n/**\n * Encodes JSON records into frame payloads, sharing one DEFLATE window across the log.\n *\n * The track-free core of {@link Producer}. Unlike the `Snapshot` encoder there are no group\n * boundaries to report: a log is an unbroken sequence of self-contained records, so every payload is\n * simply the next frame.\n *\n * The window spans everything encoded so far, so payloads must reach the wire in order and be\n * decoded in the same order. If the caller does roll a group, call {@link reset} so the next record\n * starts a cold window that the new group's decoder can follow.\n */\nexport class Encoder<T> {\n\t#compress: boolean;\n\t// The DEFLATE window for the whole log, present while compressing.\n\t#flate?: Flate;\n\n\t// Set when a compressed record was encoded but never written. The window is then ahead of the\n\t// consumer for the rest of the group, so encoding stops until the caller rolls a new one.\n\t#desynced = false;\n\t// Whether the record from the last {@link encode} is still unacknowledged.\n\t#pending = false;\n\t// Bumped for each record handed out, so a commit that arrives after the encoder has moved on can\n\t// tell that it is acknowledging a record that is no longer the outstanding one.\n\t#generation = 0;\n\n\tconstructor(config: ProducerConfig = {}) {\n\t\tthis.#compress = config.compression ?? false;\n\t\tthis.#flate = this.#compress ? new Flate() : undefined;\n\t}\n\n\t/**\n\t * Start a cold DEFLATE window, for a caller that has just rolled a group.\n\t *\n\t * This is also how a caller clears a desync: roll a new group so the consumer starts its own cold\n\t * window, then reset.\n\t */\n\treset(): void {\n\t\tthis.#flate = this.#compress ? new Flate() : undefined;\n\t\tthis.#desynced = false;\n\t\tthis.#pending = false;\n\t}\n\n\t/**\n\t * Encode one record into the next frame payload.\n\t *\n\t * The record comes back as a {@link Pending} the caller writes and then commits. Throws if a\n\t * previous compressed record was left uncommitted, since every frame after it would be\n\t * undecodable.\n\t */\n\tencode(value: T): Pending {\n\t\t// An uncompressed record carries no shared state, so losing one leaves a gap in the log rather\n\t\t// than an undecodable stream, and encoding continues.\n\t\tif (this.#pending && this.#compress) this.#desynced = true;\n\t\tif (this.#desynced) {\n\t\t\tthrow new Error(\"compression desynchronized: a record was encoded but never written\");\n\t\t}\n\n\t\tconst text = JSON.stringify(value);\n\t\tif (text === undefined) {\n\t\t\t// `JSON.stringify` yields undefined for a top-level undefined, function, or symbol, which\n\t\t\t// would otherwise frame as empty bytes and fail on the consumer instead of here.\n\t\t\tthrow new Error(\"record is not representable as JSON\");\n\t\t}\n\n\t\tconst bytes = new TextEncoder().encode(text);\n\t\tconst payload = this.#flate ? this.#flate.frame(bytes) : bytes;\n\n\t\tthis.#pending = true;\n\t\tconst generation = ++this.#generation;\n\n\t\treturn {\n\t\t\tpayload,\n\t\t\tcommit: () => {\n\t\t\t\t// A caller that starts the next encode before this record settles has already made the\n\t\t\t\t// encoder account for it. Acknowledging it now would clear the flag belonging to the newer\n\t\t\t\t// record, so a later loss of that one would go unnoticed.\n\t\t\t\tif (this.#generation === generation) this.#pending = false;\n\t\t\t},\n\t\t};\n\t}\n}\n"]}

package/stream/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lossless append-log JSON publishing over MoQ tracks: the counterpart to the lossy `Snapshot`
+ * module. Instead of one value updated over time, a stream is an ordered log of self-contained
+ * records that preserves everything; every {@link Producer.append} writes one JSON object as one
+ * frame, nothing is ever superseded, and a {@link Consumer} yields every record in order.
+ *
+ * The whole log rides a **single group** that is never rolled: with {@link ProducerConfig.compression}
+ * on, that one group is one DEFLATE window, so every record compresses against the earlier ones.
+ * There is deliberately no group rolling (and so no catch-up machinery); a caller that wants to
+ * bound the record rate throttles at the source. Interoperable on the wire with the Rust
+ * `moq_json::stream`.
+ *
+ * {@link Producer} and {@link Consumer} own a track. {@link Encoder} and {@link Decoder} are the
+ * same logic without it, for when something else is already in charge of the track; they carry the
+ * shared DEFLATE window and nothing else, since a log has no group boundaries to report.
+ *
+ * @module
+ */
+export { Consumer } from "./consumer";
+export { type ConsumerConfig, Decoder } from "./decoder";
+export { Encoder, type Pending, type ProducerConfig } from "./encoder";
+export { Producer } from "./producer";
+//# sourceMappingURL=index.d.ts.map

package/stream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stream/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/stream/index.js

@@ -0,0 +1,24 @@
+/* @ts-self-types="./index.d.ts" */
+/**
+ * Lossless append-log JSON publishing over MoQ tracks: the counterpart to the lossy `Snapshot`
+ * module. Instead of one value updated over time, a stream is an ordered log of self-contained
+ * records that preserves everything; every {@link Producer.append} writes one JSON object as one
+ * frame, nothing is ever superseded, and a {@link Consumer} yields every record in order.
+ *
+ * The whole log rides a **single group** that is never rolled: with {@link ProducerConfig.compression}
+ * on, that one group is one DEFLATE window, so every record compresses against the earlier ones.
+ * There is deliberately no group rolling (and so no catch-up machinery); a caller that wants to
+ * bound the record rate throttles at the source. Interoperable on the wire with the Rust
+ * `moq_json::stream`.
+ *
+ * {@link Producer} and {@link Consumer} own a track. {@link Encoder} and {@link Decoder} are the
+ * same logic without it, for when something else is already in charge of the track; they carry the
+ * shared DEFLATE window and nothing else, since a log has no group boundaries to report.
+ *
+ * @module
+ */
+export { Consumer } from "./consumer.js";
+export { Decoder } from "./decoder.js";
+export { Encoder } from "./encoder.js";
+export { Producer } from "./producer.js";
+//# sourceMappingURL=index.js.map

package/stream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stream/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC","sourcesContent":["/**\n * Lossless append-log JSON publishing over MoQ tracks: the counterpart to the lossy `Snapshot`\n * module. Instead of one value updated over time, a stream is an ordered log of self-contained\n * records that preserves everything; every {@link Producer.append} writes one JSON object as one\n * frame, nothing is ever superseded, and a {@link Consumer} yields every record in order.\n *\n * The whole log rides a **single group** that is never rolled: with {@link ProducerConfig.compression}\n * on, that one group is one DEFLATE window, so every record compresses against the earlier ones.\n * There is deliberately no group rolling (and so no catch-up machinery); a caller that wants to\n * bound the record rate throttles at the source. Interoperable on the wire with the Rust\n * `moq_json::stream`.\n *\n * {@link Producer} and {@link Consumer} own a track. {@link Encoder} and {@link Decoder} are the\n * same logic without it, for when something else is already in charge of the track; they carry the\n * shared DEFLATE window and nothing else, since a log has no group boundaries to report.\n *\n * @module\n */\n\nexport { Consumer } from \"./consumer.ts\";\nexport { type ConsumerConfig, Decoder } from \"./decoder.ts\";\nexport { Encoder, type Pending, type ProducerConfig } from \"./encoder.ts\";\nexport { Producer } from \"./producer.ts\";\n"]}

package/stream/producer.d.ts

@@ -0,0 +1,18 @@
+import type * as Moq from "@norskvideo/moq-net";
+import { type ProducerConfig } from "./encoder";
+/**
+ * Publishes an ordered log of JSON records to a track, one record per frame in a single group.
+ *
+ * An {@link Encoder} that owns its track. When something else already owns the track, use the
+ * {@link Encoder} directly.
+ */
+export declare class Producer<T> {
+    #private;
+    /** Wrap a track to publish a record log into it. */
+    constructor(track: Moq.Track.Producer, config?: ProducerConfig);
+    /** Append one record to the log. */
+    append(value: T): void;
+    /** Finish the track, closing the group. */
+    finish(): void;
+}
+//# sourceMappingURL=producer.d.ts.map

package/stream/producer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.d.ts","sourceRoot":"","sources":["../../src/stream/producer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC;;IAOtB,oDAAoD;IACpD,YAAY,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAE,cAAmB,EAGjE;IAED,oCAAoC;IACpC,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAoBrB;IAED,2CAA2C;IAC3C,MAAM,IAAI,IAAI,CAIb;CACD"}

package/stream/producer.js

@@ -0,0 +1,49 @@
+/* @ts-self-types="./producer.d.ts" */
+import { Time } from "@norskvideo/moq-net";
+import { Encoder } from "./encoder.js";
+/**
+ * Publishes an ordered log of JSON records to a track, one record per frame in a single group.
+ *
+ * An {@link Encoder} that owns its track. When something else already owns the track, use the
+ * {@link Encoder} directly.
+ */
+export class Producer {
+    #track;
+    #encoder;
+    // The single group carrying the whole log, opened on the first append.
+    #group;
+    /** Wrap a track to publish a record log into it. */
+    constructor(track, config = {}) {
+        this.#track = track;
+        this.#encoder = new Encoder(config);
+    }
+    /** Append one record to the log. */
+    append(value) {
+        // Encode first, so a value that can't be serialized doesn't publish an empty group that
+        // subscribers would advance into and wait on. Opening the group afterwards is safe because
+        // the record stays uncommitted until the write lands.
+        const record = this.#encoder.encode(value);
+        try {
+            this.#group ??= this.#track.appendGroup();
+            this.#group.writeFrame({ payload: record.payload, timestamp: Time.Timestamp.now() });
+        }
+        catch (err) {
+            // The group is already visible on the track, so leaving it open would strand a subscriber
+            // that advanced into it. Closing it is also the group roll that recovery needs, so reset the
+            // encoder to finish it: the record never landed, and without the reset a compressed encoder
+            // refuses every later one even though the fresh group could carry it.
+            this.#group?.close();
+            this.#group = undefined;
+            this.#encoder.reset();
+            throw err;
+        }
+        record.commit();
+    }
+    /** Finish the track, closing the group. */
+    finish() {
+        this.#group?.close();
+        this.#group = undefined;
+        this.#track.close();
+    }
+}
+//# sourceMappingURL=producer.js.map

package/stream/producer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.js","sourceRoot":"","sources":["../../src/stream/producer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,OAAO,EAAuB,MAAM,cAAc,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IACpB,MAAM,CAAqB;IAC3B,QAAQ,CAAa;IAErB,uEAAuE;IACvE,MAAM,CAAsB;IAE5B,oDAAoD;IACpD,YAAY,KAAyB,EAAE,MAAM,GAAmB,EAAE;QACjE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,KAAQ;QACd,wFAAwF;QACxF,2FAA2F;QAC3F,sDAAsD;QACtD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,CAAC;YACJ,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACtF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,0FAA0F;YAC1F,6FAA6F;YAC7F,4FAA4F;YAC5F,sEAAsE;YACtE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,GAAG,CAAC;QACX,CAAC;QACD,MAAM,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IAED,2CAA2C;IAC3C,MAAM;QACL,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACD","sourcesContent":["import type * as Moq from \"@moq/net\";\nimport { Time } from \"@moq/net\";\n\nimport { Encoder, type ProducerConfig } from \"./encoder.ts\";\n\n/**\n * Publishes an ordered log of JSON records to a track, one record per frame in a single group.\n *\n * An {@link Encoder} that owns its track. When something else already owns the track, use the\n * {@link Encoder} directly.\n */\nexport class Producer<T> {\n\t#track: Moq.Track.Producer;\n\t#encoder: Encoder<T>;\n\n\t// The single group carrying the whole log, opened on the first append.\n\t#group?: Moq.Group.Producer;\n\n\t/** Wrap a track to publish a record log into it. */\n\tconstructor(track: Moq.Track.Producer, config: ProducerConfig = {}) {\n\t\tthis.#track = track;\n\t\tthis.#encoder = new Encoder(config);\n\t}\n\n\t/** Append one record to the log. */\n\tappend(value: T): void {\n\t\t// Encode first, so a value that can't be serialized doesn't publish an empty group that\n\t\t// subscribers would advance into and wait on. Opening the group afterwards is safe because\n\t\t// the record stays uncommitted until the write lands.\n\t\tconst record = this.#encoder.encode(value);\n\n\t\ttry {\n\t\t\tthis.#group ??= this.#track.appendGroup();\n\t\t\tthis.#group.writeFrame({ payload: record.payload, timestamp: Time.Timestamp.now() });\n\t\t} catch (err) {\n\t\t\t// The group is already visible on the track, so leaving it open would strand a subscriber\n\t\t\t// that advanced into it. Closing it is also the group roll that recovery needs, so reset the\n\t\t\t// encoder to finish it: the record never landed, and without the reset a compressed encoder\n\t\t\t// refuses every later one even though the fresh group could carry it.\n\t\t\tthis.#group?.close();\n\t\t\tthis.#group = undefined;\n\t\t\tthis.#encoder.reset();\n\t\t\tthrow err;\n\t\t}\n\t\trecord.commit();\n\t}\n\n\t/** Finish the track, closing the group. */\n\tfinish(): void {\n\t\tthis.#group?.close();\n\t\tthis.#group = undefined;\n\t\tthis.#track.close();\n\t}\n}\n"]}

package/window/consumer.d.ts

@@ -0,0 +1,26 @@
+import type * as Moq from "@norskvideo/moq-net";
+import { type ConsumerConfig, type Event } from "./decoder";
+/**
+ * Consumes a sliding window of JSON records from a track, yielding one event per change.
+ *
+ * A {@link Decoder} that owns its track: it reads groups, starts a cold DEFLATE window at each
+ * boundary, and turns each group's header into just the changes this reader has not been told about.
+ * When something else already owns the track, use the {@link Decoder} directly.
+ *
+ * Group rolls never surface. A publisher rolls for compression's sake, and a header restating the
+ * window yields nothing for records already delivered, so this reads as one continuous stream of
+ * {@link Event}s regardless of how the publisher framed them.
+ *
+ * @public
+ */
+export declare class Consumer<T> {
+    #private;
+    constructor(track: Moq.Track.Subscriber, config?: ConsumerConfig);
+    /** Absolute index of the oldest record in the window. */
+    get offset(): number;
+    /** Get the next event, or `undefined` once the track ends. */
+    next(): Promise<Event<T> | undefined>;
+    /** Iterate over events until the track ends. */
+    [Symbol.asyncIterator](): AsyncIterator<Event<T>>;
+}
+//# sourceMappingURL=consumer.d.ts.map

package/window/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../src/window/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,KAAK,cAAc,EAAW,KAAK,KAAK,EAAc,MAAM,cAAc,CAAC;AAEpF;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAQ,CAAC,CAAC;;IAQtB,YAAY,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAE,cAAmB,EAGnE;IAED,yDAAyD;IACzD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,8DAA8D;IAC9D,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAMpC;IA4BD,gDAAgD;IACzC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAMvD;CACD"}

package/window/consumer.js

@@ -0,0 +1,74 @@
+/* @ts-self-types="./consumer.d.ts" */
+import { Decoder } from "./decoder.js";
+/**
+ * Consumes a sliding window of JSON records from a track, yielding one event per change.
+ *
+ * A {@link Decoder} that owns its track: it reads groups, starts a cold DEFLATE window at each
+ * boundary, and turns each group's header into just the changes this reader has not been told about.
+ * When something else already owns the track, use the {@link Decoder} directly.
+ *
+ * Group rolls never surface. A publisher rolls for compression's sake, and a header restating the
+ * window yields nothing for records already delivered, so this reads as one continuous stream of
+ * {@link Event}s regardless of how the publisher framed them.
+ *
+ * @public
+ */
+export class Consumer {
+    #track;
+    #decoder;
+    #group;
+    #codec;
+    #reading = false;
+    constructor(track, config = {}) {
+        this.#track = track;
+        this.#decoder = new Decoder(config);
+    }
+    /** Absolute index of the oldest record in the window. */
+    get offset() {
+        return this.#decoder.offset;
+    }
+    /** Get the next event, or `undefined` once the track ends. */
+    next() {
+        if (this.#reading)
+            throw new Error("multiple calls to next not supported");
+        this.#reading = true;
+        return this.#read().finally(() => {
+            this.#reading = false;
+        });
+    }
+    async #read() {
+        for (;;) {
+            // Drain what the frames already decoded produced before reading more.
+            const event = this.#decoder.next();
+            if (event)
+                return event;
+            if (!this.#group) {
+                this.#group = await this.#track.nextGroup();
+                if (!this.#group)
+                    return undefined;
+                this.#codec = this.#decoder.group();
+            }
+            const frame = await this.#group.readFrame();
+            if (frame === undefined) {
+                // This group is exhausted. Wait for a later one, which restates the window; the stream
+                // ends only when the track does.
+                this.#group = undefined;
+                this.#codec = undefined;
+                continue;
+            }
+            if (!this.#codec)
+                throw new Error("an open MoQ group has a window codec");
+            this.#codec.decode(frame.payload);
+        }
+    }
+    /** Iterate over events until the track ends. */
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const event = await this.next();
+            if (event === undefined)
+                return;
+            yield event;
+        }
+    }
+}
+//# sourceMappingURL=consumer.js.map

package/window/consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.js","sourceRoot":"","sources":["../../src/window/consumer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuB,OAAO,EAA0B,MAAM,cAAc,CAAC;AAEpF;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,QAAQ;IACpB,MAAM,CAAuB;IAC7B,QAAQ,CAAa;IAErB,MAAM,CAAsB;IAC5B,MAAM,CAAS;IACf,QAAQ,GAAG,KAAK,CAAC;IAEjB,YAAY,KAA2B,EAAE,MAAM,GAAmB,EAAE;QACnE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,8DAA8D;IAC9D,IAAI;QACH,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACvB,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK;QACV,SAAS,CAAC;YACT,sEAAsE;YACtE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC;YAExB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBAClB,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBAC5C,IAAI,CAAC,IAAI,CAAC,MAAM;oBAAE,OAAO,SAAS,CAAC;gBACnC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACrC,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC5C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,uFAAuF;gBACvF,iCAAiC;gBACjC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;gBACxB,SAAS;YACV,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;YAC1E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;IACF,CAAC;IAED,gDAAgD;IAChD,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;CACD","sourcesContent":["import type * as Moq from \"@moq/net\";\n\nimport { type ConsumerConfig, Decoder, type Event, type Group } from \"./decoder.ts\";\n\n/**\n * Consumes a sliding window of JSON records from a track, yielding one event per change.\n *\n * A {@link Decoder} that owns its track: it reads groups, starts a cold DEFLATE window at each\n * boundary, and turns each group's header into just the changes this reader has not been told about.\n * When something else already owns the track, use the {@link Decoder} directly.\n *\n * Group rolls never surface. A publisher rolls for compression's sake, and a header restating the\n * window yields nothing for records already delivered, so this reads as one continuous stream of\n * {@link Event}s regardless of how the publisher framed them.\n *\n * @public\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#codec?: Group;\n\t#reading = false;\n\n\tconstructor(track: Moq.Track.Subscriber, config: ConsumerConfig = {}) {\n\t\tthis.#track = track;\n\t\tthis.#decoder = new Decoder(config);\n\t}\n\n\t/** Absolute index of the oldest record in the window. */\n\tget offset(): number {\n\t\treturn this.#decoder.offset;\n\t}\n\n\t/** Get the next event, or `undefined` once the track ends. */\n\tnext(): Promise<Event<T> | undefined> {\n\t\tif (this.#reading) throw new Error(\"multiple calls to next not supported\");\n\t\tthis.#reading = true;\n\t\treturn this.#read().finally(() => {\n\t\t\tthis.#reading = false;\n\t\t});\n\t}\n\n\tasync #read(): Promise<Event<T> | undefined> {\n\t\tfor (;;) {\n\t\t\t// Drain what the frames already decoded produced before reading more.\n\t\t\tconst event = this.#decoder.next();\n\t\t\tif (event) return event;\n\n\t\t\tif (!this.#group) {\n\t\t\t\tthis.#group = await this.#track.nextGroup();\n\t\t\t\tif (!this.#group) return undefined;\n\t\t\t\tthis.#codec = this.#decoder.group();\n\t\t\t}\n\n\t\t\tconst frame = await this.#group.readFrame();\n\t\t\tif (frame === undefined) {\n\t\t\t\t// This group is exhausted. Wait for a later one, which restates the window; the stream\n\t\t\t\t// ends only when the track does.\n\t\t\t\tthis.#group = undefined;\n\t\t\t\tthis.#codec = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (!this.#codec) throw new Error(\"an open MoQ group has a window codec\");\n\t\t\tthis.#codec.decode(frame.payload);\n\t\t}\n\t}\n\n\t/** Iterate over events until the track ends. */\n\tasync *[Symbol.asyncIterator](): AsyncIterator<Event<T>> {\n\t\tfor (;;) {\n\t\t\tconst event = await this.next();\n\t\t\tif (event === undefined) return;\n\t\t\tyield event;\n\t\t}\n\t}\n}\n"]}

package/window/decoder.d.ts

@@ -0,0 +1,57 @@
+/** Options for a {@link Decoder}, and so for the {@link Consumer} wrapping one. */
+export interface ConsumerConfig {
+    /** Read frames written with `ProducerConfig.compression` on. Defaults to `false`. */
+    compression?: boolean;
+}
+/**
+ * One change to the window, as the consumer sees it.
+ *
+ * A record is `push`ed when it first reaches this consumer. Contiguous spans are `pop`ped when they
+ * leave the window or `skip`ped when they were dropped before this consumer saw them.
+ */
+export type Event<T> = {
+    push: {
+        index: number;
+        value: T;
+    };
+} | {
+    pop: Span;
+} | {
+    skip: Span;
+};
+/** A half-open range of absolute record indices. */
+export interface Span {
+    /** First index in the span. */
+    start: number;
+    /** One past the last index in the span. */
+    end: number;
+}
+/** Decodes the frames in one MoQ group, requiring a header at frame zero. */
+export interface Group {
+    /** Decode the next frame in this group. */
+    decode(payload: Uint8Array): void;
+}
+/**
+ * Reconstructs window events from frame payloads.
+ *
+ * The track-free core of {@link Consumer}. It tracks indices, not contents: it knows where the
+ * window starts and how far it has delivered, which is all it needs to turn a header into the
+ * pushes, pops, and skips the reader has not already been told about.
+ *
+ * Group rolls are invisible here on purpose. A header restates the window, and this decoder emits
+ * only what is new, so a reader sees one continuous stream of edits no matter how often the
+ * publisher rolled for compression's sake.
+ *
+ * @public
+ */
+export declare class Decoder<T> {
+    #private;
+    constructor(config?: ConsumerConfig);
+    /** Create the decoder for one MoQ group. */
+    group(): Group;
+    /** Absolute index of the oldest record in the window. */
+    get offset(): number;
+    /** Take the next event produced by the frames decoded so far. */
+    next(): Event<T> | undefined;
+}
+//# sourceMappingURL=decoder.d.ts.map

package/window/decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.d.ts","sourceRoot":"","sources":["../../src/window/decoder.ts"],"names":[],"mappings":"AAgBA,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC9B,qFAAqF;IACrF,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAI9F,oDAAoD;AACpD,MAAM,WAAW,IAAI;IACpB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IAEd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,6EAA6E;AAC7E,MAAM,WAAW,KAAK;IACrB,2CAA2C;IAC3C,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO,CAAC,CAAC;;IAarB,YAAY,MAAM,GAAE,cAAmB,EAEtC;IAED,4CAA4C;IAC5C,KAAK,IAAI,KAAK,CAkCb;IAED,yDAAyD;IACzD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,iEAAiE;IACjE,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAgB3B;CA4ED"}

package/window/decoder.js

@@ -0,0 +1,169 @@
+/* @ts-self-types="./decoder.d.ts" */
+import { Decoder as Flate } from "@norskvideo/moq-flate";
+function object(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+function index(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${label} must be a nonnegative safe integer`);
+    }
+    return value;
+}
+/**
+ * Reconstructs window events from frame payloads.
+ *
+ * The track-free core of {@link Consumer}. It tracks indices, not contents: it knows where the
+ * window starts and how far it has delivered, which is all it needs to turn a header into the
+ * pushes, pops, and skips the reader has not already been told about.
+ *
+ * Group rolls are invisible here on purpose. A header restates the window, and this decoder emits
+ * only what is new, so a reader sees one continuous stream of edits no matter how often the
+ * publisher rolled for compression's sake.
+ *
+ * @public
+ */
+export class Decoder {
+    #compress;
+    #generation = 0;
+    // Absolute index of the window's front, once a group header has positioned us.
+    #front = 0;
+    #len = 0;
+    // Next index to deliver, or undefined before the first header. A fresh consumer adopts the first
+    // header's offset rather than skipping everything that came before it.
+    #delivered;
+    #events = [];
+    #nextEvent = 0;
+    constructor(config = {}) {
+        this.#compress = config.compression ?? false;
+    }
+    /** Create the decoder for one MoQ group. */
+    group() {
+        const generation = ++this.#generation;
+        let flate;
+        let positioned = false;
+        return {
+            decode: (payload) => {
+                if (generation !== this.#generation)
+                    throw new Error("stale window group");
+                if (this.#compress)
+                    flate ??= new Flate();
+                const bytes = flate ? flate.frame(payload) : payload;
+                const frame = object(JSON.parse(new TextDecoder().decode(bytes)), "window frame");
+                if (!positioned) {
+                    if (!Array.isArray(frame.records))
+                        throw new Error("window header records must be an array");
+                    this.#applyHeader(index(frame.offset, "window offset"), frame.records);
+                    positioned = true;
+                    return;
+                }
+                const keys = Object.keys(frame);
+                if (keys.length !== 1)
+                    throw new Error("window op must contain exactly one operation");
+                switch (keys[0]) {
+                    case "push":
+                        this.#applyPush(frame.push);
+                        break;
+                    case "pop":
+                        this.#applyPop(index(frame.pop, "window pop count"));
+                        break;
+                    default:
+                        throw new Error("unrecognized window op");
+                }
+            },
+        };
+    }
+    /** Absolute index of the oldest record in the window. */
+    get offset() {
+        return this.#front;
+    }
+    /** Take the next event produced by the frames decoded so far. */
+    next() {
+        const queued = this.#events[this.#nextEvent];
+        if (!queued) {
+            this.#clearEvents();
+            return undefined;
+        }
+        if ("records" in queued) {
+            const next = queued.next++;
+            const event = { push: { index: queued.offset + next, value: queued.records[next] } };
+            if (queued.next >= queued.records.length)
+                this.#advanceEvent();
+            return event;
+        }
+        this.#advanceEvent();
+        return queued;
+    }
+    #advanceEvent() {
+        this.#nextEvent += 1;
+        if (this.#nextEvent >= this.#events.length)
+            this.#clearEvents();
+    }
+    #clearEvents() {
+        this.#events = [];
+        this.#nextEvent = 0;
+    }
+    /** The window is exactly these records. Report what this reader missed, then what is new. */
+    #applyHeader(offset, records) {
+        const end = offset + records.length;
+        if (!Number.isSafeInteger(end))
+            throw new Error("window range exceeds the safe integer range");
+        let delivered = this.#delivered;
+        if (delivered === undefined) {
+            // First position: adopt the publisher's offset rather than skipping all of history.
+            delivered = offset;
+        }
+        else {
+            if (offset < this.#front || end < delivered)
+                throw new Error("window header moved backwards");
+            // Records that left the window while we were away. Those we had delivered are pops; those we
+            // never saw are skips. Keep each gap compact: the offset is untrusted and may jump by far
+            // more indices than a consumer could materialize individually.
+            this.#range("pop", this.#front, Math.min(delivered, offset));
+            this.#range("skip", delivered, offset);
+        }
+        // Keep the unseen tail as one batch and materialize each push only when the caller asks for it.
+        const next = Math.max(delivered - offset, 0);
+        if (next < records.length) {
+            this.#events.push({ offset, records, next });
+        }
+        this.#front = offset;
+        this.#len = end - offset;
+        this.#delivered = Math.max(delivered, end);
+    }
+    /** One record joined the back. */
+    #applyPush(value) {
+        if (this.#delivered === undefined)
+            throw new Error("window op before group header");
+        const index = this.#front + this.#len;
+        if (!Number.isSafeInteger(index + 1))
+            throw new Error("window range exceeds the safe integer range");
+        this.#len += 1;
+        if (index >= this.#delivered) {
+            this.#events.push({ push: { index, value } });
+            this.#delivered = index + 1;
+        }
+    }
+    /** Records left the front. */
+    #applyPop(count) {
+        if (this.#delivered === undefined)
+            throw new Error("window op before group header");
+        if (count > this.#len) {
+            throw new Error(`pop of ${count} exceeds the ${this.#len} record(s) in the window`);
+        }
+        const end = this.#front + count;
+        this.#range("pop", this.#front, Math.min(this.#delivered, end));
+        this.#range("skip", Math.max(this.#delivered, this.#front), end);
+        this.#front = end;
+        this.#len -= count;
+        this.#delivered = Math.max(this.#delivered, this.#front);
+    }
+    #range(kind, start, end) {
+        if (start >= end)
+            return;
+        this.#events.push(kind === "pop" ? { pop: { start, end } } : { skip: { start, end } });
+    }
+}
+//# sourceMappingURL=decoder.js.map

package/window/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../../src/window/decoder.ts"],"names":[],"mappings":"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","sourcesContent":["import { Decoder as Flate } from \"@moq/flate\";\n\nfunction object(value: unknown, label: string): Record<string, unknown> {\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n\t\tthrow new Error(`${label} must be an object`);\n\t}\n\treturn value as Record<string, unknown>;\n}\n\nfunction index(value: unknown, label: string): number {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < 0) {\n\t\tthrow new Error(`${label} must be a nonnegative safe integer`);\n\t}\n\treturn value;\n}\n\n/** Options for a {@link Decoder}, and so for the {@link Consumer} wrapping one. */\nexport interface ConsumerConfig {\n\t/** Read frames written with `ProducerConfig.compression` on. Defaults to `false`. */\n\tcompression?: boolean;\n}\n\n/**\n * One change to the window, as the consumer sees it.\n *\n * A record is `push`ed when it first reaches this consumer. Contiguous spans are `pop`ped when they\n * leave the window or `skip`ped when they were dropped before this consumer saw them.\n */\nexport type Event<T> = { push: { index: number; value: T } } | { pop: Span } | { skip: Span };\n\ntype Queued<T> = Event<T> | { offset: number; records: T[]; next: number };\n\n/** A half-open range of absolute record indices. */\nexport interface Span {\n\t/** First index in the span. */\n\tstart: number;\n\n\t/** One past the last index in the span. */\n\tend: number;\n}\n\n/** Decodes the frames in one MoQ group, requiring a header at frame zero. */\nexport interface Group {\n\t/** Decode the next frame in this group. */\n\tdecode(payload: Uint8Array): void;\n}\n\n/**\n * Reconstructs window events from frame payloads.\n *\n * The track-free core of {@link Consumer}. It tracks indices, not contents: it knows where the\n * window starts and how far it has delivered, which is all it needs to turn a header into the\n * pushes, pops, and skips the reader has not already been told about.\n *\n * Group rolls are invisible here on purpose. A header restates the window, and this decoder emits\n * only what is new, so a reader sees one continuous stream of edits no matter how often the\n * publisher rolled for compression's sake.\n *\n * @public\n */\nexport class Decoder<T> {\n\t#compress: boolean;\n\t#generation = 0;\n\n\t// Absolute index of the window's front, once a group header has positioned us.\n\t#front = 0;\n\t#len = 0;\n\t// Next index to deliver, or undefined before the first header. A fresh consumer adopts the first\n\t// header's offset rather than skipping everything that came before it.\n\t#delivered?: number;\n\t#events: Queued<T>[] = [];\n\t#nextEvent = 0;\n\n\tconstructor(config: ConsumerConfig = {}) {\n\t\tthis.#compress = config.compression ?? false;\n\t}\n\n\t/** Create the decoder for one MoQ group. */\n\tgroup(): Group {\n\t\tconst generation = ++this.#generation;\n\t\tlet flate: Flate | undefined;\n\t\tlet positioned = false;\n\n\t\treturn {\n\t\t\tdecode: (payload) => {\n\t\t\t\tif (generation !== this.#generation) throw new Error(\"stale window group\");\n\t\t\t\tif (this.#compress) flate ??= new Flate();\n\t\t\t\tconst bytes = flate ? flate.frame(payload) : payload;\n\t\t\t\tconst frame = object(JSON.parse(new TextDecoder().decode(bytes)) as unknown, \"window frame\");\n\n\t\t\t\tif (!positioned) {\n\t\t\t\t\tif (!Array.isArray(frame.records)) throw new Error(\"window header records must be an array\");\n\t\t\t\t\tthis.#applyHeader(index(frame.offset, \"window offset\"), frame.records as T[]);\n\t\t\t\t\tpositioned = true;\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tconst keys = Object.keys(frame);\n\t\t\t\tif (keys.length !== 1) throw new Error(\"window op must contain exactly one operation\");\n\n\t\t\t\tswitch (keys[0]) {\n\t\t\t\t\tcase \"push\":\n\t\t\t\t\t\tthis.#applyPush(frame.push as T);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"pop\":\n\t\t\t\t\t\tthis.#applyPop(index(frame.pop, \"window pop count\"));\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tdefault:\n\t\t\t\t\t\tthrow new Error(\"unrecognized window op\");\n\t\t\t\t}\n\t\t\t},\n\t\t};\n\t}\n\n\t/** Absolute index of the oldest record in the window. */\n\tget offset(): number {\n\t\treturn this.#front;\n\t}\n\n\t/** Take the next event produced by the frames decoded so far. */\n\tnext(): Event<T> | undefined {\n\t\tconst queued = this.#events[this.#nextEvent];\n\t\tif (!queued) {\n\t\t\tthis.#clearEvents();\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (\"records\" in queued) {\n\t\t\tconst next = queued.next++;\n\t\t\tconst event = { push: { index: queued.offset + next, value: queued.records[next] as T } };\n\t\t\tif (queued.next >= queued.records.length) this.#advanceEvent();\n\t\t\treturn event;\n\t\t}\n\n\t\tthis.#advanceEvent();\n\t\treturn queued;\n\t}\n\n\t#advanceEvent(): void {\n\t\tthis.#nextEvent += 1;\n\t\tif (this.#nextEvent >= this.#events.length) this.#clearEvents();\n\t}\n\n\t#clearEvents(): void {\n\t\tthis.#events = [];\n\t\tthis.#nextEvent = 0;\n\t}\n\n\t/** The window is exactly these records. Report what this reader missed, then what is new. */\n\t#applyHeader(offset: number, records: T[]): void {\n\t\tconst end = offset + records.length;\n\t\tif (!Number.isSafeInteger(end)) throw new Error(\"window range exceeds the safe integer range\");\n\t\tlet delivered = this.#delivered;\n\n\t\tif (delivered === undefined) {\n\t\t\t// First position: adopt the publisher's offset rather than skipping all of history.\n\t\t\tdelivered = offset;\n\t\t} else {\n\t\t\tif (offset < this.#front || end < delivered) throw new Error(\"window header moved backwards\");\n\n\t\t\t// Records that left the window while we were away. Those we had delivered are pops; those we\n\t\t\t// never saw are skips. Keep each gap compact: the offset is untrusted and may jump by far\n\t\t\t// more indices than a consumer could materialize individually.\n\t\t\tthis.#range(\"pop\", this.#front, Math.min(delivered, offset));\n\t\t\tthis.#range(\"skip\", delivered, offset);\n\t\t}\n\n\t\t// Keep the unseen tail as one batch and materialize each push only when the caller asks for it.\n\t\tconst next = Math.max(delivered - offset, 0);\n\t\tif (next < records.length) {\n\t\t\tthis.#events.push({ offset, records, next });\n\t\t}\n\n\t\tthis.#front = offset;\n\t\tthis.#len = end - offset;\n\t\tthis.#delivered = Math.max(delivered, end);\n\t}\n\n\t/** One record joined the back. */\n\t#applyPush(value: T): void {\n\t\tif (this.#delivered === undefined) throw new Error(\"window op before group header\");\n\n\t\tconst index = this.#front + this.#len;\n\t\tif (!Number.isSafeInteger(index + 1)) throw new Error(\"window range exceeds the safe integer range\");\n\t\tthis.#len += 1;\n\n\t\tif (index >= this.#delivered) {\n\t\t\tthis.#events.push({ push: { index, value } });\n\t\t\tthis.#delivered = index + 1;\n\t\t}\n\t}\n\n\t/** Records left the front. */\n\t#applyPop(count: number): void {\n\t\tif (this.#delivered === undefined) throw new Error(\"window op before group header\");\n\t\tif (count > this.#len) {\n\t\t\tthrow new Error(`pop of ${count} exceeds the ${this.#len} record(s) in the window`);\n\t\t}\n\n\t\tconst end = this.#front + count;\n\t\tthis.#range(\"pop\", this.#front, Math.min(this.#delivered, end));\n\t\tthis.#range(\"skip\", Math.max(this.#delivered, this.#front), end);\n\n\t\tthis.#front = end;\n\t\tthis.#len -= count;\n\t\tthis.#delivered = Math.max(this.#delivered, this.#front);\n\t}\n\n\t#range(kind: \"pop\" | \"skip\", start: number, end: number): void {\n\t\tif (start >= end) return;\n\t\tthis.#events.push(kind === \"pop\" ? { pop: { start, end } } : { skip: { start, end } });\n\t}\n}\n"]}

package/window/encoder.d.ts

@@ -0,0 +1,72 @@
+/** Op ratio used when {@link ProducerConfig.opRatio} is left unset. */
+export declare const DEFAULT_OP_RATIO = 8;
+/** Options shared by an {@link Encoder} and the {@link Producer} that wraps one. */
+export interface ProducerConfig {
+    /**
+     * How much the ops in a group may cost before a fresh group is emitted.
+     *
+     * A new group opens once the pushes and pops *already written* exceed `opRatio` times the size of
+     * the group's header frame. The pending op is excluded, so the one that tips the group over budget
+     * still lands. `0` disables ops entirely, so every edit is its own single-frame group.
+     *
+     * The window's counterpart to Snapshot's `deltaRatio`. Defaults to `8`.
+     */
+    opRatio?: number;
+    /**
+     * Compress each group as one sync-flushed `deflate-raw` stream, so every op reuses the header and
+     * the ops before it as context. A {@link Decoder} reading the frames must set the same flag.
+     * Defaults to `false`.
+     */
+    compression?: boolean;
+}
+/** One encoded frame, and the group boundary it implies. */
+export interface Encoded {
+    /** The frame payload. */
+    payload: Uint8Array;
+    /**
+     * Whether this frame is a group header, which must open a new group.
+     *
+     * The encoder decides this, never the caller: the op budget and the frame cap force a new group
+     * independently of which edit was requested.
+     */
+    keyframe: boolean;
+}
+/**
+ * An encoded frame the caller has not yet acknowledged writing.
+ *
+ * Write the frame, then {@link commit}. The edit is staged until commit, so leaving the frame
+ * uncommitted keeps the window unchanged and makes the next frame open a new group.
+ */
+export interface Pending extends Encoded {
+    /** Acknowledge that the frame reached the wire, applying its edit to the retained window. */
+    commit(): void;
+}
+/**
+ * Encodes window edits into frame payloads, deciding where the group boundaries fall.
+ *
+ * The track-free core of {@link Producer}. It owns the retained window, so it can restate it
+ * whenever a group rolls; that restatement is the whole point of the mode, and is what an
+ * append-only log cannot do.
+ *
+ * @public
+ */
+export declare class Encoder<T> {
+    #private;
+    constructor(config?: ProducerConfig);
+    /** The retained window, oldest first. */
+    get window(): T[];
+    /** Absolute index of the oldest retained record. */
+    get offset(): number;
+    /** Absolute index the next pushed record will take. */
+    get end(): number;
+    /** Append one record to the back of the window. */
+    push(value: T): Pending;
+    /**
+     * Drop `count` records from the front of the window.
+     *
+     * Returns `undefined` when there is nothing to drop, so a caller can trim unconditionally.
+     * Clamped to what the window holds.
+     */
+    pop(count: number): Pending | undefined;
+}
+//# sourceMappingURL=encoder.d.ts.map

package/window/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/window/encoder.ts"],"names":[],"mappings":"AAMA,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAIlC,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,OAAO;IACvB,yBAAyB;IACzB,OAAO,EAAE,UAAU,CAAC;IAEpB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACvC,6FAA6F;IAC7F,MAAM,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO,CAAC,CAAC;;IAwBrB,YAAY,MAAM,GAAE,cAAmB,EAMtC;IAED,yCAAyC;IACzC,IAAI,MAAM,IAAI,CAAC,EAAE,CAEhB;IAED,oDAAoD;IACpD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,uDAAuD;IACvD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAaD,mDAAmD;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAmBtB;IAED;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAkBtC;CAiFD"}