murow 0.0.60 → 0.0.71

package/dist/protocol/rpc/rpc-registry.js

@@ -1,159 +0,0 @@
-/**
- * Registry for managing RPC definitions with binary encoding/decoding
- *
- * Maps RPC method names to numeric IDs for efficient binary protocol:
- * - Method names are assigned sequential IDs (0, 1, 2, ...)
- * - Binary format: [methodId: u16][data: variable]
- * - Supports bidirectional RPCs (client ↔ server)
- *
- * @example
- * ```ts
- * const registry = new RpcRegistry();
- *
- * // Register RPCs
- * registry.register(MatchCountdown);
- * registry.register(BuyItem);
- *
- * // Encode RPC to binary
- * const binary = registry.encode(MatchCountdown, { secondsRemaining: 10 });
- *
- * // Decode RPC from binary
- * const { method, data } = registry.decode(binary);
- * console.log(method); // 'matchCountdown'
- * console.log(data.secondsRemaining); // 10
- * ```
- */
-export class RpcRegistry {
-    constructor() {
-        this.codecs = new Map();
-        this.methodToId = new Map();
-        this.idToMethod = new Map();
-        this.nextId = 0;
-    }
-    /**
-     * Register an RPC definition
-     *
-     * @param rpc The RPC definition created by defineRPC()
-     * @throws Error if method is already registered
-     *
-     * @example
-     * ```ts
-     * const MatchCountdown = defineRPC({
-     *   method: 'matchCountdown',
-     *   schema: { secondsRemaining: BinaryCodec.u8 }
-     * });
-     *
-     * registry.register(MatchCountdown);
-     * ```
-     */
-    register(rpc) {
-        if (this.codecs.has(rpc.method)) {
-            throw new Error(`RPC "${rpc.method}" is already registered`);
-        }
-        const id = this.nextId++;
-        this.codecs.set(rpc.method, rpc.codec);
-        this.methodToId.set(rpc.method, id);
-        this.idToMethod.set(id, rpc.method);
-    }
-    /**
-     * Encode an RPC to binary format
-     *
-     * Binary format: [methodId: u16][data: variable]
-     *
-     * @param rpc The RPC definition
-     * @param data The RPC data to encode
-     * @returns Encoded binary data
-     * @throws Error if RPC is not registered
-     *
-     * @example
-     * ```ts
-     * const binary = registry.encode(MatchCountdown, {
-     *   secondsRemaining: 10
-     * });
-     * ```
-     */
-    encode(rpc, data) {
-        const codec = this.codecs.get(rpc.method);
-        if (!codec) {
-            throw new Error(`RPC "${rpc.method}" is not registered`);
-        }
-        const methodId = this.methodToId.get(rpc.method);
-        const encodedData = codec.encode(data);
-        // Message format: [methodId: u16][data]
-        const buffer = new Uint8Array(2 + encodedData.byteLength);
-        new DataView(buffer.buffer).setUint16(0, methodId, true);
-        buffer.set(new Uint8Array(encodedData), 2);
-        return buffer;
-    }
-    /**
-     * Decode an RPC from binary format
-     *
-     * @param buffer Binary data to decode
-     * @returns Object with method name and decoded data
-     * @throws Error if method ID is unknown
-     *
-     * @example
-     * ```ts
-     * const { method, data } = registry.decode(binary);
-     * console.log(method); // 'matchCountdown'
-     * console.log(data.secondsRemaining); // 10
-     * ```
-     */
-    decode(buffer) {
-        if (buffer.byteLength < 2) {
-            throw new Error('Buffer too small for RPC message');
-        }
-        const view = new DataView(buffer.buffer, buffer.byteOffset);
-        const methodId = view.getUint16(0, true);
-        const method = this.idToMethod.get(methodId);
-        if (!method) {
-            throw new Error(`Unknown RPC method ID: ${methodId}`);
-        }
-        const codec = this.codecs.get(method);
-        const data = codec.decode(buffer.slice(2));
-        return { method, data };
-    }
-    /**
-     * Check if an RPC method is registered
-     *
-     * @param method Method name to check
-     * @returns True if registered, false otherwise
-     */
-    has(method) {
-        return this.codecs.has(method);
-    }
-    /**
-     * Get all registered RPC method names
-     *
-     * @returns Array of method names
-     */
-    getMethods() {
-        return Array.from(this.codecs.keys());
-    }
-    /**
-     * Get the numeric ID for a method
-     *
-     * @param method Method name
-     * @returns Method ID or undefined if not registered
-     */
-    getMethodId(method) {
-        return this.methodToId.get(method);
-    }
-    /**
-     * Release a decoded RPC data object back to the pool.
-     * Call this after you're done processing the RPC to enable object pooling.
-     *
-     * @param method The RPC method name (same as used in decode)
-     * @param data The RPC data object to release
-     */
-    release(method, data) {
-        const codec = this.codecs.get(method);
-        if (!codec) {
-            throw new Error(`RPC "${method}" is not registered`);
-        }
-        // Only release if the codec supports pooling
-        if ('release' in codec && typeof codec.release === 'function') {
-            codec.release(data);
-        }
-    }
-}

