@softize/opus 8.6.6

package/src/schema/entity.ts

@@ -0,0 +1,439 @@
+/**
+ * @softize/opus/schema — `defineEntity` + relations + inferência de tipos.
+ *
+ * Uma entidade é a descrição declarativa de um recorte de dado persistido
+ * (campos, relações, índices). Serve de fonte única pra:
+ *   - tipo TS da linha (`EntityRow`), input de create (`EntityInsert`) e
+ *     update (`EntityUpdate`);
+ *   - colunas resolvidas (`entityColumns`) que o data/migration adapter lê;
+ *   - projeção de view/search (consumido pelas actions com `entity:`).
+ *
+ * Puro: `defineEntity` valida e devolve o config (identity), sem efeito
+ * colateral — igual `defineAction`/`defineDomain`. A materialização (migration,
+ * repo tipado) é do adapter, não daqui. Ver §15 do protocolo.
+ */
+
+import { z } from 'zod'
+import { error } from '../core/index.ts'
+import type { ColumnMeta, LogicalType } from './drivers/zod.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// =============================================================================
+// Relations
+// =============================================================================
+
+export type RelationKind = 'belongsTo' | 'hasOne' | 'hasMany' | 'manyToMany'
+
+export interface Relation {
+  kind: RelationKind
+  /** Nome da entidade alvo (referência por string — resolvida no register). */
+  target: string
+  /** FK local (belongsTo). */
+  from?: string
+  /** FK no alvo (hasOne/hasMany). */
+  to?: string
+  /** Tabela de junção (manyToMany). */
+  through?: string
+}
+
+/** FK local → alvo. Ex: `belongsTo('user', { from: 'ownerId' })`. */
+export const belongsTo = (target: string, opts: { from: string }): Relation => ({
+  kind: 'belongsTo',
+  target,
+  from: opts.from,
+})
+
+/** FK no alvo, 1:1. Ex: `hasOne('profile', { to: 'userId' })`. */
+export const hasOne = (target: string, opts: { to: string }): Relation => ({
+  kind: 'hasOne',
+  target,
+  to: opts.to,
+})
+
+/** FK no alvo, 1:N. Ex: `hasMany('attachment', { to: 'dealId' })`. */
+export const hasMany = (target: string, opts: { to: string }): Relation => ({
+  kind: 'hasMany',
+  target,
+  to: opts.to,
+})
+
+/** N:N via tabela de junção. Ex: `manyToMany('tag', { through: 'deal_tags' })`. */
+export const manyToMany = (target: string, opts: { through: string }): Relation => ({
+  kind: 'manyToMany',
+  target,
+  through: opts.through,
+})
+
+// =============================================================================
+// Config
+// =============================================================================
+
+export interface IndexSpec {
+  on: string[]
+  unique?: boolean
+  using?: string
+}
+
+export type EntityFields = Record<string, LogicalType<any>>
+
+export interface EntityConfig<F extends EntityFields = EntityFields> {
+  /** Nome singular da entidade. `[a-z][a-zA-Z0-9_]*`. */
+  name: string
+  /** Doc de negócio da entidade — o que ela é/representa. A fonte de
+   *  entendimento; flui pro manifest/lente (substitui a prosa do domain.md). */
+  description?: string
+  /** Nome da tabela. Default: plural simples de `name`. */
+  table?: string
+  fields: F
+  relations?: Record<string, Relation>
+  indexes?: IndexSpec[]
+  /** Injeta `createdAt`/`updatedAt` (geridos pelo runtime). */
+  timestamps?: boolean
+  /** Injeta `deletedAt`; search/view filtram deletados por default. */
+  softDelete?: boolean
+}
+
+// =============================================================================
+// Inferência de tipos
+// =============================================================================
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+type FieldT<X> = X extends LogicalType<infer T> ? T : never
+
+type HasPk<F> = true extends {
+  [K in keyof F]: F[K] extends { readonly __pk: true } ? true : false
+}[keyof F]
+  ? true
+  : false
+
+type HasDefault<X> = X extends { readonly __hasDefault: true } ? true : false
+type IsNullable<X> = null extends FieldT<X> ? true : false
+
+type IdPart<F> = HasPk<F> extends true ? {} : { id: string }
+type TimestampPart<E> = E extends { timestamps: true }
+  ? { createdAt: string; updatedAt: string }
+  : {}
+type SoftDeletePart<E> = E extends { softDelete: true } ? { deletedAt: string | null } : {}
+
+/** Linha completa da entidade (id auto + campos + timestamps + softDelete). */
+export type EntityRow<E extends EntityConfig> = Simplify<
+  IdPart<E['fields']> &
+    { [K in keyof E['fields']]: FieldT<E['fields'][K]> } &
+    TimestampPart<E> &
+    SoftDeletePart<E>
+>
+
+// Insert: sem colunas geradas; campos com default/nullable são opcionais.
+type OptionalInsertKeys<F> = {
+  [K in keyof F]: HasDefault<F[K]> extends true
+    ? K
+    : IsNullable<F[K]> extends true
+      ? K
+      : never
+}[keyof F]
+type RequiredInsertKeys<F> = Exclude<keyof F, OptionalInsertKeys<F>>
+
+/** Input de create: sem id auto/timestamps; default/nullable opcionais. */
+export type EntityInsert<E extends EntityConfig> = Simplify<
+  { [K in RequiredInsertKeys<E['fields']>]: FieldT<E['fields'][K]> } & {
+    [K in OptionalInsertKeys<E['fields']>]?: FieldT<E['fields'][K]>
+  }
+>
+
+/** Input de update: partial do insert. */
+export type EntityUpdate<E extends EntityConfig> = Partial<EntityInsert<E>>
+
+// =============================================================================
+// defineEntity
+// =============================================================================
+
+const ENTITY_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/
+
+/**
+ * Constrói e valida uma entidade. Em sucesso devolve o próprio config
+ * (identity, pra preservar inferência). Erros são `ActionError` com
+ * `category: 'internal'`.
+ */
+export function defineEntity<const E extends EntityConfig>(config: E): E {
+  validateEntity(config)
+  return config
+}
+
+function validateEntity(config: EntityConfig): void {
+  if (typeof config.name !== 'string' || config.name.length === 0) {
+    throw error({
+      code: 'entity.invalid_name',
+      category: 'internal',
+      message: 'Entity "name" deve ser string não-vazia',
+    })
+  }
+  if (!ENTITY_NAME_RE.test(config.name)) {
+    throw error({
+      code: 'entity.invalid_name_format',
+      category: 'internal',
+      message: `Entity name "${config.name}" deve casar com [a-z][a-zA-Z0-9_]*`,
+    })
+  }
+
+  const pkFields = Object.entries(config.fields).filter(([, f]) => f.column.pk === true)
+  if (pkFields.length > 1) {
+    throw error({
+      code: 'entity.multiple_pk',
+      category: 'internal',
+      message: `Entity "${config.name}" tem ${pkFields.length} primary keys (${pkFields
+        .map(([k]) => k)
+        .join(', ')}); declare no máximo uma`,
+    })
+  }
+
+  if (config.relations !== undefined) {
+    for (const [relName, rel] of Object.entries(config.relations)) {
+      if (typeof rel.target !== 'string' || rel.target.length === 0) {
+        throw error({
+          code: 'entity.invalid_relation_target',
+          category: 'internal',
+          message: `Relation "${relName}" em "${config.name}" tem target inválido`,
+        })
+      }
+    }
+  }
+}
+
+// =============================================================================
+// Materialização (lida pelo data/migration adapter)
+// =============================================================================
+
+export interface ResolvedColumn {
+  name: string
+  /** `undefined` em colunas injetadas (id/timestamps/softDelete). */
+  logicalType?: string
+  column: ColumnMeta
+  /** `true` em colunas geridas pelo runtime (id auto, timestamps, deletedAt). */
+  generated: boolean
+}
+
+/**
+ * Resolve as colunas da entidade incluindo as injetadas (id auto quando não há
+ * pk declarada, timestamps, deletedAt). É o input do migration adapter.
+ */
+export function entityColumns(config: EntityConfig): ResolvedColumn[] {
+  const cols: ResolvedColumn[] = []
+  const hasPk = Object.values(config.fields).some((f) => f.column.pk === true)
+
+  if (!hasPk) {
+    cols.push({ name: 'id', logicalType: 'uuid', column: { pk: true }, generated: true })
+  }
+
+  for (const [name, field] of Object.entries(config.fields)) {
+    cols.push({
+      name,
+      logicalType: field.meta.logicalType,
+      column: field.column,
+      generated: false,
+    })
+  }
+
+  if (config.timestamps === true) {
+    cols.push({ name: 'createdAt', logicalType: 'datetime', column: {}, generated: true })
+    cols.push({ name: 'updatedAt', logicalType: 'datetime', column: {}, generated: true })
+  }
+  if (config.softDelete === true) {
+    cols.push({
+      name: 'deletedAt',
+      logicalType: 'datetime',
+      column: { nullable: true },
+      generated: true,
+    })
+  }
+
+  return cols
+}
+
+/**
+ * Primary key da entidade. `auto: true` quando é o `id` injetado (nenhum campo
+ * declarou `.pk()`) — nesse caso o repo gera o valor (uuid).
+ */
+export function entityPk(config: EntityConfig): { name: string; auto: boolean } {
+  for (const [name, field] of Object.entries(config.fields)) {
+    if (field.column.pk === true) return { name, auto: false }
+  }
+  return { name: 'id', auto: true }
+}
+
+// =============================================================================
+// Schemas Zod derivados (input/output de actions a partir da entidade)
+// =============================================================================
+
+/** Schema Zod da linha completa (output): todos os campos + colunas geradas. */
+export function entityRowSchema(config: EntityConfig): z.ZodObject<z.ZodRawShape> {
+  const shape: z.ZodRawShape = {}
+  for (const col of entityColumns(config)) {
+    const field = config.fields[col.name]
+    shape[col.name] =
+      field !== undefined
+        ? field.zod()
+        : col.column.nullable === true
+          ? z.string().nullable()
+          : z.string()
+  }
+  return z.object(shape)
+}
+
+/** Schema Zod de create: só campos declarados; nullable/default viram opcionais. */
+export function entityInsertSchema(config: EntityConfig): z.ZodObject<z.ZodRawShape> {
+  const shape: z.ZodRawShape = {}
+  for (const [name, field] of Object.entries(config.fields)) {
+    const base = field.zod()
+    shape[name] =
+      field.column.nullable === true || field.column.hasDefault === true
+        ? base.optional()
+        : base
+  }
+  return z.object(shape)
+}
+
+/** Schema Zod de update: partial do insert. */
+export function entityUpdateSchema(config: EntityConfig): z.ZodObject<z.ZodRawShape> {
+  return entityInsertSchema(config).partial()
+}
+
+/** Nome da tabela: `table` explícito ou plural simples de `name`. */
+export function entityTable(config: EntityConfig): string {
+  if (config.table !== undefined) return config.table
+  const n = config.name
+  if (n.endsWith('y')) return `${n.slice(0, -1)}ies`
+  if (/(s|x|z|ch|sh)$/.test(n)) return `${n}es`
+  return `${n}s`
+}
+
+/**
+ * `true` se `value` parece um `EntityConfig`. Usado pra coletar entidades de
+ * `domain.models` (que é `unknown`) sem confundir com action/reaction/model.
+ * Heurística: tem `name` string + `fields` objeto e **não** tem `kind`
+ * (descarta `ActionDef`).
+ */
+export function isEntityConfig(value: unknown): value is EntityConfig {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.name === 'string' &&
+    typeof v.fields === 'object' &&
+    v.fields !== null &&
+    !('kind' in v)
+  )
+}
+
+// =============================================================================
+// Drift-check (comparador puro — sem Kysely)
+// =============================================================================
+
+/** Shape mínimo de coluna pra comparar entidade ↔ banco. */
+export interface ColumnShape {
+  name: string
+  nullable: boolean
+}
+
+export type DriftKind =
+  | 'missing_table'
+  | 'missing_column'
+  | 'extra_column'
+  | 'nullable_mismatch'
+
+export interface DriftFinding {
+  table: string
+  column?: string
+  kind: DriftKind
+  message: string
+}
+
+/**
+ * Convenção de nome de coluna. `snake` (default) mapeia camelCase → snake_case
+ * (idiomático Postgres); `identity` mantém; ou uma fn custom. Ver `docs/data-layer.md`.
+ */
+export type NamingStrategy = 'snake' | 'identity' | ((name: string) => string)
+
+/** camelCase → snake_case. `ownerId` → `owner_id`, `id` → `id`. */
+export function snakeCase(name: string): string {
+  return name.replace(/([A-Z])/g, '_$1').toLowerCase()
+}
+
+/** Resolve a estratégia num mapeador `nome → coluna`. */
+export function resolveNaming(naming: NamingStrategy): (name: string) => string {
+  if (naming === 'snake') return snakeCase
+  if (naming === 'identity') return (n) => n
+  return naming
+}
+
+/**
+ * Colunas desejadas (do `defineEntity`) no shape de comparação, com os nomes já
+ * mapeados pela `naming` (default `snake`) — pra bater com a introspecção crua
+ * do banco no drift-check.
+ */
+export function desiredColumns(
+  config: EntityConfig,
+  naming: NamingStrategy = 'snake',
+): ColumnShape[] {
+  const map = resolveNaming(naming)
+  return entityColumns(config).map((c) => ({
+    name: map(c.name),
+    nullable: c.column.nullable === true,
+  }))
+}
+
+/**
+ * Compara o schema desejado (entidade) com o real (banco). Puro: recebe os dois
+ * lados já normalizados. `actual: null` significa tabela inexistente.
+ *
+ * v1: compara presença e nullable. Tipos/defaults/índices/FK ficam pro passo 2.
+ */
+export function diffColumns(
+  table: string,
+  desired: ColumnShape[],
+  actual: ColumnShape[] | null,
+): DriftFinding[] {
+  if (actual === null) {
+    return [{ table, kind: 'missing_table', message: `Tabela "${table}" não existe` }]
+  }
+
+  const findings: DriftFinding[] = []
+  const actualByName = new Map(actual.map((c) => [c.name, c]))
+  const desiredNames = new Set(desired.map((c) => c.name))
+
+  for (const d of desired) {
+    const a = actualByName.get(d.name)
+    if (a === undefined) {
+      findings.push({
+        table,
+        column: d.name,
+        kind: 'missing_column',
+        message: `Coluna "${table}.${d.name}" existe na entidade mas não no banco`,
+      })
+      continue
+    }
+    if (a.nullable !== d.nullable) {
+      findings.push({
+        table,
+        column: d.name,
+        kind: 'nullable_mismatch',
+        message: `Coluna "${table}.${d.name}" deveria ser ${
+          d.nullable ? 'NULL-able' : 'NOT NULL'
+        } mas está ${a.nullable ? 'NULL-able' : 'NOT NULL'} no banco`,
+      })
+    }
+  }
+
+  for (const a of actual) {
+    if (!desiredNames.has(a.name)) {
+      findings.push({
+        table,
+        column: a.name,
+        kind: 'extra_column',
+        message: `Coluna "${table}.${a.name}" existe no banco mas não na entidade`,
+      })
+    }
+  }
+
+  return findings
+}

