@crossdelta/cloudevents 0.5.6 → 0.6.0

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

@@ -1,367 +0,0 @@
-import { connect, StringCodec, } from 'nats';
-import { discoverHandlers } from '../../domain';
-// String literals matching NATS enum values (enums not reliably exported in CI/Bun)
-// AckPolicy.Explicit = "explicit", DeliverPolicy.All/Last/New/StartTime, RetentionPolicy.Limits = "limits", StorageType.File = "file"
-const ACK_EXPLICIT = 'explicit';
-const DELIVER_ALL = 'all';
-const DELIVER_LAST = 'last';
-const DELIVER_NEW = 'new';
-const DELIVER_START_TIME = 'by_start_time';
-const RETENTION_LIMITS = 'limits';
-const STORAGE_FILE = 'file';
-import { logger } from '../../infrastructure/logging';
-import { processHandler } from '../../processing/handler-cache';
-import { checkAndMarkProcessed, getDefaultIdempotencyStore } from '../../processing/idempotency';
-import { createJetStreamMessageProcessor } from './jetstream-message-processor';
-const sc = StringCodec();
-// Default stream configuration
-const DEFAULT_STREAM_CONFIG = {
-    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days in ms
-    maxBytes: 1024 * 1024 * 1024, // 1 GB
-    replicas: 1,
-};
-/**
- * Ensures a JetStream stream exists with the given configuration.
- * This is typically called once during application startup or in infrastructure setup.
- *
- * @example
- * ```typescript
- * // In infrastructure/setup code:
- * await ensureJetStreamStream({
- *   stream: 'ORDERS',
- *   subjects: ['orders.>'],
- *   config: {
- *     maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
- *     replicas: 3
- *   }
- * })
- * ```
- */
-export async function ensureJetStreamStream(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();
-        await ensureStream(jsm, options.stream, options.subjects, options.config);
-    }
-    finally {
-        await nc.close();
-    }
-}
-/**
- * Ensures stream exists with the given configuration (internal helper)
- */
-async function ensureStream(jsm, name, subjects, config = {}) {
-    const streamConfig = { ...DEFAULT_STREAM_CONFIG, ...config };
-    try {
-        const stream = await jsm.streams.info(name);
-        // Update subjects if needed
-        const existingSubjects = new Set(stream.config.subjects);
-        const newSubjects = subjects.filter((s) => !existingSubjects.has(s));
-        if (newSubjects.length > 0) {
-            await jsm.streams.update(name, {
-                subjects: [...stream.config.subjects, ...newSubjects],
-            });
-            logger.info(`[jetstream] updated stream ${name} with subjects: ${newSubjects.join(', ')}`);
-        }
-    }
-    catch {
-        // Stream doesn't exist, create it
-        await jsm.streams.add({
-            name,
-            subjects,
-            retention: RETENTION_LIMITS,
-            storage: STORAGE_FILE,
-            max_age: streamConfig.maxAge * 1_000_000, // Convert ms to nanoseconds
-            max_bytes: streamConfig.maxBytes,
-            num_replicas: streamConfig.replicas,
-        });
-        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
- */
-async function ensureConsumer(jsm, streamName, consumerName, options) {
-    const deliverPolicy = (() => {
-        switch (options.startFrom) {
-            case 'all':
-                return DELIVER_ALL;
-            case 'last':
-                return DELIVER_LAST;
-            default:
-                return DELIVER_NEW;
-        }
-    })();
-    const optStartTime = options.startFrom instanceof Date ? options.startFrom : undefined;
-    try {
-        await jsm.consumers.info(streamName, consumerName);
-        // Consumer exists, no update needed for durable consumers
-    }
-    catch {
-        // Consumer doesn't exist, create it
-        await jsm.consumers.add(streamName, {
-            durable_name: consumerName,
-            ack_policy: ACK_EXPLICIT,
-            deliver_policy: optStartTime ? DELIVER_START_TIME : deliverPolicy,
-            opt_start_time: optStartTime?.toISOString(),
-            // replay_policy defaults to 'instant', no need to specify explicitly
-            ack_wait: (options.ackWait ?? 30_000) * 1_000_000, // Convert to nanoseconds
-            max_deliver: options.maxDeliver ?? 3,
-            // Filter subjects at consumer level (optional)
-            filter_subjects: options.filterSubjects,
-        });
-        logger.info(`[jetstream] created durable consumer ${consumerName} on stream ${streamName}`);
-    }
-}
-/**
- * Consume CloudEvents from NATS JetStream with persistence and guaranteed delivery.
- *
- * Features:
- * - Automatic stream and consumer creation
- * - Durable subscriptions (survive restarts)
- * - Automatic acknowledgments on successful processing
- * - Configurable retry with max redelivery
- * - Dead letter queue support
- *
- * @example
- * ```typescript
- * await consumeJetStreamEvents({
- *   stream: 'ORDERS',
- *   subjects: ['orders.>'],
- *   consumer: 'notifications',
- *   discover: `./src/events/**\/*.handler.ts`,
- * })
- * ```
- */
-export async function consumeJetStreamEvents(options) {
-    const name = options.consumer;
-    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
-    // Authentication (from options or env vars)
-    const user = options.user ?? process.env.NATS_USER;
-    const pass = options.pass ?? process.env.NATS_PASSWORD;
-    // 1) Discover handlers
-    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
-    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();
-    // 4) Ensure durable consumer exists (stream must already exist)
-    await ensureConsumer(jsm, options.stream, name, options);
-    // 5) Get consumer and start consuming
-    const consumer = await js.consumers.get(options.stream, name);
-    const messages = await consumer.consume({
-        max_messages: options.maxMessages ?? 100,
-    });
-    logger.info(`[${name}] consuming from stream ${options.stream}`);
-    const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
-    // Setup idempotency store
-    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,
-    });
-    // Check idempotency and skip duplicates
-    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;
-    };
-    // Process a single message
-    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);
-        }
-    };
-    (async () => {
-        try {
-            for await (const msg of messages) {
-                await processSingleMessage(msg);
-            }
-        }
-        catch (err) {
-            logger.error(`[${name}] message processing loop crashed`, err);
-        }
-    })();
-    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/**\/*.handler.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;
-}
-/**
- * Alias for ensureJetStreamStreams - shorter name
- * @see ensureJetStreamStreams
- */
-export const ensureJetStreams = ensureJetStreamStreams;
-/**
- * Alias for consumeJetStreamStreams - shorter name
- * @see consumeJetStreamStreams
- */
-export const consumeJetStreams = consumeJetStreamStreams;