package/dist/protocol/rpc/rpc.js

@@ -1,12 +0,0 @@
-/**
- * RPC (Remote Procedure Call) type definitions
- *
- * 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)
- */
-export {};

package/dist/protocol/snapshot/index.js

@@ -1,43 +0,0 @@
-/**
- * Snapshot system for server-to-client state updates.
- *
- * Snapshots are delta updates that contain:
- * 1. Server tick number
- * 2. Partial state updates (only what changed)
- *
- * They need to be:
- * 1. Encoded efficiently (binary)
- * 2. Sent over network
- * 3. Decoded on the client
- * 4. Merged into client state
- *
- * @example
- * ```ts
- * import { Snapshot, SnapshotCodec, applySnapshot } from './protocol/snapshot';
- * import { PooledCodec } from '../core/pooled-codec';
- * import { BinaryCodec } from '../core/binary-codec';
- *
- * interface GameState {
- *   players: Record<number, { x: number; y: number }>;
- * }
- *
- * // 1. Create codec once (reuse this instance)
- * const snapshotCodec = new SnapshotCodec<GameState>(
- *   new PooledCodec({ players: // ... your schema })
- * );
- *
- * // 2. Server: Encode snapshot
- * const snapshot: Snapshot<GameState> = {
- *   tick: 100,
- *   updates: { players: { 1: { x: 5, y: 10 } } }
- * };
- * const buf = snapshotCodec.encode(snapshot);
- *
- * // 3. Client: Decode and apply
- * const snapshot = snapshotCodec.decode(buf);
- * applySnapshot(clientState, snapshot);
- * ```
- */
-export { applySnapshot } from "./snapshot";
-export { SnapshotCodec } from "./snapshot-codec";
-export { SnapshotRegistry } from "./snapshot-registry";

package/dist/protocol/snapshot/snapshot-codec.js

