murow 0.0.1

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

@@ -0,0 +1,70 @@
+# Pooled Binary Codec
+
+A small library for efficiently encoding and decoding structured binary data in multiplayer games, with object pooling to minimize allocations.
+
+## Features
+
+* Reusable **object pool** for any type.
+* **PooledEncoder / PooledDecoder** for single objects.
+* **PooledArrayDecoder / PooledArrayEncoder** for arrays of objects.
+* **PooledCodec**: combined encoder + decoder for easy bidirectional use.
+* Supports primitive types (`u8`, `u16`, `i32`, `f32`, etc.), vectors, colors, booleans, and strings.
+* Automatically initializes objects using `toNil()` from the field schema.
+
+## Installation
+
+```ts
+import { PooledCodec, PooledArrayDecoder } from "./pooled-codec.ts";
+import { BinaryPrimitives } from "./binary-primitives.ts";
+```
+
+## Usage Example
+
+```ts
+// Define a position schema
+const PositionSchema = {
+  x: BinaryPrimitives.f32,
+  y: BinaryPrimitives.f32,
+};
+
+// Define a snapshot schema using pooled arrays
+const PositionsCodec = new PooledCodec(PositionSchema);
+
+const SnapshotSchema = {
+  tick: BinaryPrimitives.u16,
+  updates: {
+    positions: PositionsCodec,
+    target: {
+      id: BinaryPrimitives.u32,
+      name: BinaryPrimitives.string(32),
+    },
+  },
+};
+
+// Create pooled codec for snapshots
+const snapshotCodec = new PooledCodec(SnapshotSchema);
+
+// Encode
+const buffer = snapshotCodec.encode({
+  tick: 42,
+  updates: {
+    positions: [
+      { x: 10, y: 20 },
+      { x: 30, y: 40 },
+    ],
+    target: { id: 1, name: "Player1" },
+  },
+});
+
+// Decode
+const snapshot = snapshotCodec.decode(buffer);
+
+// Release pooled objects
+snapshotCodec.release(snapshot);
+```
+
+## Notes
+
+* Use **pooled objects** to reduce garbage collection overhead in fast-paced games.
+* Fields with a `toNil()` method are automatically initialized when acquired from the pool.
+* Suitable for real-time multiplayer snapshots, intents, and any high-frequency data.

package/src/core/pooled-codec/index.ts

@@ -0,0 +1 @@
+export * from './pooled-codec';

