asljs-eventful 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alex Netkachov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# eventful
+
+> Part of [Alexantrite Software Library][#1] - a set of high-quality and
+performant JavaScript libraries for everyday use.
+
+Lightweight event helper adding on/off/emit to any object.
+
+## Installation
+
+```bash
+npm install asljs-eventful
+```
+
+## Usage
+
+### Basic Example
+
+```js
+import { eventful } from 'asljs-eventful';
+
+const obj = eventful({ name: 'Alice' });
+obj.on('greet', msg => console.log(`${msg}, ${obj.name}!`));
+obj.emit('greet', 'Hello'); // Logs: "Hello, Alice!"
+```
+
+### Advanced Options
+
+Trace event invocations to console:
+
+```js
+const obj =
+  eventful(
+    { },
+    { trace: (object, action, payload) =>
+        console.log(
+          `Action: ${action}`,
+          payload) });
+
+// Tracing actions include:
+// - 'new' on creation: payload { object }
+// - 'on' when subscribing: payload { event, listener }
+// - 'off' when unsubscribing: payload { event, listener }
+// - 'emit' for sync emit: payload { event, args, listeners }
+// - 'emitAsync' for async emit: payload { event, args, listeners }
+```
+
+Custom error handler for listener errors:
+
+```js
+const obj =
+  eventful(
+    { },
+    { error: (err, { object, event, listener }) =>
+        console.error(
+          `Error in listener for event "${event}"`,
+          err) });
+```
+
+Strict mode to propagate listener errors:
+
+```js
+const obj =
+  eventful(
+    { },
+    { strict: true });
+```
+
+Change the error handler or trace function globally:
+
+```js
+eventful.options.trace =
+  (object, action, payload) =>
+    console.log(
+      `Action: ${action}`,
+      payload);
+
+eventful.options.error =
+  (err, { object, event, listener }) =>
+    console.error(
+      `Error in listener for event "${event}"`,
+      err);
+```
+
+## API
+
+### eventful([target], [options])
+
+Wraps the `target` object with event capabilities. If no target is provided, a new empty object is created.
+
+- `target` (Object): The object to be enhanced with event capabilities.
+- `options` (Object): Configuration options.
+  - `error` (Function): Custom error handler for listener errors `(err, { object, event, listener })`.
+  - `trace` (Function): Custom trace hook `(object, action, payload)` for `new`, `on`, `off`, `emit`, `emitAsync`.
+  - `strict` (Boolean): If true, propagates listener errors; otherwise they are isolated. Defaults to false.
+
+### on(event, listener)
+
+Registers a listener for the specified event.
+
+- `event` (String): The event name.
+- `listener` (Function): The callback function to be invoked when the event is emitted.
+
+Returns a function to remove the listener.
+
+### once(event, listener)
+
+Registers a one-time listener for the specified event. The listener is removed after its first invocation.
+
+- `event` (String): The event name.
+- `listener` (Function): The callback function to be invoked when the event is emitted.
+
+Returns a function to remove the listener.
+
+### off(event, listener)
+
+Removes a listener for the specified event.
+
+- `event` (String): The event name.
+- `listener` (Function): The callback function to be removed.
+
+### emit(event, ...args)
+
+Emits the specified event, invoking all registered listeners with the provided arguments.
+
+- `event` (String): The event name.
+- `...args` (Any): Arguments to pass to the listeners.
+
+### emitAsync(event, ...args)
+
+Emits the specified event asynchronously, running listeners in parallel. In non-strict mode, all listeners run and rejections are isolated; in strict mode, the first rejection causes the returned promise to reject.
+
+- `event` (String): The event name.
+- `...args` (Any): Arguments to pass to the listeners.
+
+Returns a Promise that resolves when all listeners have been invoked.
+
+### has(event)
+
+Checks if there are any listeners registered for the specified event.
+
+- `event` (String): The event name.
+
+Returns `true` if there are listeners, otherwise `false`.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs

package/eventful.d.ts

@@ -0,0 +1,106 @@
+
+export type Listener<Args extends any[] = any[]> =
+  (...args: Args) => any;
+
+export type EventMap =
+  Record<string | symbol, any[]>;
+
+export interface Eventful<E extends EventMap =
+  Record<string | symbol, any[]>> {
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof E>(
+      event: K,
+      listener: Listener<E[K]>
+    ): () => boolean;
+
+    /** Subscribe once to an event. Returns an unsubscribe function (called automatically). */
+    once<K extends keyof E>(
+      event: K,
+      listener: Listener<E[K]>
+    ): () => boolean;
+
+    /** Unsubscribe a previously registered listener. */
+    off<K extends keyof E>(
+      event: K,
+      listener: Listener<E[K]>
+    ): boolean;
+
+    /** Emit an event synchronously. */
+    emit<K extends keyof E>(
+      event: K,
+      ...args: E[K]
+    ): void;
+
+    /** Emit an event and wait for all listeners (run in parallel, errors isolated unless strict). */
+    emitAsync<K extends keyof E>(
+      event: K,
+      ...args: E[K]
+    ): Promise<void>;
+
+    /** Returns true if there is at least one listener for the event. */
+    has<K extends keyof E>(
+      event: K
+    ): boolean;
+  }
+
+
+export interface ErrorContext {
+  object: object | Function;
+  event: string | symbol;
+  listener: Function;
+}
+
+type TracePayload =
+  | {
+      event: string | symbol;
+      args: any[];
+      listeners?: Function[];
+    }
+  | {
+      object: object | Function;
+    };
+
+export interface EventfulOptions {
+  /** If true, exceptions from listeners are propagated. Otherwise they are swallowed after calling `error`. */
+  strict?: boolean;
+
+  /** Optional tracing hook; defaults to `eventful.trace`. */
+  trace?: ((
+    object: object | Function,
+    action: string,
+    payload: TracePayload
+  ) => void) | null;
+
+  /** Optional error hook; defaults to `eventful.error`. */
+  error?: ((
+    err: unknown,
+    context: ErrorContext
+  ) => void) | null;
+}
+
+
+export interface EventfulFactory {
+  <T extends object | Function | undefined,
+   E extends EventMap = Record<string | symbol, any[]>>(
+    object?: T,
+    options?: EventfulOptions
+  ): (T extends undefined ? {} : T) & Eventful<E>;
+
+  /** Global hooks you can override. */
+  options: {
+    /** Default tracer. Replace to integrate with your logger. */
+    trace: (
+      object: object | Function,
+      action: string,
+      payload: TracePayload
+    ) => void | null;
+
+    /** Default error handler. Replace to integrate with your logger. */
+    error: (
+      err: unknown,
+      context: ErrorContext
+    ) => void | null;
+  };
+}
+
+export const eventful: EventfulFactory;

package/eventful.js

@@ -0,0 +1,370 @@
+/**
+ * @typedef {Object} ErrorContext
+ * @property {Object|Function} object The object emitting the event.
+ * @property {string|symbol} event The event name.
+ * @property {Function} listener The listener function that caused the error.
+ */
+
+/**
+ * @typedef {Object} EventfulOptions
+ * @property {boolean} [strict] If true, exceptions from listeners are propagated.
+ * @property {(object: Object|Function, action: string, payload: any) => void} [trace] Optional tracing hook.
+ * @property {(err: any, context: ErrorContext) => void} [error] Optional error hook.
+ */
+
+/**
+ * A mixin that adds event emitter capabilities to an object.
+ *
+ * The method returns the original object enhanced with the event
+ * subscribing and emitting methods.
+ * 
+ * If no object is provided, a new empty object is created and enhanced.
+ * 
+ * The options can configure the behavior of the event emitter.
+ * 
+ * @param {Object|Function} object The object to enhance.
+ * @param {EventfulOptions} options The options to configure the event emitter.
+ * @returns {Object|Function} The enhanced object.
+ * 
+ * @throws {TypeError} If the first argument is not an object or function.
+ */
+const eventful =
+  (object = Object.create(null),
+   options = { }) =>
+  {
+    const emptySet =
+      new Set();
+
+    if (!isObject(object)
+        && !isFunction(object))
+    {
+      throw new TypeError(
+        'Expect an object or a function.');
+    }
+  
+    const { strict = false,
+            trace = null,
+            error = null } =
+      options;
+
+    const globalOptions =
+      eventful.options;
+
+    const traceFn =
+      trace || globalOptions.trace;
+
+    if (traceFn) {
+      traceFn(
+        object,
+        'new',
+        { object });
+    }
+
+    for (const method of
+        [ 'on',
+          'once',
+          'off',
+          'emit',
+          'emitAsync',
+          'has' ]) {
+      if (method in object) {
+        throw new Error(
+          `Method "${method}" already exists.`);
+      }
+    }
+  
+    /** @type {Map<string|symbol, Set<Function>>} */
+    const map =
+      new Map();
+  
+    const add =
+      (event, listener) => {
+        let listeners =
+          map.get(event);
+  
+        if (!listeners) {
+          listeners = new Set();
+          map.set(event, listeners);
+        }
+  
+        listeners.add(listener);
+      };
+  
+    const remove =
+      (event, listener) => {
+        const listeners =
+          map.get(event);
+  
+        if (!listeners)
+          return false;
+  
+        const deleted =
+          listeners.delete(listener);
+  
+        if (listeners.size === 0)
+          map.delete(event);
+  
+        return deleted;
+      };
+
+    const getListeners =
+      event =>
+        map.get(event)
+        || emptySet;
+  
+    /**
+     * Subscribe to an event.
+     *
+     * @type {(event: string|symbol, listener: Function) => () => boolean}
+     */
+    const on =
+      (event, listener) => {
+        functionTypeGuard(listener);
+  
+        const traceFn =
+          trace
+          || globalOptions.trace;
+
+        if (traceFn) {
+          traceFn(
+            object,
+            'on',
+            { event,
+              listener });
+        }
+  
+        add(
+          event,
+          listener);
+  
+        let active = true;
+  
+        return () => {
+          if (!active)
+            return false;
+  
+          active = false;
+  
+          return remove(
+            event,
+            listener);
+        };
+      };
+  
+    /**
+     * Subscribe to an event for a single occurrence.
+     *
+     * @type {(event: string|symbol, listener: Function) => () => boolean}
+     */
+    const once =
+      (event, listener) => {
+        functionTypeGuard(listener);
+  
+        const off =
+          on(
+            event,
+            (...args) => {
+              off();
+              listener(...args);
+            });
+  
+        return off;
+      };
+  
+    
+    /** @type {(event: string|symbol) => boolean} */
+    const has =
+      event =>
+        map.get(event)?.size > 0
+        || false;
+  
+    /**
+     * Emit an event synchronously.
+     * All listeners run in order.
+     * Errors are isolated (ignored) unless `strict` is true.
+     *
+     * @param {string|symbol} event
+     * @param {...any} args
+     */
+    const emit =
+      (event, ...args) => {
+        const listeners =
+          getListeners(event);
+
+        const traceFn =
+          trace
+          || globalOptions.trace;
+
+        if (traceFn) {
+          traceFn(
+            object,
+            'emit',
+            { listeners: [...listeners],
+              event,
+              args });
+        }
+
+        if (listeners.size === 0)
+          return;
+          
+        for (const listener of listeners) {
+          try {
+            listener(...args);
+          } catch (err) {
+            const context =
+              { object,
+                event,
+                listener };
+
+            (error || globalOptions.error)(
+              err,
+              context);
+
+            if (strict)
+              throw err;
+          }
+        }
+      };
+    
+    /**
+     * Emit an event and wait for all listeners (run in parallel).
+     * Errors are isolated (ignored) so all listeners run.
+     *
+     * @param {string|symbol} event
+     * @param {...any} args
+     * @returns {Promise<void>}
+     */
+    const emitAsync =
+      async (event, ...args) => {
+        const listeners =
+          getListeners(event);
+
+        const traceFn =
+          trace
+          || globalOptions.trace;
+
+        if (traceFn) {
+          traceFn(
+            object,
+            'emitAsync',
+            { listeners: [...listeners],
+              event,
+              args });
+        }
+
+        if (listeners.size === 0)
+          return;
+  
+        const calls =
+          Array.from(listeners)
+            .map(listener =>
+              new Promise(
+                (resolve, reject) => {
+                  try {
+                    Promise.resolve(listener(...args))
+                      .then(resolve, err => {
+                        const errorFn =
+                          error
+                          || globalOptions.error;
+                        
+                        if (errorFn) {
+                          const context =
+                            { object,
+                              event,
+                              listener };
+
+                          errorFn(err, context);
+                        }
+
+                        reject(err);
+                      });
+                  } catch (err) {
+                    const errorFn =
+                      error
+                      || globalOptions.error;
+                    
+                    if (errorFn) {
+                      const context =
+                        { object,
+                          event,
+                          listener };
+
+                      errorFn(err, context);
+                    }
+
+                    reject(err);
+                  }
+                }));
+
+        if (strict)
+          await Promise.all(calls);
+        else
+          await Promise.allSettled(calls);
+      };
+  
+    /**
+     * Unsubscribe from an event.
+     *
+     * @param {string} event The event name.
+     * @param {Function} listener The handling function.
+     * @returns {boolean} True if unsubscribed, false if not found.
+     */
+    const off =
+      (event, listener) => {
+        functionTypeGuard(listener);
+
+        const traceFn =
+          trace
+          || globalOptions.trace;
+
+        if (traceFn) {
+          traceFn(
+            object,
+            'off',
+            { event,
+              listener });
+        }
+  
+        return remove(
+          event,
+          listener);
+      };
+  
+    const attributes =
+     { enumerable: false,
+       configurable: true,
+       writable: true };
+  
+    Object.defineProperties(
+      object,
+      { on: { value: on, ...attributes },
+        once: { value: once, ...attributes },
+        off: { value: off, ...attributes },
+        emit: { value: emit, ...attributes },
+        emitAsync: { value: emitAsync, ...attributes },
+        has: { value: has, ...attributes } });
+  
+    return object;
+  };
+
+eventful.options =
+  { trace: null,
+    error: null };
+
+function isFunction(value) {
+  return typeof value === 'function';
+}
+
+function isObject(value) {
+  return value !== null
+    && typeof value === 'object';
+}
+
+function functionTypeGuard(value) {
+  if (!isFunction(value)) {
+    throw new TypeError(
+      'Expect a function.');
+  }
+}
+
+export { eventful };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "asljs-eventful",
+  "version": "0.1.3",
+  "description": "Lightweight event helper adding on/off/emit to any object.",
+  "keywords": [
+    "events",
+    "javascript",
+    "js"
+  ],
+  "homepage": "https://github.com/alex-netkachov/asljs-eventful#readme",
+  "bugs": {
+    "url": "https://github.com/alex-netkachov/asljs-eventful/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-netkachov/asljs-eventful.git"
+  },
+  "license": "MIT",
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "type": "module",
+  "main": "eventful.js",
+  "types": "eventful.d.ts",
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:watch": "node --watch --test",
+    "coverage": "NODE_V8_COVERAGE=.coverage node --test && node -e \"console.log('Coverage in .coverage (use c8/istanbul if you want reports)')\""
+  }
+}

