murow 0.0.70 → 0.0.71

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

@@ -1,198 +0,0 @@
-import { describe, it, expect, beforeEach } from "bun:test";
-import { IntentRegistry } from "./intent-registry";
-import { Intent } from "./intent";
-import { defineIntent } from "./define-intent";
-import { BinaryCodec } from "../../core/binary-codec";
-
-// Define intents using defineIntent for testing
-const MockIntent = defineIntent({
-  kind: 1 as const,
-  schema: {
-    value: BinaryCodec.u32,
-  },
-});
-
-const AnotherIntent = defineIntent({
-  kind: 2 as const,
-  schema: {
-    data: BinaryCodec.string(64),
-  },
-});
-
-type MockIntentType = typeof MockIntent.type;
-type AnotherIntentType = typeof AnotherIntent.type;
-
-describe("IntentRegistry", () => {
-  let registry: IntentRegistry;
-
-  beforeEach(() => {
-    registry = new IntentRegistry();
-  });
-
-  describe("register", () => {
-    it("should register a codec for an intent kind", () => {
-      registry.register(MockIntent);
-      expect(registry.has(1)).toBe(true);
-    });
-
-    it("should throw error when registering duplicate kind", () => {
-      registry.register(MockIntent);
-      expect(() => registry.register(MockIntent)).toThrow(
-        "Intent kind 1 is already registered"
-      );
-    });
-
-    it("should allow registering multiple different kinds", () => {
-      registry.register(MockIntent);
-      registry.register(AnotherIntent);
-      expect(registry.has(1)).toBe(true);
-      expect(registry.has(2)).toBe(true);
-    });
-  });
-
-  describe("encode", () => {
-    it("should encode an intent using registered codec", () => {
-      registry.register(MockIntent);
-      const intent: MockIntentType = { kind: 1, tick: 100, value: 42 };
-      const buf = registry.encode(intent);
-
-      expect(buf).toBeInstanceOf(Uint8Array);
-      expect(buf[0]).toBe(1); // kind
-    });
-
-    it("should throw error when encoding unregistered intent kind", () => {
-      const intent: MockIntentType = { kind: 1, tick: 100, value: 42 };
-      expect(() => registry.encode(intent)).toThrow(
-        "No codec registered for intent kind 1"
-      );
-    });
-
-    it("should encode different intent types correctly", () => {
-      registry.register(MockIntent);
-      registry.register(AnotherIntent);
-
-      const intent1: MockIntentType = { kind: 1, tick: 100, value: 42 };
-      const intent2: AnotherIntentType = { kind: 2, tick: 200, data: "test" };
-
-      const buf1 = registry.encode(intent1);
-      const buf2 = registry.encode(intent2);
-
-      expect(buf1[0]).toBe(1);
-      expect(buf2[0]).toBe(2);
-    });
-  });
-
-  describe("decode", () => {
-    it("should decode a buffer using registered codec", () => {
-      registry.register(MockIntent);
-      const original: MockIntentType = { kind: 1, tick: 100, value: 42 };
-      const buf = registry.encode(original);
-      const decoded = registry.decode(buf);
-
-      expect(decoded).toEqual(original);
-    });
-
-    it("should throw error when decoding with unregistered kind", () => {
-      const buf = new Uint8Array([99, 0, 0, 0, 100, 0, 0, 0, 42]); // kind=99 not registered
-      expect(() => registry.decode(buf)).toThrow(
-        "No codec registered for intent kind 99"
-      );
-    });
-
-    it("should decode different intent types correctly", () => {
-      registry.register(MockIntent);
-      registry.register(AnotherIntent);
-
-      const intent1: MockIntentType = { kind: 1, tick: 100, value: 42 };
-      const intent2: AnotherIntentType = { kind: 2, tick: 200, data: "hello" };
-
-      const buf1 = registry.encode(intent1);
-      const buf2 = registry.encode(intent2);
-
-      const decoded1 = registry.decode(buf1);
-      const decoded2 = registry.decode(buf2);
-
-      expect(decoded1).toEqual(intent1);
-      expect(decoded2).toEqual(intent2);
-    });
-  });
-
-  describe("has", () => {
-    it("should return true for registered kinds", () => {
-      registry.register(MockIntent);
-      expect(registry.has(1)).toBe(true);
-    });
-
-    it("should return false for unregistered kinds", () => {
-      expect(registry.has(1)).toBe(false);
-    });
-  });
-
-  describe("unregister", () => {
-    it("should remove a registered codec", () => {
-      registry.register(MockIntent);
-      expect(registry.has(1)).toBe(true);
-
-      const removed = registry.unregister(1);
-      expect(removed).toBe(true);
-      expect(registry.has(1)).toBe(false);
-    });
-
-    it("should return false when unregistering non-existent kind", () => {
-      const removed = registry.unregister(1);
-      expect(removed).toBe(false);
-    });
-  });
-
-  describe("clear", () => {
-    it("should remove all registered codecs", () => {
-      registry.register(MockIntent);
-      registry.register(AnotherIntent);
-
-      registry.clear();
-
-      expect(registry.has(1)).toBe(false);
-      expect(registry.has(2)).toBe(false);
-    });
-  });
-
-  describe("getKinds", () => {
-    it("should return empty array when no codecs registered", () => {
-      expect(registry.getKinds()).toEqual([]);
-    });
-
-    it("should return all registered kinds", () => {
-      registry.register(MockIntent);
-      registry.register(AnotherIntent);
-
-      const kinds = registry.getKinds();
-      expect(kinds).toContain(1);
-      expect(kinds).toContain(2);
-      expect(kinds.length).toBe(2);
-    });
-  });
-
-  describe("round-trip encoding/decoding", () => {
-    it("should preserve intent data through encode/decode cycle", () => {
-      registry.register(MockIntent);
-
-      const original: MockIntentType = { kind: 1, tick: 12345, value: 98765 };
-      const buf = registry.encode(original);
-      const decoded = registry.decode(buf);
-
-      expect(decoded).toEqual(original);
-    });
-
-    it("should handle multiple round-trips", () => {
-      registry.register(MockIntent);
-
-      const original: MockIntentType = { kind: 1, tick: 100, value: 42 };
-
-      for (let i = 0; i < 10; i++) {
-        const buf = registry.encode(original);
-        const decoded = registry.decode(buf);
-        expect(decoded).toEqual(original);
-      }
-    });
-  });
-});

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

