App Services

packages/app-services/README.md

@repo/app-services

Servicios de aplicación reutilizables que encapsulan la lógica de dominio y el acceso a datos para el monorepo Nidus.

Índice

Función del package
Instalación
API — Surveys
Constantes de dominio
Tipos compartidos
Lineamientos de desarrollo
Contribución y validación

1. Función del package

Centraliza casos de uso compartidos entre apps.
Evita duplicar lógica de negocio en componentes o páginas.
Acepta dependencias externas (ej. Firestore) por parámetro para mantenerse desacoplado del proveedor.
Expone sus módulos como subpath exports independientes.

Subpath export	Contenido
`@repo/app-services/surveys`	`saveSurvey`, `getSurveys`
`@repo/app-services/constants`	`SURVEYS_COLLECTION`

2. Instalación

json

{
  "dependencies": {
    "@repo/app-services": "workspace:*"
  }
}

bash

pnpm install

3. API — Surveys

Importar desde @repo/app-services/surveys (subpath export) o desde @repo/app-services.

`saveSurvey(db, surveyData)`

Persiste una nueva encuesta en Firestore.

import { saveSurvey } from '@repo/app-services/surveys';
import type { CreateSurveyData, SurveyData } from '@repo/schemas';

const nueva: CreateSurveyData = {
  name: 'Martín García',
  email: 'martin@barrio.com',
  phone: '+541112345678',
  role: 'Administrador',
  control_methods: ['Sistema digital'],
  main_problem: 'No tenemos trazabilidad de las obras en curso.',
  neighborhood_size: '51-100',
  willingness_to_pay: 'Sí, si realmente funciona',
  willing_to_interview: 'Sí',
};

const guardada: SurveyData = await saveSurvey(db, nueva);
console.log(guardada.id); // ID generado por Firestore

Firma:

function saveSurvey(db: Firestore, surveyData: CreateSurveyData): Promise<SurveyData>;

Parámetro	Tipo	Descripción
`db`	`Firestore`	Instancia de Firestore (client o admin, según el contexto)
`surveyData`	`CreateSurveyData`	Datos de la encuesta sin metadatos (`id`, `createdAt`, `updatedAt`)

`getSurveys(db, dateRange?)`

Consulta encuestas desde Firestore con filtro opcional por rango de fechas.

import { getSurveys } from '@repo/app-services/surveys';

// Todas las encuestas
const todas = await getSurveys(db);

// Solo encuestas de un rango específico
const recientes = await getSurveys(db, {
  from: new Date('2025-01-01'),
  to: new Date('2025-01-31'),
});

Firma:

function getSurveys(db: Firestore, dateRange?: IDateRange): Promise<SurveysData>;

Parámetro	Tipo	Descripción
`db`	`Firestore`	Instancia de Firestore
`dateRange`	`IDateRange?`	Rango de fechas opcional. Filtra por `createdAt`.

4. Constantes de dominio

import { SURVEYS_COLLECTION } from '@repo/app-services/constants';

console.log(SURVEYS_COLLECTION); // 'surveys'

Constante	Valor	Descripción
`SURVEYS_COLLECTION`	`'surveys'`	Nombre de la colección Firestore

5. Tipos compartidos

// src/types/types.ts
export interface IDateRange {
  from: Date;
  to: Date;
}

Los tipos de las entidades (SurveyData, CreateSurveyData, SurveysData) están definidos en @repo/schemas y reexportados desde ahí.

6. Lineamientos de desarrollo

Separación de responsabilidades: lógica de dominio sin detalles de UI.
Inyección de dependencias: Firestore se pasa como parámetro, nunca se importa directamente.
Tipos explícitos: entrada y salida siempre tipados con interfaces de @repo/schemas.
Sin errores silenciosos: propagar o mapear errores de forma explícita.
Un módulo por contexto de negocio: no mezclar dominios en el mismo archivo.

Agregar un nuevo servicio

Crear src/<dominio>/<dominio>-service.ts.
Exportar desde src/index.ts o como subpath export nuevo en package.json.
Definir los contratos en @repo/schemas.
Documentar la API en este README.

7. Contribución y validación

bash

pnpm lint --filter @repo/app-services
pnpm build --filter @repo/app-services
pnpm check-types --filter @repo/app-services