@tsed/hooks 8.0.0 → 8.0.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/hooks",
   "description": "Hooks module for Ts.ED Framework",
   "type": "module",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -10,6 +10,7 @@
   "browser": "./lib/browser/core.umd.min.js",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "browser": "./lib/browser/hooks.umd.min.js",
       "import": "./lib/esm/index.js",
@@ -34,8 +35,8 @@
   },
   "devDependencies": {
     "@tsed/monorepo-utils": "2.3.9",
-    "@tsed/typescript": "8.0.0",
-    "@tsed/vitest": "8.0.0",
+    "@tsed/typescript": "8.0.2",
+    "@tsed/vitest": "8.0.2",
     "eslint": "9.12.0",
     "typescript": "5.4.5",
     "vite": "^5.4.8",

package/src/Hooks.spec.ts

@@ -0,0 +1,219 @@
+import {Hooks} from "./Hooks.js";
+
+describe("Hooks", () => {
+  describe("off()", () => {
+    it("should remove a listener (using event, cb)", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+      const fn2 = vi.fn();
+      const fn3 = vi.fn();
+
+      hooks.on("event", fn);
+      hooks.on("event2", fn2);
+      hooks.on("event2", fn3);
+
+      expect(hooks.has("event")).toBe(true);
+      expect(hooks.has("event2")).toBe(true);
+
+      hooks.off("event", fn);
+      hooks.off("event2", fn2);
+
+      expect(hooks.has("event")).toBe(false);
+      expect(hooks.has("event2")).toBe(true);
+
+      hooks.off("event3", fn2);
+
+      expect(hooks.has("event2")).toBe(true);
+
+      hooks.emit("event", ["arg1"]);
+
+      expect(fn).not.toHaveBeenCalled();
+    });
+    it("should remove a listener (using ref)", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+      const fn2 = vi.fn();
+      const ref = Symbol("ref");
+
+      hooks.on("event", ref, fn);
+      hooks.on("event2", ref, fn2);
+
+      expect(hooks.has("event")).toBe(true);
+      expect(hooks.has("event2")).toBe(true);
+
+      hooks.off(ref);
+
+      expect(hooks.has("event")).toBe(false);
+      expect(hooks.has("event2")).toBe(false);
+
+      hooks.emit("event", ["arg1"]);
+      hooks.emit("event2", ["arg1"]);
+
+      expect(fn).not.toHaveBeenCalled();
+      expect(fn2).not.toHaveBeenCalled();
+    });
+  });
+  describe("once()", () => {
+    it("should call once a listener (using event, cb)", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+
+      hooks.once("event", fn);
+
+      expect(hooks.has("event")).toBe(true);
+
+      hooks.emit("event", ["arg1"]);
+
+      expect(hooks.has("event")).toBe(false);
+      expect(fn).toHaveBeenCalled();
+    });
+    it("should call once a listener (using ref)", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+      const fn2 = vi.fn();
+      const ref = Symbol("ref");
+
+      hooks.once("event", ref, fn);
+      hooks.once("event2", ref, fn2);
+
+      expect(hooks.has("event")).toBe(true);
+      expect(hooks.has("event2")).toBe(true);
+
+      hooks.emit("event", ["arg1"]);
+      hooks.emit("event2", ["arg1"]);
+
+      expect(hooks.has("event")).toBe(false);
+      expect(hooks.has("event2")).toBe(false);
+      expect(fn).toHaveBeenCalled();
+      expect(fn2).toHaveBeenCalled();
+    });
+  });
+  describe("emit()", () => {
+    it("should listen a hook and calls listener", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+
+      hooks.on("event", fn);
+
+      hooks.emit("event", ["arg1"]);
+
+      expect(fn).toHaveBeenCalledWith("arg1");
+
+      hooks.off("event", fn);
+    });
+    it("should calls listeners that match listeners with matching ref and without ref", () => {
+      const hooks = new Hooks();
+      const fn: any = vi.fn();
+      fn.id = "f1";
+
+      const fn2: any = vi.fn();
+      fn.id = "f2";
+
+      const fn3: any = vi.fn();
+      fn3.id = "f3";
+      const ref = Symbol("ref");
+
+      hooks.on("event", ref, fn);
+      hooks.on("event2", ref, fn2);
+      hooks.on("event2", fn3);
+
+      hooks.emit("event", ref, ["arg1"]);
+
+      expect(fn).toHaveBeenCalledWith("arg1");
+      expect(fn2).not.toHaveBeenCalledWith("arg1");
+      expect(fn3).not.toHaveBeenCalledWith("arg1");
+
+      hooks.emit("event2", ref, ["arg1"]);
+
+      expect(fn2).toHaveBeenCalledWith("arg1");
+      expect(fn3).toHaveBeenCalledWith("arg1");
+
+      hooks.off(ref);
+    });
+    it("should not call listeners if the ref mismatch", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+      const fn2 = vi.fn();
+      const fn3 = vi.fn();
+      const ref = Symbol("ref");
+      const ref2 = Symbol("ref");
+
+      hooks.on("event", ref, fn);
+      hooks.on("event2", ref, fn2);
+      hooks.on("event2", ref, fn3);
+
+      hooks.emit("event", ref2, ["arg1"]);
+
+      expect(fn).not.toHaveBeenCalledWith("arg1");
+      expect(fn2).not.toHaveBeenCalledWith("arg1");
+      expect(fn3).not.toHaveBeenCalledWith("arg1");
+
+      hooks.off(ref);
+    });
+    it("should call", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+      const fn2 = vi.fn();
+      const fn3 = vi.fn();
+      const ref = Symbol("ref");
+      const ref2 = Symbol("ref");
+
+      hooks.on("event", ref, fn);
+      hooks.on("event2", ref, fn2);
+      hooks.on("event2", ref, fn3);
+
+      hooks.emit("event", ref2, ["arg1"]);
+
+      expect(fn).not.toHaveBeenCalledWith("arg1");
+      expect(fn2).not.toHaveBeenCalledWith("arg1");
+      expect(fn3).not.toHaveBeenCalledWith("arg1");
+
+      hooks.off(ref);
+    });
+  });
+  describe("asyncEmit()", () => {
+    it("should async listen a hook and calls listener", async () => {
+      const hooks = new Hooks();
+      const fn = vi.fn();
+
+      hooks.on("event", fn);
+
+      await hooks.asyncEmit("event", ["arg1"]);
+
+      expect(fn).toHaveBeenCalledWith("arg1");
+
+      hooks.off("event", fn);
+    });
+  });
+  describe("alter()", () => {
+    it("should listen a hook and calls listener", () => {
+      const hooks = new Hooks();
+      const fn = vi.fn().mockReturnValue("valueAltered");
+
+      hooks.on("event", fn);
+
+      const value = hooks.alter("event", "value");
+
+      expect(fn).toHaveBeenCalledWith("value");
+      expect(value).toBe("valueAltered");
+
+      hooks.off("event", fn);
+    });
+  });
+  describe("alterAsync()", () => {
+    it("should async listen a hook and calls listener", async () => {
+      const hooks = new Hooks();
+      const fn = vi.fn().mockReturnValue("valueAltered");
+
+      hooks.on("event", fn);
+
+      await hooks.asyncAlter("event", "value", ["arg1"]);
+
+      expect(fn).toHaveBeenCalledWith("value", "arg1");
+
+      hooks.off("event", fn);
+
+      hooks.destroy();
+    });
+  });
+});

