voltjs-framework 1.0.0

package/src/utils/schema.js

@@ -0,0 +1,985 @@
+/**
+ * VoltJS Schema Builder (Zod/Yup Alternative)
+ * 
+ * Type-safe, chainable, composable schema validation with transforms.
+ * 
+ * @example
+ * const { Schema } = require('voltjs');
+ * 
+ * const userSchema = Schema.object({
+ *   name: Schema.string().min(2).max(50).required(),
+ *   email: Schema.string().email().required(),
+ *   age: Schema.number().int().min(18).max(120).optional(),
+ *   role: Schema.enum(['admin', 'user', 'editor']).default('user'),
+ *   tags: Schema.array(Schema.string()).min(1),
+ *   address: Schema.object({
+ *     street: Schema.string(),
+ *     city: Schema.string().required(),
+ *     zip: Schema.string().regex(/^\d{5}$/),
+ *   }).optional(),
+ * });
+ * 
+ * const result = userSchema.validate(data);
+ * // { valid: true, data: { ... } } or { valid: false, errors: { ... } }
+ * 
+ * const parsed = userSchema.parse(data); // throws on invalid
+ */
+
+'use strict';
+
+// ============================================
+// BASE SCHEMA
+// ============================================
+
+class BaseSchema {
+  constructor() {
+    this._checks = [];
+    this._required = false;
+    this._optional = false;
+    this._nullable = false;
+    this._default = undefined;
+    this._hasDefault = false;
+    this._transforms = [];
+    this._label = null;
+    this._messages = {};
+  }
+
+  /** Mark as required */
+  required(message) {
+    this._required = true;
+    this._optional = false;
+    if (message) this._messages.required = message;
+    return this;
+  }
+
+  /** Mark as optional */
+  optional() {
+    this._optional = true;
+    this._required = false;
+    return this;
+  }
+
+  /** Allow null */
+  nullable() {
+    this._nullable = true;
+    return this;
+  }
+
+  /** Set default value */
+  default(value) {
+    this._default = value;
+    this._hasDefault = true;
+    return this;
+  }
+
+  /** Set label for error messages */
+  label(name) {
+    this._label = name;
+    return this;
+  }
+
+  /** Custom error message override */
+  message(key, msg) {
+    this._messages[key] = msg;
+    return this;
+  }
+
+  /** Add a transform (applied before validation) */
+  transform(fn) {
+    this._transforms.push(fn);
+    return this;
+  }
+
+  /** Add a custom validation check */
+  refine(fn, message = 'Validation failed') {
+    this._checks.push({
+      name: 'custom',
+      fn,
+      message: typeof message === 'string' ? message : message.message || 'Validation failed',
+    });
+    return this;
+  }
+
+  /** Alias for refine */
+  test(name, message, fn) {
+    this._checks.push({ name, fn, message });
+    return this;
+  }
+
+  /** Internal: get label for error messages */
+  _getLabel(fallback = 'Value') {
+    return this._label || fallback;
+  }
+
+  /** Internal: get custom message or default */
+  _msg(key, defaultMsg) {
+    return this._messages[key] || defaultMsg;
+  }
+
+  /** Apply transforms */
+  _applyTransforms(value) {
+    let result = value;
+    for (const fn of this._transforms) {
+      result = fn(result);
+    }
+    return result;
+  }
+
+  /** Core validate logic (override in subclasses) */
+  _validate(value, path = '') {
+    const label = this._getLabel(path || 'Value');
+    const errors = [];
+
+    // Handle undefined/null
+    if (value === undefined || value === null || value === '') {
+      if (this._nullable && value === null) return { valid: true, value: null };
+      if (this._hasDefault) return { valid: true, value: this._default };
+      if (this._required) {
+        errors.push(this._msg('required', `${label} is required`));
+        return { valid: false, errors };
+      }
+      if (this._optional) return { valid: true, value: undefined };
+      // Default: treat as optional
+      return { valid: true, value: undefined };
+    }
+
+    // Apply transforms
+    value = this._applyTransforms(value);
+
+    // Type-specific validation
+    const typeResult = this._validateType(value, label);
+    if (typeResult) {
+      if (Array.isArray(typeResult)) {
+        errors.push(...typeResult);
+      } else {
+        errors.push(typeResult);
+      }
+    }
+
+    // Run custom checks
+    for (const check of this._checks) {
+      try {
+        const result = check.fn(value);
+        if (result === false) {
+          errors.push(check.message.replace('{label}', label));
+        }
+      } catch (err) {
+        errors.push(err.message || check.message);
+      }
+    }
+
+    return errors.length > 0
+      ? { valid: false, errors }
+      : { valid: true, value };
+  }
+
+  /** Override in subclasses for type-specific validation */
+  _validateType(value, label) {
+    return null;
+  }
+
+  /** Validate and return result */
+  validate(value, path = '') {
+    return this._validate(value, path);
+  }
+
+  /** Validate — throw if invalid */
+  parse(value) {
+    const result = this._validate(value);
+    if (!result.valid) {
+      const err = new Error('Schema validation failed');
+      err.errors = result.errors;
+      throw err;
+    }
+    return result.value;
+  }
+
+  /** Validate — return undefined instead of throwing */
+  safeParse(value) {
+    return this._validate(value);
+  }
+}
+
+// ============================================
+// STRING SCHEMA
+// ============================================
+
+class StringSchema extends BaseSchema {
+  constructor() {
+    super();
+    this._coerce = false;
+  }
+
+  /** Coerce value to string */
+  coerce() {
+    this._coerce = true;
+    return this;
+  }
+
+  min(n, message) {
+    this._checks.push({ name: 'min', fn: v => v.length >= n, message: message || `Must be at least ${n} characters` });
+    return this;
+  }
+
+  max(n, message) {
+    this._checks.push({ name: 'max', fn: v => v.length <= n, message: message || `Must be at most ${n} characters` });
+    return this;
+  }
+
+  length(n, message) {
+    this._checks.push({ name: 'length', fn: v => v.length === n, message: message || `Must be exactly ${n} characters` });
+    return this;
+  }
+
+  email(message) {
+    this._checks.push({ name: 'email', fn: v => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v), message: message || 'Must be a valid email' });
+    return this;
+  }
+
+  url(message) {
+    this._checks.push({ name: 'url', fn: v => { try { new URL(v); return true; } catch { return false; } }, message: message || 'Must be a valid URL' });
+    return this;
+  }
+
+  uuid(message) {
+    this._checks.push({ name: 'uuid', fn: v => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v), message: message || 'Must be a valid UUID' });
+    return this;
+  }
+
+  regex(pattern, message) {
+    this._checks.push({ name: 'regex', fn: v => pattern.test(v), message: message || `Must match pattern ${pattern}` });
+    return this;
+  }
+
+  includes(substr, message) {
+    this._checks.push({ name: 'includes', fn: v => v.includes(substr), message: message || `Must include "${substr}"` });
+    return this;
+  }
+
+  startsWith(prefix, message) {
+    this._checks.push({ name: 'startsWith', fn: v => v.startsWith(prefix), message: message || `Must start with "${prefix}"` });
+    return this;
+  }
+
+  endsWith(suffix, message) {
+    this._checks.push({ name: 'endsWith', fn: v => v.endsWith(suffix), message: message || `Must end with "${suffix}"` });
+    return this;
+  }
+
+  ip(message) {
+    this._checks.push({ name: 'ip', fn: v => /^(\d{1,3}\.){3}\d{1,3}$/.test(v), message: message || 'Must be a valid IP address' });
+    return this;
+  }
+
+  phone(message) {
+    this._checks.push({ name: 'phone', fn: v => /^\+?[\d\s()-]{7,15}$/.test(v), message: message || 'Must be a valid phone number' });
+    return this;
+  }
+
+  creditCard(message) {
+    this._checks.push({
+      name: 'creditCard',
+      fn: v => {
+        const cleaned = v.replace(/[\s-]/g, '');
+        if (!/^\d{13,19}$/.test(cleaned)) return false;
+        let sum = 0, alt = false;
+        for (let i = cleaned.length - 1; i >= 0; i--) {
+          let n = parseInt(cleaned[i]);
+          if (alt) { n *= 2; if (n > 9) n -= 9; }
+          sum += n;
+          alt = !alt;
+        }
+        return sum % 10 === 0;
+      },
+      message: message || 'Must be a valid credit card number',
+    });
+    return this;
+  }
+
+  /** Trim whitespace (transform) */
+  trim() {
+    return this.transform(v => typeof v === 'string' ? v.trim() : v);
+  }
+
+  /** Convert to lowercase (transform) */
+  toLowerCase() {
+    return this.transform(v => typeof v === 'string' ? v.toLowerCase() : v);
+  }
+
+  /** Convert to uppercase (transform) */
+  toUpperCase() {
+    return this.transform(v => typeof v === 'string' ? v.toUpperCase() : v);
+  }
+
+  /** Allow only alphanumeric */
+  alphanumeric(message) {
+    this._checks.push({ name: 'alphanumeric', fn: v => /^[a-zA-Z0-9]+$/.test(v), message: message || 'Must be alphanumeric' });
+    return this;
+  }
+
+  /** Slug format */
+  slug(message) {
+    this._checks.push({ name: 'slug', fn: v => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v), message: message || 'Must be a valid slug' });
+    return this;
+  }
+
+  /** Non-empty (at least one non-whitespace character) */
+  nonempty(message) {
+    this._checks.push({ name: 'nonempty', fn: v => v.trim().length > 0, message: message || 'Must not be empty' });
+    return this;
+  }
+
+  _validateType(value, label) {
+    if (this._coerce) value = String(value);
+    if (typeof value !== 'string') {
+      return this._msg('type', `${label} must be a string`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    if (this._coerce && value !== undefined && value !== null) {
+      value = String(value);
+    }
+    return super._validate(value, path);
+  }
+}
+
+// ============================================
+// NUMBER SCHEMA
+// ============================================
+
+class NumberSchema extends BaseSchema {
+  constructor() {
+    super();
+    this._coerce = false;
+  }
+
+  coerce() {
+    this._coerce = true;
+    return this;
+  }
+
+  min(n, message) {
+    this._checks.push({ name: 'min', fn: v => v >= n, message: message || `Must be at least ${n}` });
+    return this;
+  }
+
+  max(n, message) {
+    this._checks.push({ name: 'max', fn: v => v <= n, message: message || `Must be at most ${n}` });
+    return this;
+  }
+
+  int(message) {
+    this._checks.push({ name: 'int', fn: v => Number.isInteger(v), message: message || 'Must be an integer' });
+    return this;
+  }
+
+  positive(message) {
+    this._checks.push({ name: 'positive', fn: v => v > 0, message: message || 'Must be positive' });
+    return this;
+  }
+
+  negative(message) {
+    this._checks.push({ name: 'negative', fn: v => v < 0, message: message || 'Must be negative' });
+    return this;
+  }
+
+  nonnegative(message) {
+    this._checks.push({ name: 'nonnegative', fn: v => v >= 0, message: message || 'Must be non-negative' });
+    return this;
+  }
+
+  finite(message) {
+    this._checks.push({ name: 'finite', fn: v => Number.isFinite(v), message: message || 'Must be finite' });
+    return this;
+  }
+
+  multipleOf(n, message) {
+    this._checks.push({ name: 'multipleOf', fn: v => v % n === 0, message: message || `Must be a multiple of ${n}` });
+    return this;
+  }
+
+  port(message) {
+    return this.int().min(0).max(65535);
+  }
+
+  _validateType(value, label) {
+    if (typeof value !== 'number' || isNaN(value)) {
+      return this._msg('type', `${label} must be a number`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    if (this._coerce && value !== undefined && value !== null) {
+      const num = Number(value);
+      if (!isNaN(num)) value = num;
+    }
+    return super._validate(value, path);
+  }
+}
+
+// ============================================
+// BOOLEAN SCHEMA
+// ============================================
+
+class BooleanSchema extends BaseSchema {
+  constructor() {
+    super();
+    this._coerce = false;
+  }
+
+  coerce() {
+    this._coerce = true;
+    return this;
+  }
+
+  _validateType(value, label) {
+    if (typeof value !== 'boolean') {
+      return this._msg('type', `${label} must be a boolean`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    if (this._coerce && value !== undefined && value !== null) {
+      if (value === 'true' || value === '1' || value === 1) value = true;
+      else if (value === 'false' || value === '0' || value === 0) value = false;
+    }
+    return super._validate(value, path);
+  }
+}
+
+// ============================================
+// DATE SCHEMA
+// ============================================
+
+class DateSchema extends BaseSchema {
+  constructor() {
+    super();
+    this._coerce = false;
+  }
+
+  coerce() {
+    this._coerce = true;
+    return this;
+  }
+
+  min(date, message) {
+    const d = new Date(date);
+    this._checks.push({ name: 'min', fn: v => new Date(v) >= d, message: message || `Must be after ${d.toISOString()}` });
+    return this;
+  }
+
+  max(date, message) {
+    const d = new Date(date);
+    this._checks.push({ name: 'max', fn: v => new Date(v) <= d, message: message || `Must be before ${d.toISOString()}` });
+    return this;
+  }
+
+  past(message) {
+    this._checks.push({ name: 'past', fn: v => new Date(v) < new Date(), message: message || 'Must be in the past' });
+    return this;
+  }
+
+  future(message) {
+    this._checks.push({ name: 'future', fn: v => new Date(v) > new Date(), message: message || 'Must be in the future' });
+    return this;
+  }
+
+  _validateType(value, label) {
+    const d = value instanceof Date ? value : new Date(value);
+    if (isNaN(d.getTime())) {
+      return this._msg('type', `${label} must be a valid date`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    if (this._coerce && typeof value === 'string') {
+      const d = new Date(value);
+      if (!isNaN(d.getTime())) value = d;
+    }
+    return super._validate(value, path);
+  }
+}
+
+// ============================================
+// ARRAY SCHEMA
+// ============================================
+
+class ArraySchema extends BaseSchema {
+  constructor(itemSchema = null) {
+    super();
+    this._itemSchema = itemSchema;
+  }
+
+  min(n, message) {
+    this._checks.push({ name: 'min', fn: v => v.length >= n, message: message || `Must have at least ${n} items` });
+    return this;
+  }
+
+  max(n, message) {
+    this._checks.push({ name: 'max', fn: v => v.length <= n, message: message || `Must have at most ${n} items` });
+    return this;
+  }
+
+  length(n, message) {
+    this._checks.push({ name: 'length', fn: v => v.length === n, message: message || `Must have exactly ${n} items` });
+    return this;
+  }
+
+  nonempty(message) {
+    return this.min(1, message || 'Must not be empty');
+  }
+
+  unique(message) {
+    this._checks.push({
+      name: 'unique',
+      fn: v => new Set(v.map(i => JSON.stringify(i))).size === v.length,
+      message: message || 'Must contain unique items',
+    });
+    return this;
+  }
+
+  _validateType(value, label) {
+    if (!Array.isArray(value)) {
+      return this._msg('type', `${label} must be an array`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    const baseResult = super._validate(value, path);
+    if (!baseResult.valid) return baseResult;
+    if (baseResult.value === undefined) return baseResult;
+
+    // Validate each item if item schema provided
+    if (this._itemSchema && Array.isArray(baseResult.value)) {
+      const errors = [];
+      const transformed = [];
+
+      for (let i = 0; i < baseResult.value.length; i++) {
+        const itemResult = this._itemSchema.validate(baseResult.value[i], `${path || 'Array'}[${i}]`);
+        if (!itemResult.valid) {
+          errors.push(...itemResult.errors.map(e => `[${i}]: ${e}`));
+        } else {
+          transformed.push(itemResult.value);
+        }
+      }
+
+      if (errors.length > 0) {
+        return { valid: false, errors };
+      }
+      return { valid: true, value: transformed };
+    }
+
+    return baseResult;
+  }
+}
+
+// ============================================
+// OBJECT SCHEMA
+// ============================================
+
+class ObjectSchema extends BaseSchema {
+  constructor(shape = {}) {
+    super();
+    this._shape = shape;
+    this._strict = false;
+    this._passthrough = false;
+  }
+
+  /** Reject unknown keys */
+  strict() {
+    this._strict = true;
+    this._passthrough = false;
+    return this;
+  }
+
+  /** Allow and pass through unknown keys */
+  passthrough() {
+    this._passthrough = true;
+    this._strict = false;
+    return this;
+  }
+
+  /** Add or override schema for a key */
+  extend(shape) {
+    return new ObjectSchema({ ...this._shape, ...shape });
+  }
+
+  /** Pick specific keys (returns new schema) */
+  pick(keys) {
+    const newShape = {};
+    for (const key of keys) {
+      if (this._shape[key]) newShape[key] = this._shape[key];
+    }
+    return new ObjectSchema(newShape);
+  }
+
+  /** Omit specific keys (returns new schema) */
+  omit(keys) {
+    const keySet = new Set(keys);
+    const newShape = {};
+    for (const [key, schema] of Object.entries(this._shape)) {
+      if (!keySet.has(key)) newShape[key] = schema;
+    }
+    return new ObjectSchema(newShape);
+  }
+
+  /** Make all fields partial/optional (returns new schema) */
+  partial() {
+    const newShape = {};
+    for (const [key, schema] of Object.entries(this._shape)) {
+      // Clone-ish: create new schema that's optional
+      const clone = Object.create(Object.getPrototypeOf(schema));
+      Object.assign(clone, schema);
+      clone._required = false;
+      clone._optional = true;
+      newShape[key] = clone;
+    }
+    return new ObjectSchema(newShape);
+  }
+
+  /** Make all fields required (returns new schema) */
+  deepRequired() {
+    const newShape = {};
+    for (const [key, schema] of Object.entries(this._shape)) {
+      const clone = Object.create(Object.getPrototypeOf(schema));
+      Object.assign(clone, schema);
+      clone._required = true;
+      clone._optional = false;
+      newShape[key] = clone;
+    }
+    return new ObjectSchema(newShape);
+  }
+
+  /** Validate a single field from the schema */
+  validateField(field, value) {
+    const fieldSchema = this._shape[field];
+    if (!fieldSchema) return { valid: true, value };
+    return fieldSchema.validate(value, field);
+  }
+
+  _validateType(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      return this._msg('type', `${label} must be an object`);
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    const baseResult = super._validate(value, path);
+    if (!baseResult.valid) return baseResult;
+    if (baseResult.value === undefined) return baseResult;
+
+    const obj = baseResult.value;
+    const errors = {};
+    const result = {};
+
+    // Validate shape
+    for (const [key, schema] of Object.entries(this._shape)) {
+      const fieldResult = schema.validate(obj[key], key);
+      if (!fieldResult.valid) {
+        errors[key] = fieldResult.errors;
+      } else if (fieldResult.value !== undefined) {
+        result[key] = fieldResult.value;
+      }
+    }
+
+    // Handle unknown keys
+    if (this._strict) {
+      for (const key of Object.keys(obj)) {
+        if (!this._shape[key]) {
+          errors[key] = [`Unknown field: ${key}`];
+        }
+      }
+    } else if (this._passthrough) {
+      for (const key of Object.keys(obj)) {
+        if (!this._shape[key]) {
+          result[key] = obj[key];
+        }
+      }
+    }
+
+    if (Object.keys(errors).length > 0) {
+      return { valid: false, errors };
+    }
+    return { valid: true, value: result, data: result };
+  }
+}
+
+// ============================================
+// ENUM SCHEMA
+// ============================================
+
+class EnumSchema extends BaseSchema {
+  constructor(values = []) {
+    super();
+    this._values = values;
+  }
+
+  _validateType(value, label) {
+    if (!this._values.includes(value)) {
+      return this._msg('type', `${label} must be one of: ${this._values.join(', ')}`);
+    }
+    return null;
+  }
+}
+
+// ============================================
+// UNION SCHEMA (oneOf)
+// ============================================
+
+class UnionSchema extends BaseSchema {
+  constructor(schemas = []) {
+    super();
+    this._schemas = schemas;
+  }
+
+  _validate(value, path = '') {
+    // If any schema passes, succeed
+    for (const schema of this._schemas) {
+      const result = schema.validate(value, path);
+      if (result.valid) return result;
+    }
+    return {
+      valid: false,
+      errors: [`${this._getLabel(path)} does not match any of the allowed types`],
+    };
+  }
+}
+
+// ============================================
+// LITERAL SCHEMA
+// ============================================
+
+class LiteralSchema extends BaseSchema {
+  constructor(expected) {
+    super();
+    this._expected = expected;
+  }
+
+  _validateType(value, label) {
+    if (value !== this._expected) {
+      return `${label} must be exactly ${JSON.stringify(this._expected)}`;
+    }
+    return null;
+  }
+}
+
+// ============================================
+// ANY SCHEMA
+// ============================================
+
+class AnySchema extends BaseSchema {
+  _validateType() { return null; }
+}
+
+// ============================================
+// TUPLE SCHEMA
+// ============================================
+
+class TupleSchema extends BaseSchema {
+  constructor(schemas = []) {
+    super();
+    this._schemas = schemas;
+  }
+
+  _validateType(value, label) {
+    if (!Array.isArray(value)) return `${label} must be a tuple (array)`;
+    if (value.length !== this._schemas.length) {
+      return `${label} must have exactly ${this._schemas.length} elements`;
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    const baseResult = super._validate(value, path);
+    if (!baseResult.valid) return baseResult;
+    if (baseResult.value === undefined) return baseResult;
+
+    const errors = [];
+    const result = [];
+
+    for (let i = 0; i < this._schemas.length; i++) {
+      const itemResult = this._schemas[i].validate(value[i], `${path || 'Tuple'}[${i}]`);
+      if (!itemResult.valid) {
+        errors.push(...itemResult.errors.map(e => `[${i}]: ${e}`));
+      } else {
+        result.push(itemResult.value);
+      }
+    }
+
+    if (errors.length > 0) return { valid: false, errors };
+    return { valid: true, value: result };
+  }
+}
+
+// ============================================
+// RECORD SCHEMA (Map-like: { [key: string]: ValueSchema })
+// ============================================
+
+class RecordSchema extends BaseSchema {
+  constructor(keySchema, valueSchema) {
+    super();
+    this._keySchema = keySchema;
+    this._valueSchema = valueSchema;
+  }
+
+  _validateType(value, label) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      return `${label} must be an object`;
+    }
+    return null;
+  }
+
+  _validate(value, path = '') {
+    const baseResult = super._validate(value, path);
+    if (!baseResult.valid) return baseResult;
+    if (baseResult.value === undefined) return baseResult;
+
+    const errors = [];
+    const result = {};
+
+    for (const [k, v] of Object.entries(baseResult.value)) {
+      if (this._keySchema) {
+        const keyResult = this._keySchema.validate(k, `key(${k})`);
+        if (!keyResult.valid) {
+          errors.push(...keyResult.errors);
+          continue;
+        }
+      }
+      if (this._valueSchema) {
+        const valResult = this._valueSchema.validate(v, k);
+        if (!valResult.valid) {
+          errors.push(...valResult.errors.map(e => `${k}: ${e}`));
+        } else {
+          result[k] = valResult.value;
+        }
+      } else {
+        result[k] = v;
+      }
+    }
+
+    if (errors.length > 0) return { valid: false, errors };
+    return { valid: true, value: result };
+  }
+}
+
+// ============================================
+// SCHEMA FACTORY
+// ============================================
+
+class Schema {
+  static string() { return new StringSchema(); }
+  static number() { return new NumberSchema(); }
+  static boolean() { return new BooleanSchema(); }
+  static date() { return new DateSchema(); }
+  static array(itemSchema) { return new ArraySchema(itemSchema); }
+  static object(shape) { return new ObjectSchema(shape); }
+  static enum(values) { return new EnumSchema(values); }
+  static union(schemas) { return new UnionSchema(schemas); }
+  static literal(value) { return new LiteralSchema(value); }
+  static any() { return new AnySchema(); }
+  static tuple(schemas) { return new TupleSchema(schemas); }
+  static record(keySchema, valueSchema) { return new RecordSchema(keySchema, valueSchema); }
+
+  // Convenience shortcuts
+  static email() { return new StringSchema().email().required(); }
+  static url() { return new StringSchema().url().required(); }
+  static uuid() { return new StringSchema().uuid().required(); }
+  static port() { return new NumberSchema().int().min(0).max(65535).required(); }
+  static id() { return new NumberSchema().int().positive().required(); }
+
+  /**
+   * Combine schemas with .and() — all must pass
+   * 
+   * @example
+   * const schema = Schema.intersection(schemaA, schemaB);
+   */
+  static intersection(...schemas) {
+    return {
+      validate(value, path = '') {
+        let mergedResult = {};
+        for (const schema of schemas) {
+          const result = schema.validate(value, path);
+          if (!result.valid) return result;
+          if (result.value && typeof result.value === 'object') {
+            mergedResult = { ...mergedResult, ...result.value };
+          } else {
+            mergedResult = result.value;
+          }
+        }
+        return { valid: true, value: mergedResult };
+      },
+      parse(value) {
+        const result = this.validate(value);
+        if (!result.valid) {
+          const err = new Error('Schema validation failed');
+          err.errors = result.errors;
+          throw err;
+        }
+        return result.value;
+      },
+    };
+  }
+
+  /**
+   * Preprocess value before schema validation
+   * 
+   * @example
+   * const schema = Schema.preprocess(
+   *   (val) => typeof val === 'string' ? parseInt(val) : val,
+   *   Schema.number().min(0)
+   * );
+   */
+  static preprocess(transform, schema) {
+    return {
+      validate(value, path = '') {
+        return schema.validate(transform(value), path);
+      },
+      parse(value) {
+        return schema.parse(transform(value));
+      },
+    };
+  }
+
+  /**
+   * Lazy schema for recursive types
+   * 
+   * @example
+   * const categorySchema = Schema.object({
+   *   name: Schema.string(),
+   *   children: Schema.lazy(() => Schema.array(categorySchema)),
+   * });
+   */
+  static lazy(fn) {
+    return {
+      validate(value, path = '') {
+        return fn().validate(value, path);
+      },
+      parse(value) {
+        return fn().parse(value);
+      },
+    };
+  }
+}
+
+module.exports = {
+  Schema,
+  StringSchema,
+  NumberSchema,
+  BooleanSchema,
+  DateSchema,
+  ArraySchema,
+  ObjectSchema,
+  EnumSchema,
+  UnionSchema,
+  LiteralSchema,
+  AnySchema,
+  TupleSchema,
+  RecordSchema,
+};