package/src/schema/format/locale.ts

@@ -0,0 +1,144 @@
+/**
+ * @softize/opus/schema/format/locale — helpers internos de formatação.
+ *
+ * Wrappa `Intl.*` com defaults pt-BR. Usado pelas factories de `t.*` pra
+ * implementar `.format(value, { locale })` sem repetir boilerplate.
+ *
+ * Não é parte da superfície pública — consumers acessam via `t.money().format(...)`.
+ */
+
+const DEFAULT_LOCALE = 'pt-BR'
+
+// =============================================================================
+// Numbers / decimals / percent
+// =============================================================================
+
+/**
+ * Formata número decimal seguindo locale. `value` é string canônica
+ * (dot como decimal separator) — convertemos pra Number antes do `Intl`.
+ */
+export function formatDecimal(
+  value: string,
+  locale: string = DEFAULT_LOCALE,
+  options?: Intl.NumberFormatOptions,
+): string {
+  const n = Number(value)
+  return new Intl.NumberFormat(locale, options).format(n)
+}
+
+/**
+ * Parse string decimal aceitando pt-BR ("1.234,56") ou en ("1234.56").
+ * Heurística: se contém vírgula, assume pt-BR (ponto = milhar, vírgula = decimal).
+ * Caso contrário, deixa como está. Resultado é string canônica (dot decimal).
+ */
+export function parseDecimal(input: string): string {
+  const trimmed = input.trim()
+  if (trimmed.includes(',')) {
+    // pt-BR: remove pontos (milhar), troca vírgula por ponto.
+    return trimmed.replace(/\./g, '').replace(',', '.')
+  }
+  return trimmed
+}
+
+// =============================================================================
+// Money — bigint cents
+// =============================================================================
+
+/**
+ * Formata bigint cents como moeda no locale.
+ * Ex: formatMoney(123456n, 'BRL', 'pt-BR') → "R$ 1.234,56"
+ */
+export function formatMoney(
+  cents: bigint,
+  currency: string,
+  locale: string = DEFAULT_LOCALE,
+): string {
+  // bigint → number pra Intl. Pra valores acima de Number.MAX_SAFE_INTEGER
+  // perdemos precisão, mas é trade-off aceitável pra formatação de display.
+  const value = Number(cents) / 100
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  }).format(value)
+}
+
+/**
+ * Parse string de moeda em bigint cents. Aceita "R$ 1.234,56", "1234.56",
+ * "1,234.56" (en com milhar), "1234,56" (pt-BR), etc.
+ * Retorna `null` se input não tem dígitos.
+ */
+export function parseMoney(input: string): bigint | null {
+  // Remove símbolos de moeda / espaços / NBSP — sobra dígitos, separadores e sinal.
+  const cleaned = input.replace(/[^\d.,\-]/g, '').trim()
+  if (cleaned === '' || cleaned === '-') return null
+
+  const negative = cleaned.startsWith('-')
+  const body = negative ? cleaned.slice(1) : cleaned
+
+  // Determina separador decimal: o último ponto-ou-vírgula é decimal se tiver
+  // exatamente 2 dígitos depois. Caso contrário, sem decimal.
+  const lastDot = body.lastIndexOf('.')
+  const lastComma = body.lastIndexOf(',')
+  const lastSep = Math.max(lastDot, lastComma)
+
+  let intPart: string
+  let fracPart: string
+
+  if (lastSep === -1) {
+    intPart = body
+    fracPart = ''
+  } else {
+    const tail = body.slice(lastSep + 1)
+    if (tail.length === 2) {
+      intPart = body.slice(0, lastSep).replace(/[.,]/g, '')
+      fracPart = tail
+    } else {
+      // Sem decimal — todos os separadores são milhar.
+      intPart = body.replace(/[.,]/g, '')
+      fracPart = ''
+    }
+  }
+
+  intPart = intPart.replace(/\D/g, '')
+  fracPart = fracPart.padEnd(2, '0').slice(0, 2)
+
+  if (intPart === '') intPart = '0'
+
+  const cents = BigInt(intPart) * 100n + BigInt(fracPart)
+  return negative ? -cents : cents
+}
+
+// =============================================================================
+// Datetime / date / time — pt-BR aware
+// =============================================================================
+
+/**
+ * Formata ISO datetime ("2026-05-28T13:45:00Z") como string humana.
+ * pt-BR → "28/05/2026 13:45". Outros locales delegam pra Intl.
+ */
+export function formatDatetime(iso: string, locale: string = DEFAULT_LOCALE): string {
+  const d = new Date(iso)
+  return new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(d)
+}
+
+/**
+ * Formata date "YYYY-MM-DD" como string humana. pt-BR → "28/05/2026".
+ * Constrói o Date em UTC pra evitar drift de timezone que mudaria o dia.
+ */
+export function formatDate(date: string, locale: string = DEFAULT_LOCALE): string {
+  const [y, m, d] = date.split('-').map(Number)
+  const utc = new Date(Date.UTC(y!, m! - 1, d!))
+  return new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric',
+    timeZone: 'UTC',
+  }).format(utc)
+}

