easy-signal 1.0.2 → 2.0.1

package/README.md

@@ -1,6 +1,10 @@
 # Easy Signal
 
-A simple interface for creating a defined event or action that can be triggered with a set API and listened to by any number of subscribers.
+A simple interface for creating a defined event or action that can be triggered and listened to by any number of
+subscribers. Producing a single function that can be used to subscribe to the events, subscribe to errors, and dispatch
+events and errors.
+
+Full type safety with TypeScript providing good autocomplete.
 
 ## Installation
 
@@ -10,9 +14,13 @@ npm install easy-signal
 
 ## Usage
 
-A signal is a subscriber function that represents a single event. A signal function (the subscriber) has a function attached to it called `dispatch()` to trigger the event.
+A signal is a function that represents a single event. The function can be used to subscribe to be notified of the
+events as well as to trigger them.
 
-Signals offer similar functionality as the browser's `eventDispatcher` API, but rather than a general API for any event, each event would use its own signal. This allows each signal to have a specific function signature as opposed to the browser's generic `event` object. This is a great system in TypeScript being able to see the exact data each event produces.
+Signals offer similar functionality as the browser's `eventDispatcher` API, but rather than a general API for any event,
+each event would use its own signal. This allows each signal to have a specific function signature as opposed to the
+browser's generic `event` object. This is a great system in TypeScript being able to see the exact data each event
+produces.
 
 ### Basic Usage
 
@@ -21,9 +29,13 @@ 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(() => {
+  const currentSecond = Math.floor(Date.now() / 1000);
+  onSecond(currentSecond);
+});
 ```
 
 ```ts
@@ -35,15 +47,47 @@ const unsubscribe = onSecond(seconds => {
 });
 ```
 
-The TypeScript definition has been extended to allow an `error` signal to be added to an existing signal for situations
-where a signal may need to handle errors.
+Errors may also be listened to from the signal by passing `ForErrors` as the second parameter when adding the listener
+and errors may be dispatched by passing an Error object to the signal method.
 
 ```ts
-import { signal } from 'easy-signal';
+import { signal, ForErrors } from 'easy-signal';
 
 const dataStream = signal();
-dataStream.error = signal();
 
