murow 0.0.70 → 0.0.71

package/src/protocol/snapshot/snapshot-registry.test.ts

@@ -1,310 +0,0 @@
-import { describe, it, expect, beforeEach } from "bun:test";
-import { SnapshotRegistry } from "./snapshot-registry";
-import { Snapshot } from "./snapshot";
-
-// Mock codec for testing
-class MockCodec<T> {
-  encode(value: T): Uint8Array {
-    const json = JSON.stringify(value);
-    return new TextEncoder().encode(json);
-  }
-
-  decode(buf: Uint8Array): T {
-    const json = new TextDecoder().decode(buf);
-    return JSON.parse(json);
-  }
-}
-
-// Test update types
-interface PlayerUpdate {
-  players: Array<{ entityId: number; x: number; y: number }>;
-}
-
-interface ScoreUpdate {
-  score: number;
-}
-
-interface ProjectileUpdate {
-  projectiles: Array<{ id: number; x: number; y: number }>;
-}
-
-type GameUpdate = PlayerUpdate & ScoreUpdate & ProjectileUpdate;
-
-describe("SnapshotRegistry", () => {
-  let registry: SnapshotRegistry<GameUpdate>;
-
-  beforeEach(() => {
-    registry = new SnapshotRegistry<GameUpdate>();
-  });
-
-  describe("register", () => {
-    it("should register a codec for a snapshot type", () => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      expect(registry.has("players")).toBe(true);
-    });
-
-    it("should throw error when registering duplicate type", () => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      expect(() => registry.register("players", new MockCodec<PlayerUpdate>())).toThrow(
-        'Snapshot type "players" is already registered'
-      );
-    });
-
-    it("should allow registering multiple types", () => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-      registry.register("projectiles", new MockCodec<ProjectileUpdate>());
-
-      expect(registry.has("players")).toBe(true);
-      expect(registry.has("score")).toBe(true);
-      expect(registry.has("projectiles")).toBe(true);
-    });
-  });
-
-  describe("encode", () => {
-    beforeEach(() => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-    });
-
-    it("should encode a snapshot with type ID", () => {
-      const snapshot: Snapshot<PlayerUpdate> = {
-        tick: 100,
-        updates: {
-          players: [
-            { entityId: 1, x: 10, y: 20 },
-          ],
-        },
-      };
-
-      const buf = registry.encode("players", snapshot);
-
-      expect(buf).toBeInstanceOf(Uint8Array);
-      expect(buf.length).toBeGreaterThan(5); // type(1) + tick(4) + data
-      expect(buf[0]).toBe(0); // First registered type gets ID 0
-    });
-
-    it("should encode different types with different type IDs", () => {
-      const playerSnapshot: Snapshot<PlayerUpdate> = {
-        tick: 100,
-        updates: { players: [{ entityId: 1, x: 10, y: 20 }] },
-      };
-
-      const scoreSnapshot: Snapshot<ScoreUpdate> = {
-        tick: 101,
-        updates: { score: 50 },
-      };
-
-      const buf1 = registry.encode("players", playerSnapshot);
-      const buf2 = registry.encode("score", scoreSnapshot);
-
-      expect(buf1[0]).toBe(0); // players = ID 0
-      expect(buf2[0]).toBe(1); // score = ID 1
-    });
-
-    it("should throw error when encoding unregistered type", () => {
-      const snapshot: Snapshot<ProjectileUpdate> = {
-        tick: 100,
-        updates: { projectiles: [] },
-      };
-
-      expect(() => registry.encode("projectiles", snapshot)).toThrow(
-        'No codec registered for snapshot type "projectiles"'
-      );
-    });
-
-    it("should preserve tick number in encoding", () => {
-      const snapshot: Snapshot<ScoreUpdate> = {
-        tick: 12345,
-        updates: { score: 100 },
-      };
-
-      const buf = registry.encode("score", snapshot);
-
-      // Tick is at bytes 1-4 (after type ID)
-      const tick = new DataView(buf.buffer, buf.byteOffset + 1).getUint32(0, true);
-      expect(tick).toBe(12345);
-    });
-  });
-
-  describe("decode", () => {
-    beforeEach(() => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-    });
-
-    it("should decode a snapshot and return type", () => {
-      const original: Snapshot<PlayerUpdate> = {
-        tick: 100,
-        updates: {
-          players: [
-            { entityId: 1, x: 10, y: 20 },
-          ],
-        },
-      };
-
-      const buf = registry.encode("players", original);
-      const { type, snapshot } = registry.decode<PlayerUpdate>(buf);
-
-      expect(type).toBe("players");
-      expect(snapshot.tick).toBe(100);
-      expect(snapshot.updates).toEqual(original.updates);
-    });
-
-    it("should decode different snapshot types correctly", () => {
-      const playerSnapshot: Snapshot<PlayerUpdate> = {
-        tick: 100,
-        updates: { players: [{ entityId: 1, x: 10, y: 20 }] },
-      };
-
-      const scoreSnapshot: Snapshot<ScoreUpdate> = {
-        tick: 101,
-        updates: { score: 50 },
-      };
-
-      const buf1 = registry.encode("players", playerSnapshot);
-      const buf2 = registry.encode("score", scoreSnapshot);
-
-      const decoded1 = registry.decode(buf1);
-      const decoded2 = registry.decode(buf2);
-
-      expect(decoded1.type).toBe("players");
-      expect(decoded1.snapshot.updates).toEqual(playerSnapshot.updates);
-
-      expect(decoded2.type).toBe("score");
-      expect(decoded2.snapshot.updates).toEqual(scoreSnapshot.updates);
-    });
-
-    it("should throw error when decoding unknown type ID", () => {
-      const buf = new Uint8Array([99, 0, 0, 0, 100]); // Unknown type ID 99
-
-      expect(() => registry.decode(buf)).toThrow("Unknown snapshot type ID: 99");
-    });
-  });
-
-  describe("round-trip encoding/decoding", () => {
-    beforeEach(() => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-      registry.register("projectiles", new MockCodec<ProjectileUpdate>());
-    });
-
-    it("should preserve data through encode/decode cycle", () => {
-      const original: Snapshot<PlayerUpdate> = {
-        tick: 500,
-        updates: {
-          players: [
-            { entityId: 1, x: 100, y: 200 },
-            { entityId: 2, x: 300, y: 400 },
-          ],
-        },
-      };
-
-      const buf = registry.encode("players", original);
-      const { type, snapshot } = registry.decode(buf);
-
-      expect(type).toBe("players");
-      expect(snapshot).toEqual(original);
-    });
-
-    it("should handle multiple round-trips", () => {
-      const original: Snapshot<ScoreUpdate> = {
-        tick: 1000,
-        updates: { score: 99999 },
-      };
-
-      for (let i = 0; i < 10; i++) {
-        const buf = registry.encode("score", original);
-        const { type, snapshot } = registry.decode(buf);
-        expect(type).toBe("score");
-        expect(snapshot).toEqual(original);
-      }
-    });
-
-    it("should handle arrays in updates", () => {
-      const original: Snapshot<ProjectileUpdate> = {
-        tick: 250,
-        updates: {
-          projectiles: [
-            { id: 1, x: 10, y: 20 },
-            { id: 2, x: 30, y: 40 },
-            { id: 3, x: 50, y: 60 },
-          ],
-        },
-      };
-
-      const buf = registry.encode("projectiles", original);
-      const { type, snapshot } = registry.decode(buf);
-
-      expect(type).toBe("projectiles");
-      expect(snapshot.updates).toEqual(original.updates);
-    });
-  });
-
-  describe("getTypes", () => {
-    it("should return empty array when no types registered", () => {
-      expect(registry.getTypes()).toEqual([]);
-    });
-
-    it("should return all registered types", () => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-
-      const types = registry.getTypes();
-      expect(types).toContain("players");
-      expect(types).toContain("score");
-      expect(types.length).toBe(2);
-    });
-  });
-
-  describe("integration scenarios", () => {
-    beforeEach(() => {
-      registry.register("players", new MockCodec<PlayerUpdate>());
-      registry.register("score", new MockCodec<ScoreUpdate>());
-    });
-
-    it("should allow sending only specific updates", () => {
-      // Server only sends player updates this tick
-      const playerBuf = registry.encode("players", {
-        tick: 100,
-        updates: { players: [{ entityId: 1, x: 5, y: 10 }] },
-      });
-
-      // Next tick, only send score
-      const scoreBuf = registry.encode("score", {
-        tick: 101,
-        updates: { score: 100 },
-      });
-
-      // Client can decode both
-      const decoded1 = registry.decode(playerBuf);
-      const decoded2 = registry.decode(scoreBuf);
-
-      expect(decoded1.type).toBe("players");
-      expect(decoded2.type).toBe("score");
-    });
-
-    it("should maintain type safety with unions", () => {
-      const snapshot: Snapshot<PlayerUpdate> = {
-        tick: 100,
-        updates: { players: [{ entityId: 1, x: 5, y: 10 }] },
-      };
-
-      const buf = registry.encode("players", snapshot);
-      const { type, snapshot: decoded } = registry.decode<GameUpdate>(buf);
-
-      if (('players' in decoded.updates)) {
-        decoded.updates.players!.forEach((p) => {
-          expect(typeof p.entityId).toBe("number");
-          expect(typeof p.x).toBe("number");
-          expect(typeof p.y).toBe("number");
-        });
-      }
-
-      // Type narrowing based on type field
-      expect(type).toBe("players");
-      expect(type in decoded.updates).toBeDefined();
-      expect(type in decoded.updates).toBe(true);
-    });
-  });
-});

