@moqtap/trace 0.1.0 → 0.1.2

package/src/binary.ts

@@ -1,27 +1,21 @@
-import { encode, decode, decodeMultiple } from 'cbor-x';
-import type {
-  Trace,
-  TraceHeader,
-  TraceEvent,
-  DetailLevel,
-  Perspective,
-} from './types.js';
-
-const MAGIC = new Uint8Array([0x4d, 0x4f, 0x51, 0x54, 0x52, 0x41, 0x43, 0x45]); // "MOQTRACE"
-const FORMAT_VERSION = 1;
-const PREAMBLE_SIZE = 16; // 8 magic + 4 version + 4 header length
+import { decode, decodeMultiple, encode } from 'cbor-x'
+import type { DetailLevel, Perspective, Trace, TraceEvent, TraceHeader } from './types.js'
+
+const MAGIC = new Uint8Array([0x4d, 0x4f, 0x51, 0x54, 0x52, 0x41, 0x43, 0x45]) // "MOQTRACE"
+const FORMAT_VERSION = 1
+const PREAMBLE_SIZE = 16 // 8 magic + 4 version + 4 header length
 
 // Event type string ↔ integer mapping
 const EVENT_TYPE_TO_INT: Record<TraceEvent['type'], number> = {
-  '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,
+}
 
 const INT_TO_EVENT_TYPE: Record<number, TraceEvent['type']> = {
   0: 'control',
@@ -32,7 +26,7 @@ const INT_TO_EVENT_TYPE: Record<number, TraceEvent['type']> = {
   5: 'state-change',
   6: 'error',
   7: 'annotation',
-};
+}
 
 // --- Header serialization ---
 
@@ -42,14 +36,14 @@ function headerToCbor(header: TraceHeader): Record<string, unknown> {
     perspective: header.perspective,
     detail: header.detail,
     startTime: header.startTime,
-  };
-  if (header.endTime != null) map.endTime = header.endTime;
-  if (header.transport != null) map.transport = header.transport;
-  if (header.source != null) map.source = header.source;
-  if (header.endpoint != null) map.endpoint = header.endpoint;
-  if (header.sessionId != null) map.sessionId = header.sessionId;
-  if (header.custom != null) map.custom = header.custom;
-  return map;
+  }
+  if (header.endTime != null) map.endTime = header.endTime
+  if (header.transport != null) map.transport = header.transport
+  if (header.source != null) map.source = header.source
+  if (header.endpoint != null) map.endpoint = header.endpoint
+  if (header.sessionId != null) map.sessionId = header.sessionId
+  if (header.custom != null) map.custom = header.custom
+  return map
 }
 
 function cborToHeader(obj: Record<string, unknown>): TraceHeader {
@@ -64,7 +58,7 @@ function cborToHeader(obj: Record<string, unknown>): TraceHeader {
     ...(obj.endpoint != null ? { endpoint: obj.endpoint as string } : {}),
     ...(obj.sessionId != null ? { sessionId: obj.sessionId as string } : {}),
     ...(obj.custom != null ? { custom: obj.custom as Record<string, unknown> } : {}),
-  };
+  }
 }
 
 // --- Event serialization ---
