asljs-eventful 0.3.0 → 0.4.0

package/dist/eventful-base.js

@@ -0,0 +1,6 @@
+import { eventful, } from './eventful.js';
+export class EventfulBase {
+    constructor(options = {}) {
+        eventful(this, options);
+    }
+}

package/dist/eventful-base.test.js

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EventfulBase, } from './eventful-base.js';
+test('EventfulBase wires eventful methods in constructor', () => {
+    class Demo extends EventfulBase {
+    }
+    const demo = new Demo();
+    let seen = null;
+    demo.on('ping', value => seen = value);
+    demo.emit('ping', 7);
+    assert.equal(seen, 7);
+});
+test('EventfulBase passes options to eventful setup', () => {
+    class Demo extends EventfulBase {
+    }
+    const demo = new Demo({ strict: true,
+        error: () => { } });
+    demo.on('boom', () => {
+        throw new Error('boom');
+    });
+    assert.throws(() => demo.emit('boom'), Error);
+});

package/dist/eventful-like.js

@@ -0,0 +1,14 @@
+import { isFunction, isObject, } from './guards.js';
+export function isEvenfulLike(value) {
+    if (!isObject(value)
+        && !isFunction(value)) {
+        return false;
+    }
+    return typeof value.on === 'function';
+}
+export function asEventfulLike(value) {
+    if (isEvenfulLike(value)) {
+        return value;
+    }
+    return undefined;
+}

package/dist/eventful-like.test.js

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { eventful, } from './eventful.js';
+import { asEventfulLike, isEvenfulLike, } from './eventful-like.js';
+test('isEvenfulLike returns true for eventful instances', () => {
+    const value = eventful();
+    assert.equal(isEvenfulLike(value), true);
+});
+test('isEvenfulLike returns true for plain object with on method', () => {
+    const value = { on: () => () => true };
+    assert.equal(isEvenfulLike(value), true);
+});
+test('isEvenfulLike returns false for non-like values', () => {
+    assert.equal(isEvenfulLike(undefined), false);
+    assert.equal(isEvenfulLike(null), false);
+    assert.equal(isEvenfulLike({}), false);
+    assert.equal(isEvenfulLike({ on: 1 }), false);
+});
+test('asEventfulLike returns value when compatible', () => {
+    const value = eventful();
+    const converted = asEventfulLike(value);
+    assert.equal(converted, value);
+    const typed = converted;
+    assert.ok(typed);
+});
+test('asEventfulLike returns undefined when incompatible', () => {
+    assert.equal(asEventfulLike({}), undefined);
+    assert.equal(asEventfulLike(42), undefined);
+});

package/dist/eventful.js

@@ -1,4 +1,5 @@
-import { ListenerError } from './types.js';
+import { ListenerError, } from './types.js';
+import { asEventfulLike, isEvenfulLike, } from './eventful-like.js';
 import { eventNameTypeGuard, functionTypeGuard, isFunction, isObject, } from './guards.js';
 const eventfulImpl = (object = Object.create(null), options = {}) => {
     if (!isObject(object)
@@ -145,9 +146,5 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
     }
 };
 export const eventful = eventfulImpl;
+export { isEvenfulLike, asEventfulLike, };
 eventful(eventful);
-export class EventfulBase {
-    constructor(options = {}) {
-        eventful(this, options);
-    }
-}

package/dist/eventful.test.js

