@moqtap/trace 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 moqtap
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 moqtap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,82 +21,82 @@ npm install @moqtap/trace @moqtap/codec
 ### Recording a session
 
 ```typescript
-import { createRecorder, writeMoqtrace } from '@moqtap/trace';
-import { createDraft14SessionState } from '@moqtap/codec/draft14/session';
+import { createRecorder, writeMoqtrace } from '@moqtap/trace'
+import { createDraft17SessionState } from '@moqtap/codec/draft17/session'
 
 const recorder = createRecorder({
-  protocol: 'moq-transport-14',
+  protocol: 'moq-transport-17',
   perspective: 'client',
   detail: 'control',
-});
+})
 
 // Wrap a session to auto-capture control messages and state transitions
-const session = createDraft14SessionState({ codec: { draft: 'draft-ietf-moq-transport-14' }, role: 'client' });
-const traced = recorder.wrapSession(session);
+const session = createDraft17SessionState('client')
+const traced = recorder.wrapSession(session)
 
 // Use `traced` instead of `session` — all send/receive calls are recorded
-traced.send(clientSetupMessage);
-traced.receive(serverSetupMessage);
+traced.send(setupMessage)
+traced.receive(setupMessage)
 
 // Manually record events the session layer doesn't see
-recorder.recordStreamOpened(4n, 0, 0); // outgoing subgroup stream
-recorder.annotate('connected', { relay: 'cdn.example.com' });
+recorder.recordStreamOpened(4n, 0, 0) // outgoing subgroup stream
+recorder.annotate('connected', { relay: 'cdn.example.com' })
 
 // Finalize and serialize
-const trace = recorder.finalize();
-const bytes = writeMoqtrace(trace); // → Uint8Array (.moqtrace binary)
+const trace = recorder.finalize()
+const bytes = writeMoqtrace(trace) // → Uint8Array (.moqtrace binary)
 ```
 
 ### Reading a trace file
 
 ```typescript
-import { readMoqtrace, readMoqtraceHeader } from '@moqtap/trace';
+import { readMoqtrace, readMoqtraceHeader } from '@moqtap/trace'
 
 // Quick metadata peek (no event parsing)
-const header = readMoqtraceHeader(bytes);
-console.log(header.protocol);   // "moq-transport-14"
-console.log(header.perspective); // "client"
-console.log(header.detail);     // "control"
+const header = readMoqtraceHeader(bytes)
+console.log(header.protocol) // "moq-transport-17"
+console.log(header.perspective) // "client"
+console.log(header.detail) // "control"
 
 // Full parse
-const trace = readMoqtrace(bytes);
+const trace = readMoqtrace(bytes)
 for (const event of trace.events) {
-  console.log(event.type, event.timestamp);
+  console.log(event.type, event.timestamp)
 }
 ```
 
 ### Streaming writer (for large traces)
 
 ```typescript
-import { createMoqtraceWriter } from '@moqtap/trace';
+import { createMoqtraceWriter } from '@moqtap/trace'
 
-const writer = createMoqtraceWriter(header);
-outputStream.write(writer.preamble());
+const writer = createMoqtraceWriter(header)
+outputStream.write(writer.preamble())
 
 for (const event of events) {
-  outputStream.write(writer.writeEvent(event));
+  outputStream.write(writer.writeEvent(event))
 }
 ```
 
 ## Detail Levels
 
-| Level | What's recorded |
-|---|---|
-| `control` | Control messages only (setup, subscribe, publish, goaway) |
-| `headers` | + data stream headers (subgroup/fetch, object metadata) |
-| `headers+sizes` | + payload byte lengths |
-| `headers+data` | + full payload bytes |
-| `full` | + raw wire bytes (pre-decode) |
+| Level           | What's recorded                                           |
+| --------------- | --------------------------------------------------------- |
+| `control`       | Control messages only (setup, subscribe, publish, goaway) |
+| `headers`       | + data stream headers (subgroup/fetch, object metadata)   |
+| `headers+sizes` | + payload byte lengths                                    |
+| `headers+data`  | + full payload bytes                                      |
+| `full`          | + raw wire bytes (pre-decode)                             |
 
 ## JSON Export
 
 For human-readable debugging (not lossless — bigint/Uint8Array become strings):
 
 ```typescript
-import { traceToJSON } from '@moqtap/trace';
+import { traceToJSON } from '@moqtap/trace'
 
-const json = traceToJSON(trace);
-console.log(json);
+const json = traceToJSON(trace)
+console.log(json)
 ```
 
 ## File Format

package/dist/index.cjs

