asljs-eventful 0.2.2 → 0.3.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 Alexandrite Software Ltd
+Copyright (c) 2026 Alexandrite Software Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -11,16 +11,140 @@ Lightweight event helper adding on/off/emit to any object.
 npm install asljs-eventful
 ```
 
+NPM Package: [asljs-eventful](https://www.npmjs.com/package/asljs-eventful)
+
 ## Usage
 
-### Basic Example
+### Basic (JavaScript)
+
+Adding events to an object, add listeners, and emit events:
 
 ```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!"
+
+obj.on('greet',
+  msg => console.log(`${msg}, ${obj.name}!`));
+ 
+// writes "Hello, Alice!" to console
+obj.emit('greet', 'Hello');
+```
+
+### Basic (TypeScript)
+
+```ts
+import { eventful, type Eventful } from 'asljs-eventful';
+
+type Events =
+  { greet: [msg: string] };
+
+const obj: { name: string } & Eventful<Events> =
+  eventful({ name: 'Alice' });
+
+obj.on('greet',
+  msg => console.log(`${msg}, ${obj.name}!`));
+
+// writes "Hello, Alice!" to console
+obj.emit('greet', 'Hello');
+```
+
+### Inheritance (JavaScript)
+
+Adding events to a class via inheritance:
+
+```js
+import { EventfulBase } from 'asljs-eventful';
+
+class MyClass extends EventfulBase {
+  constructor(name) {
+    super();
+
+    this.name = name;
+  }
+
+  greet() {
+    this.emit(
+      'greet',
+      `Hello, ${this.name}`);
+  }
+}
+```
+
+### Inheritance (TypeScript)
+
+```ts
+import { EventfulBase } from 'asljs-eventful';
+
+class MyClass extends EventfulBase {
+  name: string;
+
+  constructor(name: string) {
+    super();
+
+    this.name = name;
+  }
+
+  greet() {
+    this.emit(
+      'greet',
+      `Hello, ${this.name}`);
+  }
+}
+```
+
+### Construction (JavaScript)
+
+Adding events to an existing class during construction:
+
+```js
+import { eventful } from 'asljs-eventful';
+
+export class MyClass {
+  constructor(name) {
+    eventful(this);
+
+    this.name = name;
+  }
+
+  greet() {
+    this.emit(
+      'greet',
+      `Hello, ${this.name}`);
+  }
+}
+```
+
+### Construction (TypeScript)
+
+```ts
+import { eventful, type Eventful } from 'asljs-eventful';
+
+type MyClassEvents =
+  { greet: [message: string]; };
+
+export class MyClass implements Eventful<MyClassEvents> {
+  name: string;
+
+  declare on: Eventful<MyClassEvents>['on'];
+  declare once: Eventful<MyClassEvents>['once'];
+  declare off: Eventful<MyClassEvents>['off'];
+  declare emit: Eventful<MyClassEvents>['emit'];
+  declare emitAsync: Eventful<MyClassEvents>['emitAsync'];
+  declare has: Eventful<MyClassEvents>['has'];
+
+  constructor(name: string) {
+    eventful(this);
+
+    this.name = name;
+  }
+
+  greet() {
+    this.emit(
+      'greet',
+      `Hello, ${this.name}`);
+  }
+}
 ```
 
 ### Advanced Options
@@ -38,12 +162,12 @@ const obj =
             payload);
         } });
 
-// Tracing actions include:
-// - 'new' on creation: payload { object }
-// - 'on' when subscribing: payload { object, event, listener }
-// - 'off' when unsubscribing: payload { object, event, listener }
-// - 'emit' for sync emit: payload { object, event, args, listeners }
-// - 'emitAsync' for async emit: payload { object, event, args, listeners }
+// Tracing (event, payload):
+// - 'new' on creation, { object }
+// - 'on' when subscribing, { object, event, listener }
+// - 'off' when unsubscribing, { object, event, listener }
+// - 'emit' for sync emit, { object, event, args, listeners }
+// - 'emitAsync' for async emit, { object, event, args, listeners }
 ```
 
 Custom error handler for listener errors:
@@ -71,7 +195,9 @@ const obj =
 
 ### Global Events
 
-`eventful` is also a global emitter. When you create an enhanced object via `eventful(target, options)`, its lifecycle and actions are traced via the per-instance `trace` hook and also emitted as global events on `eventful`.
+`eventful` is also a global emitter. When you create an enhanced object via
+`eventful(target, options)`, its lifecycle and actions are traced via the
+per-instance `trace` hook and also emitted as global events on `eventful`.
 
 ```js
 const offNew =
@@ -93,7 +219,9 @@ offNew();
 offError();
 ```
 