@@ -0,0 +1,206 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { eventful, } from './eventful.js';
+import { EventfulBase, } from './eventful-base.js';
+test('eventful extends an object', () => {
+    const original = {};
+    const enhanced = eventful(original);
+    assert.equal(enhanced, original);
+    assertEventfulMethods(enhanced);
+});
+test('eventful extends a function', () => {
+    const original = () => { };
+    const enhanced = eventful(original);
+    assert.equal(enhanced, original);
+    assertEventfulMethods(enhanced);
+});
+test('eventful can be called without arguments', () => {
+    const enhanced = eventful();
+    assert.ok(enhanced !== null);
+    assertEventfulMethods(enhanced);
+});
+test('eventful can be extended by inheritance', () => {
+    class MyClass extends EventfulBase {
+        constructor(name) {
+            super();
+            this.name = name;
+        }
+        greet() {
+            this.emit('greet', `Hello, ${this.name}`);
+        }
+    }
+    const instance = new MyClass('Alice');
+    let greeting = null;
+    instance.on('greet', message => greeting = message);
+    instance.greet();
+    assert.equal(greeting, 'Hello, Alice');
+});
+test('eventful can be added during construction', () => {
+    class MyClass {
+        constructor(name) {
+            eventful(this);
+            this.name = name;
+        }
+        greet() {
+            this.emit('greet', `Hello, ${this.name}`);
+        }
+    }
+    const instance = new MyClass('Alice');
+    let greeting = null;
+    instance.on('greet', message => greeting = message);
+    instance.greet();
+    assert.equal(greeting, 'Hello, Alice');
+});
+test('trace is called on creation with action "new"', () => {
+    const recorder = createRecorder();
+    const object = eventful({}, { trace: recorder.write });
+    const creation = recorder.records().find(item => item.action === 'new');
+    assert.ok(creation);
+    assert.equal(creation.payload.object, object);
+});
+test('global trace is called on creation with action "new"', () => {
+    const recorder = createRecorder();
+    const off = eventful.on('new', (...args) => recorder.write('new', args[0]));
+    try {
+        const object = eventful({}, { trace: recorder.write });
+        const creation = recorder.records().find(item => item.action === 'new');
+        assert.ok(creation);
+        assert.equal(creation.payload.object, object);
+    }
+    finally {
+        off();
+    }
+});
+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 in async emit by default', async () => {
+    const obj = eventful();
+    obj.on('test', () => { throw new Error('test error'); });
+    await assert.doesNotReject(() => obj.emitAsync('test'));
+});
+function assertEventfulMethods(object) {
+    const candidate = object;
+    assert.equal(typeof candidate.on, 'function');
+    assert.equal(typeof candidate.off, 'function');
+    assert.equal(typeof candidate.emit, 'function');
+    assert.equal(typeof candidate.emitAsync, 'function');
+    assert.equal(typeof candidate.has, 'function');
+}
+test('exceptions in listeners are suppressed in async emit by default', async () => {
+    const obj = eventful();
+    obj.on('test', () => { throw new Error('test error'); });
+    await assert.doesNotReject(() => obj.emitAsync('test'));
+});
+test('exceptions in listeners are suppressed in emit by default', () => {
+    const obj = eventful();
+    obj.on('test', () => { throw new Error('test error'); });
+    assert.doesNotThrow(() => obj.emit('test'));
+});
+test('strict mode propagates exceptions in listeners in async emit', async () => {
+    const obj = eventful({}, { error: () => { },
+        strict: true });
+    obj.on('test', () => { throw new Error('test error'); });
+    await assert.rejects(() => obj.emitAsync('test'));
+});
+test('strict mode propagates exceptions in listeners in emit', () => {
+    const obj = eventful({}, { error: () => { },
+        strict: true });
+    obj.on('test', () => { throw new Error('test error'); });
+    assert.throws(() => obj.emit('test'), Error);
+});
+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 recorder = createRecorder();
+    const obj = eventful({}, { trace: recorder.write });
+    const off = obj.on('e', () => { });
+    obj.emit('e', 1, 2);
+    await obj.emitAsync('e', 3, 4);
+    off();
+    assert.ok(recorder.records().find(item => item.action === 'on'));
+    assert.ok(recorder.records().find(item => item.action === 'emit'));
+    assert.ok(recorder.records().find(item => item.action === 'emitAsync'));
+    const emitTrace = recorder.records().find(item => item.action === 'emit');
+    assert.ok(emitTrace);
+    assert.ok(Array.isArray(emitTrace.payload.listeners));
+    assert.equal(emitTrace.payload.event, 'e');
+    assert.deepEqual(emitTrace.payload.args, [1, 2]);
+    const emitAsyncTrace = recorder.records().find(item => item.action === 'emitAsync');
+    assert.ok(emitAsyncTrace);
+    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'));
+});
+test('emit ignores errors when no error hook (non-strict)', () => {
+    const obj = eventful();
+    obj.on('x', () => { throw new Error('boom'); });
+    assert.doesNotThrow(() => obj.emit('x'));
+});
+test('throw in global error listener does not loop', () => {
+    let globalErrorCalls = 0;
+    const off = eventful.on('error', () => {
+        globalErrorCalls += 1;
+        if (globalErrorCalls > 1)
+            throw new Error('global error listener loop');
+        throw new Error('boom');
+    });
+    try {
+        const obj = eventful();
+        obj.on('e', () => { throw new Error('listener failed'); });
+        assert.throws(() => obj.emit('e'), Error);
+        assert.equal(globalErrorCalls, 1);
+    }
+    finally {
+        off();
+    }
+});
+test('event must be string or symbol', () => {
+    const obj = eventful();
+    assert.throws(() => obj.on(123, () => { }), TypeError);
+    assert.throws(() => obj.emit(123), TypeError);
+    const s = Symbol('e');
+    assert.doesNotThrow(() => obj.on(s, () => { }));
+    assert.doesNotThrow(() => obj.emit(s));
+});
+export function createRecorder() {
+    const records = [];
+    return {
+        write: (action, payload) => {
+            records.push({ action, payload });
+        },
+        records: () => records
+    };
+}

