feat: add Zod validation support for configuration schema

Author: iamnivekx

lib/conditional.module.ts

@@ -37,6 +37,7 @@ export class ConditionalModule {
     options?: { timeout?: number; debug?: boolean },
   ) {
     const { timeout = 5000, debug = true } = options ?? {};
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
     const moduleName = getInstanceName(module) || module.toString();
 
     const timer = setTimeout(() => {

lib/config.module.ts

@@ -14,7 +14,12 @@ import {
   VALIDATED_ENV_PROPNAME,
 } from './config.constants';
 import { ConfigService } from './config.service';
-import { ConfigFactory, ConfigModuleOptions } from './interfaces';
+import type {
+  ConfigFactory,
+  ConfigModuleOptions,
+  ValidationSchema,
+} from './interfaces';
+import { ValidatorFactory, Validator } from './validators';
 import { ConfigFactoryKeyHost } from './utils';
 import { createConfigProvider } from './utils/create-config-factory.util';
 import { getRegistrationToken } from './utils/get-registration-token.util';
@@ -78,8 +83,13 @@ export class ConfigModule {
       this.assignVariablesToProcess(validatedConfig);
     } else if (options.validationSchema) {
       const validationOptions = this.getSchemaValidationOptions(options);
-      const { error, value: validatedConfig } =
-        options.validationSchema.validate(config, validationOptions);
+
+      // Create validator from schema
+      const validator = this.createValidator(options.validationSchema);
+      const { error, value: validatedConfig } = validator.validate(
+        config,
+        validationOptions,
+      );
 
       if (error) {
         throw new Error(`Config validation error: ${error.message}`);
@@ -253,4 +263,9 @@ export class ConfigModule {
       allowUnknown: true,
     };
   }
+
+  private static createValidator(schema: ValidationSchema): Validator {
+    // Use the factory to create the appropriate validator
+    return ValidatorFactory.createValidator(schema);
+  }
 }

lib/index.ts

@@ -4,3 +4,4 @@ export * from './config.service';
 export * from './types';
 export * from './utils';
 export * from './interfaces';
+export * from './validators';

lib/interfaces/config-module-options.interface.ts

@@ -1,5 +1,6 @@
 import { DotenvExpandOptions } from 'dotenv-expand';
 import { ConfigFactory } from './config-factory.interface';
+import { ValidationSchema } from './validation-schema.interface';
 
 /**
  * @publicApi
@@ -61,9 +62,9 @@ export interface ConfigModuleOptions<
   skipProcessEnv?: boolean;
 
   /**
-   * Environment variables validation schema (Joi).
+   * Environment variables validation schema (Joi, Zod, or custom ValidationSchema).
    */
-  validationSchema?: any;
+  validationSchema?: ValidationSchema;
 
   /**
    * Schema validation options.

lib/interfaces/index.ts

@@ -1,3 +1,4 @@
 export * from './config-change-event.interface';
 export * from './config-factory.interface';
 export * from './config-module-options.interface';
+export * from './validation-schema.interface';

lib/interfaces/validation-schema.interface.ts

@@ -0,0 +1,49 @@
+/**
+ * @publicApi
+ */
+export interface ValidationSchema {
+  /**
+   * Validates the given configuration object
+   * @param config The configuration object to validate
+   * @param options Optional validation options
+   * @returns An object containing error (if any) and validated value
+   */
+  validate?(
+    config: Record<string, any>,
+    options?: Record<string, any>,
+  ): { error?: Error; value: Record<string, any> };
+
+  /**
+   * Parses and validates the given configuration object
+   * @param config The configuration object to parse and validate
+   * @param options Optional validation options
+   * @returns The validated configuration object
+   * @throws Error if validation fails
+   */
+  parse?(
+    config: Record<string, any>,
+    options?: Record<string, any>,
+  ): Record<string, any>;
+}
+
+/**
+ * @publicApi
+ */
+export interface ValidationOptions {
+  /**
+   * [Joi] Whether to allow unknown properties
+   * @default true
+   */
+  allowUnknown?: boolean;
+
+  /**
+   * [Joi] Whether to abort validation on first error
+   * @default false
+   */
+  abortEarly?: boolean;
+
+  /**
+   * Additional validation options specific to the validation library
+   */
+  [key: string]: any;
+}

lib/validators/abstract.validator.ts

@@ -0,0 +1,38 @@
+import { ValidationSchema } from '../interfaces/validation-schema.interface';
+
+/**
+ * @publicApi
+ */
+export abstract class Validator implements ValidationSchema {
+  validate(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _config: Record<string, any>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options?: Record<string, any>,
+  ): { error?: Error; value: Record<string, any> } {
+    throw new Error('Please implement the validate method');
+  }
+
+  succeed(result: unknown): {
+    error?: Error;
+    value?: Record<string, any>;
+  } {
+    return {
+      value: result as Record<string, any>,
+      error: undefined,
+    };
+  }
+
+  failed(
+    error: Error,
+    config: Record<string, any>,
+  ): {
+    error: Error;
+    value: Record<string, any>;
+  } {
+    return {
+      error: error instanceof Error ? error : new Error(String(error)),
+      value: config,
+    };
+  }
+}

lib/validators/index.ts

@@ -0,0 +1,4 @@
+export * from './abstract.validator';
+export * from './joi.validator';
+export * from './zod.validator';
+export * from './validator.factory';

lib/validators/joi.validator.ts

@@ -0,0 +1,50 @@
+import type { Schema as JoiSchema, ValidationResult } from 'joi';
+import { ValidationOptions } from '../interfaces/validation-schema.interface';
+import { Validator } from './abstract.validator';
+
+/**
+ * Joi validation schema adapter with validate method
+ *
+ * If you need parse method instead, implement the parse method:
+ *
+ * parse(config: Record<string, any>, options?: ValidationOptions): Record<string, any> {
+ *   const result = this.schema.validate(config, { ...this.options, ...options });
+ *   if (result.error) throw result.error;
+ *   return result.value;
+ * }
+ *
+ * @publicApi
+ */
+export class JoiValidator extends Validator {
+  constructor(private schema: JoiSchema) {
+    super();
+  }
+
+  validate(
+    config: Record<string, any>,
+    options?: ValidationOptions,
+  ): { error?: Error; value: Record<string, any> } {
+    const validationOptions = {
+      abortEarly: false,
+      allowUnknown: true,
+      ...options,
+    };
+
+    try {
+      const result = this.schema.validate(config, validationOptions);
+      return this.succeed(result);
+    } catch (error) {
+      return this.failed(error, config);
+    }
+  }
+
+  succeed(result: ValidationResult): {
+    error?: Error;
+    value: Record<string, any>;
+  } {
+    return {
+      error: result.error || undefined,
+      value: result.value,
+    };
+  }
+}

lib/validators/validator.factory.ts

@@ -0,0 +1,67 @@
+import { type Schema as JoiSchema } from 'joi';
+import { type ZodType } from 'zod';
+import { type ValidationSchema } from '../interfaces/validation-schema.interface';
+import { Validator } from './abstract.validator';
+import { JoiValidator } from './joi.validator';
+import { ZodValidator } from './zod.validator';
+
+/**
+ * Factory for creating validation schemas
+ * @publicApi
+ */
+export class ValidatorFactory {
+  /**
+   * Creates a Joi validator
+   * @param schema Joi schema
+   * @returns JoiValidator instance
+   */
+  static createJoiValidator(schema: JoiSchema): Validator {
+    return new JoiValidator(schema);
+  }
+
+  /**
+   * Creates a Zod validator
+   * @param schema Zod schema
+   * @returns ZodValidator instance
+   */
+  static createZodValidator(schema: ZodType): Validator {
+    return new ZodValidator(schema);
+  }
+
+  /**
+   * Creates a validator from a schema object
+   * Automatically detects the schema type based on the schema object
+   * @param schema Schema object (Joi or Zod)
+   * @returns ValidationSchema instance
+   */
+  static createValidator(schema: ValidationSchema): Validator {
+    // Check if it's a validator instance
+    if (schema instanceof Validator) {
+      return schema;
+    }
+
+    // Check if it's a Joi schema first
+    if (
+      schema &&
+      typeof schema === 'object' &&
+      'validate' in schema &&
+      typeof schema.validate === 'function'
+    ) {
+      return this.createJoiValidator(schema as JoiSchema);
+    }
+
+    // Check if it's a Zod schema
+    if (
+      schema &&
+      typeof schema === 'object' &&
+      'parse' in schema &&
+      typeof schema.parse === 'function'
+    ) {
+      return this.createZodValidator(schema as ZodType);
+    }
+
+    throw new Error(
+      'Unsupported schema type. Please use Joi or Zod schema or implement the validator directly.',
+    );
+  }
+}