-stream.on('data', obj => dataStream.dispatch(obj))
-stream.on('error', err => dataStream.error.dispatch(err))
+dataStream(data => console.log('data is:' data));
+dataStream(error => console.log('Error is:' error), ForErrors);
+
+stream.on('data', obj => dataStream(obj));
+stream.on('error', err => dataStream(err));
+```
+
+To get a subscriber-only method for external use, pass in the `GetOnSignal` constant.
+
+```ts
+import { signal, GetOnSignal } from 'easy-signal';
+
+
+function getMyAPI() {
+  const doSomething = signal();
+
+  // doSomething() will trigger subscribers that were added in onSomething(...). This protects the signal from being
+  // triggered/dispatched outside of `getMyAPI`. Sometimes you may want more control to prevent just anyone from
+  // triggering the event.
+
+  return {
+    onSomething: doSomething(GetOnSignal),
+  };
+}
+```
+
+
+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,10 +1,36 @@
 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;
-    error?: Signal<(err: Error) => any>;
+export declare type ErrorSubscriber = (error: Error) => any;
+export declare type Unsubscriber = () => void;
+export declare type OnSignal<T extends Subscriber = Subscriber> = {
+    (subscriber: T): Unsubscriber;
+    (errorListener: ErrorSubscriber, what: typeof ForErrors): Unsubscriber;
 };
+export declare type Signal<T extends Subscriber = Subscriber> = OnSignal<T> & {
+    (...args: Args<T>): void;
+    (data: Error): void;
+    (data: typeof ClearSignal): void;
+    (data: typeof GetOnSignal): OnSignal<T>;
+};
+export declare const ClearSignal: unique symbol;
+export declare const GetOnSignal: unique symbol;
+export declare const ForErrors: unique symbol;
+/**
+ * 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 extends Subscriber = Subscriber>(): Signal<T>;
 export {};

package/index.js

@@ -1,10 +1,51 @@
+export const ClearSignal = Symbol();
+export const GetOnSignal = Symbol();
+export const ForErrors = Symbol();
+/**
+ * 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 onSignal(subscriber, what) {
+        const listeners = what === ForErrors ? errorListeners : subscribers;
+        listeners.add(subscriber);
+        return () => {
+            listeners.delete(subscriber);
+        };
     }
-    subscribe.dispatch = (...args) => listeners.forEach(listener => listener(...args));
-    subscribe.clear = listeners.clear.bind(listeners);
-    return subscribe;
+    function signal(...args) {
+        const arg = args[0];
+        if (typeof arg === 'function') {
+            return onSignal(arg);
+        }
+        else if (arg === ClearSignal) {
+            subscribers.clear();
+            errorListeners.clear();
+        }
+        else if (arg === GetOnSignal) {
+            return onSignal;
+        }
+        else if (arg instanceof Error) {
+            errorListeners.forEach(listener => listener(arg));
+        }
+        else {
+            subscribers.forEach(listener => listener(...args));
+        }
+    }
+    return signal;
 }

package/index.ts

@@ -1,23 +1,75 @@
 type Args<T> = T extends (...args: infer A) => any ? A : never;
 export type Subscriber = (...args: any[]) => any;
-export type Unsubscriber = () => boolean;
+export type ErrorSubscriber = (error: Error) => any;
+export type Unsubscriber = () => void;
 
-export type Signal<T extends Subscriber = Subscriber> = {
-  (listener: T): Unsubscriber;
-  dispatch: (...args: Args<T>) => void;
-  error?: Signal<(err: Error) => any>;
+export type OnSignal<T extends Subscriber = Subscriber> = {
+  (subscriber: T): Unsubscriber;
+  (errorListener: ErrorSubscriber, what: typeof ForErrors): Unsubscriber;
 }
 
+export type Signal<T extends Subscriber = Subscriber> = OnSignal<T> & {
+  (...args: Args<T>): void;
+  (data: Error): void;
+  (data: typeof ClearSignal): void;
+  (data: typeof GetOnSignal): OnSignal<T>;
+}
+
+export const ClearSignal = Symbol();
+export const GetOnSignal = Symbol();
+export const ForErrors = Symbol();
+
+
+/**
+ * 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 extends Subscriber = Subscriber>(): Signal<T> {
-  const listeners = new Set<T>();
+  const subscribers = new Set<Subscriber>();
+  const errorListeners = new Set<Subscriber>();
 
-  function subscribe(listener: T) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
+  function onSignal(subscriber: T | ErrorSubscriber, what?: typeof ForErrors): Unsubscriber {
+    const listeners = what === ForErrors ? errorListeners : subscribers;
+      listeners.add(subscriber);
+      return () => {
+        listeners.delete(subscriber);
+      };
   }
 
-  subscribe.dispatch = (...args: Args<T>) => listeners.forEach(listener => listener(...args));
-  subscribe.clear = listeners.clear.bind(listeners);
+  function signal(...args: Args<T>): void;
+  function signal(error: Error): void;
+  function signal(data: typeof ClearSignal): void;
+  function signal(data: typeof GetOnSignal): OnSignal<T>;
+  function signal(subscriber: T): Unsubscriber;
+  function signal(errorListener: Subscriber, what: typeof ForErrors): Unsubscriber;
+  function signal(...args: any[]): Unsubscriber | OnSignal<T> | void {
+    const arg = args[0];
+    if (typeof arg === 'function') {
+      return onSignal(arg);
+    } else if (arg === ClearSignal) {
+      subscribers.clear();
+      errorListeners.clear();
+    } else if (arg === GetOnSignal) {
+      return onSignal as OnSignal<T>;
+    } else if (arg instanceof Error) {
+      errorListeners.forEach(listener => listener(arg));
+    } else {
+      subscribers.forEach(listener => listener(...args));
+    }
+  }
 
-  return subscribe;
+  return signal;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "easy-signal",
-  "version": "1.0.2",
-  "description": "A tiny (10 LOC), simple utility for alerting subscribers when an event happens.",
+  "version": "2.0.1",
+  "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",