package/src/protocol/snapshot/snapshot-registry.ts

@@ -1,201 +0,0 @@
-import type { Snapshot } from "./snapshot";
-
-/**
- * Generic codec interface (users import from core/pooled-codec)
- */
-interface Codec<T> {
-  encode(value: T): Uint8Array;
-  decode(buf: Uint8Array): T;
-  calculateSize?(value: T): number;
-  encodeInto?(value: T, buffer: Uint8Array, offset: number): number;
-}
-
-/**
- * Registry for multiple snapshot types with different update schemas.
- *
- * This allows efficient delta encoding by only sending specific update types
- * instead of encoding all fields (including empty/nil ones).
- *
- * ## Memory Efficiency
- *
- * The encoding path minimizes allocations:
- * 1. PooledCodec acquires a buffer from its pool (reused across calls)
- * 2. PooledCodec writes data directly to the buffer at sequential offsets
- * 3. SnapshotRegistry creates ONE final buffer: [typeId(1) + tick(4) + updatesBytes]
- * 4. Total allocations per encode: 1 pooled buffer + 1 final buffer
- *
- * Buffer Layout:
- * ```
- * ┌─────────┬────────────┬──────────────────┐
- * │ Type ID │    Tick    │  Updates (codec) │
- * │ (u8)    │   (u32)    │   (variable)     │
- * │ 1 byte  │  4 bytes   │    N bytes       │
- * └─────────┴────────────┴──────────────────┘
- * ```
- *
- * @example
- * ```ts
- * import { SnapshotRegistry } from './protocol/snapshot';
- * import { PooledCodec } from './core/pooled-codec';
- * import { BinaryPrimitives } from './core/binary-codec';
- *
- * // Define different update types
- * interface PlayerUpdate {
- *   players: Array<{ entityId: number; x: number; y: number }>;
- * }
- *
- * interface ScoreUpdate {
- *   score: number;
- * }
- *
- * // Create registry
- * const registry = new SnapshotRegistry<PlayerUpdate | ScoreUpdate>();
- *
- * // Register codecs for each update type
- * registry.register('players', new PooledCodec({
- *   players: PooledCodec.array({
- *     entityId: BinaryPrimitives.u32,
- *     x: BinaryPrimitives.f32,
- *     y: BinaryPrimitives.f32,
- *   })
- * }));
- *
- * registry.register('score', new PooledCodec({
- *   score: BinaryPrimitives.u32
- * }));
- *
- * // Server: Encode specific update type
- * const buf = registry.encode('players', {
- *   tick: 100,
- *   updates: { players: [{ entityId: 1, x: 5, y: 10 }] }
- * });
- *
- * // Client: Decode (type is embedded in message)
- * const { type, snapshot } = registry.decode(buf);
- * applySnapshot(state, snapshot);
- * ```
- */
-export class SnapshotRegistry<T extends Object = {}> {
-  private codecs = new Map<string, Codec<any>>();
-  private typeIds = new Map<string, number>();
-  private idToType = new Map<number, string>();
-  private nextId = 0;
-
-  /**
-   * Register a codec for a specific update type.
-   * Call this once per update type at startup.
-   */
-  register<U extends Partial<T>>(type: string, codec: Codec<U>): void {
-    if (this.codecs.has(type)) {
-      throw new Error(`Snapshot type "${type}" is already registered`);
-    }
-
-    const typeId = this.nextId++;
-    this.codecs.set(type, codec);
-    this.typeIds.set(type, typeId);
-    this.idToType.set(typeId, type);
-  }
-
-  /**
-   * Encode a snapshot with a specific update type.
-   * Format: [typeId: u8][tick: u32][updates: encoded by codec]
-   *
-   * Zero-copy encoding path:
-   * - Calculate total size needed
-   * - Allocate ONE final buffer for [typeId + tick + updates]
-   * - Write directly into buffer using encodeInto (no intermediate allocations)
-   *
-   * Falls back to legacy encode() method if codec doesn't support encodeInto.
-   */
-  encode<U extends Partial<T>>(type: string, snapshot: Snapshot<U>): Uint8Array {
-    const codec = this.codecs.get(type);
-    const typeId = this.typeIds.get(type);
-
-    if (!codec || typeId === undefined) {
-      throw new Error(`No codec registered for snapshot type "${type}"`);
-    }
-
-    // Use zero-copy path if available
-    if (codec.calculateSize && codec.encodeInto) {
-      // Calculate total size
-      const updatesSize = codec.calculateSize(snapshot.updates);
-      const buf = new Uint8Array(5 + updatesSize);
-
-      // Write type ID (1 byte)
-      buf[0] = typeId;
-
-      // Write tick (4 bytes, little-endian)
-      new DataView(buf.buffer).setUint32(1, snapshot.tick, true);
-
-      // Write updates directly into buffer (ZERO COPY!)
-      codec.encodeInto(snapshot.updates, buf, 5);
-
-      return buf;
-    }
-
-    // Fallback to legacy path for backward compatibility
-    const updatesBytes = codec.encode(snapshot.updates);
-    const buf = new Uint8Array(1 + 4 + updatesBytes.length);
-
-    buf[0] = typeId;
-    new DataView(buf.buffer).setUint32(1, snapshot.tick, true);
-    buf.set(updatesBytes, 5);
-
-    return buf;
-  }
-
-  /**
-   * Decode a snapshot and return both the type and the snapshot.
-   */
-  decode<U extends Partial<T> = Partial<T>>(buf: Uint8Array): { type: string; snapshot: Snapshot<U> } {
-    // Decode type ID (first byte)
-    const typeId = buf[0];
-    const type = this.idToType.get(typeId);
-
-    if (!type) {
-      throw new Error(`Unknown snapshot type ID: ${typeId}`);
-    }
-
-    const codec = this.codecs.get(type);
-    if (!codec) {
-      throw new Error(`No codec registered for snapshot type "${type}"`);
-    }
-
-    // Decode tick (bytes 1-4)
-    const tick = new DataView(buf.buffer, buf.byteOffset + 1).getUint32(0, true);
-
-    // Decode updates (remaining bytes)
-    const updatesBytes = buf.subarray(5);
-    const updates = codec.decode(updatesBytes) as U;
-
-    return { type, snapshot: { tick, updates } };
-  }
-
-  has(type: string): boolean {
-    return this.codecs.has(type);
-  }
-
-  getTypes(): string[] {
-    return Array.from(this.codecs.keys());
-  }
-
-  /**
-   * Release a decoded snapshot's updates object back to the pool.
-   * Call this after you're done processing the snapshot to enable object pooling.
-   *
-   * @param type The snapshot type (same as used in decode)
-   * @param updates The updates object to release
-   */
-  release<U extends Partial<T>>(type: string, updates: U): void {
-    const codec = this.codecs.get(type);
-
-    if (!codec) {
-      throw new Error(`No codec registered for snapshot type "${type}"`);
-    }
-
-    // Only release if the codec supports pooling
-    if ('release' in codec && typeof codec.release === 'function') {
-      codec.release(updates);
-    }
-  }
-}

