Queries

Construcción

jsorm usa una forma estructurada de query JSON en lugar de builders encadenados.

Consejo

Los ejemplos asumen const db = await createJsorm().init(); en tu bootstrap de aplicación.

Select

const rows = await db.get(User, {
  select: {
    id: true,
    name: true,
    role: { name: true },
    _count: true,
  },
  where: {
    AND: [
      { active: true },
      { role: { name: { eq: 'admin' } } },
    ],
  },
  orderBy: [{ createdAt: 'desc' }],
});

Cuando omites pagination, get() aplica un LIMIT 150 por defecto para evitar lecturas masivas accidentales. Puedes sobreescribir con JSORM_LIMIT_DEFAULT.

Operadores escalares en where

Operador	Comportamiento
{ eq: value }	Igual
{ ne: value }	Distinto
{ gt: value }	Mayor que
{ gte: value }	Mayor o igual
{ lt: value }	Menor que
{ lte: value }	Menor o igual
{ in: [...] }	Valor dentro de lista
{ contains: string }	LIKE %value%
{ startsWith: string }	LIKE value%
{ endsWith: string }	LIKE %value

Operadores lógicos

const rows = await db.get(User, {
  select: { id: true, name: true },
  where: {
    OR: [
      { email: { contains: '@corp.com' } },
      { role: { name: { eq: 'admin' } } },
    ],
  },
});

Paginación por cursor

const page = await db.get(User, {
  select: { id: true, name: true },
  orderBy: [{ id: 'asc' }],
  cursor: {
    after: '...token-base64url-opaco...',
    take: 25,
  },
});
// page.pageInfo: { hasNextPage, hasPreviousPage, startCursor, endCursor }

Reglas de cursor:

• El modo cursor requiere orderBy
• jsorm agrega automáticamente un tie-breaker por clave primaria cuando hace falta
• cursor.take se limita por JSORM_CURSOR_HARD_MAX_LIMIT (default 1000)

Insert / update / delete

await db.insert(User, {
  name: 'Alice',
  createdAt: new Date(),
  role: { connect: 1 },
});

await db.update(User, {
  data: { active: false },
  where: { id: { eq: 10 } },
});

await db.delete(User, {
  where: { id: { eq: 10 } },
});

Precaución

where es obligatorio en update y delete.

Mutaciones de relaciones

await db.insert(User, {
  name: 'Bob',
  createdAt: new Date(),
  roles: [1, 2],
});

await db.update(User, {
  data: {
    roles: { connect: [3], disconnect: [1] },
  },
  where: { id: { eq: 5 } },
});

SQL raw

Usa solo el escape hatch documentado:

const rows = await db.raw.execute(
  'SELECT id, name FROM users WHERE active = $1 AND created_at > $2',
  [true, new Date('2024-01-01')],
);

const compiled = await db.raw.compile(
  'SELECT id, name FROM users WHERE active = $1',
  [true],
);

Precaución

Usa siempre placeholders ($1, ?) y arrays de parámetros. Nunca interpoles input no confiable en strings SQL.

Buenas prácticas

1. Mantén where explícito en todas las escrituras.
2. Prefiere filtros de relación anidados sobre SQL manual con joins.
3. Usa orderBy junto con paginación para endpoints estables.
4. Usa paginación por cursor para datasets grandes o scroll infinito.
5. Reserva db.raw.* para queries que el DSL JSON no puede expresar limpiamente.