@cutticat/zod-extras

A library of additional Zod schemas and utilities.

Contents

• Overview
• Installation
• Quick start
• Domain constants
• API
• Documentation
• Requirements

Overview

The library provides:

• Schemas — UUID, environment, ports, phones, email, Telegram ID, i18n (including locale), legal identifiers (INN, KPP, OGRN, BIC, passport, SWIFT, IBAN), S3, durations, timezones, strings (NonEmptyString, Slug, length-limited String255…String65535), auth (username, access lists), API (ErrorResponse), pagination, JSON string, log levels (trace–error), URL path, cron expressions (cron-parser), and more.
• Domain constants — length bounds and regex pattern strings exported next to many scalar schemas (for Drizzle CHECK constraints, OpenAPI, etc.).
• Functions — withDefaultsUnwrapped, extractDefaultValues, nullishToUndefined

Source is organized under lib/schemas/ in domain folders (see Project structure). Tests mirror the same layout under tests/.

Installation

pnpm i @cutticat/zod-extras

Quick start

import {
  UuidSchema,
  EnvironmentSchema,
  PortSchema,
  PhoneSchema,
  EmailSchema,
  DurationSchema,
  CronSchema,
  LogLevelSchema,
  String255Schema,
  UsernameSchema,
  AccessListAlpha2Schema,
  ErrorResponseSchema,
  slugPattern,
  string255MaxLength,
  withDefaultsUnwrapped,
  extractDefaultValues,
  nullishToUndefined,
} from "@cutticat/zod-extras"
import { z } from "zod"

// Schemas

UuidSchema.parse("550e8400-e29b-41d4-a716-446655440000")
EnvironmentSchema.parse("production")
PortSchema.parse(8080)
DurationSchema.parse("10h") // 36_000_000
CronSchema.parse("0 3 * * *").normalized // "0 3 * * *"
LogLevelSchema.parse("info")
String255Schema.parse("short label")
UsernameSchema.parse("my-user")
AccessListAlpha2Schema.parse({ type: "whitelist", list: ["RU"] })
ErrorResponseSchema.parse({ error: "Not found" })

// Domain constants (also used by @cutticat/drizzle-extras)

string255MaxLength // 255
slugPattern        // "^[a-z0-9]+(?:-[a-z0-9]+)*$"

// Defaults

const schema = z.object({
  name: z.string().default("John"),
  age: z.number().optional(),
})
const withDefaults = withDefaultsUnwrapped(schema, true)
withDefaults.parse({}) // { name: "John" }

extractDefaultValues(schema) // { name: "John" }

// Nulls

nullishToUndefined(z.object({ a: z.string().nullable() }))

Domain constants

Many modules export camelCase constants alongside the Zod schema:

Patterns are plain strings suitable for new RegExp(pattern) in Zod and for PostgreSQL column ~ '…' in Drizzle CHECK constraints.

Full list and file layout: documents/STRUCTURE.md.

API

Schemas

• API: ErrorResponseSchema
• Auth: UsernameSchema, createUsernameSchema, AccessListSchema, AccessListAlpha2Schema, AccessListAlpha3Schema, createAccessListSchema
• Strings: NonEmptyStringSchema, SlugSchema, String255Schema … String65535Schema, createSizedStringSchema, string*MaxLength constants, slugPattern
• Time: DurationSchema, TimezoneSchema, CronSchema, Cron, CronField (wildcard, values), timezoneMaxLength, timezonePattern
• Network: PortSchema, UrlPathSchema, portMin, portMax, urlPathPattern
• i18n: Alpha2CodeSchema, Alpha3CodeSchema, CurrencyCodeSchema, LocaleSchema (+ length/pattern constants)
• Messaging: PhoneSchema, EmailSchema, TraditionalContactTypeSchema, Telegram ID/username schemas, PushSubscriptionSchema (+ email/telegram constants)
• Legal (Russia): INN, KPP, OGRN, BIC, accounts, passport, SWIFT, IBAN schemas (+ length/pattern constants)
• Storage: DataSizeSchema
• Geo: GeoCoordinatesSchema, GeoCoordinatesBoundedSchema, latitudeMin/Max, longitudeMin/Max
• Logging: LogLevelSchema
• Other: UuidSchema, EnvironmentSchema, SortDirectionSchema, DecimalSchema, PercentageSchema, S3BucketSchema, S3ObjectKeySchema, LimitOffsetSchema, JsonStringSchema, CoercedBooleanSchema

Functions

• withDefaultsUnwrapped(schema, strict?) — lifts field .default() / .prefault() to the object level
• extractDefaultValues(schema, options?) — extracts default values from a schema
• nullishToUndefined(schema) — replaces null with undefined in fields

Documentation

• Project structure — lib/ and tests/ layout, barrel index rules, constants
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0