package/dist/guards.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { eventNameTypeGuard, functionTypeGuard, isFunction, isObject, } from './guards.js';
+test('eventNameTypeGuard accepts string and symbol', () => {
+    assert.doesNotThrow(() => eventNameTypeGuard('event'));
+    assert.doesNotThrow(() => eventNameTypeGuard(Symbol('event')));
+});
+test('eventNameTypeGuard throws for invalid values', () => {
+    assert.throws(() => eventNameTypeGuard(42), TypeError);
+    assert.throws(() => eventNameTypeGuard(null), TypeError);
+});
+test('isFunction returns expected result', () => {
+    assert.equal(isFunction(() => { }), true);
+    assert.equal(isFunction({}), false);
+});
+test('isObject returns expected result', () => {
+    assert.equal(isObject({ key: 'value' }), true);
+    assert.equal(isObject(null), false);
+    assert.equal(isObject(() => { }), false);
+});
+test('functionTypeGuard validates value', () => {
+    assert.doesNotThrow(() => functionTypeGuard(() => { }));
+    assert.throws(() => functionTypeGuard('nope'), TypeError);
+});

package/dist/types.test.js

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { ListenerError, } from './types.js';
+test('ListenerError extends Error and stores context', () => {
+    const inner = new Error('inner');
+    const object = { id: 1 };
+    const listener = () => { };
+    const error = new ListenerError('failed', inner, object, 'test', listener);
+    assert.ok(error instanceof Error);
+    assert.equal(error.name, 'ListenerError');
+    assert.equal(error.message, 'failed');
+    assert.equal(error.error, inner);
+    assert.equal(error.object, object);
+    assert.equal(error.event, 'test');
+    assert.equal(error.listener, listener);
+});

package/eventful.d.ts

@@ -1,15 +1,24 @@
 export {
   eventful,
-  EventfulBase
+  isEvenfulLike,
+  asEventfulLike
 } from './dist/eventful.js';
 
+export {
+  EventfulBase
+} from './dist/eventful-base.js';
+
 export type {
-  EventName,
-  EventMap,
-  Eventful,
-  EventfulFactory,
-  EventfulOptions,
-  Listener,
+  EventfulLike
+} from './dist/eventful-like.js';
+
+export {
+  type EventName,
+  type EventMap,
+  type Eventful,
+  type EventfulFactory,
+  type EventfulOptions,
+  type Listener,
   ListenerError,
-  TraceFn
+  type TraceFn
 } from './dist/types.js';

package/eventful.js

@@ -1,8 +1,13 @@
 export {
   eventful,
-  EventfulBase
+  isEvenfulLike,
+  asEventfulLike,
 } from './dist/eventful.js';
 
+export {
+  EventfulBase,
+} from './dist/eventful-base.js';
+
 export {
     ListenerError
   } from './dist/types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-eventful",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Lightweight event helper adding on/off/emit to any object.",
   "files": [
     "dist/**",
@@ -38,13 +38,13 @@
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "tsc -p .",
-    "build:tests": "tsc -p tsconfig.tests.json",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "prepack": "npm run build",
-    "test": "npm run build && npm run build:tests && node --test .tests/*.test.js",
-    "test:watch": "npm run build && npm run build:tests && node --watch --test .tests/*.test.js",
-    "coverage": "npm run build && npm run build:tests && NODE_V8_COVERAGE=.coverage node --test .tests/*.test.js && node -e \"console.log('Coverage in .coverage (use c8/istanbul if you want reports)')\""
+    "build": "npx tsc -p tsconfig.json",
+    "build:test": "npx tsc -p tsconfig.test.json",
+    "lint": "npx eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "prepack": "npm run clean && npm run build",
+    "test": "npm run build:test && node --test dist/*.test.js",
+    "test:watch": "npm run build:test && node --watch --test dist/*.test.js",
+    "coverage": "npm run build:test && NODE_V8_COVERAGE=.coverage node --test dist/*.test.js && node -e \"console.log('Coverage in .coverage (use c8/istanbul if you want reports)')\""
   }
 }

package/dist/eventful.d.ts