@@ -74,65 +68,65 @@ function eventToCbor(event: TraceEvent): Record<string, unknown> {
     n: event.seq,
     t: event.timestamp,
     e: EVENT_TYPE_TO_INT[event.type],
-  };
+  }
 
   switch (event.type) {
     case 'control': {
-      base.d = event.direction;
-      base.mt = event.messageType;
-      base.msg = event.message;
-      if (event.raw != null) base.raw = event.raw;
-      break;
+      base.d = event.direction
+      base.mt = event.messageType
+      base.msg = event.message
+      if (event.raw != null) base.raw = event.raw
+      break
     }
     case 'stream-opened': {
-      base.sid = event.streamId;
-      base.d = event.direction;
-      base.st = event.streamType;
-      break;
+      base.sid = event.streamId
+      base.d = event.direction
+      base.st = event.streamType
+      break
     }
     case 'stream-closed': {
-      base.sid = event.streamId;
-      base.ec = event.errorCode;
-      break;
+      base.sid = event.streamId
+      base.ec = event.errorCode
+      break
     }
     case 'object-header': {
-      base.sid = event.streamId;
-      base.g = event.groupId;
-      base.o = event.objectId;
-      base.pp = event.publisherPriority;
-      base.os = event.objectStatus;
-      break;
+      base.sid = event.streamId
+      base.g = event.groupId
+      base.o = event.objectId
+      base.pp = event.publisherPriority
+      base.os = event.objectStatus
+      break
     }
     case 'object-payload': {
-      base.sid = event.streamId;
-      base.g = event.groupId;
-      base.o = event.objectId;
-      base.sz = event.size;
-      if (event.payload != null) base.pl = event.payload;
-      break;
+      base.sid = event.streamId
+      base.g = event.groupId
+      base.o = event.objectId
+      base.sz = event.size
+      if (event.payload != null) base.pl = event.payload
+      break
     }
     case 'state-change': {
-      base.from = event.from;
-      base.to = event.to;
-      break;
+      base.from = event.from
+      base.to = event.to
+      break
     }
     case 'error': {
-      base.ec = event.errorCode;
-      base.reason = event.reason;
-      break;
+      base.ec = event.errorCode
+      base.reason = event.reason
+      break
     }
     case 'annotation': {
-      base.label = event.label;
-      if (event.data !== undefined) base.data = event.data;
-      break;
+      base.label = event.label
+      if (event.data !== undefined) base.data = event.data
+      break
     }
   }
 
-  return base;
+  return base
 }
 
 function cborToEvent(obj: Record<string, unknown>): TraceEvent {
-  const eventType = INT_TO_EVENT_TYPE[obj.e as number];
+  const eventType = INT_TO_EVENT_TYPE[obj.e as number]
   if (eventType == null) {
     // Unknown event type — skip per spec (return annotation as fallback)
     return {
@@ -141,11 +135,11 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
       timestamp: Number(obj.t ?? 0),
       label: `unknown-event-${obj.e}`,
       data: obj,
-    };
+    }
   }
 
-  const seq = Number(obj.n ?? 0);
-  const timestamp = Number(obj.t ?? 0);
+  const seq = Number(obj.n ?? 0)
+  const timestamp = Number(obj.t ?? 0)
 
   switch (eventType) {
     case 'control':
@@ -157,7 +151,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         messageType: Number(obj.mt ?? 0),
         message: (obj.msg ?? {}) as Record<string, unknown>,
         ...(obj.raw != null ? { raw: obj.raw as Uint8Array } : {}),
-      };
+      }
 
     case 'stream-opened':
       return {
@@ -167,7 +161,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         streamId: BigInt(obj.sid as bigint | number),
         direction: obj.d as 0 | 1,
         streamType: obj.st as 0 | 1 | 2,
-      };
+      }
 
     case 'stream-closed':
       return {
@@ -176,7 +170,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         timestamp,
         streamId: BigInt(obj.sid as bigint | number),
         errorCode: Number(obj.ec ?? 0),
-      };
+      }
 
     case 'object-header':
       return {
@@ -188,7 +182,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         objectId: BigInt(obj.o as bigint | number),
         publisherPriority: Number(obj.pp ?? 0),
         objectStatus: Number(obj.os ?? 0),
-      };
+      }
 
     case 'object-payload':
       return {
@@ -200,7 +194,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         objectId: BigInt(obj.o as bigint | number),
         size: Number(obj.sz ?? 0),
         ...(obj.pl != null ? { payload: obj.pl as Uint8Array } : {}),
-      };
+      }
 
     case 'state-change':
       return {
@@ -209,7 +203,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         timestamp,
         from: obj.from as string,
         to: obj.to as string,
-      };
+      }
 
     case 'error':
       return {
@@ -218,7 +212,7 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         timestamp,
         errorCode: Number(obj.ec ?? 0),
         reason: (obj.reason ?? '') as string,
-      };
+      }
 
     case 'annotation':
       return {
@@ -227,45 +221,48 @@ function cborToEvent(obj: Record<string, unknown>): TraceEvent {
         timestamp,
         label: (obj.label ?? '') as string,
         data: obj.data,
-      };
+      }
   }
 }
 
 // --- Preamble helpers ---
 
 function writePreamble(headerCbor: Uint8Array): Uint8Array {
-  const buf = new Uint8Array(PREAMBLE_SIZE + headerCbor.length);
-  buf.set(MAGIC, 0);
-  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
-  view.setUint32(8, FORMAT_VERSION, true);
-  view.setUint32(12, headerCbor.length, true);
-  buf.set(headerCbor, PREAMBLE_SIZE);
-  return buf;
+  const buf = new Uint8Array(PREAMBLE_SIZE + headerCbor.length)
+  buf.set(MAGIC, 0)
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+  view.setUint32(8, FORMAT_VERSION, true)
+  view.setUint32(12, headerCbor.length, true)
+  buf.set(headerCbor, PREAMBLE_SIZE)
+  return buf
 }
 