package/tests/eventful.test.js

@@ -0,0 +1,206 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { eventful } from '../eventful.js';
+
+test(
+  'trace is called on creation with action "new"',
+  () => {
+    const traces = [];
+
+    const original = { };
+
+    const enhanced =
+      eventful(
+        original,
+        { trace:
+            (object, action, payload) =>
+              traces.push({ object, action, payload }) });
+
+    const creation =
+      traces.find(t => t.action === 'new');
+
+    assert.ok(creation);
+
+    assert.equal(
+      creation.payload.object,
+      original);
+
+    assert.equal(
+      creation.object,
+      enhanced);      
+
+    assert.equal(
+      creation.payload.object,
+      enhanced);      
+  });
+
+test(
+  'eventful creates an empty event emitter object',
+  () => {
+    const obj =
+      eventful();
+
+    assert.ok(obj);
+    assert.equal(typeof obj.on, 'function');
+    assert.equal(typeof obj.off, 'function');
+    assert.equal(typeof obj.emit, 'function');
+    assert.equal(typeof obj.emitAsync, 'function');
+    assert.equal(typeof obj.has, 'function');
+  });
+
+test(
+  'eventful throws when an object has one of the event emitter methods',
+  () => {
+    for (const method of ['on', 'once', 'off', 'emit', 'emitAsync', 'has']) {
+      assert.throws(
+        () => eventful({ [method]: () => { } }));
+    }
+  });
+
+test(
+  'exceptions in listeners are suppressed by default',
+  async () => {
+    const obj =
+      eventful(
+        { },
+        { error: () => { } });
+
+    obj.on(
+      'test',
+      () => { throw new Error('test error'); });
+
+    await assert.doesNotReject(
+      () => obj.emitAsync('test'));
+  });
+
+test(
+  'strict mode propagates exceptions in listeners',
+  async () => {
+    const obj =
+      eventful(
+        { },
+        { error: () => { },
+          strict: true });
+
+    obj.on(
+      'test',
+      () => { throw new Error('test error'); });
+
+    await assert.rejects(
+      () => obj.emitAsync('test'));
+  });
+
+test(
+  'async listener rejection is suppressed by default',
+  async () => {
+    const obj =
+      eventful(
+        { },
+        { error: () => {} });
+
+    obj.on(
+      'test',
+      async () => { throw new Error('async fail'); });
+
+    await assert.doesNotReject(
+      () => obj.emitAsync('test'));
+  });
+
+test(
+  'non-strict runs other listeners even if one fails',
+  async () => {
+    const obj =
+      eventful(
+        { },
+        { error: () => {} });
+
+    let ran = 0;
+
+    obj.on(
+      'test',
+      () => { ran += 1; });
+
+    obj.on(
+      'test',
+      () => { throw new Error('boom'); });
+
+    obj.on(
+      'test',
+      () => { ran += 1; });
+
+    await assert.doesNotReject(
+      () => obj.emitAsync('test'));
+
+    assert.equal(ran, 2);
+  });  
+
+test(
+  'trace receives safe payload and action names',
+  async () => {
+    const traces = [];
+    const obj =
+      eventful(
+        { },
+        { trace:
+            (object, action, payload) =>
+              traces.push({ action, payload }) });
+
+    const off = obj.on('e', () => {});
+    obj.emit('e', 1, 2);
+    await obj.emitAsync('e', 3, 4);
+    off();
+
+    // Expect actions at least 'on', 'emit', 'emitAsync'
+    const actions = traces.map(t => t.action);
+    assert.ok(actions.includes('on'));
+    assert.ok(actions.includes('emit'));
+    assert.ok(actions.includes('emitAsync'));
+
+    const emitTrace = traces.find(t => t.action === 'emit');
+    assert.ok(Array.isArray(emitTrace.payload.listeners));
+    assert.equal(emitTrace.payload.event, 'e');
+    assert.deepEqual(emitTrace.payload.args, [1, 2]);
+
+    const emitAsyncTrace = traces.find(t => t.action === 'emitAsync');
+    assert.ok(Array.isArray(emitAsyncTrace.payload.listeners));
+    assert.equal(emitAsyncTrace.payload.event, 'e');
+    assert.deepEqual(emitAsyncTrace.payload.args, [3, 4]);
+  });
+
+test(
+  'error hook runs for async rejection (non-strict)',
+  async () => {
+    let errors = 0;
+    const obj =
+      eventful(
+        { },
+        { error: () => { errors += 1; } });
+
+    obj.on('e', async () => { throw new Error('reject'); });
+
+    await assert.doesNotReject(() => obj.emitAsync('e'));
+    assert.equal(errors, 1);
+  });
+
+test(
+  'has reflects subscribe and unsubscribe',
+  () => {
+    const obj = eventful();
+    assert.equal(obj.has('x'), false);
+    const off = obj.on('x', () => {});
+    assert.equal(obj.has('x'), true);
+    off();
+    assert.equal(obj.has('x'), false);
+  });
+
+test(
+  'strict mode propagates async rejections',
+  async () => {
+    const obj =
+      eventful(
+        { },
+        { error: () => { }, strict: true });
+
+    obj.on('e', async () => { throw new Error('nope'); });
+    await assert.rejects(() => obj.emitAsync('e'));
+  });