@pawells/rxjs-events 1.0.1 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-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)
 
@@ -86,8 +86,8 @@ async function processOnce() {
 import { AsyncObservable, BackpressureStrategy } from '@pawells/rxjs-events';
 
 const obs = new AsyncObservable<string>({
-  bufferSize: 100,
-  strategy: BackpressureStrategy.DropOldest,
+  maxBufferSize: 100,
+  overflowStrategy: BackpressureStrategy.DropOldest,
 });
 
 for await (const item of obs) {
@@ -117,14 +117,16 @@ 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 |
+| `constructor` | `(name: string)` | Creates a handler with the given event name (cannot be empty or whitespace-only) |
+| `Name` | `string` (readonly) | Returns the event name |
+| `Subscribe` | `(onEvent: TEventFunction<TEvent>) => number` | Subscribes and returns a numeric ID |
+| `Unsubscribe` | `(subscription: number) => void` | Removes subscription by ID |
+| `Trigger` | `(data: TObject) => 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 |
+| `GetAsyncIterableIterator` | `() => AsyncIterableIterator<TEvent>` | Returns an async iterable iterator |
+| `GetAsyncIterator` | `() => AsyncIterator<TEvent>` | Returns an async iterator |
+| `GetSubscriptionCount` | `() => number` | Returns the count of active subscriptions |
+| `GetActiveSubscriptionIds` | `() => number[]` | Returns array of active subscription IDs |
 
 Subscription IDs are recycled internally — allocation is O(1).
 
@@ -132,10 +134,10 @@ Subscription IDs are recycled internally — allocation is O(1).
 
 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` |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxBufferSize` | `number` | 1000 | Maximum number of buffered items |
+| `overflowStrategy` | `BackpressureStrategy` | `DropOldest` | How to handle buffer overflow: `DropOldest`, `DropNewest`, or `Error` |
 
 Throws `BufferOverflowError` when strategy is `Error` and the buffer is full.
 
@@ -202,7 +204,7 @@ yarn vitest run src/path/to/file.test.ts
 
 ## Requirements
 
-- Node.js >= 24.0.0
+- Node.js >= 22.0.0
 - ESM-only (`"type": "module"`) — use ESM imports throughout
 
 ## License

package/build/async-observable.js

@@ -183,7 +183,7 @@ export class AsyncObservable extends Observable {
                 subscription?.unsubscribe();
                 // Resolve all pending next() promises so callers are not left hanging.
                 handleComplete();
-                return Promise.resolve({ done: true, value: null });
+                return Promise.resolve({ done: true, value: undefined });
             },
             throw: (err) => {
                 subscription?.unsubscribe();

package/build/async-observable.js.map

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

package/build/event-filter.d.ts

@@ -3,10 +3,15 @@ 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.
+ * Supports nested property paths using dot notation and predicate functions.
  *
  * @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
+ * @param args - Filter criteria object with property-value pairs to match against the event payload.
+ *              Values can be:
+ *              - Primitives: matched via strict equality
+ *              - Functions: treated as predicates that must return true
+ *              - Keys can use dot notation for nested paths (e.g., 'user.profile.role')
  * @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
@@ -20,20 +25,36 @@ import { IFilterCriteria } from './filter-criteria.js';
  *     userId: string;
  *     username: string;
  *     role: string;
+ *     profile: {
+ *       age: number;
+ *       status: string;
+ *     };
  *   };
  * }
  *
  * const event: UserEvent = {
- *   UserCreated: { userId: '123', username: 'john', role: 'admin' }
+ *   UserCreated: {
+ *     userId: '123',
+ *     username: 'john',
+ *     role: 'admin',
+ *     profile: { age: 30, status: 'active' }
+ *   }
  * };
  *
  * // 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
+ * // Match by nested path
+ * EventFilter(event, { 'profile.age': 30 }); // true
+ * EventFilter(event, { 'profile.status': 'active' }); // true
+ *
+ * // Match by predicate function
+ * EventFilter(event, { 'profile.age': (v) => v > 18 }); // true
+ * EventFilter(event, { role: (r) => r === 'admin' }); // true
+ *
+ * // Multiple criteria
+ * EventFilter(event, { role: 'admin', 'profile.age': (v) => v > 18 }); // true
  *
  * // No filter (always passes)
  * EventFilter(event, null); // true
@@ -41,4 +62,27 @@ import { IFilterCriteria } from './filter-criteria.js';
  * ```
  */
 export declare function EventFilter<TEvent extends TEventData = TEventData>(event: TEvent, args: IFilterCriteria | null | undefined): boolean;
+/**
+ * Partitions an event into matching and non-matching tuples based on filter criteria.
+ * Uses EventFilter internally to apply the filtering logic.
+ *
+ * @template TEvent - The event data type extending TEventData
+ * @param event - The event to partition
+ * @param args - Filter criteria (same as EventFilter)
+ * @returns Tuple of [matching event, non-matching event] where non-matching is null if event matches
+ *
+ * @example
+ * ```typescript
+ * const event: UserEvent = {
+ *   UserCreated: { userId: '123', username: 'john', role: 'admin' }
+ * };
+ *
+ * const [match, noMatch] = PartitionEventFilter(event, { role: 'admin' });
+ * // match = event, noMatch = null
+ *
+ * const [match2, noMatch2] = PartitionEventFilter(event, { role: 'user' });
+ * // match2 = null, noMatch2 = event
+ * ```
+ */
+export declare function PartitionEventFilter<TEvent extends TEventData = TEventData>(event: TEvent, args: IFilterCriteria | null | undefined): [TEvent | null, TEvent | null];
 //# sourceMappingURL=event-filter.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"event-filter.d.ts","sourceRoot":"","sources":["../src/event-filter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EACjE,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GACtC,OAAO,CAmBT;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAC1E,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GACtC,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAGhC"}

package/build/event-filter.js

@@ -1,10 +1,16 @@
+import { ObjectFilter } from '@pawells/typescript-common';
 /**
  * Filters events based on payload property matching criteria.
  * Performs strict equality comparison between event payload properties and filter arguments.
+ * Supports nested property paths using dot notation and predicate functions.
  *
  * @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
+ * @param args - Filter criteria object with property-value pairs to match against the event payload.
+ *              Values can be:
+ *              - Primitives: matched via strict equality
+ *              - Functions: treated as predicates that must return true
+ *              - Keys can use dot notation for nested paths (e.g., 'user.profile.role')
  * @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
@@ -18,20 +24,36 @@
  *     userId: string;
  *     username: string;
  *     role: string;
+ *     profile: {
+ *       age: number;
+ *       status: string;
+ *     };
  *   };
  * }
  *
  * const event: UserEvent = {
- *   UserCreated: { userId: '123', username: 'john', role: 'admin' }
+ *   UserCreated: {
+ *     userId: '123',
+ *     username: 'john',
+ *     role: 'admin',
+ *     profile: { age: 30, status: 'active' }
+ *   }
  * };
  *
  * // 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
+ * // Match by nested path
+ * EventFilter(event, { 'profile.age': 30 }); // true
+ * EventFilter(event, { 'profile.status': 'active' }); // true
+ *
+ * // Match by predicate function
+ * EventFilter(event, { 'profile.age': (v) => v > 18 }); // true
+ * EventFilter(event, { role: (r) => r === 'admin' }); // true
+ *
+ * // Multiple criteria
+ * EventFilter(event, { role: 'admin', 'profile.age': (v) => v > 18 }); // true
  *
  * // No filter (always passes)
  * EventFilter(event, null); // true
@@ -47,7 +69,7 @@ export function EventFilter(event, args) {
     // Identify Payload Key
     const eventKeys = Object.keys(event);
     if (eventKeys.length === 0)
-        throw new Error('No payload structure.');
+        throw new Error('Event object must have exactly one top-level key, but received an empty object ({}).');
     if (eventKeys.length > 1)
         throw new Error('More than one payload structure.');
     const eventKey = eventKeys[0];
@@ -55,12 +77,32 @@ export function EventFilter(event, args) {
     const payload = event[eventKey];
     if (!payload)
         throw new Error('No Payload');
-    for (const [key, filterValue] of Object.entries(args)) {
-        // Type-safe property access with proper unknown handling
-        const payloadValue = payload[key];
-        if (payloadValue !== filterValue)
-            return false;
-    }
-    return true;
+    return ObjectFilter(payload, args);
+}
+/**
+ * Partitions an event into matching and non-matching tuples based on filter criteria.
+ * Uses EventFilter internally to apply the filtering logic.
+ *
+ * @template TEvent - The event data type extending TEventData
+ * @param event - The event to partition
+ * @param args - Filter criteria (same as EventFilter)
+ * @returns Tuple of [matching event, non-matching event] where non-matching is null if event matches
+ *
+ * @example
+ * ```typescript
+ * const event: UserEvent = {
+ *   UserCreated: { userId: '123', username: 'john', role: 'admin' }
+ * };
+ *
+ * const [match, noMatch] = PartitionEventFilter(event, { role: 'admin' });
+ * // match = event, noMatch = null
+ *
+ * const [match2, noMatch2] = PartitionEventFilter(event, { role: 'user' });
+ * // match2 = null, noMatch2 = event
+ * ```
+ */
+export function PartitionEventFilter(event, args) {
+    const matches = EventFilter(event, args);
+    return matches ? [event, null] : [null, event];
 }
 //# sourceMappingURL=event-filter.js.map

package/build/event-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-filter.js","sourceRoot":"","sources":["../src/event-filter.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAa,EACb,IAAwC;IAExC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC,oEAAoE;IACpE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,uBAAuB;IACvB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAErC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACrE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAE9E,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAiB,CAAC;IAE9C,mCAAmC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAiC,CAAC;IAEhE,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAE5C,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,yDAAyD;QACzD,MAAM,YAAY,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;QAE/D,IAAI,YAAY,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;IAChD,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC"}
+{"version":3,"file":"event-filter.js","sourceRoot":"","sources":["../src/event-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAK1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAa,EACb,IAAwC;IAExC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IACxC,oEAAoE;IACpE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,uBAAuB;IACvB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAErC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;IACpI,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAE9E,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAiB,CAAC;IAE9C,mCAAmC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAiC,CAAC;IAEhE,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAE5C,OAAO,YAAY,CAAC,OAAO,EAAE,IAA+B,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CACnC,KAAa,EACb,IAAwC;IAExC,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/build/event-operators.d.ts

@@ -0,0 +1,92 @@
+import { EventHandler } from './handler.js';
+import { TEventData } from './event-data.js';
+/**
+ * Collects events into batches of a specified size and yields each batch as an array.
+ * The final batch may be smaller if the total number of events is not a multiple of the batch size.
+ *
+ * @template TEvent - The event type
+ * @param handler - EventHandler to collect events from
+ * @param size - Size of each batch (must be > 0)
+ * @returns AsyncIterableIterator that yields arrays of events
+ *
+ * @throws {RangeError} When size is <= 0
+ *
+ * @example
+ * ```typescript
+ * const handler = new EventHandler<MessageData, MessageEvent>('Message');
+ *
+ * // Batch events in groups of 5
+ * for await (const batch of ChunkEvents(handler, 5)) {
+ *   console.log(`Processing batch of ${batch.length} events`);
+ *   batch.forEach(event => processEvent(event));
+ * }
+ * ```
+ */
+export declare function ChunkEvents<TEvent extends TEventData = TEventData>(handler: EventHandler<any, TEvent>, size: number): AsyncIterableIterator<TEvent[]>;
+/**
+ * Partitions an event stream into two separate async iterators: one for matching events and one for non-matching.
+ * The predicate function determines which iterator receives each event.
+ *
+ * @template TEvent - The event type
+ * @param handler - EventHandler to partition events from
+ * @param predicate - Function that determines if an event matches (true = matching, false = non-matching)
+ * @returns Tuple of [matching iterator, non-matching iterator]
+ *
+ * @example
+ * ```typescript
+ * const handler = new EventHandler<UserEvent, UserEvent>('UserCreated');
+ *
+ * // Split events by admin status
+ * const [admins, users] = PartitionEvents(handler, (event) => {
+ *   return 'UserCreated' in event && event.UserCreated.role === 'admin';
+ * });
+ *
+ * // Process matching (admin) events
+ * for await (const event of admins) {
+ *   console.log('Admin created:', event);
+ * }
+ *
+ * // Process non-matching (regular user) events in parallel
+ * for await (const event of users) {
+ *   console.log('User created:', event);
+ * }
+ * ```
+ */
+export declare function PartitionEvents<TEvent extends TEventData = TEventData>(handler: EventHandler<any, TEvent>, predicate: (event: TEvent) => boolean): [AsyncIterableIterator<TEvent>, AsyncIterableIterator<TEvent>];
+/**
+ * Groups events by a key function and yields each group as a Map when the group reaches a specified size.
+ * Groups are keyed by the result of applying the key function to each event.
+ *
+ * @template TEvent - The event type
+ * @template TKey - The type of the grouping key
+ * @param handler - EventHandler to group events from
+ * @param keyFn - Function that extracts the grouping key from an event
+ * @param flushSize - Number of events needed to trigger a flush of a group
+ * @returns AsyncIterableIterator that yields Maps of grouped events
+ *
+ * @throws {RangeError} When flushSize is <= 0
+ *
+ * @example
+ * ```typescript
+ * interface UserEvent extends TEventData {
+ *   UserActivity: {
+ *     userId: string;
+ *     action: string;
+ *     timestamp: number;
+ *   };
+ * }
+ *
+ * const handler = new EventHandler<any, UserEvent>('UserActivity');
+ *
+ * // Group events by userId, flush each group after 10 events
+ * for await (const groups of GroupEventsByPayload(handler, (event) => {
+ *   return 'UserActivity' in event ? event.UserActivity.userId : 'unknown';
+ * }, 10)) {
+ *   groups.forEach((events, userId) => {
+ *     console.log(`User ${userId} has ${events.length} events`);
+ *   });
+ * }
+ * ```
+ */
+export declare function GroupEventsByPayload<TEvent extends TEventData = TEventData, TKey = string>(handler: EventHandler<any, TEvent>, keyFn: (event: TEvent) => TKey, flushSize: number): AsyncIterableIterator<Map<TKey, TEvent[]>>;
+//# sourceMappingURL=event-operators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-operators.d.ts","sourceRoot":"","sources":["../src/event-operators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EACjE,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAClC,IAAI,EAAE,MAAM,GACV,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAsBjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EACrE,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GACnC,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,CA2EhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAAE,IAAI,GAAG,MAAM,EACzF,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,EAClC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EAC9B,SAAS,EAAE,MAAM,GACf,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAmC5C"}

package/build/event-operators.js

@@ -0,0 +1,203 @@
+/**
+ * Collects events into batches of a specified size and yields each batch as an array.
+ * The final batch may be smaller if the total number of events is not a multiple of the batch size.
+ *
+ * @template TEvent - The event type
+ * @param handler - EventHandler to collect events from
+ * @param size - Size of each batch (must be > 0)
+ * @returns AsyncIterableIterator that yields arrays of events
+ *
+ * @throws {RangeError} When size is <= 0
+ *
+ * @example
+ * ```typescript
+ * const handler = new EventHandler<MessageData, MessageEvent>('Message');
+ *
+ * // Batch events in groups of 5
+ * for await (const batch of ChunkEvents(handler, 5)) {
+ *   console.log(`Processing batch of ${batch.length} events`);
+ *   batch.forEach(event => processEvent(event));
+ * }
+ * ```
+ */
+export function ChunkEvents(handler, size) {
+    if (size <= 0) {
+        throw new RangeError('Batch size must be greater than 0');
+    }
+    return (async function* () {
+        const batch = [];
+        for await (const event of handler) {
+            batch.push(event);
+            if (batch.length === size) {
+                yield [...batch];
+                batch.length = 0;
+            }
+        }
+        // Yield any remaining events in the final batch
+        if (batch.length > 0) {
+            yield batch;
+        }
+    })();
+}
+/**
+ * Partitions an event stream into two separate async iterators: one for matching events and one for non-matching.
+ * The predicate function determines which iterator receives each event.
+ *
+ * @template TEvent - The event type
+ * @param handler - EventHandler to partition events from
+ * @param predicate - Function that determines if an event matches (true = matching, false = non-matching)
+ * @returns Tuple of [matching iterator, non-matching iterator]
+ *
+ * @example
+ * ```typescript
+ * const handler = new EventHandler<UserEvent, UserEvent>('UserCreated');
+ *
+ * // Split events by admin status
+ * const [admins, users] = PartitionEvents(handler, (event) => {
+ *   return 'UserCreated' in event && event.UserCreated.role === 'admin';
+ * });
+ *
+ * // Process matching (admin) events
+ * for await (const event of admins) {
+ *   console.log('Admin created:', event);
+ * }
+ *
+ * // Process non-matching (regular user) events in parallel
+ * for await (const event of users) {
+ *   console.log('User created:', event);
+ * }
+ * ```
+ */
+export function PartitionEvents(handler, predicate) {
+    const matchingQueue = [];
+    const nonMatchingQueue = [];
+    let matchingResolve;
+    let nonMatchingResolve;
+    // Track reference count for proper cleanup
+    let activeIterators = 2;
+    // Subscribe to the handler and distribute events to appropriate queues
+    const subscriptionId = handler.Subscribe((event) => {
+        if (predicate(event)) {
+            matchingQueue.push(event);
+            if (matchingResolve) {
+                matchingResolve();
+                matchingResolve = undefined;
+            }
+        }
+        else {
+            nonMatchingQueue.push(event);
+            if (nonMatchingResolve) {
+                nonMatchingResolve();
+                nonMatchingResolve = undefined;
+            }
+        }
+    });
+    const createIterator = (queue) => {
+        let closed = false;
+        return {
+            async next() {
+                if (closed) {
+                    return { done: true, value: undefined };
+                }
+                while (queue.length === 0) {
+                    await new Promise((resolve) => {
+                        if (queue === matchingQueue) {
+                            matchingResolve = resolve;
+                        }
+                        else {
+                            nonMatchingResolve = resolve;
+                        }
+                    });
+                }
+                if (queue.length > 0) {
+                    const event = queue.shift();
+                    return { done: false, value: event };
+                }
+                return { done: true, value: undefined };
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
+            async return() {
+                await Promise.resolve();
+                closed = true;
+                activeIterators--;
+                // Only unsubscribe when all iterators have closed
+                if (activeIterators === 0) {
+                    handler.Unsubscribe(subscriptionId);
+                }
+                return { done: true, value: undefined };
+            },
+        };
+    };
+    // Create iterators that share the same queues and handler
+    const matchingIterator = createIterator(matchingQueue);
+    const nonMatchingIterator = createIterator(nonMatchingQueue);
+    return [matchingIterator, nonMatchingIterator];
+}
+/**
+ * Groups events by a key function and yields each group as a Map when the group reaches a specified size.
+ * Groups are keyed by the result of applying the key function to each event.
+ *
+ * @template TEvent - The event type
+ * @template TKey - The type of the grouping key
+ * @param handler - EventHandler to group events from
+ * @param keyFn - Function that extracts the grouping key from an event
+ * @param flushSize - Number of events needed to trigger a flush of a group
+ * @returns AsyncIterableIterator that yields Maps of grouped events
+ *
+ * @throws {RangeError} When flushSize is <= 0
+ *
+ * @example
+ * ```typescript
+ * interface UserEvent extends TEventData {
+ *   UserActivity: {
+ *     userId: string;
+ *     action: string;
+ *     timestamp: number;
+ *   };
+ * }
+ *
+ * const handler = new EventHandler<any, UserEvent>('UserActivity');
+ *
+ * // Group events by userId, flush each group after 10 events
+ * for await (const groups of GroupEventsByPayload(handler, (event) => {
+ *   return 'UserActivity' in event ? event.UserActivity.userId : 'unknown';
+ * }, 10)) {
+ *   groups.forEach((events, userId) => {
+ *     console.log(`User ${userId} has ${events.length} events`);
+ *   });
+ * }
+ * ```
+ */
+export function GroupEventsByPayload(handler, keyFn, flushSize) {
+    if (flushSize <= 0) {
+        throw new RangeError('Flush size must be greater than 0');
+    }
+    return (async function* () {
+        const groups = new Map();
+        let totalCount = 0;
+        for await (const event of handler) {
+            const key = keyFn(event);
+            if (!groups.has(key)) {
+                groups.set(key, []);
+            }
+            const group = groups.get(key);
+            if (group) {
+                group.push(event);
+                totalCount++;
+                // Flush all groups when any reaches the flush size
+                if (group.length >= flushSize) {
+                    yield new Map(groups);
+                    groups.clear();
+                    totalCount = 0;
+                }
+            }
+        }
+        // Yield any remaining groups
+        if (totalCount > 0) {
+            yield groups;
+        }
+    })();
+}
+//# sourceMappingURL=event-operators.js.map

package/build/event-operators.js.map

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