-function validatePreamble(bytes: Uint8Array): { version: number; headerLength: number } {
+function validatePreamble(bytes: Uint8Array): {
+  version: number
+  headerLength: number
+} {
   if (bytes.length < PREAMBLE_SIZE) {
-    throw new Error('File too short: expected at least 16 bytes');
+    throw new Error('File too short: expected at least 16 bytes')
   }
 
   for (let i = 0; i < 8; i++) {
     if (bytes[i] !== MAGIC[i]) {
-      throw new Error('Invalid magic bytes: not a .moqtrace file');
+      throw new Error('Invalid magic bytes: not a .moqtrace file')
     }
   }
 
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  const version = view.getUint32(8, true);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const version = view.getUint32(8, true)
   if (version !== FORMAT_VERSION) {
-    throw new Error(`Unsupported format version: ${version} (expected ${FORMAT_VERSION})`);
+    throw new Error(`Unsupported format version: ${version} (expected ${FORMAT_VERSION})`)
   }
 
-  const headerLength = view.getUint32(12, true);
+  const headerLength = view.getUint32(12, true)
   if (PREAMBLE_SIZE + headerLength > bytes.length) {
-    throw new Error('File truncated: header extends beyond file');
+    throw new Error('File truncated: header extends beyond file')
   }
 
-  return { version, headerLength };
+  return { version, headerLength }
 }
 
 // --- Public API ---
@@ -274,56 +271,56 @@ function validatePreamble(bytes: Uint8Array): { version: number; headerLength: n
  * Write a complete trace to .moqtrace binary format.
  */
 export function writeMoqtrace(trace: Trace): Uint8Array {
-  const headerCbor = encode(headerToCbor(trace.header));
-  const preamble = writePreamble(headerCbor);
+  const headerCbor = encode(headerToCbor(trace.header))
+  const preamble = writePreamble(headerCbor)
 
-  const eventChunks: Uint8Array[] = [];
-  let totalEventBytes = 0;
+  const eventChunks: Uint8Array[] = []
+  let totalEventBytes = 0
   for (const event of trace.events) {
-    const chunk = encode(eventToCbor(event));
-    eventChunks.push(chunk);
-    totalEventBytes += chunk.length;
+    const chunk = encode(eventToCbor(event))
+    eventChunks.push(chunk)
+    totalEventBytes += chunk.length
   }
 
-  const result = new Uint8Array(preamble.length + totalEventBytes);
-  result.set(preamble, 0);
-  let offset = preamble.length;
+  const result = new Uint8Array(preamble.length + totalEventBytes)
+  result.set(preamble, 0)
+  let offset = preamble.length
   for (const chunk of eventChunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
+    result.set(chunk, offset)
+    offset += chunk.length
   }
 
-  return result;
+  return result
 }
 
 /**
  * Read a complete .moqtrace file from bytes.
  */
 export function readMoqtrace(bytes: Uint8Array): Trace {
-  const { headerLength } = validatePreamble(bytes);
+  const { headerLength } = validatePreamble(bytes)
 
-  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
-  const header = cborToHeader(decode(headerBytes) as Record<string, unknown>);
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength)
+  const header = cborToHeader(decode(headerBytes) as Record<string, unknown>)
 
-  const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength);
-  const events: TraceEvent[] = [];
+  const eventBytes = bytes.slice(PREAMBLE_SIZE + headerLength)
+  const events: TraceEvent[] = []
 
   if (eventBytes.length > 0) {
     decodeMultiple(eventBytes, (obj: unknown) => {
-      events.push(cborToEvent(obj as Record<string, unknown>));
-    });
+      events.push(cborToEvent(obj as Record<string, unknown>))
+    })
   }
 
