feat(framework): add class-validator support

.cspell.json

@@ -708,7 +708,8 @@
     "rstrip",
     "truncatewords",
     "xmlschema",
-    "jsonify"
+    "jsonify",
+    "metadatas"
   ],
   "flagWords": [],
   "patterns": [

packages/framework/package.json

@@ -38,7 +38,7 @@
     "build:watch": "tsup --watch",
     "postbuild": "pnpm run check:exports && pnpm check:circulars",
     "check:exports": "attw --pack .",
-    "check:circulars": "madge --circular --extensions ts ./src",
+    "check:circulars": "madge --circular --extensions ts --exclude ../../shared ./src",
     "$comment:bump:prerelease": "This is a workaround to support `npm version prerelease` with lerna",
     "bump:prerelease": "npm version prerelease --preid=alpha & PID=$!; (sleep 1 && kill -9 $PID) & wait $PID",
     "release:alpha": "pnpm bump:prerelease || pnpm build && npm publish",
@@ -169,9 +169,13 @@
     "@sveltejs/kit": ">=1.27.3",
     "@vercel/node": ">=2.15.9",
     "aws-lambda": ">=1.0.7",
+    "class-transformer": ">=0.5.1",
+    "class-validator": ">=0.14.0",
+    "class-validator-jsonschema": ">=5.0.0",
     "express": ">=4.19.2",
     "h3": ">=1.8.1",
     "next": ">=12.0.0",
+    "reflect-metadata": ">=0.2.2",
     "zod": ">=3.0.0",
     "zod-to-json-schema": ">=3.0.0"
   },
@@ -200,6 +204,18 @@
     "next": {
       "optional": true
     },
+    "class-transformer": {
+      "optional": true
+    },
+    "class-validator": {
+      "optional": true
+    },
+    "class-validator-jsonschema": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     },
@@ -218,11 +234,15 @@
     "@types/sanitize-html": "2.11.0",
     "@vercel/node": "^2.15.9",
     "aws-lambda": "^1.0.7",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "class-validator-jsonschema": "^5.0.1",
     "express": "^4.19.2",
     "h3": "^1.11.1",
     "madge": "^8.0.0",
     "next": "^13.5.4",
     "prettier": "^3.2.5",
+    "reflect-metadata": "^0.2.2",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.2",
     "tsx": "4.16.2",

packages/framework/src/resources/workflow/workflow.resource.test-d.ts

