@oreefy/event 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oreefy
+
+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,200 @@
+# @oreefy/event
+
+A lightweight, type-safe event emitter for frontend web applications with built-in cross-tab communication support.
+
+`@oreefy/event` is a library built for the Oreefy ecosystem. The package is officially developed, maintained, and fully controlled by Oreefy, ensuring long-term stability, consistency, and compatibility across the ecosystem.
+
+> Browser only: This package is designed exclusively for `frontend/browser` environments. It requires the native `BroadcastChannel` API and is not intended for Node.js, server-side, or other non-browser environments.
+
+## Required Capabilities
+
+- JavaScript / TypeScript
+- A browser environment with native `BroadcastChannel` support
+- Frontend/client-side application
+
+<br>
+
+# Basic Usage
+
+The following example demonstrates a typical `client-side` usage:
+
+```ts
+import { eventInstance } from "@oreefy/event";
+
+const event = eventInstance();
+
+function listener(data) {
+  console.log("Signed in:", data); // { success: true }
+}
+
+// Register a listener
+event.on("signedIn", listener);
+
+// Remove the listener (Memory Efficient)
+event.off("signedIn", listener);
+
+// Emit an event
+event.emit("signedIn", { success: true });
+```
+
+Events are delivered to listeners in the same tab and automatically broadcast to other open tabs via `BroadcastChannel`.
+
+# API Reference
+
+Import `eventInstance` and create an event instance:
+
+```ts
+import { eventInstance } from "@oreefy/event";
+
+const event = eventInstance();
+event.emit();
+event.on();
+event.off();
+```
+
+All operations are _synchronous_.
+
+## `event.emit()`
+
+Emits an event with data payload.
+
+```ts
+import { eventInstance } from "@oreefy/event";
+
+interface Theme {
+  mode: "light" | "dark" | "system";
+  fontSize: string;
+  // ...
+}
+
+const event = eventInstance();
+
+// With type safety
+event.emit<Theme>("theme", {
+  mode: "system",
+  fontSize: "14px",
+});
+
+// Without type safety
+event.emit("theme", {
+  mode: "system",
+  fontSize: "14px",
+});
+```
+
+The event is immediately delivered to all listeners in the current tab and broadcast to other tabs using `BroadcastChannel`.
+
+## `idb.on()`
+
+Registers a _listener_ for a specific event.
+
+```ts
+import { eventInstance } from "@oreefy/event";
+
+interface Theme {
+  mode: "light" | "dark" | "system";
+  fontSize: string;
+  // ...
+}
+
+function listener(theme: Theme) {
+  console.log(theme); // { mode: "system", fontSize: "14px" }
+}
+
+const event = eventInstance();
+event.on<Theme>("theme", listener);
+```
+
+Multiple listeners can be registered for the same event.
+
+## `idb.off()`
+
+Removes a previously registered _listener_.
+
+```ts
+import { eventInstance } from "@oreefy/event";
+
+interface Theme {
+  mode: "light" | "dark" | "system";
+  fontSize: string;
+  // ...
+}
+
+function listener(theme: Theme) {
+  console.log(theme);
+}
+
+const event = eventInstance();
+event.on<Theme>("theme", listener);
+event.off("theme", handler); // Must pass the same function reference
+```
+
+If the listener is not registered, the call is silently ignored.
+
+## Cross-Tab Communication
+
+`@oreefy/event` uses the browser’s native `BroadcastChannel` API to share events across tabs.
+
+### Tab A:
+
+```ts
+event.emit("signedIn", true);
+```
+
+### Tab B:
+
+```ts
+event.on("signedIn", (data) => {
+  console.log("Received from another tab:", data);
+});
+```
+
+The originating tab does not receive its own broadcast message, preventing duplicate delivery.
+
+## Same-Tab vs Cross-Tab Behavior
+
+When you call `event.emit()`
+
+1. The event is delivered immediately to listeners in the current tab.
+2. The event is broadcast to other tabs via `BroadcastChannel`.
+
+## Event Listener Errors
+
+Errors thrown inside a listener do not prevent other listeners from running.
+
+```ts
+event.on("example", () => {
+  throw new Error("Something went wrong");
+});
+
+event.on("example", (data) => {
+  console.log("This listener still executes:", data);
+});
+
+event.emit("example", true);
+```
+
+An error thrown by one listener does not interrupt the event dispatch process.
+
+## Browser Compatibility
+
+This package depends on the native `BroadcastChannel` Web API. It is intended for modern browsers that provide `BroadcastChannel` support.
+
+It is not designed for:
+
+- Node.js
+- Server-side applications
+- Backend services
+- Serverless runtime environments
+- Cloudflare Workers
+- Other non-browser JavaScript runtimes
+
+Use this package when the code is running in a browser/client environment.
+
+## About Oreefy
+
+[**Oreefy**](https://www.oreefy.com) is an affordable business ecosystem designed for small to enterprise businesses. [**Oreefy**](https://www.oreefy.com) provides essential software you need for your modern business within a single ecosystem. It will save you significant time, effort, and money.
+
+## License
+
+MIT © Oreefy

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+type EventListener<T = any> = (data: T) => void;
+declare class Event {
+    private static _instance;
+    private static readonly TAB_ID;
+    private listeners;
+    private channel;
+    private _triggerLocalListeners;
+    private constructor();
+    static _initInstance(): Event;
+    emit<T = any>(name: string, data: T): void;
+    on<T = any>(name: string, listener: EventListener<T>): void;
+    off<T = any>(name: string, listener: EventListener<T>): void;
+}
+declare const eventInstance: typeof Event._initInstance;
+
+export { eventInstance };

package/dist/index.js

@@ -0,0 +1 @@
+var r=class s{static _instance;static TAB_ID=crypto.randomUUID();listeners=new Map;channel=new BroadcastChannel("@oreefy/idb");_triggerLocalListeners(t,e){let n=this.listeners.get(t);if(n)for(let i of n)try{i(e);}catch{}}constructor(){this.channel.addEventListener("message",t=>{let{name:e,data:n,sourceTabId:i}=t.data||{};e&&i!==s.TAB_ID&&this._triggerLocalListeners(e,n);});}static _initInstance(){return s._instance||(s._instance=new s),s._instance}emit(t,e){this._triggerLocalListeners(t,e),this.channel.postMessage({name:t,data:e,sourceTabId:s.TAB_ID});}on(t,e){this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(e);}off(t,e){let n=this.listeners.get(t);n&&(n.delete(e),n.size===0&&this.listeners.delete(t));}},a=r._initInstance;export{a as eventInstance};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@oreefy/event",
+  "version": "1.0.0",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oreefy/oreefy-event.git"
+  },
+  "bugs": {
+    "url": "https://github.com/oreefy/oreefy-event/issues"
+  },
+  "homepage": "https://github.com/oreefy/oreefy-event#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Oreefy",
+  "description": "A lightweight, type-safe event emitter for frontend web applications with built-in cross-tab communication support.",
+  "keywords": [
+    "event",
+    "listener",
+    "emitter",
+    "broadcastchannel",
+    "clinet",
+    "browser",
+    "ecosystem",
+    "oreefy"
+  ]
+}