feat(validation): Add Middy.js middleware for JSON Schema validation

packages/validation/src/decorator.ts

@@ -0,0 +1,62 @@
+import { SchemaValidationError } from './errors.js';
+import type { ValidatorOptions } from './types.js';
+import { validate } from './validate.js';
+export function validator(options: ValidatorOptions) {
+  return (
+    _target: unknown,
+    _propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ) => {
+    if (!descriptor.value) {
+      return descriptor;
+    }
+    const {
+      inboundSchema,
+      outboundSchema,
+      envelope,
+      formats,
+      externalRefs,
+      ajv,
+    } = options;
+    if (!inboundSchema && !outboundSchema) {
+      return descriptor;
+    }
+    const originalMethod = descriptor.value;
+    descriptor.value = async function (...args: unknown[]) {
+      let validatedInput = args[0];
+      if (inboundSchema) {
+        try {
+          validatedInput = validate({
+            payload: validatedInput,
+            schema: inboundSchema,
+            envelope: envelope,
+            formats: formats,
+            externalRefs: externalRefs,
+            ajv: ajv,
+          });
+        } catch (error) {
+          throw new SchemaValidationError('Inbound validation failed', error);
+        }
+      }
+      const result = await originalMethod.apply(this, [
+        validatedInput,
+        ...args.slice(1),
+      ]);
+      if (outboundSchema) {
+        try {
+          return validate({
+            payload: result,
+            schema: outboundSchema,
+            formats: formats,
+            externalRefs: externalRefs,
+            ajv: ajv,
+          });
+        } catch (error) {
+          throw new SchemaValidationError('Outbound Validation failed', error);
+        }
+      }
+      return result;
+    };
+    return descriptor;
+  };
+}

packages/validation/src/index.ts

@@ -1,2 +1,4 @@
-export { validate } from './validate';
+export { validate } from './validate.js';
 export { SchemaValidationError } from './errors.js';
+export { validator } from './decorator.js';
+export { validationMiddleware } from './middleware.js';

packages/validation/src/middleware.ts

@@ -0,0 +1,42 @@
+import { SchemaValidationError } from './errors.js';
+import type { ValidatorOptions } from './types.js';
+import { validate } from './validate.js';
+
+export function validationMiddleware(options: ValidatorOptions) {
+  if (!options.inboundSchema && !options.outboundSchema) {
+    return {};
+  }
+  return {
+    before: async (handler: { event: unknown }) => {
+      if (options.inboundSchema) {
+        try {
+          handler.event = validate({
+            payload: handler.event,
+            schema: options.inboundSchema,
+            envelope: options.envelope,
+            formats: options.formats,
+            externalRefs: options.externalRefs,
+            ajv: options.ajv,
+          });
+        } catch (error) {
+          throw new SchemaValidationError('Inbound validation failed', error);
+        }
+      }
+    },
+    after: async (handler: { response: unknown }) => {
+      if (options.outboundSchema) {
+        try {
+          handler.response = validate({
+            payload: handler.response,
+            schema: options.outboundSchema,
+            formats: options.formats,
+            externalRefs: options.externalRefs,
+            ajv: options.ajv,
+          });
+        } catch (error) {
+          throw new SchemaValidationError('Outbound validation failed', error);
+        }
+      }
+    },
+  };
+}

packages/validation/src/types.ts

@@ -1,18 +1,36 @@
-import type Ajv from 'ajv';
-export interface ValidateParams<T = unknown> {
+import type {
+  Ajv,
+  AnySchema,
+  AsyncFormatDefinition,
+  FormatDefinition,
+} from 'ajv';
+
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+type ValidateParams = {
   payload: unknown;
-  schema: object;
+  schema: AnySchema;
   envelope?: string;
   formats?: Record<
     string,
     | string
     | RegExp
-    | {
-        type?: 'string' | 'number';
-        validate: (data: string) => boolean;
-        async?: boolean;
-      }
+    | FormatDefinition<string>
+    | FormatDefinition<number>
+    | AsyncFormatDefinition<string>
+    | AsyncFormatDefinition<number>
   >;
   externalRefs?: object[];
   ajv?: Ajv;
-}
+};
+
+type ValidatorOptions = Prettify<
+  Omit<ValidateParams, 'payload' | 'schema'> & {
+    inboundSchema?: AnySchema;
+    outboundSchema?: AnySchema;
+  }
+>;
+
+export type { ValidateParams, ValidatorOptions };

packages/validation/src/validate.ts

@@ -1,9 +1,9 @@
 import { search } from '@aws-lambda-powertools/jmespath';
-import Ajv, { type ValidateFunction } from 'ajv';
+import { Ajv, type ValidateFunction } from 'ajv';
 import { SchemaValidationError } from './errors.js';
 import type { ValidateParams } from './types.js';
 
