@axijs/emitter 1.0.1 → 1.1.0

package/README.md

@@ -19,9 +19,10 @@ yarn add @axijs/emitter
 
 ## Features
 
-- **Strictly Typed**: Full TypeScript support for event arguments.
+- **Strictly Typed**: Full TypeScript support for emitted values.
 - **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.
+- **Distinct Updates**: `StateEmitter` can optionally skip emitting unchanged values.
 - **Composite Subscriptions**: Easily group multiple subscriptions and teardown logic into a single `Subscription` object to prevent memory leaks.
 
 ## Usage
@@ -32,23 +33,18 @@ 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]>();
+const onPlayerMove = new Emitter<string>();
 
-// Subscribe to the event
-const sub = onPlayerMove.subscribe((player, x) => {
-  console.log(`${player} moved to ${x}`);
+const sub = onPlayerMove.subscribe((player) => {
+  console.log(`Player moved: ${player}`);
 });
 
-// Fire the event
-onPlayerMove.emit('Alice', 10); 
+onPlayerMove.emit('Alice');
 
-// Subscribe to fire only once
-onPlayerMove.once((player, x) => {
+onPlayerMove.once((player) => {
   console.log('This will only run once!');
 });
 
-// Unsubscribe when no longer needed
 sub.unsubscribe();
 ```
 
@@ -59,19 +55,61 @@ 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]);
+const health = new StateEmitter<number>(100);
 
-// New subscribers immediately receive the current state (100)
 health.subscribe((currentHealth) => {
-  console.log(`Health is: ${currentHealth}`);
+  console.log(`Health is: ${currentHealth}`); // Immediately logs: "Health is: 100"
 });
 
-// Emit a new state. All listeners will be notified.
-health.emit(80);
+health.emit(80); // Logs: "Health is: 80"
 
-// Get current state synchronously without subscribing
-console.log(health.value); // [80]
+console.log(health.value); // 80
+```
+
+#### Distinct Values & Custom Comparison
+You can prevent the emitter from firing consecutively with the same value by using the `StateEmitterOptions`.
+
+```typescript
+export interface StateEmitterOptions<T> {
+  distinct?: boolean;
+  compare?: (prev: T, next: T) => boolean;
+}
+```
+
+When `distinct: true` is set, the emitter checks if the new value is the same as the previous one. 
+**By default, it uses simple reference equality (`Object.is`)**, which is fast and works perfectly for primitives.
+
+```typescript
+// Prevents emitting the same primitive value twice
+const status = new StateEmitter('idle', { distinct: true });
+status.emit('idle'); // Ignored
+```
+
+For complex objects, or if you want to apply custom comparison logic, you can provide a `compare` callback.
+This is useful when you only care about specific fields changing (like an `id`) or when using a deep equal function from a library.
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+}
+
+const activeUser = new StateEmitter<User>(
+  { id: 1, name: 'Alice' }, 
+  {
+    distinct: true,
+    // Custom logic: objects are considered the same if their IDs match
+    compare: (prev, next) => prev.id === next.id
+  }
+);
+
+activeUser.subscribe(user => console.log('User changed:', user.name));
+
+// Will NOT emit, because the 'id' is still 1
+activeUser.emit({ id: 1, name: 'Alice Updated' });
+
+// WILL emit, because the 'id' has changed
+activeUser.emit({ id: 2, name: 'Bob' });
 ```
 
 ### 3. Composite Subscriptions
@@ -80,8 +118,8 @@ Group multiple unsubscriptions together. Very useful for cleaning up UI componen
 ```typescript
 import { Emitter, Subscription } from '@axijs/emitter';
 
-const onJump = new Emitter<[]>();
-const onShoot = new Emitter<[]>();
+const onJump = new Emitter<void>();
+const onShoot = new Emitter<void>();
 
 const masterSub = new Subscription();
 

package/dist/index.d.mts

@@ -1,16 +1,17 @@
+type ListenerType<T> = (value: T) => void;
 /**
  * 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.
+ * @template T The type of the emitted value.
  */
-type Subscribable<T extends any[]> = {
+type Subscribable<T> = {
     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;
+    subscribe(listener: (value: T) => void): Unsubscribable;
+    unsubscribe(listener: (value: T) => void): boolean;
     clear(): void;
 };
 /**
@@ -51,9 +52,9 @@ declare class Subscription implements Unsubscribable {
 /**
  * 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.
+ * @template T The type of the emitted value.
  */
-declare class Emitter<T extends any[]> implements Subscribable<T> {
+declare class Emitter<T = void> implements Subscribable<T> {
     private listeners;
     /**
      * Returns the number of listeners.
@@ -63,54 +64,61 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      * Subscribes a listener to this event.
      * @returns A Subscription object to manage the unsubscription.
      */
-    subscribe(listener: (...args: T) => void): Subscription;
+    subscribe(listener: ListenerType<T>): 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;
+    once(listener: ListenerType<T>): Subscription;
     /**
-     * Manually unsubscribe by listener
-     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     * Manually unsubscribe by listener.
+     * @returns returns true if a listener has been removed, or false if it does not exist.
      */
-    unsubscribe(listener: (...args: T) => void): boolean;
+    unsubscribe(listener: ListenerType<T>): boolean;
     /**
      * Dispatches the event to all subscribed listeners.
      */
-    emit(...args: T): void;
+    emit(value: T): void;
     /**
      * Clears all listeners.
      */
     clear(): void;
 }
 
+interface StateEmitterOptions<T> {
+    distinct?: boolean;
+    compare?: (prev: T, next: T) => boolean;
+}
 /**
  * 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> {
+declare class StateEmitter<T> extends Emitter<T> {
     private _lastValue;
+    private readonly _distinct;
+    private readonly _compare;
     /**
      * @param initialValue Optional initial value to set.
+     * @param options Optional behavior flags.
      */
-    constructor(initialValue?: T);
+    constructor(initialValue?: T, options?: StateEmitterOptions<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).
+     * @param value The new value.
      */
-    emit(...args: T): void;
+    emit(value: 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;
+    subscribe(listener: (value: T) => void): Subscription;
     clear(): void;
 }
 
-export { Emitter, StateEmitter, type Subscribable, Subscription, type Unsubscribable };
+export { Emitter, type ListenerType, StateEmitter, type StateEmitterOptions, type Subscribable, Subscription, type Unsubscribable };

package/dist/index.d.ts

@@ -1,16 +1,17 @@
+type ListenerType<T> = (value: T) => void;
 /**
  * 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.
+ * @template T The type of the emitted value.
  */
-type Subscribable<T extends any[]> = {
+type Subscribable<T> = {
     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;
+    subscribe(listener: (value: T) => void): Unsubscribable;
+    unsubscribe(listener: (value: T) => void): boolean;
     clear(): void;
 };
 /**
@@ -51,9 +52,9 @@ declare class Subscription implements Unsubscribable {
 /**
  * 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.
+ * @template T The type of the emitted value.
  */
-declare class Emitter<T extends any[]> implements Subscribable<T> {
+declare class Emitter<T = void> implements Subscribable<T> {
     private listeners;
     /**
      * Returns the number of listeners.
@@ -63,54 +64,61 @@ declare class Emitter<T extends any[]> implements Subscribable<T> {
      * Subscribes a listener to this event.
      * @returns A Subscription object to manage the unsubscription.
      */
-    subscribe(listener: (...args: T) => void): Subscription;
+    subscribe(listener: ListenerType<T>): 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;
+    once(listener: ListenerType<T>): Subscription;
     /**
-     * Manually unsubscribe by listener
-     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     * Manually unsubscribe by listener.
+     * @returns returns true if a listener has been removed, or false if it does not exist.
      */
-    unsubscribe(listener: (...args: T) => void): boolean;
+    unsubscribe(listener: ListenerType<T>): boolean;
     /**
      * Dispatches the event to all subscribed listeners.
      */
-    emit(...args: T): void;
+    emit(value: T): void;
     /**
      * Clears all listeners.
      */
     clear(): void;
 }
 
+interface StateEmitterOptions<T> {
+    distinct?: boolean;
+    compare?: (prev: T, next: T) => boolean;
+}
 /**
  * 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> {
+declare class StateEmitter<T> extends Emitter<T> {
     private _lastValue;
+    private readonly _distinct;
+    private readonly _compare;
     /**
      * @param initialValue Optional initial value to set.
+     * @param options Optional behavior flags.
      */
-    constructor(initialValue?: T);
+    constructor(initialValue?: T, options?: StateEmitterOptions<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).
+     * @param value The new value.
      */
-    emit(...args: T): void;
+    emit(value: 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;
+    subscribe(listener: (value: T) => void): Subscription;
     clear(): void;
 }
 
-export { Emitter, StateEmitter, type Subscribable, Subscription, type Unsubscribable };
+export { Emitter, type ListenerType, StateEmitter, type StateEmitterOptions, type Subscribable, Subscription, type Unsubscribable };

package/dist/index.js

@@ -92,15 +92,15 @@ var Emitter = class {
    * @returns A Subscription object (can be used to cancel before the event fires).
    */
   once(listener) {
-    const wrapper = (...args) => {
+    const wrapper = (value) => {
       this.unsubscribe(wrapper);
-      listener(...args);
+      listener(value);
     };
     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.
+   * Manually unsubscribe by listener.
+   * @returns returns true if a listener has been removed, or false if it does not exist.
    */
   unsubscribe(listener) {
     return this.listeners.delete(listener);
@@ -108,8 +108,8 @@ var Emitter = class {
   /**
    * Dispatches the event to all subscribed listeners.
    */
-  emit(...args) {
-    this.listeners.forEach((listener) => listener(...args));
+  emit(value) {
+    this.listeners.forEach((listener) => listener(value));
   }
   /**
    * Clears all listeners.
@@ -122,12 +122,17 @@ var Emitter = class {
 // src/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
+  _distinct;
+  _compare;
   /**
    * @param initialValue Optional initial value to set.
+   * @param options Optional behavior flags.
    */
-  constructor(initialValue) {
+  constructor(initialValue, options = {}) {
     super();
     this._lastValue = initialValue ?? void 0;
+    this._distinct = options.distinct ?? false;
+    this._compare = options.compare ?? Object.is;
   }
   /**
    * Gets the current value synchronously without subscribing.
@@ -137,11 +142,14 @@ var StateEmitter = class extends Emitter {
   }
   /**
    * Updates the state and notifies all listeners.
-   * @param args The new value(s).
+   * @param value The new value.
    */
-  emit(...args) {
-    this._lastValue = args;
-    super.emit(...args);
+  emit(value) {
+    if (this._distinct && this._lastValue !== void 0 && this._compare(this._lastValue, value)) {
+      return;
+    }
+    this._lastValue = value;
+    super.emit(value);
   }
   /**
    * Subscribes to the event. If a value exists, the listener is called immediately.
@@ -151,7 +159,7 @@ var StateEmitter = class extends Emitter {
   subscribe(listener) {
     const unsubscribe = super.subscribe(listener);
     if (this._lastValue !== void 0) {
-      listener(...this._lastValue);
+      listener(this._lastValue);
     }
     return unsubscribe;
   }

package/dist/index.mjs

@@ -64,15 +64,15 @@ var Emitter = class {
    * @returns A Subscription object (can be used to cancel before the event fires).
    */
   once(listener) {
-    const wrapper = (...args) => {
+    const wrapper = (value) => {
       this.unsubscribe(wrapper);
-      listener(...args);
+      listener(value);
     };
     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.
+   * Manually unsubscribe by listener.
+   * @returns returns true if a listener has been removed, or false if it does not exist.
    */
   unsubscribe(listener) {
     return this.listeners.delete(listener);
@@ -80,8 +80,8 @@ var Emitter = class {
   /**
    * Dispatches the event to all subscribed listeners.
    */
-  emit(...args) {
-    this.listeners.forEach((listener) => listener(...args));
+  emit(value) {
+    this.listeners.forEach((listener) => listener(value));
   }
   /**
    * Clears all listeners.
@@ -94,12 +94,17 @@ var Emitter = class {
 // src/state-emitter.ts
 var StateEmitter = class extends Emitter {
   _lastValue;
+  _distinct;
+  _compare;
   /**
    * @param initialValue Optional initial value to set.
+   * @param options Optional behavior flags.
    */
-  constructor(initialValue) {
+  constructor(initialValue, options = {}) {
     super();
     this._lastValue = initialValue ?? void 0;
+    this._distinct = options.distinct ?? false;
+    this._compare = options.compare ?? Object.is;
   }
   /**
    * Gets the current value synchronously without subscribing.
@@ -109,11 +114,14 @@ var StateEmitter = class extends Emitter {
   }
   /**
    * Updates the state and notifies all listeners.
-   * @param args The new value(s).
+   * @param value The new value.
    */
-  emit(...args) {
-    this._lastValue = args;
-    super.emit(...args);
+  emit(value) {
+    if (this._distinct && this._lastValue !== void 0 && this._compare(this._lastValue, value)) {
+      return;
+    }
+    this._lastValue = value;
+    super.emit(value);
   }
   /**
    * Subscribes to the event. If a value exists, the listener is called immediately.
@@ -123,7 +131,7 @@ var StateEmitter = class extends Emitter {
   subscribe(listener) {
     const unsubscribe = super.subscribe(listener);
     if (this._lastValue !== void 0) {
-      listener(...this._lastValue);
+      listener(this._lastValue);
     }
     return unsubscribe;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axijs/emitter",
-  "version": "1.0.1",
+  "version": "1.1.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",