@alcadur/react-events-hook 1.0.0

package/README.md

@@ -0,0 +1,14 @@
+# react-events-hook
+
+Simple Observer pattern for React.
+
+## 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]
+
+## Usage
+[soon]

package/index.ts

@@ -0,0 +1 @@
+export * from './src';

package/package.json

@@ -0,0 +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"
+  }
+}

package/src/actions/emit-event.ts

@@ -0,0 +1,11 @@
+import { sharedEvents } from "../shared-events";
+import { EventNameType } from "../events.model";
+
+export function emitEvent(event: EventNameType, ...args: any[]) {
+    const callbacks = sharedEvents[event];
+    if (!callbacks) {
+        return;
+    }
+
+    callbacks.forEach(callback => callback(...args));
+}

package/src/actions/index.test.ts

@@ -0,0 +1,77 @@
+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();
+        });
+    });
+});

package/src/actions/index.ts

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

package/src/actions/on-event.ts

@@ -0,0 +1,11 @@
+import { 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));
+
+    sharedEvents[event] = callbacks;
+}

package/src/actions/remove-event.ts

@@ -0,0 +1,17 @@
+import { sharedEvents } from "../shared-events";
+import { getAsArray } from "../utils";
+import { EventCallbackType, EventNameType } from "../events.model";
+
+export function removeEvent(event: EventNameType, callback: EventCallbackType | EventCallbackType[]) {
+    const declaredCallbacks = sharedEvents[event];
+    if (!declaredCallbacks) {
+        return;
+    }
+
+    getAsArray(callback).forEach(cb => {
+        const index = declaredCallbacks.indexOf(cb);
+        if (index !== -1) {
+            declaredCallbacks.splice(index, 1);
+        }
+    })
+}

package/src/events.model.ts

@@ -0,0 +1,4 @@
+export type EventNameType = string | number | symbol
+export type EventCallbackType = ((...args: any[]) => void) | (() => void)
+
+export type InitEventsType = { [key: EventNameType]: EventCallbackType[] | EventCallbackType }

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useEvents';

package/src/hooks/useEvents.test.ts

@@ -0,0 +1,53 @@
+import { renderHook, act } from '@testing-library/react';
+import { useEvents } from './useEvents';
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { sharedEvents } from '../shared-events';
+
+describe('useEvents', () => {
+    beforeEach(() => {
+        Object.keys(sharedEvents).forEach(key => delete sharedEvents[key]);
+    });
+
+    it('should register and emit events', () => {
+        const { result } = renderHook(() => useEvents());
+        const callback = vi.fn();
+
+        act(() => {
+            result.current.onEvent('test-event', callback);
+        });
+
+        act(() => {
+            result.current.emitEvent('test-event', 'data');
+        });
+
+        expect(callback).toHaveBeenCalledWith('data');
+    });
+
+    it('should remove events', () => {
+        const { result } = renderHook(() => useEvents());
+        const callback = vi.fn();
+
+        act(() => {
+            result.current.onEvent('test-event', callback);
+            result.current.removeEvent('test-event', callback);
+        });
+
+        act(() => {
+            result.current.emitEvent('test-event', 'data');
+        });
+
+        expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('should register events from init map', () => {
+        const callback = vi.fn();
+        renderHook(() => useEvents({ 'init-event': callback }));
+
+        const { result } = renderHook(() => useEvents());
+        act(() => {
+            result.current.emitEvent('init-event', 'init-data');
+        });
+
+        expect(callback).toHaveBeenCalledWith('init-data');
+    });
+});

package/src/hooks/useEvents.ts

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import { InitEventsType } from "../events.model";
+import { emitEvent, onEvent, removeEvent } from "../actions";
+
+export const useEvents = (eventMap: InitEventsType = {}) => {
+    useEffect(() => {
+        if (!eventMap) {
+            return;
+        }
+        const eventMapEntries = Object.entries(eventMap);
+        eventMapEntries.forEach(([event, callback]) => {
+            onEvent(event, callback)
+        })
+
+        return () => {
+            eventMapEntries.forEach(([event, callback]) => {
+                removeEvent(event, callback)
+            })
+        }
+    }, [eventMap])
+
+    return { onEvent, emitEvent, removeEvent };
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './hooks';
+export * from './utils';

package/src/setupTests.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/src/shared-events.ts

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

package/src/utils.test.ts

@@ -0,0 +1,16 @@
+import { getAsArray } from './utils';
+import { describe, it, expect, vi } from "vitest";
+
+describe('utils', () => {
+    describe('getAsArray', () => {
+        it('should return the same array if an array is passed', () => {
+            const arr = [vi.fn()];
+            expect(getAsArray(arr)).toBe(arr);
+        });
+
+        it('should wrap a single value in an array', () => {
+            const callback = vi.fn();
+            expect(getAsArray(callback)).toEqual([callback]);
+        });
+    });
+});

package/src/utils.ts

@@ -0,0 +1,5 @@
+import { EventCallbackType } from "./events.model";
+
+export function getAsArray(value: EventCallbackType[] | EventCallbackType): EventCallbackType[] {
+    return Array.isArray(value) ? value : [value];
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "jsx": "react",
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "lib": ["esnext"],
+    "strictNullChecks": true,
+  },
+  "include": ["src"],
+  "exclude": ["example"]
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    type: 'module',
+    setupFiles: './src/setupTests.ts',
+    exclude: ['dist/**', 'node_modules/**']
+  },
+});