@crossdelta/cloudevents 0.3.3 → 0.4.0

package/README.md

@@ -29,13 +29,14 @@ bun add @crossdelta/cloudevents zod@4
 
 ## Quick Start
 
-**1. Create an event handler** (`src/handlers/order-created.event.ts`):
+**1. Create an event handler** (`src/events/order-created.event.ts`):
 
 ```typescript
 import { handleEvent } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-const OrderCreatedSchema = z.object({
+// Export schema for mock generation
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   total: z.number(),
 })
@@ -54,20 +55,30 @@ export default handleEvent(
 )
 ```
 
-**2. Start consuming:**
+**2. Ensure stream exists** (once, during setup):
+
+```typescript
+import { ensureJetStreamStream } from '@crossdelta/cloudevents'
+
+await ensureJetStreamStream({
+  stream: 'ORDERS',
+  subjects: ['orders.*'],
+})
+```
+
+**3. Start consuming:**
 
 ```typescript
 import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
 
 await consumeJetStreamEvents({
-  stream: 'ORDERS',                         // Auto-created if not exists
-  subjects: ['orders.*'],
+  stream: 'ORDERS',
   consumer: 'my-service',
-  discover: './src/handlers/**/*.event.ts',
+  discover: './src/events/**/*.event.ts',
 })
 ```
 
-**3. Publish from another service:**
+**4. Publish from another service:**
 
 ```typescript
 import { publish } from '@crossdelta/cloudevents'
@@ -118,7 +129,7 @@ export default handleEvent(
 Drop a `*.event.ts` file anywhere — it's auto-registered:
 
 ```typescript
