@alcadur/react-events-hook 1.0.0 → 1.0.2

package/README.md

@@ -2,13 +2,82 @@
 
 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
-[soon]
+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) })
+```
+
+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;
+```
+
+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);
+```
+
+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);
+```
 
-## Usage
-[soon]
+There no difference between directly usage of `removeEvent` and `removeEvent` returned from `useEvents` hook.

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@alcadur/react-events-hook",
-  "version": "1.0.0",
-  "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.0.2",
+  "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/hooks/useEvents.test.ts

@@ -41,13 +41,20 @@ describe('useEvents', () => {
 
     it('should register events from init map', () => {
         const callback = vi.fn();
-        renderHook(() => useEvents({ 'init-event': callback }));
+        const callbackSymbol = vi.fn();
+        const symbolEvent = Symbol('init-event');
+        renderHook(() => useEvents({
+            'init-event': callback,
+            [symbolEvent]: callbackSymbol
+        }));
 
         const { result } = renderHook(() => useEvents());
         act(() => {
             result.current.emitEvent('init-event', 'init-data');
+            result.current.emitEvent(symbolEvent);
         });
 
         expect(callback).toHaveBeenCalledWith('init-data');
+        expect(callbackSymbol).toHaveBeenCalled()
     });
 });

package/src/hooks/useEvents.ts

@@ -7,14 +7,15 @@ export const useEvents = (eventMap: InitEventsType = {}) => {
         if (!eventMap) {
             return;
         }
-        const eventMapEntries = Object.entries(eventMap);
-        eventMapEntries.forEach(([event, callback]) => {
-            onEvent(event, callback)
+        const events = [...Object.keys(eventMap), ...Object.getOwnPropertySymbols(eventMap)]
+
+        events.forEach( event => {
+            onEvent(event, eventMap[event])
         })
 
         return () => {
-            eventMapEntries.forEach(([event, callback]) => {
-                removeEvent(event, callback)
+            events.forEach((event) => {
+                removeEvent(event, eventMap[event])
             })
         }
     }, [eventMap])