package/src/schema/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @softize/opus/schema — driver-agnostic schema utilities.
+ *
+ * Aqui mora:
+ *   - Metadata machinery (`attachLogicalType`, `getLogicalType`) — armazena
+ *     logical type info anexada a qualquer Schema, independente de driver.
+ *   - Tipo `LogicalTypeMeta` re-exportado de `@softize/opus/core`.
+ *
+ * Drivers (zod) implementam factories (`t.*`) que usam essa machinery.
+ * OpenAPI gen (`./openapi`) consome a metadata pra anotar specs.
+ */
+
+import type { LogicalTypeMeta } from '../core/index.ts'
+
+// =============================================================================
+// Metadata mechanism (driver-agnostic)
+// =============================================================================
+
+// A implementação MUDOU pro core (a UI lê a meta do contrato e a fronteira SPA
+// só deixa ui tocar ui/lib/core) — re-export mantém a API pública daqui.
+export { attachLogicalType, getLogicalType } from '../core/logical-type.ts'
+
+export type { LogicalTypeMeta }
+
+// =============================================================================
+// Entity layer (defineEntity + relations + inferência)
+// =============================================================================
+
+export {
+  defineEntity,
+  belongsTo,
+  hasOne,
+  hasMany,
+  manyToMany,
+  entityColumns,
+  entityTable,
+  entityPk,
+  entityRowSchema,
+  entityInsertSchema,
+  entityUpdateSchema,
+  desiredColumns,
+  diffColumns,
+  isEntityConfig,
+  snakeCase,
+  resolveNaming,
+} from './entity.ts'
+export type {
+  EntityConfig,
+  EntityFields,
+  EntityRow,
+  EntityInsert,
+  EntityUpdate,
+  Relation,
+  RelationKind,
+  IndexSpec,
+  ResolvedColumn,
+  ColumnShape,
+  DriftKind,
+  DriftFinding,
+  NamingStrategy,
+} from './entity.ts'
+
+// — Scaffold de migration ——————————————————————————————————————————————————————
+export { scaffoldMigration, scaffoldFileContent, kyselyColumnType } from './scaffold.ts'
+export type { ScaffoldResult } from './scaffold.ts'