-Note: if a **global** `eventful.on('error', ...)` listener throws, `eventful` throws a `ListenerError` (an `Error` subclass with fields `{ error, object, event, listener }`) to avoid an infinite error loop.
+Note: if a **global** `eventful.on('error', ...)` listener throws, `eventful`
+throws a `ListenerError` (an `Error` subclass with fields
+`{ error, object, event, listener }`) to avoid an infinite error loop.
 
 ## API
 
@@ -104,8 +232,10 @@ a new empty object is created.
 
 - `target` (Object): The object to be enhanced with event capabilities.
 - `options` (Object): Configuration options.
-  - `error` (Function | null): Optional error hook called with `{ error, object, event, listener }`.
-  - `trace` (Function | null): Optional trace hook called with `(action, payload)`.
+  - `error` (Function | null): Optional error hook called with
+    `{ error, object, event, listener }`.
+  - `trace` (Function | null): Optional trace hook called with
+    `(action, payload)`.
   - `strict` (Boolean): If true, propagates listener errors; otherwise they
     are isolated. Defaults to false.
 

package/dist/eventful.js

@@ -1,12 +1,12 @@
 import { ListenerError } from './types.js';
-import { eventTypeGuard, functionTypeGuard, isFunction, isObject, } from './guards.js';
+import { eventNameTypeGuard, functionTypeGuard, isFunction, isObject, } from './guards.js';
 const eventfulImpl = (object = Object.create(null), options = {}) => {
     if (!isObject(object)
         && !isFunction(object)) {
         throw new TypeError('Expect an object or a function.');
     }
     for (const method of ['on', 'once', 'off', 'emit', 'emitAsync', 'has']) {
-        if (object[method] !== undefined) {
+        if (method in object) {
             throw new Error(`Method "${method}" already exists.`);
         }
     }
@@ -66,7 +66,7 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
         eventful.emit('error', errorArgs);
     }
     function on(event, listener) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         functionTypeGuard(listener);
         traceFn('on', { object,
             event,
@@ -78,7 +78,7 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
             : false;
     }
     function once(event, listener) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         functionTypeGuard(listener);
         const off = on(event, (...args) => {
             off();
@@ -87,7 +87,7 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
         return off;
     }
     function off(event, listener) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         functionTypeGuard(listener);
         traceFn('off', { object,
             event,
@@ -95,11 +95,11 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
         return remove(event, listener);
     }
     function has(event) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         return (map.get(event)?.size ?? 0) > 0;
     }
     function emit(event, ...args) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         const listeners = map.get(event)
             || emptySet;
         traceFn('emit', { object,
@@ -120,7 +120,7 @@ const eventfulImpl = (object = Object.create(null), options = {}) => {
         }
     }
     async function emitAsync(event, ...args) {
-        eventTypeGuard(event);
+        eventNameTypeGuard(event);
         const listeners = map.get(event)
             || emptySet;
         traceFn('emitAsync', { object,

package/dist/guards.d.ts

@@ -1,5 +1,5 @@
 import type { EventName } from './types.js';
-export declare function eventTypeGuard(value: any): asserts value is EventName;
+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/guards.js

@@ -1,4 +1,4 @@
-export function eventTypeGuard(value) {
+export function eventNameTypeGuard(value) {
     if (typeof value !== 'string'
         && typeof value !== 'symbol') {
         throw new TypeError('Expect event to be a string or symbol.');

package/dist/types.d.ts

@@ -69,29 +69,29 @@ export interface Eventful<E extends EventMap = EventMap> {
     /**
      * Subscribe to an event. Returns an unsubscribe function.
      */
-    on(event: keyof E & EventName, listener: Listener<E[keyof E & EventName]>): () => boolean;
+    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(event: keyof E & EventName, listener: Listener<E[keyof E & EventName]>): () => boolean;
+    once<K extends keyof E & EventName>(event: K, listener: Listener<E[K]>): () => boolean;
     /**
      * Unsubscribe a previously registered listener. Returns true if removed.
      */
-    off(event: keyof E & EventName, listener: Listener<E[keyof E & EventName]>): boolean;
+    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(event: keyof E & EventName, ...args: E[keyof E & EventName]): void;
+    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(event: keyof E & EventName, ...args: E[keyof E & EventName]): Promise<void>;
+    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(event: keyof E & EventName): boolean;
+    has<K extends keyof E & EventName>(event: K): boolean;
 }
 export {};

package/eventful.js

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

package/package.json

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