Feat/data structures

.changeset/eager-spiders-divide.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Add vector2 implementation.

.changeset/famous-books-teach.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Added dot and cross product to vector3

.changeset/fast-chefs-cough.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Add vector3 implementation.

.changeset/fine-numbers-vanish.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': patch
+---
+
+Remove jsdoc types in math utils in favor of ts types.

.changeset/little-ghosts-give.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Add type-safe EventDispatcher implementation.

.changeset/nasty-colts-cut.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Added dot product to vector2

.changeset/true-adults-give.md

@@ -0,0 +1,5 @@
+---
+'@bengsfort/stdlib': minor
+---
+
+Add support for 2d ray collisions.

lib/diagnostics/measure.ts

@@ -0,0 +1,5 @@
+export class Measure {
+  public readonly id: string;
+  #_start: number;
+  #_end: number;
+}

lib/events/__tests__/event-dispatcher.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { EventDispatcher, EventMap } from '../event-dispatcher.js';
+
+interface TestEventMap extends EventMap {
+  foo: [value: number, bool: boolean];
+  bar: [str: string];
+  gaz: [];
+}
+
+describe('EventDispatcher', () => {
+  it('should expose how many listeners are currently attached', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+
+    expect(dispatch.getListenerCount()).toEqual(0);
+
+    const onFoo = vi.fn();
+    const onBar = vi.fn();
+
+    dispatch.addListener('foo', onFoo);
+    dispatch.addListener('bar', onBar);
+    expect(dispatch.getListenerCount()).toEqual(2);
+
+    dispatch.removeListener('foo', onFoo);
+    expect(dispatch.getListenerCount()).toEqual(1);
+
+    dispatch.removeAllListeners();
+    expect(dispatch.getListenerCount()).toEqual(0);
+  });
+
+  it('should expose the event names that have listeners', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+
+    expect(dispatch.getEvents()).toHaveLength(0);
+
+    dispatch.addListener('foo', () => {});
+    expect(dispatch.getEvents()).toContain('foo');
+
+    const onGaz = (): void => {};
+    dispatch.addListener('foo', () => {});
+    dispatch.addListener('gaz', onGaz);
+    const withGaz = dispatch.getEvents();
+
+    expect(withGaz).toHaveLength(2);
+    expect(withGaz).toContain('gaz');
+
+    dispatch.removeListener('gaz', onGaz);
+    const withoutGaz = dispatch.getEvents();
+
+    expect(withoutGaz).toHaveLength(1);
+    expect(withoutGaz).not.toContain('gaz');
+  });
+
+  it('should support adding event listeners and triggering events', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+    const onFoo = vi.fn();
+
+    dispatch.addListener('foo', onFoo);
+    dispatch.trigger('foo', 52, true);
+    expect(onFoo).toHaveBeenCalledExactlyOnceWith(52, true);
+  });
+
+  it('should not call a listener after removing it', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+    const onFoo = vi.fn();
+
+    dispatch.addListener('foo', onFoo);
+    dispatch.trigger('foo', 52, true);
+    dispatch.removeListener('foo', onFoo);
+    dispatch.trigger('foo', 5, false);
+
+    expect(onFoo).toHaveBeenCalledExactlyOnceWith(52, true);
+  });
+
+  it('should only call listeners for the event that is being triggered', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+    const onFoo = vi.fn();
+    const onBar = vi.fn();
+
+    dispatch.addListener('foo', onFoo);
+    dispatch.addListener('bar', onBar);
+
+    dispatch.trigger('foo', 52, true);
+    dispatch.trigger('bar', 'triggered');
+
+    expect(onFoo).toHaveBeenCalledExactlyOnceWith(52, true);
+    expect(onBar).toHaveBeenCalledExactlyOnceWith('triggered');
+  });
+
+  it('should support removing a listener after one event', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+    const onFoo = vi.fn();
+
+    dispatch.addListener('foo', onFoo, true);
+    expect(dispatch.getListenerCount()).toEqual(1);
+
+    dispatch.trigger('foo', 52, true);
+    dispatch.trigger('foo', 30, false);
+    expect(onFoo).toHaveBeenCalledExactlyOnceWith(52, true);
+
+    expect(dispatch.getListenerCount()).toEqual(0);
+  });
+
+  it('should support removing a listener via the unsub callback', () => {
+    const dispatch = new EventDispatcher<TestEventMap>();
+    const onFoo = vi.fn();
+
+    const unsub = dispatch.addListener('foo', onFoo);
+    expect(dispatch.getListenerCount()).toEqual(1);
+    dispatch.trigger('foo', 52, true);
+
+    unsub();
+    expect(dispatch.getListenerCount()).toEqual(0);
+    dispatch.trigger('foo', 30, false);
+    expect(onFoo).toHaveBeenCalledExactlyOnceWith(52, true);
+  });
+});

lib/events/event-dispatcher.ts

