Queries & live data

Eén keer lezen. Of live blijven.

Maak een client aan met je schema, de Worker-URL, een workspace-ID en een token-callback. Je applicatie levert deze verbindingswaarden.

import { createClient } from "tapedb";
import schema from "./tapedb.schema";

const db = createClient({ schema, url, workspace, getToken });

const open = await db.task.findMany({
  where: { done: false, due: { lt: Date.now() } },
  orderBy: { due: "asc" },
  take: 50,
  include: { column: { include: { board: true } } },
});

findMany geeft elke overeenkomende rij terug tenzij je take meegeeft; take en findPage hebben geen bovengrens. Brede reads draaien onder de motorkap als begrensde statements: keyset-chunks van 1.000 rijen, met includes die 1.000 ouders per keer hydrateren.

Eén rij, een telling, een pagina

const one = await db.task.findUnique({ where: { id } });   // rij of null

const total = await db.task.count({ where: { done: false } });

const page = await db.task.findPage({ orderBy: { due: "asc" }, take: 50 });
// { rows, hasMore, cursor } — geef cursor terug mee als `after`

const first = await db.task.findFirst({ where: { done: false } }); // eerste match of null

Paginering is keyset, dus een insert boven het venster kan een rij niet herhalen.

Select en include

select geeft alleen de velden terug die je noemt; relaties in select krijgen hun eigen select:

const titles = await db.task.findMany({
  select: { title: true, column: { select: { name: true } } },
});
// { title: string; column: { name: string } | null }[]

De engine leest en verstuurt alleen die kolommen, plus de id van de rij waarop live-updates sleutelen. Een live select krijgt alleen een update als een geselecteerd veld veranderde. select en include worden niet op hetzelfde niveau gecombineerd.

Aggregates

Aggregates nemen dezelfde where en geven alleen de gevraagde maten terug:

const stats = await db.task.aggregate({
  where: { done: false },
  _count: true,                       // of { _all: true, due: true } voor counts van niet-null waarden
  _sum: { points: true },
  _avg: { points: true },
  _min: { due: true },
  _max: { due: true },
});

const perColumn = await db.task.groupBy({
  by: ["columnId"],
  _count: true,
  _sum: { points: true },
  orderBy: { columnId: "asc" },
  take: 20,
});

Ze draaien als één GROUP BY-statement over de rijen die de caller mag lezen. Een filter()-leesregel wordt erin gecompileerd; een model met een functie als leesregel wordt rij voor rij toegepast nadat de regel liep. Counts en aggregates zijn live met subscribe.

Filters

Filters ondersteunen not, in, notIn, gt, gte, lt, lte, en AND / OR / NOT over hele filters.

Een to-one-relatie neemt een filter op de rij waarnaar hij wijst; een to-many-relatie neemt some, every of none:

await db.column.findMany({ where: { board: { archived: false } } });
await db.board.findMany({ where: { columns: { some: { tasks: { none: {} } } } } });
await db.task.findMany({ where: { column: null } });          // geen ouder

Deze compileren naar gecorreleerde subqueries, dus gekoppelde rijen worden nooit opgehaald. De leesregel van het gekoppelde model wordt in de subquery gecompileerd; een model met een functie als leesregel wordt geweigerd als filtertarget. Types volgen één link; verdere hops controleert de engine. Relatiefilters nesten tot SQLite’s expressiediepte, ongeveer acht hops; brede filters zijn niet begrensd.

Alles wat de engine beslist (rechten, een ontbrekende rij, een conflict) komt naar boven wanneer je de query await, of in de error van een live query.

Live

Een query wordt live wanneer je je erop abonneert:

const stop = db.task
  .findMany({ where: { done: false }, orderBy: { due: "asc" } })
  .subscribe(({ data }) => renderTasks(data));

// Als de weergave wordt opgeruimd:
stop();

Na een commit draaien alleen subscriptions opnieuw waarvan de query een gewijzigd model raakt, gebundeld per 50 ms, en clients ontvangen verschillen per rij. Counts en aggregates blijven ook live. Een live select krijgt alleen een update als een geselecteerd veld veranderde.

React-bindings (useLive, useLivePage, usePresence, useBroadcast) staan in React.