@@ -1,67 +0,0 @@
-/**
- * Codec for encoding/decoding snapshots with binary serialization.
- *
- * Users instantiate this once with a PooledCodec for their state schema.
- *
- * @example
- * ```ts
- * import { SnapshotCodec } from './protocol/snapshot';
- * import { PooledCodec } from './core/pooled-codec';
- * import { BinaryCodec } from './core/binary-codec';
- *
- * interface GameState {
- *   players: Record<number, { x: number; y: number }>;
- * }
- *
- * const snapshotCodec = new SnapshotCodec<GameState>(
- *   new PooledCodec({ players: // schema })
- * );
- *
- * // Encode/decode
- * const buf = snapshotCodec.encode(snapshot);
- * const decoded = snapshotCodec.decode(buf);
- * ```
- */
-export class SnapshotCodec {
-    /**
-     * @param updatesCodec Codec for encoding/decoding the state updates
-     */
-    constructor(updatesCodec) {
-        this.updatesCodec = updatesCodec;
-    }
-    /**
-     * Encode a snapshot into binary format.
-     * Format: [tick: u32][updates: encoded by updatesCodec]
-     *
-     * Uses zero-copy path if codec supports calculateSize and encodeInto.
-     */
-    encode(snapshot) {
-        // Use zero-copy path if available
-        if (this.updatesCodec.calculateSize && this.updatesCodec.encodeInto) {
-            const updatesSize = this.updatesCodec.calculateSize(snapshot.updates);
-            const buf = new Uint8Array(4 + updatesSize);
-            // Encode tick (4 bytes, little-endian)
-            new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
-            // Write updates directly into buffer (ZERO COPY!)
-            this.updatesCodec.encodeInto(snapshot.updates, buf, 4);
-            return buf;
-        }
-        // Fallback to legacy path
-        const updatesBytes = this.updatesCodec.encode(snapshot.updates);
-        const buf = new Uint8Array(4 + updatesBytes.length);
-        new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
-        buf.set(updatesBytes, 4);
-        return buf;
-    }
-    /**
-     * Decode binary data into a snapshot.
-     */
-    decode(buf) {
-        // Decode tick (first 4 bytes)
-        const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
-        // Decode updates (remaining bytes)
-        const updatesBytes = buf.subarray(4);
-        const updates = this.updatesCodec.decode(updatesBytes);
-        return { tick, updates };
-    }
-}

package/dist/protocol/snapshot/snapshot-registry.js

@@ -1,168 +0,0 @@
-/**
- * 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 {
-    constructor() {
-        this.codecs = new Map();
-        this.typeIds = new Map();
-        this.idToType = new Map();
-        this.nextId = 0;
-    }
-    /**
-     * Register a codec for a specific update type.
-     * Call this once per update type at startup.
-     */
-    register(type, codec) {
-        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(type, snapshot) {
-        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(buf) {
-        // 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);
-        return { type, snapshot: { tick, updates } };
-    }
-    has(type) {
-        return this.codecs.has(type);
-    }
-    getTypes() {
-        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(type, updates) {
-        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/dist/protocol/snapshot/snapshot.js

@@ -1,30 +0,0 @@
-/**
- * Apply snapshot updates to state (mutating).
- * Deep merges objects, replaces arrays.
- *
- * @param state State to update
- * @param snapshot Snapshot to apply
- */
-export function applySnapshot(state, snapshot) {
-    deepMerge(state, snapshot.updates);
-}
-function deepMerge(target, update) {
-    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;
-        }
-        else if (Array.isArray(updateValue)) {
-            target[key] = updateValue;
-        }
-        else if (typeof updateValue === "object" && typeof targetValue === "object") {
-            deepMerge(targetValue, updateValue);
-        }
-        else {
-            target[key] = updateValue;
-        }
-    }
-}

package/src/core/binary-codec/README.md

@@ -1,60 +0,0 @@
-# BinaryCodec
-
-A minimal TypeScript library for **schema-driven binary encoding and decoding**.
-Supports fixed-size numeric fields with automatic buffer sizing.
-
----
-
-## Usage
-
-### Define a schema
-
-```ts
-import { BinaryCodec } from ".";
-
-type Player = {
-  id: number;
-  score: number;
-};
-
-const playerSchema = {
-  id: BinaryCodec.u8,
-  score: BinaryCodec.u16,
-};
-```
-
-### Encode an object
-
-```ts
-const data: Player = { id: 1, score: 420 };
-const buffer = BinaryCodec.encode(playerSchema, data);
-
-console.log(buffer); // Uint8Array [1, 1, 164] (example)
-```
-
-### Decode into an object
-
-```ts
-const target: Player = { id: 0, score: 0 };
-BinaryCodec.decode(playerSchema, buffer, target);
-
-console.log(target); // { id: 1, score: 420 }
-```
-
----
-
-## Features
-
-* Fixed-size fields (`u8`, `u16`, `f32`)
-* Automatic buffer sizing
-* Explicit big-endian encoding
-* Safe, re-entrant, and concurrent-friendly
-* Schema-driven and type-safe
-
----
-
-## Notes
-
-* Object keys define **field order** in the binary layout.
-* Buffer sizes are validated on decode to avoid overflow.
-* Works in browsers and Node.js.