Field Types

The field helper provides type-safe field definitions built on Zod.

Import

import { field } from '@codician-team/monch';

Basic Types

field.string()

field.string()                    // Required string
field.string().min(1)             // Minimum length
field.string().max(100)           // Maximum length
field.string().length(10)         // Exact length
field.string().trim()             // Trim whitespace
field.string().toLowerCase()      // Convert to lowercase
field.string().toUpperCase()      // Convert to uppercase
field.string().regex(/pattern/)   // Regex validation
field.string().optional()         // Optional
field.string().nullable()         // Can be null
field.string().default('value')   // Default value

field.number()

field.number()                    // Required number
field.number().int()              // Integer only
field.number().positive()         // > 0
field.number().nonnegative()      // >= 0
field.number().negative()         // < 0
field.number().nonpositive()      // <= 0
field.number().min(0)             // Minimum value
field.number().max(100)           // Maximum value
field.number().multipleOf(5)      // Multiple of
field.number().finite()           // Not Infinity

field.boolean()

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

field.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 current time:

field.datetime()                  // Default: new Date()

ID Types

field.id()

Auto-generating ObjectId for _id fields:

field.id()

// Accepts string, converts to ObjectId
// Generates new ObjectId if not provided

field.objectId()

Required ObjectId for references:

field.objectId()

// Requires a value (string or ObjectId)
// Transforms strings to ObjectId

field.uuid()

Auto-generating UUID v4:

field.uuid()

// Generates UUID if not provided
// Result: '123e4567-e89b-12d3-a456-426614174000'

Validation Types

field.email()

Email validation:

field.email()

// Validates email format

field.url()

URL validation:

field.url()

// Validates URL format

field.enum()

Enum/union type:

field.enum(['pending', 'active', 'suspended'])
field.enum(['user', 'admin']).default('user')

Complex Types

field.array()

field.array(field.string())              // string[]
field.array(field.number()).min(1)       // At least 1 element
field.array(field.number()).max(10)      // At most 10 elements
field.array(field.number()).length(5)    // Exactly 5 elements
field.array(field.number()).nonempty()   // At least 1 element

field.object()

field.object({
  street: field.string(),
  city: field.string(),
  zip: field.string(),
})

BSON Types

field.long()

64-bit integer (MongoDB Long):

field.long()

// Usage
import { Long } from '@codician-team/monch';
{ count: Long.fromNumber(9007199254740993) }

// Serializes to number (safe range) or bigint

field.decimal()

High-precision decimal (MongoDB Decimal128):

field.decimal()

// Usage
import { Decimal128 } from '@codician-team/monch';
{ price: Decimal128.fromString('99999999999999.99') }

// Serializes to string

field.binary()

Binary data (MongoDB Binary):

field.binary()

// Usage
import { Binary } from '@codician-team/monch';
{ data: new Binary(Buffer.from('hello')) }

// Serializes to base64 string

field.timestamp()

MongoDB Timestamp:

field.timestamp()

// Usage
import { Timestamp } from '@codician-team/monch';
{ ts: new Timestamp({ t: 1234567890, i: 1 }) }

// Serializes to { t: number, i: number }

Money Type

field.money()

Currency field stored as Decimal128 for precision:

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

Options:

field.money({
  currency: 'USD',        // Currency code (default: 'USD')
  min: 0,                 // Minimum amount
  max: 10000,             // Maximum amount
  allowNegative: false,   // Allow negative (default: false)
})

MoneyValue structure:

{
  amount: Decimal128,    // High-precision decimal
  currency: string,      // Currency code
}

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, BTC, ETH

Money Utility Class

The Money class provides all operations for monetary values:

import { Money } from '@codician-team/monch';

Formatting & Conversion

Money.format(price)                     // '$99.99'
Money.format(price, { precision: 0 })   // '$100'
Money.toNumber(price)                   // 99.99 (may lose precision)
Money.toString(price)                   // '99.99' (exact)
Money.toCents(price)                    // 9999 (for Stripe)
Money.fromCents(9999, 'USD')            // MoneyValue
Money.toJSON(price)                     // { amount, currency, display, cents }

Creating MoneyValue

Money.from(99.99)                              // From number (USD)
Money.from('99.99', 'EUR')                     // From string
Money.from({ amount: 99.99, currency: 'GBP' }) // From object

Arithmetic

Money.add(a, b)              // Add (same currency)
Money.add(a, 10)             // Add number
Money.subtract(a, b)         // Subtract
Money.multiply(a, 1.1)       // Multiply by factor
Money.divide(a, 4)           // Divide
Money.percentage(a, 15)      // 15% of value
Money.round(a)               // Round to currency precision

Aggregation & Splitting

Money.sum([a, b, c])         // Sum array
Money.min(a, b, c)           // Minimum value
Money.max(a, b, c)           // Maximum value
Money.split(total, 3)        // Split equally (handles rounding)
Money.allocate(total, [2,1]) // Split by ratios

Comparison

Money.equals(a, b)           // Equality
Money.compare(a, b)          // -1 | 0 | 1
Money.greaterThan(a, b)      // a > b
Money.lessThan(a, b)         // a < b
Money.greaterThanOrEqual(a, b)
Money.lessThanOrEqual(a, b)
Money.isZero(a)              // Check zero
Money.isPositive(a)          // Check positive
Money.isNegative(a)          // Check negative
Money.abs(a)                 // Absolute value
Money.negate(a)              // Negate

Currency Configuration

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

getCurrencyConfig('USD')
// { code: 'USD', symbol: '$', precision: 2, symbolPosition: 'before' }

CURRENCY_CONFIGS.JPY
// { code: 'JPY', symbol: '¥', precision: 0, symbolPosition: 'before' }

Using Zod Directly

The z export is Zod itself:

import { z } from '@codician-team/monch';

const schema = {
  _id: field.id(),
  metadata: z.record(z.string(), z.any()),
  tags: z.set(z.string()),
  data: z.union([z.string(), z.number()]),
};

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