event-emission 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Steve Kinney
+
+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,331 @@
+# Event Emission
+
+A lightweight, zero-dependency, type-safe event system with DOM EventTarget ergonomics and TC39 Observable interoperability. Use one event source with callbacks, async iterators, and RxJS without losing TypeScript safety.
+
+## Tasting notes
+
+- **Typed events** - Event maps keep payloads and event names in sync
+- **Familiar API** - `addEventListener`, `removeEventListener`, `dispatchEvent`
+- **Observable-ready** - Works with RxJS and other TC39 Observable libraries
+- **Async iteration** - `for await...of` over events with backpressure options
+- **Wildcard listeners** - Listen to `*` or namespaced `user:*` patterns
+- **Observable state** - Proxy any object and emit change events automatically
+- **AbortSignal support** - Cleanup with AbortController
+- **No dependencies** - Framework-agnostic, works in Node, Bun, and browsers
+
+## When to use it
+
+- Typed app-level event buses
+- Bridging DOM events to RxJS pipelines
+- State objects that emit change events for UI updates
+- Component/service emitters without stringly-typed payloads
+
+## Installation
+
+```bash
+npm install event-emission
+# or
+bun add event-emission
+# or
+pnpm add event-emission
+```
+
+## Quick start
+
+```typescript
+import { createEventTarget } from 'event-emission';
+
+type UserEvents = {
+  'user:login': { userId: string; timestamp: Date };
+  'user:logout': { userId: string };
+  error: Error;
+};
+
+const events = createEventTarget<UserEvents>();
+
+events.addEventListener('user:login', (event) => {
+  console.log(`User ${event.detail.userId} logged in at ${event.detail.timestamp}`);
+});
+
+events.dispatchEvent({
+  type: 'user:login',
+  detail: { userId: '123', timestamp: new Date() },
+});
+```
+
+## Core concepts
+
+- **Event map**: a TypeScript type that maps event names to payload types.
+- **Event shape**: `{ type: string; detail: Payload }` for all listeners.
+- **Unsubscribe**: `addEventListener` returns a function to remove the listener.
+
+## API overview
+
+- `createEventTarget<E>(options?)`
+- `createEventTarget(target, { observe: true, ... })`
+- `Eventful<E>` base class
+- Interop: `fromEventTarget`, `forwardToEventTarget`, `pipe`
+- Utilities: `isObserved`, `getOriginal`
+
+## createEventTarget
+
+### `createEventTarget<E>(options?)`
+
+Creates a typed event target.
+
+```typescript
+type Events = {
+  message: { text: string };
+  error: Error;
+};
+
+const target = createEventTarget<Events>();
+```
+
+#### Options
+
+| Option            | Type                                     | Description                                  |
+| ----------------- | ---------------------------------------- | -------------------------------------------- |
+| `onListenerError` | `(type: string, error: unknown) => void` | Custom error handler for listener exceptions |
+
+If a listener throws and no `onListenerError` is provided, an `error` event is emitted. If there are no `error` listeners, the error is re-thrown.
+
+### Observable state
+
+Create state objects that emit change events:
+
+```typescript
+const state = createEventTarget({ count: 0, user: { name: 'Ada' } }, { observe: true });
+
+state.addEventListener('update', (event) => {
+  console.log('State changed:', event.detail.current);
+});
+
+state.addEventListener('update:count', (event) => {
+  console.log(
+    `Count changed from ${event.detail.previous.count} to ${event.detail.value}`,
+  );
+});
+
+state.count = 1; // Triggers 'update' and 'update:count'
+state.user.name = 'Grace'; // Triggers 'update' and 'update:user.name'
+```
+
+**Observe options:**
+
+| Option          | Type                            | Default  | Description                        |
+| --------------- | ------------------------------- | -------- | ---------------------------------- |
+| `observe`       | `boolean`                       | `false`  | Enable property change observation |
+| `deep`          | `boolean`                       | `true`   | Observe nested objects             |
+| `cloneStrategy` | `'shallow' \| 'deep' \| 'path'` | `'path'` | How to clone previous state        |
+
+**Update event details:**
+
+- `update` and `update:path` events include `{ value, current, previous }`.
+- Array mutators emit method events like `update:items.push` with `{ method, args, added, removed, current, previous }`.
+
+## Event listeners
+
+### `addEventListener(type, listener, options?)`
+
+Adds a listener and returns an unsubscribe function.
+
+```typescript
+const unsubscribe = events.addEventListener('message', (event) => {
+  console.log(event.detail.text);
+});
+
+unsubscribe();
+```
+
+**Options:**
+
+| Option   | Type          | Description                                  |
+| -------- | ------------- | -------------------------------------------- |
+| `once`   | `boolean`     | Remove listener after first invocation       |
+| `signal` | `AbortSignal` | Abort signal to remove listener when aborted |
+
+### `once(type, listener, options?)`
+
+Adds a one-time listener.
+
+### `removeEventListener(type, listener)`
+
+Removes a specific listener.
+
+### `removeAllListeners(type?)`
+
+Removes all listeners, or all listeners for a type.
+
+### Wildcard listeners
+
+```typescript
+events.addWildcardListener('*', (event) => {
+  console.log(`Got ${event.originalType}:`, event.detail);
+});
+
+events.addWildcardListener('user:*', (event) => {
+  console.log(`User event: ${event.originalType}`);
+});
+```
+
+Wildcard events include `{ type: pattern, originalType, detail }`.
+
+## Async iteration
+
+```typescript
+for await (const event of events.events('message', { bufferSize: 16 })) {
+  console.log('Received:', event.detail.text);
+}
+```
+
+**Iterator options:**
+
+| Option             | Type                                        | Default         | Description                    |
+| ------------------ | ------------------------------------------- | --------------- | ------------------------------ |
+| `signal`           | `AbortSignal`                               | -               | Abort signal to stop iteration |
+| `bufferSize`       | `number`                                    | `Infinity`      | Maximum buffered events        |
+| `overflowStrategy` | `'drop-oldest' \| 'drop-latest' \| 'throw'` | `'drop-oldest'` | Behavior when buffer is full   |
+
+When `overflowStrategy` is `throw`, the iterator throws `BufferOverflowError`.
+
+## Observable interoperability
+
+### `subscribe(type, observer)`
+
+```typescript
+const subscription = events.subscribe('message', {
+  next: (event) => console.log(event.detail),
+  error: (err) => console.error(err),
+  complete: () => console.log('Done'),
+});
+
+subscription.unsubscribe();
+```
+
+### `toObservable()`
+
+Returns an Observable that emits all events.
+
+```typescript
+import { from } from 'rxjs';
+import { filter, map } from 'rxjs/operators';
+
+const observable = from(events);
+
+observable
+  .pipe(
+    filter((event) => event.type === 'message'),
+    map((event) => event.detail.text),
+  )
+  .subscribe(console.log);
+```
+
+## Lifecycle
+
+### `complete()`
+
+Marks the event target as complete, clears listeners, and ends iterators.
+
+### `clear()`
+
+Removes all listeners without marking as complete.
+
+## Eventful base class
+
+Extend `Eventful` to build typed emitters:
+
+```typescript
+import { Eventful } from 'event-emission';
+
+class UserService extends Eventful<{
+  'user:created': { id: string; name: string };
+  'user:deleted': { id: string };
+  error: Error;
+}> {
+  createUser(name: string) {
+    const id = crypto.randomUUID();
+    this.dispatchEvent({ type: 'user:created', detail: { id, name } });
+    return id;
+  }
+}
+```
+
+## DOM interoperability
+
+### `fromEventTarget(domTarget, eventTypes, options?)`
+
+```typescript
+import { fromEventTarget } from 'event-emission';
+
+type ButtonEvents = {
+  click: MouseEvent;
+  focus: FocusEvent;
+};
+
+const button = document.getElementById('my-button');
+const events = fromEventTarget<ButtonEvents>(button, ['click', 'focus']);
+
+events.addEventListener('click', (event) => {
+  console.log('Button clicked!', event.detail);
+});
+
+events.destroy();
+```
+
+### `forwardToEventTarget(source, domTarget, options?)`
+
+```typescript
+import { createEventTarget, forwardToEventTarget } from 'event-emission';
+
+const events = createEventTarget<{ custom: { value: number } }>();
+const element = document.getElementById('target');
+
+const unsubscribe = forwardToEventTarget(events, element);
+
+events.dispatchEvent({ type: 'custom', detail: { value: 42 } });
+
+unsubscribe();
+```
+
+### `pipe(source, target, options?)`
+
+```typescript
+import { createEventTarget, pipe } from 'event-emission';
+
+const componentEvents = createEventTarget<{ ready: void }>();
+const appBus = createEventTarget<{ ready: void }>();
+
+const unsubscribe = pipe(componentEvents, appBus);
+
+unsubscribe();
+```
+
+Note: `pipe(source, target)` forwards all events via a wildcard listener. The instance method `events.pipe(target)` only forwards event types that already have listeners when you call it.
+
+## Utilities
+
+### `isObserved(obj)`
+
+Checks if an object is an observed proxy.
+
+### `getOriginal(proxy)`
+
+Returns the original unproxied object.
+
+## TypeScript types
+
+```typescript
+import type {
+  EventfulEvent,
+  EventTargetLike,
+  ObservableLike,
+  Observer,
+  Subscription,
+  WildcardEvent,
+  AddEventListenerOptionsLike,
+  ObservableEventMap,
+  PropertyChangeDetail,
+  ArrayMutationDetail,
+} from 'event-emission';
+```

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Error thrown when an async iterator's event buffer overflows
+ * and the overflow strategy is 'throw'.
+ */
+export declare class BufferOverflowError extends Error {
+    constructor(eventType: string, bufferSize: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAIlD"}

package/dist/eventful.d.ts

@@ -0,0 +1,153 @@
+import { SymbolObservable } from './symbols';
+import type { AddEventListenerOptionsLike, EventfulEvent, EventsIteratorOptions, EventTargetLike, ObservableLike, Observer, Subscription, WildcardEvent } from './types';
+/**
+ * Abstract base class for typed event emitters with DOM EventTarget
+ * and TC39 Observable compatibility.
+ *
+ * Extend this class to create custom event emitters with typed events.
+ * The class provides:
+ * - DOM EventTarget compatible API (addEventListener, removeEventListener, dispatchEvent)
+ * - TC39 Observable interop (subscribe, Symbol.observable)
+ * - Async iteration support (events() method)
+ * - Wildcard listeners for namespaced events
+ * - Lifecycle management (complete(), completed)
+ *
+ * Listener errors are handled via 'error' event: if a listener throws,
+ * an 'error' event is emitted. If no 'error' listener is registered,
+ * the error is re-thrown (Node.js behavior).
+ *
+ * @template E - Event map type where keys are event names and values are event detail types.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Define your emitter with typed events
+ * class UserService extends Eventful<{
+ *   'user:created': { id: string; name: string };
+ *   'user:deleted': { id: string };
+ *   error: Error;
+ * }> {
+ *   createUser(name: string) {
+ *     const id = crypto.randomUUID();
+ *     // ... create user logic
+ *     this.dispatchEvent({ type: 'user:created', detail: { id, name } });
+ *   }
+ * }
+ *
+ * const service = new UserService();
+ * service.addEventListener('user:created', (event) => {
+ *   console.log(`Created user: ${event.detail.name}`);
+ * });
+ * ```
+ *
+ * @example TC39 Observable interop
+ * ```typescript
+ * const service = new UserService();
+ *
+ * // Subscribe to all events
+ * service.subscribe({
+ *   next: (event) => console.log(event.type, event.detail),
+ *   complete: () => console.log('Service completed'),
+ * });
+ *
+ * // Use with RxJS or other Observable libraries
+ * import { from } from 'rxjs';
+ * const observable = from(service);
+ * ```
+ *
+ * @example Async iteration
+ * ```typescript
+ * const service = new UserService();
+ *
+ * // Iterate over events as async iterator
+ * for await (const event of service.events('user:created')) {
+ *   console.log(`User created: ${event.detail.name}`);
+ * }
+ * ```
+ */
+export declare abstract class Eventful<E extends Record<string, any>> {
+    #private;
+    /**
+     * Returns this observable for Symbol.observable interop.
+     */
+    [SymbolObservable]: () => ObservableLike<EventfulEvent<E[keyof E]>>;
+    constructor();
+    /**
+     * Adds an event listener for the specified event type.
+     * Returns an unsubscribe function for convenience.
+     */
+    addEventListener<K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>, options?: AddEventListenerOptionsLike): () => void;
+    /**
+     * Removes an event listener for the specified event type.
+     */
+    removeEventListener<K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>): void;
+    /**
+     * Dispatches an event to all registered listeners.
+     * Returns false if the emitter has been completed, true otherwise.
+     */
+    dispatchEvent<K extends keyof E & string>(event: EventfulEvent<E[K]>): boolean;
+    /**
+     * Adds a one-time listener for the specified event type.
+     * Returns an unsubscribe function.
+     */
+    once<K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>, options?: Omit<AddEventListenerOptionsLike, 'once'>): () => void;
+    /**
+     * Removes all listeners, or those of the specified event type.
+     */
+    removeAllListeners<K extends keyof E & string>(type?: K): void;
+    /**
+     * Removes all listeners. Does not trigger completion.
+     */
+    clear(): void;
+    /**
+     * Pipe events from this emitter to another target.
+     * Note: Only forwards events for types that have listeners when pipe() is called.
+     * Events for types registered after piping won't be forwarded automatically.
+     */
+    pipe<T extends Record<string, any>>(target: EventTargetLike<T>, mapFn?: <K extends keyof E & string>(event: EventfulEvent<E[K]>) => EventfulEvent<T[keyof T & string]> | null): () => void;
+    /**
+     * Adds a wildcard listener that receives events matching the pattern.
+     * Use '*' for all events, or 'namespace:*' for namespaced events.
+     */
+    addWildcardListener(pattern: '*' | `${string}:*`, listener: (event: WildcardEvent<E>) => void | Promise<void>, options?: AddEventListenerOptionsLike): () => void;
+    /**
+     * Removes a wildcard listener.
+     */
+    removeWildcardListener(pattern: '*' | `${string}:*`, listener: (event: WildcardEvent<E>) => void | Promise<void>): void;
+    /**
+     * Subscribes an observer to all events (untyped).
+     */
+    subscribe(observerOrNext: Observer<EventfulEvent<E[keyof E]>> | ((value: EventfulEvent<E[keyof E]>) => void)): Subscription;
+    /**
+     * Subscribes an observer to events of a specific type (typed).
+     */
+    subscribe<K extends keyof E & string>(type: K, observerOrNext?: Observer<EventfulEvent<E[K]>> | ((value: EventfulEvent<E[K]>) => void), error?: (err: unknown) => void, completeHandler?: () => void): Subscription;
+    /**
+     * Returns an observable that emits all events.
+     */
+    toObservable(): ObservableLike<EventfulEvent<E[keyof E]>>;
+    /**
+     * Marks the emitter as complete. Invokes complete() on all observable subscribers,
+     * ends all async iterators, and suppresses further emits/dispatches.
+     * Idempotent.
+     */
+    complete(): void;
+    /**
+     * Returns true if the emitter has been completed.
+     */
+    get completed(): boolean;
+    /**
+     * Returns an async iterator over events of the specified type.
+     *
+     * @param type - The event type to iterate over
+     * @param options - Iterator options (signal, bufferSize, overflowStrategy)
+     *
+     * @example
+     * ```typescript
+     * for await (const event of emitter.events('foo')) {
+     *   console.log(event.detail);
+     * }
+     * ```
+     */
+    events<K extends keyof E & string>(type: K, options?: EventsIteratorOptions): AsyncIterableIterator<EventfulEvent<E[K]>>;
+}
+//# sourceMappingURL=eventful.d.ts.map

