@crossdelta/cloudevents 0.2.1 → 0.3.2

package/README.md

@@ -20,10 +20,12 @@ Type-safe event-driven microservices with [NATS](https://nats.io) and [Zod](http
 ```
 
 ```bash
-bun add @crossdelta/cloudevents zod
+bun add @crossdelta/cloudevents zod@4
 ```
 
 > **Prerequisites:** A running [NATS server](https://docs.nats.io/running-a-nats-service/introduction) with JetStream enabled.
+> 
+> **Note:** Requires Zod v4 for full TypeScript support.
 
 ## Quick Start
 
@@ -33,15 +35,23 @@ bun add @crossdelta/cloudevents zod
 import { handleEvent } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export default handleEvent({
-  type: 'orders.created',
-  schema: z.object({
-    orderId: z.string(),
-    total: z.number(),
-  }),
-}, async (data) => {
-  console.log(`New order: ${data.orderId}, total: ${data.total}`)
+const OrderCreatedSchema = z.object({
+  orderId: z.string(),
+  total: z.number(),
 })
+
+// Export type for use in use-cases
+export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+
+export default handleEvent(
+  {
+    schema: OrderCreatedSchema,
+    type: 'orders.created',
+  },
+  async (data) => {
+    console.log(`New order: ${data.orderId}, total: ${data.total}`)
+  },
+)
 ```
 
 **2. Start consuming:**
@@ -82,18 +92,52 @@ That's it. Handlers are auto-discovered, validated with Zod, and messages persis
 
 ## Core Concepts
 
+### Event Type vs. Event Data
+
+**Important distinction:**
+
+- **Event Type** (`orders.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
+const Schema = z.object({
+  orderId: z.string(), 
+})
+
+export default handleEvent(
+  {
+    schema: Schema,
+    type: 'orders.created',
+  },
+  async (data) => { ... }
+)
+```
+
 ### Handlers
 
 Drop a `*.event.ts` file anywhere — it's auto-registered:
 
 ```typescript
 // src/handlers/user-signup.event.ts
-export default handleEvent({
-  type: 'users.signup',
-  schema: z.object({ email: z.string().email() }),
-}, async (data) => {
-  await sendWelcomeEmail(data.email)
+import { z } from 'zod'
+
+const UserSignupSchema = z.object({ 
+  email: z.string().email(),
+  name: z.string(),
 })
+
+// Export type for use in use-cases
+export type UserSignupEvent = z.infer<typeof UserSignupSchema>
+
+export default handleEvent(
+  {
+    schema: UserSignupSchema,
+    type: 'users.signup',
+  },
+  async (data) => {
+    await sendWelcomeEmail(data.email)
+  },
+)
 ```
 
 ### Publishing

package/dist/src/processing/dlq-safe.js

@@ -19,6 +19,23 @@ export const quarantineMessage = async (processingContext, reason, options, erro
         return;
     }
     try {
+        // Serialize error properly - handle ValidationError specially
+        let serializedError;
+        if (error) {
+            if (typeof error === 'object' && error !== null && 'type' in error && error.type === 'ValidationError') {
+                serializedError = JSON.stringify(error, null, 2);
+            }
+            else if (error instanceof Error) {
+                serializedError = JSON.stringify({
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                }, null, 2);
+            }
+            else {
+                serializedError = JSON.stringify(error, null, 2);
+            }
+        }
         const quarantineData = {
             originalMessageId: processingContext.messageId,
             originalEventType: processingContext.eventType,
@@ -27,7 +44,7 @@ export const quarantineMessage = async (processingContext, reason, options, erro
             originalCloudEvent: processingContext.originalCloudEvent,
             quarantinedAt: new Date().toISOString(),
             quarantineReason: reason,
-            error: error ? String(error) : undefined,
+            error: serializedError,
         };
         await publishRawEvent(options.quarantineTopic, 'hono.cloudevents.quarantined', quarantineData, {
             projectId: options.projectId,

package/dist/src/transports/nats/base-message-processor.js

@@ -40,6 +40,8 @@ export function createBaseMessageProcessor(deps) {
         return { handled: true, shouldAck: true };
     };
     const handleValidationFailure = async (validationResult, handler, context) => {
+        // Log validation errors with full details for debugging
+        logger.error(`[${name}] validation failed for handler ${handler.name}`, JSON.stringify(validationResult.error, null, 2));
         if (dlqEnabled) {
             await quarantineMessage(context, 'validation_error', options, validationResult.error);
             return { handled: true, shouldAck: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",
@@ -50,7 +50,7 @@
   },
   "peerDependencies": {
     "hono": "^4.6.0",
-    "zod": "^3.23.0 || ^4.0.0"
+    "zod": "^4.0.0"
   },
   "trustedDependencies": [],
   "devDependencies": {