-  return { header, events };
+  return { header, events }
 }
 
 /**
  * Read only the header from a .moqtrace file (fast metadata peek).
  */
 export function readMoqtraceHeader(bytes: Uint8Array): TraceHeader {
-  const { headerLength } = validatePreamble(bytes);
-  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength);
-  return cborToHeader(decode(headerBytes) as Record<string, unknown>);
+  const { headerLength } = validatePreamble(bytes)
+  const headerBytes = bytes.slice(PREAMBLE_SIZE, PREAMBLE_SIZE + headerLength)
+  return cborToHeader(decode(headerBytes) as Record<string, unknown>)
 }
 
 /**
@@ -331,21 +328,21 @@ export function readMoqtraceHeader(bytes: Uint8Array): TraceHeader {
  */
 export interface MoqtraceWriter {
   /** Returns the file preamble (magic + version + header). Write this first. */
-  preamble(): Uint8Array;
+  preamble(): Uint8Array
   /** Encode a single event. Append the returned bytes after the preamble. */
-  writeEvent(event: TraceEvent): Uint8Array;
+  writeEvent(event: TraceEvent): Uint8Array
 }
 
 export function createMoqtraceWriter(header: TraceHeader): MoqtraceWriter {
-  const headerCbor = encode(headerToCbor(header));
-  const preambleBytes = writePreamble(headerCbor);
+  const headerCbor = encode(headerToCbor(header))
+  const preambleBytes = writePreamble(headerCbor)
 
   return {
     preamble(): Uint8Array {
-      return preambleBytes;
+      return preambleBytes
     },
     writeEvent(event: TraceEvent): Uint8Array {
-      return encode(eventToCbor(event));
+      return encode(eventToCbor(event))
     },
-  };
+  }
 }

package/src/index.ts

@@ -1,33 +1,32 @@
 // Binary .moqtrace format
+
+export type { MoqtraceWriter } from './binary.js'
 export {
-  writeMoqtrace,
+  createMoqtraceWriter,
   readMoqtrace,
   readMoqtraceHeader,
-  createMoqtraceWriter,
-} from './binary.js';
-export type { MoqtraceWriter } from './binary.js';
-
-// Recorder
-export { createRecorder } from './recorder.js';
-export type { TraceRecorder } from './recorder.js';
-
+  writeMoqtrace,
+} from './binary.js'
 // JSON (convenience)
-export { traceToJSON } from './json.js';
+export { traceToJSON } from './json.js'
+export type { TraceRecorder } from './recorder.js'
+// Recorder
+export { createRecorder } from './recorder.js'
 
 // Types
 export type {
-  Trace,
-  TraceHeader,
-  TraceEvent,
+  AnnotationEvent,
   ControlMessageEvent,
-  StreamOpenedEvent,
-  StreamClosedEvent,
+  DetailLevel,
   ObjectHeaderEvent,
   ObjectPayloadEvent,
-  StateChangeEvent,
-  TraceErrorEvent,
-  AnnotationEvent,
-  DetailLevel,
   Perspective,
   RecorderOptions,
-} from './types.js';
+  StateChangeEvent,
+  StreamClosedEvent,
+  StreamOpenedEvent,
+  Trace,
+  TraceErrorEvent,
+  TraceEvent,
+  TraceHeader,
+} from './types.js'

package/src/json.ts

@@ -1,4 +1,4 @@
-import type { Trace } from './types.js';
+import type { Trace } from './types.js'
 
 /**
  * Serialize a trace to human-readable JSON.
@@ -9,13 +9,19 @@ import type { Trace } from './types.js';
  * (`writeMoqtrace` / `readMoqtrace`).
  */
 export function traceToJSON(trace: Trace): string {
-  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);
+  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,
+  )
 }