@formajs/mold v2.1.0

Release Date: December 23, 2025

We're excited to present @formajs/mold v2.1.0 – a massive feature update that dramatically expands the schema definition capabilities. This release introduces support for complex data structures (Maps, Sets, Tuples), advanced type composition (Unions, Intersections), and powerful recursive schemas, bringing Mold to feature parity with major schema validation libraries while maintaining our lightweight orchestration philosophy.

🚀 What's New

✨ New Primitive & Complex Schemas

Mold now supports a much wider range of JavaScript types:

New Primitives

• Boolean: Strict validation with f.boolean()
• Date: Native Date object validation with f.date().min().max()
• File: Generic file validation with f.file() supporting size and type checks

Complex Structures

const complexSchema = forma.object({
  // Validate JS Maps
  settings: forma.map(forma.string(), forma.boolean()),
  
  // Validate JS Sets
  tags: forma.set(forma.string()).min(1),
  
  // Fixed-length arrays (Tuples)
  coordinates: forma.tuple([forma.number(), forma.number()]),
  
  // Objects with uniform values (Records)
  metadata: forma.record(forma.string()),
});

� Advanced Type Composition

Model complex relationships with new type helpers:

• Unions (.or): Match any of multiple schemas
• Intersections (.and): Match all schemas combined
• Literals & Enums: Exact value matching
• Lazy/Recursive: Define circular references (e.g., generic trees, nested comments)

// Recursive schema example (Category Tree)
const categorySchema = forma.object({
  name: forma.string(),
  subcategories: forma.array(forma.lazy(() => categorySchema)).optional(),
});

// Union example
const idSchema = forma.union([
  forma.string().validateUUID(),
  forma.number().min(1)
]);

🛠 Enhanced Object & Base Capabilities

Existing schemas got smarter and more flexible:

• Object Manipulation: .pick(), .omit(), .partial(), .required(), .extend()
• Unknown Key Handling: .strip(), .strict(), .passthrough()
• Transformation Pipelines: .transform(fn) and .refine(fn) for custom logic
• Defaults & Coercion: .default(val), .catch(val), and f.coerce.x()

� Migration Guide

Update to v2.1.0

This is a minor release and is fully backward compatible with v2.0.0.

npm update @formajs/mold@^2.1.0

New Features Usage

No changes are required for existing code. You can incrementally adopt the new schemas and utilities.

🎯 Key Features

Complete Type System

• Primitives: String, Number, Boolean, Date, File, Literal, Enum, Symbol, Void, Any, Unknown, Never, Null, Undefined
• Structural: Object, Array, Tuple, Record, Map, Set
• Flow: Promise, Function
• Logical: Union, Intersection, Lazy (Recursive)

Developer Utilities

• toJSONSchema(): Export standard JSON Draft-7 schemas for documentation or frontend usage.
• Deep Partial: Create partial versions of deeply nested object schemas easily.

💡 Usage Examples

recursive Comment Thread

const commentSchema = forma.object({
  id: forma.string().validateUUID(),
  content: forma.string().min(1),
  author: forma.object({
    name: forma.string(),
    email: forma.string().validateEmail()
  }),
  // Recursive replies
  replies: forma.array(forma.lazy(() => commentSchema)).default([])
});

Polymorphic Input (Union)

const searchFilter = forma.object({
  query: forma.string(),
  // Status can be a specific string OR an array of strings
  status: forma.union([
    forma.enum(['active', 'pending', 'archived']),
    forma.array(forma.enum(['active', 'pending', 'archived']))
  ])
});

📚 Documentation

• Updated API Reference: All new methods documented.
• JSON Schema Interop: Guide on exporting schemas for OpenAPI/Swagger.

---

Ready to expand?

npm install @formajs/mold@^2.1.0

Happy modeling with @formajs/mold v2.1.0! 🧱✨

@formajs/mold v2.0.0

Release Date: December 4, 2025

We're thrilled to announce @formajs/mold v2.0.0 – a major update that brings powerful new formatting capabilities, enhanced locale management, and improved compatibility with the latest FormaJS v2.0.0. This release transforms Mold from a pure validation library into a comprehensive data transformation and validation powerhouse.

🚀 What's New

✨ New Formatting Capabilities

Mold now supports formatters alongside validators and sanitizers, enabling complete data transformation pipelines:

String Schema Formatters

const userSchema = forma.object({
  birthDate: forma.string().formatDate({ locale: 'pt-BR' }),
  phone: forma.string().formatMobileNumber({ style: 'international' }),
  postalCode: forma.string().formatPostalCode(),
  taxId: forma.string().formatTaxId(),
  salary: forma.string().formatCurrency({ currency: 'BRL' }),
});

Number Schema Formatters

const statsSchema = forma.object({
  percentage: forma.number().toPercentage({ decimals: 2 }),
  accessibleNumber: forma.number().toAccessible(),
  price: forma.number().formatCurrency({ currency: 'USD' }),
});

🌍 Enhanced Locale Management

Improved locale handling with async support and automatic locale loading:

import { forma } from '@formajs/mold';

// Synchronous locale setting (optimistic)
forma.setLocale('pt-BR');

// Asynchronous locale setting with auto-loading
await forma.setLocaleAsync('pt-BR');

// Manual locale loading
await forma.ensureLocale('pt-BR');
forma.setLocale('pt-BR');