@@ -1,112 +0,0 @@
-import { DefinedIntent } from "./define-intent";
-import type { Intent } from "./intent";
-
-/**
- * Generic codec interface (users import from core/pooled-codec)
- */
-export 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 mapping intent kinds to their codecs.
- *
- * Users instantiate this once and register their intent types with
- * PooledCodec instances (from core/pooled-codec).
- *
- * @example
- * ```ts
- * import { IntentRegistry } from './protocol/intent';
- * import { PooledCodec } from './core/pooled-codec';
- * import { BinaryCodec } from './core/binary-codec';
- *
- * const registry = new IntentRegistry();
- *
- * registry.register(1, new PooledCodec({
- *   kind: BinaryCodec.u8,
- *   tick: BinaryCodec.u32,
- *   dx: BinaryCodec.f32,
- *   dy: BinaryCodec.f32,
- * }));
- *
- * // Encode/decode
- * const buf = registry.encode(intent);
- * const decoded = registry.decode(buf);
- * ```
- */
-export class IntentRegistry {
-  private codecs = new Map<number, Codec<any>>();
-
-  /**
-   * Register a codec for a specific intent kind.
-   * Call this once per intent type at startup.
-   */
-  register<T extends Intent>(intent: DefinedIntent<T['kind'], T>): void {
-    if (this.codecs.has(intent.kind)) {
-      throw new Error(`Intent kind ${intent.kind} is already registered`);
-    }
-    this.codecs.set(intent.kind, intent.codec);
-  }
-
-  /**
-   * Encode an intent into binary format.
-   */
-  encode<T extends Intent>(intent: T): Uint8Array {
-    const codec = this.codecs.get(intent.kind);
-    if (!codec) {
-      throw new Error(`No codec registered for intent kind ${intent.kind}`);
-    }
-    return codec.encode(intent);
-  }
-
-  /**
-   * Decode binary data into an intent.
-   * Extracts the kind from the first byte of the buffer.
-   */
-  decode(buf: Uint8Array): Intent {
-    if (buf.byteLength === 0) {
-      throw new Error('Cannot decode empty buffer');
-    }
-
-    // Extract kind from first byte (all intent codecs must encode kind as u8 in first byte)
-    const kind = buf[0];
-
-    const codec = this.codecs.get(kind);
-    if (!codec) {
-      throw new Error(`No codec registered for intent kind ${kind}`);
-    }
-    return codec.decode(buf);
-  }
-
-  /**
-   * Decode binary data into an intent when kind is already known.
-   * Useful for testing or when kind is transmitted separately.
-   * @deprecated Use decode(buf) instead for standard intent decoding
-   */
-  decodeWithKnownKind(kind: number, buf: Uint8Array): Intent {
-    const codec = this.codecs.get(kind);
-    if (!codec) {
-      throw new Error(`No codec registered for intent kind ${kind}`);
-    }
-    return codec.decode(buf);
-  }
-
-  has(kind: number): boolean {
-    return this.codecs.has(kind);
-  }
-
-  unregister(kind: number): boolean {
-    return this.codecs.delete(kind);
-  }
-
-  clear(): void {
-    this.codecs.clear();
-  }
-
-  getKinds(): number[] {
-    return Array.from(this.codecs.keys());
-  }
-}

