@pawells/rxjs-events 1.0.0

package/build/event-filter.js

@@ -0,0 +1,66 @@
+/**
+ * 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 function EventFilter(event, args) {
+    if (!event)
+        throw new Error('No Event');
+    // If no arguments are provided, then we are not filtering anything.
+    if (!args)
+        return true;
+    // Identify Payload Key
+    const eventKeys = Object.keys(event);
+    if (eventKeys.length === 0)
+        throw new Error('No payload structure.');
+    if (eventKeys.length > 1)
+        throw new Error('More than one payload structure.');
+    const eventKey = eventKeys[0];
+    // Get Payload - now properly typed
+    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;
+}
+//# sourceMappingURL=event-filter.js.map

package/build/event-filter.js.map

@@ -0,0 +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"}

package/build/event-function.d.ts

@@ -0,0 +1,23 @@
+import { TEventData } from './event-data.js';
+/**
+ * Function type for handling events. Can be synchronous or asynchronous.
+ *
+ * @template TEvent - The specific event data type extending TEventData
+ * @param data - The event data to be processed
+ * @returns Promise<void> for async handlers, void for sync handlers
+ *
+ * @example
+ * ```typescript
+ * // Synchronous event handler
+ * const syncHandler: TEventFunction<UserCreatedEvent> = (event) => {
+ *   console.log('User created:', event.UserCreated.username);
+ * };
+ *
+ * // Asynchronous event handler
+ * const asyncHandler: TEventFunction<UserCreatedEvent> = async (event) => {
+ *   await saveUserToDatabase(event.UserCreated);
+ * };
+ * ```
+ */
+export type TEventFunction<TEvent extends TEventData = TEventData> = (_data: TEvent) => Promise<void> | void;
+//# sourceMappingURL=event-function.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-function.d.ts","sourceRoot":"","sources":["../src/event-function.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/build/event-function.js

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

package/build/event-function.js.map

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

package/build/extract-event-payload.d.ts

@@ -0,0 +1,7 @@
+import { TEventData } from './event-data.js';
+/**
+ * Type to extract the payload type from an event.
+ * Takes the first (and only) property value from an TEventData object.
+ */
+export type TExtractEventPayload<TEvent extends TEventData> = TEvent[keyof TEvent];
+//# sourceMappingURL=extract-event-payload.d.ts.map

package/build/extract-event-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-event-payload.d.ts","sourceRoot":"","sources":["../src/extract-event-payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,UAAU,IAAI,MAAM,CAAC,MAAM,MAAM,CAAC,CAAC"}

package/build/extract-event-payload.js

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

package/build/extract-event-payload.js.map

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

package/build/filter-criteria.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Filter criteria interface for event filtering.
+ * Represents property-value pairs to match against event payloads.
+ */
+export interface IFilterCriteria {
+    [key: string]: unknown;
+}
+//# sourceMappingURL=filter-criteria.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter-criteria.d.ts","sourceRoot":"","sources":["../src/filter-criteria.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB"}

package/build/filter-criteria.js

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

package/build/filter-criteria.js.map

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

package/build/handler.d.ts

