murow 0.0.70 → 0.0.71

package/src/core/events/README.md

@@ -1,47 +0,0 @@
-# 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 });
-```

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

@@ -1,243 +0,0 @@
-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

@@ -1,140 +0,0 @@
-/* ---------- 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

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

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

@@ -1,77 +0,0 @@
-# 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 alpha (0-1)
-  render(ticker.alpha); // for smooth rendering between ticks
-}
-```
-
-## 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 `ticker.alpha` for smooth client-side rendering between fixed ticks (automatically clamped to prevent extrapolation).
-
-## 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.alpha));
-}
-
-// 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

@@ -1,151 +0,0 @@
-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);
-  });
-});