@crossdelta/cloudevents 0.5.4 → 0.5.6

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/dist/domain/discovery.js

@@ -53,11 +53,24 @@ const loadHandlers = async (filePath, filter) => {
         });
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        const errorStack = error instanceof Error ? error.stack : undefined;
-        logger?.warn(`Failed to load ${filePath}: ${errorMessage}`);
-        if (errorStack) {
-            logger?.warn(errorStack);
+        // Comprehensive error logging for debugging
+        logger?.warn(`Failed to load ${filePath}`);
+        logger?.warn(`Error type: ${typeof error}`);
+        logger?.warn(`Error constructor: ${error?.constructor?.name}`);
+        if (error instanceof Error) {
+            logger?.warn(`Error message: ${error.message}`);
+            if (error.stack) {
+                logger?.warn(`Stack trace:\n${error.stack}`);
+            }
+        }
+        else {
+            logger?.warn(`Error value: ${String(error)}`);
+            try {
+                logger?.warn(`Error JSON: ${JSON.stringify(error, null, 2)}`);
+            }
+            catch {
+                logger?.warn('(Error is not JSON-serializable)');
+            }
         }
         return [];
     }

package/package.json

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