@pawells/rxjs-events 1.0.1 → 1.1.0

package/build/nestjs-pubsub.js

@@ -0,0 +1,226 @@
+import { EventHandler } from './handler.js';
+/**
+ * Adapter that makes EventHandler compatible with NestJS GraphQL @Subscription() decorators.
+ * Implements the IPubSubEngine interface for pub/sub messaging patterns.
+ *
+ * This adapter bridges EventHandler with GraphQL subscriptions by maintaining a map of
+ * EventHandlers (one per trigger name) and coordinating subscription/publication.
+ *
+ * @remarks
+ * - No external dependencies required (graphql-subscriptions not needed)
+ * - Each trigger name gets its own EventHandler for isolation
+ * - Thread-safe subscription ID management
+ *
+ * @example
+ * ```typescript
+ * // In your NestJS GraphQL module:
+ * import { EventHandlerPubSub } from '@pawells/rxjs-events';
+ *
+ * const pubSub = new EventHandlerPubSub();
+ *
+ * // In a GraphQL resolver:
+ * @Subscription(() => MessagePayload, {
+ *   resolve: (payload) => payload,
+ * })
+ * messageSent(): AsyncIterableIterator<MessagePayload> {
+ *   return pubSub.asyncIterator<MessagePayload>('MESSAGE_SENT');
+ * }
+ *
+ * // In a mutation:
+ * @Mutation(() => MessagePayload)
+ * sendMessage(@Args('text') text: string): MessagePayload {
+ *   const payload = { text, timestamp: Date.now() };
+ *   pubSub.publish('MESSAGE_SENT', payload);
+ *   return payload;
+ * }
+ * ```
+ */
+export class EventHandlerPubSub {
+    /**
+     * Map storing EventHandlers indexed by trigger name.
+     * Each trigger maintains its own handler for event isolation.
+     */
+    _handlers = new Map();
+    /**
+     * Map storing handler subscriptions and their IDs for cleanup.
+     * Maps subscription ID to [handler, subscription ID within handler].
+     */
+    _subscriptions = new Map();
+    /**
+     * Counter for generating unique subscription IDs across all triggers.
+     */
+    _nextSubscriptionId = 0;
+    /**
+     * Gets or creates an EventHandler for a specific trigger name.
+     *
+     * @param triggerName - The trigger channel name
+     * @returns The EventHandler for this trigger
+     */
+    _getOrCreateHandler(triggerName) {
+        let handler = this._handlers.get(triggerName);
+        if (!handler) {
+            handler = new EventHandler(triggerName);
+            this._handlers.set(triggerName, handler);
+        }
+        return handler;
+    }
+    /**
+     * Publishes a payload to all subscribers of a trigger.
+     *
+     * @param triggerName - The trigger channel name
+     * @param payload - The payload to publish
+     */
+    async publish(triggerName, payload) {
+        await Promise.resolve();
+        const handler = this._getOrCreateHandler(triggerName);
+        handler.Trigger(payload);
+    }
+    /**
+     * Subscribes to a trigger channel and calls the callback when messages are published.
+     *
+     * @param triggerName - The trigger channel name
+     * @param onMessage - Callback function that receives the published payload
+     * @param _options - Optional subscription options (not used in current implementation)
+     * @returns Unique subscription ID for later unsubscription
+     */
+    async subscribe(triggerName, onMessage, _options) {
+        const handler = this._getOrCreateHandler(triggerName);
+        const handlerSubId = handler.Subscribe(onMessage);
+        // Generate a unique subscription ID for external tracking
+        const externalSubId = this._nextSubscriptionId++;
+        this._subscriptions.set(externalSubId, [handler, handlerSubId]);
+        await Promise.resolve();
+        return externalSubId;
+    }
+    /**
+     * Unsubscribes from a trigger channel.
+     *
+     * @param subId - The subscription ID returned from subscribe()
+     */
+    unsubscribe(subId) {
+        const subscription = this._subscriptions.get(subId);
+        if (subscription) {
+            const [handler, handlerSubId] = subscription;
+            handler.Unsubscribe(handlerSubId);
+            this._subscriptions.delete(subId);
+        }
+    }
+    /**
+     * Creates an async iterator for one or more trigger channels.
+     * Useful for GraphQL subscription resolvers.
+     *
+     * @template T - The type of values yielded by the iterator
+     * @param triggers - Single trigger name or array of trigger names
+     * @returns AsyncIterableIterator that yields published payloads
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to a single trigger
+     * const iterator = pubSub.asyncIterator('USER_CREATED');
+     *
+     * // Subscribe to multiple triggers
+     * const iterator = pubSub.asyncIterator(['USER_CREATED', 'USER_UPDATED']);
+     * ```
+     */
+    asyncIterator(triggers) {
+        const triggerArray = Array.isArray(triggers) ? triggers : [triggers];
+        if (triggerArray.length === 0) {
+            // Return an empty iterator if no triggers provided
+            return (async function* () {
+                // Empty iterator
+            })();
+        }
+        if (triggerArray.length === 1) {
+            // Single trigger - use the handler's async iterator directly
+            const handler = this._getOrCreateHandler(triggerArray[0]);
+            return handler.GetAsyncIterableIterator();
+        }
+        // Multiple triggers - merge iterators from all handlers
+        return this._mergeAsyncIterators(triggerArray);
+    }
+    /**
+     * Merges async iterators from multiple trigger handlers.
+     * Events from any trigger are yielded as they arrive.
+     *
+     * @template T - The type of values yielded
+     * @param triggers - Array of trigger names
+     * @returns Merged async iterator that yields events from all triggers concurrently
+     */
+    _mergeAsyncIterators(triggers) {
+        const handlers = triggers.map((trigger) => this._getOrCreateHandler(trigger));
+        return (async function* () {
+            const iterators = handlers.map((h) => h.GetAsyncIterableIterator());
+            let activeIterators = iterators.length;
+            try {
+                // Create promises for each iterator's next() call
+                const createNextPromises = () => {
+                    return iterators.map((iter) => iter.next()
+                        .then((result) => {
+                        if (result.done) {
+                            activeIterators--;
+                        }
+                        return result;
+                    })
+                        .catch((err) => {
+                        activeIterators--;
+                        throw err;
+                    }));
+                };
+                let promises = createNextPromises();
+                while (activeIterators > 0) {
+                    const result = await Promise.race(promises);
+                    if (!result.done) {
+                        yield result.value;
+                        promises = createNextPromises();
+                    }
+                }
+            }
+            finally {
+                // Clean up all iterators
+                for (const iterator of iterators) {
+                    if (typeof iterator.return === 'function') {
+                        await iterator.return?.();
+                    }
+                }
+            }
+        })();
+    }
+}
+/**
+ * Wraps an async iterator with a filter predicate for use with GraphQL subscriptions.
+ * Mirrors the withFilter helper from graphql-subscriptions.
+ *
+ * @template T - The type of values in the iterator
+ * @param asyncIteratorFn - Function that returns an async iterator
+ * @param filterFn - Predicate function that determines which values to yield (async functions supported)
+ * @returns Filtered async iterator
+ *
+ * @example
+ * ```typescript
+ * const pubSub = new EventHandlerPubSub();
+ *
+ * // In a GraphQL resolver:
+ * @Subscription(() => UserPayload)
+ * userUpdated(
+ *   @Args('userId') userId: string
+ * ): AsyncIterableIterator<UserPayload> {
+ *   return WithFilter(
+ *     () => pubSub.asyncIterator<UserPayload>('USER_UPDATED'),
+ *     (payload: UserPayload) => payload.userId === userId
+ *   );
+ * }
+ * ```
+ */
+export function WithFilter(asyncIteratorFn, filterFn) {
+    return (async function* () {
+        const asyncIterator = asyncIteratorFn();
+        for await (const value of asyncIterator) {
+            const result = filterFn(value);
+            const passes = result instanceof Promise ? await result : result;
+            if (passes) {
+                yield value;
+            }
+        }
+    })();
+}
+//# sourceMappingURL=nestjs-pubsub.js.map

