@alcadur/react-events-hook 1.0.1 → 1.1.0

package/README.md

@@ -2,15 +2,117 @@
 
 Simple Observer pattern for React.
 
+[Live Demo](https://codesandbox.io/p/sandbox/w9wqwh)
+
+[npm package](https://www.npmjs.com/package/@alcadur/react-events-hook)
+
+## Installation
+```
+npm i @alcadur/react-events-hook
+```
+
 ## What for?
 Useful for communication between components in different parts of the view. 
 
 Using standard React mechanisms, it's also possible to synchronize with external events.
 
-## Installation
+Lets look at an example:
+
+![image](https://i.postimg.cc/6QTvgnz9/chrome-XWt93Ap2ma.png)
+
+If we want to change background colors for C1, C2 and C3 from C6 we have few options:
+1. use context
+2. use global state
+3. props drilling
+
+   [![chrome-ZO2l-FT6NWj.png](https://i.postimg.cc/tggMcSL6/chrome-ZO2l-FT6NWj.png)](https://postimg.cc/BjdpLgZZ)
+
+With events, we can avoid unnecessary boilerplate.
+
+[![chrome-69c-Hd-SCHv-C.png](https://i.postimg.cc/tg0sSw1D/chrome-69c-Hd-SCHv-C.png)](https://postimg.cc/ZWcY0fxy)
+[![chrome-M22485Lpnz.gif](https://i.postimg.cc/502bnSmm/chrome-M22485Lpnz.gif)](https://postimg.cc/SX3BK83X)
+
+
+## Docs
+
+### onEvent
+`onEvent` is a function that subscribes to event outsite of React context.
+
+:warning: If you want to use `onEvent` in react component without `useEvents` hook, make sure to not add a new listiner on each render.
+
+```ts
+onEvent('eventName', (...args) => console.log('event fired with: ', args));
+````
+
+### useEvents
+Use to subscribe to events in React components.
+```tsx
+    const { onEvent, emitEvent, removeEvent } = useEvents({ eventName: (...args) => console.log('event fired with: ', args) })
 ```
-npm i @alcadur/react-events-hooknpm i @alcadur/react-events-hook
+
+Event name can be: `string`, `number` or `symbol`
+```ts
+export const Events = {
+  C4_TITLE_CHANGE: Symbol(),
+  REMOVE_LEFT_CHILD: "remove-element",
+  CHANGE_COLOR: 3
+} as const;
 ```
 
-## Usage
-[soon]
+You don't need to use `useEvents` hook to emit or remove events.
+
+### emitEvent
+`emitEvent` is a function that emits single event.
+
+```ts
+emitEvent('eventName', 'some data');
+emitEvent('eventWithParams', 1, 2, 3);
+```
+
+#### emitEvent.memo
+`emitEvent.memo` remembers the last emitted value and triggers a new callback immediately with that value. To clear memorized value, call `emitEvent.memo(undefined)` or to avoid extra emission, use `clearMemo` (described below)
+```ts
+onEvent('eventName', (data) => console.log(data)) 
+emitEvent('eventName', 'some data');
+// expected log: some data
+
+emitEvent('eventName', 'some data');
+onEvent('eventName', (data) => console.log(data))
+// no logs expected, event was emited before subscription
+
+emitEvent.memo('eventName', 'some data');
+onEvent('eventName', (data) => console.log(data))
+// expected log: some data
+
+emitEvent.memo('eventName', 'some data');
+emitEvent('eventName', 123); // value emited without memo
+onEvent('eventName', (data) => console.log(data))
+// expected log: some data
+
+```
+
+There no difference between directly usage of `emitEvent` and `emitEvent` returned from `useEvents` hook.
+
+### removeEvent
+`removeEvent` is a function that removes event listener.
+
+```ts
+const eventHandler = () => console.log('event fired');
+onEvent('eventName', eventHandler);
+removeEvent('eventName', eventHandler);
+```
+
+There no difference between directly usage of `removeEvent` and `removeEvent` returned from `useEvents` hook.
+
+
+### clearMemo
+`clearMemo` removes the last memorized event emitted value
+
+```ts
+clearMemo('eventName');
+```
+
+There no difference between directly usage of `clearMemo` and `clearMemo` returned from `useEvents` hook.
+
+
+

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@alcadur/react-events-hook",
-  "version": "1.0.1",
-  "description": "no",
-  "keywords": [
-    "react",
-    "react",
-    "hook",
-    "react",
-    "hooks",
-    "events",
-    "events",
-    "hook"
-  ],
-  "homepage": "https://github.com/Alcadur/react-events-hook#readme",
-  "bugs": {
-    "url": "https://github.com/Alcadur/react-events-hook/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Alcadur/react-events-hook.git"
-  },
-  "license": "MIT",
-  "author": "Alcadur",
-  "type": "module",
-  "main": "index.ts",
-  "scripts": {
-    "test": "vitest run"
-  },
-  "peerDependencies": {
-    "react": "*18.0.0"
-  },
-  "devDependencies": {
-    "@rollup/plugin-typescript": "^12.3.0",
-    "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^14.3.1",
-    "@types/react": "^18.3.28",
-    "@types/react-dom": "^18.3.7",
-    "@vitejs/plugin-react": "^6.0.1",
-    "jsdom": "^29.0.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "rollup": "^4.59.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.3"
-  }
-}
+{
+  "name": "@alcadur/react-events-hook",
+  "version": "1.1.0",
+  "description": "Helps in easy communication between React components as also with external sources",
+  "keywords": [
+    "react",
+    "react",
+    "hook",
+    "react",
+    "hooks",
+    "events",
+    "events",
+    "hook"
+  ],
+  "homepage": "https://github.com/Alcadur/react-events-hook#readme",
+  "bugs": {
+    "url": "https://github.com/Alcadur/react-events-hook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alcadur/react-events-hook.git"
+  },
+  "license": "MIT",
+  "author": "Alcadur",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": "*18.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^14.3.1",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rollup": "^4.59.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.3"
+  }
+}

package/src/actions/clear-memo.ts

@@ -0,0 +1,8 @@
+import { lastEmittedValues } from "../shared-events";
+import { EventNameType } from "../events.model";
+
+export const clearMemo = (key: EventNameType) => {
+    lastEmittedValues[key] = undefined;
+    delete lastEmittedValues[key];
+
+}

package/src/actions/emit-event.ts

@@ -1,7 +1,8 @@
-import { sharedEvents } from "../shared-events";
+import { lastEmittedValues, sharedEvents } from "../shared-events";
 import { EventNameType } from "../events.model";
+import { clearMemo } from "./clear-memo";
 
-export function emitEvent(event: EventNameType, ...args: any[]) {
+function emitter(event: EventNameType, ...args: any[]) {
     const callbacks = sharedEvents[event];
     if (!callbacks) {
         return;
@@ -9,3 +10,19 @@ export function emitEvent(event: EventNameType, ...args: any[]) {
 
     callbacks.forEach(callback => callback(...args));
 }
+
+export function emitEvent(event: EventNameType, ...args: any[]) {
+    emitter(event, ...args);
+}
+
+if (!emitEvent.memo) {
+    emitEvent.memo = (event: EventNameType, ...args: any[]) => {
+        lastEmittedValues[event] = args;
+
+        if (args.length === 1 && args[0] === undefined) {
+            clearMemo(event);
+        }
+
+        emitter(event, ...args);
+    }
+}

package/src/actions/index.test.ts

@@ -1,77 +1,147 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { sharedEvents } from "../shared-events";
-import { emitEvent } from "./emit-event";
-import { onEvent } from "./on-event";
-import { removeEvent } from "./remove-event";
-
-describe("actions", () => {
-    beforeEach(() => {
-        Object.keys(sharedEvents).forEach((key) => delete sharedEvents[key]);
-    });
-
-    describe("onEvent", () => {
-        it("registers a single callback", () => {
-            const callback = vi.fn();
-
-            onEvent("test-event", callback);
-
-            expect(sharedEvents["test-event"]).toEqual([callback]);
-        });
-
-        it("registers an array of callbacks", () => {
-            const callback1 = vi.fn();
-            const callback2 = vi.fn();
-
-            onEvent("test-event", [callback1, callback2]);
-
-            expect(sharedEvents["test-event"]).toEqual([callback1, callback2]);
-        });
-    });
-
-    describe("emitEvent", () => {
-        it("invokes all callbacks with provided args", () => {
-            const callback1 = vi.fn();
-            const callback2 = vi.fn();
-
-            onEvent("test-event", [callback1, callback2]);
-            emitEvent("test-event", "data", 1);
-
-            expect(callback1).toHaveBeenCalledWith("data", 1);
-            expect(callback2).toHaveBeenCalledWith("data", 1);
-        });
-
-        it("does nothing when event has no callbacks", () => {
-            expect(() => emitEvent("missing-event", "data")).not.toThrow();
-        });
-    });
-
-    describe("removeEvent", () => {
-        it("removes a single callback", () => {
-            const callback = vi.fn();
-
-            onEvent("test-event", callback);
-            removeEvent("test-event", callback);
-            emitEvent("test-event", "data");
-
-            expect(callback).not.toHaveBeenCalled();
-        });
-
-        it("removes multiple callbacks from array input", () => {
-            const callback1 = vi.fn();
-            const callback2 = vi.fn();
-
-            onEvent("test-event", [callback1, callback2]);
-            removeEvent("test-event", [callback1, callback2]);
-            emitEvent("test-event", "data");
-
-            expect(callback1).not.toHaveBeenCalled();
-            expect(callback2).not.toHaveBeenCalled();
-        });
-
-        it("does nothing when event has no callbacks", () => {
-            const callback = vi.fn();
-
-            expect(() => removeEvent("missing-event", callback)).not.toThrow();
-        });
-    });
-});
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { lastEmittedValues, sharedEvents } from "../shared-events";
+import { emitEvent } from "./emit-event";
+import { onEvent } from "./on-event";
+import { removeEvent } from "./remove-event";
+import { clearMemo } from "./clear-memo";
+
+describe("actions", () => {
+    beforeEach(() => {
+        Object.keys(sharedEvents).forEach((key) => delete sharedEvents[key]);
+        Object.keys(lastEmittedValues).forEach((key) => delete lastEmittedValues[key]);
+    });
+
+    describe("onEvent", () => {
+        it("registers a single callback", () => {
+            const callback = vi.fn();
+
+            onEvent("test-event", callback);
+
+            expect(sharedEvents["test-event"]).toEqual([callback]);
+        });
+
+        it("registers an array of callbacks", () => {
+            const callback1 = vi.fn();
+            const callback2 = vi.fn();
+
+            onEvent("test-event", [callback1, callback2]);
+
+            expect(sharedEvents["test-event"]).toEqual([callback1, callback2]);
+        });
+    });
+
+    describe("emitEvent", () => {
+        it("invokes all callbacks with provided args", () => {
+            const callback1 = vi.fn();
+            const callback2 = vi.fn();
+
+            onEvent("test-event", [callback1, callback2]);
+            emitEvent("test-event", "data", 1);
+
+            expect(callback1).toHaveBeenCalledWith("data", 1);
+            expect(callback2).toHaveBeenCalledWith("data", 1);
+        });
+
+        it("does nothing when event has no callbacks", () => {
+            expect(() => emitEvent("missing-event", "data")).not.toThrow();
+        });
+
+        describe("memo", () => {
+            it("invokes all callback and stores the value", () => {
+                const callback = vi.fn();
+                onEvent("memo-event", callback);
+
+                emitEvent.memo("memo-event", "memo-data");
+
+                expect(callback).toHaveBeenCalledWith("memo-data");
+                expect(lastEmittedValues["memo-event"]).toEqual(["memo-data"]);
+            });
+
+            it("triggers callback immediately if event was already memoized", () => {
+                const callback = vi.fn();
+
+                emitEvent.memo("memo-event", "old-data");
+                onEvent("memo-event", callback);
+
+                expect(callback).toHaveBeenCalledWith("old-data");
+            });
+
+            it("clears memoized value when emitEvent.memo is called with undefined", () => {
+                const callback = vi.fn();
+                onEvent("memo-event", callback);
+
+                emitEvent.memo("memo-event", "some-data");
+                expect(lastEmittedValues["memo-event"]).toEqual(["some-data"]);
+                expect(callback).toHaveBeenCalledWith("some-data");
+
+                emitEvent.memo("memo-event", undefined);
+                expect(lastEmittedValues["memo-event"]).toBeUndefined();
+                expect(callback).toHaveBeenCalledWith(undefined);
+            });
+
+            it("should not trigger callback immediately when last emitted value is undefined", () => {
+                const callback = vi.fn();
+                const callback2 = vi.fn();
+
+                emitEvent.memo("memo-event", "some-data");
+                onEvent("memo-event", callback);
+                expect(callback).toHaveBeenCalledWith("some-data");
+
+                emitEvent.memo("memo-event", undefined);
+                onEvent("memo-event", callback2);
+                expect(callback).toHaveBeenCalledWith(undefined);
+                expect(callback2).not.toHaveBeenCalled();
+            });
+        });
+    });
+
+    describe("clearMemo", () => {
+        it("removes the memoized value for a given event", () => {
+            emitEvent.memo("test-event", "data");
+            expect(lastEmittedValues["test-event"]).toEqual(["data"]);
+
+            clearMemo("test-event");
+            expect(lastEmittedValues["test-event"]).toBeUndefined();
+        });
+
+        it("does not trigger callbacks", () => {
+            const callback = vi.fn();
+            onEvent("test-event", callback);
+            emitEvent.memo("test-event", "data");
+            callback.mockClear();
+
+            clearMemo("test-event");
+            expect(callback).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("removeEvent", () => {
+        it("removes a single callback", () => {
+            const callback = vi.fn();
+
+            onEvent("test-event", callback);
+            removeEvent("test-event", callback);
+            emitEvent("test-event", "data");
+
+            expect(callback).not.toHaveBeenCalled();
+        });
+
+        it("removes multiple callbacks from array input", () => {
+            const callback1 = vi.fn();
+            const callback2 = vi.fn();
+
+            onEvent("test-event", [callback1, callback2]);
+            removeEvent("test-event", [callback1, callback2]);
+            emitEvent("test-event", "data");
+
+            expect(callback1).not.toHaveBeenCalled();
+            expect(callback2).not.toHaveBeenCalled();
+        });
+
+        it("does nothing when event has no callbacks", () => {
+            const callback = vi.fn();
+
+            expect(() => removeEvent("missing-event", callback)).not.toThrow();
+        });
+    });
+});

package/src/actions/index.ts

@@ -1,3 +1,4 @@
 export * from './emit-event';
 export * from './on-event';
 export * from './remove-event';
+export * from './clear-memo';

package/src/actions/on-event.ts

@@ -1,11 +1,16 @@
-import { sharedEvents } from "../shared-events";
+import { lastEmittedValues, sharedEvents } from "../shared-events";
 import { getAsArray } from "../utils";
 import { EventCallbackType, EventNameType } from "../events.model";
 
 export function onEvent(event: EventNameType, callback: EventCallbackType[] | EventCallbackType) {
     const callbacks = sharedEvents[event] ?? [];
 
-    callbacks.push(...getAsArray(callback));
+    const newCallbacks = getAsArray(callback)
+    callbacks.push(...newCallbacks);
 
     sharedEvents[event] = callbacks;
+
+    if (lastEmittedValues[event]) {
+        newCallbacks.forEach(callback => callback(...lastEmittedValues[event]));
+    }
 }

package/src/hooks/useEvents.test.ts

@@ -1,11 +1,12 @@
 import { renderHook, act } from '@testing-library/react';
 import { useEvents } from './useEvents';
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { sharedEvents } from '../shared-events';
+import { lastEmittedValues, sharedEvents } from '../shared-events';
 
 describe('useEvents', () => {
     beforeEach(() => {
         Object.keys(sharedEvents).forEach(key => delete sharedEvents[key]);
+        Object.keys(lastEmittedValues).forEach(key => delete lastEmittedValues[key]);
     });
 
     it('should register and emit events', () => {
@@ -57,4 +58,38 @@ describe('useEvents', () => {
         expect(callback).toHaveBeenCalledWith('init-data');
         expect(callbackSymbol).toHaveBeenCalled()
     });
+
+    it('should support memoized events', () => {
+        const { result } = renderHook(() => useEvents());
+        const callback = vi.fn();
+
+        act(() => {
+            result.current.emitEvent.memo('memo-event', 'memo-data');
+        });
+
+        act(() => {
+            result.current.onEvent('memo-event', callback);
+        });
+
+        expect(callback).toHaveBeenCalledWith('memo-data');
+    });
+
+    it('should clear memoized events', () => {
+        const { result } = renderHook(() => useEvents());
+        const callback = vi.fn();
+
+        act(() => {
+            result.current.emitEvent.memo('memo-event', 'memo-data');
+        });
+
+        act(() => {
+            result.current.clearMemo('memo-event');
+        });
+
+        act(() => {
+            result.current.onEvent('memo-event', callback);
+        });
+
+        expect(callback).not.toHaveBeenCalled();
+    });
 });

package/src/hooks/useEvents.ts

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 import { InitEventsType } from "../events.model";
-import { emitEvent, onEvent, removeEvent } from "../actions";
+import { emitEvent, onEvent, removeEvent, clearMemo } from "../actions";
 
 export const useEvents = (eventMap: InitEventsType = {}) => {
     useEffect(() => {
@@ -20,5 +20,5 @@ export const useEvents = (eventMap: InitEventsType = {}) => {
         }
     }, [eventMap])
 
-    return { onEvent, emitEvent, removeEvent };
+    return { onEvent, emitEvent, removeEvent, clearMemo };
 };

package/src/shared-events.ts

@@ -1,3 +1,5 @@
 import type { EventCallbackType, EventNameType } from "./events.model";
 
 export const sharedEvents: { [key: EventNameType]: EventCallbackType[] } = {};
+
+export const lastEmittedValues: { [key: EventNameType]: any } = {};