Schemas

packages/schemas/README.md

@repo/schemas

Contrato de validación y tipos compartidos basado en Zod para el monorepo Nidus.

Índice

  1. Función del package
  2. Schemas disponibles
  3. Tipos inferidos
  4. Constantes de validación
  5. Validación en runtime
  6. Estructura de archivos
  7. Lineamientos de desarrollo
  8. Contribución y tests

1. Función del package

  • Define esquemas de datos reutilizables con Zod.
  • Comparte reglas de validación entre frontend (formularios) y backend (Firestore).
  • Exporta tipos TypeScript inferidos desde los schemas.
  • Evita inconsistencias de tipos entre módulos del monorepo.

2. Schemas disponibles

surveySchema

Valida el documento completo de una encuesta tal como se almacena en Firestore.

ts
import { surveySchema } from '@repo/schemas';

const resultado = surveySchema.safeParse(data);
if (resultado.success) {
  console.log(resultado.data.email);
}

Campos:

CampoTipoDescripción
idstringID generado por Firestore
pathstringPath del documento en Firestore
createdAtstringTimestamp de creación
updatedAtstringTimestamp de última actualización
namestring (min 1)Nombre completo del encuestado
emailstring (email válido)Email del encuestado
phonestringNúmero de teléfono
roleROLE_OPTIONSRol del encuestado en el barrio
control_methodsArray<METHODS_OPTIONS> (min 1)Métodos actuales de control de obras
main_problemstring (min 1)Principal problema de gestión
neighborhood_sizeNEIGHBORHOOD_SIZE_OPTIONS|nullCantidad de lotes del barrio
willingness_to_payWILLINGNESS_TO_PAY_OPTIONSDisposición a pagar por la plataforma
willing_to_interviewWILLING_TO_INTERVIEW_OPTIONSDisponibilidad para entrevista de usuario

surveyDataSchema

Array de surveySchema. Usado para validar colecciones completas retornadas por Firestore.

ts
import { surveyDataSchema } from '@repo/schemas';

const encuestas = surveyDataSchema.parse(rawArray);

createSurveyDataSchema

Versión del schema sin los campos generados por el servidor (id, path, createdAt, updatedAt). Usado para validar el payload de creación de una nueva encuesta.

ts
import { createSurveyDataSchema } from '@repo/schemas';

const input = createSurveyDataSchema.parse({
  name: 'Ana Rodríguez',
  email: 'ana@barrio.com',
  phone: '+5491187654321',
  role: 'Propietario',
  control_methods: ['WhatsApp', 'Papel / Cuaderno'],
  main_problem: 'Todo se maneja por WhatsApp y no hay registro.',
  neighborhood_size: '51-100',
  willingness_to_pay: 'Sí, bajo costo (menos de $3.000 por lote/mes)',
  willing_to_interview: 'Por ahora no',
});

3. Tipos inferidos

ts
import type { SurveyData, SurveysData, CreateSurveyData } from '@repo/schemas';

// Documento completo de Firestore
type SurveyData = z.infer<typeof surveySchema>;

// Array de documentos
type SurveysData = z.infer<typeof surveyDataSchema>;

// Payload de creación (sin metadatos del servidor)
type CreateSurveyData = z.infer<typeof createSurveyDataSchema>;

4. Constantes de validación

Todas las constantes son arrays as const que alimentan los enums del schema y los <select> del formulario.

ts
import {
  ROLE_OPTIONS,
  METHODS_OPTIONS,
  NEIGHBORHOOD_SIZE_OPTIONS,
  WILLINGNESS_TO_PAY_OPTIONS,
  WILLING_TO_INTERVIEW_OPTIONS,
} from '@repo/schemas';
ConstanteValores
ROLE_OPTIONS'Administrador', 'Arquitecto', 'Portería', 'Propietario', 'Consejo del barrio'
METHODS_OPTIONS'Planillas / Excel', 'WhatsApp', 'Papel / Cuaderno', 'Sistema digital', 'No hay un control claro'
NEIGHBORHOOD_SIZE_OPTIONS'1-50', '51-100', '101-200', 'Más de 200'
WILLINGNESS_TO_PAY_OPTIONS'No', 'Sí, bajo costo...', 'Sí, costo medio...', 'Sí, si realmente funciona'
WILLING_TO_INTERVIEW_OPTIONS'Sí', 'Por ahora no'

5. Validación en runtime

ts
// safeParse — no lanza, retorna { success, data } o { success, error }
const resultado = createSurveyDataSchema.safeParse(inputDelFormulario);
if (!resultado.success) {
  console.error(resultado.error.flatten());
}

// parse — lanza ZodError si falla
const encuesta = surveySchema.parse(docDeFirestore);

6. Estructura de archivos

packages/schemas/ ├── index.ts # Re-exports desde ./firestore └── firestore/ ├── index.ts # Re-exports: schemas, tipos y constantes └── surveys.schema.ts # Definición del schema, tipos y constantes de encuestas

7. Lineamientos de desarrollo

  1. Todo schema nuevo debe representar una entidad o contrato reutilizable.
  2. Exportar schemas y tipos desde index.ts.
  3. Nombres semánticos: userSchema, expenseSchema, etc.
  4. Definir infer types junto a cada schema para evitar sincronización manual.
  5. Reutilizar composición Zod (omit, pick, extend) en lugar de duplicar reglas.
  6. Testear edge-cases en validaciones críticas.

Agregar un nuevo schema

  1. Crear firestore/<entidad>.schema.ts.
  2. Exportar desde firestore/index.ts y desde index.ts.
  3. Documentar campos y constantes en este README.
  4. Escribir tests en firestore/tests/.

8. Contribución y tests

bash
pnpm lint --filter @repo/schemas
pnpm build --filter @repo/schemas
pnpm check-types --filter @repo/schemas
pnpm test --filter @repo/schemas