-// src/handlers/user-signup.event.ts
+// src/events/user-signup.event.ts
 import { z } from 'zod'
 
 const UserSignupSchema = z.object({ 
@@ -146,21 +157,38 @@ export default handleEvent(
 await publish('orders.created', orderData)
 ```
 
+### Stream Setup
+
+Create the stream once during infrastructure setup:
+
+```typescript
+import { ensureJetStreamStream } from '@crossdelta/cloudevents'
+
+await ensureJetStreamStream({
+  stream: 'ORDERS',
+  subjects: ['orders.>'],
+  config: {
+    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days retention
+    replicas: 3,                       // For HA
+  }
+})
+```
+
 ### Consuming
 
 ```typescript
 // JetStream (recommended) — persistent, retries, exactly-once
 await consumeJetStreamEvents({
   stream: 'ORDERS',
-  subjects: ['orders.*'],
   consumer: 'billing',
-  discover: './src/handlers/**/*.event.ts',
+  discover: './src/events/**/*.event.ts',
+  filterSubjects: ['orders.created', 'orders.updated'], // Optional: filter at consumer level
 })
 
 // Core NATS — fire-and-forget, simpler
 await consumeNatsEvents({
   subjects: ['notifications.*'],
-  discover: './src/handlers/**/*.event.ts',
+  discover: './src/events/**/*.event.ts',
 })
 ```
 
@@ -176,21 +204,40 @@ NATS_USER=myuser        # optional
 NATS_PASSWORD=mypass    # optional
 ```
 
+### Stream Options
+
+```typescript
+await ensureJetStreamStream({
+  // Required
+  stream: 'ORDERS',
+  subjects: ['orders.>'],
+
+  // Optional
+  servers: 'nats://localhost:4222',
+  config: {
+    maxAge: 7 * 24 * 60 * 60 * 1000,  // Message retention (ms)
+    replicas: 1,                        // Replication factor
+    storage: 'file',                    // 'file' or 'memory'
+    retention: 'limits',                // 'limits', 'interest', or 'workqueue'
+  }
+})
+```
+
 ### Consumer Options
 
 ```typescript
 await consumeJetStreamEvents({
   // Required
   stream: 'ORDERS',
-  subjects: ['orders.*'],
   consumer: 'my-service',
-  discover: './src/handlers/**/*.event.ts',
+  discover: './src/events/**/*.event.ts',
 
   // Optional
   servers: 'nats://localhost:4222',
-  maxDeliver: 5,           // Retry attempts
-  ackWait: 30_000,         // Timeout per attempt (ms)
-  quarantineTopic: 'dlq',  // For poison messages
+  filterSubjects: ['orders.created'],  // Filter specific subjects
+  maxDeliver: 5,                       // Retry attempts
+  ackWait: 30_000,                     // Timeout per attempt (ms)
+  quarantineTopic: 'dlq',              // For poison messages
 })
 ```
 
@@ -198,6 +245,51 @@ await consumeJetStreamEvents({
 
 ## Advanced Features
 
+<details>
+<summary><b>Shared Contracts</b></summary>
+
+When multiple services consume the same event, use `createContract` to create shared event contracts:
+
+```typescript
+// packages/contracts/src/schemas/order-created.schema.ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrderCreatedSchema = z.object({
+  orderId: z.string(),
+  total: z.number(),
+})
+
+export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>
+
+export const OrderCreatedContract = createContract({
+  type: 'orders.created',
+  schema: OrderCreatedSchema,
+})
+```
+
+Then import and use in handlers:
+
+```typescript
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrderCreatedContract } from '@my-org/contracts'
+
+export default handleEvent(
+  OrderCreatedContract,
+  async (data) => {
+    // data is typed as OrderCreatedData
+    console.log(data.orderId)
+  },
+)
+```
+
+Benefits:
+- Single source of truth for event schemas
+- No schema duplication
+- Type safety across services
+
+</details>
+
 <details>
 <summary><b>Multi-Tenancy</b></summary>
 
@@ -270,7 +362,7 @@ import { Hono } from 'hono'
 import { cloudEvents } from '@crossdelta/cloudevents'
 
 const app = new Hono()
-app.use('/events', cloudEvents({ discover: 'src/handlers/**/*.event.ts' }))
+app.use('/events', cloudEvents({ discover: 'src/events/**/*.event.ts' }))
 ```
 
 </details>
@@ -282,6 +374,8 @@ app.use('/events', cloudEvents({ discover: 'src/handlers/**/*.event.ts' }))
 | Function | Purpose |
 |----------|---------|
 | `handleEvent(options, handler)` | Create a handler |
+| `createContract(options)` | Create shared event contract |
+| `ensureJetStreamStream(options)` | Create/update JetStream stream |
 | `consumeJetStreamEvents(options)` | Consume with persistence |
 | `consumeNatsEvents(options)` | Consume fire-and-forget |
 | `publish(type, data)` | Publish event |

package/dist/domain/contract-helper.d.ts

@@ -0,0 +1,34 @@
+import type { ZodTypeAny } from 'zod';
+import type { HandleEventOptions } from './types';
+/**
+ * Creates a type-safe event contract for Advanced Mode
+ *
+ * This helper ensures proper type inference when using contracts
+ * with handleEvent across package boundaries.
+ *
+ * @example
+ * ```typescript
+ * import { createContract } from '@crossdelta/cloudevents'
+ * import { z } from 'zod'
+ *
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   schema: z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }),
+ * })
+ *
+ * // Type is inferred: { orderId: string, total: number }
+ * export type OrderCreatedData = typeof OrderCreatedContract._schema._output
+ * ```
+ */
+export declare function createContract<TSchema extends ZodTypeAny>(options: {
+    type: string;
+    schema: TSchema;
+    match?: HandleEventOptions['match'];
+    safeParse?: boolean;
+    tenantId?: string | string[];
+}): HandleEventOptions<TSchema> & {
+    _schema: TSchema;
+};

package/dist/domain/contract-helper.js

@@ -0,0 +1,29 @@
+/**
+ * Creates a type-safe event contract for Advanced Mode
+ *
+ * This helper ensures proper type inference when using contracts
+ * with handleEvent across package boundaries.
+ *
+ * @example
+ * ```typescript
+ * import { createContract } from '@crossdelta/cloudevents'
+ * import { z } from 'zod'
+ *
+ * export const OrderCreatedContract = createContract({
+ *   type: 'orders.created',
+ *   schema: z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }),
+ * })
+ *
+ * // Type is inferred: { orderId: string, total: number }
+ * export type OrderCreatedData = typeof OrderCreatedContract._schema._output
+ * ```
+ */
+export function createContract(options) {
+    return {
+        ...options,
+        _schema: options.schema,
+    };
+}

package/dist/{src/domain → domain}/discovery.js

@@ -1,4 +1,5 @@
-import { dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { glob } from 'glob';
 import { logger } from '../infrastructure';
@@ -13,17 +14,28 @@ const getSearchDirectories = () => {
     try {
         const currentDir = dirname(fileURLToPath(import.meta.url));
         directories.add(currentDir);
+        // For monorepo tests: also check packages/cloudevents if we're in dist/
+        if (currentDir.includes('/dist/')) {
+            const pkgRoot = currentDir.split('/dist/')[0];
+            if (pkgRoot)
+                directories.add(pkgRoot);
+        }
     }
     catch {
         // Ignore resolution errors; fallback to process.cwd()
     }
-    return [...directories];
+    // Filter out directories that don't exist (e.g., during hot-reload)
+    return [...directories].filter((dir) => existsSync(dir));
 };
 /**
  * Loads and validates handlers from a TypeScript/JavaScript file.
  */
 const loadHandlers = async (filePath, filter) => {
     try {
+        // Check if file exists before import to avoid ENOENT during hot-reload
+        if (!existsSync(filePath)) {
+            return [];
+        }
         const module = await import(filePath);
         return Object.entries(module)
             .filter(([name, handler]) => isValidHandler(handler) && (!filter || filter(name, handler)))
@@ -78,19 +90,47 @@ const expandPatternVariants = (pattern, preferCompiled) => {
     const ordered = preferCompiled ? [...compiledVariants, basePattern] : [basePattern, ...compiledVariants];
     return [...new Set(ordered)];
 };
+/**
+ * Check if a directory path should be scanned (exists and is accessible)
+ */
+const shouldScanDirectory = (basePath, variant) => {
+    if (!existsSync(basePath)) {
+        return false;
+    }
+    // For patterns with directory prefixes like "dist/...", check if prefix dir exists
+    const dirPrefix = variant.match(/^([^*{[]+)\//)?.[1];
+    if (dirPrefix) {
+        const fullDirPath = join(basePath, dirPrefix);
+        return existsSync(fullDirPath);
+    }
+    return true;
+};
 const discoverFiles = async (pattern, basePath, preferCompiled) => {
-    const prefixedPattern = `{src,dist,build,lib,out}/${pattern}`;
+    // Don't add src/dist prefix for test patterns or absolute paths
+    const isTestPattern = pattern.startsWith('test/');
+    const prefixedPattern = isTestPattern ? pattern : `{src,dist,build,lib,out}/${pattern}`;
     const patterns = preferCompiled ? [prefixedPattern, pattern] : [pattern, prefixedPattern];
     const allFiles = [];
     for (const globPattern of patterns) {
         const variants = expandPatternVariants(globPattern, preferCompiled);
         for (const variant of variants) {
             try {
-                const files = await glob(variant, { cwd: basePath, absolute: true });
-                allFiles.push(...files);
+                // Check if directory should be scanned to avoid scandir errors during hot-reload
+                if (!shouldScanDirectory(basePath, variant)) {
+                    continue;
+                }
+                const files = await glob(variant, {
+                    cwd: basePath,
+                    absolute: true,
+                    nodir: true,
+                    windowsPathsNoEscape: true,
+                });
+                // Filter out files that no longer exist (race condition during hot-reload)
+                const existingFiles = files.filter((f) => existsSync(f));
+                allFiles.push(...existingFiles);
             }
             catch {
-                // Ignore errors
+                // Ignore errors silently - directory might have been deleted during hot-reload
             }
         }
     }

package/dist/{src/domain → domain}/handler-factory.d.ts

@@ -5,7 +5,9 @@ import type { HandleEventOptions, HandlerConstructor } from './types';
  * Creates an event handler using the handleEvent pattern
  * Compatible with the new middleware system
  *
- * @example Data-only schema
+ * Supports both inline schemas (Basic Mode) and shared contracts (Advanced Mode).
+ *
+ * @example Basic Mode - Data-only schema inline
  * ```typescript
  * export default handleEvent({
  *   type: 'orderboss.orders.created',
@@ -15,6 +17,15 @@ import type { HandleEventOptions, HandlerConstructor } from './types';
  * })
  * ```
  *
+ * @example Advanced Mode - With shared contract
+ * ```typescript
+ * import { OrderCreatedContract } from '@orderboss/contracts'
+ *
+ * export default handleEvent(OrderCreatedContract, async (data) => {
+ *   console.log('Order created:', data.orderId)
+ * })
+ * ```
+ *
  * @example With tenant filtering
  * ```typescript
  * export default handleEvent({
@@ -26,7 +37,7 @@ import type { HandleEventOptions, HandlerConstructor } from './types';
  * })
  * ```
  */
-export declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | HandleEventOptions<TSchema>, handler: (payload: TSchema['_output'], context?: EventContext) => Promise<void> | void, eventType?: string): HandlerConstructor;
+export declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | HandleEventOptions<TSchema> | HandleEventOptions, handler: (payload: TSchema['_output'], context?: EventContext) => Promise<void> | void, eventType?: string): HandlerConstructor;
 /**
  * Creates an event schema with type inference
  * Automatically enforces the presence of a 'type' field

package/dist/{src/domain → domain}/handler-factory.js

@@ -67,7 +67,9 @@ function combineMatchers(matchers) {
  * Creates an event handler using the handleEvent pattern
  * Compatible with the new middleware system
  *
- * @example Data-only schema
+ * Supports both inline schemas (Basic Mode) and shared contracts (Advanced Mode).
+ *
+ * @example Basic Mode - Data-only schema inline
  * ```typescript
  * export default handleEvent({
  *   type: 'orderboss.orders.created',
@@ -77,6 +79,15 @@ function combineMatchers(matchers) {
  * })
  * ```
  *
+ * @example Advanced Mode - With shared contract
+ * ```typescript
+ * import { OrderCreatedContract } from '@orderboss/contracts'
+ *
+ * export default handleEvent(OrderCreatedContract, async (data) => {
+ *   console.log('Order created:', data.orderId)
+ * })
+ * ```
+ *
  * @example With tenant filtering
  * ```typescript
  * export default handleEvent({

package/dist/{src/domain → domain}/index.d.ts

@@ -1,4 +1,5 @@
 export { discoverHandlers } from './discovery';
+export { createContract } from './contract-helper';
 export { eventSchema, handleEvent } from './handler-factory';
 export type { EnrichedEvent, EventHandler, HandleEventOptions, HandlerConstructor, HandlerMetadata, IdempotencyStore, InferEventData, MatchFn, RoutingConfig, } from './types';
 export type { HandlerValidationError, ValidationErrorDetail } from './validation';

package/dist/{src/domain → domain}/index.js

@@ -1,3 +1,4 @@
 export { discoverHandlers } from './discovery';
+export { createContract } from './contract-helper';
 export { eventSchema, handleEvent } from './handler-factory';
 export { extractTypeFromSchema, isValidHandler } from './validation';

package/dist/{src/domain → domain}/types.d.ts

@@ -45,8 +45,11 @@ export type HandlerMetadata<S extends ZodTypeAny> = {
 };
 /**
  * Options for creating event handlers
+ *
+ * Note: In Zod v4, we use a more relaxed schema constraint to allow
+ * contracts defined in external packages to work correctly.
  */
-export interface HandleEventOptions<S extends ZodTypeAny> {
+export interface HandleEventOptions<S = ZodTypeAny> {
     schema: S;
     type?: string;
     match?: MatchFn<unknown>;

package/dist/{src/index.d.ts → index.d.ts}

@@ -1,7 +1,9 @@
 export type { EventContext } from './adapters/cloudevents';
 export { parseEventFromContext } from './adapters/cloudevents';
-export type { EnrichedEvent, IdempotencyStore, InferEventData, RoutingConfig } from './domain';
+export { createContract } from './domain';
+export type { EnrichedEvent, HandleEventOptions, IdempotencyStore, InferEventData, RoutingConfig } from './domain';
 export { 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';

package/dist/{src/index.js → index.js}

@@ -1,5 +1,7 @@
 export { parseEventFromContext } from './adapters/cloudevents';
+export { createContract } from './domain';
 export { 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';

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

@@ -13,21 +13,43 @@ export interface StreamConfig {
     replicas?: number;
 }
 /**
- * JetStream consumer configuration
+ * Options for creating/ensuring a JetStream stream exists
  */
-export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+export interface JetStreamStreamOptions {
     /** 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;
-    /** JetStream stream name. Will be auto-created if it doesn't exist */
+    /** JetStream stream name */
     stream: string;
     /** Subjects to bind to the stream (e.g., ['orders.>', 'payments.>']) */
     subjects: string[];
+    /** Stream configuration */
+    config?: StreamConfig;
+}
+/**
+ * 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;
+    /** NATS username for authentication (defaults to NATS_USER env var) */
+    user?: string;
+    /** NATS password for authentication (defaults to NATS_PASSWORD env var) */
+    pass?: string;
+    /** JetStream stream name (must already exist or use ensureJetStreamStream first) */
+    stream: string;
     /** Durable consumer name. Required for persistence across restarts */
     consumer: string;
+    /**
+     * Optional filter subjects for this consumer.
+     * If specified, consumer only receives messages matching these subjects.
+     * If omitted, consumer receives all messages from the stream.
+     * @example ['orders.created', 'orders.updated']
+     */
+    filterSubjects?: string[];
     /** Glob pattern to discover event handlers */
     discover: string;
     /**
@@ -51,8 +73,6 @@ export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quar
      * @default 3
      */
     maxDeliver?: number;
-    /** Stream configuration (only used when auto-creating) */
-    streamConfig?: StreamConfig;
     /**
      * Idempotency store for deduplication. Defaults to in-memory store.
      * Pass `false` to disable idempotency checks entirely.
@@ -64,6 +84,24 @@ export interface JetStreamConsumerOptions extends Pick<CloudEventsOptions, 'quar
      */
     idempotencyTtl?: number;
 }
+/**
+ * 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 declare function ensureJetStreamStream(options: JetStreamStreamOptions): Promise<void>;
 /**
  * Consume CloudEvents from NATS JetStream with persistence and guaranteed delivery.
  *

package/dist/{src/transports → transports}/nats/jetstream-consumer.js

@@ -1,19 +1,19 @@
-import { AckPolicy, connect, DeliverPolicy, ReplayPolicy, RetentionPolicy, StorageType, StringCodec, } from 'nats';
+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();
-// 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
@@ -21,7 +21,40 @@ const DEFAULT_STREAM_CONFIG = {
     replicas: 1,
 };
 /**
- * Ensures stream exists with the given configuration
+ * 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 };
@@ -42,8 +75,8 @@ async function ensureStream(jsm, name, subjects, config = {}) {
         await jsm.streams.add({
             name,
             subjects,
-            retention: RetentionPolicy.Limits,
-            storage: StorageType.File,
+            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,
@@ -58,11 +91,11 @@ async function ensureConsumer(jsm, streamName, consumerName, options) {
     const deliverPolicy = (() => {
         switch (options.startFrom) {
             case 'all':
-                return DeliverPolicy.All;
+                return DELIVER_ALL;
             case 'last':
-                return DeliverPolicy.Last;
+                return DELIVER_LAST;
             default:
-                return DeliverPolicy.New;
+                return DELIVER_NEW;
         }
     })();
     const optStartTime = options.startFrom instanceof Date ? options.startFrom : undefined;
@@ -74,30 +107,18 @@ async function ensureConsumer(jsm, streamName, consumerName, options) {
         // Consumer doesn't exist, create it
         await jsm.consumers.add(streamName, {
             durable_name: consumerName,
-            ack_policy: AckPolicy.Explicit,
-            deliver_policy: optStartTime ? DeliverPolicy.StartTime : deliverPolicy,
+            ack_policy: ACK_EXPLICIT,
+            deliver_policy: optStartTime ? DELIVER_START_TIME : deliverPolicy,
             opt_start_time: optStartTime?.toISOString(),
-            replay_policy: ReplayPolicy.Instant,
+            // 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}`);
     }
 }
-/**
- * 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.
  *
@@ -119,13 +140,11 @@ async function cleanupJetStreamConsumer(name) {
  * ```
  */
 export async function consumeJetStreamEvents(options) {
-    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
     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;
-    // Cleanup existing consumer (handles hot-reload)
-    await cleanupJetStreamConsumer(name);
     // 1) Discover handlers
     const handlerConstructors = await discoverHandlers(options.discover);
     const processedHandlers = handlerConstructors
@@ -142,19 +161,14 @@ export async function consumeJetStreamEvents(options) {
     // 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
+    // 4) Ensure durable consumer exists (stream must already exist)
     await ensureConsumer(jsm, options.stream, name, options);
-    // 6) Get consumer and start consuming
+    // 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}`);
-    // Track for cleanup
-    const abortController = new AbortController();
-    getJetStreamRegistry().set(name, { messages, connection: nc, abortController });
     const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
     // Setup idempotency store
     const idempotencyStore = options.idempotencyStore === false ? null : (options.idempotencyStore ?? getDefaultIdempotencyStore());
@@ -197,18 +211,15 @@ export async function consumeJetStreamEvents(options) {
             await handleUnhandledProcessingError(msg, error);
         }
     };
-    // Process messages
-    const processMessages = async () => {
-        for await (const msg of messages) {
-            if (abortController.signal.aborted)
-                break;
-            await processSingleMessage(msg);
+    (async () => {
+        try {
+            for await (const msg of messages) {
+                await processSingleMessage(msg);
+            }
         }
-    };
-    processMessages().catch((err) => {
-        if (!abortController.signal.aborted) {
+        catch (err) {
             logger.error(`[${name}] message processing loop crashed`, err);
         }
-    });
+    })();
     return messages;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",
@@ -14,15 +14,15 @@
     "hono"
   ],
   "type": "module",
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
-    "dist/src"
+    "dist"
   ],
   "exports": {
     ".": {
-      "import": "./dist/src/index.js",
-      "types": "./dist/src/index.d.ts"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
     "./transports/nats": {
       "import": "./dist/src/transports/nats/index.js",
@@ -37,6 +37,7 @@
     "start:dev": "tsc -p tsconfig.json --watch",
     "stryker": "bun stryker run",
     "lint": "biome lint --fix",
+    "pretest": "rm -rf dist",
     "test": "bun test",
     "prepublishOnly": "bun run build"
   },