@@ -0,0 +1,225 @@
+import { Subscription } from 'rxjs';
+import { TEventData } from './event-data.js';
+import { TEventFunction } from './event-function.js';
+/**
+ * Event handler class that provides reactive event management with RxJS integration.
+ * Supports subscription management, event triggering, and async iteration patterns.
+ *
+ * @template TObject - The type of data objects that can be triggered as events
+ * @template TEvent - The event data type extending TEventData that will be received by subscribers
+ *
+ * @example
+ * ```typescript
+ * interface MessageData {
+ *   id: number;
+ *   text: string;
+ * }
+ *
+ * interface MessageEvent extends TEventData {
+ *   MessageReceived: MessageData;
+ * }
+ *
+ * // Create handler
+ * const handler = new EventHandler<MessageData, MessageEvent>('MessageReceived');
+ *
+ * // Subscribe to events
+ * const subscription = handler.Subscribe(async (event) => {
+ *   console.log('Message:', event.MessageReceived.text);
+ * });
+ *
+ * // Trigger events
+ * handler.Trigger({ id: 1, text: 'Hello World' });
+ *
+ * // Unsubscribe
+ * handler.Unsubscribe(subscription);
+ *
+ * // Async iteration
+ * for await (const event of handler.GetAsyncIterableIterator()) {
+ *   console.log('Async event:', event.MessageReceived.text);
+ *   break; // Important: break to avoid infinite loop
+ * }
+ * ```
+ */
+export declare class EventHandler<TObject extends object = object, TEvent extends TEventData = TEventData> {
+    /**
+     * The name of the event type this handler manages.
+     * Used as the key when wrapping triggered data into event objects.
+     */
+    readonly Name: string;
+    /**
+     * Creates a new EventHandler instance.
+     *
+     * @param name - The name of the event type to handle. Cannot be empty.
+     * @throws {Error} 'Event Name is Empty' - When the provided name is an empty string
+     *
+     * @example
+     * ```typescript
+     * const handler = new EventHandler('UserRegistered');
+     * console.log(handler.Name); // 'UserRegistered'
+     * ```
+     */
+    constructor(name: string);
+    /** Internal map storing active subscriptions by their unique IDs */
+    protected _subscriptions: Map<number, Subscription>;
+    /**
+     * Set of available subscription IDs for efficient reuse.
+     * IDs are reused in insertion order (i.e. the order they were freed via Unsubscribe).
+     * This is deterministic but not necessarily ascending; callers must not depend on a
+     * specific reuse order.
+     */
+    private readonly _AvailableIds;
+    /** Next sequential ID to assign when no IDs are available for reuse */
+    private _NextId;
+    /** Internal RxJS Subject for event broadcasting */
+    private readonly _Subject;
+    /**
+     * Returns an async iterable iterator for receiving events.
+     * Allows using for-await-of loops to process events as they arrive.
+     *
+     * @returns AsyncIterableIterator that yields events as they are triggered
+     *
+     * @example
+     * ```typescript
+     * const handler = new EventHandler<MessageData, MessageEvent>('Message');
+     *
+     * // Process events in a background task
+     * const processEvents = async () => {
+     *   for await (const event of handler.GetAsyncIterableIterator()) {
+     *     console.log('Received:', event.Message.text);
+     *     // Important: include break condition to avoid infinite loop
+     *     if (shouldStop) break;
+     *   }
+     * };
+     *
+     * processEvents();
+     * handler.Trigger({ text: 'Hello' }); // Will be processed by the loop
+     * ```
+     */
+    GetAsyncIterableIterator(): AsyncIterableIterator<TEvent>;
+    /**
+     * Returns an async iterator for receiving events.
+     * Provides lower-level access to the event stream compared to GetAsyncIterableIterator.
+     *
+     * @returns AsyncIterator that can be manually advanced with next() calls
+     *
+     * @example
+     * ```typescript
+     * const handler = new EventHandler<MessageData, MessageEvent>('Message');
+     * const iterator = handler.GetAsyncIterator();
+     *
+     * // Manually advance the iterator
+     * const result1 = await iterator.next();
+     * console.log('First event:', result1.value?.Message.text);
+     *
+     * const result2 = await iterator.next();
+     * console.log('Second event:', result2.value?.Message.text);
+     * ```
+     */
+    GetAsyncIterator(): AsyncIterator<TEvent>;
+    /**
+     * Makes EventHandler directly usable in for-await-of loops.
+     * Delegates to GetAsyncIterableIterator().
+     *
+     * @example
+     * ```typescript
+     * for await (const event of handler) {
+     *   console.log(event);
+     *   if (shouldStop) break;
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<TEvent>;
+    /**
+     * Triggers an event with the provided data.
+     * Wraps the data in an event object using the handler's name as the key.
+     *
+     * @param data - The data to wrap and broadcast as an event
+     *
+     * @example
+     * ```typescript
+     * interface UserData {
+     *   id: string;
+     *   name: string;
+     * }
+     *
+     * const handler = new EventHandler<UserData, any>('UserCreated');
+     * handler.Trigger({ id: '123', name: 'John' });
+     * // Subscribers will receive: { UserCreated: { id: '123', name: 'John' } }
+     * ```
+     */
+    Trigger(data: TObject): void;
+    /**
+     * Subscribes to events with the provided handler function.
+     * Uses optimized O(1) ID allocation for efficient subscription management.
+     *
+     * @param onEvent - Function to call when events are triggered
+     * @returns number representing the unique subscription ID
+     *
+     * @remarks
+     * **Error handling:** if the internal RxJS Subject ever errors (which only happens if
+     * external code accesses `_Subject` directly), the error is logged via `console.error`
+     * and the subscription silently stops receiving events.  If you need in-band error
+     * delivery use `GetAsyncIterableIterator()` instead, which propagates Subject errors as
+     * iterator rejections.
+     *
+     * @example
+     * ```typescript
+     * interface MessageEvent extends TEventData {
+     *   MessageReceived: { text: string };
+     * }
+     *
+     * const handler = new EventHandler<any, MessageEvent>('MessageReceived');
+     *
+     * // Synchronous subscription
+     * const subId = handler.Subscribe((event) => {
+     *   console.log('Message:', event.MessageReceived.text);
+     * });
+     *
+     * // Asynchronous subscription
+     * const asyncSubId = handler.Subscribe(async (event) => {
+     *   await processMessage(event.MessageReceived);
+     * });
+     *
+     * // Later unsubscribe
+     * handler.Unsubscribe(subId);
+     * handler.Unsubscribe(asyncSubId);
+     * ```
+     */
+    Subscribe(onEvent: TEventFunction<TEvent>): number;
+    /**
+     * Unsubscribes from events using the subscription ID.
+     * Safely handles non-existent subscription IDs without throwing errors.
+     * Freed IDs are made available for reuse to optimize memory usage.
+     *
+     * @param subscription - The unique subscription ID returned from Subscribe()
+     *
+     * @example
+     * ```typescript
+     * const handler = new EventHandler('TestEvent');
+     *
+     * const subId = handler.Subscribe((event) => {
+     *   console.log('Event received');
+     * });
+     *
+     * // Later, unsubscribe
+     * handler.Unsubscribe(subId);
+     *
+     * // Safe to call with non-existent IDs
+     * handler.Unsubscribe(999); // No error thrown
+     * ```
+     */
+    Unsubscribe(subscription: number): void;
+    /**
+     * Destroys the event handler and cleans up all resources.
+     * Completes the internal subject and unsubscribes all active subscriptions.
+     *
+     * @example
+     * ```typescript
+     * const handler = new EventHandler('TestEvent');
+     * handler.Subscribe((event) => { });
+     * handler.Destroy(); // Cleanup
+     * ```
+     */
+    Destroy(): void;
+}
+//# sourceMappingURL=handler.d.ts.map

package/build/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,YAAY,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,SAAS,UAAU,GAAG,UAAU;IAChG;;;OAGG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;OAWG;gBACS,IAAI,EAAE,MAAM;IAKxB,oEAAoE;IACpE,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAmC;IAEtF;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE,uEAAuE;IACvE,OAAO,CAAC,OAAO,CAAa;IAE5B,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IAEnE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACY,wBAAwB,IAAI,qBAAqB,CAAC,MAAM,CAAC;IAsExE;;;;;;;;;;;;;;;;;;OAkBG;IACI,gBAAgB,IAAI,aAAa,CAAC,MAAM,CAAC;IAIhD;;;;;;;;;;;OAWG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,MAAM,CAAC;IAI9D;;;;;;;;;;;;;;;;;OAiBG;IACI,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAKnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACI,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM;IA6BzD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAW9C;;;;;;;;;;OAUG;IACI,OAAO,IAAI,IAAI;CAYtB"}