package/src/protocol/snapshot/snapshot.test.ts

@@ -1,76 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import { Snapshot, applySnapshot } from "./snapshot";
-
-interface TestState {
-  x: number;
-  y: number;
-  health?: number;
-  nested?: {
-    a: number;
-    b?: number;
-  };
-  items?: string[];
-}
-
-describe("Snapshot", () => {
-  describe("applySnapshot", () => {
-    it("should apply simple property updates", () => {
-      const state: TestState = { x: 0, y: 0 };
-      const snapshot: Snapshot<TestState> = {
-        tick: 100,
-        updates: { x: 10, y: 20 },
-      };
-
-      applySnapshot(state, snapshot);
-      expect(state.x).toBe(10);
-      expect(state.y).toBe(20);
-    });
-
-    it("should apply partial updates without affecting other properties", () => {
-      const state: TestState = { x: 0, y: 0, health: 100 };
-      const snapshot: Snapshot<TestState> = {
-        tick: 100,
-        updates: { x: 10 },
-      };
-
-      applySnapshot(state, snapshot);
-      expect(state.x).toBe(10);
-      expect(state.y).toBe(0);
-      expect(state.health).toBe(100);
-    });
-
-    it("should handle nested object updates", () => {
-      const state: TestState = { x: 0, y: 0, nested: { a: 1, b: 2 } };
-      const snapshot: Snapshot<TestState> = {
-        tick: 100,
-        updates: { nested: { a: 10 } },
-      };
-
-      applySnapshot(state, snapshot);
-      expect(state.nested?.a).toBe(10);
-      expect(state.nested?.b).toBe(2);
-    });
-
-    it("should replace arrays entirely", () => {
-      const state: TestState = { x: 0, y: 0, items: ["a", "b", "c"] };
-      const snapshot: Snapshot<TestState> = {
-        tick: 100,
-        updates: { items: ["x", "y"] },
-      };
-
-      applySnapshot(state, snapshot);
-      expect(state.items).toEqual(["x", "y"]);
-    });
-
-    it("should handle null values", () => {
-      const state: TestState = { x: 0, y: 0, health: 100 };
-      const snapshot: Snapshot<TestState> = {
-        tick: 100,
-        updates: { health: null as any },
-      };
-
-      applySnapshot(state, snapshot);
-      expect(state.health).toBeNull();
-    });
-  });
-});