@@ -109,27 +109,69 @@ describe('workflow function types', () => {
       additionalProperties: false,
     } as const;
 
-    it('should infer an unknown record type when the provided schema is for a primitive type', () => {
+    it('should infer an error message type when the provided schema is for a primitive type', () => {
       const primitiveSchema = { type: 'string' } as const;
       workflow('without-schema', async ({ step }) => {
         await step.email(
           'without-schema',
           async (controls) => {
-            expectTypeOf(controls).toEqualTypeOf<Record<string, unknown>>();
+            expectTypeOf(controls).toEqualTypeOf<{
+              SchemaError: "Schema must describe an object data structure. Got data type: 'string'";
+            }>();
 
             return {
               subject: 'Test subject',
               body: 'Test body',
             };
           },
           {
-            // @ts-expect-error - schema is for a primitive type
             controlSchema: primitiveSchema,
           }
         );
       });
     });
 
+    it('should infer an error message type when the provided schema is for an array type', () => {
+      const arraySchema = { type: 'array', items: { type: 'string' } } as const;
+      workflow('without-schema', async ({ step }) => {
+        await step.email(
+          'without-schema',
+          async (controls) => {
+            expectTypeOf(controls).toEqualTypeOf<{
+              SchemaError: `Schema must describe an object data structure. Got data type: 'string[]'`;
+            }>();
+
+            return {
+              subject: 'Test subject',
+              body: 'Test body',
+            };
+          },
+          {
+            controlSchema: arraySchema,
+          }
+        );
+      });
+    });
+
+    it('should infer an unknown record type when the provided schema is undefined', () => {
+      workflow('without-schema', async ({ step }) => {
+        await step.email(
+          'without-schema',
+          async (controls) => {
+            expectTypeOf(controls).toEqualTypeOf<Record<string, unknown>>();
+
+            return {
+              subject: 'Test subject',
+              body: 'Test body',
+            };
+          },
+          {
+            controlSchema: undefined,
+          }
+        );
+      });
+    });
+
     it('should infer correct types in the step controls', async () => {
       workflow('json-schema', async ({ step }) => {
         await step.email(

packages/framework/src/resources/workflow/workflow.resource.ts

@@ -45,7 +45,8 @@ export function workflow<
       if (validationResult.success === false) {
         throw new WorkflowPayloadInvalidError(workflowId, validationResult.errors);
       }
-      validatedData = validationResult.data as T_PayloadValidated;
+      // Coerce the validated data to handle unknown matching to SchemaError
+      validatedData = validationResult.data as Record<string, unknown> as T_PayloadValidated;
     } else {
       // This type coercion provides support to trigger Workflows without a payload schema
       validatedData = event.payload as unknown as T_PayloadValidated;

packages/framework/src/types/schema.types/base.schema.types.test-d.ts

@@ -4,16 +4,65 @@ import { FromSchema, FromSchemaUnvalidated, Schema } from './base.schema.types';
 
 describe('FromSchema', () => {
   it('should infer an unknown record type when a generic schema is provided', () => {
-    expectTypeOf<FromSchema<Schema>>().toEqualTypeOf<Record<string, unknown>>();
+    type Test = FromSchema<Schema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<Record<string, unknown>>();
   });
 
-  it('should not compile when the schema is primitive', () => {
+  it('should not compile and infer an unknown record type when the schema is undefined', () => {
+    // @ts-expect-error - Type 'undefined' does not satisfy the constraint 'Schema'.
+    type Test = FromSchema<undefined>;
+
+    expectTypeOf<Test>().toEqualTypeOf<Record<string, unknown>>();
+  });
+
+  it('not compile when the schema is undefined', () => {
+    // @ts-expect-error - Type 'undefined' does not satisfy the constraint 'Schema'.
+    type Test = FromSchemaUnvalidated<undefined>;
+
+    expectTypeOf<Test>().toEqualTypeOf<Record<string, unknown>>();
+  });
+
+  it('should infer an error message type when the schema describes a primitive type', () => {
     const primitiveSchema = { type: 'string' } as const;
+    type Test = FromSchema<typeof primitiveSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{
+      SchemaError: `Schema must describe an object data structure. Got data type: 'string'`;
+    }>();
+  });
+
+  it('should infer an error message type when the schema describes an array of primitive types', () => {
+    const primitiveSchema = { type: 'array', items: { type: 'string' } } as const;
+    type Test = FromSchema<typeof primitiveSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{
+      SchemaError: `Schema must describe an object data structure. Got data type: 'string[]'`;
+    }>();
+  });
+
+  it('should infer an error message type when the schema describes an array of objects', () => {
+    const primitiveSchema = {
+      type: 'array',
+      items: { type: 'object' },
+    } as const;
+    type Test = FromSchema<typeof primitiveSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{
+      SchemaError: `Schema must describe an object data structure. Got data type: '{ [x: string]: unknown; }[]'`;
+    }>();
+  });
 
-    // @ts-expect-error - Type '{ type: string; }' is not assignable to type '{ type: "object"; }'.
+  it('should infer an error message type when the schema describes an array of unknown types', () => {
+    const primitiveSchema = {
+      type: 'array',
+      items: {},
+    } as const;
     type Test = FromSchema<typeof primitiveSchema>;
 
-    expectTypeOf<Test>().toEqualTypeOf<never>();
+    expectTypeOf<Test>().toEqualTypeOf<{
+      SchemaError: `Schema must describe an object data structure. Got data type: 'unknown[]'`;
+    }>();
   });
 
   it('should infer a Json Schema type', () => {
@@ -26,7 +75,9 @@ describe('FromSchema', () => {
       additionalProperties: false,
     } as const;
 
-    expectTypeOf<FromSchema<typeof testJsonSchema>>().toEqualTypeOf<{ foo: string; bar?: string }>();
+    type Test = FromSchema<typeof testJsonSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo: string; bar?: string }>();
   });
 
   it('should infer a Zod Schema type', () => {
@@ -35,22 +86,28 @@ describe('FromSchema', () => {
       bar: z.string().optional(),
     });
 
-    expectTypeOf<FromSchema<typeof testZodSchema>>().toEqualTypeOf<{ foo: string; bar?: string }>();
+    type Test = FromSchema<typeof testZodSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo: string; bar?: string }>();
+  });
+
+  it('should infer a Class Schema type', () => {
+    class TestSchema {
+      foo: string = 'bar';
+      bar?: string;
+    }
+
+    type Test = FromSchema<typeof TestSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo: string; bar?: string }>();
   });
 });
 
 describe('FromSchemaUnvalidated', () => {
   it('should infer an unknown record type when a generic schema is provided', () => {
-    expectTypeOf<FromSchemaUnvalidated<Schema>>().toEqualTypeOf<Record<string, unknown>>();
-  });
+    type Test = FromSchemaUnvalidated<Schema>;
 
-  it('should not compile when the schema is primitive', () => {
-    const primitiveSchema = { type: 'string' } as const;
-
-    // @ts-expect-error - Type '{ type: string; }' is not assignable to type '{ type: "object"; }'.
-    type Test = FromSchemaUnvalidated<typeof primitiveSchema>;
-
-    expectTypeOf<Test>().toEqualTypeOf<never>();
+    expectTypeOf<Test>().toEqualTypeOf<Record<string, unknown>>();
   });
 
   it('should infer a Json Schema type', () => {
@@ -63,7 +120,9 @@ describe('FromSchemaUnvalidated', () => {
       additionalProperties: false,
     } as const;
 
-    expectTypeOf<FromSchemaUnvalidated<typeof testJsonSchema>>().toEqualTypeOf<{ foo?: string; bar?: string }>();
+    type Test = FromSchemaUnvalidated<typeof testJsonSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo?: string; bar?: string }>();
   });
 
   it('should infer a Zod Schema type', () => {
@@ -72,6 +131,19 @@ describe('FromSchemaUnvalidated', () => {
       bar: z.string().optional(),
     });
 
-    expectTypeOf<FromSchemaUnvalidated<typeof testZodSchema>>().toEqualTypeOf<{ foo?: string; bar?: string }>();
+    type Test = FromSchemaUnvalidated<typeof testZodSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo?: string; bar?: string }>();
+  });
+
+  it('should infer a Class Schema type', () => {
+    class TestClassSchema {
+      foo?: string = 'bar';
+      bar?: string;
+    }
+
+    type Test = FromSchemaUnvalidated<typeof TestClassSchema>;
+
+    expectTypeOf<Test>().toEqualTypeOf<{ foo?: string; bar?: string }>();
   });
 });

packages/framework/src/types/schema.types/base.schema.types.ts

@@ -1,10 +1,12 @@
 import type { InferJsonSchema, JsonSchemaMinimal } from './json.schema.types';
 import type { InferZodSchema, ZodSchemaMinimal } from './zod.schema.types';
+import type { InferClassValidatorSchema, ClassValidatorSchema } from './class.schema.types';
+import type { Stringify } from '../util.types';
 
 /**
  * A schema used to validate a JSON object.
  */
-export type Schema = JsonSchemaMinimal | ZodSchemaMinimal;
+export type Schema = JsonSchemaMinimal | ZodSchemaMinimal | ClassValidatorSchema;
 
 /**
  * Main utility type for schema inference
@@ -14,7 +16,32 @@
  */
 type InferSchema<T extends Schema, Options extends { validated: boolean }> =
   | InferJsonSchema<T, Options>
-  | InferZodSchema<T, Options>;
+  | InferClassValidatorSchema<T, Options>
+  | InferZodSchema<T, Options>
+  | never extends infer U
+  ? /*
+     * Use a distributive conditional type to detect if all inferred types are `never`.
+     * When all inferred types are `never`, return an unknown record.
+     *
+     * Each schema inferrence must return `never` type when:
+     * - The schema is generic (i.e. not a concrete schema type)
+     * - The schema is not supported (i.e. tried to specify `string` as the schema type)
+     * - The schema is undefined
+     *
+     * @see - https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+     */
+    [U] extends [never]
+    ? // When all inferred types are `never`, return an unknown record.
+      Record<string, unknown>
+    : // The type inferrence did not return `never`. Ensure the inferred type is a record type, as only objects are supported.
+      U extends Record<string, unknown>
+      ? // Got a record type, return it.
+        U
+      : // The schema describes a non-record type, return an error message.
+        {
+          SchemaError: `Schema must describe an object data structure. Got data type: '${Stringify<U>}'`;
+        }
+  : never;
 
 /**
  * Infer the type of a Schema for unvalidated data.