Buenas prácticas

Buenas prácticas operativas

Usa jsorm con límites de runtime explícitos y reglas de arranque predecibles. La configuración más segura en producción separa la responsabilidad de base de datos, el ciclo de vida de adaptadores y los deploys según el entorno.

1. Respeta los límites del runtime

• Usa @jsorm/core o @jsorm/node con adaptadores nativos en runtimes Node.
• Usa @jsorm/runtime con @jsorm/fetch solo en runtimes edge o fetch-only.
• Mantén el CLI, las migraciones y jsorm deploy en un entorno Node separado.

Precaución

@jsorm/fetch es transporte para queries en request-time, no responsabilidad de migraciones. No trates un bundle edge como el lugar donde deben ejecutarse cambios de schema.

2. Configura e inicializa de forma explícita

Si la config ya está en memoria, prefiere una inicialización explícita en lugar de depender del descubrimiento por filesystem:

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { pgAdapter } from '@jsorm/pg';

const main = defineConnectionSource({
  adapter: pgAdapter({
    name: 'main',
    connectionString: process.env.DATABASE_URL!,
  }),
});

const config = defineJsormConfig({
  connectionSources: { main },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init(config);

Usa este patrón cuando:

• la plataforma no expone jsorm.config.ts en disco
• quieres que el arranque falle rápido con una config conocida
• necesitas un único bootstrap compartido entre APIs, workers y scripts

createJsorm().configure(config) también es válido cuando quieres inyectar la config antes del primer uso.

3. Reutiliza adaptadores y recursos de runtime

Crea instancias del runtime en el arranque del proceso o del módulo, no dentro de cada request handler. Los runtimes compatibles reutilizan pools de adaptadores y recursos de workers, pero inicializar por request sigue añadiendo sobrecoste evitable.

Patrón recomendado:

• bootstrap una vez
• reutiliza el mismo runtime en handlers, jobs o módulos de servicio
• llama a db.close() durante el apagado graceful
• para testing: usa createJsormTest() para obtener un sandbox aislado en lugar de reutilizar el runtime de la aplicación

Esto mantiene los pools calientes, evita reinicios repetidos de workers y deja claro quién es dueño del ciclo de vida.

4. Separa readiness del tráfico de requests

Inicializa jsorm antes de servir tráfico cuando sea posible. Trata la disponibilidad de base de datos como una preocupación operativa, no como una sorpresa en el primer request real.

Enfoque recomendado:

1. inicializa el runtime durante el arranque de la app
2. ejecuta una verificación ligera de readiness que confirme config y conectividad
3. expón health checks que fallen si el runtime no puede alcanzar su source configurado
4. cierra el runtime durante el shutdown para drenar pools y workers limpiamente

En plataformas de vida corta, mantén la inicialización determinista y las probes ligeras.

5. Mantén la responsabilidad del deploy en Node

Ejecuta jsorm deploy desde CI, un release job u otro entorno Node controlado:

pnpm exec jsorm deploy --strict --verbose

Esto sigue siendo válido aunque el runtime de la aplicación sea solo edge. Los request handlers deben ejecutar queries; los jobs de deploy deben ser dueños de migraciones y verificación de schema.

6. Errores comunes

Error	Por qué duele	Opción más segura
Crear un runtime nuevo en cada request	Repite trabajo de arranque y fragmenta el control del ciclo de vida	Inicializa una vez y reutiliza
Usar adaptadores nativos dentro de edge isolates	Los runtimes edge normalmente no soportan TCP crudo ni binarios nativos	Usa @jsorm/runtime + @jsorm/fetch
Esperar que @jsorm/fetch ejecute migraciones	El transporte fetch no es dueño de migraciones	Ejecuta deploys desde @jsorm/node en Node
Depender de config en disco en runtimes restringidos	El descubrimiento por filesystem puede no existir o no ser deseable	Pasa la config explícitamente con init(config) o configure(config)
Olvidar la limpieza en shutdown	Pools y workers pueden quedar abiertos más tiempo del esperado	Llama a db.close() durante el apagado graceful

Checklist de producción

• Elige paquetes que correspondan al límite real del runtime.
• Inicializa jsorm explícitamente cuando la config ya exista en memoria.
• Reutiliza instancias del runtime en lugar de recrearlas por request.
• Añade readiness checks antes de enviar tráfico real.
• Mantén jsorm deploy y las migraciones en workflows de release dueños de Node.