dbrest-ts

TypeScript SDK for dbREST — a high-performance REST API layer for PostgreSQL.

Install

pnpm add @dbrest-ts/client
# or
npm install @dbrest-ts/client

Quick start

import { createClient } from '@dbrest-ts/client'

const db = createClient('https://your-dbrest-server.example.com', {
  token: 'your-jwt-token',
})

// SELECT with filters
const { data: users, error } = await db
  .from('users')
  .select('id,name,email')
  .eq('status', 'active')
  .order('name', { ascending: true })
  .limit(10)

// SELECT single row
const { data: user } = await db
  .from('users')
  .select('id,name,email')
  .eq('id', 1)
  .single()

// INSERT
const { data: newUser } = await db
  .from('users')
  .insert({ name: 'Alice', email: 'alice@example.com' })
  .prefer({ return: 'representation' })

// UPDATE
const { data: updated } = await db
  .from('users')
  .update({ name: 'Alice Smith' })
  .eq('id', 1)
  .prefer({ return: 'representation' })

// DELETE
await db.from('users').delete().eq('id', 99)

// RPC (server-side functions)
const { data: result } = await db.rpc('search_posts', { query: 'hello' })

// Realtime subscriptions (SSE)
db.channel('users')
  .on('INSERT', (event) => console.log('New user:', event.new))
  .on('UPDATE', (event) => console.log('Updated:', event.new))
  .subscribe()

Authentication

// Static token
const db = createClient(url, { token: 'your-jwt' })

// Dynamic token provider (auto-caches, deduplicates refresh calls)
const db = createClient(url, {
  tokenProvider: async () => await getAccessToken(),
})

// Per-request override
const { data } = await db.from('users').select('*').auth('other-token')

// Schema switching
const tenant = db.schema('tenant_123')
const { data } = await tenant.from('users').select('*')

Packages

Package	Description	Path
@dbrest-ts/client	High-level facade (createClient)	packages/client
@dbrest-ts/rest	Low-level query builders, HTTP, auth, transport	packages/rest
@dbrest-ts/realtime	SSE-based realtime subscriptions	packages/realtime
@dbrest-ts/cli	Code generation CLI (npx dbrest-ts gen types)	packages/cli

Most users only need @dbrest-ts/client, which re-exports key types from the other packages.

Development

# Prerequisites: Node.js 20+, pnpm 9+

pnpm install            # Install dependencies
pnpm -r build           # Build all packages
pnpm test               # Run unit tests
pnpm lint               # Lint + format check (Biome)
pnpm format             # Auto-format
pnpm typecheck          # TypeScript type checking

Testing

Unit tests

pnpm test               # All unit tests across all packages

Unit tests use MSW mocks and require no external services.

Integration tests

# Option A: testcontainers (auto-starts Docker containers)
pnpm integration-test

# Option B: manual Docker Compose
docker compose -f packages/rest/test/smoke/docker-compose.smoke.yml up -d
DBREST_URL=http://localhost:3000 pnpm integration-test

Smoke tests

docker compose -f packages/rest/test/smoke/docker-compose.smoke.yml up -d
RUN_SMOKE=1 pnpm --filter @dbrest-ts/rest test

See TESTING.md for the full testing guide and ARCHITECTURE.md for technical details.