package/src/core/pooled-codec/pooled-codec.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ObjectPool,
+  PooledDecoder,
+  PooledEncoder,
+  PooledCodec,
+  PooledArrayDecoder,
+} from "./pooled-codec";
+import { BinaryCodec, BinaryPrimitives, Schema } from "../binary-codec";
+
+describe("ObjectPool", () => {
+  test("should create new object when pool is empty", () => {
+    const pool = new ObjectPool(() => ({ value: 0 }));
+    const obj = pool.acquire();
+    expect(obj).toEqual({ value: 0 });
+  });
+
+  test("should reuse released objects", () => {
+    const pool = new ObjectPool(() => ({ value: 0 }));
+    const obj1 = pool.acquire();
+    obj1.value = 42;
+    pool.release(obj1);
+
+    const obj2 = pool.acquire();
+    expect(obj2.value).toBe(42);
+    expect(obj2).toBe(obj1); // Same object reference
+  });
+
+  test("should handle multiple acquire/release cycles", () => {
+    const pool = new ObjectPool(() => ({ count: 0 }));
+
+    const obj1 = pool.acquire();
+    obj1.count = 1;
+    pool.release(obj1);
+
+    const obj2 = pool.acquire();
+    obj2.count = 2;
+    pool.release(obj2);
+
+    const obj3 = pool.acquire();
+    expect(obj3.count).toBe(2); // Gets the last released object
+  });
+
+  test("should release multiple objects at once", () => {
+    const pool = new ObjectPool(() => ({ id: 0 }));
+
+    const objs = [
+      pool.acquire(),
+      pool.acquire(),
+      pool.acquire(),
+    ];
+
+    objs.forEach((obj, i) => (obj.id = i));
+    pool.releaseAll(objs);
+
+    const reused1 = pool.acquire();
+    const reused2 = pool.acquire();
+    const reused3 = pool.acquire();
+
+    expect([reused1.id, reused2.id, reused3.id].sort()).toEqual([0, 1, 2]);
+  });
+});
+
+describe("PooledDecoder", () => {
+  test("should decode data into pooled objects", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.f32,
+    };
+
+    const decoder = new PooledDecoder(schema);
+
+    // Use BinaryCodec to encode the data first
+    const data = { value: 10.5 };
+    const buffer = BinaryCodec.encode(schema, data);
+
+    const obj = decoder.decode(buffer);
+    expect(obj.value).toBeCloseTo(10.5, 5);
+  });
+
+  test("should reuse released objects", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u32,
+    };
+
+    const decoder = new PooledDecoder(schema);
+
+    const buffer = new Uint8Array(4);
+    const view = new DataView(buffer.buffer);
+    view.setUint32(0, 42, false);
+
+    const obj1 = decoder.decode(buffer);
+    expect(obj1.value).toBe(42);
+
+    decoder.release(obj1);
+
+    view.setUint32(0, 100, false);
+    const obj2 = decoder.decode(buffer);
+    expect(obj2.value).toBe(100);
+    expect(obj2).toBe(obj1); // Same object reference
+  });
+
+  test("should decode into existing target object", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u8,
+    };
+
+    const decoder = new PooledDecoder(schema);
+
+    // Use BinaryCodec to encode the data first
+    const data = { value: 10 };
+    const buffer = BinaryCodec.encode(schema, data);
+    const target = { value: 0 };
+
+    decoder.decodeInto(buffer, target);
+    expect(target.value).toBe(10);
+  });
+});
+
+describe("PooledArrayDecoder", () => {
+  test("should decode multiple buffers into pooled objects", () => {
+    const schema: Schema<{ id: number }> = {
+      id: BinaryPrimitives.u32,
+    };
+
+    const arrayDecoder = new PooledArrayDecoder(schema);
+
+    const buffers = [
+      new Uint8Array([0, 0, 0, 1]),
+      new Uint8Array([0, 0, 0, 2]),
+      new Uint8Array([0, 0, 0, 3]),
+    ];
+
+    const objs = arrayDecoder.decodeAll(buffers);
+    expect(objs.length).toBe(3);
+    expect(objs[0].id).toBe(1);
+    expect(objs[1].id).toBe(2);
+    expect(objs[2].id).toBe(3);
+  });
+
+  test("should release multiple objects", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u8,
+    };
+
+    const arrayDecoder = new PooledArrayDecoder(schema);
+
+    // Use BinaryCodec to encode the data first
+    const buffers = [
+      BinaryCodec.encode(schema, { value: 10 }),
+      BinaryCodec.encode(schema, { value: 20 }),
+      BinaryCodec.encode(schema, { value: 30 }),
+    ];
+
+    const objs = arrayDecoder.decodeAll(buffers);
+    const objValues = objs.map(o => o.value);
+    expect(objValues).toEqual([10, 20, 30]);
+
+    arrayDecoder.releaseAll(objs);
+
+    // Decode again and verify objects are reused (checking references)
+    const newObjs = arrayDecoder.decodeAll(buffers);
+    // Objects should be reused (same references)
+    let reuseCount = 0;
+    for (const newObj of newObjs) {
+      if (objs.includes(newObj)) reuseCount++;
+    }
+    expect(reuseCount).toBeGreaterThan(0);
+  });
+});
+
+describe("PooledEncoder", () => {
+  test("should encode objects into pooled buffers", () => {
+    const schema: Schema<{ x: number; y: number }> = {
+      x: BinaryPrimitives.f32,
+      y: BinaryPrimitives.f32,
+    };
+
+    const encoder = new PooledEncoder(schema);
+    const data = { x: 5.5, y: 10.5 };
+
+    const buffer = encoder.encode(data);
+    expect(buffer.length).toBe(8);
+
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    expect(view.getFloat32(0, false)).toBeCloseTo(5.5, 5);
+    expect(view.getFloat32(4, false)).toBeCloseTo(10.5, 5);
+  });
+
+  test("should reuse released buffers", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u32,
+    };
+
+    const encoder = new PooledEncoder(schema, 16);
+    const data1 = { value: 42 };
+
+    const buffer1 = encoder.encode(data1);
+    encoder.release(buffer1);
+
+    const data2 = { value: 100 };
+    const buffer2 = encoder.encode(data2);
+
+    // Should reuse the same underlying buffer
+    expect(buffer2.buffer).toBe(buffer1.buffer);
+  });
+
+  test("should handle custom buffer size", () => {
+    const schema: Schema<{ id: number }> = {
+      id: BinaryPrimitives.u8,
+    };
+
+    const encoder = new PooledEncoder(schema, 64);
+    const data = { id: 5 };
+
+    const buffer = encoder.encode(data);
+    expect(buffer.length).toBe(1); // Only actual data
+  });
+});
+
+describe("PooledCodec", () => {
+  test("should encode and decode with pooling", () => {
+    const schema: Schema<{ id: number }> = {
+      id: BinaryPrimitives.u32,
+    };
+
+    const codec = new PooledCodec(schema);
+    const data = { id: 123 };
+
+    const encoded = codec.encode(data);
+    const decoded = codec.decode(encoded);
+
+    expect(decoded.id).toBe(123);
+  });
+
+  test("should reuse objects after release", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u32,
+    };
+
+    const codec = new PooledCodec(schema);
+
+    const encoded1 = codec.encode({ value: 42 });
+    const decoded1 = codec.decode(encoded1);
+    expect(decoded1.value).toBe(42);
+
+    codec.release(decoded1);
+
+    const encoded2 = codec.encode({ value: 100 });
+    const decoded2 = codec.decode(encoded2);
+    expect(decoded2.value).toBe(100);
+    expect(decoded2).toBe(decoded1); // Same object
+  });
+
+  test("should handle multiple encode/decode cycles", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u16,
+    };
+
+    const codec = new PooledCodec(schema);
+
+    for (let i = 0; i < 100; i++) {
+      const data = { value: i * 10 };
+      const encoded = codec.encode(data);
+      const decoded = codec.decode(encoded);
+
+      expect(decoded.value).toBe(i * 10);
+
+      codec.release(decoded);
+    }
+  });
+
+  test("should work with single field schemas", () => {
+    const schema: Schema<{
+      id: number;
+    }> = {
+      id: BinaryPrimitives.u32,
+    };
+
+    const codec = new PooledCodec(schema);
+    const data = {
+      id: 999,
+    };
+
+    const encoded = codec.encode(data);
+    const decoded = codec.decode(encoded);
+
+    expect(decoded.id).toBe(999);
+  });
+});
+
+describe("PooledCodec - Memory Efficiency", () => {
+  test("should reduce allocations with pooling", () => {
+    const schema: Schema<{ value: number }> = {
+      value: BinaryPrimitives.u32,
+    };
+
+    const codec = new PooledCodec(schema);
+    const objects: any[] = [];
+
+    const times = 10000;
+
+    // Encode and decode {times} times
+    for (let i = 0; i < times; i++) {
+      const encoded = codec.encode({ value: i });
+      const decoded = codec.decode(encoded);
+      objects.push(decoded);
+    }
+
+    // Release all
+    objects.forEach((obj) => codec.release(obj));
+
+    // Decode again - should reuse objects
+    const newObjects: any[] = [];
+    for (let i = 0; i < times; i++) {
+      const encoded = codec.encode({ value: i });
+      const decoded = codec.decode(encoded);
+      newObjects.push(decoded);
+    }
+
+    // At least some objects should be reused
+    let reusedCount = 0;
+    for (const newObj of newObjects) {
+      if (objects.includes(newObj)) {
+        reusedCount++;
+      }
+    }
+
+    expect(reusedCount).toBeGreaterThan(0);
+  });
+
+  test("should handle concurrent encode/decode without release", () => {
+    const schema: Schema<{ id: number }> = {
+      id: BinaryPrimitives.u16,
+    };
+
+    const codec = new PooledCodec(schema);
+    const objects: any[] = [];
+
+    // Create many objects without releasing
+    for (let i = 0; i < 50; i++) {
+      const encoded = codec.encode({ id: i });
+      const decoded = codec.decode(encoded);
+      objects.push(decoded);
+    }
+
+    expect(objects.length).toBe(50);
+    objects.forEach((obj, i) => expect(obj.id).toBe(i));
+  });
+});

