Introducción

¿Qué es JSORM?

jsorm es un ORM JSON-first para TypeScript enfocado en claridad, tipado fuerte y comportamiento SQL explícito. En lugar de builders encadenados o metadatos de decoradores, describes la intención con objetos planos — el ORM los convierte a través de un AST estructurado en SQL parametrizado.

Idea central

Describe una query con un objeto plano:

import { jsorm } from 'jsorm';

const users = await jsorm.get(User, {
  select: {
    id: true,
    name: true,
    role: { name: true },
  },
  where: {
    active: true,
    role: { name: { eq: 'admin' } },
  },
  orderBy: [{ name: 'asc' }],
  pagination: { perPage: 10, currentPage: 1 },
});
// Tipado como: Array<{ id: number; name: string; role: { name: string } }>

El ORM convierte eso en un AST estructurado y emite SQL parametrizado a través del adaptador configurado. Sin interpolación de strings. Sin joins mágicos. Sin eager loading oculto.

Qué hace diferente a jsorm

Queries JSON-first

Describe lecturas, escrituras y mutaciones de relaciones con objetos planos en lugar de builders opacos.

Generación SQL basada en AST

La estructura interna de la query permanece inspeccionable y versionable antes de convertirse en SQL. Inspecciona con query.ast.

Inferencia de tipos desde modelos

defineModel() es la fuente única de verdad para tipos TypeScript y metadatos en runtime — sin archivos de schema separados.

Builders de relaciones explícitos

belongsTo, hasOne, hasMany y manyToMany definen el comportamiento SQL exacto por adelantado. Nada se carga implícitamente.

Migraciones opcionales

Conéctate a una base de datos existente de inmediato. Adopta el runtime de migraciones solo cuando necesites gestión del ciclo de vida del schema.

Adaptadores modulares

PostgreSQL, MySQL, SQLite o un adaptador de pool personalizado. El núcleo no tiene dependencias de drivers de BD.

Visión general de la arquitectura

defineModel()  →  Objeto JSON de query
                        ↓
               normalizar + validar
                        ↓
               AST estructurado (inspeccionable)
                        ↓
               Motor Rust → generación SQL
                        ↓
               SQL parametrizado + params
                        ↓
               adaptador ejecuta + mapea filas
                        ↓
               resultado tipado (inferido del modelo)

Cuándo jsorm encaja bien

Backends TypeScript

Inferencia de tipos basada en modelos que coincide con tu schema de base de datos — sin paso de codegen.

Equipos que prefieren SQL explícito

¿Prefieres SQL predecible sobre eager loading mágico? jsorm hace visible cada join en el objeto de query.

Proyectos multi-adaptador

PostgreSQL, MySQL, SQLite o pools personalizados — cambia adaptadores sin tocar el código de queries.

Bases de datos existentes

Usa jsorm sobre un schema existente sin ninguna ceremonia de migración.

Cuándo jsorm puede no encajar

Browser / edge runtimes — jsorm requiere el binario del motor Rust (solo servidor).
Entidades basadas en decoradores — prefiere TypeORM o MikroORM para el estilo @Entity() / @Column().
Transacciones auto-gestionadas — jsorm expone hooks jsorm.transaction() pero no hace begin/commit implícito.

Próximos pasos

Instalación Provisiona el motor, instala el adaptador y crea jsorm.config.ts.

Inicio rápido Define tu primer modelo y ejecuta queries tipadas en minutos.