murow 0.0.1

package/src/core/events/event-system.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, test, spyOn } from "bun:test";
+import { EventSystem } from "./event-system";
+
+type TestEvents = [
+  ["userJoined", { userId: string; name: string }],
+  ["userLeft", { userId: string }],
+  ["messageReceived", { from: string; message: string }],
+  ["scoreUpdated", { playerId: string; score: number }]
+];
+
+describe("EventSystem", () => {
+  test("should initialize with provided events", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined", "userLeft"],
+    });
+    expect(events).toBeDefined();
+  });
+
+  test("should register and call event callback", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    let called = false;
+    events.on("userJoined", (data) => {
+      called = true;
+      expect(data.userId).toBe("123");
+      expect(data.name).toBe("Alice");
+    });
+
+    events.emit("userJoined", { userId: "123", name: "Alice" });
+    expect(called).toBe(true);
+  });
+
+  test("should call multiple callbacks for same event", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    let count = 0;
+    events.on("userJoined", () => count++);
+    events.on("userJoined", () => count++);
+    events.on("userJoined", () => count++);
+
+    events.emit("userJoined", { userId: "123", name: "Bob" });
+    expect(count).toBe(3);
+  });
+
+  test("should handle once() callback that runs only once", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["messageReceived"],
+    });
+
+    let count = 0;
+    events.once("messageReceived", () => count++);
+
+    events.emit("messageReceived", { from: "Alice", message: "Hello" });
+    events.emit("messageReceived", { from: "Bob", message: "Hi" });
+    events.emit("messageReceived", { from: "Charlie", message: "Hey" });
+
+    expect(count).toBe(1);
+  });
+
+  test("should remove callback with off()", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["scoreUpdated"],
+    });
+
+    let count = 0;
+    const callback = () => count++;
+
+    events.on("scoreUpdated", callback);
+    events.emit("scoreUpdated", { playerId: "p1", score: 100 });
+    expect(count).toBe(1);
+
+    events.off("scoreUpdated", callback);
+    events.emit("scoreUpdated", { playerId: "p1", score: 200 });
+    expect(count).toBe(1); // Should still be 1
+  });
+
+  test("should clear specific event callbacks", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined", "userLeft"],
+    });
+
+    let joinCount = 0;
+    let leaveCount = 0;
+
+    events.on("userJoined", () => joinCount++);
+    events.on("userJoined", () => joinCount++);
+    events.on("userLeft", () => leaveCount++);
+
+    events.clear("userJoined");
+
+    events.emit("userJoined", { userId: "123", name: "Alice" });
+    events.emit("userLeft", { userId: "123" });
+
+    expect(joinCount).toBe(0);
+    expect(leaveCount).toBe(1);
+  });
+
+  test("should clear all event callbacks", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined", "userLeft", "messageReceived"],
+    });
+
+    let count = 0;
+    events.on("userJoined", () => count++);
+    events.on("userLeft", () => count++);
+    events.on("messageReceived", () => count++);
+
+    events.clear();
+
+    events.emit("userJoined", { userId: "123", name: "Alice" });
+    events.emit("userLeft", { userId: "123" });
+    events.emit("messageReceived", { from: "Alice", message: "Hi" });
+
+    expect(count).toBe(0);
+  });
+
+  test("should warn when registering callback for non-existent event", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    const consoleWarn = spyOn(console, "warn");
+    // @ts-expect-error Testing invalid event name
+    events.on("nonExistent", () => {});
+    expect(consoleWarn).toHaveBeenCalledWith('Event "nonExistent" does not exist.');
+    consoleWarn.mockRestore();
+  });
+
+  test("should warn when emitting non-existent event", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    const consoleWarn = spyOn(console, "warn");
+    // @ts-expect-error Testing invalid event name
+    events.emit("nonExistent", {});
+    expect(consoleWarn).toHaveBeenCalledWith('Event "nonExistent" does not exist.');
+    consoleWarn.mockRestore();
+  });
+
+  test("should pass correct data to callbacks", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["scoreUpdated"],
+    });
+
+    const receivedData: Array<{ playerId: string; score: number }> = [];
+    events.on("scoreUpdated", (data) => receivedData.push(data));
+
+    events.emit("scoreUpdated", { playerId: "p1", score: 100 });
+    events.emit("scoreUpdated", { playerId: "p2", score: 200 });
+
+    expect(receivedData).toEqual([
+      { playerId: "p1", score: 100 },
+      { playerId: "p2", score: 200 },
+    ]);
+  });
+
+  test("should handle callbacks that throw errors", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    let successCount = 0;
+    events.on("userJoined", () => {
+      throw new Error("Callback error");
+    });
+    events.on("userJoined", () => successCount++);
+
+    expect(() =>
+      events.emit("userJoined", { userId: "123", name: "Alice" })
+    ).toThrow();
+
+    // First callback threw, so second wasn't reached
+    expect(successCount).toBe(0);
+  });
+
+  test("should maintain callback order", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["messageReceived"],
+    });
+
+    const order: number[] = [];
+    events.on("messageReceived", () => order.push(1));
+    events.on("messageReceived", () => order.push(2));
+    events.on("messageReceived", () => order.push(3));
+
+    events.emit("messageReceived", { from: "Test", message: "Hello" });
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  test("should allow same callback to be registered multiple times", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    let count = 0;
+    const callback = () => count++;
+
+    events.on("userJoined", callback);
+    events.on("userJoined", callback);
+
+    events.emit("userJoined", { userId: "123", name: "Alice" });
+    // Set only stores unique callbacks, so it should be called once
+    expect(count).toBe(1);
+  });
+
+  test("should handle rapid event emissions", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["scoreUpdated"],
+    });
+
+    let count = 0;
+    events.on("scoreUpdated", () => count++);
+
+    for (let i = 0; i < 1000; i++) {
+      events.emit("scoreUpdated", { playerId: "p1", score: i });
+    }
+
+    expect(count).toBe(1000);
+  });
+
+  test("should handle once() with multiple callbacks", () => {
+    const events = new EventSystem<TestEvents>({
+      events: ["userJoined"],
+    });
+
+    let count1 = 0;
+    let count2 = 0;
+
+    events.once("userJoined", () => count1++);
+    events.on("userJoined", () => count2++);
+
+    events.emit("userJoined", { userId: "123", name: "Alice" });
+    events.emit("userJoined", { userId: "456", name: "Bob" });
+
+    expect(count1).toBe(1);
+    expect(count2).toBe(2);
+  });
+});