-export function validate<T = unknown>(params: ValidateParams<T>): T {
+export function validate<T = unknown>(params: ValidateParams): T {
   const { payload, schema, envelope, formats, externalRefs, ajv } = params;
   const ajvInstance = ajv || new Ajv({ allErrors: true });
 

packages/validation/tests/unit/decorator.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+import { validator } from '../../src/decorator.js';
+import { SchemaValidationError } from '../../src/errors.js';
+
+const inboundSchema = {
+  type: 'object',
+  properties: {
+    value: { type: 'number' },
+  },
+  required: ['value'],
+  additionalProperties: false,
+};
+
+const outboundSchema = {
+  type: 'object',
+  properties: {
+    result: { type: 'number' },
+  },
+  required: ['result'],
+  additionalProperties: false,
+};
+
+describe('validator decorator', () => {
+  it('should validate inbound and outbound successfully', async () => {
+    // Prepare
+    class TestClass {
+      @validator({ inboundSchema, outboundSchema })
+      async multiply(input: { value: number }): Promise<{ result: number }> {
+        return { result: input.value * 2 };
+      }
+    }
+    const instance = new TestClass();
+    const input = { value: 5 };
+    // Act
+    const output = await instance.multiply(input);
+    // Assess
+    expect(output).toEqual({ result: 10 });
+  });
+
+  it('should throw error on inbound validation failure', async () => {
+    // Prepare
+    class TestClass {
+      @validator({ inboundSchema, outboundSchema })
+      async multiply(input: { value: number }): Promise<{ result: number }> {
+        return { result: input.value * 2 };
+      }
+    }
+    const instance = new TestClass();
+    const invalidInput = { value: 'not a number' } as unknown as {
+      value: number;
+    };
+    // Act & Assess
+    await expect(instance.multiply(invalidInput)).rejects.toThrow(
+      SchemaValidationError
+    );
+  });
+
+  it('should throw error on outbound validation failure', async () => {
+    // Prepare
+    class TestClassInvalid {
+      @validator({ inboundSchema, outboundSchema })
+      async multiply(input: { value: number }): Promise<{ result: number }> {
+        return { result: 'invalid' } as unknown as { result: number };
+      }
+    }
+    const instance = new TestClassInvalid();
+    const input = { value: 5 };
+    // Act & Assess
+    await expect(instance.multiply(input)).rejects.toThrow(
+      SchemaValidationError
+    );
+  });
+
+  it('should no-op when no schemas are provided', async () => {
+    // Prepare
+    class TestClassNoOp {
+      @validator({})
+      async echo(input: unknown): Promise<unknown> {
+        return input;
+      }
+    }
+    const instance = new TestClassNoOp();
+    const data = { foo: 'bar' };
+    // Act
+    const result = await instance.echo(data);
+    // Assess
+    expect(result).toEqual(data);
+  });
+
+  it('should return descriptor unmodified if descriptor.value is undefined', () => {
+    // Prepare
+    const descriptor: PropertyDescriptor = {};
+    // Act
+    const result = validator({ inboundSchema })(
+      null as unknown as object,
+      'testMethod',
+      descriptor
+    );
+    // Assess
+    expect(result).toEqual(descriptor);
+  });
+
+  it('should validate inbound only', async () => {
+    // Prepare
+    class TestClassInbound {
+      @validator({ inboundSchema })
+      async process(input: { value: number }): Promise<{ data: string }> {
+        return { data: JSON.stringify(input) };
+      }
+    }
+    const instance = new TestClassInbound();
+    const input = { value: 10 };
+    // Act
+    const output = await instance.process(input);
+    // Assess
+    expect(output).toEqual({ data: JSON.stringify(input) });
+  });
+
+  it('should validate outbound only', async () => {
+    // Prepare
+    class TestClassOutbound {
+      @validator({ outboundSchema })
+      async process(input: { text: string }): Promise<{ result: number }> {
+        return { result: 42 };
+      }
+    }
+    const instance = new TestClassOutbound();
+    const input = { text: 'hello' };
+    // Act
+    const output = await instance.process(input);
+    // Assess
+    expect(output).toEqual({ result: 42 });
+  });
+});

packages/validation/tests/unit/middleware.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { SchemaValidationError } from '../../src/errors.js';
+import { validationMiddleware } from '../../src/middleware.js';
+
+const inboundSchema = {
+  type: 'object',
+  properties: {
+    inputValue: { type: 'number' },
+  },
+  required: ['inputValue'],
+  additionalProperties: false,
+};
+
+const outboundSchema = {
+  type: 'object',
+  properties: {
+    outputValue: { type: 'number' },
+  },
+  required: ['outputValue'],
+  additionalProperties: false,
+};
+
+describe('validatorMiddleware', () => {
+  it('should validate inbound and outbound successfully', async () => {
+    // Prepare
+    const middleware = validationMiddleware({ inboundSchema, outboundSchema });
+    const handler = {
+      event: { inputValue: 10 },
+      response: { outputValue: 20 },
+    };
+    // Act
+    if (middleware.before) {
+      await middleware.before(handler);
+    }
+    if (middleware.after) {
+      await middleware.after(handler);
+    }
+    // Assess
+    expect(handler.event).toEqual({ inputValue: 10 });
+    expect(handler.response).toEqual({ outputValue: 20 });
+  });
+
+  it('should throw error on inbound validation failure', async () => {
+    // Prepare
+    const middleware = validationMiddleware({ inboundSchema });
+    const handler = {
+      event: { inputValue: 'invalid' },
+      response: {},
+    };
+    // Act & Assess
+    await expect(middleware.before?.(handler)).rejects.toThrow(
+      SchemaValidationError
+    );
+  });
+
+  it('should throw error on outbound validation failure', async () => {
+    // Prepare
+    const middleware = validationMiddleware({ outboundSchema });
+    const handler = {
+      event: {},
+      response: { outputValue: 'invalid' },
+    };
+    // Act & Assess
+    await expect(middleware.after?.(handler)).rejects.toThrow(
+      SchemaValidationError
+    );
+  });
+
+  it('should no-op when no schemas are provided', async () => {
+    // Prepare
+    const middleware = validationMiddleware({});
+    const handler = {
+      event: { someKey: 'value' },
+      response: { anotherKey: 'value' },
+    };
+    // Act
+    if (middleware.before) {
+      await middleware.before(handler);
+    }
+    if (middleware.after) {
+      await middleware.after(handler);
+    }
+    // Assess
+    expect(handler.event).toEqual({ someKey: 'value' });
+    expect(handler.response).toEqual({ anotherKey: 'value' });
+  });
+});