@cutticat/zod-extras

A library of additional Zod schemas and utilities.

Contents

• Overview
• Installation
• Quick start
• 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 (including timezone), strings (NonEmptyString, Slug, length-limited String255…String65535), auth (username, access lists), API (ErrorResponse), pagination, JSON string, log levels (trace–error), URL path, and more.
• Functions — withDefaultsUnwrapped, extractDefaultValues, nullishToUndefined

Installation

pnpm i @cutticat/zod-extras

Quick start

import {
  UuidSchema,
  EnvironmentSchema,
  PortSchema,
  PhoneSchema,
  EmailSchema,
  DurationSchema,
  LogLevelSchema,
  String255Schema,
  UsernameSchema,
  AccessListAlpha2Schema,
  ErrorResponseSchema,
  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
LogLevelSchema.parse("info")
String255Schema.parse("short label")
UsernameSchema.parse("my-user")
AccessListAlpha2Schema.parse({ type: "whitelist", list: ["RU"] })
ErrorResponseSchema.parse({ error: "Not found" })

// 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() }))

API

Schemas

• API: ErrorResponseSchema
• Auth: UsernameSchema, createUsernameSchema, AccessListSchema, AccessListAlpha2Schema, AccessListAlpha3Schema, createAccessListSchema
• Strings: NonEmptyStringSchema, SlugSchema, String255Schema … String65535Schema, createSizedStringSchema, string*MaxLength constants
• Time: DurationSchema, TimezoneSchema
• Network: PortSchema, UrlPathSchema
• i18n: Alpha2CodeSchema, Alpha3CodeSchema, CurrencyCodeSchema, LocaleSchema
• Messaging: PhoneSchema, EmailSchema, TraditionalContactTypeSchema, TelegramUserIdSchema, TelegramGroupIdSchema, TelegramChannelIdSchema, TelegramUsernameSchema, PushSubscriptionSchema
• Legal (Russia): PhysicalInnSchema, LegalInnSchema, KppSchema, OgrnSchema, BicSchema, PaymentAccountSchema, CorrespondentAccountSchema, PassportSeriesSchema, PassportNumberSchema, PassportIssueCodeSchema, SwiftSchema, IbanSchema
• Storage: DataSizeSchema
• Geo: GeoCoordinatesSchema, GeoCoordinatesBoundedSchema
• Logging: LogLevelSchema
• Other: UuidSchema, EnvironmentSchema, SortDirectionSchema, DecimalSchema, PercentageSchema, S3BucketSchema, S3ObjectKeySchema, LimitOffsetSchema, JsonStringSchema, CoercedBooleanSchema

Functions

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

Documentation

Detailed documentation:

• Project structure
• 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