@@ -4,14 +4,14 @@ var MAGIC = new Uint8Array([77, 79, 81, 84, 82, 65, 67, 69]);
 var FORMAT_VERSION = 1;
 var PREAMBLE_SIZE = 16;
 var EVENT_TYPE_TO_INT = {
-  "control": 0,
+  control: 0,
   "stream-opened": 1,
   "stream-closed": 2,
   "object-header": 3,
   "object-payload": 4,
   "state-change": 5,
-  "error": 6,
-  "annotation": 7
+  error: 6,
+  annotation: 7
 };
 var INT_TO_EVENT_TYPE = {
   0: "control",
@@ -279,13 +279,30 @@ function createMoqtraceWriter(header) {
   };
 }
 
+// src/json.ts
+function traceToJSON(trace) {
+  return JSON.stringify(
+    trace,
+    (_key, value) => {
+      if (typeof value === "bigint") {
+        return `0x${value.toString(16)}`;
+      }
+      if (value instanceof Uint8Array) {
+        return Array.from(value).map((b) => b.toString(16).padStart(2, "0")).join("");
+      }
+      return value;
+    },
+    2
+  );
+}
+
 // src/recorder.ts
 var DETAIL_RANK = {
-  "control": 0,
-  "headers": 1,
+  control: 0,
+  headers: 1,
   "headers+sizes": 2,
   "headers+data": 3,
-  "full": 4
+  full: 4
 };
 function createRecorder(options) {
   const detail = options.detail;
@@ -385,7 +402,7 @@ function createRecorder(options) {
     wrapSession,
     record: addEvent,
     recordStreamOpened(streamId, direction, streamType) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "stream-opened",
         seq: nextSeq(),
@@ -396,7 +413,7 @@ function createRecorder(options) {
       });
     },
     recordStreamClosed(streamId, errorCode = 0) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "stream-closed",
         seq: nextSeq(),
@@ -406,7 +423,7 @@ function createRecorder(options) {
       });
     },
     recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
         seq: nextSeq(),
@@ -471,19 +488,6 @@ function createRecorder(options) {
   };
 }
 
-// src/json.ts
-function traceToJSON(trace) {
-  return JSON.stringify(trace, (_key, value) => {
-    if (typeof value === "bigint") {
-      return `0x${value.toString(16)}`;
-    }
-    if (value instanceof Uint8Array) {
-      return Array.from(value).map((b) => b.toString(16).padStart(2, "0")).join("");
-    }
-    return value;
-  }, 2);
-}
-
 
 
 

package/dist/index.d.cts

@@ -109,9 +109,21 @@ interface MoqtraceWriter {
 }
 declare function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter;
 