package/src/core/events/event-system.ts

@@ -0,0 +1,140 @@
+/* ---------- Types ---------- */
+type Callback<Props> = (props: Props) => void;
+
+
+type EventMapFromTuple<T extends [string, unknown][]> = {
+    [K in T[number]as K[0]]: K[1];
+};
+
+/* ---------- Interfaces ---------- */
+interface EventSystemProps<EventNames extends string> {
+    /**
+     * @description
+     * The list of events to ever be registered.
+     */
+    events: EventNames[];
+}
+
+/**
+ * @description
+ * A callback-based event handling system designed to simplify 
+ * event-driven programming.
+ */
+export class EventSystem<EventTuple extends [string, unknown][]> {
+    /**
+     * @private
+     * @description
+     * The map of registered events and their callbacks.
+    */
+    private callbacks: Map<string, Set<Callback<unknown>>>;
+
+    /**
+     * @private
+     * @description
+     * The list of events that were registered.
+    */
+    private events: string[];
+
+    constructor({ events }: EventSystemProps<string>) {
+        this.callbacks = new Map();
+        this.events = events;
+
+        for (const name of this.events) {
+            this.callbacks.set(name, new Set());
+        }
+    }
+
+    /**
+     * @description
+     * Registers a callback for an event.
+     *
+     * @param name Event name
+     * @param callback Callback to run when the event is emitted
+     */
+    on<EventName extends keyof EventMapFromTuple<EventTuple> & string>(
+        name: EventName,
+        callback: Callback<EventMapFromTuple<EventTuple>[EventName]>
+    ): void {
+        const event = this.callbacks.get(name) as Set<Callback<EventMapFromTuple<EventTuple>[EventName]>> | undefined;
+        if (!event) return console.warn(`Event "${name}" does not exist.`);
+
+        event.add(callback);
+    }
+
+    /**
+     * @description
+     * Registers a callback for an event that runs only once.
+     *
+     * @param name Event name
+     * @param callback Callback to run when the event is emitted
+     */
+    once<EventName extends keyof EventMapFromTuple<EventTuple> & string>(
+        name: EventName,
+        callback: Callback<EventMapFromTuple<EventTuple>[EventName]>
+    ): void {
+        const wrapper: Callback<EventMapFromTuple<EventTuple>[EventName]> = (props) => {
+            callback(props);
+            this.off(name, wrapper);
+        };
+
+        this.on(name, wrapper);
+    }
+
+    /**
+     * @description
+     * Emits an event, running all registered callbacks.
+     *
+     * @param name Event name
+     * @param data Event data
+     */
+    emit<EventName extends keyof EventMapFromTuple<EventTuple> & string>(
+        name: EventName,
+        data: EventMapFromTuple<EventTuple>[EventName]
+    ) {
+        const event = this.callbacks.get(name);
+        if (!event) return console.warn(`Event "${name}" does not exist.`);
+
+        for (const callback of event) {
+            callback(data);
+        }
+    }
+
+    /**
+     * @description
+     * Removes a callback from an event.
+     *
+     * @param name Event name
+     * @param callback Callback to remove
+     */
+    off<EventName extends keyof EventMapFromTuple<EventTuple> & string>(
+        name: EventName,
+        callback: Callback<EventMapFromTuple<EventTuple>[EventName]>
+    ): void {
+        const event = this.callbacks.get(name) as Set<Callback<EventMapFromTuple<EventTuple>[EventName]>> | undefined;
+        if (!event) return console.warn(`Event "${name}" does not exist.`);
+
+        event.delete(callback);
+    }
+
+    /**
+     * @description
+     * Removes all callbacks.
+     *
+     * @param name Optional event name
+     */
+    clear<EventName extends keyof EventMapFromTuple<EventTuple> & string>(name?: EventName): void {
+        if (!name) {
+            this.callbacks.clear();
+            for (const name of this.events) {
+                this.callbacks.set(name, new Set());
+            }
+
+            return;
+        }
+
+        const event = this.callbacks.get(name);
+        if (!event) return console.warn(`Event "${name}" does not exist.`);
+
+        event.clear();
+    }
+}