package/dist/eventful.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventful.d.ts","sourceRoot":"","sources":["../src/eventful.ts"],"names":[],"mappings":"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"}

package/dist/factory.d.ts

@@ -0,0 +1,89 @@
+import { type ObservableEventMap, type ObserveOptions } from './observe';
+import type { EventTargetLike } from './types';
+/**
+ * Options for createEventTarget.
+ *
+ * @property onListenerError - Custom error handler called when a listener throws.
+ *   If not provided, errors are emitted as 'error' events or re-thrown.
+ */
+export interface CreateEventTargetOptions {
+    /** Custom error handler for listener errors. Receives event type and error. */
+    onListenerError?: (type: string, error: unknown) => void;
+}
+/**
+ * Options for createEventTarget with observe mode.
+ * Extends CreateEventTargetOptions with proxy observation settings.
+ *
+ * @property observe - Must be true to enable observation mode.
+ * @property deep - If true, nested objects are also observed (default: false).
+ * @property cloneStrategy - Strategy for cloning previous state: 'shallow', 'deep', or 'path'.
+ */
+export interface CreateEventTargetObserveOptions extends CreateEventTargetOptions, ObserveOptions {
+    /** Must be true to enable observation mode. */
+    observe: true;
+}
+/**
+ * Creates a type-safe event target with DOM EventTarget and TC39 Observable compatibility.
+ *
+ * @template E - Event map type where keys are event names and values are event detail types.
+ * @param opts - Optional configuration options.
+ * @returns A type-safe event target implementing EventTargetLike.
+ *
+ * @example
+ * ```typescript
+ * // Define event types
+ * type Events = {
+ *   'user:login': { userId: string };
+ *   'user:logout': { reason: string };
+ * };
+ *
+ * // Create event target
+ * const events = createEventTarget<Events>();
+ *
+ * // Add typed listener
+ * events.addEventListener('user:login', (event) => {
+ *   console.log(`User logged in: ${event.detail.userId}`);
+ * });
+ *
+ * // Dispatch typed event
+ * events.dispatchEvent({ type: 'user:login', detail: { userId: '123' } });
+ * ```
+ *
+ * @overload Creates a basic event target
+ */
+export declare function createEventTarget<E extends Record<string, any>>(opts?: CreateEventTargetOptions): EventTargetLike<E>;
+/**
+ * Creates an observable proxy that dispatches events when properties change.
+ *
+ * @template T - The type of object to observe.
+ * @param target - The object to wrap with an observable proxy.
+ * @param opts - Configuration options with observe: true.
+ * @returns The proxied object with EventTargetLike methods mixed in.
+ *
+ * @example
+ * ```typescript
+ * // Create observable state
+ * const state = createEventTarget({ count: 0, user: { name: 'Alice' } }, {
+ *   observe: true,
+ *   deep: true,
+ * });
+ *
+ * // Listen for any update
+ * state.addEventListener('update', (event) => {
+ *   console.log('State changed:', event.detail.current);
+ * });
+ *
+ * // Listen for specific property changes
+ * state.addEventListener('update:count', (event) => {
+ *   console.log('Count changed to:', event.detail.value);
+ * });
+ *
+ * // Mutations trigger events automatically
+ * state.count = 1; // Triggers 'update' and 'update:count'
+ * state.user.name = 'Bob'; // Triggers 'update' and 'update:user.name'
+ * ```
+ *
+ * @overload Wraps an object with a Proxy that dispatches events on mutations
+ */
+export declare function createEventTarget<T extends object>(target: T, opts: CreateEventTargetObserveOptions): T & EventTargetLike<ObservableEventMap<T>>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAGV,eAAe,EAKhB,MAAM,SAAS,CAAC;AAcjB;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,+BACf,SAAQ,wBAAwB,EAAE,cAAc;IAChD,+CAA+C;IAC/C,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7D,IAAI,CAAC,EAAE,wBAAwB,GAC9B,eAAe,CAAC,CAAC,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,+BAA+B,GACpC,CAAC,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC"}