Runtimes

Elige paquetes según el límite del runtime

jsorm separa las APIs de authoring, los imports runtime-safe, la propiedad del CLI y el transporte hacia la base de datos para que cada entorno use solo lo que realmente puede ejecutar.

Selección de paquetes de un vistazo

Paquete	Úsalo para	No lo uses para
@jsorm/core	Paquete principal para modelos, queries, tipos de config y primitivas de migración en apps con Node	Bundles edge que no pueden usar APIs de Node o binarios nativos
@jsorm/runtime	Código de aplicación universal o edge-safe, además de inyección directa de config cuando no hay acceso al filesystem	Ser dueño del CLI jsorm
@jsorm/node	Paquete de tooling y runtime para Node y Bun. En Node, provee el puente al motor Rust y la plomería de adaptadores nativos para migraciones y deploy. En Bun, detecta la configuración de Bun y usa las APIs nativas de Bun directamente (sin motor Rust)	Propiedad del CLI o request handlers edge
@jsorm/fetch	Transporte HTTP/fetch para bases de datos en runtimes sin sockets TCP o binarios nativos	Propiedad de migraciones o jsorm deploy
@jsorm/pg, @jsorm/mysql, @jsorm/sqlite	Adaptadores nativos para acceso directo a la base de datos desde Node	Runtimes edge sin acceso TCP crudo

Combinaciones recomendadas

• Runtime de app en Node: @jsorm/core o @jsorm/node con un paquete de adaptador nativo
• Runtime Bun: @jsorm/node — detecta Bun y usa las APIs nativas de Bun directamente, sin motor Rust
• Runtime edge: @jsorm/runtime con @jsorm/fetch
• CI, release y deploy: @jsorm/core + @jsorm/node en un entorno Node 24+

Precaución

@jsorm/fetch es transporte runtime-safe para queries, no un adaptador de migraciones. Mantén jsorm deploy y el resto de workflows de migración en un entorno Node separado.

Guía por entorno

Servicios y workers en Node

Usa adaptadores nativos cuando tu runtime puede abrir conexiones directas a la base de datos y ejecutar APIs de Node.

pnpm add @jsorm/core @jsorm/node @jsorm/pg pg

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);

Este formato encaja para servidores de larga vida, workers en background y apps Node en contenedores.

Servicios y scripts en Bun

Usa @jsorm/node en Bun. El paquete detecta el runtime Bun y usa las APIs nativas SQLite, MySQL y PostgreSQL de Bun directamente — sin el motor Rust.

pnpm add @jsorm/core @jsorm/node @jsorm/pg pg

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);

En Bun, las llamadas al adaptador usan las bindings nativas de Bun en lugar del worker Rust. La API de consulta, inferencia de tipos y forma de la config son idénticas a Node.

Runtimes edge y fetch-only

Usa imports runtime-safe junto con @jsorm/fetch cuando el runtime de request no puede usar sockets TCP crudos ni binarios nativos.

pnpm add @jsorm/runtime @jsorm/fetch
pnpm add -D @jsorm/node

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/runtime';
import { fetchAdapter } from '@jsorm/fetch';

const main = defineConnectionSource({
  adapter: fetchAdapter({
    name: 'main',
    dialect: 'postgres',
    endpoint: process.env.SQL_HTTP_ENDPOINT!,
    headers: () => ({
      authorization: `Bearer ${process.env.SQL_HTTP_TOKEN!}`,
    }),
  }),
});

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

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

Este es el camino recomendado para Vercel Edge, Cloudflare Workers y otros runtimes que solo exponen fetch.

Workflows de CI y deploy

Ejecuta los comandos de migración y deploy desde Node, incluso si la aplicación corre en edge.

pnpm exec jsorm deploy --strict --verbose

Lugares típicos para ejecutarlo:

• GitHub Actions
• un release container o init job
• un paso de deploy en Node antes del rollout

Matriz rápida de decisión

Entorno	Paquete runtime	Transporte	Dueño de migraciones/deploy
API/servidor Node	@jsorm/core o @jsorm/node	adaptador nativo	el mismo runtime Node o un job de CI
Servicio/script Bun	@jsorm/node	API nativa de Bun	el mismo runtime Bun o CI (Node)
Vercel Edge / Workers	@jsorm/runtime	@jsorm/fetch	job separado con @jsorm/core + @jsorm/node
Pipeline de CI / release	@jsorm/core + @jsorm/node	adaptador nativo	@jsorm/core + @jsorm/node

Modo engine y workers

jsorm usa un proceso worker persistente por defecto en runtimes Node para eliminar el sobrecoste de crear procesos por cada query. Cuando se omite engine.mode en jsorm.config.ts, por defecto usa "worker".

// jsorm.config.ts
export default defineJsormConfig({
  engine: {
    // el mode por defecto es "worker"
    worker: {
      startupTimeoutMs: 5_000,
      requestTimeoutMs: 10_000,
      restartLimit: 3,
    },
  },
});

Puedes recurrir a la ejecución tradicional por query estableciendo explícitamente engine.mode: "spawn" si es necesario. Ten en cuenta que el modo worker es solo para el runtime Node.js — en Bun, @jsorm/node evita el motor Rust por completo y usa las APIs nativas de Bun.

Recursos compartidos y aislamiento

Los runtimes en el mismo proceso Node comparten pools de adaptadores y procesos worker de Rust cuando su configuración efectiva coincide.

• createJsorm(): Las instancias estándar participan automáticamente en el registro de recursos compartidos. Esto evita recrear pools de conexiones a la BD a través de importaciones repetidas.
• createJsormTest(): Las instancias de sandbox para testing desactivan intencionalmente el descubrimiento de config por filesystem y aíslan sus recursos por defecto, previniendo que los tests colisionen usando los pools de otros.

import { createJsorm, createJsormTest } from '@jsorm/core';

// Reutiliza pools de conexiones y workers compartidos según el fingerprint de config
const appDb = await createJsorm().init();

// Usa recursos aislados por defecto
const testDb = await createJsormTest().init();

Adaptadores nativos

Elige el paquete de adaptador que coincide con tu base de datos:

• PostgreSQL → @jsorm/pg
• MySQL / PlanetScale → @jsorm/mysql
• SQLite → @jsorm/sqlite

Instala solo los adaptadores que realmente uses. Los paquetes core no incluyen drivers de base de datos por defecto.

Buenas prácticas

1. Separa los imports de app/runtime de la propiedad del CLI.
2. Usa adaptadores nativos en Node y @jsorm/fetch solo en runtimes fetch-only.
3. En Bun, @jsorm/node detecta el runtime automáticamente — el mismo paquete funciona tanto en Node como en Bun.
4. Ejecuta jsorm deploy fuera de funciones edge.
5. Trata CI y release jobs como entornos Node con responsabilidad completa sobre migraciones.