@itbaf/tournaments-models

Modelos Prisma (MySQL) reutilizables para integraciones de torneos: clients, apiKeys, regions, countries, tournaments, editions, scores, scoreCriteria y más.
Incluye schema Prisma, migraciones versionadas y cliente Prisma listo para usar en múltiples proyectos.

Índice

1. Objetivo de la librería
2. Tecnologías que utiliza
3. Instalación rápida
4. Configuración de entorno (.env)
5. Uso en un proyecto consumidor
   • 5.1 Usar el cliente Prisma del paquete
   • 5.2 Ejecutar migraciones del paquete
   • 5.3 Modelos disponibles
6. Desarrollo de la librería
   • 6.1 Agregar/editar modelos o relaciones
   • 6.2 Crear nuevas migraciones
   • 6.3 Probar localmente
   • 6.4 Publicar una nueva versión en npm
   • 6.5 Actualización y Migraciones
7. Notas y troubleshooting
8. Licencia

Objetivo de la librería

Centralizar el modelo de datos de torneos (y sus integraciones) en un solo paquete para:

• Evitar duplicar esquemas entre servicios y funciones.
• Desplegar migraciones de forma consistente desde cada proyecto consumidor.
• Reutilizar un PrismaClient listo para usar con todos los modelos de torneos.
• Mantener consistencia en la estructura de datos entre diferentes aplicaciones.

Tecnologías que utiliza

• TypeScript (ESM)
• Prisma ORM (datasource MySQL)
• Node.js 18+
• Migraciones gestionadas por Prisma

Instalación rápida

npm i @itbaf/tournaments-models
# o
pnpm add @itbaf/tournaments-models
# o
yarn add @itbaf/tournaments-models

El paquete incluye su propio schema.prisma, migraciones y cliente Prisma generado.
El cliente Prisma del paquete se genera automáticamente en la instalación.

Configuración de entorno (.env)

En el proyecto consumidor, definí la variable DATABASE_URL (MySQL). Ejemplos:

# .env del proyecto consumidor
DATABASE_URL="mysql://usuario:password@host:3306/nombre_db"

Esta URL es la que usarán las migraciones del paquete cuando se ejecuten desde tu proyecto.

Uso en un proyecto consumidor

5.1 Usar el cliente Prisma del paquete

import { db } from '@itbaf/tournaments-models'

const prisma = db()

// Ejemplos de uso
const tournaments = await prisma.tournament.findMany()
const regions = await prisma.region.findMany({ where: { enabled: true } })
const scores = await prisma.score.findMany({ 
  include: { 
    country: true, 
    edition: true 
  } 
})

5.2 Ejecutar migraciones del paquete

npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

O bien en package.json:

{
  "scripts": {
    "tournaments:migrate": "prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma"
  }
}

5.3 Modelos disponibles

La librería incluye los siguientes modelos:

• Client: Clientes que pueden crear torneos
• ApiKey: Claves de API para autenticación
• Region: Regiones geográficas habilitadas por cliente
• Country: Países del mundo
• RegionCountry: Relación muchos-a-muchos entre regiones y países
• Tournament: Torneos creados por clientes
• TournamentEdition: Ediciones de torneos con fechas y criterios
• Score: Puntuaciones de usuarios en torneos
• ScoreCriterion: Criterios de puntuación para torneos

Desarrollo de la librería

6.1 Agregar/editar modelos o relaciones

Editá prisma/schema.prisma.

6.2 Crear nuevas migraciones

npx prisma migrate dev --name <descripcion> --schema ./prisma/schema.prisma

6.3 Probar localmente

npm i
npx prisma generate --schema ./prisma/schema.prisma
npm run build
export DATABASE_URL="mysql://user:pass@localhost:3306/prueba"
npx prisma migrate deploy --schema ./prisma/schema.prisma

6.4 Publicar una nueva versión en npm

npm run release:patch   # fixes
npm run release:minor   # nuevas features
npm run release:major   # cambios incompatibles

Luego en el consumidor:

npm update @itbaf/tournaments-models
npm run tournaments:migrate

6.5 Actualización y Migraciones

Importante: Flujo de actualización para proyectos consumidores

Cuando se publica una nueva versión del paquete, los proyectos consumidores deben seguir este flujo:

1. Actualizar el paquete:

   npm update @itbaf/tournaments-models
   # o
   npm install @itbaf/tournaments-models@latest

2. Verificar si hay nuevas migraciones:

   # Listar migraciones pendientes
   npx prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

3. Aplicar migraciones pendientes:

   npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

4. Regenerar el cliente Prisma (si es necesario):

   npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

Scripts recomendados para package.json del consumidor:

{
  "scripts": {
    "tournaments:update": "npm update @itbaf/tournaments-models && npm run tournaments:migrate",
    "tournaments:migrate": "prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma",
    "tournaments:status": "prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma"
  }
}

Cuándo ejecutar migraciones:

• ✅ SÍ ejecutar: Al instalar/actualizar el paquete
• ✅ SÍ ejecutar: Al hacer deploy en producción
• ✅ SÍ ejecutar: Al cambiar de versión del paquete
• ❌ NO ejecutar: En cada build/compilación del proyecto
• ❌ NO ejecutar: En cada request HTTP

Notas y troubleshooting

• Node 18+ recomendado.
• Si el consumer no tiene Prisma CLI:

  npx -p prisma prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

• prisma/generated/client se crea con prisma generate, no hace falta versionarlo.
• Las migraciones (prisma/migrations) sí se versionan.

Problemas comunes con migraciones:

Error: "Migration failed"

# Verificar estado de migraciones
npx prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

# Si hay conflictos, resetear y aplicar desde cero
npx prisma migrate reset --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

Error: "Database schema is out of sync"

# Regenerar cliente Prisma
npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

# Verificar que el schema coincida con la base de datos
npx prisma db pull --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

Migraciones en entornos de CI/CD:

# Script recomendado para pipelines
npm ci
npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

Versionado semántico del paquete:

• PATCH (1.0.1): Solo fixes, no requieren migraciones
• MINOR (1.1.0): Nuevas features, pueden requerir migraciones
• MAJOR (2.0.0): Cambios incompatibles, siempre requieren migraciones

Nota: Antes de actualizar a una versión MAJOR, revisar el changelog y las migraciones pendientes.

Licencia

MIT