2 files changed, 445 insertions, 0 deletions
diff --git a/src/eventx.test.ts b/src/eventx.test.ts
new file mode 100644
index 0000000..bb47449
--- /dev/null
+++ b/src/eventx.test.ts
@@ -0,0 +1,211 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import EventX from "./eventx";
+
+describe("EventX", () => {
+  describe("subscribe", () => {
+    test("subscribes to an event", () => {
+      const $ = EventX({ counter: 1 });
+      const id = $.subscribe("test-event", (state) => ({ state }));
+      expect(id).toBe(1);
+      expect($.subscriptionCount("test-event")).toBe(1);
+    });
+
+    test("subscribes to an event once", () => {
+      const $ = EventX({ counter: 1 });
+      const id = $.subscribeOnce("test-event", (state) => ({ state }));
+      expect(id).toBe(1);
+      expect($.subscriptionCount("test-event")).toBe(1);
+
+      // Dispatch the event to trigger the one-time subscription
+      $.dispatch("test-event");
+      expect($.subscriptionCount("test-event")).toBe(0);
+    });
+
+    test("unsubscribes from an event", () => {
+      const $ = EventX({ counter: 1 });
+      $.subscribe("test-event", (state) => ({ state }));
+      expect($.subscriptionCount("test-event")).toBe(1);
+
+      $.unsubscribe("test-event");
+      expect($.subscriptionCount("test-event")).toBe(0);
+    });
+  });
+
+  describe("dispatch", () => {
+    test("dispatches an event without arguments", () => {
+      const $ = EventX({ counter: 1 });
+      const callback = vi.fn((state) => ({ state }));
+
+      $.subscribe("test-event", callback);
+      $.dispatch("test-event");
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith({ counter: 1 });
+    });
+
+    test("dispatches an event with arguments", () => {
+      const $ = EventX({ counter: 1 });
+      const callback = vi.fn((state, arg1, arg2) => ({ state }));
+
+      $.subscribe("test-event", callback);
+      $.dispatch("test-event", "arg1-value", "arg2-value");
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith({ counter: 1 }, "arg1-value", "arg2-value");
+    });
+
+    test("updates state when event handler returns new state", () => {
+      const $ = EventX({ counter: 1 });
+      const stateChangeSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("$counter", stateChangeSpy);
+      $.subscribe("increment", (state) => ({
+        state: { ...state, counter: state.counter + 1 },
+      }));
+
+      $.dispatch("increment");
+
+      expect(stateChangeSpy).toHaveBeenCalledTimes(1);
+      expect(stateChangeSpy).toHaveBeenCalledWith({ counter: 2 });
+    });
+
+    test("dispatches nested events", () => {
+      const $ = EventX({ counter: 1 });
+      const nestedEventSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("nested-event", nestedEventSpy);
+      $.subscribe("parent-event", (state) => ({
+        state,
+        dispatch: { eventName: "nested-event" },
+      }));
+
+      $.dispatch("parent-event");
+
+      expect(nestedEventSpy).toHaveBeenCalledTimes(1);
+    });
+
+    test("dispatches multiple nested events", () => {
+      const $ = EventX({ counter: 1 });
+      const nestedEvent1Spy = vi.fn((state) => ({ state }));
+      const nestedEvent2Spy = vi.fn((state) => ({ state }));
+
+      $.subscribe("nested-event-1", nestedEvent1Spy);
+      $.subscribe("nested-event-2", nestedEvent2Spy);
+      $.subscribe("parent-event", (state) => ({
+        state,
+        dispatch: [{ eventName: "nested-event-1" }, { eventName: "nested-event-2" }],
+      }));
+
+      $.dispatch("parent-event");
+
+      expect(nestedEvent1Spy).toHaveBeenCalledTimes(1);
+      expect(nestedEvent2Spy).toHaveBeenCalledTimes(1);
+    });
+
+    test("dispatches nested events with arguments", () => {
+      const $ = EventX({ counter: 1 });
+      const nestedEventSpy = vi.fn((state, arg) => ({ state }));
+
+      $.subscribe("nested-event", nestedEventSpy);
+      $.subscribe("parent-event", (state) => ({
+        state,
+        dispatch: { eventName: "nested-event", args: ["arg-value"] },
+      }));
+
+      $.dispatch("parent-event");
+
+      expect(nestedEventSpy).toHaveBeenCalledTimes(1);
+      expect(nestedEventSpy).toHaveBeenCalledWith({ counter: 1 }, "arg-value");
+    });
+  });
+
+  describe("state change detection", () => {
+    test("detects value changes in state", () => {
+      const $ = EventX({ counter: 1, nested: { value: "test" } });
+      const counterChangeSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("$counter", counterChangeSpy);
+      $.subscribe("change-counter", (state) => ({
+        state: { ...state, counter: 2 },
+      }));
+
+      $.dispatch("change-counter");
+
+      expect(counterChangeSpy).toHaveBeenCalledTimes(1);
+      expect(counterChangeSpy).toHaveBeenCalledWith({ counter: 2, nested: { value: "test" } });
+    });
+
+    test("detects nested value changes in state", () => {
+      const $ = EventX({ counter: 1, nested: { value: "test" } });
+      const nestedValueChangeSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("$nested.value", nestedValueChangeSpy);
+      $.subscribe("change-nested-value", (state) => ({
+        state: {
+          ...state,
+          nested: { ...state.nested, value: "changed" },
+        },
+      }));
+
+      $.dispatch("change-nested-value");
+
+      expect(nestedValueChangeSpy).toHaveBeenCalledTimes(1);
+      expect(nestedValueChangeSpy).toHaveBeenCalledWith({
+        counter: 1,
+        nested: { value: "changed" },
+      });
+    });
+
+    test("detects deleted properties in state", () => {
+      const $ = EventX({ counter: 1, toDelete: "value" } as { counter: number; toDelete?: string });
+      const deleteChangeSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("$toDelete", deleteChangeSpy);
+      $.subscribe("delete-property", (state) => {
+        const newState = { counter: state.counter };
+        return { state: newState };
+      });
+
+      $.dispatch("delete-property");
+
+      expect(deleteChangeSpy).toHaveBeenCalledTimes(1);
+    });
+
+    test("detects type changes in state", () => {
+      const $ = EventX({ counter: 1 } as { counter: string | number });
+      const counterChangeSpy = vi.fn((state) => ({ state }));
+
+      $.subscribe("$counter", counterChangeSpy);
+      $.subscribe("change-counter-type", (state) => ({
+        state: { ...state, counter: "string now" },
+      }));
+
+      $.dispatch("change-counter-type");
+
+      expect(counterChangeSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("utility methods", () => {
+    test("returns all subscription names", () => {
+      const $ = EventX({ counter: 1 });
+      $.subscribe("event1", (state) => ({ state }));
+      $.subscribe("event2", (state) => ({ state }));
+
+      const subs = $.subscriptions();
+      expect(subs).toContain("event1");
+      expect(subs).toContain("event2");
+      expect(subs.length).toBe(2);
+    });
+
+    test("returns subscription count for specific event", () => {
+      const $ = EventX({ counter: 1 });
+      $.subscribe("event1", (state) => ({ state }));
+      $.subscribe("event1", (state) => ({ state }));
+      $.subscribe("event2", (state) => ({ state }));
+
+      expect($.subscriptionCount("event1")).toBe(2);
+      expect($.subscriptionCount("event2")).toBe(1);
+    });
+  });
+});
diff --git a/src/eventx.ts b/src/eventx.ts
new file mode 100644
index 0000000..0e108d9
--- /dev/null
+++ b/src/eventx.ts
@@ -0,0 +1,234 @@
+export type EventDispatcher = (eventName: string, ...args: unknown[]) => void;
+
+export type SubscriptionResponseDispatch = {
+  eventName: string;
+  args?: unknown[];
+};
+
+export type SubscriptionResponse<T> = {
+  state?: T;
+  dispatch?: SubscriptionResponseDispatch | SubscriptionResponseDispatch[];
+};
+
+const isSubscriptionResponseList = (
+  dispatch: SubscriptionResponseDispatch | SubscriptionResponseDispatch[],
+): dispatch is SubscriptionResponseDispatch[] => Array.isArray(dispatch);
+
+export type EventCallback<T> = (state: T, ...args: any[]) => SubscriptionResponse<T>;
+
+export type Subscription<T> = {
+  listener: string;
+  callback: EventCallback<T>;
+  once: boolean;
+};
+
+export type StateChange = "deleted" | "changed-type" | "changed-value";
+
+export type EventX<T> = {
+  subscribe: (listener: string, callback: EventCallback<T>) => number;
+  subscribeOnce: (listener: string, callback: EventCallback<T>) => number;
+  unsubscribe: (listener: string) => void;
+  subscriptionCount: (eventName: string) => number;
+  subscriptions: () => string[];
+  dispatch: (eventName: string, ...args: any[]) => void;
+};
+
+/**
+ * A function that creates an EventX object.
+ *
+ * @param {T extends object} initialState The initial application state.
+ * @returns {EventX<T>} The EventX object.
+ */
+const EventX = <T extends object>(initialState: T): EventX<T> => {
+  let _state = initialState;
+  const _subscriptions: Map<string, Subscription<T>[]> = new Map();
+  let subscriptionId = 0;
+
+  /**
+   * Subcribe to an event.
+   *
+   * @param {string} listener
+   * @param {EventCallback<T>} callback
+   * @returns
+   */
+  const subscribe = (listener: string, callback: EventCallback<T>): number => {
+    if (!_subscriptions.has(listener)) {
+      _subscriptions.set(listener, []);
+    }
+
+    _subscriptions.get(listener)?.push({
+      listener,
+      callback,
+      once: false,
+    });
+
+    return ++subscriptionId;
+  };
+
+  /**
+   * Subcribe to an event, once.
+   *
+   * @param {string} listener
+   * @param {EventCallback<T>} callback
+   * @returns
+   */
+  const subscribeOnce = (listener: string, callback: EventCallback<T>): number => {
+    if (!_subscriptions.has(listener)) {
+      _subscriptions.set(listener, []);
+    }
+
+    _subscriptions.get(listener)?.push({
+      listener,
+      callback,
+      once: true,
+    });
+
+    return ++subscriptionId;
+  };
+
+  const unsubscribe = (listener: string): void => {
+    if (_subscriptions.has(listener)) {
+      _subscriptions.delete(listener);
+    }
+  };
+
+  /**
+   * Composes a list of changes between two states.
+   *
+   * @param {T extends object} oldState
+   * @param {T extends object} newState
+   * @param {string} path
+   * @returns {StateChange[]} The list of changes.
+   */
+  const changedState = <T extends object>(
+    oldState: T,
+    newState: T,
+    path: string = "",
+  ): Map<string, StateChange> => {
+    let changes: Map<string, StateChange> = new Map();
+
+    for (const k in oldState) {
+      const currentPath = path ? `${path}.${k}` : k;
+
+      // Missing?
+      if (!(k in newState)) {
+        if (!changes.has(currentPath)) {
+          changes.set(currentPath, "deleted");
+        }
+      }
+
+      // Type changed?
+      if (typeof oldState[k] !== typeof newState[k]) {
+        if (!changes.has(currentPath)) {
+          changes.set(currentPath, "changed-type");
+        }
+      }
+
+      // Recursive object check
+      if (
+        typeof oldState[k] === "object" &&
+        typeof newState[k] === "object" &&
+        oldState[k] !== null &&
+        newState[k] !== null
+      ) {
+        changedState(oldState[k], newState[k], currentPath).forEach((v, k) => {
+          changes.set(k, v);
+        });
+      }
+
+      // Value changed?
+      if (JSON.stringify(oldState[k]) !== JSON.stringify(newState[k])) {
+        if (!changes.has(currentPath)) {
+          changes.set(currentPath, "changed-value");
+        }
+      }
+    }
+
+    return changes;
+  };
+
+  /**
+   * Dispatches an event with the given name and arguments.
+   *
+   * @param {string} eventName The name of the event to dispatch.
+   * @param {unknown[]} args The arguments to pass to the event listeners.
+   * @returns {void}
+   */
+  const dispatch = (eventName: string, ...args: unknown[]): void => {
+    if (!_subscriptions.has(eventName)) {
+      return;
+    }
+
+    const scopedSubsriptions = _subscriptions.get(eventName) ?? [];
+    const remainingSubscriptions = [];
+    let callbackCount = 0;
+
+    for (const subscription of scopedSubsriptions) {
+      const response = subscription.callback(_state, ...args);
+
+      // Updates state, and checks for state changes, and if any changes present,
+      // fires a dispatch for all the state listeners (if there are any).
+      if (typeof response.state !== "undefined") {
+        const changes = changedState(_state, response.state);
+        _state = response.state;
+
+        changes.forEach((_, v) => {
+          dispatch(`\$${v}`);
+        });
+      }
+
+      // Dispatches events
+      if (response.dispatch) {
+        if (isSubscriptionResponseList(response.dispatch)) {
+          for (const dispatchee of response.dispatch) {
+            dispatch(dispatchee.eventName, ...(dispatchee.args ?? []));
+          }
+        } else {
+          dispatch(response.dispatch.eventName, ...(response.dispatch.args ?? []));
+        }
+      }
+
+      callbackCount++;
+
+      if (!subscription.once) {
+        remainingSubscriptions.push(subscription);
+      }
+    }
+
+    _subscriptions.set(eventName, remainingSubscriptions);
+  };
+
+  /**
+   * Returns the number of subscriptions for the given event name.
+   *
+   * @param {string} eventName The name of the event to check.
+   * @returns {number} The number of subscriptions for the given event name.
+   */
+  const subscriptionCount = (eventName: string | null): number => {
+    if (eventName) {
+      return _subscriptions.get(eventName)?.length ?? 0;
+    }
+
+    return Array.from(_subscriptions.keys()).length;
+  };
+
+  /**
+   * Returns the names of all subscriptions.
+   *
+   * @returns {string[]} An array of subscription names.
+   */
+  const subscriptions = (): string[] => {
+    return Array.from(_subscriptions.keys());
+  };
+
+  return {
+    subscribe,
+    subscribeOnce,
+    unsubscribe,
+    subscriptionCount,
+    subscriptions,
+    dispatch,
+  };
+};
+
+export default EventX;