@guanghechen/eventbus 7.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
+
+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,147 @@
+<header>
+  <h1 align="center">
+    <a href="https://github.com/guanghechen/sora/tree/@guanghechen/eventbus@7.0.0/packages/eventbus#readme">@guanghechen/eventbus</a>
+  </h1>
+  <div align="center">
+    <a href="https://www.npmjs.com/package/@guanghechen/eventbus">
+      <img
+        alt="Npm Version"
+        src="https://img.shields.io/npm/v/@guanghechen/eventbus.svg"
+      />
+    </a>
+    <a href="https://www.npmjs.com/package/@guanghechen/eventbus">
+      <img
+        alt="Npm Download"
+        src="https://img.shields.io/npm/dm/@guanghechen/eventbus.svg"
+      />
+    </a>
+    <a href="https://www.npmjs.com/package/@guanghechen/eventbus">
+      <img
+        alt="Npm License"
+        src="https://img.shields.io/npm/l/@guanghechen/eventbus.svg"
+      />
+    </a>
+    <a href="#install">
+      <img
+        alt="Module Formats: cjs, esm"
+        src="https://img.shields.io/badge/module_formats-cjs%2C%20esm-green.svg"
+      />
+    </a>
+    <a href="https://github.com/nodejs/node">
+      <img
+        alt="Node.js Version"
+        src="https://img.shields.io/node/v/@guanghechen/eventbus"
+      />
+    </a>
+    <a href="https://github.com/vitest-dev/vitest">
+      <img
+        alt="Tested with Vitest"
+        src="https://img.shields.io/badge/tested_with-vitest-6e9f18.svg"
+      />
+    </a>
+    <a href="https://github.com/prettier/prettier">
+      <img
+        alt="Code Style: prettier"
+        src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square"
+      />
+    </a>
+  </div>
+</header>
+<br/>
+
+A simple event bus with disposable support.
+
+## Features
+
+- Type-specific listeners (`on`/`once`) and global subscribers (`subscribe`)
+- Returns `IUnsubscribable` for easy cleanup
+- Implements `IBatchDisposable` for resource management
+- Exception isolation: one handler's error won't stop other handlers
+- Alias methods: `off` for `removeListener`, `emit` for `dispatch`
+- `listenerCount()` to get the number of listeners
+
+## Install
+
+- npm
+
+  ```bash
+  npm install --save @guanghechen/eventbus
+  ```
+
+- yarn
+
+  ```bash
+  yarn add @guanghechen/eventbus
+  ```
+
+## Usage
+
+```typescript
+import type { IEvent, IEventHandler } from '@guanghechen/eventbus'
+import { EventBus } from '@guanghechen/eventbus'
+
+enum EventTypes {
+  INIT = 'INIT',
+  EXIT = 'EXIT',
+}
+
+const eventBus = new EventBus<EventTypes>('my-bus')
+
+const handle: IEventHandler<EventTypes> = (evt, eventBus): void => {
+  console.log('evt:', evt)
+}
+
+// Listen for specific event, returns IUnsubscribable
+const unsub1 = eventBus.on(EventTypes.INIT, handle)
+
+// Listen for specific event, auto-removed after first call
+const unsub2 = eventBus.once(EventTypes.INIT, handle)
+
+// Subscribe to all events
+const unsub3 = eventBus.subscribe(handle)
+
+// Dispatch an event
+eventBus.dispatch({ type: EventTypes.INIT, payload: { id: 1 } })
+// Or use alias
+eventBus.emit({ type: EventTypes.INIT, payload: { id: 1 } })
+
+// Remove listener
+eventBus.off(EventTypes.INIT, handle)
+// Or use unsubscribable
+unsub1.unsubscribe()
+
+// Get listener count
+console.log(eventBus.listenerCount()) // all listeners + subscribers
+console.log(eventBus.listenerCount(EventTypes.INIT)) // only INIT listeners
+
+// Cleanup all listeners and subscribers
+eventBus.cleanup()
+
+// Dispose the event bus (also disposes registered disposables)
+eventBus.dispose()
+```
+
+## API
+
+### `EventBus<T>`
+
+| Method                              | Description                                           |
+| ----------------------------------- | ----------------------------------------------------- |
+| `on(type, handle)`                  | Listen for a specific event type                      |
+| `once(type, handle)`                | Listen for a specific event type, auto-removed        |
+| `off(type, handle)`                 | Remove a listener (alias of `removeListener`)         |
+| `removeListener(type, handle)`      | Remove a listener                                     |
+| `subscribe(handle, once?)`          | Subscribe to all events                               |
+| `unsubscribe(handle)`               | Cancel a subscription                                 |
+| `dispatch(evt)`                     | Dispatch an event                                     |
+| `emit(evt)`                         | Dispatch an event (alias of `dispatch`)               |
+| `listenerCount(type?)`              | Get listener count                                    |
+| `cleanup()`                         | Remove all listeners and subscribers                  |
+| `dispose()`                         | Dispose the event bus                                 |
+| `registerDisposable(disposable)`    | Register a disposable to be disposed with the bus     |
+
+## Reference
+
+- [homepage][homepage]
+
+[homepage]: https://github.com/guanghechen/sora/tree/@guanghechen/eventbus@7.0.0/packages/eventbus#readme

