@crossdelta/cloudevents 0.1.7 → 0.1.8

package/README.md

@@ -1,15 +1,38 @@
 # @crossdelta/cloudevents
 
-CloudEvents toolkit for TypeScript. Handler discovery, DLQ-safe processing, NATS streaming, and optional Hono middleware.
+[![npm version](https://img.shields.io/npm/v/@crossdelta/cloudevents.svg)](https://www.npmjs.com/package/@crossdelta/cloudevents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-## Features
+A TypeScript toolkit for [CloudEvents](https://cloudevents.io/) over [NATS](https://nats.io/).
 
-- Automatic handler discovery for `*.event.(ts|js)` files
-- CloudEvents parsing (structured, binary, Pub/Sub push, raw)
-- DLQ-safe mode with quarantine for invalid messages
-- Zod validation with optional safe-parse fallback
-- NATS publish & consume support
-- Google Pub/Sub support (optional dependency)
+Publish events from one service, consume them in another — with automatic handler discovery, type-safe validation, and guaranteed delivery via JetStream.
+
+```
+┌─────────────────┐       NATS        ┌─────────────────┐
+│  orders-service │ ──── publish ───► │  JetStream      │
+└─────────────────┘    CloudEvent     │  (persistent)   │
+                                      └────────┬────────┘
+                                               │
+                       ┌───────────────────────┼───────────────────────┐
+                       ▼                       ▼                       ▼
+              ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+              │  notifications  │     │  billing        │     │  analytics      │
+              │  service        │     │  service        │     │  service        │
+              └─────────────────┘     └─────────────────┘     └─────────────────┘
+                   consume               consume                  consume
+```
+
+## Why this library?
+
+Event-driven microservices are hard: messages get lost when services restart, handlers are scattered across files, validation is inconsistent.
+
+| Feature | Benefit |
+|---------|---------|
+| 🔍 **Auto-discovery** | Drop a `*.event.ts` file, it's registered automatically |
+| 🛡️ **Type-safe handlers** | Zod schemas ensure runtime validation matches TypeScript |
+| 🔄 **JetStream persistence** | Messages survive restarts, get retried on failure |
+| 🏥 **DLQ-safe processing** | Invalid messages are quarantined, not lost |
 
 ## Installation
 
@@ -17,79 +40,238 @@ CloudEvents toolkit for TypeScript. Handler discovery, DLQ-safe processing, NATS
 bun add @crossdelta/cloudevents
 ```
 
-### Optional: Google Pub/Sub
+## Getting Started
 
-For Pub/Sub publishing, install the optional dependency:
+A minimal example: `orders-service` publishes an event, `notifications-service` consumes it.
 
-```bash
-bun add @google-cloud/pubsub
-```
+### 1. Publish an Event (orders-service)
+
+```typescript
+// orders-service/src/index.ts
+import { publishNatsEvent } from '@crossdelta/cloudevents'
 
-## Quick Start
+// When an order is created...
+await publishNatsEvent({
+  type: 'com.acme.orders.created',
+  source: '/orders-service',
+  data: {
+    orderId: 'ord_123',
+    customerId: 'cust_456',
+    total: 99.99,
+  },
+})
+```
 
-### Define a handler
+### 2. Define a Handler (notifications-service)
 
 ```typescript
+// notifications-service/src/handlers/order-created.event.ts
 import { z } from 'zod'
-import { eventSchema, handleEvent } from '@crossdelta/cloudevents'
+import { handleEvent } from '@crossdelta/cloudevents'
 
-const CustomerCreatedSchema = eventSchema({
-  type: z.literal('customer.created'),
-  payload: z.object({
-    id: z.string(),
-    email: z.string().email(),
+export default handleEvent({
+  type: 'com.acme.orders.created',
+  schema: z.object({
+    orderId: z.string(),
+    customerId: z.string(),
+    total: z.number(),
   }),
+  async handle(data) {
+    console.log(`📧 Sending confirmation for order ${data.orderId}`)
+    // Send email, push notification, etc.
+  },
 })
+```
 
-export const CustomerCreatedHandler = handleEvent(CustomerCreatedSchema, async ({ payload }) => {
-  await provisionAccount(payload)
+### 3. Start Consuming (notifications-service)
+
+```typescript
+// notifications-service/src/index.ts
+import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
+
+await consumeJetStreamEvents({
+  stream: 'ORDERS',
+  subjects: ['com.acme.orders.>'],
+  consumer: 'notifications-service',
+  discover: './src/handlers/**/*.event.ts',  // Auto-discovers handlers
 })
+
+console.log('🎧 Listening for order events...')
 ```
 
-### Register middleware
+**That's it.** The handler is discovered automatically, events are persisted in JetStream, and failed messages are retried.
+
+## Consuming Events
+
+### NATS Core (Fire & Forget)
+
+For high-throughput scenarios where occasional message loss is acceptable:
 
 ```typescript
-import { Hono } from 'hono'
-import { cloudEvents } from '@crossdelta/cloudevents'
+import { consumeNatsEvents } from '@crossdelta/cloudevents'
 
-const app = new Hono()
+await consumeNatsEvents({
+  subject: 'telemetry.>',
+  discover: './src/handlers/**/*.event.ts',
+})
+```
 
-app.use('/events', cloudEvents({
-  discover: 'src/events/**/*.event.{ts,js}',
-}))
+### NATS JetStream (Guaranteed Delivery)
+
+For critical business events that must not be lost:
+
+```typescript
+import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
+
+await consumeJetStreamEvents({
+  // Stream configuration
+  stream: 'ORDERS',
+  subjects: ['orders.>'],
+  
+  // Consumer configuration
+  consumer: 'billing-service',
+  discover: './src/handlers/**/*.event.ts',
+  
+  // Optional: Stream settings
+  streamConfig: {
+    maxAge: 7 * 24 * 60 * 60 * 1_000_000_000, // 7 days retention
+    maxBytes: 1024 * 1024 * 1024,              // 1 GB max
+    numReplicas: 3,                            // For HA clusters
+  },
+  
+  // Optional: Consumer settings
+  ackWait: 30_000,   // 30s to process before retry
+  maxDeliver: 5,     // Max retry attempts
+  startFrom: 'all',  // 'new' | 'all' | 'last' | Date
+})
+```
+
+## Handler Patterns
+
+### Data-Only Schema (Recommended)
+
+The simplest pattern — just validate the `data` field:
+
+```typescript
+export default handleEvent({
+  type: 'com.example.users.created',
+  schema: z.object({
+    userId: z.string().uuid(),
+    email: z.string().email(),
+  }),
+  async handle(data) {
+    // data is typed as { userId: string, email: string }
+  },
+})
+```
+
+### Full CloudEvent Schema
+
+When you need access to CloudEvent metadata:
+
+```typescript
+export default handleEvent({
+  type: 'com.example.orders.shipped',
+  schema: z.object({
+    data: z.object({
+      orderId: z.string(),
+      trackingNumber: z.string(),
+    }),
+    source: z.string(),
+    subject: z.string().optional(),
+  }),
+  async handle(event) {
+    // event.data, event.source, event.subject all available
+  },
+})
+```
+
+### Conditional Matching
+
+Process only specific events:
+
+```typescript
+export default handleEvent({
+  type: 'com.example.orders.*',
+  schema: OrderSchema,
+  match: (event) => event.data.region === 'EU',
+  async handle(data) {
+    // Only EU orders
+  },
+})
 ```
 
 ## Publishing
 
+### To NATS
+
 ```typescript
-import { publishNatsEvent } from '@crossdelta/cloudevents'
+import { publishNatsEvent, publishNatsRawEvent } from '@crossdelta/cloudevents'
 
-await publishNatsEvent('orders.placed', OrderPlacedSchema, {
-  payload: { id: 'ord_42', total: 149.9 },
+// Structured CloudEvent
+await publishNatsEvent({
+  type: 'com.example.orders.created',
+  source: '/orders-service',
+  subject: 'order-123',
+  data: { orderId: '123', total: 99.99 },
+})
+
+// Raw data (auto-wrapped in CloudEvent)
+await publishNatsRawEvent('orders.created', {
+  orderId: '123',
+  total: 99.99,
 })
 ```
 
-## Consuming from NATS
+### To Google Pub/Sub
 
 ```typescript
-import { consumeNatsEvents } from '@crossdelta/cloudevents/transports/nats'
+import { publishEvent } from '@crossdelta/cloudevents'
 
-await consumeNatsEvents({
-  servers: process.env.NATS_URL,
-  subject: 'orders.placed',
-  discover: 'dist/events/*.event.js',
-  consumerName: 'orders-api',
+await publishEvent('orders-topic', {
+  type: 'com.example.orders.created',
+  data: { orderId: '123' },
 })
 ```
 
-## API
+## Hono Middleware
+
+For HTTP-based event ingestion:
+
+```typescript
+import { Hono } from 'hono'
+import { cloudEvents } from '@crossdelta/cloudevents'
+
+const app = new Hono()
+
+app.use('/events', cloudEvents({
+  discover: 'src/handlers/**/*.event.ts',
+  dlqEnabled: true,
+}))
+```
+
+## API Reference
 
 | Function | Description |
 |----------|-------------|
-| `cloudEvents(options)` | Hono middleware with discovery and DLQ-safe semantics |
-| `eventSchema(schema)` | Wraps a Zod schema with `type` literal |
-| `handleEvent(schema, handler)` | Creates discovery-ready handler |
-| `publishNatsEvent` / `publishNatsRawEvent` | Publish to NATS |
-| `publishEvent` / `publishRawEvent` | Publish to Google Pub/Sub (requires optional dep) |
-| `consumeNatsEvents` | Subscribe to NATS and execute handlers |
-| `clearHandlerCache()` | Reset discovery cache |
+| `handleEvent(config)` | Create a discoverable event handler |
+| `consumeJetStreamEvents(options)` | Subscribe with guaranteed delivery |
+| `consumeNatsEvents(options)` | Subscribe with fire-and-forget |
+| `publishNatsEvent(event)` | Publish structured CloudEvent to NATS |
+| `publishNatsRawEvent(subject, data)` | Publish raw data to NATS |
+| `cloudEvents(options)` | Hono middleware for HTTP ingestion |
+| `clearHandlerCache()` | Reset handler discovery cache |
+
+## Why JetStream?
+
+| Scenario | Core NATS | JetStream |
+|----------|-----------|-----------|
+| Service restarts | ❌ Messages lost | ✅ Messages replayed |
+| Handler crashes | ❌ Message lost | ✅ Auto-retry with backoff |
+| Multiple consumers | ❌ All receive same msg | ✅ Load balanced |
+| Message history | ❌ None | ✅ Configurable retention |
+| Exactly-once | ❌ At-most-once | ✅ With deduplication |
+
+## License
+
+MIT

package/dist/src/domain/handler-factory.js

@@ -36,11 +36,11 @@ export function handleEvent(schemaOrOptions, handler, eventType) {
         finalEventType = 'unknown.event';
     }
     // Create handler class with proper naming (e.g., "orderboss.orders.created" → "OrdersCreatedHandler")
-    const handlerName = finalEventType
+    const handlerName = `${finalEventType
         .split('.')
         .slice(-2) // Take last 2 segments (e.g., ["orders", "created"])
         .map(s => s.charAt(0).toUpperCase() + s.slice(1)) // Capitalize
-        .join('') + 'Handler';
+        .join('')}Handler`;
     const HandlerClass = class extends Object {
         static __eventarcMetadata = {
             schema,

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

@@ -0,0 +1,44 @@
+/**
+ * Shared message processing logic for NATS Core and JetStream consumers.
+ * Abstracts CloudEvent parsing, handler matching, validation, and execution.
+ */
+import type { CloudEventV1 } from 'cloudevents';
+import type { EnrichedEvent } from '../../domain';
+import { createProcessingContext, type DlqOptions } from '../../processing/dlq-safe';
+import type { ProcessedHandler } from '../../processing/handler-cache';
+export interface LoggerLike {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+}
+export interface BaseMessageProcessorDeps {
+    name: string;
+    dlqEnabled: boolean;
+    options: DlqOptions;
+    processedHandlers: ProcessedHandler[];
+    decode: (data: Uint8Array) => string;
+    logger: LoggerLike;
+}
+export type ProcessingContext = ReturnType<typeof createProcessingContext>;
+export type ParseResult<T> = {
+    ok: true;
+    cloudEvent: CloudEventV1<unknown>;
+    enriched: EnrichedEvent<unknown>;
+} | {
+    ok: false;
+    error: unknown;
+    context: ProcessingContext;
+    rawMessage: T;
+};
+/**
+ * Creates shared message processing utilities
+ */
+export declare function createBaseMessageProcessor(deps: BaseMessageProcessorDeps): {
+    toEnrichedEvent: (ce: CloudEventV1<unknown>) => EnrichedEvent<unknown>;
+    createContext: (event: EnrichedEvent<unknown>, ce?: CloudEventV1<unknown>) => import("../../processing").ProcessingContext;
+    parseCloudEvent: (data: Uint8Array) => CloudEventV1<unknown>;
+    findHandler: (event: EnrichedEvent<unknown>) => ProcessedHandler | undefined;
+    processEvent: (cloudEvent: CloudEventV1<unknown>, enriched: EnrichedEvent<unknown>) => Promise<boolean>;
+    handleParseError: (error: unknown, context: ProcessingContext, redeliveryCount?: number) => Promise<boolean>;
+    handleUnhandledError: (error: unknown, context: ProcessingContext, ackFn?: () => void) => Promise<void>;
+};

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

@@ -0,0 +1,107 @@
+/**
+ * Shared message processing logic for NATS Core and JetStream consumers.
+ * Abstracts CloudEvent parsing, handler matching, validation, and execution.
+ */
+import { createProcessingContext, publishRecoverableError, quarantineMessage, } from '../../processing/dlq-safe';
+import { throwValidationError, validateEventData } from '../../processing/validation';
+/**
+ * Creates shared message processing utilities
+ */
+export function createBaseMessageProcessor(deps) {
+    const { name, dlqEnabled, options, processedHandlers, decode, logger } = deps;
+    const toEnrichedEvent = (ce) => ({
+        eventType: ce.type,
+        source: ce.source,
+        subject: ce.subject,
+        time: ce.time ?? new Date().toISOString(),
+        messageId: ce.id,
+        data: ce.data,
+    });
+    const createContext = (event, ce) => createProcessingContext(event.eventType, event.data, event, ce);
+    const parseCloudEvent = (data) => {
+        return JSON.parse(decode(data));
+    };
+    const findHandler = (event) => processedHandlers.find((handler) => handler.type === event.eventType && (!handler.match || handler.match(event)));
+    const handleMissingHandler = async (context, eventType) => {
+        logger.warn(`[${name}] no handler for event type: ${eventType}`);
+        if (dlqEnabled) {
+            await quarantineMessage(context, 'no_handler', options, new Error(`No handler for event type ${eventType}`));
+        }
+        // Ack - no point in retrying if there's no handler
+        return { handled: true, shouldAck: true };
+    };
+    const handleValidationFailure = async (validationResult, handler, context) => {
+        if (dlqEnabled) {
+            await quarantineMessage(context, 'validation_error', options, validationResult.error);
+            return { handled: true, shouldAck: true };
+        }
+        if (validationResult.shouldSkip) {
+            return { handled: true, shouldAck: true };
+        }
+        // Throw to trigger retry
+        throwValidationError(handler.name, validationResult.error);
+        return { handled: true, shouldAck: false }; // Never reached
+    };
+    const executeHandler = async (handler, enriched, context) => {
+        try {
+            await handler.handle(enriched.data, enriched);
+            return { success: true };
+        }
+        catch (error) {
+            if (dlqEnabled) {
+                await publishRecoverableError(context, error, options);
+                return { success: true }; // Ack after publishing to error topic
+            }
+            throw error; // Will trigger retry
+        }
+    };
+    /**
+     * Process a parsed CloudEvent message
+     * @returns true if message was handled successfully (should ack), false for retry (should nak)
+     */
+    const processEvent = async (cloudEvent, enriched) => {
+        const context = createContext(enriched, cloudEvent);
+        const handler = findHandler(enriched);
+        if (!handler) {
+            const result = await handleMissingHandler(context, enriched.eventType);
+            return result.shouldAck;
+        }
+        const validationResult = validateEventData(handler, enriched.data);
+        if ('error' in validationResult) {
+            const result = await handleValidationFailure(validationResult, handler, context);
+            return result.shouldAck;
+        }
+        const result = await executeHandler(handler, enriched, context);
+        return result.success;
+    };
+    const handleParseError = async (error, context, redeliveryCount = 0) => {
+        logger.error(`[${name}] failed to parse CloudEvent (attempt ${redeliveryCount + 1})`, error);
+        if (dlqEnabled) {
+            await quarantineMessage(context, 'parse_error', options, error);
+            return true; // Ack after quarantine
+        }
+        // After max retries, ack to prevent infinite loop
+        return redeliveryCount >= 2;
+    };
+    const handleUnhandledError = async (error, context, ackFn) => {
+        logger.error(`[${name}] unhandled processing error`, error);
+        if (dlqEnabled) {
+            try {
+                await quarantineMessage(context, 'unhandled_error', options, error);
+                ackFn?.();
+            }
+            catch (quarantineError) {
+                logger.error(`[${name}] failed to quarantine unhandled error`, quarantineError);
+            }
+        }
+    };
+    return {
+        toEnrichedEvent,
+        createContext,
+        parseCloudEvent,
+        findHandler,
+        processEvent,
+        handleParseError,
+        handleUnhandledError,
+    };
+}

package/dist/src/transports/nats/index.d.ts

@@ -1,2 +1,5 @@
+export * from './base-message-processor';
+export * from './jetstream-consumer';
+export { createJetStreamMessageProcessor, type JetStreamMessageProcessor, type JetStreamMessageProcessorDeps, } from './jetstream-message-processor';
 export * from './nats-consumer';
 export * from './nats-message-processor';

package/dist/src/transports/nats/index.js

@@ -1,2 +1,5 @@
+export * from './base-message-processor';
+export * from './jetstream-consumer';
+export { createJetStreamMessageProcessor, } from './jetstream-message-processor';
 export * from './nats-consumer';
 export * from './nats-message-processor';

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

@@ -0,0 +1,72 @@
+import { type ConsumerMessages } from 'nats';
+import type { CloudEventsOptions } from '../../middlewares/cloudevents-middleware';
+/**
+ * Stream configuration options
+ */
+export interface StreamConfig {
+    /** Maximum age of messages in the stream (ms). @default 7 days */
+    maxAge?: number;
+    /** Maximum size of the stream in bytes. @default 1GB */
+    maxBytes?: number;
+    /** Number of replicas. @default 1 */
+    replicas?: number;
+}
+/**
+ * JetStream consumer configuration
+ */
+export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    /** NATS server URL. Defaults to NATS_URL env or nats://localhost:4222 */
+    servers?: string;
+    /** JetStream stream name. Will be auto-created if it doesn't exist */
+    stream: string;
+    /** Subjects to bind to the stream (e.g., ['orders.>', 'payments.>']) */
+    subjects: string[];
+    /** Durable consumer name. Required for persistence across restarts */
+    consumer: string;
+    /** Glob pattern to discover event handlers */
+    discover: string;
+    /**
+     * Where to start consuming from on first subscription.
+     * @default 'new' - Only new messages
+     * Options: 'all' | 'new' | 'last' | Date
+     */
+    startFrom?: 'all' | 'new' | 'last' | Date;
+    /**
+     * Max number of messages to buffer for processing
+     * @default 100
+     */
+    maxMessages?: number;
+    /**
+     * Ack wait timeout in milliseconds before message is redelivered
+     * @default 30000 (30 seconds)
+     */
+    ackWait?: number;
+    /**
+     * Max redelivery attempts before message goes to DLQ
+     * @default 3
+     */
+    maxDeliver?: number;
+    /** Stream configuration (only used when auto-creating) */
+    streamConfig?: StreamConfig;
+}
+/**
+ * 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/handlers/**\/*.event.ts',
+ * })
+ * ```
+ */
+export declare function consumeJetStreamEvents(options: JetStreamConsumerOptions): Promise<ConsumerMessages>;

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

@@ -0,0 +1,187 @@
+import { AckPolicy, connect, DeliverPolicy, ReplayPolicy, RetentionPolicy, StorageType, StringCodec, } from 'nats';
+import { discoverHandlers } from '../../domain';
+import { logger } from '../../infrastructure/logging';
+import { processHandler } from '../../processing/handler-cache';
+import { createJetStreamMessageProcessor } from './jetstream-message-processor';
+const sc = StringCodec();
+// Use globalThis to persist across hot-reloads
+const JETSTREAM_REGISTRY_KEY = '__crossdelta_jetstream_consumers__';
+function getJetStreamRegistry() {
+    if (!globalThis[JETSTREAM_REGISTRY_KEY]) {
+        ;
+        globalThis[JETSTREAM_REGISTRY_KEY] = new Map();
+    }
+    return globalThis[JETSTREAM_REGISTRY_KEY];
+}
+// 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 stream exists with the given configuration
+ */
+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: RetentionPolicy.Limits,
+            storage: StorageType.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 durable consumer exists
+ */
+async function ensureConsumer(jsm, streamName, consumerName, options) {
+    const deliverPolicy = (() => {
+        switch (options.startFrom) {
+            case 'all':
+                return DeliverPolicy.All;
+            case 'last':
+                return DeliverPolicy.Last;
+            default:
+                return DeliverPolicy.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: AckPolicy.Explicit,
+            deliver_policy: optStartTime ? DeliverPolicy.StartTime : deliverPolicy,
+            opt_start_time: optStartTime?.toISOString(),
+            replay_policy: ReplayPolicy.Instant,
+            ack_wait: (options.ackWait ?? 30_000) * 1_000_000, // Convert to nanoseconds
+            max_deliver: options.maxDeliver ?? 3,
+        });
+        logger.info(`[jetstream] created durable consumer ${consumerName} on stream ${streamName}`);
+    }
+}
+/**
+ * Cleanup function to close a JetStream consumer
+ */
+async function cleanupJetStreamConsumer(name) {
+    const registry = getJetStreamRegistry();
+    const consumer = registry.get(name);
+    if (consumer) {
+        logger.info(`[${name}] cleaning up JetStream consumer...`);
+        consumer.abortController.abort();
+        await consumer.messages.close();
+        await consumer.connection.drain();
+        registry.delete(name);
+    }
+}
+/**
+ * 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/handlers/**\/*.event.ts',
+ * })
+ * ```
+ */
+export async function consumeJetStreamEvents(options) {
+    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+    const name = options.consumer;
+    // Cleanup existing consumer (handles hot-reload)
+    await cleanupJetStreamConsumer(name);
+    // 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 });
+    logger.info(`[${name}] connected to NATS: ${servers}`);
+    // 3) Setup JetStream
+    const jsm = await nc.jetstreamManager();
+    const js = nc.jetstream();
+    // 4) Ensure stream exists
+    await ensureStream(jsm, options.stream, options.subjects, options.streamConfig);
+    // 5) Ensure durable consumer exists
+    await ensureConsumer(jsm, options.stream, name, options);
+    // 6) 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}`);
+    // Track for cleanup
+    const abortController = new AbortController();
+    getJetStreamRegistry().set(name, { messages, connection: nc, abortController });
+    const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
+    const { handleMessage, handleUnhandledProcessingError } = createJetStreamMessageProcessor({
+        name,
+        dlqEnabled,
+        options,
+        processedHandlers,
+        decode: (data) => sc.decode(data),
+        logger,
+    });
+    // Process messages
+    const processMessages = async () => {
+        for await (const msg of messages) {
+            if (abortController.signal.aborted)
+                break;
+            try {
+                const success = await handleMessage(msg);
+                if (success) {
+                    msg.ack();
+                }
+                else {
+                    // Handler returned false, negative ack for retry
+                    msg.nak();
+                }
+            }
+            catch (error) {
+                await handleUnhandledProcessingError(msg, error);
+                // Don't ack - message will be redelivered after ack_wait
+            }
+        }
+    };
+    processMessages().catch((err) => {
+        if (!abortController.signal.aborted) {
+            logger.error(`[${name}] message processing loop crashed`, err);
+        }
+    });
+    return messages;
+}

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

@@ -0,0 +1,9 @@
+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/src/transports/nats/jetstream-message-processor.js

@@ -0,0 +1,32 @@
+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/src/transports/nats/nats-message-processor.d.ts

@@ -1,22 +1,11 @@
 import type { Msg } from 'nats';
-import { type DlqOptions } from '../../processing/dlq-safe';
-import type { ProcessedHandler } from '../../processing/handler-cache';
-export interface LoggerLike {
-    info(message: string, meta?: unknown): void;
-    warn(message: string, meta?: unknown): void;
-    error(message: string, meta?: unknown): void;
-}
-export interface NatsMessageProcessorDeps {
-    name: string;
+import { type BaseMessageProcessorDeps, type LoggerLike } from './base-message-processor';
+export type { LoggerLike };
+export interface NatsMessageProcessorDeps extends BaseMessageProcessorDeps {
     subject: string;
-    dlqEnabled: boolean;
-    options: DlqOptions;
-    processedHandlers: ProcessedHandler[];
-    decode: (data: Uint8Array) => string;
-    logger: LoggerLike;
 }
 export interface NatsMessageProcessor {
     handleMessage(msg: Msg): Promise<void>;
     handleUnhandledProcessingError(msg: Msg, error: unknown): Promise<void>;
 }
-export declare const createNatsMessageProcessor: ({ name, subject, dlqEnabled, options, processedHandlers, decode, logger, }: NatsMessageProcessorDeps) => NatsMessageProcessor;
+export declare const createNatsMessageProcessor: (deps: NatsMessageProcessorDeps) => NatsMessageProcessor;

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

@@ -1,14 +1,8 @@
-import { createProcessingContext, publishRecoverableError, quarantineMessage, } from '../../processing/dlq-safe';
-import { throwValidationError, validateEventData } from '../../processing/validation';
-export const createNatsMessageProcessor = ({ name, subject, dlqEnabled, options, processedHandlers, decode, logger, }) => {
-    const toEnrichedEvent = (ce) => ({
-        eventType: ce.type,
-        source: ce.source,
-        subject: ce.subject,
-        time: ce.time ?? new Date().toISOString(),
-        messageId: ce.id,
-        data: ce.data,
-    });
+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}`,
@@ -17,79 +11,22 @@ export const createNatsMessageProcessor = ({ name, subject, dlqEnabled, options,
         messageId: msg.headers?.get('Nats-Msg-Id') ?? 'unknown',
         data: decode(msg.data),
     });
-    const createContext = (event, ce) => createProcessingContext(event.eventType, event.data, event, ce);
-    const safeParseMessage = (msg) => {
-        try {
-            const cloudEvent = JSON.parse(decode(msg.data));
-            return { ok: true, cloudEvent, enriched: toEnrichedEvent(cloudEvent) };
-        }
-        catch (error) {
-            return { ok: false, error, context: createContext(toUnknownContext(msg)) };
-        }
-    };
-    const findHandler = (event) => processedHandlers.find((handler) => handler.type === event.eventType && (!handler.match || handler.match(event)));
-    const handleParseFailure = async ({ context, error }) => {
-        logger.error(`[${name}] failed to parse CloudEvent payload`, error);
-        if (!dlqEnabled)
-            return;
-        await quarantineMessage(context, 'parse_error', options, error);
-    };
-    const handleMissingHandler = async (context, eventType) => {
-        logger.warn(`[${name}] no handler for event type ${eventType}`);
-        if (!dlqEnabled)
-            return;
-        await quarantineMessage(context, 'no_handler', options, new Error(`No handler for event type ${eventType}`));
-    };
-    const handleValidationFailure = async (validationResult, handler, context) => {
-        if (dlqEnabled) {
-            await quarantineMessage(context, 'validation_error', options, validationResult.error);
-            return;
-        }
-        if (validationResult.shouldSkip)
-            return;
-        throwValidationError(handler.name, validationResult.error);
-    };
-    const executeHandler = async (handler, enriched, context) => {
+    const handleMessage = async (msg) => {
         try {
-            await handler.handle(enriched.data, enriched);
+            const cloudEvent = base.parseCloudEvent(msg.data);
+            const enriched = base.toEnrichedEvent(cloudEvent);
+            await base.processEvent(cloudEvent, enriched);
         }
         catch (error) {
-            if (!dlqEnabled)
-                throw error;
-            await publishRecoverableError(context, error, options);
-        }
-    };
-    const handleMessage = async (msg) => {
-        const parseResult = safeParseMessage(msg);
-        if (!parseResult.ok) {
-            await handleParseFailure(parseResult);
-            return;
-        }
-        const { cloudEvent, enriched } = parseResult;
-        const processingContext = createContext(enriched, cloudEvent);
-        const handler = findHandler(enriched);
-        if (!handler) {
-            await handleMissingHandler(processingContext, enriched.eventType);
-            return;
+            const unknownCtx = toUnknownContext(msg);
+            const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
+            await base.handleParseError(error, context);
         }
-        const validationResult = validateEventData(handler, enriched.data);
-        if ('error' in validationResult) {
-            await handleValidationFailure(validationResult, handler, processingContext);
-            return;
-        }
-        await executeHandler(handler, enriched, processingContext);
     };
     const handleUnhandledProcessingError = async (msg, error) => {
-        logger.error(`[${name}] failed to handle NATS message`, error);
-        if (!dlqEnabled) {
-            return;
-        }
-        try {
-            await quarantineMessage(createContext(toUnknownContext(msg)), 'unhandled_error', options, error);
-        }
-        catch (quarantineError) {
-            logger.error(`[${name}] failed to quarantine unhandled error`, quarantineError);
-        }
+        const unknownCtx = toUnknownContext(msg);
+        const context = createProcessingContext('unknown', decode(msg.data), unknownCtx, undefined);
+        await base.handleUnhandledError(error, context);
     };
     return { handleMessage, handleUnhandledProcessingError };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CloudEvents toolkit for TypeScript - handler discovery, DLQ-safe processing, NATS streaming",
   "author": "crossdelta",
   "license": "MIT",