@crossdelta/cloudevents 0.4.22 → 0.4.24

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export type { EventContext } from './adapters/cloudevents';
 export { parseEventFromContext } from './adapters/cloudevents';
-export { createContract } from './domain';
 export type { EnrichedEvent, HandleEventOptions, IdempotencyStore, InferEventData, RoutingConfig } from './domain';
-export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
+export { createContract, eventSchema, extractTypeFromSchema, handleEvent } from './domain';
 export { clearHandlerCache, cloudEvents } from './middlewares';
 export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';
-export { consumeJetStreamEvents, consumeNatsEvents, ensureJetStreamStream } from './transports/nats';
+export type { JetStreamConsumerOptions, JetStreamStreamOptions, JetStreamStreamsConsumerOptions, JetStreamStreamsOptions, StreamConfig, StreamDefinition, } from './transports/nats';
+export { consumeJetStreamEvents, consumeJetStreamStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, } from './transports/nats';

package/dist/index.js

@@ -1,7 +1,6 @@
 export { parseEventFromContext } from './adapters/cloudevents';
-export { createContract } from './domain';
-export { eventSchema, extractTypeFromSchema, handleEvent } from './domain';
+export { createContract, eventSchema, extractTypeFromSchema, handleEvent } from './domain';
 export { clearHandlerCache, cloudEvents } from './middlewares';
 export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';
-export { consumeJetStreamEvents, consumeNatsEvents, ensureJetStreamStream } from './transports/nats';
+export { consumeJetStreamEvents, consumeJetStreamStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, } from './transports/nats';

package/dist/transports/nats/jetstream-consumer.d.ts

@@ -29,6 +29,30 @@ export interface JetStreamStreamOptions {
     /** Stream configuration */
     config?: StreamConfig;
 }
+/**
+ * Stream definition for batch operations
+ */
+export interface StreamDefinition {
+    /** JetStream stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** Subjects to bind (e.g., ['orders.*']) */
+    subjects: string[];
+    /** Optional stream-specific config */
+    config?: StreamConfig;
+}
+/**
+ * Options for ensuring multiple JetStream streams exist
+ */
+export interface JetStreamStreamsOptions {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** Array of stream definitions */
+    streams: StreamDefinition[];
+}
 /**
  * JetStream consumer configuration
  */
@@ -102,6 +126,21 @@ export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quar
  * ```
  */
 export declare function ensureJetStreamStream(options: JetStreamStreamOptions): Promise<void>;
+/**
+ * Ensures multiple JetStream streams exist with a single NATS connection.
+ * More efficient than calling ensureJetStreamStream multiple times.
+ *
+ * @example
+ * ```typescript
+ * await ensureJetStreamStreams({
+ *   streams: [
+ *     { stream: 'ORDERS', subjects: ['orders.*'] },
+ *     { stream: 'CUSTOMERS', subjects: ['customers.*'] },
+ *   ]
+ * })
+ * ```
+ */
+export declare function ensureJetStreamStreams(options: JetStreamStreamsOptions): Promise<void>;
 /**
  * Consume CloudEvents from NATS JetStream with persistence and guaranteed delivery.
  *
@@ -123,3 +162,46 @@ export declare function ensureJetStreamStream(options: JetStreamStreamOptions):
  * ```
  */
 export declare function consumeJetStreamEvents(options: JetStreamConsumerOptions): Promise<ConsumerMessages>;
+/**
+ * Options for consuming from multiple JetStream streams
+ */
+export interface JetStreamStreamsConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** Durable consumer name. Required for persistence across restarts */
+    consumer: string;
+    /** Array of stream names to consume from */
+    streams: string[];
+    /** Glob pattern to discover event handlers */
+    discover: string;
+    /** Where to start consuming from on first subscription. @default 'new' */
+    startFrom?: 'all' | 'new' | 'last' | Date;
+    /** Max number of messages to buffer for processing @default 100 */
+    maxMessages?: number;
+    /** Ack wait timeout in milliseconds @default 30000 */
+    ackWait?: number;
+    /** Max redelivery attempts @default 3 */
+    maxDeliver?: number;
+    /** Idempotency store for deduplication */
+    idempotencyStore?: IdempotencyStore | false;
+    /** TTL for idempotency records in milliseconds @default 86400000 */
+    idempotencyTtl?: number;
+}
+/**
+ * Consume CloudEvents from multiple JetStream streams with a single connection.
+ * More efficient than calling consumeJetStreamEvents multiple times.
+ *
+ * @example
+ * ```typescript
+ * await consumeJetStreamStreams({
+ *   streams: ['ORDERS', 'CUSTOMERS'],
+ *   consumer: 'notifications',
+ *   discover: './src/events/**\/*.event.ts',
+ * })
+ * ```
+ */
+export declare function consumeJetStreamStreams(options: JetStreamStreamsConsumerOptions): Promise<ConsumerMessages[]>;

package/dist/transports/nats/jetstream-consumer.js

@@ -84,6 +84,38 @@ async function ensureStream(jsm, name, subjects, config = {}) {
         logger.info(`[jetstream] created stream ${name} with subjects: ${subjects.join(', ')}`);
     }
 }