package/src/protocol/intent/intent.ts

@@ -1,12 +0,0 @@
-/**
- * Base interface for all game intents.
- *
- * Intents represent player or AI actions that need to be processed by the game simulation.
- * They are timestamped with a tick number for deterministic replay and synchronization.
- */
-export interface Intent {
-  /** The game tick at which this intent should be processed */
-  tick: number;
-  /** Numeric identifier for the intent type (used for codec lookup) */
-  kind: number;
-}

package/src/protocol/rpc/define-rpc.test.ts

@@ -1,141 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import { defineRPC } from "./define-rpc";
-import { BinaryCodec } from "../../core/binary-codec";
-import { RpcRegistry } from "./rpc-registry";
-
-describe("defineRPC", () => {
-	describe("type inference", () => {
-		it("should infer correct type from schema", () => {
-			const MatchCountdown = defineRPC({
-				method: 'matchCountdown',
-				schema: {
-					secondsRemaining: BinaryCodec.u8,
-				},
-			});
-
-			type MatchCountdown = typeof MatchCountdown.type;
-
-			// Create an instance to verify type inference
-			const countdown: MatchCountdown = {
-				secondsRemaining: 10,
-			};
-
-			expect(countdown.secondsRemaining).toBe(10);
-		});
-
-		it("should support RPCs with different field types", () => {
-			const BuyItem = defineRPC({
-				method: 'buyItem',
-				schema: {
-					itemId: BinaryCodec.string(32),
-					quantity: BinaryCodec.u16,
-					price: BinaryCodec.f32,
-				},
-			});
-
-			type BuyItem = typeof BuyItem.type;
-
-			const purchase: BuyItem = {
-				itemId: 'long_sword',
-				quantity: 5,
-				price: 100.5,
-			};
-
-			expect(purchase.itemId).toBe('long_sword');
-			expect(purchase.quantity).toBe(5);
-			expect(purchase.price).toBe(100.5);
-		});
-
-		it("should support empty RPCs (no parameters)", () => {
-			const Ping = defineRPC({
-				method: 'ping',
-				schema: {},
-			});
-
-			type Ping = typeof Ping.type;
-
-			const ping: Ping = {};
-
-			expect(ping).toEqual({});
-		});
-	});
-
-	describe("codec generation", () => {
-		it("should generate a codec that can encode/decode", () => {
-			const TestRpc = defineRPC({
-				method: 'test',
-				schema: {
-					value: BinaryCodec.u32,
-				},
-			});
-
-			type TestRpc = typeof TestRpc.type;
-
-			const data: TestRpc = { value: 42 };
-			const encoded = TestRpc.codec.encode(data);
-
-			expect(encoded).toBeInstanceOf(Uint8Array);
-
-			const decoded = TestRpc.codec.decode(encoded);
-			expect(decoded.value).toBe(42);
-		});
-
-		it("should encode/decode complex types", () => {
-			const PlayerInfo = defineRPC({
-				method: 'playerInfo',
-				schema: {
-					playerId: BinaryCodec.u32,
-					name: BinaryCodec.string(64),
-					level: BinaryCodec.u8,
-					health: BinaryCodec.f32,
-				},
-			});
-
-			type PlayerInfo = typeof PlayerInfo.type;
-
-			const data: PlayerInfo = {
-				playerId: 12345,
-				name: 'TestPlayer',
-				level: 50,
-				health: 85.5,
-			};
-
-			const encoded = PlayerInfo.codec.encode(data);
-			const decoded = PlayerInfo.codec.decode(encoded);
-
-			expect(decoded.playerId).toBe(12345);
-			expect(decoded.name).toBe('TestPlayer');
-			expect(decoded.level).toBe(50);
-			expect(decoded.health).toBeCloseTo(85.5, 1);
-		});
-	});
-
-	describe("integration with RpcRegistry", () => {
-		it("should work with RpcRegistry", () => {
-			const Notification = defineRPC({
-				method: 'notification',
-				schema: {
-					message: BinaryCodec.string(128),
-					priority: BinaryCodec.u8,
-				},
-			});
-
-			type Notification = typeof Notification.type;
-
-			const registry = new RpcRegistry();
-			registry.register(Notification);
-
-			const data: Notification = {
-				message: 'Test notification',
-				priority: 1,
-			};
-
-			const encoded = registry.encode(Notification, data);
-			const decoded = registry.decode(encoded);
-
-			expect(decoded.method).toBe('notification');
-			expect(decoded.data.message).toBe('Test notification');
-			expect(decoded.data.priority).toBe(1);
-		});
-	});
-});

