config-validation-and-normalization

Config Validation and Normalization

When implementing config files (e.g. prisma-next.config.ts), use Arktype for validation and normalization. This gives type safety, clear error messages, and sensible defaults.

Pattern: Validate + Normalize in defineConfig()

import { type } from 'arktype';
import { join, dirname } from 'node:path';

const ConfigSchema = type({
  required: 'string',
  'optional?': 'string',
  nested: type({ 'nestedOptional?': 'number' }),
});

export function defineConfig(config: ConfigInput): ConfigOutput {
  // 1. Validate structure with Arktype
  const validated = ConfigSchema(config);
  if (validated instanceof type.errors) {
    const messages = validated.map((p: { message: string }) => p.message).join('; ');
    throw new Error(`Config validation failed: ${messages}`);
  }
  // 2. Normalize by applying defaults
  const normalized: ConfigOutput = {
    ...config,
    optional: config.optional ?? 'default-value',
    nested: { ...config.nested, nestedOptional: config.nested?.nestedOptional ?? 42 },
  };
  // 3. Return the normalized IR (not the raw input)
  return normalized;
}

Validation catches structural errors early with clear messages; normalization applies defaults in one place; Arktype keeps structure aligned with TypeScript types.

Normalization Responsibilities

defineConfig() is the ONLY place normalization happens. It validates structure, applies defaults for optional fields, returns the normalized config IR, and throws on invalid structure. It should always output a fully normalized config. All other components assume configs are already normalized:

• Config loader — loading only. Loads the config file (c12 or similar) and calls defineConfig() to validate/normalize, then returns the result. Does NOT set defaults or normalize structure.
• Command handlers — using only. Use normalized values directly, accessing fields without checking for defaults. Do NOT set defaults or normalize structure.
• Validators. Never normalize.