Field Types

Monch provides a field helper with common field types built on Zod. All field types support the full Zod API.

Basic Types

String

field.string()                    // Required string
field.string().min(1)             // At least 1 character
field.string().max(100)           // At most 100 characters
field.string().length(10)         // Exactly 10 characters
field.string().trim()             // Trim whitespace
field.string().toLowerCase()      // Convert to lowercase
field.string().optional()         // Optional (can be undefined)
field.string().nullable()         // Can be null
field.string().default('hello')   // Default value

Number

field.number()                    // Required number
field.number().int()              // Integer only
field.number().positive()         // Greater than 0
field.number().negative()         // Less than 0
field.number().min(0)             // Minimum value
field.number().max(100)           // Maximum value
field.number().multipleOf(5)      // Must be multiple of 5

Boolean

field.boolean()                   // Required boolean
field.boolean().default(false)    // Default value

Date

field.date()                      // Required date
field.date().min(new Date())      // Minimum date
field.date().max(new Date())      // Maximum date

field.datetime()                  // Date with default to now

ID Types

ObjectId

// Auto-generating ObjectId (for _id field)
field.id()

// Required ObjectId reference (for foreign keys)
field.objectId()

Both accept strings and automatically convert them to ObjectId:

await Users.insertOne({
  _id: '507f1f77bcf86cd799439011',  // Converted to ObjectId
  name: 'Alice',
});

UUID

field.uuid()  // Auto-generating UUID v4

// Result: '123e4567-e89b-12d3-a456-426614174000'

Validation Types

Email

field.email()  // Email validation

URL

field.url()  // URL validation

Enum

// String enum
field.enum(['pending', 'active', 'suspended'])

// With default
field.enum(['user', 'admin']).default('user')

Complex Types

Array

// Array of strings
field.array(field.string())

// Array of numbers with constraints
field.array(field.number()).min(1).max(10)

// Array of objects
field.array(field.object({
  name: field.string(),
  value: field.number(),
}))

Object

// Nested object
field.object({
  street: field.string(),
  city: field.string(),
  zip: field.string(),
  country: field.string().default('US'),
})

// Optional nested object
field.object({
  bio: field.string().optional(),
  website: field.url().optional(),
}).optional()

BSON Types

Long (64-bit Integer)

field.long()  // MongoDB Long (Int64)

// Usage
await Stats.insertOne({
  viewCount: Long.fromNumber(9007199254740993),  // Beyond JS safe integer
});

Serialization

Long values serialize to number when within JavaScript's safe integer range (±9,007,199,254,740,991). Values outside this range serialize to bigint to preserve precision.

Decimal128 (High-Precision Decimal)

field.decimal()  // MongoDB Decimal128

// Usage - great for financial calculations
await Accounts.insertOne({
  balance: Decimal128.fromString('99999999999999.99'),
});

Binary

field.binary()  // MongoDB Binary

// Usage
await Files.insertOne({
  content: new Binary(Buffer.from('hello')),
});

Timestamp

field.timestamp()  // MongoDB Timestamp

// Usage - internal MongoDB operations
await OpLog.insertOne({
  ts: new Timestamp({ t: 1234567890, i: 1 }),
});

Serialization

Timestamp serializes to { t: number, i: number } where t is the timestamp and i is the increment.

Money Type

Built-in currency support with 30+ currencies:

field.money()                           // Default: USD
field.money({ currency: 'EUR' })        // Euro
field.money({ currency: 'JPY' })        // Japanese Yen (no decimals)
field.money({ currency: 'BTC' })        // Bitcoin (8 decimals)

Money Options

field.money({
  currency: 'USD',        // Default currency code (default: 'USD')
  precision: 2,           // Decimal places (auto-detected by currency)
  min: 0,                 // Minimum amount
  max: 10000,             // Maximum amount
  allowNegative: false,   // Allow negative amounts (default: false)
  symbol: '$',            // Custom symbol (auto-detected by currency)
  symbolPosition: 'before', // 'before' or 'after' (auto-detected)
});

MoneyValue Structure

{
  amount: number,      // Value in smallest unit (cents, etc.)
  currency: string,    // Currency code
  display: string,     // Display string (e.g., "$19.99")
}

Flexible Input Formats

Money fields accept multiple input formats:

await Products.insertOne({
  name: 'Widget',
  price: 29.99,                              // Number
  priceEUR: '49.99',                         // String
  priceJPY: { amount: 3500 },                // Object
});

// Output includes formatted display string
// {
//   price: { amount: 29.99, currency: 'USD', display: '$29.99' },
//   priceEUR: { amount: 49.99, currency: 'EUR', display: '€49.99' },
//   priceJPY: { amount: 3500, currency: 'JPY', display: '¥3,500' }
// }

Example Usage

const Products = collection({
  name: 'products',
  schema: {
    _id: field.id(),
    name: field.string(),
    price: field.money({ currency: 'USD' }),
  },
});

// Insert with cents
await Products.insertOne({
  name: 'Widget',
  price: { amount: 1999 },  // $19.99 in cents
});

// Result includes formatted string
// { amount: 1999, currency: 'USD', display: '$19.99' }

Supported Currencies

USD, EUR, GBP, JPY, CNY, INR, AUD, CAD, CHF, HKD, SGD, SEK, KRW, NOK, NZD, MXN, TWD, ZAR, BRL, DKK, PLN, THB, ILS, IDR, CZK, AED, TRY, HUF, CLP, SAR, PHP, MYR, COP, RUB, RON, and BTC.

Money Helpers

import {
  getCurrencyConfig,
  formatMoney,
  toSmallestUnit,
  fromSmallestUnit,
  CURRENCY_CONFIGS,
} from '@codician-team/monch';

// Get currency configuration
const config = getCurrencyConfig('USD');
// { code: 'USD', symbol: '$', decimals: 2, ... }

// Format a value
formatMoney({ amount: 1999, currency: 'USD' });
// '$19.99'

// Convert to smallest unit
toSmallestUnit(19.99, 'USD');  // 1999

// Convert from smallest unit
fromSmallestUnit(1999, 'USD');  // 19.99

Quick Reference

Method	Output Type	Description
field.id()	ObjectId	Auto-generating ObjectId
field.objectId()	ObjectId	Required ObjectId reference
field.uuid()	string	Auto-generating UUID
field.string()	string	String
field.number()	number	Number
field.boolean()	boolean	Boolean
field.date()	Date	Date
field.datetime()	Date	Date with default to now
field.email()	string	Email validation
field.url()	string	URL validation
field.enum([...])	union	Enum type
field.array(type)	T[]	Array of type
field.object({...})	object	Nested object
field.long()	Long	64-bit integer
field.decimal()	Decimal128	High-precision decimal
field.binary()	Binary	Binary data
field.timestamp()	Timestamp	MongoDB timestamp
field.money(opts?)	MoneyValue	Currency with formatting