@@ -0,0 +1,188 @@
+export type EventMap = object;
+export type EventType<Map extends EventMap> = keyof Map;
+export type EventPayload<
+  Map extends EventMap,
+  Key extends EventType<Map> = EventType<Map>,
+> = Map[Key] extends unknown[] ? Map[Key] : unknown[];
+export type EventListener<
+  Map extends EventMap,
+  Key extends EventType<Map> = EventType<Map>,
+> = (...args: EventPayload<Map, Key>) => void | Promise<void>;
+
+type LazyListenerMap<Map extends EventMap> = {
+  [K in keyof Map]?: Set<EventListener<Map, K>>;
+};
+
+type UnsubListener = () => void;
+
+/**
+ * Event Dispatcher with support for full listener and payload type safety.
+ *
+ * Instantiate or type with an event map that contains an array of arguments for
+ * each key. The keys become the events and their associated array becomes the
+ * event payload. Event Maps should extend the `EventMap` type.
+ *
+ * @example
+ * ```
+ * interface ExampleMap extends EventMap {
+ *  foo: [num: number, bool: boolean];
+ * }
+ *
+ * const dispatcher = new EventDispatcher<ExampleMap>();
+ * dispatcher.addListener('foo', (num, bool) => {});
+ * dispatcher.trigger('foo', 500, true);
+ * ```
+ */
+export class EventDispatcher<Map extends EventMap> {
+  #_listeners: LazyListenerMap<Map> = {};
+  #_autoRemoveListeners: LazyListenerMap<Map> = {};
+
+  #_listenerCount = 0;
+  #_events = new Set<EventType<Map>>();
+
+  /**
+   * Adds a listener for the given event. If `once` is set to true, the listener
+   * will be removed automatically after the first time the listener is triggered.
+   * Returns a callback that can be used to remove the listener without needing
+   * to call `removeListener`.
+   *
+   * @param event The event name to listen for.
+   * @param listener The callback to trigger once the event triggers.
+   * @param once If the listener should be removed after first invocation.
+   * @returns A callback to remove the listener.
+   */
+  public addListener<Event extends EventType<Map> = EventType<Map>>(
+    event: Event,
+    listener: EventListener<Map, Event>,
+    once?: boolean,
+  ): UnsubListener {
+    // Lazy-instantiate the listener set.
+    let listeners = this.#_listeners[event];
+    if (!listeners) {
+      listeners = new Set();
+      this.#_listeners[event] = listeners;
+      this.#_events.add(event);
+    }
+
+    const unsub: UnsubListener = () => {
+      this.removeListener(event, listener);
+    };
+
+    // Only add the listener if we don't already have it.
+    if (listeners.has(listener)) {
+      return unsub;
+    }
+
+    this.#_listenerCount++;
+    listeners.add(listener);
+
+    // Cache the listener reference to the auto remove set so we can remove it
+    // after it triggers for the first time.
+    if (once) {
+      let autoRemoveListeners = this.#_autoRemoveListeners[event];
+
+      if (!autoRemoveListeners) {
+        autoRemoveListeners = new Set();
+        this.#_autoRemoveListeners[event] = autoRemoveListeners;
+      }
+
+      autoRemoveListeners.add(listener);
+    }
+
+    return unsub;
+  }
+
+  /**
+   * Removes a given listener from the event dispatcher. The listener provided
+   * **MUST BE THE SAME REFERENCE**, otherwise the listener will not be
+   * removed.
+   *
+   * @param event The event the listener was registered to.
+   * @param listener The listener that was registered.
+   */
+  public removeListener<Event extends EventType<Map> = EventType<Map>>(
+    event: Event,
+    listener: EventListener<Map, Event>,
+  ): void {
+    const listeners = this.#_listeners[event];
+    if (listeners?.delete(listener)) {
+      this.#_listenerCount = Math.max(this.#_listenerCount - 1, 0);
+    }
+
+    const autoRemoveListeners = this.#_autoRemoveListeners[event];
+    autoRemoveListeners?.delete(listener);
+
+    this.#_removeEmptyEvent(event);
+  }
+
+  /**
+   * Removes all listeners that have been registered on this event dispatcher,
+   * and resets all internal dispatcher state.
+   */
+  public removeAllListeners(): void {
+    for (const event in this.#_listeners) {
+      this.#_listeners[event]?.clear();
+    }
+
+    for (const event in this.#_autoRemoveListeners) {
+      this.#_autoRemoveListeners[event]?.clear();
+    }
+
+    this.#_autoRemoveListeners = {};
+    this.#_listeners = {};
+
+    this.#_events.clear();
+    this.#_listenerCount = 0;
+  }
+
+  /**
+   * Triggers an event dispatch, calling all registered listeners for the given
+   * event with the provided payload.
+   *
+   * @param event The event to trigger.
+   * @param ...payload The payload to pass to all listeners.
+   */
+  public trigger<Event extends EventType<Map> = EventType<Map>>(
+    event: Event,
+    ...payload: EventPayload<Map, Event>
+  ): void {
+    const listeners = this.#_listeners[event];
+
+    listeners?.forEach((listener) => {
+      void listener(...payload);
+
+      if (this.#_autoRemoveListeners[event]?.has(listener)) {
+        this.removeListener(event, listener);
+      }
+    });
+  }
+
+  /**
+   * Returns the current number of registered event listeners on this dispatcher.
+   * @returns The total registered event listeners.
+   */
+  public getListenerCount(): number {
+    return this.#_listenerCount;
+  }
+
+  /**
+   * Returns a list of the events that have listeners registered on this dispatcher.
+   * @returns The events with registered listeners.
+   */
+  public getEvents(): EventType<Map>[] {
+    return [...this.#_events];
+  }
+
+  #_removeEmptyEvent(event: EventType<Map>): void {
+    if ((this.#_listeners[event]?.size ?? 0) < 1) {
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete this.#_listeners[event];
+      this.#_events.delete(event);
+    }
+
+    if ((this.#_autoRemoveListeners[event]?.size ?? 0) < 1) {
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete this.#_autoRemoveListeners[event];
+    }
+  }
+}