+/**
+ * Serialize a trace to human-readable JSON.
+ *
+ * Handles bigint → hex string and Uint8Array → hex string.
+ * This is a one-way export for human inspection and debugging.
+ * For lossless round-tripping, use the binary .moqtrace format
+ * (`writeMoqtrace` / `readMoqtrace`).
+ */
+declare function traceToJSON(trace: Trace): string;
+
 interface TraceRecorder {
     /** Wrap a SessionState to auto-record control messages and state changes. */
-    wrapSession(session: SessionState): SessionState;
+    wrapSession<M extends {
+        type: string;
+    }, T extends string>(session: SessionState<M, T>): SessionState<M, T>;
     /** Record an arbitrary event manually. */
     record(event: TraceEvent): void;
     /** Record a stream-opened event. Ignored at 'control' detail level. */
@@ -133,14 +145,4 @@ interface TraceRecorder {
 }
 declare function createRecorder(options: RecorderOptions): TraceRecorder;
 
-/**
- * Serialize a trace to human-readable JSON.
- *
- * Handles bigint → hex string and Uint8Array → hex string.
- * This is a one-way export for human inspection and debugging.
- * For lossless round-tripping, use the binary .moqtrace format
- * (`writeMoqtrace` / `readMoqtrace`).
- */
-declare function traceToJSON(trace: Trace): string;
-
 export { type AnnotationEvent, type ControlMessageEvent, type DetailLevel, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type Perspective, type RecorderOptions, type StateChangeEvent, type StreamClosedEvent, type StreamOpenedEvent, type Trace, type TraceErrorEvent, type TraceEvent, type TraceHeader, type TraceRecorder, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, traceToJSON, writeMoqtrace };

package/dist/index.d.ts

@@ -109,9 +109,21 @@ interface MoqtraceWriter {
 }
 declare function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter;
 
+/**
+ * Serialize a trace to human-readable JSON.
+ *
+ * Handles bigint → hex string and Uint8Array → hex string.
+ * This is a one-way export for human inspection and debugging.
+ * For lossless round-tripping, use the binary .moqtrace format
+ * (`writeMoqtrace` / `readMoqtrace`).
+ */
+declare function traceToJSON(trace: Trace): string;
+
 interface TraceRecorder {
     /** Wrap a SessionState to auto-record control messages and state changes. */
-    wrapSession(session: SessionState): SessionState;
+    wrapSession<M extends {
+        type: string;
+    }, T extends string>(session: SessionState<M, T>): SessionState<M, T>;
     /** Record an arbitrary event manually. */
     record(event: TraceEvent): void;
     /** Record a stream-opened event. Ignored at 'control' detail level. */
@@ -133,14 +145,4 @@ interface TraceRecorder {
 }
 declare function createRecorder(options: RecorderOptions): TraceRecorder;
 
-/**
- * Serialize a trace to human-readable JSON.
- *
- * Handles bigint → hex string and Uint8Array → hex string.
- * This is a one-way export for human inspection and debugging.
- * For lossless round-tripping, use the binary .moqtrace format
- * (`writeMoqtrace` / `readMoqtrace`).
- */
-declare function traceToJSON(trace: Trace): string;
-
 export { type AnnotationEvent, type ControlMessageEvent, type DetailLevel, type MoqtraceWriter, type ObjectHeaderEvent, type ObjectPayloadEvent, type Perspective, type RecorderOptions, type StateChangeEvent, type StreamClosedEvent, type StreamOpenedEvent, type Trace, type TraceErrorEvent, type TraceEvent, type TraceHeader, type TraceRecorder, createMoqtraceWriter, createRecorder, readMoqtrace, readMoqtraceHeader, traceToJSON, writeMoqtrace };

package/dist/index.js

@@ -1,17 +1,17 @@
 // src/binary.ts
-import { encode, decode, decodeMultiple } from "cbor-x";
+import { decode, decodeMultiple, encode } from "cbor-x";
 var MAGIC = new Uint8Array([77, 79, 81, 84, 82, 65, 67, 69]);
 var FORMAT_VERSION = 1;
 var PREAMBLE_SIZE = 16;
 var EVENT_TYPE_TO_INT = {
-  "control": 0,
+  control: 0,
   "stream-opened": 1,
   "stream-closed": 2,
   "object-header": 3,
   "object-payload": 4,
   "state-change": 5,
-  "error": 6,
-  "annotation": 7
+  error: 6,
+  annotation: 7
 };
 var INT_TO_EVENT_TYPE = {
   0: "control",
@@ -279,13 +279,30 @@ function createMoqtraceWriter(header) {
   };
 }
 
+// src/json.ts
+function traceToJSON(trace) {
+  return JSON.stringify(
+    trace,
+    (_key, value) => {
+      if (typeof value === "bigint") {
+        return `0x${value.toString(16)}`;
+      }
+      if (value instanceof Uint8Array) {
+        return Array.from(value).map((b) => b.toString(16).padStart(2, "0")).join("");
+      }
+      return value;
+    },
+    2
+  );
+}
+
 // src/recorder.ts
 var DETAIL_RANK = {
-  "control": 0,
-  "headers": 1,
+  control: 0,
+  headers: 1,
   "headers+sizes": 2,
   "headers+data": 3,
-  "full": 4
+  full: 4
 };
 function createRecorder(options) {
   const detail = options.detail;
@@ -385,7 +402,7 @@ function createRecorder(options) {
     wrapSession,
     record: addEvent,
     recordStreamOpened(streamId, direction, streamType) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "stream-opened",
         seq: nextSeq(),
@@ -396,7 +413,7 @@ function createRecorder(options) {
       });
     },
     recordStreamClosed(streamId, errorCode = 0) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "stream-closed",
         seq: nextSeq(),
@@ -406,7 +423,7 @@ function createRecorder(options) {
       });
     },
     recordObjectHeader(streamId, groupId, objectId, publisherPriority, objectStatus) {
-      if (detailRank < DETAIL_RANK["headers"]) return;
+      if (detailRank < DETAIL_RANK.headers) return;
       addEvent({
         type: "object-header",
         seq: nextSeq(),
@@ -470,19 +487,6 @@ function createRecorder(options) {
     }
   };
 }
-
-// src/json.ts
-function traceToJSON(trace) {
-  return JSON.stringify(trace, (_key, value) => {
-    if (typeof value === "bigint") {
-      return `0x${value.toString(16)}`;
-    }
-    if (value instanceof Uint8Array) {
-      return Array.from(value).map((b) => b.toString(16).padStart(2, "0")).join("");
-    }
-    return value;
-  }, 2);
-}
 export {
   createMoqtraceWriter,
   createRecorder,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@moqtap/trace",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MoQT session trace format — record, serialize, and analyze .moqtrace files",
   "type": "module",
   "license": "MIT",
   "author": "moqtap",
   "repository": {
     "type": "git",
-    "url": "https://github.com/moqtap/moqtap-js.git",
+    "url": "git+https://github.com/moqtap/moqtap-js.git",
     "directory": "packages/trace"
   },
   "homepage": "https://github.com/moqtap/moqtap-js/tree/master/packages/trace",
@@ -32,7 +32,7 @@
     ".": {
       "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
+      "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
   },