asljs-eventful 0.4.2 → 0.4.3

package/dist/eventful-base.d.ts

@@ -0,0 +1,10 @@
+import { type EventMap, type Eventful, type EventfulOptions } from './types.js';
+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/eventful-like.d.ts

@@ -0,0 +1,6 @@
+import { type EventName, type Listener } from './types.js';
+export interface EventfulLike {
+    on(event: EventName, listener: Listener): () => boolean;
+}
+export declare function isEventfulLike(value: unknown): value is EventfulLike;
+export declare function asEventfulLike(value: unknown): EventfulLike | undefined;

package/dist/eventful.d.ts

@@ -0,0 +1,2 @@
+import { type EventfulFn } from './types.js';
+export declare const eventful: EventfulFn;

package/dist/guards.d.ts

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

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+export type EventName = string | symbol;
+export type EventMap = Record<EventName, unknown[]>;
+export type Listener<Args extends unknown[] = unknown[]> = (...args: Args) => unknown;
+export interface ListenerErrorArgs {
+    error: unknown;
+    object: object | Function;
+    event: EventName;
+    listener: Function;
+}
+export declare class ListenerError extends Error implements ListenerErrorArgs {
+    error: unknown;
+    object: object | Function;
+    event: EventName;
+    listener: Function;
+    constructor(message: string, error: unknown, 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: unknown[];
+    };
+    emitAsync: {
+        object: object | Function;
+        listeners: Function[];
+        event: EventName;
+        args: unknown[];
+    };
+};
+export type TraceFn = <A extends TraceAction>(action: A, args: TracePayloadByAction[A]) => void;
+export type ErrorFn = (error: ListenerErrorArgs) => 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;
+    /**
+     * Optional error hook. Receives structured context of listener failures
+     * (error, object, event, listener). Called for sync and async errors.
+     */
+    error?: ErrorFn;
+}
+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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asljs-eventful",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Lightweight event helper adding on/off/emit to any object.",
   "files": [
     "dist/**",
@@ -38,7 +38,7 @@
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npx tsc -p tsconfig.json",
+    "build": "npx tsc -p tsconfig.build.json",
     "build:test": "npx tsc -p tsconfig.test.json",
     "lint": "npx eslint .",
     "lint:fix": "npx eslint . --fix",

package/dist/eventful-base.test.js

@@ -1,22 +0,0 @@
-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.test.js

@@ -1,19 +0,0 @@
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { eventful, } from './eventful.js';
-import { asEventfulLike, isEventfulLike } from './eventful-like.js';
-test('isEventfulLike returns true for eventful instances', () => {
-    const value = eventful();
-    assert.equal(isEventfulLike(value), true);
-});
-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.test.js

@@ -1,206 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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);
-});