package/src/protocol/snapshot/snapshot.ts

@@ -1,41 +0,0 @@
-/**
- * Server-authoritative snapshot with delta updates.
- *
- * @template T The full state type
- */
-export interface Snapshot<T> {
-  /** Server tick when this snapshot was created */
-  tick: number;
-  /** Partial state updates (only what changed) */
-  updates: Partial<T>;
-}
-
-/**
- * Apply snapshot updates to state (mutating).
- * Deep merges objects, replaces arrays.
- *
- * @param state State to update
- * @param snapshot Snapshot to apply
- */
-export function applySnapshot<T>(state: T, snapshot: Snapshot<T>): void {
-  deepMerge(state, snapshot.updates);
-}
-
-function deepMerge<T>(target: T, update: Partial<T>): void {
-  for (const key in update) {
-    if (!Object.prototype.hasOwnProperty.call(update, key)) continue;
-
-    const updateValue = update[key];
-    const targetValue = target[key];
-
-    if (updateValue === null || updateValue === undefined) {
-      target[key] = updateValue as T[Extract<keyof T, string>];
-    } else if (Array.isArray(updateValue)) {
-      target[key] = updateValue as T[Extract<keyof T, string>];
-    } else if (typeof updateValue === "object" && typeof targetValue === "object") {
-      deepMerge(targetValue as any, updateValue as any);
-    } else {
-      target[key] = updateValue as T[Extract<keyof T, string>];
-    }
-  }
-}