react-event-channel-z 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delpi.Kye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# 📡 react-event-channel-z
+
+[![NPM](https://img.shields.io/npm/v/react-event-channel-z.svg)](https://www.npmjs.com/package/react-event-channel-z)\
+![Downloads](https://img.shields.io/npm/dt/react-event-channel-z.svg)
+
+[LIVE EXAMPLE](https://codesandbox.io/p/sandbox/6w6wtk)
+
+---
+
+**react-event-channel-z** is a lightweight, fully typed, React-aware event channel built on top of `eventbus-z`.
+
+> Build scalable UI communication without prop drilling or global state
+> overkill.
+
+---
+
+## 📖 Why react-event-channel-z?
+
+- ✅ Fully typed EventMap
+- ⚛️ Optional startTransition support (React 18+)
+- 🛡 Safe subscriptions with useChannel
+- 🧼 No any, no unsafe casts
+- 📦 Lightweight and focused
+- 🔗 Built on top of eventbus-z
+
+---
+
+## 📦 Installation
+
+``` bash
+npm install react-event-channel-z
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1️⃣ Define your EventMap
+
+``` ts
+type AppEvents = {
+  toast: [message: string, type?: "success" | "error"];
+  modal: [open: boolean];
+};
+```
+
+---
+
+### 2️⃣ Create a Channel
+
+``` ts
+import { createChannel } from "react-event-channel-z";
+
+export const appChannel = createChannel<AppEvents>();
+```
+
+---
+
+### 3️⃣ Emit Events
+
+``` ts
+appChannel.emit("toast", "Saved successfully", "success");
+
+appChannel.emit("modal", true, {
+  transition: true // uses React.startTransition if available
+});
+```
+
+---
+
+### 4️⃣ Listen inside React Components
+
+``` ts
+import { useChannel } from "react-event-channel-z";
+
+useChannel(appChannel, "toast", (message, type) => {
+  console.log(message, type);
+});
+```
+
+---
+
+## ⚡ React 18 Transition Support
+
+If `transition: true` is passed in `emit` options, the event will be
+wrapped with:
+
+``` ts
+React.startTransition(() => { ... });
+```
+
+Fallback is automatically applied for React \<18.
+
+---
+
+## 🧠 Type Safety
+
+-   Full inference from `EventMap`
+-   Strongly typed `emit`
+-   Strongly typed `useChannel`
+-   No unsafe casts
+-   No `any`
+
+---
+
+## 🎯 Use Cases
+
+-   Toast systems
+-   Modal controllers
+-   Global notifications
+-   Micro-frontend communication
+-   Plugin architecture
+-   Dashboard cross-widgets sync
+
+---
+
+## 📦 Bundle Philosophy
+
+-   No global singletons
+-   No Context nesting
+-   No reducers
+-   No external state managers
+-   Just events --- fully typed
+
+---
+
+## 🔎 Comparison with eventbus-z
+
+| Criteria                  | eventbus-z | react-event-channel-z |
+|---------------------------|------------|-----------------------|
+| Framework agnostic        | ✅         | ❌ (React only)        |
+| React hook (`useChannel`) | ❌         | ✅                     |
+| `startTransition` support | ❌         | ✅                     |
+| StrictMode-safe           | ❌         | ✅                     |
+
+---
+
+## 🧩 What’s the difference?
+#### 📦 eventbus-z
+
+- Framework-agnostic
+- Pure TypeScript event bus
+- Zero React awareness
+- Works in Node, Vue, Svelte, vanilla JS, etc.
+- Best when you need a core pub/sub engine.
+
+#### ⚛️ react-event-channel-z
+
+- Built specifically for React 18+
+- Wraps eventbus-z
+- Adds:
+  - useChannel hook
+  - React startTransition integration
+  - StrictMode-safe subscription lifecycle
+  - React-friendly typing patterns
+
+Best when you're building React applications and want event-based communication that behaves correctly with concurrent rendering.
+
+> Think of react-event-channel-z as a React-native layer on top of eventbus-z.
+
+---
+
+## 📄 License
+
+MIT

package/build/channel/createChannel.d.ts

@@ -0,0 +1,8 @@
+import type { EventMapType, EmitOptions } from "./types";
+export type ChannelType<E extends EventMapType> = {
+    emit<K extends keyof E>(name: K, ...args: E[K]): void;
+    emit<K extends keyof E>(name: K, ...args: [...E[K], EmitOptions]): void;
+    on<K extends keyof E>(name: K, handler: (...args: E[K]) => void): void;
+    off<K extends keyof E>(name: K, handler: (...args: E[K]) => void): void;
+};
+export declare function createChannel<E extends EventMapType>(): ChannelType<E>;

package/build/channel/types.d.ts

@@ -0,0 +1,4 @@
+export type EventMapType = Record<string, any[]>;
+export type EmitOptions = {
+    transition?: boolean;
+};

package/build/channel/useChannel.d.ts

@@ -0,0 +1,3 @@
+import type { EventMapType } from "./types";
+import type { ChannelType } from "./createChannel";
+export declare function useChannel<E extends EventMapType, K extends keyof E>(channel: ChannelType<E>, name: K, handler: (...args: E[K]) => void): void;

package/build/index.cjs.js

@@ -0,0 +1,2 @@
+"use strict";var t=require("react"),n=require("eventbus-z");exports.createChannel=function(){const e=n.createTypedEventBus(),o={emit(t,n){e.$emit(t,...n)},on(t,n){e.$on(t,n)},off(t,n){e.$off(t,n)}},r="function"==typeof t.startTransition?t.startTransition:t=>t();return{emit:function(t,...n){const e=n[n.length-1],i="object"==typeof e&&null!==e&&"transition"in e,f=i?n.slice(0,-1):n;i&&e.transition?r(()=>{o.emit(t,f)}):o.emit(t,f)},on:o.on,off:o.off}},exports.useChannel=function(n,e,o){const r=t.useRef(o);r.current=o,t.useEffect(()=>{function t(...t){r.current(...t)}return n.on(e,t),()=>{n.off(e,t)}},[n,e])};
+//# sourceMappingURL=index.cjs.js.map

package/build/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/channel/createChannel.ts","../src/channel/useChannel.ts"],"sourcesContent":["import React from \"react\";\nimport { createTypedEventBus } from \"eventbus-z\";\nimport type { EventMapType, EmitOptions } from \"./types\";\n\nexport type ChannelType<E extends EventMapType> = {\n  emit<K extends keyof E>(\n    name: K,\n    ...args: E[K]\n  ): void;\n\n  emit<K extends keyof E>(\n    name: K,\n    ...args: [...E[K], EmitOptions]\n  ): void;\n\n  on<K extends keyof E>(\n    name: K,\n    handler: (...args: E[K]) => void\n  ): void;\n\n  off<K extends keyof E>(\n    name: K,\n    handler: (...args: E[K]) => void\n  ): void;\n};\n\nexport function createChannel<E extends EventMapType>(): ChannelType<E> {\n  const rawBus = createTypedEventBus<E>();\n\n  // Fully typed internal adapter\n  const bus = {\n    emit<K extends keyof E>(name: K, args: E[K]) {\n      rawBus.$emit(name as string, ...args);\n    },\n    on<K extends keyof E>(\n      name: K,\n      handler: (...args: E[K]) => void\n    ) {\n      rawBus.$on(name as string, handler);\n    },\n    off<K extends keyof E>(\n      name: K,\n      handler: (...args: E[K]) => void\n    ) {\n      rawBus.$off(name as string, handler);\n    }\n  };\n\n  const startTransition: (cb: () => void) => void =\n    typeof React.startTransition === \"function\"\n      ? React.startTransition\n      : (cb) => cb();\n\n  // ────────────────────────────────\n  // overload signatures\n  // ────────────────────────────────\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: E[K]\n  ): void;\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: [...E[K], EmitOptions]\n  ): void;\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: unknown[]\n  ) {\n    const last = args[args.length - 1];\n\n    const hasOptions =\n      typeof last === \"object\" &&\n      last !== null &&\n      \"transition\" in last;\n\n    const eventArgs = (hasOptions\n      ? args.slice(0, -1)\n      : args) as E[K];\n\n    if (hasOptions && (last as EmitOptions).transition) {\n      startTransition(() => {\n        bus.emit(name, eventArgs);\n      });\n    } else {\n      bus.emit(name, eventArgs);\n    }\n  }\n\n  return {\n    emit,\n    on: bus.on,\n    off: bus.off\n  };\n}\n","import { useEffect, useRef } from \"react\";\nimport type { EventMapType } from \"./types\";\nimport type { ChannelType } from \"./createChannel\";\n\nexport function useChannel<\n  E extends EventMapType,\n  K extends keyof E\n>(\n  channel: ChannelType<E>,\n  name: K,\n  handler: (...args: E[K]) => void\n) {\n  const handlerRef = useRef(handler);\n\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    function stableWrapper(...args: E[K]) {\n      handlerRef.current(...args);\n    }\n\n    channel.on(name, stableWrapper);\n\n    return () => {\n      channel.off(name, stableWrapper);\n    };\n  }, [channel, name]);\n}\n"],"names":["rawBus","createTypedEventBus","bus","emit","name","args","$emit","on","handler","$on","off","$off","startTransition","React","cb","last","length","hasOptions","eventArgs","slice","transition","channel","handlerRef","useRef","current","useEffect","stableWrapper"],"mappings":"6FA2BE,MAAMA,EAASC,EAAAA,sBAGTC,EAAM,CACV,IAAAC,CAAwBC,EAASC,GAC/BL,EAAOM,MAAMF,KAAmBC,EAClC,EACA,EAAAE,CACEH,EACAI,GAEAR,EAAOS,IAAIL,EAAgBI,EAC7B,EACA,GAAAE,CACEN,EACAI,GAEAR,EAAOW,KAAKP,EAAgBI,EAC9B,GAGII,EAC6B,mBAA1BC,EAAMD,gBACTC,EAAMD,gBACLE,GAAOA,IAwCd,MAAO,CACLX,KAzBF,SACEC,KACGC,GAEH,MAAMU,EAAOV,EAAKA,EAAKW,OAAS,GAE1BC,EACY,iBAATF,GACE,OAATA,GACA,eAAgBA,EAEZG,EAAaD,EACfZ,EAAKc,MAAM,GAAG,GACdd,EAEAY,GAAeF,EAAqBK,WACtCR,EAAgB,KACdV,EAAIC,KAAKC,EAAMc,KAGjBhB,EAAIC,KAAKC,EAAMc,EAEnB,EAIEX,GAAIL,EAAIK,GACRG,IAAKR,EAAIQ,IAEb,8BCxFEW,EACAjB,EACAI,GAEA,MAAMc,EAAaC,EAAAA,OAAOf,GAE1Bc,EAAWE,QAAUhB,EAErBiB,EAAAA,UAAU,KACR,SAASC,KAAiBrB,GACxBiB,EAAWE,WAAWnB,EACxB,CAIA,OAFAgB,EAAQd,GAAGH,EAAMsB,GAEV,KACLL,EAAQX,IAAIN,EAAMsB,KAEnB,CAACL,EAASjB,GACf"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./channel/createChannel";
+export * from "./channel/useChannel";
+export * from "./channel/types";

package/build/index.esm.js

@@ -0,0 +1,2 @@
+import t,{useRef as n,useEffect as o}from"react";import{createTypedEventBus as i}from"eventbus-z";function r(){const n=i(),o={emit(t,o){n.$emit(t,...o)},on(t,o){n.$on(t,o)},off(t,o){n.$off(t,o)}},r="function"==typeof t.startTransition?t.startTransition:t=>t();return{emit:function(t,...n){const i=n[n.length-1],f="object"==typeof i&&null!==i&&"transition"in i,e=f?n.slice(0,-1):n;f&&i.transition?r(()=>{o.emit(t,e)}):o.emit(t,e)},on:o.on,off:o.off}}function f(t,i,r){const f=n(r);f.current=r,o(()=>{function n(...t){f.current(...t)}return t.on(i,n),()=>{t.off(i,n)}},[t,i])}export{r as createChannel,f as useChannel};
+//# sourceMappingURL=index.esm.js.map

package/build/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/channel/createChannel.ts","../src/channel/useChannel.ts"],"sourcesContent":["import React from \"react\";\nimport { createTypedEventBus } from \"eventbus-z\";\nimport type { EventMapType, EmitOptions } from \"./types\";\n\nexport type ChannelType<E extends EventMapType> = {\n  emit<K extends keyof E>(\n    name: K,\n    ...args: E[K]\n  ): void;\n\n  emit<K extends keyof E>(\n    name: K,\n    ...args: [...E[K], EmitOptions]\n  ): void;\n\n  on<K extends keyof E>(\n    name: K,\n    handler: (...args: E[K]) => void\n  ): void;\n\n  off<K extends keyof E>(\n    name: K,\n    handler: (...args: E[K]) => void\n  ): void;\n};\n\nexport function createChannel<E extends EventMapType>(): ChannelType<E> {\n  const rawBus = createTypedEventBus<E>();\n\n  // Fully typed internal adapter\n  const bus = {\n    emit<K extends keyof E>(name: K, args: E[K]) {\n      rawBus.$emit(name as string, ...args);\n    },\n    on<K extends keyof E>(\n      name: K,\n      handler: (...args: E[K]) => void\n    ) {\n      rawBus.$on(name as string, handler);\n    },\n    off<K extends keyof E>(\n      name: K,\n      handler: (...args: E[K]) => void\n    ) {\n      rawBus.$off(name as string, handler);\n    }\n  };\n\n  const startTransition: (cb: () => void) => void =\n    typeof React.startTransition === \"function\"\n      ? React.startTransition\n      : (cb) => cb();\n\n  // ────────────────────────────────\n  // overload signatures\n  // ────────────────────────────────\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: E[K]\n  ): void;\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: [...E[K], EmitOptions]\n  ): void;\n\n  function emit<K extends keyof E>(\n    name: K,\n    ...args: unknown[]\n  ) {\n    const last = args[args.length - 1];\n\n    const hasOptions =\n      typeof last === \"object\" &&\n      last !== null &&\n      \"transition\" in last;\n\n    const eventArgs = (hasOptions\n      ? args.slice(0, -1)\n      : args) as E[K];\n\n    if (hasOptions && (last as EmitOptions).transition) {\n      startTransition(() => {\n        bus.emit(name, eventArgs);\n      });\n    } else {\n      bus.emit(name, eventArgs);\n    }\n  }\n\n  return {\n    emit,\n    on: bus.on,\n    off: bus.off\n  };\n}\n","import { useEffect, useRef } from \"react\";\nimport type { EventMapType } from \"./types\";\nimport type { ChannelType } from \"./createChannel\";\n\nexport function useChannel<\n  E extends EventMapType,\n  K extends keyof E\n>(\n  channel: ChannelType<E>,\n  name: K,\n  handler: (...args: E[K]) => void\n) {\n  const handlerRef = useRef(handler);\n\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    function stableWrapper(...args: E[K]) {\n      handlerRef.current(...args);\n    }\n\n    channel.on(name, stableWrapper);\n\n    return () => {\n      channel.off(name, stableWrapper);\n    };\n  }, [channel, name]);\n}\n"],"names":["createChannel","rawBus","createTypedEventBus","bus","emit","name","args","$emit","on","handler","$on","off","$off","startTransition","React","cb","last","length","hasOptions","eventArgs","slice","transition","useChannel","channel","handlerRef","useRef","current","useEffect","stableWrapper"],"mappings":"2GA0BgBA,IACd,MAAMC,EAASC,IAGTC,EAAM,CACV,IAAAC,CAAwBC,EAASC,GAC/BL,EAAOM,MAAMF,KAAmBC,EAClC,EACA,EAAAE,CACEH,EACAI,GAEAR,EAAOS,IAAIL,EAAgBI,EAC7B,EACA,GAAAE,CACEN,EACAI,GAEAR,EAAOW,KAAKP,EAAgBI,EAC9B,GAGII,EAC6B,mBAA1BC,EAAMD,gBACTC,EAAMD,gBACLE,GAAOA,IAwCd,MAAO,CACLX,KAzBF,SACEC,KACGC,GAEH,MAAMU,EAAOV,EAAKA,EAAKW,OAAS,GAE1BC,EACY,iBAATF,GACE,OAATA,GACA,eAAgBA,EAEZG,EAAaD,EACfZ,EAAKc,MAAM,GAAG,GACdd,EAEAY,GAAeF,EAAqBK,WACtCR,EAAgB,KACdV,EAAIC,KAAKC,EAAMc,KAGjBhB,EAAIC,KAAKC,EAAMc,EAEnB,EAIEX,GAAIL,EAAIK,GACRG,IAAKR,EAAIQ,IAEb,UC5FgBW,EAIdC,EACAlB,EACAI,GAEA,MAAMe,EAAaC,EAAOhB,GAE1Be,EAAWE,QAAUjB,EAErBkB,EAAU,KACR,SAASC,KAAiBtB,GACxBkB,EAAWE,WAAWpB,EACxB,CAIA,OAFAiB,EAAQf,GAAGH,EAAMuB,GAEV,KACLL,EAAQZ,IAAIN,EAAMuB,KAEnB,CAACL,EAASlB,GACf"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "react-event-channel-z",
+  "version": "1.0.0",
+  "description": "Fully typed React-aware event channel built on top of eventbus-z.",
+  "author": "Delpi.Kye",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+
+  "main": "./build/index.cjs.js",
+  "module": "./build/index.esm.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.esm.js",
+      "require": "./build/index.cjs.js"
+    }
+  },
+  "files": [
+    "build"
+  ],
+
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rollup -c",
+    "cb": "npm run clean && npm run build",
+    "prepublishOnly": "npm run build"
+  },
+
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delpikye-v/react-event-channel.git"
+  },
+  "homepage": "https://github.com/delpikye-v/react-event-channel#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/react-event-channel/issues"
+  },
+
+  "keywords": [
+    "react",
+    "typescript",
+    "event-bus",
+    "event-channel",
+    "pubsub",
+    "react-patterns",
+    "micro-frontend",
+    "react-architecture"
+  ],
+
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "eventbus-z": "^2.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/react": "^18.0.0",
+    "rimraf": "^5.0.0",
+    "rollup": "^4.0.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "tslib": "^2.6.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}