@pawells/rxjs-events 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Aaron Wells
+
+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,210 @@
+# RxJS Events
+
+[![npm](https://img.shields.io/npm/v/@pawells/rxjs-events)](https://www.npmjs.com/package/@pawells/rxjs-events)
+[![GitHub Release](https://img.shields.io/github/v/release/PhillipAWells/rxjs-events)](https://github.com/PhillipAWells/rxjs-events/releases)
+[![CI](https://github.com/PhillipAWells/rxjs-events/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/rxjs-events/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/PhillipAWells?style=social)](https://github.com/sponsors/PhillipAWells)
+
+RxJS-based event handling library with reactive observables and async event streams. Supports subscription management, backpressure-aware async iteration, and TC39 Explicit Resource Management (`await using`).
+
+## Installation
+
+```bash
+npm install @pawells/rxjs-events
+# or
+yarn add @pawells/rxjs-events
+```
+
+## Usage
+
+### Defining an event shape
+
+Events must have **exactly one top-level key** whose name is the event type and whose value is the payload:
+
+```typescript
+import type { TEventData } from '@pawells/rxjs-events';
+
+interface UserCreatedEvent extends TEventData {
+  UserCreated: { userId: string; username: string };
+}
+```
+
+### EventHandler — subscribe, trigger, and unsubscribe
+
+```typescript
+import { EventHandler } from '@pawells/rxjs-events';
+
+const handler = new EventHandler<{ UserCreated: { userId: string; username: string } }, 'UserCreated'>('UserCreated');
+
+// Subscribe — returns a numeric ID
+const id = handler.Subscribe((payload) => {
+  console.log('New user:', payload.userId);
+});
+
+// Trigger the event
+handler.Trigger({ userId: '42', username: 'alice' });
+
+// Unsubscribe by ID
+handler.Unsubscribe(id);
+
+// Destroy — completes the underlying Subject and removes all subscriptions
+handler.Destroy();
+```
+
+### Async iteration with `GetAsyncIterableIterator`
+
+```typescript
+const handler = new EventHandler<{ MessageReceived: { text: string } }, 'MessageReceived'>('MessageReceived');
+
+async function processMessages() {
+  for await (const payload of handler.GetAsyncIterableIterator()) {
+    console.log('Message:', payload.text);
+  }
+}
+```
+
+### Explicit Resource Management (`await using`)
+
+`EventHandler` exposes `GetAsyncIterator()`, which returns an `IAsyncGeneratorESN` implementing `Symbol.asyncDispose`:
+
+```typescript
+async function processOnce() {
+  await using iter = handler.GetAsyncIterator();
+  const { value, done } = await iter.next();
+  if (!done) console.log(value);
+  // iter is automatically disposed at block exit
+}
+```
+
+### AsyncObservable with backpressure
+
+`AsyncObservable` is an `Observable` subclass with a push buffer and configurable overflow handling:
+
+```typescript
+import { AsyncObservable, BackpressureStrategy } from '@pawells/rxjs-events';
+
+const obs = new AsyncObservable<string>({
+  bufferSize: 100,
+  strategy: BackpressureStrategy.DropOldest,
+});
+
+for await (const item of obs) {
+  console.log(item);
+}
+```
+
+### Filtering events
+
+```typescript
+import { EventFilter } from '@pawells/rxjs-events';
+import type { IFilterCriteria } from '@pawells/rxjs-events';
+
+const criteria: IFilterCriteria = { userId: '42' };
+const event = { UserCreated: { userId: '42', username: 'alice' } };
+
+if (EventFilter(event, criteria)) {
+  // event matches all criteria
+}
+```
+
+## API
+
+### `EventHandler<TObject, TEvent>`
+
+Main event handler class wrapping an RxJS `Subject`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `constructor` | `(name: TEvent)` | Creates a handler with the given event name |
+| `Name` | `string` (getter) | Returns the event name |
+| `Subscribe` | `(handler: TEventFunction<TObject[TEvent]>, options?: ISubscriptionOptions) => number` | Subscribes and returns a numeric ID |
+| `Unsubscribe` | `(id: number) => void` | Removes subscription by ID |
+| `Trigger` | `(data: TObject[TEvent]) => void` | Emits the event with the given payload |
+| `Destroy` | `() => void` | Completes the Subject and cleans up all subscriptions |
+| `GetAsyncIterableIterator` | `() => AsyncIterableIterator<TObject[TEvent]>` | Returns an async iterable iterator |
+| `GetAsyncIterator` | `() => IAsyncGeneratorESN<TObject[TEvent]>` | Returns a disposable async generator |
+
+Subscription IDs are recycled internally — allocation is O(1).
+
+### `AsyncObservable<T>`
+
+An `Observable` subclass with a push buffer and configurable backpressure. Implements `Symbol.asyncIterator`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `bufferSize` | `number` | Maximum number of buffered items |
+| `strategy` | `BackpressureStrategy` | `DropOldest`, `DropNewest`, or `Error` |
+
+Throws `BufferOverflowError` when strategy is `Error` and the buffer is full.
+
+### `EventFilter(event, criteria)`
+
+Filters a single-key event object against an `IFilterCriteria` map using strict equality. Returns `true` if all criteria match.
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `TEventData` | Base type alias (`Record<string, unknown>`) — all event shapes extend this |
+| `TEventFunction<TEvent>` | Handler callback: `(data: TEvent) => Promise<void> \| void` |
+| `TEventHandler` | Union type for handler references |
+| `TEventFilter` | Filter function type |
+| `TAsyncObserver` | Async observer callback type |
+| `TUnsubscribe` | Unsubscribe function type |
+| `IFilterCriteria` | Index-signature interface `{ [key: string]: unknown }` |
+| `ISubscriptionOptions` | Options passed to `Subscribe` |
+| `IBackpressureConfig` | Configuration object for `AsyncObservable` |
+| `IAsyncGeneratorESN<T, TReturn, TNext>` | `AsyncGenerator` extended with `Symbol.asyncDispose` |
+| `TExtractEventPayload<TEvent>` | Utility type — extracts payload type from a `TEventData` object |
+| `BackpressureStrategy` | Enum: `DropOldest`, `DropNewest`, `Error` |
+| `BufferOverflowError` | Error thrown on buffer overflow when strategy is `Error` |
+
+### Mocks (test helpers)
+
+Import from `@pawells/rxjs-events/src/mocks/index.js` in tests (not re-exported from the main entry point):
+
+| Export | Description |
+|--------|-------------|
+| `MockEventHandler` | Controllable mock with spy capabilities for asserting triggers and subscriptions |
+| `MockAsyncObservable` | Controllable mock exposing push/complete/error helpers |
+| `SetupMatchers` | Registers all custom Vitest matchers — call from `vitest.setup.ts` |
+| `ToHaveSubscribers` | Custom matcher: asserts a handler has N active subscribers |
+| `ToHaveTriggeredEvent` | Custom matcher: asserts a mock handler triggered a specific event |
+| `ToMatchEventFilter` | Custom matcher: asserts an event matches a filter criteria map |
+| `GenerateUserEvents` | Factory for typed user-event objects |
+| `GenerateMessageEvents` | Factory for message-event objects |
+| `GenerateEventData` | Generic event-data factory |
+| `GenerateFilterCriteria` | Produces `IFilterCriteria` maps for filter tests |
+| `GenerateSubscriptionScenarios` | Generates multi-subscription test scenarios |
+
+## Development
+
+```bash
+yarn build            # Compile TypeScript → ./build/
+yarn dev              # Build and run
+yarn watch            # TypeScript watch mode
+yarn typecheck        # Type check without emitting
+yarn lint             # ESLint src/
+yarn lint:fix         # ESLint with auto-fix
+yarn test             # Run Vitest tests
+yarn test:ui          # Open interactive Vitest UI in a browser
+yarn test:coverage    # Run tests with coverage report
+yarn start            # Run built output
+```
+
+To run a single test file:
+
+```bash
+yarn vitest run src/path/to/file.test.ts
+```
+
+## Requirements
+
+- Node.js >= 24.0.0
+- ESM-only (`"type": "module"`) — use ESM imports throughout
+
+## License
+
+MIT — See [LICENSE](./LICENSE) for details.

package/build/async-generator-esn.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Extended AsyncGenerator interface with async disposal support.
+ *
+ * ESN = Explicit Symbol Notation — extends AsyncGenerator with `Symbol.asyncDispose` support
+ * for the TC39 Explicit Resource Management proposal (`using` keyword). `Symbol.asyncDispose`
+ * is called when the generator is used in a `await using` block.
+ *
+ * @template T The type of the values yielded by the generator.
+ * @template TReturn The type of the value returned by the generator.
+ * @template TNext The type of the value that can be passed to the generator's next() method.
+ *
+ * @example
+ * ```typescript
+ * async function* myGenerator(): IAsyncGeneratorESN<string, void, void> {
+ *   yield 'value1';
+ *   yield 'value2';
+ * }
+ *
+ * // With await using (requires TypeScript 5.2+)
+ * await using gen = myGenerator() as unknown as AsyncDisposable;
+ * // gen is automatically disposed when it goes out of scope
+ * ```
+ */
+export interface IAsyncGeneratorESN<T = unknown, TReturn = unknown, TNext = unknown> extends AsyncGenerator<T, TReturn, TNext> {
+    [Symbol.asyncDispose](): PromiseLike<void>;
+}
+//# sourceMappingURL=async-generator-esn.d.ts.map

package/build/async-generator-esn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-generator-esn.d.ts","sourceRoot":"","sources":["../src/async-generator-esn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,CAAE,SAAQ,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC;IAC7H,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,CAAA;CAC1C"}

package/build/async-generator-esn.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=async-generator-esn.js.map

package/build/async-generator-esn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-generator-esn.js","sourceRoot":"","sources":["../src/async-generator-esn.ts"],"names":[],"mappings":""}

package/build/async-observable.d.ts

@@ -0,0 +1,72 @@
+import { Observable } from 'rxjs';
+/**
+ * Error thrown when the observable buffer overflows.
+ */
+export declare class BufferOverflowError extends Error {
+    constructor(maxSize: number);
+}
+/**
+ * Backpressure overflow strategy
+ */
+export declare enum BackpressureStrategy {
+    /** Drop oldest events when buffer is full */
+    DropOldest = "DropOldest",
+    /** Drop newest events when buffer is full */
+    DropNewest = "DropNewest",
+    /** Throw error when buffer is full */
+    Error = "Error"
+}
+/**
+ * Configuration for AsyncObservable backpressure
+ */
+export interface IBackpressureConfig {
+    /** Maximum buffer size (default: 1000) */
+    maxBufferSize?: number;
+    /** Strategy when buffer overflows (default: DropOldest) */
+    overflowStrategy?: BackpressureStrategy;
+}
+/**
+ * An Observable that can be used as an async iterator with backpressure support.
+ * @template T The type of the values emitted by the observable.
+ */
+export declare class AsyncObservable<T> extends Observable<T> {
+    private readonly _Subject;
+    private readonly _Buffer;
+    private readonly _MaxBufferSize;
+    private readonly _OverflowStrategy;
+    /**
+     * @remarks
+     * **Buffer replay on subscription:** every new subscriber receives all buffered items
+     * (those added via `Push()` before the subscriber connected), followed by live items.
+     * This is intentional "replay" behaviour — late subscribers see historical data.
+     * If you only want live items, subscribe before pushing any data.
+     */
+    constructor(config?: IBackpressureConfig);
+    /**
+     * Adds an event to the buffer with backpressure handling
+     */
+    Push(value: T): void;
+    private _HandleOverflow;
+    /**
+     * Destroys the observable and completes the internal subject, cleaning up all resources.
+     *
+     * @example
+     * ```typescript
+     * const observable = new AsyncObservable<number>();
+     * observable.Push(1);
+     * observable.Destroy(); // Completes the subject; subscribers stop receiving events
+     * ```
+     */
+    Destroy(): void;
+    /**
+     * Returns an async generator that can be used to iterate over the values emitted by the observable.
+     *
+     * Each call creates an independent iterator with its own local queue, so multiple concurrent
+     * iterators on the same AsyncObservable are safe — they do not interfere with each other or
+     * with the shared replay buffer.
+     *
+     * @returns An async generator.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, void>;
+}
+//# sourceMappingURL=async-observable.d.ts.map

package/build/async-observable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-observable.d.ts","sourceRoot":"","sources":["../src/async-observable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAyB,MAAM,MAAM,CAAC;AAGzD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI3B;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC/B,6CAA6C;IAC7C,UAAU,eAAe;IACzB,6CAA6C;IAC7C,UAAU,eAAe;IACzB,sCAAsC;IACtC,KAAK,UAAU;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;CACxC;AAKD;;;GAGG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAE7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IAEnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAEzD;;;;;;OAMG;gBACS,MAAM,CAAC,EAAE,mBAAmB;IAqBxC;;OAEG;IACI,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAS3B,OAAO,CAAC,eAAe;IAevB;;;;;;;;;OASG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;;;;;OAQG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;CAwG9D"}

package/build/async-observable.js

@@ -0,0 +1,201 @@
+import { Observable, Subject } from 'rxjs';
+/**
+ * Error thrown when the observable buffer overflows.
+ */
+export class BufferOverflowError extends Error {
+    constructor(maxSize) {
+        super(`Buffer overflow: maximum buffer size of ${maxSize} exceeded`);
+        this.name = 'BufferOverflowError';
+    }
+}
+/**
+ * Backpressure overflow strategy
+ */
+export var BackpressureStrategy;
+(function (BackpressureStrategy) {
+    /** Drop oldest events when buffer is full */
+    BackpressureStrategy["DropOldest"] = "DropOldest";
+    /** Drop newest events when buffer is full */
+    BackpressureStrategy["DropNewest"] = "DropNewest";
+    /** Throw error when buffer is full */
+    BackpressureStrategy["Error"] = "Error";
+})(BackpressureStrategy || (BackpressureStrategy = {}));
+/** Default maximum buffer size for AsyncObservable instances */
+const DEFAULT_MAX_BUFFER_SIZE = 1000;
+/**
+ * An Observable that can be used as an async iterator with backpressure support.
+ * @template T The type of the values emitted by the observable.
+ */
+export class AsyncObservable extends Observable {
+    _Subject = new Subject();
+    _Buffer = [];
+    _MaxBufferSize;
+    _OverflowStrategy;
+    /**
+     * @remarks
+     * **Buffer replay on subscription:** every new subscriber receives all buffered items
+     * (those added via `Push()` before the subscriber connected), followed by live items.
+     * This is intentional "replay" behaviour — late subscribers see historical data.
+     * If you only want live items, subscribe before pushing any data.
+     */
+    constructor(config) {
+        super(observer => {
+            // Connect the observer to the live subject first so it will receive future pushes,
+            // then replay already-buffered items in order. Because JavaScript is single-threaded,
+            // no new Push() can interleave between these two steps, so replay order is guaranteed.
+            const innerSub = this._Subject.subscribe(observer);
+            for (const item of this._Buffer) {
+                observer.next(item);
+            }
+            return () => innerSub.unsubscribe();
+        });
+        this._MaxBufferSize = config?.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+        this._OverflowStrategy = config?.overflowStrategy ?? BackpressureStrategy.DropOldest;
+        // Validate buffer size
+        if (this._MaxBufferSize <= 0) {
+            throw new RangeError('maxBufferSize must be a positive integer');
+        }
+    }
+    /**
+     * Adds an event to the buffer with backpressure handling
+     */
+    Push(value) {
+        if (this._Buffer.length >= this._MaxBufferSize) {
+            this._HandleOverflow(value);
+        }
+        else {
+            this._Buffer.push(value);
+            this._Subject.next(value);
+        }
+    }
+    _HandleOverflow(value) {
+        switch (this._OverflowStrategy) {
+            case BackpressureStrategy.DropOldest:
+                this._Buffer.shift();
+                this._Buffer.push(value);
+                this._Subject.next(value);
+                break;
+            case BackpressureStrategy.DropNewest:
+                // Simply don't add the new value
+                break;
+            case BackpressureStrategy.Error:
+                throw new BufferOverflowError(this._MaxBufferSize);
+        }
+    }
+    /**
+     * Destroys the observable and completes the internal subject, cleaning up all resources.
+     *
+     * @example
+     * ```typescript
+     * const observable = new AsyncObservable<number>();
+     * observable.Push(1);
+     * observable.Destroy(); // Completes the subject; subscribers stop receiving events
+     * ```
+     */
+    Destroy() {
+        this._Subject.complete();
+        this._Buffer.length = 0;
+    }
+    /**
+     * Returns an async generator that can be used to iterate over the values emitted by the observable.
+     *
+     * Each call creates an independent iterator with its own local queue, so multiple concurrent
+     * iterators on the same AsyncObservable are safe — they do not interfere with each other or
+     * with the shared replay buffer.
+     *
+     * @returns An async generator.
+     */
+    [Symbol.asyncIterator]() {
+        let subscription;
+        let hasError = false;
+        let error;
+        let completed = false;
+        // Per-iterator queue — never mutates the shared _Buffer.
+        const localQueue = [];
+        const deferreds = [];
+        const handleError = (err) => {
+            hasError = true;
+            error = err;
+            while (deferreds.length) {
+                const deferred = deferreds.shift();
+                if (deferred) {
+                    const [, reject] = deferred;
+                    reject(err);
+                }
+            }
+        };
+        const handleComplete = () => {
+            completed = true;
+            while (deferreds.length) {
+                const deferred = deferreds.shift();
+                if (deferred) {
+                    const [resolve] = deferred;
+                    resolve({ done: true, value: undefined });
+                }
+            }
+        };
+        const generator = {
+            [Symbol.asyncDispose]: () => {
+                return new Promise((resolve) => {
+                    subscription?.unsubscribe();
+                    resolve();
+                });
+            },
+            next: () => {
+                // Lazily create the subscription on first next() call.
+                // Because JS is single-threaded, the Observable's subscriber function runs
+                // synchronously: it first connects to _Subject (for live items), then replays
+                // all buffered items through the `next` handler below.  At that point `deferreds`
+                // is always empty, so every replayed item lands in `localQueue`.  This means the
+                // shared _Buffer is never mutated here and multiple concurrent iterators are safe.
+                subscription ??= this.subscribe({
+                    complete: handleComplete,
+                    error: handleError,
+                    next: (value) => {
+                        if (deferreds.length) {
+                            // A consumer is already waiting; deliver directly.
+                            const deferred = deferreds.shift();
+                            if (deferred) {
+                                const [resolve] = deferred;
+                                resolve({ done: false, value });
+                            }
+                        }
+                        else {
+                            localQueue.push(value);
+                        }
+                    },
+                });
+                if (localQueue.length) {
+                    const value = localQueue.shift();
+                    return Promise.resolve({ done: false, value });
+                }
+                if (completed) {
+                    return Promise.resolve({ done: true, value: undefined });
+                }
+                if (hasError) {
+                    return Promise.reject(error);
+                }
+                return new Promise((resolve, reject) => {
+                    deferreds.push([resolve, reject]);
+                });
+            },
+            return: () => {
+                subscription?.unsubscribe();
+                // Resolve all pending next() promises so callers are not left hanging.
+                handleComplete();
+                return Promise.resolve({ done: true, value: null });
+            },
+            throw: (err) => {
+                subscription?.unsubscribe();
+                // Reject all pending next() promises so callers are not left hanging.
+                handleError(err);
+                return Promise.reject(err);
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+        };
+        return generator;
+    }
+}
+//# sourceMappingURL=async-observable.js.map

package/build/async-observable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-observable.js","sourceRoot":"","sources":["../src/async-observable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAgB,MAAM,MAAM,CAAC;AAGzD;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QAC1B,KAAK,CAAC,2CAA2C,OAAO,WAAW,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACnC,CAAC;CACD;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,oBAOX;AAPD,WAAY,oBAAoB;IAC/B,6CAA6C;IAC7C,iDAAyB,CAAA;IACzB,6CAA6C;IAC7C,iDAAyB,CAAA;IACzB,sCAAsC;IACtC,uCAAe,CAAA;AAChB,CAAC,EAPW,oBAAoB,KAApB,oBAAoB,QAO/B;AAYD,gEAAgE;AAChE,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAErC;;;GAGG;AACH,MAAM,OAAO,eAAmB,SAAQ,UAAa;IACnC,QAAQ,GAAG,IAAI,OAAO,EAAK,CAAC;IAE5B,OAAO,GAAQ,EAAE,CAAC;IAElB,cAAc,CAAS;IAEvB,iBAAiB,CAAuB;IAEzD;;;;;;OAMG;IACH,YAAY,MAA4B;QACvC,KAAK,CAAC,QAAQ,CAAC,EAAE;YAChB,mFAAmF;YACnF,sFAAsF;YACtF,uFAAuF;YACvF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YACnD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;YACD,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACrC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,cAAc,GAAG,MAAM,EAAE,aAAa,IAAI,uBAAuB,CAAC;QACvE,IAAI,CAAC,iBAAiB,GAAG,MAAM,EAAE,gBAAgB,IAAI,oBAAoB,CAAC,UAAU,CAAC;QAErF,uBAAuB;QACvB,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,UAAU,CAAC,0CAA0C,CAAC,CAAC;QAClE,CAAC;IACF,CAAC;IAED;;OAEG;IACI,IAAI,CAAC,KAAQ;QACnB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAChD,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACF,CAAC;IAEO,eAAe,CAAC,KAAQ;QAC/B,QAAQ,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAChC,KAAK,oBAAoB,CAAC,UAAU;gBACnC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC1B,MAAM;YACP,KAAK,oBAAoB,CAAC,UAAU;gBACnC,iCAAiC;gBACjC,MAAM;YACP,KAAK,oBAAoB,CAAC,KAAK;gBAC9B,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACrD,CAAC;IACF,CAAC;IAED;;;;;;;;;OASG;IACI,OAAO;QACb,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC;QAC5B,IAAI,YAAsC,CAAC;QAC3C,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,KAAc,CAAC;QACnB,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,yDAAyD;QACzD,MAAM,UAAU,GAAQ,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAwE,EAAE,CAAC;QAE1F,MAAM,WAAW,GAAG,CAAC,GAAY,EAAQ,EAAE;YAC1C,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,GAAG,GAAG,CAAC;YAEZ,OAAO,SAAS,CAAC,MAAM,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;gBACnC,IAAI,QAAQ,EAAE,CAAC;oBACd,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC;oBAC5B,MAAM,CAAC,GAAG,CAAC,CAAC;gBACb,CAAC;YACF,CAAC;QACF,CAAC,CAAC;QAEF,MAAM,cAAc,GAAG,GAAS,EAAE;YACjC,SAAS,GAAG,IAAI,CAAC;YAEjB,OAAO,SAAS,CAAC,MAAM,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;gBACnC,IAAI,QAAQ,EAAE,CAAC;oBACd,MAAM,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC;oBAC3B,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC3C,CAAC;YACF,CAAC;QACF,CAAC,CAAC;QAEF,MAAM,SAAS,GAAsC;YACpD,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE;gBAC3B,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;oBACpC,YAAY,EAAE,WAAW,EAAE,CAAC;oBAC5B,OAAO,EAAE,CAAC;gBACX,CAAC,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,EAAE,GAA+B,EAAE;gBACtC,uDAAuD;gBACvD,2EAA2E;gBAC3E,8EAA8E;gBAC9E,kFAAkF;gBAClF,iFAAiF;gBACjF,mFAAmF;gBACnF,YAAY,KAAK,IAAI,CAAC,SAAS,CAAC;oBAC/B,QAAQ,EAAE,cAAc;oBACxB,KAAK,EAAE,WAAW;oBAElB,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;wBACf,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;4BACtB,mDAAmD;4BACnD,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;4BACnC,IAAI,QAAQ,EAAE,CAAC;gCACd,MAAM,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC;gCAC3B,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;4BACjC,CAAC;wBACF,CAAC;6BAAM,CAAC;4BACP,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;wBACxB,CAAC;oBACF,CAAC;iBACD,CAAC,CAAC;gBAEH,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;oBACvB,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAO,CAAC;oBACtC,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBAChD,CAAC;gBAED,IAAI,SAAS,EAAE,CAAC;oBACf,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC1D,CAAC;gBAED,IAAI,QAAQ,EAAE,CAAC;oBACd,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;gBAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;oBACtC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;gBACnC,CAAC,CAAC,CAAC;YACJ,CAAC;YAED,MAAM,EAAE,GAA+B,EAAE;gBACxC,YAAY,EAAE,WAAW,EAAE,CAAC;gBAC5B,uEAAuE;gBACvE,cAAc,EAAE,CAAC;gBACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;YAED,KAAK,EAAE,CAAC,GAAG,EAA8B,EAAE;gBAC1C,YAAY,EAAE,WAAW,EAAE,CAAC;gBAC5B,sEAAsE;gBACtE,WAAW,CAAC,GAAG,CAAC,CAAC;gBACjB,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;YACD,CAAC,MAAM,CAAC,aAAa,CAAC;gBACrB,OAAO,IAAI,CAAC;YACb,CAAC;SACD,CAAC;QACF,OAAO,SAAS,CAAC;IAClB,CAAC;CACD"}

package/build/event-data.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Base interface for all event data structures.
+ * Events should have a single key representing the event type with associated payload data.
+ *
+ * @example
+ * ```typescript
+ * interface UserCreatedEvent extends TEventData {
+ *   UserCreated: {
+ *     userId: string;
+ *     username: string;
+ *     email: string;
+ *   };
+ * }
+ * ```
+ */
+export type TEventData = Record<string, unknown>;
+//# sourceMappingURL=event-data.d.ts.map

package/build/event-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-data.d.ts","sourceRoot":"","sources":["../src/event-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/build/event-data.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-data.js.map

package/build/event-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-data.js","sourceRoot":"","sources":["../src/event-data.ts"],"names":[],"mappings":""}

package/build/event-filter.d.ts

@@ -0,0 +1,44 @@
+import { TEventData } from './event-data.js';
+import { IFilterCriteria } from './filter-criteria.js';
+/**
+ * Filters events based on payload property matching criteria.
+ * Performs strict equality comparison between event payload properties and filter arguments.
+ *
+ * @template TEvent - The event data type extending TEventData
+ * @param event - The event to filter, must have exactly one property representing the event type
+ * @param args - Filter criteria object with property-value pairs to match against the event payload
+ * @returns true if the event matches all filter criteria or if no filter is provided, false otherwise
+ *
+ * @throws {Error} 'No Event' - When event is null or undefined
+ * @throws {Error} 'More than one payload structure.' - When event has more than one top-level property
+ * @throws {Error} 'No Payload' - When the event's payload is null or undefined
+ *
+ * @example
+ * ```typescript
+ * interface UserEvent extends TEventData {
+ *   UserCreated: {
+ *     userId: string;
+ *     username: string;
+ *     role: string;
+ *   };
+ * }
+ *
+ * const event: UserEvent = {
+ *   UserCreated: { userId: '123', username: 'john', role: 'admin' }
+ * };
+ *
+ * // Match by single property
+ * EventFilter(event, { role: 'admin' }); // true
+ * EventFilter(event, { role: 'user' }); // false
+ *
+ * // Match by multiple properties
+ * EventFilter(event, { username: 'john', role: 'admin' }); // true
+ * EventFilter(event, { username: 'john', role: 'user' }); // false
+ *
+ * // No filter (always passes)
+ * EventFilter(event, null); // true
+ * EventFilter(event, undefined); // true
+ * ```
+ */
+export declare function EventFilter<TEvent extends TEventData = TEventData>(event: TEvent, args: IFilterCriteria | null | undefined): boolean;
+//# sourceMappingURL=event-filter.d.ts.map

package/build/event-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-filter.d.ts","sourceRoot":"","sources":["../src/event-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EACjE,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GACtC,OAAO,CA0BT"}