@mitway/postgrest-js

TypeScript client for PostgREST. Provides a fluent query builder with full filter, sort, pagination, and RPC support.

Install

npm install @mitway/postgrest-js

Quick start

import { PostgrestClient } from '@mitway/postgrest-js'

const client = new PostgrestClient('https://your-postgrest-url.com')

Usage

Querying tables

// Select all columns
const { data, error } = await client
  .from('posts')
  .select('*')

// Select specific columns with filters
const { data, error } = await client
  .from('posts')
  .select('id, title, author:profiles(name)')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(10)

// Get a single row
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('id', 1)
  .single()

// Get a row that may not exist
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('slug', 'hello-world')
  .maybeSingle()

Inserting rows

// Insert a single row
const { data, error } = await client
  .from('posts')
  .insert({ title: 'Hello', content: 'World' })
  .select()
  .single()

// Insert multiple rows
const { data, error } = await client
  .from('posts')
  .insert([
    { title: 'First', content: 'Post' },
    { title: 'Second', content: 'Post' },
  ])
  .select()

// Upsert (insert or update on conflict)
const { data, error } = await client
  .from('posts')
  .upsert({ id: 1, title: 'Updated' })
  .select()
  .single()

Updating rows

const { data, error } = await client
  .from('posts')
  .update({ title: 'New title' })
  .eq('id', 1)
  .select()
  .single()

Deleting rows

const { error } = await client
  .from('posts')
  .delete()
  .eq('id', 1)

Calling stored functions (RPC)

const { data, error } = await client
  .rpc('get_user_stats', { user_id: 123 })

Filters

.eq('column', value)           // equals
.neq('column', value)          // not equals
.gt('column', value)           // greater than
.gte('column', value)          // greater than or equal
.lt('column', value)           // less than
.lte('column', value)          // less than or equal
.like('column', '%pattern%')   // LIKE (case-sensitive)
.ilike('column', '%pattern%')  // ILIKE (case-insensitive)
.is('column', null)            // IS NULL / IS true / IS false
.in('column', [1, 2, 3])      // IN array
.contains('column', value)     // @> contains (array/json/range)
.containedBy('column', value)  // <@ contained by
.overlaps('column', value)     // && overlaps
.not('column', 'eq', value)    // negate any filter
.match({ col1: 'a', col2: 'b' }) // multiple eq filters
.textSearch('column', 'query', { type: 'websearch' })

Result transforms

.order('column', { ascending: false, nullsFirst: false })
.limit(10)
.range(0, 9)                   // inclusive, 0-based
.single()                      // expect exactly 1 row → object
.maybeSingle()                 // expect 0 or 1 row → object | null
.csv()                         // return as CSV string
.explain()                     // return query plan

Count

// Get count alongside data
const { data, count, error } = await client
  .from('posts')
  .select('*', { count: 'exact' })

// Count only (no data)
const { count, error } = await client
  .from('posts')
  .select('*', { count: 'exact', head: true })

Error handling

const { data, error } = await client
  .from('posts')
  .select('*')

if (error) {
  console.error(error.message)  // human-readable message
  console.error(error.code)     // PostgREST error code (e.g. "PGRST116")
  console.error(error.details)  // details string
  console.error(error.hint)     // hint string
}

// Or throw on error instead of returning it
const { data } = await client
  .from('posts')
  .select('*')
  .throwOnError()

Custom fetch and headers

const client = new PostgrestClient('https://your-postgrest-url.com', {
  headers: { Authorization: 'Bearer your-jwt-token' },
  schema: 'public',
  fetch: customFetchFunction,
})

// Per-request custom headers
const { data, error } = await client
  .from('posts')
  .select('*')
  .setHeader('X-Custom', 'value')

Switching schemas

const { data, error } = await client
  .schema('private')
  .from('secret_table')
  .select('*')

Response format

All queries return the same envelope:

// Success
{ data: T, error: null, count: number | null, status: 200, statusText: 'OK' }

// Error
{ data: null, error: PostgrestError, count: null, status: number, statusText: string }

Exported classes

| Class | Purpose | |-------|---------| | PostgrestClient | Entry point -- constructs base URL, schema, headers | | PostgrestQueryBuilder | CRUD: select, insert, update, delete, upsert | | PostgrestFilterBuilder | 30+ filter operators | | PostgrestTransformBuilder | Result shaping: order, limit, range, single, csv | | PostgrestBuilder | Base class -- executes fetch, parses response | | PostgrestError | Error type with message, code, details, hint |

Exported types

import type {
  PostgrestResponse,
  PostgrestSingleResponse,
  PostgrestMaybeSingleResponse,
  PostgrestResponseSuccess,
  PostgrestResponseFailure,
  PostgrestClientOptions,
} from '@mitway/postgrest-js'

Protocol

This library implements the standard PostgREST HTTP API. It works with any PostgREST server (v9+), not just MITWAY-BaaS.

License

MIT. Originally vendored from @supabase/postgrest-js v1.21 (MIT).