package/dist/transports/nats/jetstream-message-processor.d.ts

@@ -1,9 +0,0 @@
-import type { JsMsg } from 'nats';
-import { type BaseMessageProcessorDeps } from './base-message-processor';
-export type JetStreamMessageProcessorDeps = BaseMessageProcessorDeps;
-export interface JetStreamMessageProcessor {
-    /** Returns true if message was handled successfully (should ack), false for retry (should nak) */
-    handleMessage(msg: JsMsg): Promise<boolean>;
-    handleUnhandledProcessingError(msg: JsMsg, error: unknown): Promise<void>;
-}
-export declare const createJetStreamMessageProcessor: (deps: JetStreamMessageProcessorDeps) => JetStreamMessageProcessor;

package/dist/transports/nats/jetstream-message-processor.js

@@ -1,32 +0,0 @@
-import { createProcessingContext } from '../../processing/dlq-safe';
-import { createBaseMessageProcessor } from './base-message-processor';
-export const createJetStreamMessageProcessor = (deps) => {
-    const { decode } = deps;
-    const base = createBaseMessageProcessor(deps);
-    const toUnknownContext = (msg) => ({
-        eventType: 'unknown',
-        source: `jetstream://${msg.info.stream}`,
-        subject: msg.subject,
-        time: new Date().toISOString(),
-        messageId: `${msg.info.stream}:${msg.seq}`,
-        data: decode(msg.data),
-    });
-    const handleMessage = async (msg) => {
-        try {
-            const cloudEvent = base.parseCloudEvent(msg.data);
-            const enriched = base.toEnrichedEvent(cloudEvent);
-            return base.processEvent(cloudEvent, enriched);
-        }
-        catch (error) {
-            const unknownCtx = toUnknownContext(msg);
-            const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
-            return base.handleParseError(error, context, msg.info.deliveryCount);
-        }
-    };
-    const handleUnhandledProcessingError = async (msg, error) => {
-        const unknownCtx = toUnknownContext(msg);
-        const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
-        await base.handleUnhandledError(error, context, () => msg.ack());
-    };
-    return { handleMessage, handleUnhandledProcessingError };
-};

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

