@africode/core 5.0.0

package/core/validation.js

@@ -0,0 +1,590 @@
+/**
+ * AfriCode Validation System
+ *
+ * Philosophy: Strict by default. Convenient by composition. Secure early.
+ *
+ * Core validation is strict — URL fields accept only valid URLs.
+ * Normalization (e.g. empty string → null) is explicit and opt-in.
+ * Security basics (CSRF, rate limiting) are built into the foundation.
+ *
+ * Provides:
+ * - Zod-based validation schemas for forms, auth, and API validation
+ * - AfriFieldBuilder: chainable field builder with .nullable(), .emptyAsNull(), .optional()
+ * - afri namespace: factory for building field schemas (afri.url(), afri.string(), etc.)
+ * - normalizeInput(): preprocessing utility that runs before validation
+ *
+ * @module core/validation
+ */
+
+import { z } from 'zod';
+import { getConfig } from './config.js';
+
+/**
+ * Common validation schemas for AfriCode components
+ */
+export const schemas = {
+  // User authentication schemas
+  login: z.object({
+    email: z.string()
+      .min(1, 'Email is required')
+      .email('Please enter a valid email address'),
+    password: z.string()
+      .min(8, 'Password must be at least 8 characters')
+      .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
+        'Password must contain at least one uppercase letter, one lowercase letter, and one number')
+  }),
+
+  register: z.object({
+    name: z.string()
+      .min(2, 'Name must be at least 2 characters')
+      .max(50, 'Name must be less than 50 characters')
+      .regex(/^[a-zA-Z\s'-]+$/, 'Name can only contain letters, spaces, hyphens, and apostrophes'),
+    email: z.string()
+      .min(1, 'Email is required')
+      .email('Please enter a valid email address'),
+    password: z.string()
+      .min(8, 'Password must be at least 8 characters')
+      .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/,
+        'Password must contain uppercase, lowercase, number, and special character'),
+    confirmPassword: z.string()
+  }).refine(data => data.password === data.confirmPassword, {
+    message: "Passwords don't match",
+    path: ["confirmPassword"]
+  }),
+
+  auth: {
+    register: z.object({
+      action: z.literal('register'),
+      email: z.string()
+        .min(1, 'Email is required')
+        .email('Please enter a valid email address'),
+      username: z.string()
+        .min(3, 'Username must be at least 3 characters')
+        .max(30, 'Username must be less than 30 characters'),
+      password: z.string()
+        .min(8, 'Password must be at least 8 characters'),
+      full_name: z.string()
+        .min(2, 'Full name is required')
+        .max(100, 'Full name is too long')
+    }),
+
+    login: z.object({
+      action: z.literal('login'),
+      email: z.string()
+        .min(1, 'Email is required')
+        .email('Please enter a valid email address'),
+      password: z.string()
+        .min(8, 'Password must be at least 8 characters')
+    }),
+
+    logout: z.object({
+      action: z.literal('logout')
+    }),
+
+    action: z.discriminatedUnion('action', [
+      z.object({ action: z.literal('register') }).merge(z.object({
+        email: z.string()
+          .min(1, 'Email is required')
+          .email('Please enter a valid email address'),
+        username: z.string()
+          .min(3, 'Username must be at least 3 characters')
+          .max(30, 'Username must be less than 30 characters'),
+        password: z.string()
+          .min(8, 'Password must be at least 8 characters'),
+        full_name: z.string()
+          .min(2, 'Full name is required')
+          .max(100, 'Full name is too long')
+      })),
+      z.object({ action: z.literal('login') }).merge(z.object({
+        email: z.string()
+          .min(1, 'Email is required')
+          .email('Please enter a valid email address'),
+        password: z.string()
+          .min(8, 'Password must be at least 8 characters')
+      })),
+      z.object({ action: z.literal('logout') })
+    ])
+  },
+
+  // Form input schemas
+  contact: z.object({
+    name: z.string()
+      .min(2, 'Name must be at least 2 characters')
+      .max(100, 'Name is too long'),
+    email: z.string()
+      .email('Please enter a valid email address'),
+    message: z.string()
+      .min(10, 'Message must be at least 10 characters')
+      .max(1000, 'Message is too long')
+  }),
+
+  // Generic input validation
+  email: z.string()
+    .min(1, 'Email is required')
+    .email('Please enter a valid email address'),
+
+  password: z.string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
+      'Password must contain uppercase, lowercase, and number'),
+
+  phone: z.string()
+    .regex(/^[\+]?[1-9][\d]{0,15}$/, 'Please enter a valid phone number'),
+
+  // Strict URL: must be a valid URL. Use afri.url().nullable() for nullable URLs.
+  url: z.string()
+    .min(1, 'URL is required')
+    .url('Please enter a valid URL'),
+
+  required: z.string()
+    .min(1, 'This field is required'),
+
+  // Number validations
+  positiveNumber: z.number()
+    .positive('Must be a positive number'),
+
+  integer: z.number()
+    .int('Must be a whole number'),
+
+  // Date validations
+  futureDate: z.date()
+    .min(new Date(), 'Date must be in the future'),
+
+  // File validations
+  imageFile: z.instanceof(File)
+    .refine(file => file.size <= 5 * 1024 * 1024, 'File size must be less than 5MB')
+    .refine(file => ['image/jpeg', 'image/png', 'image/gif', 'image/webp'].includes(file.type),
+      'File must be a JPEG, PNG, GIF, or WebP image'),
+
+  // --- DB Model Schemas ---
+
+  /**
+   * User profile update schema.
+   * avatar_url: valid URL or null (with opt-in empty-string normalization)
+   */
+  userProfile: z.object({
+    full_name: z.string().min(2, 'Full name must be at least 2 characters').max(100, 'Full name is too long').optional(),
+    bio: z.string().max(500, 'Bio must be less than 500 characters').nullable().optional(),
+    avatar_url: z.string().url('Please enter a valid URL').nullable().optional(),
+    theme: z.enum(['africanity', 'dark', 'light', 'system']).optional(),
+    language: z.string().min(2).max(10).optional()
+  }),
+
+  /**
+   * Project creation/update schema.
+   * repository_url, demo_url: valid URL or null
+   */
+  project: z.object({
+    name: z.string().min(1, 'Project name is required').max(100, 'Project name is too long'),
+    description: z.string().max(1000, 'Description is too long').nullable().optional(),
+    repository_url: z.string().url('Please enter a valid repository URL').nullable().optional(),
+    demo_url: z.string().url('Please enter a valid demo URL').nullable().optional(),
+    tags: z.array(z.string()).optional(),
+    is_public: z.boolean().optional()
+  })
+};
+
+/**
+ * Validation utilities
+ */
+export class Validation {
+  /**
+   * Validate data against a schema
+   * @param {z.ZodSchema} schema - Zod schema to validate against
+   * @param {any} data - Data to validate
+   * @returns {Object} { success: boolean, data?: any, errors?: Object }
+   */
+  static validate(schema, data) {
+    try {
+      const result = schema.parse(data);
+      return { success: true, data: result };
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const errors = {};
+        error.errors.forEach(err => {
+          const path = err.path.join('.');
+          errors[path] = err.message;
+        });
+        return { success: false, errors };
+      }
+      return { success: false, errors: { general: 'Validation failed' } };
+    }
+  }
+
+  /**
+   * Validate a single field
+   * @param {z.ZodSchema} schema - Field schema
+   * @param {any} value - Field value
+   * @returns {Object} { success: boolean, error?: string }
+   */
+  static validateField(schema, value) {
+    try {
+      schema.parse(value);
+      return { success: true };
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return { success: false, error: error.errors[0]?.message || 'Invalid value' };
+      }
+      return { success: false, error: 'Validation failed' };
+    }
+  }
+
+  /**
+   * Get validation error message for a field
+   * @param {Object} validationResult - Result from validate()
+   * @param {string} fieldPath - Dot notation field path
+   * @returns {string|null} Error message or null
+   */
+  static getFieldError(validationResult, fieldPath) {
+    if (validationResult.success) {return null;}
+    return validationResult.errors?.[fieldPath] || null;
+  }
+
+  /**
+   * Check if a field has validation errors
+   * @param {Object} validationResult - Result from validate()
+   * @param {string} fieldPath - Dot notation field path
+   * @returns {boolean} True if field has errors
+   */
+  static hasFieldError(validationResult, fieldPath) {
+    return !!this.getFieldError(validationResult, fieldPath);
+  }
+}
+
+/**
+ * Predefined validation rules for common use cases
+ */
+export const rules = {
+  required: (message = 'This field is required') =>
+    z.string().min(1, message),
+
+  email: (message = 'Please enter a valid email address') =>
+    z.string().email(message),
+
+  minLength: (min, message) =>
+    z.string().min(min, message || `Must be at least ${min} characters`),
+
+  maxLength: (max, message) =>
+    z.string().max(max, message || `Must be less than ${max} characters`),
+
+  pattern: (regex, message) =>
+    z.string().regex(regex, message),
+
+  numeric: (message = 'Must be a number') =>
+    z.string().regex(/^\d+$/, message),
+
+  phone: (message = 'Please enter a valid phone number') =>
+    z.string().regex(/^[\+]?[1-9][\d]{0,15}$/, message),
+
+  url: (message = 'Please enter a valid URL') =>
+    z.string().min(1, 'URL is required').url(message)
+};
+
+// ─────────────────────────────────────────────────────────────
+// AfriFieldBuilder — Chainable field schema builder
+//
+// Design: Strict by default. Convenient by composition.
+//
+// Usage:
+//   afri.url()                          → valid URL, required
+//   afri.url().nullable()               → valid URL or null
+//   afri.url().nullable().emptyAsNull()  → "" → null, then validates
+//   afri.url().optional()               → valid URL or undefined
+//   afri.string().trim()                → trim whitespace in normalizeInput
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Chainable field builder for AfriCode validation schemas.
+ * Wraps Zod with framework-level semantics.
+ *
+ * IMPORTANT: .emptyAsNull() does NOT alter the Zod schema itself.
+ * It marks the field for preprocessing via normalizeInput().
+ * Validation remains strict — the preprocessing layer is separate.
+ */
+export class AfriFieldBuilder {
+  /**
+   * @param {z.ZodSchema} baseSchema - The base Zod schema for this field
+   * @param {string} fieldType - The field type identifier (e.g. 'url', 'email')
+   */
+  constructor(baseSchema, fieldType = 'string') {
+    this._baseSchema = baseSchema;
+    this._fieldType = fieldType;
+    this._isNullable = false;
+    this._isOptional = false;
+    this._emptyAsNull = false;
+    this._trim = false;
+    this._customMessage = null;
+  }
+
+  /**
+   * Allow null as a valid value.
+   * @returns {AfriFieldBuilder}
+   */
+  nullable() {
+    this._isNullable = true;
+    return this;
+  }
+
+  /**
+   * Allow undefined (field can be omitted).
+   * @returns {AfriFieldBuilder}
+   */
+  optional() {
+    this._isOptional = true;
+    return this;
+  }
+
+  /**
+   * Mark this field for empty-string-to-null conversion.
+   * REQUIRES .nullable() to have been called first.
+   * The conversion happens in normalizeInput(), not in the Zod schema.
+   *
+   * @returns {AfriFieldBuilder}
+   * @throws {Error} If .nullable() was not called first
+   */
+  emptyAsNull() {
+    if (!this._isNullable) {
+      throw new Error(
+        `[AfriCode] .emptyAsNull() requires .nullable() to be called first. ` +
+        `Use: afri.${this._fieldType}().nullable().emptyAsNull()`
+      );
+    }
+    this._emptyAsNull = true;
+    return this;
+  }
+
+  /**
+   * Mark this field for whitespace trimming.
+   * The trimming happens in normalizeInput(), not in the Zod schema.
+   * "  hello  " → "hello"
+   *
+   * @returns {AfriFieldBuilder}
+   */
+  trim() {
+    this._trim = true;
+    return this;
+  }
+
+  /**
+   * Set a custom error message for the base validation.
+   * @param {string} message
+   * @returns {AfriFieldBuilder}
+   */
+  message(message) {
+    this._customMessage = message;
+    return this;
+  }
+
+  /**
+   * Build the final Zod schema.
+   * @returns {z.ZodSchema}
+   */
+  build() {
+    let schema = this._baseSchema;
+
+    if (this._isNullable) {
+      schema = schema.nullable();
+    }
+
+    if (this._isOptional) {
+      schema = schema.optional();
+    }
+
+    return schema;
+  }
+
+  /**
+   * Get the metadata for this field (used by normalizeInput).
+   * @returns {Object}
+   */
+  getMeta() {
+    return {
+      fieldType: this._fieldType,
+      isNullable: this._isNullable,
+      isOptional: this._isOptional,
+      emptyAsNull: this._emptyAsNull,
+      trim: this._trim
+    };
+  }
+}
+
+/**
+ * AfriCode field factory namespace.
+ * Creates AfriFieldBuilder instances for common field types.
+ *
+ * @example
+ * // Strict URL — required, only valid URLs accepted
+ * const urlField = afri.url().build();
+ *
+ * @example
+ * // Nullable URL — valid URL or null
+ * const avatarField = afri.url().nullable().build();
+ *
+ * @example
+ * // Nullable URL with empty-string normalization
+ * const avatarField = afri.url().nullable().emptyAsNull().build();
+ */
+export const afri = {
+  /**
+   * Create a strict URL field builder.
+   * Empty strings are always rejected at the core.
+   * @param {string} [message='Please enter a valid URL']
+   * @returns {AfriFieldBuilder}
+   */
+  url(message = 'Please enter a valid URL') {
+    return new AfriFieldBuilder(
+      z.string().min(1, 'URL cannot be empty').url(message),
+      'url'
+    );
+  },
+
+  /**
+   * Create a strict email field builder.
+   * @param {string} [message='Please enter a valid email address']
+   * @returns {AfriFieldBuilder}
+   */
+  email(message = 'Please enter a valid email address') {
+    return new AfriFieldBuilder(
+      z.string().min(1, 'Email cannot be empty').email(message),
+      'email'
+    );
+  },
+
+  /**
+   * Create a string field builder.
+   * @param {Object} [opts]
+   * @param {number} [opts.min] - Minimum length
+   * @param {number} [opts.max] - Maximum length
+   * @param {string} [opts.message] - Custom error message
+   * @returns {AfriFieldBuilder}
+   */
+  string(opts = {}) {
+    let schema = z.string();
+    if (opts.min !== undefined) {schema = schema.min(opts.min, opts.message || `Must be at least ${opts.min} characters`);}
+    if (opts.max !== undefined) {schema = schema.max(opts.max, opts.message || `Must be less than ${opts.max} characters`);}
+    return new AfriFieldBuilder(schema, 'string');
+  },
+
+  /**
+   * Create a number field builder.
+   * @param {Object} [opts]
+   * @param {number} [opts.min] - Minimum value
+   * @param {number} [opts.max] - Maximum value
+   * @param {boolean} [opts.int] - Must be integer
+   * @returns {AfriFieldBuilder}
+   */
+  number(opts = {}) {
+    let schema = z.number();
+    if (opts.min !== undefined) {schema = schema.min(opts.min);}
+    if (opts.max !== undefined) {schema = schema.max(opts.max);}
+    if (opts.int) {schema = schema.int('Must be a whole number');}
+    return new AfriFieldBuilder(schema, 'number');
+  },
+
+  /**
+   * Create a phone field builder.
+   * @param {string} [message='Please enter a valid phone number']
+   * @returns {AfriFieldBuilder}
+   */
+  phone(message = 'Please enter a valid phone number') {
+    return new AfriFieldBuilder(
+      z.string().regex(/^[\+]?[1-9][\d]{0,15}$/, message),
+      'phone'
+    );
+  }
+};
+
+/**
+ * Normalize input data before validation.
+ *
+ * This is the preprocessing layer. It examines field metadata from
+ * AfriFieldBuilder instances and applies transformations:
+ *
+ * 1. Trim whitespace (if .trim() or config.validation.trimStrings)
+ * 2. Convert "" → null (if .emptyAsNull())
+ *
+ * Order matters: trim runs BEFORE emptyAsNull so that
+ * "   " → "" → null works correctly.
+ *
+ * Separation of concerns:
+ * - normalizeInput() = input adapter (flexible)
+ * - Validation.validate() = core validation (strict)
+ *
+ * @param {Object} fieldBuilders - Map of field names to AfriFieldBuilder instances
+ * @param {Object} data - Raw input data (e.g. form submission)
+ * @returns {Object} Normalized data ready for validation
+ *
+ * @example
+ * const fields = {
+ *   avatar_url: afri.url().nullable().emptyAsNull(),
+ *   name: afri.string({ min: 2 }).trim(),
+ *   bio: afri.string({ max: 500 }).nullable()
+ * };
+ *
+ * const raw = { avatar_url: '', name: '  AfriCode  ', bio: 'Hello' };
+ * const cleaned = normalizeInput(fields, raw);
+ * // → { avatar_url: null, name: 'AfriCode', bio: 'Hello' }
+ */
+export function normalizeInput(fieldBuilders, data) {
+  const result = { ...data };
+  let globalTrim = false;
+
+  // Check framework config for global trim setting
+  try {
+    const config = getConfig();
+    globalTrim = config.validation?.trimStrings === true;
+  } catch {
+    // Config not initialized yet — use defaults (no global trim)
+  }
+
+  for (const [fieldName, builder] of Object.entries(fieldBuilders)) {
+    if (!(builder instanceof AfriFieldBuilder)) {continue;}
+
+    const meta = builder.getMeta();
+    const value = result[fieldName];
+
+    // Step 1: Trim whitespace (per-field .trim() or global config)
+    if (typeof value === 'string' && (meta.trim || globalTrim)) {
+      result[fieldName] = value.trim();
+    }
+
+    // Step 2: Convert empty string to null (per-field .emptyAsNull())
+    if (meta.emptyAsNull && result[fieldName] === '') {
+      result[fieldName] = null;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a Zod object schema from a map of AfriFieldBuilder instances.
+ * Convenience method to go from builders → Zod schema in one step.
+ *
+ * @param {Object} fieldBuilders - Map of field names to AfriFieldBuilder instances
+ * @returns {z.ZodObject}
+ *
+ * @example
+ * const schema = buildSchema({
+ *   avatar_url: afri.url().nullable().emptyAsNull(),
+ *   name: afri.string({ min: 2, max: 50 })
+ * });
+ *
+ * const result = Validation.validate(schema, data);
+ */
+export function buildSchema(fieldBuilders) {
+  const shape = {};
+
+  for (const [fieldName, builder] of Object.entries(fieldBuilders)) {
+    if (builder instanceof AfriFieldBuilder) {
+      shape[fieldName] = builder.build();
+    } else {
+      // Allow raw Zod schemas to be mixed in
+      shape[fieldName] = builder;
+    }
+  }
+
+  return z.object(shape);
+}
+
+export default { schemas, Validation, rules, afri, AfriFieldBuilder, normalizeInput, buildSchema };