@homer0/events-hub 2.0.4 → 2.0.6

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+type GenericFn = (...args: any[]) => any;
+type GenericParams = Parameters<GenericFn>;
+type OnceWrapperFn = GenericFn & {
+    once: boolean;
+};
+/**
+ * When the service receives a "once subscription", it needs to track the listener so it
+ * gets removed after being called once, and to avoid modifying the original function, it
+ * creates a wrapper function that has the "once" property set to true. The wrapper and
+ * the original function are stored in case `off` is called before the wrapper gets
+ * triggered; it will receive the original function, not the wrapper, so the class needs a
+ * way to map them together.
+ */
+type OnceWrapper = {
+    /**
+     * A simple wrapper for the original listener, with the difference that it has a `once`
+     * property set to `true`.
+     */
+    wrapper: OnceWrapperFn;
+    /**
+     * The original listener that will be called once.
+     */
+    original: GenericFn;
+};
+/**
+ * A minimal implementation of an events handler service.
+ */
+declare class EventsHub {
+    /**
+     * A dictionary of the events and their listeners.
+     */
+    protected events: Record<string, GenericFn[]>;
+    /**
+     * A dictionary of wrappers that were created for "one time subscriptions". This is
+     * used by the {@link EventsHub.off}: if it doesn't find the subscriber as it is, it
+     * will look for a wrapper and remove it.
+     */
+    protected onceWrappers: Record<string, OnceWrapper[]>;
+    /**
+     * Gets all the listeners for a specific event.
+     * The list is returned by reference, so it can be modified once obtained.
+     *
+     * @param event  The name of the event.
+     */
+    protected getSubscribers(event: string): (GenericFn | OnceWrapperFn)[];
+    on<ListenerFn extends GenericFn = GenericFn>(event: string, listener: ListenerFn): () => boolean;
+    on<ListenerFn extends GenericFn = GenericFn>(event: string[], listener: ListenerFn): () => boolean[];
+    on<ListenerFn extends GenericFn = GenericFn>(event: string | string[], listener: ListenerFn): () => boolean | boolean[];
+    once<ListenerFn extends GenericFn = GenericFn>(event: string, listener: ListenerFn): () => boolean;
+    once<ListenerFn extends GenericFn = GenericFn>(event: string[], listener: ListenerFn): () => boolean[];
+    once<ListenerFn extends GenericFn = GenericFn>(event: string | string[], listener: ListenerFn): () => boolean | boolean[];
+    off<ListenerFn extends GenericFn | OnceWrapperFn = GenericFn>(event: string[], listener: ListenerFn): boolean[];
+    off<ListenerFn extends GenericFn | OnceWrapperFn = GenericFn>(event: string, listener: ListenerFn): boolean;
+    off<ListenerFn extends GenericFn | OnceWrapperFn = GenericFn>(event: string | string[], listener: ListenerFn): boolean | boolean[];
+    /**
+     * Emits an event and call all its listeners.
+     *
+     * @param event  An event name or a list of them.
+     * @param args   A list of parameters to send to the listeners.
+     * @template Args  The type of the parameters to send to the listeners.
+     * @example
+     *
+     *   const events = new EventsHub();
+     *   events.on('event', (arg0) => {
+     *     console.log(`Event received: ${arg0}`);
+     *   });
+     *   events.emit('event', 'Hello'); // prints "Event received: Hello"
+     *
+     */
+    emit<Args extends GenericParams>(event: string | string[], ...args: Args): void;
+    /**
+     * Asynchronously reduces a target using an event. It's like emit, but the events
+     * listener return a modified (or not) version of the `target`.
+     *
+     * @param event   An event name or a list of them.
+     * @param target  The variable to reduce with the reducers/listeners.
+     * @param args    A list of parameters to send to the reducers/listeners.
+     * @returns A version of the `target` processed by the listeners.
+     * @template Target  The type of the target.
+     * @template Args    The type of the parameters to send to the reducers/listeners.
+     * @example
+     *
+     *   const events = new EventsHub();
+     *   events.on('event', async (target, arg0) => {
+     *     const data = await fetch(`https://api.example.com/${arg0}`);
+     *     target.push(data);
+     *     return target;
+     *   });
+     *   const result = await events.reduce('event', [], 'Hello');
+     *   // result would be a list of data fetched from the API.
+     *
+     */
+    reduce<Target, Args extends GenericParams>(event: string | string[], target: Target, ...args: Args): Promise<Target>;
+    /**
+     * Synchronously reduces a target using an event. It's like emit, but the events
+     * listener return a modified (or not) version of the `target`.
+     *
+     * @param event   An event name or a list of them.
+     * @param target  The variable to reduce with the reducers/listeners.
+     * @param args    A list of parameters to send to the reducers/listeners.
+     * @returns A version of the `target` processed by the listeners.
+     * @template Target  The type of the target.
+     * @template Args    The type of the parameters to send to the reducers/listeners.
+     * @example
+     *
+     *   const events = new EventsHub();
+     *   events.on('event', (target, arg0) => {
+     *     target.push(arg0);
+     *     return target;
+     *   });
+     *   events.reduce('event', [], 'Hello'); // returns ['Hello']
+     *
+     */
+    reduceSync<Target, ReducerArgs extends GenericParams>(event: string | string[], target: Target, ...args: ReducerArgs): Target;
+}
+/**
+ * Shorthand for `new EventsHub()`.
+ *
+ * @returns A new instance of {@link EventsHub}.
+ */
+declare const eventsHub: () => EventsHub;
+
+export { EventsHub, eventsHub };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homer0/events-hub",
   "description": "A simple implementation of a pubsub service for handling events",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/homer0/packages.git",
@@ -23,12 +23,12 @@
     "dist/"
   ],
   "devDependencies": {
-    "@homer0/eslint-plugin": "10.3.0",
-    "@homer0/tsconfig": "1.0.9",
-    "jest": "^29.5.0",
-    "ts-jest": "^29.1.0",
-    "tsup": "^7.0.0",
-    "typescript": "^5.1.3"
+    "@homer0/eslint-plugin": "10.3.2",
+    "@homer0/tsconfig": "1.0.11",
+    "jest": "^29.6.1",
+    "ts-jest": "^29.1.1",
+    "tsup": "^7.1.0",
+    "typescript": "^5.1.6"
   },
   "engine-strict": true,
   "engines": {
@@ -44,5 +44,5 @@
     "build": "tsup src/index.ts",
     "prepublishOnly": "pnpm run build"
   },
-  "gitHead": "d632c6e05b583ceeceff43ed7a52e1e7afbf1265"
+  "gitHead": "bab3ed6af9cf27c0d64e4169dc1f4825a978a717"
 }