drizzle-resource · open source · MIT

Typed list endpoints
for Drizzle ORM.

Define a resource on a Drizzle table. You get request validation, filters, search, sorting, pagination, facets and totals, with the SQL and the TypeScript types to match. Select a key to see what it adds.

Get started →
orders.resource.ts14 lines
1export const orders = engine.defineResource("orders", {
2 views: { list: { select: { reference: true,
3 totalAmount: true, customer: { select: { name: true } } } } },
4 query: {
5 scope: (f, ctx) => f.is("customer.orgId", ctx.orgId),
6 search: { allowed: ["reference", "customer.name"] },
7 sort: { defaults: [{ key: "createdAt", dir: "desc" }] },
8 facets: { allowed: ["status"] },
9 pagination: { modes: ["cursor"] },
10 },
11 summary: (o) => ({
12 revenue: sum(o.totalAmount),
13 }),
14});
Request it acceptsvalidated
{
  view: "list",
  search: { value: "halv" },
  sorting: [{ key: "createdAt", dir: "desc" }],
  facets: [{ key: "status" }],
  pagination: { mode: "cursor", pageSize: 25 },
  summary: true,
}
// orgId comes from the server, never the client
SQL it runsPostgreSQL
select "reference", "total_amount", c."name"
from "orders" join "customers" c on ...
where c."org_id" = $1
  and ("reference" ilike $2 or c."name" ilike $2)
order by "created_at" desc, "id" desc
limit 26
-- one aggregate statement
select "status", count(*), sum("total_amount")
group by grouping sets (("status"), ())
Types you getinferred
type Row = {
  reference: string; totalAmount: number;
  customer: { name: string }
}
type Response = {
  rows: Row[];
  pageInfo: { nextCursor: string | null };
  facets: { status: { value: string; count: number }[] };
  summary: { revenue: string | null };
}
type SortKey = "createdAt" | "reference" | …
type SearchField = "reference" | "customer.name"
Table it powersyour UI
🔒 acmeSearch “halv”
shipped 612
pending 231
processing 264
cancelled 98
referencecustomertotal
ORD-29999Halvorsen Freight$4,128
ORD-29981Halvorsen Freight$790
ORD-29944Halvorsen Freight$2,310
sorted by createdAt ↓
revenue $411,230Next →

scopeThe tenant rule wraps every request on the server. The client can't send it or remove it.

One resource, every list feature

Define a resource once on a Drizzle table. Each of these works on the server from that definition, with no endpoint code of your own.

What happens to a request

Every list request runs the same six stages on your server, in this order. Pick a request and follow it through.

Requestsearch "halv" · status is shipped
Response rows · count · facets
01

Validate

Every key, operator and path is checked against the resource.

02

Scope

The tenant condition comes from your server, never from the client.

03

Count

One count over every match, for the pager or your own totals.

04

Page ids

Filters, search and sort pick only this page's ids.

05

Rows

The rows load by id with their relations, in your view's shape.

06

Facets

Bucket counts per value, each ignoring its own filter.

Try it on a live table

2,412 sample orders, in your browser. Search, filter, sort and page: the line of the resource that allows each action lights up. Open the full playground →

orders.resource.tsthe only file you write
1export const orders = engine.defineResource("orders", {
2 relations: { customer: true,
3 orderLines: { with: { product: true } } },
4 query: {
5 scope: (f, ctx) => f.is("customer.orgId", ctx.orgId),
6 search: { allowed: ["reference", "customer.name"] },
7 sort: {
8 defaults: [{ key: "createdAt", dir: "desc" }],
9 disabled: ["orderLines.product.name"],
10 },
11 facets: {
12 allowed: ["status", "orderLines.product.category"],
13 },
14 pagination: { modes: ["cursor", "offset"] },
15 },
16 summary: (o) => ({
17 rows: count(), revenue: sum(o.totalAmount),
18 }),
19});
Orders
ORD-29999Halvorsen FreightHalden 14$4,1282026-11-17
ORD-29995Nordvik EnergyCirrus Headphones$5772026-11-16
ORD-29991Quarry Lane StudioHalden 14$1,6352026-11-16
ORD-29987Brightwater LabsCumulus SSD 2TB$2,6972026-11-16
ORD-29983Brightwater LabsStratus Router$6312026-11-16
ORD-29979Pell Street BankCumulus SSD 2TB$2,5012026-11-16
ORD-29975Pell Street BankFjord Pro 16$3082026-11-16
ORD-29971Lindqvist DentalStratus Router$2362026-11-16
rows · count()2,412
revenue · sum()$4,534,927
first page

Benchmarks

Median timings from the repository's PostgreSQL benchmark: 200,000 rows, PostgreSQL 18, one client. Bright pixels are today's time; dim pixels show what version 2.4.1 took.

Median latency, ms200,000 rows · PostgreSQL 18 · 1 client
40.0msPage, no count 2.4.1: 39.95 msstatements: 1 → 1
62.5msPage + exact count 2.4.1: 62.46 msstatements: 2 → 2
79.5msRelation search 2.4.1: 79.46 msstatements: 2 → 2
90.0ms3 root facets 2.4.1: 90.03 msstatements: 3 → 1
195.0ms5 mixed facets 2.4.1: 195.04 msstatements: 5 → 2
138.2msExclude-self facets 2.4.1: 138.22 msstatements: 5 → 3

Source: benchmark results, run of November 18, 2026. Single-client engine timings, not HTTP or production latency.

Getting started

Install the package, create the engine once, define a resource per table, and validate incoming requests with the schema it generates.

01

Install

bun add drizzle-resource
02

Create the engine once

import { createQueryEngine } from "drizzle-resource";

export const engine = createQueryEngine({ db, schema, relations })
  .withContext<{ orgId: string }>();
03

Define a resource per table

export const orders = engine.defineResource("orders", {
  relations: { customer: true },
  query: {
    scope: (f, ctx) => f.is("customer.orgId", ctx.orgId),
    search: { allowed: ["reference", "customer.name"] },
    facets: { allowed: ["status"] },
  },
});
04

Validate the request in your endpoint

const Request = requestSchema(orders); // zod, valibot or vine

app.post("/orders/query", async (c) => {
  const request = Request.parse(await c.req.json());
  return c.json(await orders.query({ request, context }));
});
drizzle-resource
Copyright © 2026