fix: improve validation error messages (#46)

Co-authored-by: JaeHo Jang <[email protected]>

Author: mag123c

.changeset/hungry-dryers-slide.md

@@ -0,0 +1,5 @@
+---
+"ventyd": patch
+---
+
+Add more descriptive validation error messages

src/standard.ts

@@ -94,7 +94,7 @@ export function standard<
           );
         }
 
-        return standardValidate(eventSchema, input) as Extract<
+        return standardValidate(eventSchema, input, eventName) as Extract<
           StandardSchemaV1.InferOutput<$$EventDefinition[K]>,
           { eventName: K }
         >;
@@ -111,6 +111,7 @@ export function standard<
  *
  * @param schema - The Standard Schema to validate against
  * @param input - The input value to validate
+ * @param eventName - Optional event name for better error messages
  * @returns The validated and typed output
  * @throws {Error} If validation fails or if the schema returns a Promise
  *
@@ -119,15 +120,52 @@ export function standard<
 function standardValidate<T extends StandardSchemaV1>(
   schema: T,
   input: unknown,
+  eventName?: string,
 ): StandardSchemaV1.InferOutput<T> {
   const result = schema["~standard"].validate(input);
 
   if (result instanceof Promise) {
     throw new Error("Promise validation result is not supported");
   }
   if (result.issues) {
-    throw new Error("Validation failed");
+    const formattedError = formatStandardSchemaIssues(result.issues, eventName);
+    throw new Error(formattedError);
   }
 
   return result.value as StandardSchemaV1.InferOutput<T>;
 }
+
+/**
+ * Formats Standard Schema validation issues into a readable error message.
+ *
+ * @param issues - Array of validation issues from Standard Schema
+ * @param eventName - Optional event name to include in the error message
+ * @returns Formatted error message string
+ *
+ * @internal
+ */
+function formatStandardSchemaIssues(
+  issues: readonly StandardSchemaV1.Issue[],
+  eventName?: string,
+): string {
+  const header = eventName
+    ? `Validation failed: "${eventName}"`
+    : "Validation failed";
+
+  const errors = issues
+    .map((issue) => {
+      const pathStr =
+        issue.path && issue.path.length > 0
+          ? issue.path
+              .map((segment) =>
+                typeof segment === "object" ? segment.key : segment,
+              )
+              .join(".")
+          : "(root)";
+
+      return `  - ${pathStr}: ${issue.message}`;
+    })
+    .join("\n");
+
+  return errors ? `${header}\n${errors}` : header;
+}

test/standard.spec.ts

@@ -303,6 +303,44 @@ describe("Standard Schema Provider", () => {
     });
   });
 
+  describe("Error message formatting", () => {
+    test("should include event name in validation error", () => {
+      const schema = defineSchema("user", {
+        schema: standard({
+          event: {
+            "user:created": v.object({
+              eventId: v.string(),
+              eventName: v.literal("user:created"),
+              eventCreatedAt: v.string(),
+              entityName: v.string(),
+              entityId: v.string(),
+              body: v.object({
+                email: v.pipe(v.string(), v.email()),
+              }),
+            }),
+          },
+          state: v.object({
+            email: v.string(),
+          }),
+        }),
+        initialEventName: "user:created",
+      });
+
+      expect(() => {
+        schema.parseEventByName("user:created", {
+          eventId: "evt-123",
+          eventName: "user:created",
+          eventCreatedAt: new Date().toISOString(),
+          entityName: "user",
+          entityId: "usr-123",
+          body: {
+            email: "not-an-email",
+          },
+        });
+      }).toThrow('Validation failed: "user:created"');
+    });
+  });
+
   describe("Type inference", () => {
     test("should infer correct event types", () => {
       const schema = defineSchema("product", {