Fields e modificadores

O DSL de field do Sapphire é a superfície voltada ao usuário da biblioteca. Toda chamada em uma instância Sapphire (a.string(), a.object({...}), a.type().union([...])) retorna um novo Field imutável. Modificadores como .optional(), .min(3), .default('x') retornam novos fields em vez de mutar o anterior — cadeias são seguras para compartilhar e reutilizar.

Esta página é a referência para todo construtor de field e todo modificador que ele suporta. Para os métodos de composição em objetos (pick, omit, partial, required, extend, merge) veja Composição. Para union/literal/enum veja Unions, literais e enums.

Exemplo mínimo

const user = a.object({
  name: a.string().min(1).max(120),
  age: a.number().int().nonnegative(),
  active: a.boolean().default(true),
  createdAt: a.date(),
})

type User = Infer<typeof user>
// User = { name: string; age: number; active: boolean; createdAt: Date }

Primitivos

a.string()

Exemplo:

const email = a.string().min(3).max(254).email()

[!NOTE] .email() é pragmático, não completo segundo a RFC 5322. O regex embutido cobre ~99% dos endereços práticos — ele rejeita lixo óbvio (a@b..c, pontos no início/fim, TLD faltando) mas não aceita formas exóticas-porém-legais-pela-RFC como partes locais entre aspas ("foo bar"@example.com). Se você precisa de conformidade total com a RFC, pluge um validador de terceiros via .regex(yourRegex) ou verificações pós-safeParse.

a.number()

Exemplo:

const age = a.number().int().gte(0).lte(150)

a.boolean()

Boolean não tem modificadores de regra — apenas os universais e .coerce(). Com coerce, as strings 'true'/'false' e os números 1/0 são aceitos.

a.date()

Estrito por padrão — apenas instâncias de Date são aceitas. Chame .coerce() para também aceitar strings ou números (payloads de formulário, parâmetros de URL, timestamps desserializados de JSON); a IR do adapter (coerce: false vs coerce: true) reflete honestamente o que o runtime vai aceitar.

Compostos

a.object(shape)

Shape é um record de Fields. A saída é um objeto simples cujas chaves espelham shape, com os fields opcionais elevados para posições ?:.

ObjectField também carrega metadados de nível de schema: .name(n), .timestamps(), .index(keys, opts?). Ele também expõe os métodos de composição pick, omit, partial, required, extend, merge — esses têm sua própria página em Composição.

a.array(item)

Homogêneo, de comprimento variável. O único argumento item é o field interno — toda entrada é validada contra ele. Modificadores: .min(n), .max(n), .length(n), .nonempty().

a.tuple([f1, f2, ...])

Heterogêneo, de comprimento fixo. Veja Tuplas vs arrays para a comparação.

Namespace de tipos

a.type() retorna um construtor para os kinds não-folha:

Refs

a.ref(target) declara “esta posição contém uma referência a um schema nomeado”. target é ou um ObjectField retornado por .name(...) ou a string do nome diretamente. A validação verifica a presença e que o nome referenciado está registrado na instância Sapphire — um alvo não registrado faz safeParse falhar com uma issue ref_target_missing. Ela não verifica o shape do valor referenciado na v1. Os adapters resolvem o shape do alvo (Mongo ObjectId, JSON Schema $ref, Drizzle references(() => target.id)). Cobertura detalhada em Refs e relações.

Modificadores universais

Estes estão disponíveis em todo field. (unique, index e os name/timestamps de nível de schema não são estritamente universais — veja as tabelas por field — mas seguem a mesma convenção encadeável.)

Exemplo:

const bio = a.string().max(280).optional().describe('User bio (markdown)')
const nickname = a.string().nullable()
const role = a.string().default('member')

Armadilhas

[!WARNING] .coerce() executa primeiro. A ordem é coerce → substituição de default → tratamento de null/undefined → verificação de invalid_type → transforms → verificações de regra. Os validadores veem o valor coagido, não a entrada crua. O trecho abaixo converte 42 para "42" antes de a verificação min(3) disparar.

const slug = a.string().coerce().toLowerCase().min(3)
// The number 42 becomes the string "42" first, then lowercases (no-op),
// then is checked against min(3) — which fails because "42".length === 2.

[!WARNING] .nullable() NÃO é .optional(). nullable aceita null; optional aceita undefined. Eles são independentes — combine-os se você quer ambos. Veja Nullable vs optional.

Relacionados

• Inferindo tipos — como os modificadores alimentam Infer<>.
• Composição — pick, omit, partial, required, extend, merge.
• Unions, literais e enums.
• Tuplas vs arrays.
• Receitas → Mensagens de erro customizadas.
• Receitas → Escrevendo um adapter customizado.