package/src/core/pooled-codec/pooled-codec.ts

@@ -0,0 +1,239 @@
+import { BinaryCodec, Schema } from "../binary-codec";
+
+/**
+ * Generic object pool for reusing objects and minimizing allocations.
+ * @template T Type of objects stored in the pool.
+ */
+export class ObjectPool<T> {
+  private pool: T[] = [];
+
+  /**
+   * @param factory Function to create a new instance when the pool is empty.
+   */
+  constructor(private factory: () => T) { }
+
+  /**
+   * Acquire an object from the pool, or create a new one if empty.
+   * @returns {T} The acquired object.
+   */
+  acquire(): T {
+    return this.pool.pop() ?? this.factory();
+  }
+
+  /**
+   * Return an object to the pool for reuse.
+   * @param {T} obj Object to release.
+   */
+  release(obj: T) {
+    this.pool.push(obj);
+  }
+
+  /**
+   * Return multiple objects to the pool at once.
+   * @param {T[]} objs Array of objects to release.
+   */
+  releaseAll(objs: T[]) {
+    this.pool.push(...objs);
+  }
+}
+
+/**
+ * Pooled decoder for single objects or nested schemas.
+ * @template T Type of object to decode.
+ */
+export class PooledDecoder<T extends object> {
+  private pool: ObjectPool<T>;
+
+  /**
+   * @param schema Schema or record describing the object structure.
+   * @param initial Initial object used as template for pooling.
+   */
+  constructor(private schema: Schema<T> | Record<string, any>) {
+    this.pool = new ObjectPool(() => this.createNil());
+  }
+
+  private createNil(): T {
+    const obj = {} as T;
+    for (const key of Object.keys(this.schema) as (keyof T)[]) {
+      const field = (this.schema as any)[key];
+      obj[key] = "toNil" in field ? field.toNil() : undefined;
+    }
+    return obj;
+  }
+
+  /**
+   * Decode a buffer into a pooled object.
+   * @param {Uint8Array} buf Buffer to decode.
+   * @returns {T} Decoded object.
+   */
+  decode(buf: Uint8Array): T {
+    const obj = this.pool.acquire();
+    this.decodeInto(buf, obj);
+    return obj;
+  }
+
+  /**
+   * Decode a buffer into a provided target object.
+   * @param {Uint8Array} buf Buffer to decode.
+   * @param {T} target Object to write decoded data into.
+   */
+  decodeInto(buf: Uint8Array, target: T) {
+    for (const key of Object.keys(this.schema) as (keyof T)[]) {
+      const field = (this.schema as any)[key];
+      if ("decodeAll" in field) {
+        target[key] = field.decodeAll(buf);
+      } else if ("decode" in field) {
+        target[key] = field.decode(buf);
+      } else {
+        BinaryCodec.decodeInto({ [key]: field } as Schema<T>, buf, target);
+      }
+    }
+  }
+
+  /**
+   * Release a decoded object back to the pool.
+   * @param {T} obj Object to release.
+   */
+  release(obj: T) {
+    this.pool.release(obj);
+  }
+}
+
+/**
+ * Pooled decoder for arrays of objects.
+ * @template T Type of object to decode.
+ */
+export class PooledArrayDecoder<T extends object> {
+  private pooledDecoder: PooledDecoder<T>;
+
+  /**
+   * @param schema Schema or record describing object structure.
+   * @param initial Initial object used as template for pooling.
+   */
+  constructor(schema: Schema<T> | Record<string, any>) {
+    this.pooledDecoder = new PooledDecoder(schema);
+  }
+
+  /**
+   * Decode multiple buffers into pooled objects.
+   * @param {Uint8Array[]} buffers Array of buffers to decode.
+   * @returns {T[]} Array of decoded objects.
+   */
+  decodeAll(buffers: Uint8Array[]): T[] {
+    return buffers.map((b) => this.pooledDecoder.decode(b));
+  }
+
+  /**
+   * Release multiple decoded objects back to the pool.
+   * @param {T[]} objs Array of objects to release.
+   */
+  releaseAll(objs: T[]) {
+    objs.forEach((o) => this.pooledDecoder.release(o));
+  }
+}
+
+/**
+ * Pooled encoder for single objects or nested schemas.
+ * @template T Type of object to encode.
+ */
+export class PooledEncoder<T extends object> {
+  private pool: ObjectPool<Uint8Array>;
+
+  /**
+   * @param schema Schema or record describing object structure.
+   * @param bufferSize Size of buffer to allocate per encoding (default: 1024).
+   */
+  constructor(private schema: Schema<T> | Record<string, any>, private bufferSize = 1024) {
+    this.pool = new ObjectPool(() => new Uint8Array(bufferSize));
+  }
+
+  /**
+   * Encode an object into a pooled buffer.
+   * @param {T} obj Object to encode.
+   * @returns {Uint8Array} Encoded buffer.
+   */
+  encode(obj: T): Uint8Array {
+    const buf = this.pool.acquire();
+    let offset = 0;
+
+    for (const key of Object.keys(this.schema) as (keyof T)[]) {
+      const field = (this.schema as any)[key];
+
+      if ("encode" in field) {
+        const nested = field.encode(obj[key]);
+        buf.set(nested, offset);
+        offset += nested.length;
+      } else if ("encodeAll" in field) {
+        const nestedArr = field.encodeAll(obj[key]);
+        let arrOffset = 0;
+        for (const item of nestedArr) {
+          buf.set(item, offset + arrOffset);
+          arrOffset += item.length;
+        }
+        offset += arrOffset;
+      } else {
+        const tmp = BinaryCodec.encode({ [key]: field }, { [key]: obj[key] });
+        buf.set(tmp, offset);
+        offset += tmp.length;
+      }
+    }
+
+    return buf.subarray(0, offset);
+  }
+
+  /**
+   * Release a buffer back to the pool.
+   * @param {Uint8Array} buf Buffer to release.
+   */
+  release(buf: Uint8Array) {
+    this.pool.release(buf);
+  }
+}
+
+/**
+ * Combined pooled encoder and decoder for a single schema.
+ * Provides a convenient wrapper around PooledEncoder and PooledDecoder.
+ * @template T Type of object to encode/decode.
+ */
+export class PooledCodec<T extends object> {
+  /** Pooled encoder for the schema */
+  encoder: PooledEncoder<T>;
+
+  /** Pooled decoder for the schema */
+  decoder: PooledDecoder<T>;
+
+  /**
+   * @param schema Schema describing the object structure.
+   * @param initial Initial object used as a template for pooling decoded objects.
+   */
+  constructor(schema: Schema<T>) {
+    this.encoder = new PooledEncoder(schema);
+    this.decoder = new PooledDecoder(schema);
+  }
+
+  /**
+   * Encode an object into a pooled buffer.
+   * @param {T} data Object to encode.
+   * @returns {Uint8Array} Encoded buffer.
+   */
+  encode(data: T) {
+    return this.encoder.encode(data);
+  }
+
+  /**
+   * Decode a buffer into a pooled object.
+   * @param {Uint8Array} buf Buffer to decode.
+   * @returns {T} Decoded object.
+   */
+  decode(buf: Uint8Array) {
+    return this.decoder.decode(buf);
+  }
+
+  /**
+   * Release a decoded object back to the pool.
+   * @param {T} obj Object to release.
+   */
+  release(obj: T) {
+    this.decoder.release(obj);
+  }
+}