easy-signal 1.0.1 → 2.0.0

package/README.md

@@ -21,9 +21,10 @@ Signals offer similar functionality as the browser's `eventDispatcher` API, but
 import { signal } from 'easy-signal';
 
 // Create the signal and export it for use. Optionally provide the subscriber signature
-export const onSecond = signal<(second: number) => any>();
+export const onSecond = signal<number>();
 
-setInterval(() => onSecond.dispatch(Math.floor(Date.now() / 1000)));
+// Passing a non-function value will dispatch the event
+setInterval(() => onSecond(Math.floor(Date.now() / 1000)));
 ```
 
 ```ts
@@ -34,3 +35,28 @@ const unsubscribe = onSecond(seconds => {
   console.log(seconds, 'since epoc');
 });
 ```
+
+Errors may also be listened to and dispatched from the signal by using the second parameter when adding the listener
+and by passing an Error object to the dispatch.
+
+```ts
+import { signal } from 'easy-signal';
+
+const dataStream = signal();
+
+dataStream(data => console.log('data is:' data));
+dataStream(error => console.log('Error is:' error), { captureErrors: true });
+
+stream.on('data', obj => dataStream(obj));
+stream.on('error', err => dataStream(err));
+```
+
+To clear the listeners from the signal, pass in the `ClearSignal` constant.
+
+```ts
+import { signal, ClearSignal } from 'easy-signal';
+
+const onSomething = signal();
+
+onSomething(ClearSignal); // clears signal
+```

package/index.d.ts

@@ -1,9 +1,29 @@
-declare type Args<T> = T extends (...args: infer A) => any ? A : never;
-export declare type Subscriber = (...args: any[]) => any;
-export declare type Unsubscriber = () => boolean;
-export declare type Signal<T extends Subscriber = Subscriber> = {
-    (listener: T): Unsubscriber;
-    dispatch: (...args: Args<T>) => void;
+export declare type Subscriber<T> = (data: T) => any;
+export declare type Unsubscriber = () => void;
+export declare type Signal<T> = {
+    (data: T): void;
+    (data: Error): void;
+    (subscriber: Subscriber<T>): Unsubscriber;
+    (errorListener: Subscriber<Error>, options: {
+        captureErrors: true;
+    }): Unsubscriber;
 };
-export declare function signal<T extends Subscriber = Subscriber>(): Signal<T>;
-export {};
+export declare const ClearSignal: {};
+/**
+ * Creates a signal, a function that can be used to subscribe to events. The signal can be called with a subscriber
+ * function, which will be called when the signal is dispatched. The signal can also be called with data, which will
+ * dispatch to all subscribers. An optional second argument can be passed to subscribe to errors instead. When the
+ * signal is called with an instance of Error, it will dispatch to all error listeners.
+ * The signal can also be called with `ClearSignal`, which will clear all subscribers.
+ * @example
+ * const onLoad = signal();
+ *
+ * // Subscribe to data
+ * onLoad((data) => console.log('loaded', data));
+ * onLoad((error) => console.error('error', error), true);
+ *
+ * // Dispatch data
+ * onLoad('data'); // logs 'loaded data'
+ * onLoad(new Error('error')); // logs 'error Error: error'
+ */
+export declare function signal<T = any>(): Signal<T>;

package/index.js

@@ -1,10 +1,42 @@
+export const ClearSignal = {};
+/**
+ * Creates a signal, a function that can be used to subscribe to events. The signal can be called with a subscriber
+ * function, which will be called when the signal is dispatched. The signal can also be called with data, which will
+ * dispatch to all subscribers. An optional second argument can be passed to subscribe to errors instead. When the
+ * signal is called with an instance of Error, it will dispatch to all error listeners.
+ * The signal can also be called with `ClearSignal`, which will clear all subscribers.
+ * @example
+ * const onLoad = signal();
+ *
+ * // Subscribe to data
+ * onLoad((data) => console.log('loaded', data));
+ * onLoad((error) => console.error('error', error), true);
+ *
+ * // Dispatch data
+ * onLoad('data'); // logs 'loaded data'
+ * onLoad(new Error('error')); // logs 'error Error: error'
+ */
 export function signal() {
-    const listeners = new Set();
-    function subscribe(listener) {
-        listeners.add(listener);
-        return () => listeners.delete(listener);
+    const subscribers = new Set();
+    const errorListeners = new Set();
+    function subscribe(arg, options) {
+        if (typeof arg === 'function') {
+            const listeners = options?.captureErrors ? errorListeners : subscribers;
+            listeners.add(arg);
+            return () => {
+                listeners.delete(arg);
+            };
+        }
+        else if (arg === ClearSignal) {
+            subscribers.clear();
+            errorListeners.clear();
+        }
+        else if (arg instanceof Error) {
+            errorListeners.forEach(listener => listener(arg));
+        }
+        else {
+            subscribers.forEach(listener => listener(arg));
+        }
     }
-    subscribe.dispatch = (...args) => listeners.forEach(listener => listener(...args));
-    subscribe.clear = listeners.clear.bind(listeners);
     return subscribe;
 }

package/index.ts

@@ -1,22 +1,56 @@
-type Args<T> = T extends (...args: infer A) => any ? A : never;
-export type Subscriber = (...args: any[]) => any;
-export type Unsubscriber = () => boolean;
+export type Subscriber<T> = (data: T) => any;
+export type Unsubscriber = () => void;
 
-export type Signal<T extends Subscriber = Subscriber> = {
-  (listener: T): Unsubscriber;
-  dispatch: (...args: Args<T>) => void;
+export type Signal<T> = {
+  (data: T): void;
+  (data: Error): void;
+  (subscriber: Subscriber<T>): Unsubscriber;
+  (errorListener: Subscriber<Error>, options: { captureErrors: true }): Unsubscriber;
 }
 
-export function signal<T extends Subscriber = Subscriber>(): Signal<T> {
-  const listeners = new Set<T>();
+export const ClearSignal = {};
 
-  function subscribe(listener: T) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  }
+/**
+ * Creates a signal, a function that can be used to subscribe to events. The signal can be called with a subscriber
+ * function, which will be called when the signal is dispatched. The signal can also be called with data, which will
+ * dispatch to all subscribers. An optional second argument can be passed to subscribe to errors instead. When the
+ * signal is called with an instance of Error, it will dispatch to all error listeners.
+ * The signal can also be called with `ClearSignal`, which will clear all subscribers.
+ * @example
+ * const onLoad = signal();
+ *
+ * // Subscribe to data
+ * onLoad((data) => console.log('loaded', data));
+ * onLoad((error) => console.error('error', error), true);
+ *
+ * // Dispatch data
+ * onLoad('data'); // logs 'loaded data'
+ * onLoad(new Error('error')); // logs 'error Error: error'
+ */
+export function signal<T = any>(): Signal<T> {
+  const subscribers = new Set<Subscriber<T>>();
+  const errorListeners = new Set<Subscriber<Error>>();
 
-  subscribe.dispatch = (...args: Args<T>) => listeners.forEach(listener => listener(...args));
-  subscribe.clear = listeners.clear.bind(listeners);
+  function subscribe(data: T): void;
+  function subscribe(error: Error): void;
+  function subscribe(subscriber: Subscriber<T>): Unsubscriber;
+  function subscribe(listener: Subscriber<Error>, options: { captureErrors: true }): Unsubscriber;
+  function subscribe(arg: T | Error | Subscriber<T> | Subscriber<Error>, options?: { captureErrors: true }): Unsubscriber {
+    if (typeof arg === 'function') {
+      const listeners = options?.captureErrors ? errorListeners : subscribers;
+      listeners.add(arg as any);
+      return () => {
+        listeners.delete(arg as any);
+      };
+    } else if (arg === ClearSignal) {
+      subscribers.clear();
+      errorListeners.clear();
+    } else if (arg instanceof Error) {
+      errorListeners.forEach(listener => listener(arg));
+    } else {
+      subscribers.forEach(listener => listener(arg));
+    }
+  }
 
   return subscribe;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "easy-signal",
-  "version": "1.0.1",
-  "description": "A tiny (10 LOC), simple utility for alerting subscribers when an event happens.",
+  "version": "2.0.0",
+  "description": "A tiny (25 LOC), simple utility for alerting subscribers when an event happens, allowing for error handling and clearing.",
   "main": "index.js",
   "scripts": {
     "build": "tsc",