@ublitzjs/channel 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# @ublitzjs/channel - REALLY fastest niche event emitter alternative
+
+A blazing-fast, lightweight Pub/Sub event channel designed as a high-performance, type-safe alternative to Node's standard `EventEmitter`. 
+
+![μBlitz.js](https://github.com/ublitzjs/core/blob/main/logo.png)
+<br/>
+
+Built for performance-critical applications, it minimizes creation overhead and leverages an optimized swap-and-pop strategy to achieve **$O(1)$ unsubscription times** for unique listeners.
+
+## Features
+
+- **Ultra Low Overhead:** Faster instantiation and publication execution than standard event emitters.
+- **$O(1)$ Removals:** True constant-time unsubscriptions via `sub_unique` and `unsub_unique`.
+- **Self-Cleaning Listeners:** Easily create single-use (`once`) events mid-execution without breaking the dispatch loop.
+- **No Dependencies:** Works in NodeJS, Bun and a Web browser
+- **TypeScript-first** 
+- **Prebuilt for ESM and CJS**
+- **Thoroughly tested**
+
+> ⚠️ **Important Note on Ordering:** To maintain extreme speed during deletions, the execution order of the remaining listeners is **not preserved** when a subscriber is removed.
+
+---
+
+## Benchmarks
+- [NodeJS](./nodejs_benchmark.md)
+- [Bun](./bunjs_benchmark.md)
+
+## Installation
+
+```bash
+bun add @ublitzjs/channel 
+```
+
+## Quick Start
+### Using a single Channel
+
+If you use EventEmitter for only one event, use **Channel** directly
+```typescript
+
+import { Channel } from '@ublitzjs/channel';
+
+// Define your payload type
+type LogMessage = `[Log] ${string}`;
+
+// Create a channel with a payload type
+const logChannel = new Channel<LogMessage>();
+
+// Subscribe to updates (like emitter.on)
+const onLog = (msg: LogMessage) => console.log(`Received: ${msg}`);
+logChannel.sub(onLog);
+
+// Publish data (like emitter.emit)
+logChannel.pub("[Log] User logged in successfully");
+
+// Unsubscribe (like emitter.off)
+logChannel.unsub(onLog);
+```
+
+## Using a ChannelMap (EventEmitter Style)
+
+For multiple lazily created centralised events use **ChannelMap**
+```typescript
+
+import { ChannelMap } from '@ublitzjs/channel';
+
+// 1. Define your Event Registry Map
+interface AppEvents {
+  'user:login': { id: number; username: string };
+  'user:logout': { id: number };
+}
+
+// 2. Instantiate the Emitter Map
+const emitter = new ChannelMap<AppEvents>();
+
+// 3. Get the specific channel and subscribe
+const loginChannel = emitter.on('user:login');
+
+loginChannel.sub(({ username }) => {
+  console.log(`Welcome back, ${username}!`);
+});
+
+// 4. Emit/Publish an event
+loginChannel.pub({ id: 42, username: 'Neo' });
+```
+
+## Core Guide & Performance Optimization
+1. Standard Subscription (sub / unsub)
+
+Best used for listeners shared across multiple distinct channels or when you intend to subscribe the exact same function reference multiple times to a single channel.
+
+    Unsubscription Cost: O(N) linear scan from the end of the array.
+
+```typescript
+channel.sub(myListener);
+channel.unsub(myListener);
+```
+
+2. High-Performance Unique Subscription (sub_unique / unsub_unique)
+
+Highly Recommended for hot code paths. By ensuring a listener is unique to this channel, the channel injects an internal tracking ID to achieve instant unsubscription.
+
+    Unsubscription Cost: O(1) constant time.
+
+```typescript
+// The listener reference must be unique to this channel instance
+const onDataReceived = (data) => processData(data);
+
+channel.sub_unique(onDataReceived);
+
+// Instantly removed in O(1) time complexity
+channel.unsub_unique(onDataReceived); 
+```
+
+    🔴 Warning: Do not manually modify or rely on the id property appended to your callback function in your external application logic.
+
+3. Single-Use / Self-Cleaning Listeners (unsubCurrent)
+
+Perfect for implementing once() behavior. If listener is It is advised to call it at the top of a listener
+```TypeScript
+
+channel.sub((data) => {
+  // Safely unsubscribes the callback while the channel is mid-publication
+  channel.unsubCurrent();
+  console.log("This will only run for the very first event dispatch:", data);
+});
+
+channel.sub(async (data)=>{
+    channel.unsubCurrent();
+    await doSomething(data);
+
+    /* Do not call unsubCurrent() here */
+})
+```

package/dist/cjs/index.js

@@ -0,0 +1,159 @@
+"use strict";
+
+/**
+ * An optimized Pub/Sub event channel designed as a high-performance, scalable alternative to the standard `EventEmitter`.
+ * Features $O(1)$ removals for unique listeners and faster creation overhead.
+ * @template MessageType The type of data payload published by this channel.
+ * @note The order of listeners is **not preserved** when removing subscribers.
+ * @see Inspired by tseep.
+ * @example
+ * type LogMessage = `[Log] ${string}`;
+ * const logChannel = new Channel<LogMessage>();
+ * const onLog = (msg: LogMessage) => console.log(msg);
+ * logChannel.sub_unique(onLog);
+ * logChannel.pub("[Log] User logged in");
+ * logChannel.unsub_unique(onLog);
+ */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ChannelMap = exports.Channel = void 0;
+class Channel {
+  cbs = [];
+  i = 0;
+  /**
+   * Indicates whether the channel currently has no active listeners.
+   */
+  get isEmpty() {
+    return !this.cbs.length;
+  }
+  /**
+   * Subscribes a listener to the channel.
+   * Use this for general listeners, that you reuse in many Channel instances OR when you need to register a listener several times OR or removal order doesn't matter.
+   * @example
+   * channel.sub((data) => console.log(data));
+   */
+  sub(fn) {
+    this.cbs.push(fn);
+  }
+  /**
+   * Subscribes a unique listener to the channel and attaches an internal ID metadata property.
+   * Use this alongside `unsub_unique` to achieve constant time $O(1)$ unsubscription performance.
+   * @example
+   * const onEvent = (data) => console.log(data);
+   * channel.sub_unique(onEvent);
+   */
+  sub_unique(fn) {
+    var cbs = this.cbs;
+    fn.id = cbs.length;
+    cbs.push(fn);
+  }
+  /**
+   * Unsubscribes a listener by performing a linear scan from the end of the array.
+   * @warning This method alters the execution order of the remaining listeners.
+   * @example
+   * channel.unsub(onEvent);
+   */
+  unsub(fn) {
+    for (var i = this.cbs.length - 1; i >= 0; i--) {
+      if (this.cbs[i] != fn) continue;
+      if (i == this.cbs.length - 1) {
+        this.cbs.pop();
+      } else {
+        let newCb = this.cbs[i] = this.cbs.pop();
+        newCb.id = i;
+      }
+      break;
+    }
+  }
+  /**
+   * Unsubscribes a listener previously registered via `sub_unique`.
+   * Leverages the internal `id` property to swap and pop elements in $O(1)$ time.
+   * @warning This method alters the execution order of the remaining listeners.
+   * @example
+   * channel.unsub_unique(onEvent);
+   */
+  unsub_unique(fn) {
+    var id = fn.id;
+    if (id == this.cbs.length - 1) {
+      this.cbs.pop();
+    } else {
+      let newCb = this.cbs[id] = this.cbs.pop();
+      newCb.id = id;
+    }
+  }
+  /**
+   * Unsubscribes the listener that is **currently executing** during a publication cycle.
+   * Useful for writing single-use ("once") listeners or self-cleaning hooks.
+   * @warning This method alters the execution order of the remaining listeners.
+   * @example
+   * channel.sub((msg) => {
+   *   console.log("Runs only once:", msg);
+   *   channel.unsubCurrent();
+   * });
+   */
+  unsubCurrent() {
+    var cbs = this.cbs;
+    if (this.i == cbs.length - 1) {
+      cbs.pop();
+      return;
+    }
+    ;
+    var newCb = cbs[this.i] = cbs.pop();
+    newCb.id = this.i--;
+  }
+  /**
+   * Publishes data synchronously to all registered listeners.
+   * Listeners can be safely removed mid-execution via `unsubCurrent()`.
+   * @example
+   * channel.pub({ eventType: "click", x: 10, y: 20 });
+   */
+  pub(data) {
+    var cbs = this.cbs;
+    while (this.i < cbs.length) {
+      cbs[this.i](data);
+      this.i++;
+    }
+    this.i = 0;
+  }
+  /**
+   * Drops all registered listeners from the channel instantly.
+   */
+  clear() {
+    this.cbs = [];
+  }
+}
+/**
+ * A strongly-typed map wrapper that dynamically manages distinct named `Channel` instances.
+ * Acts as a minimal simulation of EventEmitter
+ * For event names use should use strings performance-wise
+ * @template EventMap Type definition containing event names mapped to their respective payloads.
+ * @example
+ * interface Events {
+ *   login: { username: string };
+ * }
+ * const emitter = new ChannelMap<Events>();
+ * var channel = emitter.on("login");
+ * channel.sub(({ username }) => console.log(username));
+ * channel.pub({ username: "Neo" });
+ */
+exports.Channel = Channel;
+class ChannelMap {
+  /* Map get initialised lazily*/
+  events = {};
+  /**
+   * Retrieves or instantiates the specific `Channel` instance tied to an event name.
+   * @param ev The event name/key.
+   * @returns The `Channel` handling the event payload type.
+   */
+  on(ev) {
+    return this.events[ev] ??= new Channel();
+  }
+  /**
+   * @param ev The optional event name/key. If present - clears the channel for event. Otherwise - remove all channels
+   */
+  removeAllListeners(ev) {
+    ev ? this.events[ev]?.clear() : this.events = {};
+  }
+}
+exports.ChannelMap = ChannelMap;

package/dist/esm/index.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * An optimized Pub/Sub event channel designed as a high-performance, scalable alternative to the standard `EventEmitter`.
+ * Features $O(1)$ removals for unique listeners and faster creation overhead.
+ * @template MessageType The type of data payload published by this channel.
+ * @note The order of listeners is **not preserved** when removing subscribers.
+ * @see Inspired by tseep.
+ * @example
+ * type LogMessage = `[Log] ${string}`;
+ * const logChannel = new Channel<LogMessage>();
+ * const onLog = (msg: LogMessage) => console.log(msg);
+ * logChannel.sub_unique(onLog);
+ * logChannel.pub("[Log] User logged in");
+ * logChannel.unsub_unique(onLog);
+ */
+export class Channel {
+    cbs = [];
+    i = 0;
+    /**
+     * Indicates whether the channel currently has no active listeners.
+     */
+    get isEmpty() { return !this.cbs.length; }
+    /**
+     * Subscribes a listener to the channel.
+     * Use this for general listeners, that you reuse in many Channel instances OR when you need to register a listener several times OR or removal order doesn't matter.
+     * @example
+     * channel.sub((data) => console.log(data));
+     */
+    sub(fn) {
+        this.cbs.push(fn);
+    }
+    /**
+     * Subscribes a unique listener to the channel and attaches an internal ID metadata property.
+     * Use this alongside `unsub_unique` to achieve constant time $O(1)$ unsubscription performance.
+     * @example
+     * const onEvent = (data) => console.log(data);
+     * channel.sub_unique(onEvent);
+     */
+    sub_unique(fn) {
+        var cbs = this.cbs;
+        fn.id = cbs.length;
+        cbs.push(fn);
+    }
+    /**
+     * Unsubscribes a listener by performing a linear scan from the end of the array.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.unsub(onEvent);
+     */
+    unsub(fn) {
+        for (var i = this.cbs.length - 1; i >= 0; i--) {
+            if (this.cbs[i] != fn)
+                continue;
+            if (i == this.cbs.length - 1) {
+                this.cbs.pop();
+            }
+            else {
+                let newCb = (this.cbs[i] = this.cbs.pop());
+                newCb.id = i;
+            }
+            break;
+        }
+    }
+    /**
+     * Unsubscribes a listener previously registered via `sub_unique`.
+     * Leverages the internal `id` property to swap and pop elements in $O(1)$ time.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.unsub_unique(onEvent);
+     */
+    unsub_unique(fn) {
+        var id = fn.id;
+        if (id == this.cbs.length - 1) {
+            this.cbs.pop();
+        }
+        else {
+            let newCb = (this.cbs[id] = this.cbs.pop());
+            newCb.id = id;
+        }
+    }
+    /**
+     * Unsubscribes the listener that is **currently executing** during a publication cycle.
+     * Useful for writing single-use ("once") listeners or self-cleaning hooks.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.sub((msg) => {
+     *   console.log("Runs only once:", msg);
+     *   channel.unsubCurrent();
+     * });
+     */
+    unsubCurrent() {
+        var cbs = this.cbs;
+        if (this.i == cbs.length - 1) {
+            cbs.pop();
+            return;
+        }
+        ;
+        var newCb = (cbs[this.i] = cbs.pop());
+        newCb.id = this.i--;
+    }
+    /**
+     * Publishes data synchronously to all registered listeners.
+     * Listeners can be safely removed mid-execution via `unsubCurrent()`.
+     * @example
+     * channel.pub({ eventType: "click", x: 10, y: 20 });
+     */
+    pub(data) {
+        var cbs = this.cbs;
+        while (this.i < cbs.length) {
+            cbs[this.i](data);
+            this.i++;
+        }
+        this.i = 0;
+    }
+    /**
+     * Drops all registered listeners from the channel instantly.
+     */
+    clear() { this.cbs = []; }
+}
+/**
+ * A strongly-typed map wrapper that dynamically manages distinct named `Channel` instances.
+ * Acts as a minimal simulation of EventEmitter
+ * For event names use should use strings performance-wise
+ * @template EventMap Type definition containing event names mapped to their respective payloads.
+ * @example
+ * interface Events {
+ *   login: { username: string };
+ * }
+ * const emitter = new ChannelMap<Events>();
+ * var channel = emitter.on("login");
+ * channel.sub(({ username }) => console.log(username));
+ * channel.pub({ username: "Neo" });
+ */
+export class ChannelMap {
+    /* Map get initialised lazily*/
+    events = {};
+    /**
+     * Retrieves or instantiates the specific `Channel` instance tied to an event name.
+     * @param ev The event name/key.
+     * @returns The `Channel` handling the event payload type.
+     */
+    on(ev) {
+        return this.events[ev] ??= new Channel();
+    }
+    /**
+     * @param ev The optional event name/key. If present - clears the channel for event. Otherwise - remove all channels
+     */
+    removeAllListeners(ev) {
+        ev ? this.events[ev]?.clear() : this.events = {};
+    }
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/types/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * A callback function used as a listener in a `Channel`.
+ * * @template T The type of data payload this callback receives.
+ * * @note This type is mutated internally with an `id` property to achieve $O(1)$ lookup times during unsubscription.
+ * **Do not manually modify or rely on the `id` property in external code.**
+ */
+export type ChannelCB<T> = ((data: T) => void) & {
+    id?: number;
+};
+/**
+ * An optimized Pub/Sub event channel designed as a high-performance, scalable alternative to the standard `EventEmitter`.
+ * Features $O(1)$ removals for unique listeners and faster creation overhead.
+ * @template MessageType The type of data payload published by this channel.
+ * @note The order of listeners is **not preserved** when removing subscribers.
+ * @see Inspired by tseep.
+ * @example
+ * type LogMessage = `[Log] ${string}`;
+ * const logChannel = new Channel<LogMessage>();
+ * const onLog = (msg: LogMessage) => console.log(msg);
+ * logChannel.sub_unique(onLog);
+ * logChannel.pub("[Log] User logged in");
+ * logChannel.unsub_unique(onLog);
+ */
+export declare class Channel<MessageType> {
+    protected cbs: ChannelCB<MessageType>[];
+    protected i: number;
+    /**
+     * Indicates whether the channel currently has no active listeners.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Subscribes a listener to the channel.
+     * Use this for general listeners, that you reuse in many Channel instances OR when you need to register a listener several times OR or removal order doesn't matter.
+     * @example
+     * channel.sub((data) => console.log(data));
+     */
+    sub(fn: ChannelCB<MessageType>): void;
+    /**
+     * Subscribes a unique listener to the channel and attaches an internal ID metadata property.
+     * Use this alongside `unsub_unique` to achieve constant time $O(1)$ unsubscription performance.
+     * @example
+     * const onEvent = (data) => console.log(data);
+     * channel.sub_unique(onEvent);
+     */
+    sub_unique(fn: ChannelCB<MessageType>): void;
+    /**
+     * Unsubscribes a listener by performing a linear scan from the end of the array.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.unsub(onEvent);
+     */
+    unsub(fn: ChannelCB<MessageType>): void;
+    /**
+     * Unsubscribes a listener previously registered via `sub_unique`.
+     * Leverages the internal `id` property to swap and pop elements in $O(1)$ time.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.unsub_unique(onEvent);
+     */
+    unsub_unique(fn: ChannelCB<MessageType>): void;
+    /**
+     * Unsubscribes the listener that is **currently executing** during a publication cycle.
+     * Useful for writing single-use ("once") listeners or self-cleaning hooks.
+     * @warning This method alters the execution order of the remaining listeners.
+     * @example
+     * channel.sub((msg) => {
+     *   console.log("Runs only once:", msg);
+     *   channel.unsubCurrent();
+     * });
+     */
+    unsubCurrent(): void;
+    /**
+     * Publishes data synchronously to all registered listeners.
+     * Listeners can be safely removed mid-execution via `unsubCurrent()`.
+     * @example
+     * channel.pub({ eventType: "click", x: 10, y: 20 });
+     */
+    pub(data: MessageType): void;
+    /**
+     * Drops all registered listeners from the channel instantly.
+     */
+    clear(): void;
+}
+/**
+ * A strongly-typed map wrapper that dynamically manages distinct named `Channel` instances.
+ * Acts as a minimal simulation of EventEmitter
+ * For event names use should use strings performance-wise
+ * @template EventMap Type definition containing event names mapped to their respective payloads.
+ * @example
+ * interface Events {
+ *   login: { username: string };
+ * }
+ * const emitter = new ChannelMap<Events>();
+ * var channel = emitter.on("login");
+ * channel.sub(({ username }) => console.log(username));
+ * channel.pub({ username: "Neo" });
+ */
+export declare class ChannelMap<EventMap extends Record<string | number | symbol, any>> {
+    protected events: EventMap;
+    /**
+     * Retrieves or instantiates the specific `Channel` instance tied to an event name.
+     * @param ev The event name/key.
+     * @returns The `Channel` handling the event payload type.
+     */
+    on<Event extends keyof EventMap>(ev: Event): Channel<EventMap[Event]>;
+    /**
+     * @param ev The optional event name/key. If present - clears the channel for event. Otherwise - remove all channels
+     */
+    removeAllListeners(ev?: keyof EventMap): void;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ublitzjs/channel",
+  "version": "1.0.0",
+  "types": "./dist/types/index.d.ts",
+  "files": ["dist", "LICENSE"],
+  "typesVersions": {
+    "*": {
+      ".": ["./dist/types/index.d.ts"]
+    }
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-transform-modules-commonjs": "^7.28.6",
+    "@types/node": "^25.9.1",
+    "cozyevent": "^1.3.3",
+    "esbuild": "^0.25.12",
+    "tinybench": "^6.0.0",
+    "tsd": "^0.33.0",
+    "tseep": "^1.3.1"
+  },
+  "scripts": {
+    "trick-tsd": "bun link && bun link @ublitzjs/channel",
+    "build:esm": "tsc -p tsconfig.esm.json && echo '{\"type\": \"module\"}' > dist/esm/package.json",
+    "build:cjs": "babel dist/esm --out-dir dist/cjs",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build": "npm run build:types && npm run build:esm && npm run build:cjs",
+    "test": "tsd && vitest run tests/index.test.ts --coverage",
+    "bench:node": "node tests/bench.mjs",
+    "bench:bun": "bun tests/bench.mjs"
+  },
+  "tsd": {
+    "directory": "tests"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ublitzjs/channel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ublitzjs/channel/issues",
+    "email": "diril656@gmail.com"
+  },
+  "homepage": "https://github.com/ublitzjs/channel#readme",
+  "keywords": [
+    "ublitzjs",
+    "typescript",
+    "development",
+    "pub/sub",
+    "fastest event emitter",
+    "O(1)",
+    "asynchronous code",
+    "µBlitz.js"
+  ],
+  "dependencies": {
+    "@vitest/coverage-v8": "^4.1.7",
+    "vitest": "^4.1.7"
+  }
+}