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 with formatting:

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

Result structure:

{
  amount: number,      // Value in smallest unit (cents)
  currency: string,    // Currency code
  formatted: string,   // Display string ('$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, BTC

Money Helpers

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

getCurrencyConfig('USD')
// { code: 'USD', symbol: '$', decimals: 2, ... }

formatMoney({ amount: 1999, currency: 'USD' })
// '$19.99'

toSmallestUnit(19.99, 'USD')   // 1999
fromSmallestUnit(1999, 'USD')  // 19.99

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