@crossdelta/cloudevents 0.5.6 → 0.6.0

package/README.md

@@ -40,18 +40,18 @@ import { handleEvent } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
 // Export schema for mock generation
-export const OrdersCreatedSchema = z.object({
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   total: z.number(),
 })
 
 // Export type for use in use-cases
-export type OrdersCreatedEvent = z.infer<typeof OrdersCreatedSchema>
+export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
 
 export default handleEvent(
   {
-    schema: OrdersCreatedSchema,
-    type: 'orders.created',
+    schema: OrderCreatedSchema,
+    type: 'order.created',
   },
   async (data) => {
     console.log(`New order: ${data.orderId}, total: ${data.total}`)
@@ -76,7 +76,7 @@ consumeJetStreams({
 ```typescript
 import { publish } from '@crossdelta/cloudevents'
 
-await publish('orders.created', { orderId: 'ord_123', total: 99.99 })
+await publish('order.created', { orderId: 'ord_123', total: 99.99 })
 ```
 
 That's it. Handlers are auto-discovered, validated with Zod, and messages persist in JetStream.
@@ -104,7 +104,7 @@ That's it. Handlers are auto-discovered, validated with Zod, and messages persis
 
 **Important distinction:**
 
-- **Event Type** (`orders.created`): Lives in the CloudEvent **envelope** (`ce.type`). Used for routing and handler matching.
+- **Event Type** (`order.created`): Lives in the CloudEvent **envelope** (`ce.type`). Used for routing and handler matching.
 - **Event Data** (`{ orderId, total }`): The actual payload. Does **not** include the type.
 
 ```typescript
@@ -115,7 +115,7 @@ const Schema = z.object({
 export default handleEvent(
   {
     schema: Schema,
-    type: 'orders.created',
+    type: 'order.created',
   },
   async (data) => { ... }
 )
@@ -140,7 +140,7 @@ export type UserSignupEvent = z.infer<typeof UserSignupSchema>
 export default handleEvent(
   {
     schema: UserSignupSchema,
-    type: 'users.signup',
+    type: 'user.signup',
   },
   async (data) => {
     await sendWelcomeEmail(data.email)
@@ -151,7 +151,7 @@ export default handleEvent(
 ### Publishing
 
 ```typescript
-await publish('orders.created', orderData)
+await publish('order.created', orderData)
 ```
 
 ### Stream Setup
@@ -209,6 +209,26 @@ NATS_USER=myuser        # optional
 NATS_PASSWORD=mypass    # optional
 ```
 
+### Optional: Google Cloud Pub/Sub
+
+To use Google Cloud Pub/Sub instead of NATS, install the optional dependency:
+
+```bash
+bun add @google-cloud/pubsub
+# or
+npm install @google-cloud/pubsub
+```
+
+Then use the `publishToPubSub` function:
+
+```typescript
+import { publishToPubSub } from '@crossdelta/cloudevents'
+
+await publishToPubSub('order.created', { orderId: 'ord_123', total: 99.99 })
+```
+
+**Note:** `@google-cloud/pubsub` is not bundled with this library to keep the package size small. Install it only if you need Google Cloud Pub/Sub support.
+
 ### Stream Options
 
 ```typescript
@@ -244,7 +264,7 @@ consumeJetStreams({
 
   // Optional
   servers: 'nats://localhost:4222',
-  filterSubjects: ['orders.created'],  // Filter specific subjects
+  filterSubjects: ['order.created'],  // Filter specific subjects
   maxDeliver: 5,                       // Retry attempts
   ackWait: 30_000,                     // Timeout per attempt (ms)
   quarantineTopic: 'dlq',              // For poison messages
@@ -269,10 +289,10 @@ import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
+  type: 'order.created',
   channel: {
     stream: 'ORDERS',
-    // subject defaults to 'orders.created' if omitted
+    // subject defaults to 'order.created' if omitted
   },
   schema: z.object({
     orderId: z.string(),
@@ -300,7 +320,7 @@ interface ChannelConfig {
 // Auto-pluralized subject
 createContract({
   type: 'order.created',          // Event type: singular
-  channel: { stream: 'ORDERS' },  // Subject: orders.created (plural)
+  channel: { stream: 'ORDERS' },  // Subject: order.created (plural)
 })
 
 // Custom subject (no auto-pluralization)
@@ -316,31 +336,31 @@ createContract({
 ### Multiple Events, Same Stream
 
 ```typescript
-// orders.created → ORDERS stream
+// order.created → ORDERS stream
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
+  type: 'order.created',
   channel: { stream: 'ORDERS' },
   schema: OrderCreatedSchema,
 })
 
-// orders.updated → ORDERS stream (same stream!)
+// order.updated → ORDERS stream (same stream!)
 export const OrdersUpdatedContract = createContract({
-  type: 'orders.updated',
+  type: 'order.updated',
   channel: { stream: 'ORDERS' },
   schema: OrderUpdatedSchema,
 })
 ```
 
-**Result:** Both events share the `ORDERS` stream with subjects `orders.created` and `orders.updated`.
+**Result:** Both events share the `ORDERS` stream with subjects `order.created` and `order.updated`.
 
 ### Infrastructure Materialization
 
 Channel metadata is **conceptual** - it defines routing, not infrastructure policy.
 
 **Contracts define:**
-- Event type (`orders.created`)
+- Event type (`order.created`)
 - Stream routing (`ORDERS`)
-- Subject mapping (`orders.created`)
+- Subject mapping (`order.created`)
 
 **Infrastructure defines:**
 - Retention (7 days, 14 days, etc.)
@@ -356,7 +376,7 @@ import { ensureJetStreams } from '@crossdelta/cloudevents'
 
 // Collect from contracts
 const streams = collectStreamDefinitions()
-// [{ stream: 'ORDERS', subjects: ['orders.created', 'orders.updated'] }]
+// [{ stream: 'ORDERS', subjects: ['order.created', 'order.updated'] }]
 
 // Materialize with policies
 await ensureJetStreams({
@@ -406,16 +426,16 @@ When multiple services consume the same event, use `createContract` to create sh
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export const OrdersCreatedSchema = z.object({
+export const OrderCreatedSchema = z.object({
   orderId: z.string(),
   total: z.number(),
 })
 
-export type OrdersCreatedData = z.infer<typeof OrdersCreatedSchema>
+export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>
 
 export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
-  schema: OrdersCreatedSchema,
+  type: 'order.created',
+  schema: OrderCreatedSchema,
 })
 ```
 
@@ -428,7 +448,7 @@ import { OrdersCreatedContract } from '@my-org/contracts'
 export default handleEvent(
   OrdersCreatedContract,
   async (data) => {
-    // data is typed as OrdersCreatedData
+    // data is typed as OrderCreatedData
     console.log(data.orderId)
   },
 )
@@ -448,7 +468,7 @@ Filter events by tenant:
 
 ```typescript
 export default handleEvent({
-  type: 'orders.created',
+  type: 'order.created',
   schema: OrderSchema,
   tenantId: 'tenant-a',  // Only process tenant-a events
 }, async (data) => { ... })
@@ -463,7 +483,7 @@ Add custom filter logic:
 
 ```typescript
 export default handleEvent({
-  type: 'orders.created',
+  type: 'order.created',
   schema: OrderSchema,
   match: (event) => event.data.total > 100,  // Only high-value orders
 }, async (data) => { ... })