@axijs/emitter 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# @axijs/emitter
+
+[![NPM version](https://img.shields.io/npm/v/@axijs/emitter.svg)](https://www.npmjs.com/package/@axijs/emitter)
+
+A minimalistic, type-safe library for single-event and state emitting. 
+
+Inspired by the Observer pattern and RxJS (like `BehaviorSubject`), 
+it provides a clean way to manage subscriptions.
+
+## Installation
+
+```bash
+npm install @axijs/emitter
+# or
+pnpm add @axijs/emitter
+# or
+yarn add @axijs/emitter
+```
+
+## Features
+
+- **Strictly Typed**: Full TypeScript support for event arguments.
+- **No Magic Strings**: Object-based emitters instead of string keys (e.g., `on('event-name')`).
+- **State Emitting**: `StateEmitter` remembers the last emitted value and immediately triggers new subscribers.
+- **Composite Subscriptions**: Easily group multiple subscriptions and teardown logic into a single `Subscription` object to prevent memory leaks.
+
+## Usage
+
+### 1. Basic Event Emitter
+Create an isolated, strongly-typed event emitter.
+
+```typescript
+import { Emitter } from '@axijs/emitter';
+
+// Define an emitter that expects a string and a number
+const onPlayerMove = new Emitter<[string, number]>();
+
+// Subscribe to the event
+const sub = onPlayerMove.subscribe((player, x) => {
+  console.log(`${player} moved to ${x}`);
+});
+
+// Fire the event
+onPlayerMove.emit('Alice', 10); 
+
+// Subscribe to fire only once
+onPlayerMove.once((player, x) => {
+  console.log('This will only run once!');
+});
+
+// Unsubscribe when no longer needed
+sub.unsubscribe();
+```
+
+### 2. State Emitter
+Acts like a state container (similar to `BehaviorSubject`). 
+It holds the latest value and immediately provides it to new subscribers.
+
+```typescript
+import { StateEmitter } from '@axijs/emitter';
+
+// Initialize with a default state
+const health = new StateEmitter<[number]>([100]);
+
+// New subscribers immediately receive the current state (100)
+health.subscribe((currentHealth) => {
+  console.log(`Health is: ${currentHealth}`);
+});
+
+// Emit a new state. All listeners will be notified.
+health.emit(80);
+
+// Get current state synchronously without subscribing
+console.log(health.value); // [80]
+```
+
+### 3. Composite Subscriptions
+Group multiple unsubscriptions together. Very useful for cleaning up UI components or game objects.
+
+```typescript
+import { Emitter, Subscription } from '@axijs/emitter';
+
+const onJump = new Emitter<[]>();
+const onShoot = new Emitter<[]>();
+
+const masterSub = new Subscription();
+
+// Add multiple subscriptions to the master Subscription
+masterSub.add(onJump.subscribe(() => console.log('Jumped!')));
+masterSub.add(onShoot.subscribe(() => console.log('Pew pew!')));
+
+// You can also add custom teardown functions
+masterSub.add(() => {
+  console.log('Custom cleanup logic executed');
+});
+
+// Later, when the component/object is destroyed:
+masterSub.unsubscribe(); 
+// This automatically unsubscribes from both events and runs the custom logic
+```
+
+## API Documentation
+
+For a complete list of classes, interfaces, and methods, please visit the [API Documentation](https://github.com/axijs/tools/tree/main/packages/emitter/docs/api).
+
+## License
+
+MIT
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+/**
+ * Defines the public, read-only contract for an event emitter.
+ * It allows subscribing to an event but not emitting it.
+ * @template T A tuple representing the types of the event arguments.
+ */
+type Subscribable<T extends any[]> = {
+    readonly listenerCount: number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): Unsubscribable;
+    unsubscribe(listener: (...args: T) => void): boolean;
+    clear(): void;
+};
+/**
+ * Describes an object that can be unsubscribed from.
+ */
+interface Unsubscribable {
+    unsubscribe(): void;
+}
+
+/**
+ * Represents a disposable resource, such as the execution of an Observable or an Event Listener.
+ * Allows grouping multiple teardown logic into a single unit (Composite Subscription).
+ */
+declare class Subscription implements Unsubscribable {
+    private _closed;
+    private _teardowns;
+    /**
+     * Indicates whether this subscription has already been unsubscribed.
+     */
+    get closed(): boolean;
+    /**
+     * @param teardown Optional initial teardown logic to execute when unsubscribed.
+     */
+    constructor(teardown?: () => void);
+    /**
+     * Adds a teardown logic to this subscription.
+     * If the subscription is already closed, the teardown is executed immediately.
+     * @param teardown A function or another Unsubscribable object to be managed.
+     */
+    add(teardown: Unsubscribable | (() => void)): void;
+    /**
+     * Disposes the resources held by the subscription.
+     * Executes all attached teardown logic and clears the list.
+     */
+    unsubscribe(): void;
+}
+
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> implements Subscribable<T> {
+    private listeners;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A Subscription object to manage the unsubscription.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    /**
+     * Subscribes a listener that triggers only once and then automatically unsubscribes.
+     * @param listener The callback function to execute once.
+     * @returns A Subscription object (can be used to cancel before the event fires).
+     */
+    once(listener: (...args: T) => void): Subscription;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+}
+
+/**
+ * An Emitter that stores the last emitted value.
+ * New subscribers immediately receive the last value upon subscription.
+ */
+declare class StateEmitter<T extends any[]> extends Emitter<T> {
+    private _lastValue;
+    /**
+     * @param initialValue Optional initial value to set.
+     */
+    constructor(initialValue?: T);
+    /**
+     * Gets the current value synchronously without subscribing.
+     */
+    get value(): T | undefined;
+    /**
+     * Updates the state and notifies all listeners.
+     * @param args The new value(s).
+     */
+    emit(...args: T): void;
+    /**
+     * Subscribes to the event. If a value exists, the listener is called immediately.
+     * @param listener The callback function.
+     * @returns A Subscription object.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    clear(): void;
+}
+
+export { Emitter, StateEmitter, type Subscribable, Subscription, type Unsubscribable };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Defines the public, read-only contract for an event emitter.
+ * It allows subscribing to an event but not emitting it.
+ * @template T A tuple representing the types of the event arguments.
+ */
+type Subscribable<T extends any[]> = {
+    readonly listenerCount: number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): Unsubscribable;
+    unsubscribe(listener: (...args: T) => void): boolean;
+    clear(): void;
+};
+/**
+ * Describes an object that can be unsubscribed from.
+ */
+interface Unsubscribable {
+    unsubscribe(): void;
+}
+
+/**
+ * Represents a disposable resource, such as the execution of an Observable or an Event Listener.
+ * Allows grouping multiple teardown logic into a single unit (Composite Subscription).
+ */
+declare class Subscription implements Unsubscribable {
+    private _closed;
+    private _teardowns;
+    /**
+     * Indicates whether this subscription has already been unsubscribed.
+     */
+    get closed(): boolean;
+    /**
+     * @param teardown Optional initial teardown logic to execute when unsubscribed.
+     */
+    constructor(teardown?: () => void);
+    /**
+     * Adds a teardown logic to this subscription.
+     * If the subscription is already closed, the teardown is executed immediately.
+     * @param teardown A function or another Unsubscribable object to be managed.
+     */
+    add(teardown: Unsubscribable | (() => void)): void;
+    /**
+     * Disposes the resources held by the subscription.
+     * Executes all attached teardown logic and clears the list.
+     */
+    unsubscribe(): void;
+}
+
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> implements Subscribable<T> {
+    private listeners;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A Subscription object to manage the unsubscription.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    /**
+     * Subscribes a listener that triggers only once and then automatically unsubscribes.
+     * @param listener The callback function to execute once.
+     * @returns A Subscription object (can be used to cancel before the event fires).
+     */
+    once(listener: (...args: T) => void): Subscription;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+}
+
+/**
+ * An Emitter that stores the last emitted value.
+ * New subscribers immediately receive the last value upon subscription.
+ */
+declare class StateEmitter<T extends any[]> extends Emitter<T> {
+    private _lastValue;
+    /**
+     * @param initialValue Optional initial value to set.
+     */
+    constructor(initialValue?: T);
+    /**
+     * Gets the current value synchronously without subscribing.
+     */
+    get value(): T | undefined;
+    /**
+     * Updates the state and notifies all listeners.
+     * @param args The new value(s).
+     */
+    emit(...args: T): void;
+    /**
+     * Subscribes to the event. If a value exists, the listener is called immediately.
+     * @param listener The callback function.
+     * @returns A Subscription object.
+     */
+    subscribe(listener: (...args: T) => void): Subscription;
+    clear(): void;
+}
+
+export { Emitter, StateEmitter, type Subscribable, Subscription, type Unsubscribable };

package/dist/index.js

@@ -0,0 +1,172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Emitter: () => Emitter,
+  StateEmitter: () => StateEmitter,
+  Subscription: () => Subscription
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../ensure/dist/index.mjs
+function isFunction(value) {
+  return typeof value === "function";
+}
+
+// src/subscription.ts
+var Subscription = class {
+  _closed = false;
+  _teardowns = [];
+  /**
+   * Indicates whether this subscription has already been unsubscribed.
+   */
+  get closed() {
+    return this._closed;
+  }
+  /**
+   * @param teardown Optional initial teardown logic to execute when unsubscribed.
+   */
+  constructor(teardown) {
+    if (teardown) {
+      this._teardowns.push(teardown);
+    }
+  }
+  /**
+   * Adds a teardown logic to this subscription.
+   * If the subscription is already closed, the teardown is executed immediately.
+   * @param teardown A function or another Unsubscribable object to be managed.
+   */
+  add(teardown) {
+    if (this._closed) {
+      isFunction(teardown) ? teardown() : teardown.unsubscribe();
+      return;
+    }
+    this._teardowns.push(isFunction(teardown) ? teardown : () => teardown.unsubscribe());
+  }
+  /**
+   * Disposes the resources held by the subscription.
+   * Executes all attached teardown logic and clears the list.
+   */
+  unsubscribe() {
+    if (this._closed) return;
+    this._closed = true;
+    this._teardowns.forEach((fn) => fn());
+    this._teardowns = [];
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A Subscription object to manage the unsubscription.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return new Subscription(() => this.unsubscribe(listener));
+  }
+  /**
+   * Subscribes a listener that triggers only once and then automatically unsubscribes.
+   * @param listener The callback function to execute once.
+   * @returns A Subscription object (can be used to cancel before the event fires).
+   */
+  once(listener) {
+    const wrapper = (...args) => {
+      this.unsubscribe(wrapper);
+      listener(...args);
+    };
+    return this.subscribe(wrapper);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/state-emitter.ts
+var StateEmitter = class extends Emitter {
+  _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
+  constructor(initialValue) {
+    super();
+    this._lastValue = initialValue ?? void 0;
+  }
+  /**
+   * Gets the current value synchronously without subscribing.
+   */
+  get value() {
+    return this._lastValue;
+  }
+  /**
+   * Updates the state and notifies all listeners.
+   * @param args The new value(s).
+   */
+  emit(...args) {
+    this._lastValue = args;
+    super.emit(...args);
+  }
+  /**
+   * Subscribes to the event. If a value exists, the listener is called immediately.
+   * @param listener The callback function.
+   * @returns A Subscription object.
+   */
+  subscribe(listener) {
+    const unsubscribe = super.subscribe(listener);
+    if (this._lastValue !== void 0) {
+      listener(...this._lastValue);
+    }
+    return unsubscribe;
+  }
+  clear() {
+    super.clear();
+    this._lastValue = void 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Emitter,
+  StateEmitter,
+  Subscription
+});

package/dist/index.mjs

@@ -0,0 +1,143 @@
+// ../ensure/dist/index.mjs
+function isFunction(value) {
+  return typeof value === "function";
+}
+
+// src/subscription.ts
+var Subscription = class {
+  _closed = false;
+  _teardowns = [];
+  /**
+   * Indicates whether this subscription has already been unsubscribed.
+   */
+  get closed() {
+    return this._closed;
+  }
+  /**
+   * @param teardown Optional initial teardown logic to execute when unsubscribed.
+   */
+  constructor(teardown) {
+    if (teardown) {
+      this._teardowns.push(teardown);
+    }
+  }
+  /**
+   * Adds a teardown logic to this subscription.
+   * If the subscription is already closed, the teardown is executed immediately.
+   * @param teardown A function or another Unsubscribable object to be managed.
+   */
+  add(teardown) {
+    if (this._closed) {
+      isFunction(teardown) ? teardown() : teardown.unsubscribe();
+      return;
+    }
+    this._teardowns.push(isFunction(teardown) ? teardown : () => teardown.unsubscribe());
+  }
+  /**
+   * Disposes the resources held by the subscription.
+   * Executes all attached teardown logic and clears the list.
+   */
+  unsubscribe() {
+    if (this._closed) return;
+    this._closed = true;
+    this._teardowns.forEach((fn) => fn());
+    this._teardowns = [];
+  }
+};
+
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A Subscription object to manage the unsubscription.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return new Subscription(() => this.unsubscribe(listener));
+  }
+  /**
+   * Subscribes a listener that triggers only once and then automatically unsubscribes.
+   * @param listener The callback function to execute once.
+   * @returns A Subscription object (can be used to cancel before the event fires).
+   */
+  once(listener) {
+    const wrapper = (...args) => {
+      this.unsubscribe(wrapper);
+      listener(...args);
+    };
+    return this.subscribe(wrapper);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/state-emitter.ts
+var StateEmitter = class extends Emitter {
+  _lastValue;
+  /**
+   * @param initialValue Optional initial value to set.
+   */
+  constructor(initialValue) {
+    super();
+    this._lastValue = initialValue ?? void 0;
+  }
+  /**
+   * Gets the current value synchronously without subscribing.
+   */
+  get value() {
+    return this._lastValue;
+  }
+  /**
+   * Updates the state and notifies all listeners.
+   * @param args The new value(s).
+   */
+  emit(...args) {
+    this._lastValue = args;
+    super.emit(...args);
+  }
+  /**
+   * Subscribes to the event. If a value exists, the listener is called immediately.
+   * @param listener The callback function.
+   * @returns A Subscription object.
+   */
+  subscribe(listener) {
+    const unsubscribe = super.subscribe(listener);
+    if (this._lastValue !== void 0) {
+      listener(...this._lastValue);
+    }
+    return unsubscribe;
+  }
+  clear() {
+    super.clear();
+    this._lastValue = void 0;
+  }
+};
+export {
+  Emitter,
+  StateEmitter,
+  Subscription
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@axijs/emitter",
+  "version": "1.0.0",
+  "description": "A minimalistic, type-safe library for single-event and state emitting",
+  "license": "MIT",
+  "homepage": "https://github.com/axijs/tools/tree/main/packages/emitter",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axijs/tools.git",
+    "directory": "packages/emitter"
+  },
+  "keywords": [
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "prebuild": "npm test",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ]
+}