package/lib/cjs/index.cjs

@@ -0,0 +1,153 @@
+'use strict';
+
+function filterInPlace(elements, predicate) {
+    let tot = 0;
+    for (let i = 0; i < elements.length; ++i) {
+        const el = elements[i];
+        if (predicate(el, i)) {
+            elements[tot] = el;
+            tot += 1;
+        }
+    }
+    elements.length = tot;
+}
+
+class EventBus {
+    name;
+    _disposed;
+    _listeners;
+    _subscribers;
+    _disposables;
+    constructor(name) {
+        this.name = name;
+        this._disposed = false;
+        this._listeners = new Map();
+        this._subscribers = [];
+        this._disposables = [];
+    }
+    get disposed() {
+        return this._disposed;
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        const errors = [];
+        for (const disposable of this._disposables) {
+            try {
+                disposable.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        this._disposables.length = 0;
+        this._listeners.clear();
+        this._subscribers.length = 0;
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'EventBus dispose encountered errors');
+        }
+    }
+    registerDisposable(disposable) {
+        if (disposable.disposed)
+            return;
+        if (this._disposed) {
+            disposable.dispose();
+        }
+        else {
+            this._disposables.push(disposable);
+        }
+    }
+    on(type, handle) {
+        return this._addListener(type, handle, false);
+    }
+    once(type, handle) {
+        return this._addListener(type, handle, true);
+    }
+    off(type, handle) {
+        this.removeListener(type, handle);
+    }
+    removeListener(type, handle) {
+        const listeners = this._listeners.get(type);
+        if (listeners) {
+            filterInPlace(listeners, listener => listener.handle !== handle);
+        }
+    }
+    subscribe(handle, once = false) {
+        const existing = this._subscribers.find(subscriber => subscriber.handle === handle);
+        if (existing) {
+            existing.once = once;
+            return { unsubscribe: () => this.unsubscribe(handle) };
+        }
+        this._subscribers.push({ once, handle: handle });
+        return { unsubscribe: () => this.unsubscribe(handle) };
+    }
+    unsubscribe(handle) {
+        filterInPlace(this._subscribers, subscriber => subscriber.handle !== handle);
+    }
+    dispatch(evt) {
+        if (this._disposed)
+            return;
+        const errors = [];
+        const subscribers = [...this._subscribers];
+        for (const subscriber of subscribers) {
+            try {
+                subscriber.handle(evt, this);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        filterInPlace(this._subscribers, subscriber => !subscriber.once);
+        const listeners = this._listeners.get(evt.type);
+        if (listeners) {
+            const snapshot = [...listeners];
+            for (const listener of snapshot) {
+                try {
+                    listener.handle(evt, this);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            filterInPlace(listeners, listener => !listener.once);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'EventBus dispatch encountered errors');
+        }
+    }
+    emit(evt) {
+        this.dispatch(evt);
+    }
+    listenerCount(type) {
+        if (type !== undefined) {
+            const listeners = this._listeners.get(type);
+            return listeners ? listeners.length : 0;
+        }
+        let count = this._subscribers.length;
+        for (const listeners of this._listeners.values()) {
+            count += listeners.length;
+        }
+        return count;
+    }
+    cleanup() {
+        this._listeners.clear();
+        this._subscribers.length = 0;
+    }
+    _addListener(type, handle, once) {
+        let listeners = this._listeners.get(type);
+        if (!listeners) {
+            listeners = [];
+            this._listeners.set(type, listeners);
+        }
+        const existing = listeners.find(listener => listener.handle === handle);
+        if (existing) {
+            existing.once = once;
+            return { unsubscribe: () => this.removeListener(type, handle) };
+        }
+        listeners.push({ once, handle: handle });
+        return { unsubscribe: () => this.removeListener(type, handle) };
+    }
+}
+
+exports.EventBus = EventBus;

package/lib/esm/index.mjs

@@ -0,0 +1,151 @@
+function filterInPlace(elements, predicate) {
+    let tot = 0;
+    for (let i = 0; i < elements.length; ++i) {
+        const el = elements[i];
+        if (predicate(el, i)) {
+            elements[tot] = el;
+            tot += 1;
+        }
+    }
+    elements.length = tot;
+}
+
+class EventBus {
+    name;
+    _disposed;
+    _listeners;
+    _subscribers;
+    _disposables;
+    constructor(name) {
+        this.name = name;
+        this._disposed = false;
+        this._listeners = new Map();
+        this._subscribers = [];
+        this._disposables = [];
+    }
+    get disposed() {
+        return this._disposed;
+    }
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        const errors = [];
+        for (const disposable of this._disposables) {
+            try {
+                disposable.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        this._disposables.length = 0;
+        this._listeners.clear();
+        this._subscribers.length = 0;
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'EventBus dispose encountered errors');
+        }
+    }
+    registerDisposable(disposable) {
+        if (disposable.disposed)
+            return;
+        if (this._disposed) {
+            disposable.dispose();
+        }
+        else {
+            this._disposables.push(disposable);
+        }
+    }
+    on(type, handle) {
+        return this._addListener(type, handle, false);
+    }
+    once(type, handle) {
+        return this._addListener(type, handle, true);
+    }
+    off(type, handle) {
+        this.removeListener(type, handle);
+    }
+    removeListener(type, handle) {
+        const listeners = this._listeners.get(type);
+        if (listeners) {
+            filterInPlace(listeners, listener => listener.handle !== handle);
+        }
+    }
+    subscribe(handle, once = false) {
+        const existing = this._subscribers.find(subscriber => subscriber.handle === handle);
+        if (existing) {
+            existing.once = once;
+            return { unsubscribe: () => this.unsubscribe(handle) };
+        }
+        this._subscribers.push({ once, handle: handle });
+        return { unsubscribe: () => this.unsubscribe(handle) };
+    }
+    unsubscribe(handle) {
+        filterInPlace(this._subscribers, subscriber => subscriber.handle !== handle);
+    }
+    dispatch(evt) {
+        if (this._disposed)
+            return;
+        const errors = [];
+        const subscribers = [...this._subscribers];
+        for (const subscriber of subscribers) {
+            try {
+                subscriber.handle(evt, this);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        filterInPlace(this._subscribers, subscriber => !subscriber.once);
+        const listeners = this._listeners.get(evt.type);
+        if (listeners) {
+            const snapshot = [...listeners];
+            for (const listener of snapshot) {
+                try {
+                    listener.handle(evt, this);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            filterInPlace(listeners, listener => !listener.once);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'EventBus dispatch encountered errors');
+        }
+    }
+    emit(evt) {
+        this.dispatch(evt);
+    }
+    listenerCount(type) {
+        if (type !== undefined) {
+            const listeners = this._listeners.get(type);
+            return listeners ? listeners.length : 0;
+        }
+        let count = this._subscribers.length;
+        for (const listeners of this._listeners.values()) {
+            count += listeners.length;
+        }
+        return count;
+    }
+    cleanup() {
+        this._listeners.clear();
+        this._subscribers.length = 0;
+    }
+    _addListener(type, handle, once) {
+        let listeners = this._listeners.get(type);
+        if (!listeners) {
+            listeners = [];
+            this._listeners.set(type, listeners);
+        }
+        const existing = listeners.find(listener => listener.handle === handle);
+        if (existing) {
+            existing.once = once;
+            return { unsubscribe: () => this.removeListener(type, handle) };
+        }
+        listeners.push({ once, handle: handle });
+        return { unsubscribe: () => this.removeListener(type, handle) };
+    }
+}
+
+export { EventBus };

package/lib/types/index.d.ts

@@ -0,0 +1,134 @@
+import { IBatchDisposable, IUnsubscribable, IDisposable } from '@guanghechen/types';
+
+type IEventType = number | string | symbol;
+type IEventPayload = number | boolean | string | symbol | object;
+interface IEvent<T extends IEventType = IEventType, P extends IEventPayload = IEventPayload> {
+    type: T;
+    payload?: P;
+}
+/**
+ * The returned value will be ignored.
+ * @param evt
+ * @param eventBus
+ */
+type IEventHandler<T extends IEventType = IEventType, P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>> = (evt: Readonly<E>, eventBus: IEventBus<T>) => void;
+/**
+ * Internal subscription record.
+ */
+interface IEventSubscription<T extends IEventType = IEventType, P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>> {
+    /**
+     * If true, will be auto-removed after first called.
+     */
+    once: boolean;
+    /**
+     * Event handler.
+     */
+    handle: IEventHandler<T, P, E>;
+}
+interface IEventBus<T extends IEventType> extends IBatchDisposable {
+    /**
+     * Name of the event bus instance, useful for debugging.
+     */
+    readonly name: string;
+    /**
+     * Listen for a specific event type.
+     * @param type
+     * @param handle
+     * @returns IUnsubscribable to remove the listener
+     */
+    on<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): IUnsubscribable;
+    /**
+     * Listen for a specific event type, auto-removed after first call.
+     * @param type
+     * @param handle
+     * @returns IUnsubscribable to remove the listener
+     */
+    once<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): IUnsubscribable;
+    /**
+     * Remove a listener for a specific event type.
+     * Alias: removeListener
+     * @param type
+     * @param handle
+     */
+    off<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): void;
+    /**
+     * Remove a listener for a specific event type.
+     * @param type
+     * @param handle
+     */
+    removeListener<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): void;
+    /**
+     * Subscribe to all event types.
+     * @param handle
+     * @param once If true, auto-removed after first call. Defaults to false.
+     * @returns IUnsubscribable to cancel the subscription
+     */
+    subscribe<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(handle: IEventHandler<T, P, E>, once?: boolean): IUnsubscribable;
+    /**
+     * Cancel a subscription.
+     * @param handle
+     */
+    unsubscribe<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(handle: IEventHandler<T, P, E>): void;
+    /**
+     * Dispatch an event to all listeners and subscribers.
+     * Alias: emit
+     * @param evt
+     */
+    dispatch<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(evt: Readonly<E>): void;
+    /**
+     * Dispatch an event to all listeners and subscribers.
+     * @param evt
+     */
+    emit<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(evt: Readonly<E>): void;
+    /**
+     * Get the number of listeners.
+     * @param type If provided, count listeners for that type only. Otherwise, count all.
+     */
+    listenerCount(type?: T): number;
+    /**
+     * Remove all listeners and subscribers.
+     */
+    cleanup(): void;
+}
+
+/**
+ * A simple event bus implementation with disposable support.
+ *
+ * Features:
+ *  - Supports both type-specific listeners (on/once) and global subscribers (subscribe)
+ *  - Returns IUnsubscribable for easy cleanup
+ *  - Implements IBatchDisposable for resource management
+ *  - Exception isolation: one handler's error won't stop other handlers
+ *  - Listeners/subscribers are notified in registration order
+ *
+ * Note on `once` semantics:
+ *  All `once` handlers are removed after each dispatch cycle completes.
+ *  If a new `once` handler is registered during dispatch (e.g., inside another handler),
+ *  it will also be removed at the end of that dispatch without being called.
+ *  Use `on()` + manual `unsubscribe()` if you need more control over handler lifecycle.
+ */
+declare class EventBus<T extends IEventType> implements IEventBus<T> {
+    readonly name: string;
+    protected _disposed: boolean;
+    protected _listeners: Map<T, Array<IEventSubscription<T>>>;
+    protected _subscribers: Array<IEventSubscription<T>>;
+    protected _disposables: IDisposable[];
+    constructor(name: string);
+    get disposed(): boolean;
+    dispose(): void;
+    registerDisposable<D extends IDisposable>(disposable: D): void;
+    on<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): IUnsubscribable;
+    once<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): IUnsubscribable;
+    off<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): void;
+    removeListener<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>): void;
+    subscribe<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(handle: IEventHandler<T, P, E>, once?: boolean): IUnsubscribable;
+    unsubscribe<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(handle: IEventHandler<T, P, E>): void;
+    dispatch<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(evt: Readonly<E>): void;
+    emit<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(evt: Readonly<E>): void;
+    listenerCount(type?: T): number;
+    cleanup(): void;
+    protected _addListener<P extends IEventPayload = IEventPayload, E extends IEvent<T, P> = IEvent<T, P>>(type: T, handle: IEventHandler<T, P, E>, once: boolean): IUnsubscribable;
+}
+
+export { EventBus };
+export type { IEvent, IEventBus, IEventHandler, IEventPayload, IEventSubscription, IEventType };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@guanghechen/eventbus",
+  "version": "7.0.1",
+  "description": "A simple event bus with disposable support.",
+  "author": {
+    "name": "guanghechen",
+    "url": "https://github.com/guanghechen/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/eventbus@7.0.0",
+    "directory": "packages/eventbus"
+  },
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/eventbus@7.0.0/packages/eventbus#readme",
+  "keywords": [
+    "event bus",
+    "eventbus",
+    "pub-sub"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./lib/esm/index.mjs",
+      "require": "./lib/cjs/index.cjs"
+    }
+  },
+  "source": "./src/index.ts",
+  "main": "./lib/cjs/index.cjs",
+  "module": "./lib/esm/index.mjs",
+  "types": "./lib/types/index.d.ts",
+  "license": "MIT",
+  "dependencies": {
+    "@guanghechen/types": "^2.0.1"
+  },
+  "files": [
+    "lib/",
+    "!lib/**/*.map",
+    "package.json",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}