package/src/Hooks.ts

@@ -0,0 +1,241 @@
+export type HookRef = string | symbol | any | Function;
+export type HookListener = Function;
+
+type HookItem = {cb: HookListener; ref?: HookRef};
+
+function match(ref: HookRef | unknown[] | undefined, item: HookItem) {
+  return !ref || !item.ref || (ref && item.ref === ref);
+}
+
+export class Hooks {
+  #listeners: Map<string, HookItem[]> = new Map();
+
+  /**
+   * Check if an event has listeners
+   * @param event
+   */
+  has(event: string) {
+    return !!this.#listeners.get(event)?.length;
+  }
+
+  /**
+   * Listen a hook event
+   * @param event The event name
+   * @param ref The reference of the listener
+   * @param cb The callback
+   */
+  on(event: string, ref: HookRef, cb: HookListener): this;
+  /**
+   * Listen a hook event
+   * @param event The event name
+   * @param cb The callback
+   */
+  on(event: string, cb: HookListener): this;
+  on(event: string, cbORef: HookRef | HookListener, cb?: HookListener) {
+    let ref: HookRef | HookListener | undefined = cbORef;
+
+    if (!cb) {
+      cb = ref as HookListener;
+      ref = undefined;
+    }
+
+    const items = this.#listeners.get(event) || [];
+
+    items.push({
+      cb,
+      ref
+    });
+
+    this.#listeners.set(event, items);
+
+    return this;
+  }
+
+  /**
+   * Listen a hook event once
+   *
+   * @param event The event name
+   * @param ref The reference of the listener
+   * @param cb The callback
+   */
+  once(event: string, ref: HookRef, cb: HookListener): this;
+  /**
+   * Listen a hook event once
+   * @param event
+   * @param cb
+   */
+  once(event: string, cb: HookListener): this;
+  once(event: string, ref: HookRef | HookListener, cb?: HookListener) {
+    if (!cb) {
+      cb = ref as HookListener;
+    }
+
+    const onceCb = (...args: unknown[]) => {
+      cb(...args);
+      this.off(event, onceCb);
+    };
+
+    this.on(event, ref, onceCb);
+
+    return this;
+  }
+
+  /**
+   * Remove a listener attached to an event
+   * @param ref
+   */
+  off(ref: HookRef): this;
+  /**
+   * Remove a listener attached to an event
+   * @param event
+   * @param cb
+   */
+  off(event: string, cb: HookListener): this;
+  off(event: string | HookRef, cb?: HookListener) {
+    const set = (event: string, items: HookItem[]) => {
+      if (items.length) {
+        this.#listeners.set(event, items);
+      } else {
+        this.#listeners.delete(event);
+      }
+    };
+
+    if (typeof event === "string" && cb) {
+      let items = this.#listeners.get(event);
+
+      if (items) {
+        set(
+          event,
+          items.filter((item) => item.cb !== cb)
+        );
+      }
+    } else {
+      const ref = event as HookRef;
+
+      this.#listeners.forEach((items, event) => {
+        set(
+          event,
+          items.filter((item) => item.ref !== ref)
+        );
+      });
+    }
+
+    return this;
+  }
+
+  /**
+   * Trigger an event without arguments.
+   * @param event The event name
+   */
+  emit(event: string): void;
+  /**
+   * Trigger an event and call listener.
+   * @param event
+   * @param args
+   * @param callThis
+   */
+  emit(event: string, args: unknown[]): void;
+  /**
+   * Trigger an event with arguments and call only listener attached to the given ref.
+   * @param event The event name
+   * @param ref The reference of the listener
+   * @param args The arguments
+   */
+  emit(event: string, ref: HookRef, args?: unknown[]): void;
+  emit(event: string, ref?: HookRef | unknown[], args?: unknown[]): void {
+    if (Array.isArray(ref)) {
+      args = ref;
+      ref = undefined;
+    }
+
+    args ||= [];
+
+    const items = this.#listeners.get(event);
+
+    if (items?.length) {
+      for (const item of items) {
+        if (match(ref, item)) {
+          item.cb.apply(null, args);
+        }
+      }
+    }
+  }
+
+  /**
+   * Trigger an event and call async listener.
+   * @param event The event name
+   */
+  async asyncEmit(event: string): Promise<void>;
+  async asyncEmit(event: string, args: unknown[]): Promise<void>;
+  async asyncEmit(event: string, ref: HookRef, args?: unknown[]): Promise<void>;
+  async asyncEmit(event: string, ref?: HookRef | unknown[], args?: unknown[]): Promise<void> {
+    if (Array.isArray(ref)) {
+      args = ref;
+      ref = undefined;
+    }
+
+    const items = this.#listeners.get(event);
+
+    if (items?.length) {
+      const promises = items.filter((item) => match(ref, item)).map((item) => item.cb.apply(null, args));
+
+      await Promise.all(promises);
+    }
+  }
+
+  /**
+   * Trigger an event, listener alter given value and return it.
+   * @param event
+   * @param value
+   * @param args
+   * @param callThis
+   */
+  alter<Arg = unknown, AlteredArg = Arg>(event: string, value: Arg, args: unknown[] = [], callThis: unknown = null): AlteredArg {
+    const items = this.#listeners.get(event);
+
+    if (items?.length) {
+      for (const {cb} of items) {
+        value = cb.call(callThis, value, ...args);
+      }
+    }
+
+    return value as unknown as AlteredArg;
+  }
+
+  /**
+   * Trigger an event, async listener alter given value and return it.
+   * @param event
+   * @param value
+   * @param args
+   * @param callThis
+   */
+  async asyncAlter<Arg = unknown, AlteredArg = Arg>(
+    event: string,
+    value: Arg,
+    args: unknown[] = [],
+    callThis: unknown = null
+  ): Promise<AlteredArg> {
+    const items = this.#listeners.get(event);
+
+    if (items?.length) {
+      for (const item of items) {
+        value = await item.cb.call(callThis, value, ...args);
+      }
+    }
+
+    return value as unknown as AlteredArg;
+  }
+
+  destroy() {
+    this.#listeners.clear();
+  }
+}
+
+export const hooks = new Hooks();
+export const $on: typeof hooks.on = hooks.on.bind(hooks);
+export const $once: typeof hooks.once = hooks.once.bind(hooks);
+export const $off: typeof hooks.off = hooks.off.bind(hooks);
+export const $emit: typeof hooks.emit = hooks.emit.bind(hooks);
+export const $asyncEmit: typeof hooks.asyncEmit = hooks.asyncEmit.bind(hooks);
+export const $alter: typeof hooks.alter = hooks.alter.bind(hooks);
+export const $asyncAlter: typeof hooks.asyncAlter = hooks.asyncAlter.bind(hooks);

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./Hooks.js";