📅 Improved Date Validation

Enhanced date validation with built-in ISO-8601 support:

// Now supports ISO dates without additional options
const dateSchema = forma.string().validateDate(); // Accepts "2025-12-04"

// Still supports custom date options
const customDateSchema = forma.string().validateDate({
  min: '2020-01-01',
  max: '2030-12-31'
});

🔄 Migration Guide

From v1.x to v2.0.0

1. Update Dependencies

npm update @formajs/mold@^2.0.0 @formajs/formajs@^2.0.0

2. Locale Changes

Locales are now opt-in. Import the locale module you need:

// Before (v1.x)
import { forma } from '@formajs/mold';
forma.setLocale('pt-BR');

// After (v2.0.0) - Option A: Synchronous
import { forma } from '@formajs/mold';
import '@formajs/formajs/i18n/pt-BR';
forma.setLocale('pt-BR');

// After (v2.0.0) - Option B: Asynchronous
import { forma } from '@formajs/mold';
await forma.setLocaleAsync('pt-BR');

3. New Formatting Methods

Take advantage of the new formatting capabilities:

// Add formatters to your existing schemas
const userSchema = forma.object({
  name: forma.string().trim().validateNotEmpty(),
  email: forma.string().normalizeEmail().validateEmail(),
  phone: forma.string().formatMobileNumber(), // NEW!
  salary: forma.number().formatCurrency(),     // NEW!
});

📊 Performance & Compatibility

• Full FormaJS v2.0.0 compatibility with opt-in locales
• Zero breaking changes to existing validation logic
• Additive-only API - all existing code continues to work
• Enhanced error handling for locale loading failures
• Improved TypeScript support inherited from FormaJS v2.0.0

🎯 Key Features

Core Schema Types

• StringSchema: 50+ validators, 10+ sanitizers, 5 new formatters
• NumberSchema: Type validation, range checks, 3 new formatters
• ObjectSchema: Nested validation, strict mode
• ArraySchema: Item validation, length constraints

Advanced Capabilities

• Async validation support
• Custom validators and sanitizers
• Nested schema validation
• Error aggregation with detailed context
• i18n support with 17+ locales

Developer Experience

• Fluent API for readable schema definitions
• TypeScript-ready with JSDoc annotations
• Comprehensive documentation and examples
• 95%+ test coverage

💡 Usage Examples

Complete User Registration Schema

const registrationSchema = forma.object({
  // Personal Information
  firstName: forma.string().trim().validateNotEmpty().validateLength({ min: 2, max: 50 }),
  lastName: forma.string().trim().validateNotEmpty().validateLength({ min: 2, max: 50 }),
  email: forma.string().trim().normalizeEmail().validateEmail(),
  phone: forma.string().formatMobileNumber({ style: 'international' }),

  // Account Details
  username: forma.string().trim().toSlug().validateLength({ min: 3, max: 20 }),
  password: forma.string().validateStrongPassword(),

  // Demographics
  birthDate: forma.string().validateDate({ min: '1900-01-01' }),
  age: forma.number().validateInt().min(13).max(120),

  // Financial
  salary: forma.number().min(0).formatCurrency({ currency: 'USD' }),
  taxRate: forma.number().min(0).max(100).toPercentage(),

  // Preferences
  tags: forma.array(forma.string().trim().validateNotEmpty()).minLength(1).maxLength(10),
  notifications: forma.object({
    email: forma.boolean(),
    sms: forma.boolean(),
  }),
});

API Request Validation with Formatting

const apiRequestSchema = forma.object({
  userId: forma.string().validateUUID({ version: 4 }),
  amount: forma.number().validatePositive().formatCurrency(),
  timestamp: forma.string().validateDate(),
  metadata: forma.object({
    ip: forma.string().validateIP(),
    userAgent: forma.string().trim(),
  }),
});

🔧 Technical Details

Architecture

• Pure orchestration layer over FormaJS
• Zero reimplementation of validation logic
• Chainable method pattern for fluent APIs
• Immutable schema building with method chaining

Dependencies

• @formajs/formajs@^2.0.0 - Core validation engine
• Zero additional dependencies

Build & Distribution

• ESM + CJS dual bundles
• Tree-shakable exports
• UMD bundle for browsers
• TypeScript declarations included

🧪 Testing & Quality

• 112 test cases covering all functionality
• 68% branch coverage (optimized threshold)
• 95%+ statement coverage
• All tests passing across Node.js environments

📚 Documentation

• Updated README with comprehensive examples
• API reference for all methods
• Migration guide for upgrading from v1.x
• TypeScript guide for type-safe usage

🎉 Acknowledgments

This release represents a significant milestone in the FormaJS ecosystem. Special thanks to:

• FormaJS v2.0.0 for the enhanced foundation
• Community feedback that shaped the new formatting features
• Contributors who helped test and refine the API

🚀 What's Next?

We're already planning exciting features for future releases:

• BooleanSchema & DateSchema for complete type coverage
• Custom error messages with full i18n support
• Schema composition and inheritance
• Performance optimizations for large datasets
• Advanced validation rules (conditional, cross-field)

---

Ready to upgrade? Update your dependencies and start using the new formatting capabilities today!

npm install @formajs/mold@^2.0.0 @formajs/formajs@^2.0.0

Happy coding with @formajs/mold v2.0.0! 🎨✨