@@ -1,11 +0,0 @@
-import type { EventMap, Eventful, EventfulFn, EventfulOptions } from './types.js';
-export declare const eventful: EventfulFn;
-export declare class EventfulBase<E extends EventMap = EventMap> implements Eventful<E> {
-    on: Eventful<E>['on'];
-    once: Eventful<E>['once'];
-    off: Eventful<E>['off'];
-    emit: Eventful<E>['emit'];
-    emitAsync: Eventful<E>['emitAsync'];
-    has: Eventful<E>['has'];
-    constructor(options?: EventfulOptions);
-}

package/dist/guards.d.ts

@@ -1,5 +0,0 @@
-import type { EventName } from './types.js';
-export declare function eventNameTypeGuard(value: any): asserts value is EventName;
-export declare function isFunction(value: any): value is Function;
-export declare function isObject(value: any): value is object;
-export declare function functionTypeGuard(value: any): asserts value is Function;

package/dist/types.d.ts

@@ -1,97 +0,0 @@
-export type EventName = string | symbol;
-export type EventMap = Record<EventName, any[]>;
-export type Listener<Args extends any[] = any[]> = (...args: Args) => any;
-export interface ListenerErrorArgs {
-    error: any;
-    object: object | Function;
-    event: EventName;
-    listener: Function;
-}
-export declare class ListenerError extends Error implements ListenerErrorArgs {
-    error: any;
-    object: object | Function;
-    event: EventName;
-    listener: Function;
-    constructor(message: string, error: any, object: object | Function, event: EventName, listener: Function);
-}
-type TraceAction = 'new' | 'on' | 'off' | 'emit' | 'emitAsync';
-type TracePayloadByAction = {
-    new: {
-        object: object | Function;
-    };
-    on: {
-        object: object | Function;
-        event: EventName;
-        listener: Function;
-    };
-    off: {
-        object: object | Function;
-        event: EventName;
-        listener: Function;
-    };
-    emit: {
-        object: object | Function;
-        listeners: Function[];
-        event: EventName;
-        args: any[];
-    };
-    emitAsync: {
-        object: object | Function;
-        listeners: Function[];
-        event: EventName;
-        args: any[];
-    };
-};
-export type TraceFn = <A extends TraceAction>(action: A, args: TracePayloadByAction[A]) => void;
-export type EventfulFn = EventfulFactory & Eventful;
-export interface EventfulFactory {
-    <T extends object | Function | undefined, E extends EventMap = EventMap>(object?: T, options?: EventfulOptions): (T extends undefined ? {} : T) & Eventful<E>;
-}
-export interface EventfulOptions {
-    /**
-     * If true, exceptions from listeners are propagated (fail fast).
-     * When false, errors are isolated (ignored) after calling `error` hook.
-     */
-    strict?: boolean;
-    /**
-     * Optional tracing hook. Receives action name and a safe payload.
-     * Actions include: 'new', 'on', 'off', 'emit', 'emitAsync'.
-     * Use to integrate with your logger without exposing internals.
-     */
-    trace?: TraceFn | null;
-    /**
-     * Optional error hook. Receives structured context of listener failures
-     * (error, object, event, listener). Called for sync and async errors.
-     */
-    error?: ((error: ListenerErrorArgs) => void) | null;
-}
-export interface Eventful<E extends EventMap = EventMap> {
-    /**
-     * Subscribe to an event. Returns an unsubscribe function.
-     */
-    on<K extends keyof E & EventName>(event: K, listener: Listener<E[K]>): () => boolean;
-    /**
-     * Subscribe once to an event. Returns an unsubscribe function
-     * (called automatically).
-     */
-    once<K extends keyof E & EventName>(event: K, listener: Listener<E[K]>): () => boolean;
-    /**
-     * Unsubscribe a previously registered listener. Returns true if removed.
-     */
-    off<K extends keyof E & EventName>(event: K, listener: Listener<E[K]>): boolean;
-    /**
-     * Emit an event synchronously. All listeners run in order.
-     * Errors are isolated (ignored) unless `strict` is true.
-     */
-    emit<K extends keyof E & EventName>(event: K, ...args: E[K]): void;
-    /**
-     * Emit an event and wait for all listeners (run in parallel).
-     * Errors are isolated (ignored) unless `strict` is true.
-     */
-    emitAsync<K extends keyof E & EventName>(event: K, ...args: E[K]): Promise<void>;
-    /**
-     * Returns true if there is at least one listener for the event.
-     */
-    has<K extends keyof E & EventName>(event: K): boolean;
-}
-export {};