@crossdelta/cloudevents 0.5.0 → 0.5.2

package/README.md

@@ -58,21 +58,20 @@ export default handleEvent(
 **2. Ensure stream exists** (once, during setup):
 
 ```typescript
-import { ensureJetStreamStream } from '@crossdelta/cloudevents'
+import { ensureJetStreams } from '@crossdelta/cloudevents'
 
-await ensureJetStreamStream({
-  stream: 'ORDERS',
-  subjects: ['orders.*'],
+await ensureJetStreams({
+  streams: [{ stream: 'ORDERS', subjects: ['orders.*'] }],
 })
 ```
 
 **3. Start consuming:**
 
 ```typescript
-import { consumeJetStreamEvents } from '@crossdelta/cloudevents'
+import { consumeJetStreams } from '@crossdelta/cloudevents'
 
-await consumeJetStreamEvents({
-  stream: 'ORDERS',
+consumeJetStreams({
+  streams: ['ORDERS'],
   consumer: 'my-service',
   discover: './src/events/**/*.event.ts',
 })
@@ -162,27 +161,32 @@ await publish('orders.created', orderData)
 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
-  }
+import { ensureJetStreams } from '@crossdelta/cloudevents'
+
+await ensureJetStreams({
+  streams: [
+    {
+      stream: 'ORDERS',
+      subjects: ['orders.>'],
+      config: {
+        maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days retention
+        replicas: 3,                       // For HA
+      },
+    },
+  ],
 })
 ```
 
 ### Consuming
 
 ```typescript
+import { consumeJetStreams } from '@crossdelta/cloudevents'
+
 // JetStream (recommended) — persistent, retries, exactly-once
-await consumeJetStreamEvents({
-  stream: 'ORDERS',
+consumeJetStreams({
+  streams: ['ORDERS'],
   consumer: 'billing',
   discover: './src/events/**/*.event.ts',
-  filterSubjects: ['orders.created', 'orders.updated'], // Optional: filter at consumer level
 })
 
 // Core NATS — fire-and-forget, simpler
@@ -207,28 +211,33 @@ NATS_PASSWORD=mypass    # optional
 ### Stream Options
 
 ```typescript
-await ensureJetStreamStream({
-  // Required
-  stream: 'ORDERS',
-  subjects: ['orders.>'],
-
+await ensureJetStreams({
+  streams: [
+    {
+      // Required
+      stream: 'ORDERS',
+      subjects: ['orders.>'],
+
+      // Optional
+      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'
+      },
+    },
+  ],
   // 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({
+consumeJetStreams({
   // Required
-  stream: 'ORDERS',
+  streams: ['ORDERS'],
   consumer: 'my-service',
   discover: './src/events/**/*.event.ts',
 
@@ -331,8 +340,10 @@ const redisStore = {
   add: (id, ttl) => redis.set(`idem:${id}`, '1', 'PX', ttl),
 }
 
-await consumeJetStreamEvents({
-  // ...
+await consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.event.ts',
   idempotencyStore: redisStore,
 })
 ```
@@ -345,13 +356,17 @@ await consumeJetStreamEvents({
 Invalid messages are quarantined, not lost:
 
 ```typescript
-await consumeJetStreamEvents({
-  // ...
-  quarantineTopic: 'events.quarantine',
-  errorTopic: 'events.errors',
+await consumeJetStreams({
+  streams: ['ORDERS'],
+  consumer: 'my-service',
+  discover: './src/events/**/*.event.ts',
+  quarantineTopic: 'events.quarantine',  // For malformed messages
+  errorTopic: 'events.errors',            // For handler errors
 })
 ```
 
+Messages that fail validation go to `quarantineTopic`, messages that crash handlers go to `errorTopic`.
+
 </details>
 
 <details>
@@ -375,8 +390,9 @@ app.use('/events', cloudEvents({ discover: 'src/events/**/*.event.ts' }))
 |----------|---------|
 | `handleEvent(options, handler)` | Create a handler |
 | `createContract(options)` | Create shared event contract |
-| `ensureJetStreamStream(options)` | Create/update JetStream stream |
-| `consumeJetStreamEvents(options)` | Consume with persistence |
+| `ensureJetStreams(options)` | Create/update JetStream streams (preferred) |
+| `consumeJetStreams(options)` | Consume from multiple streams (preferred) |
+| `consumeJetStreamEvents(options)` | Consume single stream (legacy) |
 | `consumeNatsEvents(options)` | Consume fire-and-forget |
 | `publish(type, data)` | Publish event |
 

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export { clearHandlerCache, cloudEvents } from './middlewares';
 export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';
 export type { JetStreamConsumerOptions, JetStreamStreamOptions, JetStreamStreamsConsumerOptions, JetStreamStreamsOptions, StreamConfig, StreamDefinition, } from './transports/nats';
-export { consumeJetStreamEvents, consumeJetStreamStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, } from './transports/nats';
+export { consumeJetStreamEvents, consumeJetStreamStreams, consumeJetStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, ensureJetStreams, } from './transports/nats';

package/dist/index.js

@@ -3,4 +3,4 @@ export { createContract, eventSchema, extractTypeFromSchema, handleEvent } from
 export { clearHandlerCache, cloudEvents } from './middlewares';
 export { checkAndMarkProcessed, createInMemoryIdempotencyStore, getDefaultIdempotencyStore, resetDefaultIdempotencyStore, } from './processing/idempotency';
 export * from './publishing';
-export { consumeJetStreamEvents, consumeJetStreamStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, } from './transports/nats';
+export { consumeJetStreamEvents, consumeJetStreamStreams, consumeJetStreams, consumeNatsEvents, ensureJetStreamStream, ensureJetStreamStreams, ensureJetStreams, } from './transports/nats';

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

@@ -205,3 +205,13 @@ export interface JetStreamStreamsConsumerOptions extends Pick<CloudEventsOptions
  * ```
  */
 export declare function consumeJetStreamStreams(options: JetStreamStreamsConsumerOptions): Promise<ConsumerMessages[]>;
+/**
+ * Alias for ensureJetStreamStreams - shorter name
+ * @see ensureJetStreamStreams
+ */
+export declare const ensureJetStreams: typeof ensureJetStreamStreams;
+/**
+ * Alias for consumeJetStreamStreams - shorter name
+ * @see consumeJetStreamStreams
+ */
+export declare const consumeJetStreams: typeof consumeJetStreamStreams;

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

@@ -355,3 +355,13 @@ export async function consumeJetStreamStreams(options) {
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",