@@ -1,36 +0,0 @@
-import { type Subscription } from 'nats';
-import type { CloudEventsOptions } from '../../middlewares/cloudevents-middleware';
-/**
- * Describes the configuration required to bootstrap the NATS event consumer.
- *
- * @property servers - Optional NATS connection string; defaults to `NATS_URL` or the local instance.
- * @property subject - NATS subject to subscribe to for incoming events.
- * @property discover - Glob pattern or directory used to discover event handler classes.
- * @property consumerName - Optional identifier appended to log output and the consumer name.
- * @property user - Optional NATS username for authentication (can also use `NATS_USER` env var).
- * @property pass - Optional NATS password for authentication (can also use `NATS_PASSWORD` env var).
- * @property quarantineTopic - Optional Pub/Sub topic for quarantining malformed messages when DLQ mode is enabled.
- * @property errorTopic - Optional Pub/Sub topic for recovering handler errors when DLQ mode is enabled.
- * @property projectId - Optional Google Cloud project identifier used for DLQ publishing.
- * @property source - Optional CloudEvent source identifier applied to DLQ messages.
- */
-export interface NatsConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
-    servers?: string;
-    subject: string;
-    discover: string;
-    consumerName?: 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;
-}
-/**
- * Connects to NATS, discovers matching event handlers, and processes incoming CloudEvents.
- *
- * @param options - Consumer configuration describing connection, discovery, and subscription details.
- * @returns The active NATS subscription for the configured subject.
- *
- * When `quarantineTopic` or `errorTopic` is provided, the consumer forwards malformed messages
- * and handler failures to the configured DLQ topics instead of throwing errors.
- */
-export declare function consumeNatsEvents(options: NatsConsumerOptions): Promise<Subscription>;

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

