utilful 1.1.0 → 1.2.0

package/README.md

@@ -113,49 +113,36 @@ const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { na
 
 ### Emitter
 
-Simple and tiny event emitter library for JavaScript.
+Tiny functional event emitter / pubsub, based on [mitt](https://github.com/developit/mitt).
 
-`createEmitter` accepts interface with event name to listener argument types mapping:
+**Example:**
 
 ```ts
 import { createEmitter } from 'utilful'
 
-interface Events {
-  set: (name: string, count: number) => void
-  tick: () => void
+// eslint-disable-next-line ts/consistent-type-definitions
+type Events = {
+  foo: { a: string }
 }
 
 const emitter = createEmitter<Events>()
 
-// Correct calls:
-emitter.emit('set', 'prop', 1)
-emitter.emit('tick')
-
-// Compilation errors:
-emitter.emit('set', 'prop', '1')
-emitter.emit('tick', 2)
-```
+// Listen to an event
+emitter.on('foo', e => console.log('foo', e))
 
-The `on` method returns an `unbind` function. Call it and this listener will be removed from event:
+// Listen to all events
+emitter.on('*', (type, e) => console.log(type, e))
 
-```ts
-const unbind = emitter.on('tick', (number) => {
-  console.log(`on ${number}`)
-})
+// Fire an event
+emitter.emit('foo', { a: 'b' })
 
-emitter.emit('tick', 1)
-// Prints "on 1"
+// Clearing all events
+emitter.all.clear()
 
-unbind()
-emitter.emit('tick', 2)
-// Prints nothing
-```
-
-You can get the used events list by accessing the `events` property:
-
-```ts
-const unbind = emitter.on('tick', () => { })
-emitter.events // => { tick: [ [Function] ] }
+// Working with handler references:
+function onFoo() {}
+emitter.on('foo', onFoo) // Listen
+emitter.off('foo', onFoo) // Unlisten
 ```
 
 ### JSON

package/dist/csv.d.mts

@@ -30,12 +30,14 @@ declare function createCSV<T extends Record<string, unknown>>(data: T[], columns
  *
  * @remarks
  * Returns an empty string if the value is `null` or `undefined`.
+ * Values containing delimiters, quotes, or line breaks are quoted.
+ * Within quoted values, double quotes are escaped by doubling them.
  *
  * @example
  * escapeCSVValue('hello, world'); // "hello, world"
  * escapeCSVValue('contains "quotes"'); // "contains ""quotes"""
  */
-declare function escapeCSVValue(value: unknown, { delimiter, quoteAll, }?: {
+declare function escapeCSVValue(value: unknown, options?: {
     /** @default ',' */
     delimiter?: string;
     /** @default false */

package/dist/csv.d.ts

@@ -30,12 +30,14 @@ declare function createCSV<T extends Record<string, unknown>>(data: T[], columns
  *
  * @remarks
  * Returns an empty string if the value is `null` or `undefined`.
+ * Values containing delimiters, quotes, or line breaks are quoted.
+ * Within quoted values, double quotes are escaped by doubling them.
  *
  * @example
  * escapeCSVValue('hello, world'); // "hello, world"
  * escapeCSVValue('contains "quotes"'); // "contains ""quotes"""
  */
-declare function escapeCSVValue(value: unknown, { delimiter, quoteAll, }?: {
+declare function escapeCSVValue(value: unknown, options?: {
     /** @default ',' */
     delimiter?: string;
     /** @default false */

package/dist/csv.mjs

@@ -13,14 +13,15 @@ function createCSV(data, columns, options = {}) {
   }
   return rows.join("\n");
 }
-function escapeCSVValue(value, {
-  delimiter = ",",
-  quoteAll = false
-} = {}) {
+function escapeCSVValue(value, options = {}) {
+  const {
+    delimiter = ",",
+    quoteAll = false
+  } = options;
   if (value == null) {
     return "";
   }
-  const stringValue = value.toString();
+  const stringValue = String(value);
   const needsQuoting = quoteAll || stringValue.includes(delimiter) || stringValue.includes('"') || stringValue.includes("\n") || stringValue.includes("\r");
   if (needsQuoting) {
     return `"${stringValue.replaceAll('"', '""')}"`;

package/dist/emitter.d.mts

@@ -1,72 +1,24 @@
-interface EventsMap {
-    [event: string]: any;
-}
-interface DefaultEvents extends EventsMap {
-    [event: string]: (...args: any) => void;
-}
-interface Unsubscribe {
-    (): void;
-}
-interface Emitter<Events extends EventsMap = DefaultEvents> {
-    /**
-     * Calls each of the listeners registered for a given event.
-     *
-     * @example
-     * emitter.emit('tick', tickType, tickDuration)
-     *
-     * @param event The event name.
-     * @param args The arguments for listeners.
-     */
-    emit: <K extends keyof Events>(this: this, event: K, ...args: Parameters<Events[K]>) => void;
-    /**
-     * Event names in keys and arrays with listeners in values.
-     *
-     * @example
-     * emitter1.events = emitter2.events
-     * emitter2.events = { }
-     */
-    events: Partial<{
-        [E in keyof Events]: Events[E][];
-    }>;
-    /**
-     * Add a listener for a given event.
-     *
-     * @example
-     * const unbind = emitter.on('tick', (tickType, tickDuration) => {
-     *   count += 1
-     * })
-     *
-     * disable () {
-     *   unbind()
-     * }
-     *
-     * @param event The event name.
-     * @param cb The listener function.
-     * @returns Unbind listener from event.
-     */
-    on: <K extends keyof Events>(this: this, event: K, cb: Events[K]) => Unsubscribe;
+type EventType = string | symbol;
+type Handler<T = unknown> = (event: T) => void;
+type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
+type EventHandlerList<T = unknown> = Handler<T>[];
+type WildCardEventHandlerList<T = Record<string, unknown>> = WildcardHandler<T>[];
+type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | '*', EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
+interface Emitter<Events extends Record<EventType, unknown>> {
+    all: EventHandlerMap<Events>;
+    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
+    on(type: '*', handler: WildcardHandler<Events>): void;
+    off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
+    off(type: '*', handler: WildcardHandler<Events>): void;
+    emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
+    emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
 }
 /**
- * Create event emitter.
- *
- * @example
- * import { createEmitter } from 'nanoevents'
- *
- * class Ticker {
- *   constructor() {
- *     this.emitter = createEmitter()
- *   }
- *   on(...args) {
- *     return this.emitter.on(...args)
- *   }
- *   tick() {
- *     this.emitter.emit('tick')
- *   }
- * }
+ * Simple functional event emitter / pubsub.
  *
- * @remarks Ported from `nanoevents`.
- * @see https://github.com/ai/nanoevents
+ * @remarks Ported from `mitt`.
+ * @see https://github.com/developit/mitt
  */
-declare function createEmitter<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
+declare function createEmitter<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): Emitter<Events>;
 
-export { type Emitter, createEmitter };
+export { type Emitter, type EventHandlerList, type EventHandlerMap, type EventType, type Handler, type WildCardEventHandlerList, type WildcardHandler, createEmitter };

package/dist/emitter.d.ts

@@ -1,72 +1,24 @@
-interface EventsMap {
-    [event: string]: any;
-}
-interface DefaultEvents extends EventsMap {
-    [event: string]: (...args: any) => void;
-}
-interface Unsubscribe {
-    (): void;
-}
-interface Emitter<Events extends EventsMap = DefaultEvents> {
-    /**
-     * Calls each of the listeners registered for a given event.
-     *
-     * @example
-     * emitter.emit('tick', tickType, tickDuration)
-     *
-     * @param event The event name.
-     * @param args The arguments for listeners.
-     */
-    emit: <K extends keyof Events>(this: this, event: K, ...args: Parameters<Events[K]>) => void;
-    /**
-     * Event names in keys and arrays with listeners in values.
-     *
-     * @example
-     * emitter1.events = emitter2.events
-     * emitter2.events = { }
-     */
-    events: Partial<{
-        [E in keyof Events]: Events[E][];
-    }>;
-    /**
-     * Add a listener for a given event.
-     *
-     * @example
-     * const unbind = emitter.on('tick', (tickType, tickDuration) => {
-     *   count += 1
-     * })
-     *
-     * disable () {
-     *   unbind()
-     * }
-     *
-     * @param event The event name.
-     * @param cb The listener function.
-     * @returns Unbind listener from event.
-     */
-    on: <K extends keyof Events>(this: this, event: K, cb: Events[K]) => Unsubscribe;
+type EventType = string | symbol;
+type Handler<T = unknown> = (event: T) => void;
+type WildcardHandler<T = Record<string, unknown>> = (type: keyof T, event: T[keyof T]) => void;
+type EventHandlerList<T = unknown> = Handler<T>[];
+type WildCardEventHandlerList<T = Record<string, unknown>> = WildcardHandler<T>[];
+type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<keyof Events | '*', EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>>;
+interface Emitter<Events extends Record<EventType, unknown>> {
+    all: EventHandlerMap<Events>;
+    on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
+    on(type: '*', handler: WildcardHandler<Events>): void;
+    off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
+    off(type: '*', handler: WildcardHandler<Events>): void;
+    emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
+    emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
 }
 /**
- * Create event emitter.
- *
- * @example
- * import { createEmitter } from 'nanoevents'
- *
- * class Ticker {
- *   constructor() {
- *     this.emitter = createEmitter()
- *   }
- *   on(...args) {
- *     return this.emitter.on(...args)
- *   }
- *   tick() {
- *     this.emitter.emit('tick')
- *   }
- * }
+ * Simple functional event emitter / pubsub.
  *
- * @remarks Ported from `nanoevents`.
- * @see https://github.com/ai/nanoevents
+ * @remarks Ported from `mitt`.
+ * @see https://github.com/developit/mitt
  */
-declare function createEmitter<Events extends EventsMap = DefaultEvents>(): Emitter<Events>;
+declare function createEmitter<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): Emitter<Events>;
 
-export { type Emitter, createEmitter };
+export { type Emitter, type EventHandlerList, type EventHandlerMap, type EventType, type Handler, type WildCardEventHandlerList, type WildcardHandler, createEmitter };

package/dist/emitter.mjs

@@ -1,16 +1,62 @@
-function createEmitter() {
+function createEmitter(all) {
+  all ||= /* @__PURE__ */ new Map();
   return {
-    emit(event, ...args) {
-      for (let callbacks = this.events[event] || [], i = 0, length = callbacks.length; i < length; i++) {
-        callbacks[i](...args);
+    /**
+     * A Map of event names to registered handler functions.
+     */
+    all,
+    /**
+     * Register an event handler for the given type.
+     * @param {string|symbol} type Type of event to listen for, or `'*'` for all events
+     * @param {Function} handler Function to call in response to given event
+     * @memberOf createEmitter
+     */
+    on(type, handler) {
+      const handlers = all.get(type);
+      if (handlers) {
+        handlers.push(handler);
+      } else {
+        all.set(type, [handler]);
       }
     },
-    events: {},
-    on(event, cb) {
-      (this.events[event] ||= []).push(cb);
-      return () => {
-        this.events[event] = this.events[event]?.filter((i) => cb !== i);
-      };
+    /**
+     * Remove an event handler for the given type.
+     * If `handler` is omitted, all handlers of the given type are removed.
+     *
+     * @param {string|symbol} type Type of event to unregister `handler` from (`'*'` to remove a wildcard handler)
+     * @param {Function} [handler] Handler function to remove
+     * @memberOf createEmitter
+     */
+    off(type, handler) {
+      const handlers = all.get(type);
+      if (handlers) {
+        if (handler) {
+          handlers.splice(handlers.indexOf(handler) >>> 0, 1);
+        } else {
+          all.set(type, []);
+        }
+      }
+    },
+    /**
+     * Invoke all handlers for the given type.
+     * If present, `'*'` handlers are invoked after type-matched handlers.
+     *
+     * @remarks
+     * Manually firing '*' handlers is not supported.
+     *
+     * @param {string|symbol} type The event type to invoke
+     * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler
+     * @memberOf createEmitter
+     */
+    emit(type, evt) {
+      let handlers = all.get(type);
+      handlers?.slice().forEach((handler) => {
+        handler(evt);
+      });
+      handlers = all.get("*");
+      handlers?.slice().forEach((handler) => {
+        handler(type, evt);
+      });
     }
   };
 }

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 export { MaybeArray, toArray } from './array.mjs';
 export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
-export { Emitter, createEmitter } from './emitter.mjs';
+export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from './emitter.mjs';
 export { cloneJSON, tryParseJSON } from './json.mjs';
 export { lazy } from './lazy.mjs';
 export { interopDefault } from './module.mjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { MaybeArray, toArray } from './array.js';
 export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.js';
-export { Emitter, createEmitter } from './emitter.js';
+export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from './emitter.js';
 export { cloneJSON, tryParseJSON } from './json.js';
 export { lazy } from './lazy.js';
 export { interopDefault } from './module.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageManager": "pnpm@10.5.2",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",