Instalación

Requisitos previos

• Node.js 18 o superior
• TypeScript 5.0 o superior (strict: true recomendado)
• pnpm, npm o bun

Precaución

jsorm requiere un binario del motor Rust en tiempo de ejecución. El comando init lo provisiona automáticamente. Sin el binario, la ejecución se detiene con un error explícito — no hay fallback silencioso a TypeScript.

Bootstrap con jsorm init

El punto de entrada recomendado para cualquier proyecto nuevo es el comando interactivo jsorm init. Se encarga de todo: selección de adaptador, instalación de paquetes, provisión del binario del motor y generación del archivo de configuración.

pnpm

pnpm dlx jsorm@latest init

npm

npx jsorm@latest init

bun

bunx jsorm@latest init

1. Solicita la ruta de entrada del schema — por defecto src/schema/index.ts

2. Genera la estructura del schema con un modelo User de ejemplo:

   src/schema/main/user.ts
   src/schema/index.ts

3. Solicita el/los adaptador(es) — instala el paquete adaptador y su peer dependency

4. Provisiona el binario del motor Rust en node_modules/.jsorm/engine, verifica checksum y permisos

5. Escribe jsorm.config.ts — connection sources y migration sources listos para editar

6. Crea .env con un placeholder de DATABASE_URL (si no existe)

7. Crea .migrations/schema.json — snapshot vacío para generación de migraciones

jsorm.config.ts generado

Después de init, el proyecto tiene un archivo de configuración central compartido por el runtime y el CLI:

// jsorm.config.ts
import { defineConnectionSource, defineJsormConfig } from 'jsorm';
import { pgAdapter } from 'jsorm-pg';

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

export default defineJsormConfig({
  connectionSources: { main },
  defaults: {
    connectionSource: 'main',
  },
});

El singleton global jsorm carga este archivo automáticamente desde process.cwd() en el primer uso.

Paquetes

Paquete	Propósito	Peer dependency
jsorm	ORM core, singleton runtime, config, migraciones, CLI	—
jsorm-pg	Adaptador PostgreSQL	pg
jsorm-mysql	Adaptador MySQL	mysql2
jsorm-sqlite	Adaptador SQLite	sqlite3

Solo instala los adaptadores que realmente uses.

Orden de resolución del binario

1. Variable de entorno JSORM_ENGINE_PATH
2. node_modules/.jsorm/engine/jsorm-engine (.exe en Windows)
3. Instalaciones legacy .jsorm/bin/jsorm-engine

Si el binario no existe o falla la verificación de integridad, jsorm lanza un error con mensaje accionable:

[JSORM ENGINE MISSING] Run: pnpx jsorm init
[JSORM ENGINE INVALID] Integrity check failed
[JSORM VERSION MISMATCH] Incompatible AST/Engine versions

Nota sobre Edge runtimes

Precaución

jsorm requiere el runtime de Node.js. Los Edge runtimes están explícitamente bloqueados. En Next.js App Router agrega export const runtime = "nodejs" a cada route handler que use jsorm.

Configuración TypeScript

Asegúrate de que tu tsconfig.json incluya:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Buenas prácticas

1. Usa siempre pnpm dlx jsorm@latest init para proyectos nuevos — asegura que el motor y la config queden correctamente conectados.
2. Mantén DATABASE_URL y otras credenciales en .env, nunca commiteadas al repositorio.
3. Usa strict: true en tsconfig.json para aprovechar la inferencia de tipos completa.
4. Un jsorm.config.ts por proyecto — usado tanto por el runtime como por el CLI.