package/src/core/events/index.ts

@@ -0,0 +1 @@
+export * from './event-system';

package/src/core/fixed-ticker/README.md

@@ -0,0 +1,77 @@
+# FixedTicker
+
+`FixedTicker` is a utility class for managing fixed-rate update ticks in JavaScript/TypeScript applications. It is designed for deterministic game loops, working both in the browser (e.g., with Pixi.js) and on Node.js servers.
+
+This class ensures that updates run at a fixed timestep, which is essential for predictable, lockstep multiplayer simulations.
+
+---
+
+## Features
+
+- Fixed-timestep updates with configurable tick rate.
+- Accumulates elapsed time and determines how many ticks to process per frame.
+- Limits the maximum number of ticks per frame to prevent runaway loops.
+- Provides a tick count for deterministic simulation.
+- Optional callback for detecting skipped ticks (useful for debugging or network reconciliation).
+- Compatible with both client and server environments.
+
+## Usage
+
+```typescript
+import { FixedTicker } from './fixed-ticker';
+
+const ticker = new FixedTicker({
+  rate: 30, // ticks per second
+  onTick: (deltaTime, tick) => {
+    // Your fixed-step game logic here
+    // deltaTime = 1 / rate
+    console.log(`Tick ${tick} - dt: ${deltaTime}`);
+  },
+  onTickSkipped: (skipped) => {
+    console.warn(`Skipped ${skipped} ticks due to high delta time`);
+  }
+});
+
+// Call once per frame, passing elapsed time in seconds
+function gameLoop(deltaTime: number) {
+  ticker.tick(deltaTime);
+
+  // Optional: interpolate visuals using accumulatedTime
+  const alpha = ticker.accumulatedTime / (1 / 30); // for smooth rendering
+}
+```
+
+## Notes
+
+- This class does not automatically guarantee determinism; your game logic must also be deterministic (e.g., using seeded random numbers and consistent math operations).
+- For lockstep multiplayer, always use the tickCount to synchronize inputs and simulation steps.
+- Use accumulatedTime for smooth client-side rendering between fixed ticks.
+
+## Example: Deterministic Multiplayer Loop
+
+```typescript
+const ticker = new FixedTicker({
+  rate: 12, // will fire the onTick callback 12 times per second
+  onTick: (deltaTime, tick) => {
+    applyInputsForTick(tick);
+    updateSimulation(deltaTime);
+  }
+});
+
+// in browser
+function frame(deltaTime: number) {
+  ticker.tick(deltaTime);
+  render(interpolate(ticker.accumulatedTime));
+}
+
+// in Node.js
+setInterval(() => {
+  const deltaTime = 1 / ticker.rate; // fixed timestep
+  ticker.tick(deltaTime);
+  updateSimulation(deltaTime);
+}, 1000 / ticker.rate);
+```
+
+---
+
+`FixedTicker` provides a reliable, minimal, and deterministic foundation for game loops and simulations where consistent, fixed-step updates are crucial.