@@ -1,84 +0,0 @@
-import { connect, StringCodec } from 'nats';
-import { discoverHandlers } from '../../domain';
-import { logger } from '../../infrastructure/logging';
-import { processHandler } from '../../processing/handler-cache';
-import { createNatsMessageProcessor } from './nats-message-processor';
-const sc = StringCodec();
-// Use globalThis to persist across hot-reloads
-const CONSUMER_REGISTRY_KEY = '__crossdelta_nats_consumers__';
-function getConsumerRegistry() {
-    if (!globalThis[CONSUMER_REGISTRY_KEY]) {
-        ;
-        globalThis[CONSUMER_REGISTRY_KEY] = new Map();
-    }
-    return globalThis[CONSUMER_REGISTRY_KEY];
-}
-/**
- * Cleanup function to close a consumer by name
- */
-async function cleanupConsumer(name) {
-    const registry = getConsumerRegistry();
-    const consumer = registry.get(name);
-    if (consumer) {
-        logger.info(`[${name}] cleaning up subscription...`);
-        consumer.subscription.unsubscribe();
-        await consumer.connection.drain();
-        registry.delete(name);
-    }
-}
-/**
- * Connects to NATS, discovers matching event handlers, and processes incoming CloudEvents.
- *
- * @param options - Consumer configuration describing connection, discovery, and subscription details.
- * @returns The active NATS subscription for the configured subject.
- *
- * When `quarantineTopic` or `errorTopic` is provided, the consumer forwards malformed messages
- * and handler failures to the configured DLQ topics instead of throwing errors.
- */
-export async function consumeNatsEvents(options) {
-    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
-    const subject = options.subject;
-    const name = options.consumerName ?? `nats-consumer:${subject}`;
-    // Authentication (from options or env vars)
-    const user = options.user ?? process.env.NATS_USER;
-    const pass = options.pass ?? process.env.NATS_PASSWORD;
-    // Cleanup existing consumer with same name (handles hot-reload)
-    await cleanupConsumer(name);
-    // 1) Discover handler classes from *.handler.ts files
-    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
-    const nc = await connect({
-        servers,
-        ...(user && pass ? { user, pass } : {}),
-    });
-    logger.info(`[${name}] connected to NATS: ${servers}${user ? ' (authenticated)' : ''}`);
-    // 3) Subscribe to the subject
-    const sub = nc.subscribe(subject);
-    logger.info(`[${name}] subscribed to subject: ${subject}`);
-    // Track this consumer for cleanup
-    getConsumerRegistry().set(name, { subscription: sub, connection: nc });
-    const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
-    const { handleMessage, handleUnhandledProcessingError } = createNatsMessageProcessor({
-        name,
-        subject,
-        dlqEnabled,
-        options,
-        processedHandlers,
-        decode: (data) => sc.decode(data),
-        logger,
-    });
-    const processSubscription = async () => {
-        for await (const msg of sub) {
-            await handleMessage(msg).catch((error) => handleUnhandledProcessingError(msg, error));
-        }
-    };
-    processSubscription().catch((err) => {
-        logger.error(`[${name}] subscription loop crashed`, err);
-    });
-    return sub;
-}

package/dist/transports/nats/nats-message-processor.d.ts

@@ -1,11 +0,0 @@
-import type { Msg } from 'nats';
-import { type BaseMessageProcessorDeps, type LoggerLike } from './base-message-processor';
-export type { LoggerLike };
-export interface NatsMessageProcessorDeps extends BaseMessageProcessorDeps {
-    subject: string;
-}
-export interface NatsMessageProcessor {
-    handleMessage(msg: Msg): Promise<void>;
-    handleUnhandledProcessingError(msg: Msg, error: unknown): Promise<void>;
-}
-export declare const createNatsMessageProcessor: (deps: NatsMessageProcessorDeps) => NatsMessageProcessor;

package/dist/transports/nats/nats-message-processor.js

@@ -1,32 +0,0 @@
-import { createProcessingContext } from '../../processing/dlq-safe';
-import { createBaseMessageProcessor } from './base-message-processor';
-export const createNatsMessageProcessor = (deps) => {
-    const { subject, decode } = deps;
-    const base = createBaseMessageProcessor(deps);
-    const toUnknownContext = (msg) => ({
-        eventType: 'unknown',
-        source: `nats://${subject}`,
-        subject,
-        time: new Date().toISOString(),
-        messageId: msg.headers?.get('Nats-Msg-Id') ?? 'unknown',
-        data: decode(msg.data),
-    });
-    const handleMessage = async (msg) => {
-        try {
-            const cloudEvent = base.parseCloudEvent(msg.data);
-            const enriched = base.toEnrichedEvent(cloudEvent);
-            await base.processEvent(cloudEvent, enriched);
-        }
-        catch (error) {
-            const unknownCtx = toUnknownContext(msg);
-            const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
-            await base.handleParseError(error, context);
-        }
-    };
-    const handleUnhandledProcessingError = async (msg, error) => {
-        const unknownCtx = toUnknownContext(msg);
-        const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
-        await base.handleUnhandledError(error, context);
-    };
-    return { handleMessage, handleUnhandledProcessingError };
-};