murow 0.0.1

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

@@ -0,0 +1,430 @@
+/**
+ * A binary field descriptor.
+ * Defines how a single value is serialized/deserialized
+ * at a fixed byte size.
+ */
+export type Field<T> = {
+  /** Size of the field in bytes */
+  size: number;
+
+  /**
+   * Writes a value into a DataView at the given offset.
+   * @param dv DataView to write into
+   * @param o Byte offset
+   * @param v Value to write
+   */
+  write(dv: DataView, o: number, v: T): void;
+
+  /**
+   * Reads a value from a DataView at the given offset.
+   * @param dv DataView to read from
+   * @param o Byte offset
+   */
+  read(dv: DataView, o: number): T;
+
+  /**
+   * Returns the nil value
+   */
+  toNil(): T;
+};
+
+/**
+ * A schema mapping object keys to binary fields.
+ * The order of iteration defines the binary layout.
+ *
+ * IMPORTANT:
+ * Property order is respected as insertion order.
+ * Do not rely on computed or dynamic keys.
+ */
+export type Schema<T> = {
+  [K in keyof T]: Field<T[K]>;
+};
+
+/**
+ * Internal symbol used to cache computed schema byte size.
+ */
+const SCHEMA_SIZE = Symbol("schemaSize");
+
+/**
+ * Computes and caches the total byte size of a schema.
+ * @param schema Binary schema definition
+ */
+function getSchemaSize<T extends object>(schema: Schema<T>): number {
+  const cached = (schema as any)[SCHEMA_SIZE];
+  if (cached !== undefined) return cached;
+
+  let size = 0;
+  for (const k of Object.keys(schema) as (keyof T)[]) {
+    size += schema[k].size;
+  }
+
+  (schema as any)[SCHEMA_SIZE] = size;
+  return size;
+}
+
+/**
+ * Base codec implementation.
+ * Handles schema-driven encoding/decoding.
+ */
+export class BaseBinaryCodec {
+  /**
+   * Encodes an object into a binary buffer using the given schema.
+   *
+   * Allocates a right-sized buffer per call.
+   * Safe for concurrent and re-entrant usage.
+   *
+   * @param schema Binary schema definition
+   * @param data Object to encode
+   * @returns A Uint8Array containing the encoded bytes
+   */
+  protected static encodeInto<T extends object>(
+    schema: Schema<T>,
+    data: T
+  ): Uint8Array {
+    const size = getSchemaSize(schema);
+    const buffer = new ArrayBuffer(size);
+    const view = new DataView(buffer);
+
+    let o = 0;
+    for (const k of Object.keys(schema) as (keyof T)[]) {
+      const f = schema[k];
+      f.write(view, o, data[k]);
+      o += f.size;
+    }
+
+    return new Uint8Array(buffer);
+  }
+
+  /**
+   * Decodes a binary buffer into a target object using the given schema.
+   *
+   * Validates buffer size before reading.
+   * Does not mutate shared state.
+   *
+   * @param schema Binary schema definition
+   * @param buf Buffer containing encoded data
+   * @param target Target object to mutate
+   * @returns The mutated target object
+   */
+  static decodeInto<T extends object>(
+    schema: Schema<T>,
+    buf: Uint8Array,
+    target: T
+  ): T {
+    const expectedSize = getSchemaSize(schema);
+
+    if (buf.byteLength < expectedSize) {
+      throw new RangeError(
+        `Buffer too small: expected ${expectedSize} bytes, got ${buf.byteLength}`
+      );
+    }
+
+    const view = new DataView(
+      buf.buffer,
+      buf.byteOffset,
+      buf.byteLength
+    );
+
+    let o = 0;
+    for (const k of Object.keys(schema) as (keyof T)[]) {
+      const f = schema[k];
+      target[k] = f.read(view, o);
+      o += f.size;
+    }
+
+    return target;
+  }
+}
+
+/**
+ * Built-in binary primitive field definitions for multiplayer games.
+ */
+export class BinaryPrimitives {
+  /** Unsigned 8-bit integer */
+  static readonly u8: Field<number> = {
+    size: 1,
+    write: (dv, o, v) => dv.setUint8(o, v),
+    read: (dv, o) => dv.getUint8(o),
+    toNil: () => 0,
+  };
+
+  /** Unsigned 16-bit integer (big-endian) */
+  static readonly u16: Field<number> = {
+    size: 2,
+    write: (dv, o, v) => dv.setUint16(o, v, false),
+    read: (dv, o) => dv.getUint16(o, false),
+    toNil: () => 0,
+  };
+
+  /** Unsigned 32-bit integer (big-endian) */
+  static readonly u32: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setUint32(o, v, false),
+    read: (dv, o) => dv.getUint32(o, false),
+    toNil: () => 0,
+  };
+
+  /** Signed 8-bit integer */
+  static readonly i8: Field<number> = {
+    size: 1,
+    write: (dv, o, v) => dv.setInt8(o, v),
+    read: (dv, o) => dv.getInt8(o),
+    toNil: () => 0,
+  };
+
+  /** Signed 16-bit integer (big-endian) */
+  static readonly i16: Field<number> = {
+    size: 2,
+    write: (dv, o, v) => dv.setInt16(o, v, false),
+    read: (dv, o) => dv.getInt16(o, false),
+    toNil: () => 0,
+  };
+
+  /** Signed 32-bit integer (big-endian) */
+  static readonly i32: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setInt32(o, v, false),
+    read: (dv, o) => dv.getInt32(o, false),
+    toNil: () => 0,
+  };
+
+  /** 32-bit floating point number (IEEE 754, big-endian) */
+  static readonly f32: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setFloat32(o, v, false),
+    read: (dv, o) => dv.getFloat32(o, false),
+    toNil: () => 0,
+  };
+
+  /** 64-bit floating point number (double, big-endian) */
+  static readonly f64: Field<number> = {
+    size: 8,
+    write: (dv, o, v) => dv.setFloat64(o, v, false),
+    read: (dv, o) => dv.getFloat64(o, false),
+    toNil: () => 0,
+  };
+
+  /** Boolean stored as 1 byte (0 = false, 1 = true) */
+  static readonly bool: Field<boolean> = {
+    size: 1,
+    write: (dv, o, v) => dv.setUint8(o, v ? 1 : 0),
+    read: (dv, o) => dv.getUint8(o) !== 0,
+    toNil: () => false,
+  };
+
+  /**
+   * String field with UTF-8 encoding and 2-byte length prefix.
+   * @param maxLength Maximum number of bytes allowed
+   */
+  static string(maxLength: number): Field<string> {
+    return {
+      size: maxLength + 2,
+      write(dv, o, v) {
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(v);
+        if (bytes.length > maxLength)
+          throw new RangeError(`String too long, max ${maxLength} bytes`);
+        dv.setUint16(o, bytes.length, false);
+        for (let i = 0; i < bytes.length; i++) dv.setUint8(o + 2 + i, bytes[i]);
+        for (let i = bytes.length; i < maxLength; i++) dv.setUint8(o + 2 + i, 0);
+      },
+      read(dv, o) {
+        const length = dv.getUint16(o, false);
+        const bytes = new Uint8Array(length);
+        for (let i = 0; i < length; i++) bytes[i] = dv.getUint8(o + 2 + i);
+        return new TextDecoder().decode(bytes);
+      },
+      toNil: () => "",
+    };
+  }
+
+  /** 2D vector of f32 (x, y) */
+  static readonly vec2: Field<{ x: number; y: number }> = {
+    size: 8,
+    write(dv, o, v) {
+      dv.setFloat32(o, v.x, false);
+      dv.setFloat32(o + 4, v.y, false);
+    },
+    read(dv, o) {
+      return { x: dv.getFloat32(o, false), y: dv.getFloat32(o + 4, false) };
+    },
+    toNil: () => ({ x: 0, y: 0 }),
+  };
+
+  /** 3D vector of f32 (x, y, z) */
+  static readonly vec3: Field<{ x: number; y: number; z: number }> = {
+    size: 12,
+    write(dv, o, v) {
+      dv.setFloat32(o, v.x, false);
+      dv.setFloat32(o + 4, v.y, false);
+      dv.setFloat32(o + 8, v.z, false);
+    },
+    read(dv, o) {
+      return {
+        x: dv.getFloat32(o, false),
+        y: dv.getFloat32(o + 4, false),
+        z: dv.getFloat32(o + 8, false),
+      };
+    },
+    toNil: () => ({ x: 0, y: 0, z: 0 }),
+  };
+
+  /** RGBA color packed as 4 u8 bytes */
+  static readonly color: Field<{ r: number; g: number; b: number; a: number }> = {
+    size: 4,
+    write(dv, o, v) {
+      dv.setUint8(o, v.r);
+      dv.setUint8(o + 1, v.g);
+      dv.setUint8(o + 2, v.b);
+      dv.setUint8(o + 3, v.a);
+    },
+    read(dv, o) {
+      return {
+        r: dv.getUint8(o),
+        g: dv.getUint8(o + 1),
+        b: dv.getUint8(o + 2),
+        a: dv.getUint8(o + 3),
+      };
+    },
+    toNil: () => ({ r: 0, g: 0, b: 0, a: 0 }),
+  };
+
+  /** 32-bit floating point number (IEEE 754, little-endian) */
+  static readonly f32_le: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setFloat32(o, v, true),
+    read: (dv, o) => dv.getFloat32(o, true),
+    toNil: () => 0,
+  };
+
+  /** 64-bit floating point number (double, little-endian) */
+  static readonly f64_le: Field<number> = {
+    size: 8,
+    write: (dv, o, v) => dv.setFloat64(o, v, true),
+    read: (dv, o) => dv.getFloat64(o, true),
+    toNil: () => 0,
+  };
+
+  /** Unsigned 16-bit integer (little-endian) */
+  static readonly u16_le: Field<number> = {
+    size: 2,
+    write: (dv, o, v) => dv.setUint16(o, v, true),
+    read: (dv, o) => dv.getUint16(o, true),
+    toNil: () => 0,
+  };
+
+  /** Unsigned 32-bit integer (little-endian) */
+  static readonly u32_le: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setUint32(o, v, true),
+    read: (dv, o) => dv.getUint32(o, true),
+    toNil: () => 0,
+  };
+
+  /** Signed 16-bit integer (little-endian) */
+  static readonly i16_le: Field<number> = {
+    size: 2,
+    write: (dv, o, v) => dv.setInt16(o, v, true),
+    read: (dv, o) => dv.getInt16(o, true),
+    toNil: () => 0,
+  };
+
+  /** Signed 32-bit integer (little-endian) */
+  static readonly i32_le: Field<number> = {
+    size: 4,
+    write: (dv, o, v) => dv.setInt32(o, v, true),
+    read: (dv, o) => dv.getInt32(o, true),
+    toNil: () => 0,
+  };
+
+  /**
+   * 2D vector of f32 stored as a tuple [x, y] (little-endian).
+   * Useful for compact math data or shader-friendly layouts.
+   */
+  static readonly vec2_le: Field<[number, number]> = {
+    size: 8,
+    write: (dv, o, v) => {
+      dv.setFloat32(o, v[0], true);
+      dv.setFloat32(o + 4, v[1], true);
+    },
+    read: (dv, o) => [
+      dv.getFloat32(o, true),
+      dv.getFloat32(o + 4, true),
+    ],
+    toNil: () => [0, 0],
+  };
+
+  /**
+   * 3D vector of f32 stored as a tuple [x, y, z] (little-endian).
+   * Commonly used for positions, velocities, or directions.
+   */
+  static readonly vec3_le: Field<[number, number, number]> = {
+    size: 12,
+    write: (dv, o, v) => {
+      dv.setFloat32(o, v[0], true);
+      dv.setFloat32(o + 4, v[1], true);
+      dv.setFloat32(o + 8, v[2], true);
+    },
+    read: (dv, o) => [
+      dv.getFloat32(o, true),
+      dv.getFloat32(o + 4, true),
+      dv.getFloat32(o + 8, true),
+    ],
+    toNil: () => [0, 0, 0],
+  };
+
+  /**
+   * 4D vector of f32 stored as a tuple [x, y, z, w] (little-endian).
+   * Useful for quaternions, colors in shaders, or homogeneous coordinates.
+   */
+  static readonly vec4_le: Field<[number, number, number, number]> = {
+    size: 16,
+    write: (dv, o, v) => {
+      dv.setFloat32(o, v[0], true);
+      dv.setFloat32(o + 4, v[1], true);
+      dv.setFloat32(o + 8, v[2], true);
+      dv.setFloat32(o + 12, v[3], true);
+    },
+    read: (dv, o) => [
+      dv.getFloat32(o, true),
+      dv.getFloat32(o + 4, true),
+      dv.getFloat32(o + 8, true),
+      dv.getFloat32(o + 12, true),
+    ],
+    toNil: () => [0, 0, 0, 0],
+  };
+}
+
+/**
+ * Public codec API.
+ * Re-exports primitives and exposes encode/decode helpers.
+ */
+export class BinaryCodec extends BaseBinaryCodec {
+  /** Unsigned 8-bit integer field */
+  static readonly u8 = BinaryPrimitives.u8;
+  /** Unsigned 16-bit integer field */
+  static readonly u16 = BinaryPrimitives.u16;
+  /** 32-bit floating point field */
+  static readonly f32 = BinaryPrimitives.f32;
+
+  /**
+   * Encodes an object into a binary buffer.
+   */
+  static encode<T extends object>(
+    schema: Schema<T>,
+    data: T
+  ): Uint8Array {
+    return this.encodeInto(schema, data);
+  }
+
+  /**
+   * Decodes a binary buffer into an existing object.
+   */
+  static decode<T extends object>(
+    schema: Schema<T>,
+    buf: Uint8Array,
+    target: T
+  ): T {
+    return this.decodeInto(schema, buf, target);
+  }
+}

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

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