+/**
+ * Ensures multiple JetStream streams exist with a single NATS connection.
+ * More efficient than calling ensureJetStreamStream multiple times.
+ *
+ * @example
+ * ```typescript
+ * await ensureJetStreamStreams({
+ *   streams: [
+ *     { stream: 'ORDERS', subjects: ['orders.*'] },
+ *     { stream: 'CUSTOMERS', subjects: ['customers.*'] },
+ *   ]
+ * })
+ * ```
+ */
+export async function ensureJetStreamStreams(options) {
+    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+    const user = options.user ?? process.env.NATS_USER;
+    const pass = options.pass ?? process.env.NATS_PASSWORD;
+    const nc = await connect({
+        servers,
+        ...(user && pass ? { user, pass } : {}),
+    });
+    try {
+        const jsm = await nc.jetstreamManager();
+        for (const { stream, subjects, config } of options.streams) {
+            await ensureStream(jsm, stream, subjects, config);
+        }
+    }
+    finally {
+        await nc.close();
+    }
+}
 /**
  * Ensures durable consumer exists
  */
@@ -223,3 +255,103 @@ export async function consumeJetStreamEvents(options) {
     })();
     return messages;
 }
+/**
+ * Consume CloudEvents from multiple JetStream streams with a single connection.
+ * More efficient than calling consumeJetStreamEvents multiple times.
+ *
+ * @example
+ * ```typescript
+ * await consumeJetStreamStreams({
+ *   streams: ['ORDERS', 'CUSTOMERS'],
+ *   consumer: 'notifications',
+ *   discover: './src/events/**\/*.event.ts',
+ * })
+ * ```
+ */
+export async function consumeJetStreamStreams(options) {
+    const name = options.consumer;
+    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+    const user = options.user ?? process.env.NATS_USER;
+    const pass = options.pass ?? process.env.NATS_PASSWORD;
+    // 1) Discover handlers once (shared across all streams)
+    const handlerConstructors = await discoverHandlers(options.discover);
+    const processedHandlers = handlerConstructors
+        .map(processHandler)
+        .filter((h) => h !== null);
+    const handlerNames = processedHandlers.map((h) => h.name).join(', ');
+    logger.info(`[${name}] discovered ${processedHandlers.length} handler(s): ${handlerNames}`);
+    // 2) Connect to NATS once
+    const nc = await connect({
+        servers,
+        ...(user && pass ? { user, pass } : {}),
+    });
+    logger.info(`[${name}] connected to NATS: ${servers}${user ? ' (authenticated)' : ''}`);
+    // 3) Setup JetStream
+    const jsm = await nc.jetstreamManager();
+    const js = nc.jetstream();
+    const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
+    const idempotencyStore = options.idempotencyStore === false ? null : (options.idempotencyStore ?? getDefaultIdempotencyStore());
+    const idempotencyTtl = options.idempotencyTtl;
+    const { handleMessage, handleUnhandledProcessingError } = createJetStreamMessageProcessor({
+        name,
+        dlqEnabled,
+        options,
+        processedHandlers,
+        decode: (data) => sc.decode(data),
+        logger,
+    });
+    const checkIdempotency = async (msg) => {
+        if (!idempotencyStore)
+            return true;
+        const messageId = `${msg.info.stream}:${msg.seq}`;
+        const shouldProcess = await checkAndMarkProcessed(idempotencyStore, messageId, idempotencyTtl);
+        if (!shouldProcess) {
+            logger.debug(`[${name}] skipping duplicate message: ${messageId}`);
+            msg.ack();
+        }
+        return shouldProcess;
+    };
+    const processSingleMessage = async (msg) => {
+        const shouldProcess = await checkIdempotency(msg);
+        if (!shouldProcess)
+            return;
+        try {
+            const success = await handleMessage(msg);
+            if (success) {
+                msg.ack();
+            }
+            else {
+                msg.nak();
+            }
+        }
+        catch (error) {
+            await handleUnhandledProcessingError(msg, error);
+        }
+    };
+    // 4) Setup consumer for each stream
+    const allMessages = [];
+    for (const stream of options.streams) {
+        const consumerOpts = {
+            ...options,
+            stream,
+        };
+        await ensureConsumer(jsm, stream, name, consumerOpts);
+        const consumer = await js.consumers.get(stream, name);
+        const messages = await consumer.consume({
+            max_messages: options.maxMessages ?? 100,
+        });
+        logger.info(`[${name}] consuming from stream ${stream}`);
+        (async () => {
+            try {
+                for await (const msg of messages) {
+                    await processSingleMessage(msg);
+                }
+            }
+            catch (err) {
+                logger.error(`[${name}] message processing loop crashed for stream ${stream}`, err);
+            }
+        })();
+        allMessages.push(messages);
+    }
+    return allMessages;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",
@@ -11,7 +11,9 @@
     "pubsub",
     "event-driven",
     "typescript",
-    "hono"
+    "hono",
+    "nestjs",
+    "nest"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -22,11 +24,15 @@
   "exports": {
     ".": {
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./transports/nats": {
       "import": "./dist/src/transports/nats/index.js",
-      "types": "./dist/src/transports/nats/index.d.ts"
+      "require": "./dist/src/transports/nats/index.js",
+      "types": "./dist/src/transports/nats/index.d.ts",
+      "default": "./dist/src/transports/nats/index.js"
     }
   },
   "publishConfig": {
@@ -51,7 +57,8 @@
   },
   "peerDependencies": {
     "hono": "^4.6.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@nestjs/common": "^10.0.0"
   },
   "trustedDependencies": [],
   "devDependencies": {