package/src/core/fixed-ticker/fixed-ticker.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from "bun:test";
+import { FixedTicker } from "./fixed-ticker";
+
+describe("FixedTicker", () => {
+  test("should initialize with correct rate", () => {
+    const ticker = new FixedTicker({ rate: 60, onTick: () => { } });
+    expect(ticker.rate).toBe(60);
+  });
+
+  test("should call onTick with correct deltaTime", () => {
+    let calledDelta = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: (dt) => {
+        calledDelta = dt;
+      },
+    });
+
+    ticker.tick(1 / 60);
+    expect(calledDelta).toBeCloseTo(1 / 60, 5);
+  });
+
+  test("should accumulate time and execute multiple ticks", () => {
+    let tickCount = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => {
+        tickCount++;
+      },
+    });
+
+    // Simulate 3 frames worth of time (add small epsilon for floating point)
+    ticker.tick(3.01 / 60);
+    expect(tickCount).toBe(3);
+  });
+
+  test("should track tick count correctly", () => {
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => { },
+    });
+
+    ticker.tick(5.01 / 60);
+    expect(ticker.tickCount).toBe(5);
+  });
+
+  test("should reset tick count", () => {
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => { },
+    });
+
+    ticker.tick(3.01 / 60);
+    expect(ticker.tickCount).toBe(3);
+
+    ticker.resetTickCount();
+    expect(ticker.tickCount).toBe(0);
+  });
+
+  test("should pass tick number to onTick callback", () => {
+    const tickNumbers: number[] = [];
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: (_dt, tick) => {
+        if (tick !== undefined) tickNumbers.push(tick);
+      },
+    });
+
+    ticker.tick(3.01 / 60);
+    expect(tickNumbers).toEqual([0, 1, 2]);
+  });
+
+  test("should limit ticks per frame to maxTicksPerFrame", () => {
+    let tickCount = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => {
+        tickCount++;
+      },
+    });
+
+    // Simulate a huge delta time (2 seconds)
+    ticker.tick(2);
+    // maxTicksPerFrame should be Math.max(1, Math.floor(60 / 2)) = 30
+    expect(tickCount).toBe(30);
+  });
+
+  test("should provide accumulated time", () => {
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => { },
+    });
+
+    // Give it 1.5 ticks worth of time
+    ticker.tick(1.5 / 60);
+    expect(ticker.accumulatedTime).toBeCloseTo(0.5 / 60, 5);
+  });
+
+  test("should call onTickSkipped when ticks are skipped", () => {
+    let skippedCount = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => { },
+    });
+
+    // Access the private onTickSkipped through constructor
+    const tickerWithSkip = new FixedTicker({
+      rate: 60,
+      onTick: () => { },
+    });
+
+    // Monkey patch to add onTickSkipped
+    (tickerWithSkip as any).onTickSkipped = (count: number) => {
+      skippedCount = count;
+    };
+
+    // Simulate huge delta that exceeds maxTicksPerFrame
+    tickerWithSkip.tick(2);
+    expect(skippedCount).toBeGreaterThan(0);
+  });
+
+  test("should handle zero delta time", () => {
+    let tickCount = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => {
+        tickCount++;
+      },
+    });
+
+    ticker.tick(0);
+    expect(tickCount).toBe(0);
+    expect(ticker.tickCount).toBe(0);
+  });
+
+  test("should handle very small delta times", () => {
+    let tickCount = 0;
+    const ticker = new FixedTicker({
+      rate: 60,
+      onTick: () => {
+        tickCount++;
+      },
+    });
+
+    // Simulate 100 very small frames that add up to slightly more than 1 tick
+    for (let i = 0; i < 100; i++) {
+      ticker.tick(1.01 / 60 / 100);
+    }
+    expect(tickCount).toBe(1);
+  });
+});