Documentação do Sapphire

Schema uma vez, tipos e adapters em todo lugar. Esta documentação leva você de uma primeira instalação por todo conceito e adapter que o Sapphire traz.

Primeiros passos

• Primeiros passos — instalação, o seu primeiro schema, parse/safeParse, plugar um adapter.

Conceitos

• Visão geral — o que o Sapphire é, o que ele não é, e o modelo mental.
• Fields e modificadores — vocabulário completo de primitivos, compostos e modificadores.
• Inferindo tipos — Infer<> vs InferInput<> e o modelo de brand types.
• Composição — pick, omit, partial, required, extend, merge.
• Unions, literais e enums — o namespace a.type().
• Tuplas vs arrays — coleções de posição fixa vs homogêneas.
• Refs e relações — schemas nomeados e a.ref().
• Nullable vs optional — a confusão canônica, resolvida.
• Validação — parse / safeParse, issues, resolução de mensagens.
• Configuração — opções do Sapphire e sobrescritas por chamada.
• Escape hatch — .adapter(name, opts) para opções específicas de ORM.

Adapters

• Mongo (@ascendance-hub/sapphire-bson) — validadores de coleção $jsonSchema do driver nativo do MongoDB.
• Mongoose (@ascendance-hub/sapphire-mongoose) — saída de Schema do Mongoose, com refs, timestamps e índices compostos.
• JSON Schema (@ascendance-hub/sapphire-json-schema) — saída de JSON Schema 2020-12 para o AJV, ferramentas MCP e geradores de formulários de frontend.
• Drizzle (@ascendance-hub/sapphire-drizzle) — saída de pgTable / mysqlTable / sqliteTable com refs preguiçosas e índices compostos.

Receitas

• Validação de formulários — colete toda issue do safeParse e pivote para erros de UI por campo.
• Compartilhar tipos com o frontend — um schema alimenta o Mongo, tipos Infer<> e JSON Schema para formulários ou ferramentas MCP.
• Um schema, muitos adapters — registre múltiplos adapters e emita cada um a partir da mesma IR.
• Escrevendo um adapter customizado — percorra os 12 kinds da IR e plugue no registro.
• Mensagens de erro customizadas — i18n e mensagens marcadas através da hierarquia de resolução de 5 níveis.
• Migrando do Zod — mapeamento lado a lado mais o que cada biblioteca faz que a outra não faz.

Meta

• Arquitetura — o modelo de 3 camadas (DSL → IR → adapter) com um diagrama Mermaid.
• Decisões de design — por que a API tem a aparência que tem.
• Contribuindo — configuração do repositório e como escrever um adapter de terceiros.