package/src/protocol/rpc/define-rpc.ts

@@ -1,113 +0,0 @@
-import type { DefinedRPC, RpcCodec } from "./rpc";
-import type { Schema } from "../../core/binary-codec";
-import { BinaryCodec } from "../../core/binary-codec";
-
-/**
- * Configuration for defining an RPC type.
- * @template S The schema type describing the RPC's data fields
- */
-export interface RpcDefinition<S extends Record<string, any>> {
-	/** Method name for this RPC (must be unique) */
-	method: string;
-	/** Schema describing the RPC's data fields */
-	schema: S;
-}
-
-/**
- * Infers the TypeScript type from an RPC schema.
- * @template S The schema type
- */
-export type InferRpcType<S extends Record<string, any>> = {
-	[P in keyof S]: S[P] extends { read(dv: DataView, o: number): infer R } ? R : never;
-};
-
-/**
- * Simple codec implementation that uses BinaryCodec for encoding/decoding.
- * @template T The RPC data type
- */
-class RpcCodecImpl<T extends object> implements RpcCodec<T> {
-	constructor(private schema: Schema<T>) {}
-
-	encode(value: T): Uint8Array {
-		return BinaryCodec.encode(this.schema, value);
-	}
-
-	decode(buf: Uint8Array): T {
-		// Create a target object with nil values
-		const target = {} as T;
-		for (const key of Object.keys(this.schema) as (keyof T)[]) {
-			const field = this.schema[key];
-			target[key] = field.toNil() as T[keyof T];
-		}
-		return BinaryCodec.decode(this.schema, buf, target);
-	}
-}
-
-/**
- * Define a type-safe RPC with automatic schema generation.
- *
- * RPCs are bidirectional one-off events/commands for:
- * - Meta-game events (achievements, notifications)
- * - Match lifecycle (countdown, results)
- * - Request/response patterns
- * - System announcements
- *
- * NOT for game state synchronization (use Snapshots) or player inputs (use Intents)
- *
- * @template S The schema type
- * @param definition RPC configuration with method and schema
- * @returns A DefinedRpc object with method and codec
- *
- * @example Server → Client RPC
- * ```ts
- * const MatchCountdown = defineRPC({
- *   method: 'matchCountdown',
- *   schema: {
- *     secondsRemaining: BinaryCodec.u8,
- *   }
- * });
- *
- * // Server sends
- * server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 10 });
- *
- * // Client receives
- * client.onRpc(MatchCountdown, (rpc) => {
- *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
- * });
- * ```
- *
- * @example Client → Server RPC
- * ```ts
- * const BuyItem = defineRPC({
- *   method: 'buyItem',
- *   schema: {
- *     itemId: BinaryCodec.string(32),
- *   }
- * });
- *
- * // Client sends
- * client.sendRpc(BuyItem, { itemId: 'long_sword' });
- *
- * // Server receives
- * server.onRpc(BuyItem, (peerId, rpc) => {
- *   console.log(`${peerId} wants to buy ${rpc.itemId}`);
- * });
- * ```
- */
-export function defineRPC<S extends Record<string, any>>(
-	definition: RpcDefinition<S>
-): DefinedRPC<InferRpcType<S>> {
-	type RpcType = InferRpcType<S>;
-
-	// Create the schema from definition
-	const schema = definition.schema as Schema<RpcType>;
-
-	// Create the codec using BinaryCodec
-	const codec = new RpcCodecImpl<RpcType>(schema);
-
-	return {
-		method: definition.method,
-		codec,
-		type: undefined as any as RpcType, // Phantom type for inference
-	};
-}

package/src/protocol/rpc/index.ts

@@ -1,3 +0,0 @@
-export * from './rpc';
-export * from './define-rpc';
-export * from './rpc-registry';