@crossdelta/cloudevents 0.5.4 → 0.5.5

package/README.md

@@ -11,7 +11,7 @@ Type-safe event-driven microservices with [NATS](https://nats.io) and [Zod](http
   └──────────────┘      │              │      └──────────────┘
                         └──────────────┘
         │                                            │
-        │  publishNatsRawEvent(...)                  │  handleEvent(...)
+        │  publish(...)                              │  handleEvent(...)
         ▼                                            ▼
   ┌──────────────┐                            ┌──────────────┐
   │ { orderId,   │                            │ Zod schema   │
@@ -286,14 +286,32 @@ export const OrdersCreatedContract = createContract({
 ```typescript
 interface ChannelConfig {
   stream: string    // JetStream stream name (e.g., 'ORDERS')
-  subject?: string  // NATS subject (defaults to event type)
+  subject?: string  // NATS subject (optional override)
 }
 ```
 
-**Subject Defaulting:**
-- If `subject` is **not provided**, it defaults to the event `type`
-- This follows the convention: `orders.created` → subject `orders.created`
-- Override when needed: `subject: 'orders.v1.created'`
+**Subject Routing (CRITICAL):**
+- **Without `subject`**: Domain is auto-pluralized: `customer.created` → subject `customers.created`
+- **With `subject`**: Uses exact subject specified (no auto-pluralization)
+- **Why pluralize**: Stream subjects are plural (`customers.*`), event types are singular (`customer.created`)
+
+**Examples:**
+```typescript
+// Auto-pluralized subject
+createContract({
+  type: 'order.created',          // Event type: singular
+  channel: { stream: 'ORDERS' },  // Subject: orders.created (plural)
+})
+
+// Custom subject (no auto-pluralization)
+createContract({
+  type: 'order.created',
+  channel: { 
+    stream: 'ORDERS',
+    subject: 'orders.v1.created'  // Exact subject, no auto-pluralization
+  },
+})
+```
 
 ### Multiple Events, Same Stream
 

package/package.json

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