package/src/core/events/README.md

@@ -0,0 +1,47 @@
+# EventSystem
+
+`EventSystem` is a callback-based event handling system designed to simplify event-driven programming.
+It allows you to register, emit, and manage events with flexible callback support, making it easy to build modular and decoupled applications.
+
+## Features
+
+- Register Callbacks: Attach functions to specific events using `on`.
+- One-Time Listeners: Use `once` to register callbacks that run only once.
+- Emit Events: Trigger events with optional data using `emit`.
+- Remove Callbacks: Detach specific callbacks with `off`.
+- Clear Events: Remove all callbacks globally or for specific events with `clear`.
+
+## Why use this?
+
+Callbacks are often way faster than events, on both the browser and node, but they are also harder to manage. This system allows you to use callbacks in a more event-like way, and it is TypeScript-friendly, offering strong type safety for event names and payloads when using EventTuple definitions.
+
+### Source
+
+Benchmarks:
+
+- https://jsbench.me/qmkkfcfpcw/2
+- https://hackernoon.com/nodejs-48x-faster-if-you-go-back-to-callbacks
+
+## Usage
+
+```ts
+import { EventSystem } from "...";
+
+interface FooProps {
+  foo: string;
+}
+
+interface BarProps {
+  bar: number;
+}
+
+const events = new EventSystem<[["foo", FooProps], ["bar", BarProps]]>({
+  events: ["foo", "bar"],
+});
+
+events.on("bar", ({ bar }) => {
+  console.log("bar event listened", bar);
+});
+
+events.emit("bar", { bar: 42 });
+```