package/build/nestjs-pubsub.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pawells/rxjs-events",
 	"displayName": "RxJS Events",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"description": "RxJS-based event handling library with reactive observables and async event streams.",
 	"type": "module",
 	"main": "./build/index.js",
@@ -23,25 +23,27 @@
 		"test": "vitest run",
 		"test:ui": "vitest --ui",
 		"test:coverage": "vitest --coverage",
+		"pipeline": "yarn typecheck && yarn lint && yarn test && yarn build",
 		"prepublishOnly": "npm run build",
 		"prepare": "husky"
 	},
 	"dependencies": {
+		"@pawells/typescript-common": "^1.4.1",
 		"rxjs": "^7.8.2"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
-		"@stylistic/eslint-plugin": "^5.9.0",
-		"@types/node": "^25.3.0",
-		"@typescript-eslint/eslint-plugin": "^8.0.0",
-		"@typescript-eslint/parser": "^8.0.0",
+		"@stylistic/eslint-plugin": "^5.10.0",
+		"@types/node": "^25.3.3",
+		"@typescript-eslint/eslint-plugin": "^8.56.1",
+		"@typescript-eslint/parser": "^8.56.1",
 		"@vitest/coverage-v8": "^4.0.18",
 		"@vitest/ui": "^4.0.18",
-		"eslint": "^10.0.1",
+		"eslint": "^10.0.3",
 		"eslint-import-resolver-typescript": "^4.4.4",
 		"eslint-plugin-import": "^2.31.0",
 		"eslint-plugin-unused-imports": "^4.0.0",
-		"globals": "^17.3.0",
+		"globals": "^17.4.0",
 		"husky": "^9.1.7",
 		"typescript": "^5.3.3",
 		"vitest": "^4.0.18"
@@ -66,7 +68,7 @@
 	},
 	"homepage": "https://github.com/PhillipAWells/rxjs-events#readme",
 	"engines": {
-		"node": ">=24.0.0"
+		"node": ">=22.0.0"
 	},
 	"packageManager": "yarn@4.12.0",
 	"files": [