or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-configuration.mderror-handling.mdfiltering-conditions.mdindex.mdquery-operations.mdresult-transformation.mdstored-procedures.md
tile.json

tessl/npm-supabase--postgrest-js

Isomorphic PostgREST client for PostgreSQL database interactions with fluent API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@supabase/postgrest-js@1.21.x

To install, run

npx @tessl/cli install tessl/npm-supabase--postgrest-js@1.21.0

index.mddocs/

Supabase PostgREST-JS

Supabase PostgREST-JS is an isomorphic PostgREST client that provides a fluent, type-safe API for PostgreSQL database interactions through PostgREST. It offers comprehensive CRUD operations with a chainable builder pattern, supporting both browser and Node.js environments with zero external dependencies beyond @supabase/node-fetch.

Package Information

  • Package Name: @supabase/postgrest-js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @supabase/postgrest-js

Core Imports

import { PostgrestClient, PostgrestError } from "@supabase/postgrest-js";

For CommonJS:

const { PostgrestClient, PostgrestError } = require("@supabase/postgrest-js");

Named imports for specific builders:

import { 
  PostgrestClient,
  PostgrestQueryBuilder,
  PostgrestFilterBuilder,
  PostgrestTransformBuilder,
  PostgrestBuilder,
  PostgrestError
} from "@supabase/postgrest-js";

Type imports:

import type {
  PostgrestResponse,
  PostgrestSingleResponse,
  PostgrestMaybeSingleResponse,
  PostgrestResponseSuccess,
  PostgrestResponseFailure,
  PostgrestClientOptions
} from "@supabase/postgrest-js";

Basic Usage

import { PostgrestClient } from "@supabase/postgrest-js";

// Create client
const client = new PostgrestClient("https://your-postgrest-endpoint.com");

// Simple select query
const { data, error } = await client
  .from("users")
  .select("*")
  .eq("active", true)
  .limit(10);

// Insert data
const { data: newUser, error: insertError } = await client
  .from("users")
  .insert({ name: "John Doe", email: "john@example.com" })
  .select()
  .single();

// Update with filters
const { data: updatedUsers, error: updateError } = await client
  .from("users")
  .update({ last_login: new Date().toISOString() })
  .eq("id", userId)
  .select();

// Call stored procedure
const { data: result, error: rpcError } = await client
  .rpc("calculate_user_stats", { user_id: 123 });

Architecture

PostgREST-JS is built around a fluent builder pattern with the following key components:

  • PostgrestClient: Main entry point for connecting to PostgREST endpoints
  • Query Builders: Chainable builders for constructing complex queries with type safety
  • Filter System: Comprehensive filtering capabilities including SQL operators, text search, and JSON operations
  • Transform Layer: Result formatting, ordering, pagination, and response transformation
  • Type System: Full TypeScript integration with schema-aware type inference
  • Error Handling: Structured error responses with detailed PostgreSQL error information

Capabilities

Client Configuration

Core client setup and configuration for connecting to PostgREST endpoints with custom headers, schema switching, and fetch customization.

class PostgrestClient<Database = any, ClientOptions = {}, SchemaName = 'public', Schema = any> {
  constructor(
    url: string,
    options?: {
      headers?: HeadersInit;
      schema?: SchemaName;
      fetch?: Fetch;
    }
  );
}

Client Configuration

Query Operations

Core CRUD operations including SELECT, INSERT, UPDATE, DELETE, and UPSERT with full type safety and flexible data manipulation.

class PostgrestQueryBuilder<ClientOptions, Schema, Relation, RelationName, Relationships> {
  select<Query extends string = '*'>(
    columns?: Query,
    options?: {
      head?: boolean;
      count?: 'exact' | 'planned' | 'estimated';
    }
  ): PostgrestFilterBuilder<...>;
  
  insert(
    values: Row | Row[],
    options?: {
      count?: 'exact' | 'planned' | 'estimated';
      defaultToNull?: boolean;
    }
  ): PostgrestFilterBuilder<...>;
  
  update(
    values: Partial<Row>,
    options?: {
      count?: 'exact' | 'planned' | 'estimated';
    }
  ): PostgrestFilterBuilder<...>;
}

Query Operations

Filtering and Conditions

Comprehensive filtering system with comparison operators, pattern matching, array operations, JSON queries, range operations, and full-text search.

class PostgrestFilterBuilder<ClientOptions, Schema, Row, Result, RelationName, Relationships, Method> {
  eq<ColumnName extends string>(column: ColumnName, value: any): this;
  neq<ColumnName extends string>(column: ColumnName, value: any): this;
  gt(column: string, value: unknown): this;
  like(column: string, pattern: string): this;
  in<ColumnName extends string>(column: ColumnName, values: readonly any[]): this;
  contains(column: string, value: string | readonly unknown[] | Record<string, unknown>): this;
  textSearch(column: string, query: string, options?: {
    config?: string;
    type?: 'plain' | 'phrase' | 'websearch';
  }): this;
}

Filtering and Conditions

Result Transformation

Result processing including column selection, ordering, pagination, response formatting (CSV, GeoJSON), and query optimization tools.

class PostgrestTransformBuilder<ClientOptions, Schema, Row, Result, RelationName, Relationships, Method> {
  select<Query extends string = '*'>(columns?: Query): PostgrestTransformBuilder<...>;
  order(column: string, options?: {
    ascending?: boolean;
    nullsFirst?: boolean;
    referencedTable?: string;
  }): this;
  limit(count: number, options?: {
    referencedTable?: string;
  }): this;
  range(from: number, to: number, options?: {
    referencedTable?: string;
  }): this;
  single(): PostgrestBuilder<ClientOptions, ResultOne>;
  maybeSingle(): PostgrestBuilder<ClientOptions, ResultOne | null>;
}

Result Transformation

Stored Procedures

Remote procedure call (RPC) functionality for executing PostgreSQL stored procedures and functions with parameter handling and result processing.

rpc<FnName extends string & keyof Schema['Functions']>(
  fn: FnName,
  args?: Fn['Args'],
  options?: {
    head?: boolean;
    get?: boolean;
    count?: 'exact' | 'planned' | 'estimated';
  }
): PostgrestFilterBuilder<...>;

Stored Procedures

Error Handling

Structured error handling with PostgreSQL error details, custom error types, and response validation.

class PostgrestError extends Error {
  name: 'PostgrestError';
  details: string;
  hint: string;
  code: string;
  
  constructor(context: {
    message: string;
    details: string;
    hint: string;
    code: string;
  });
}

interface PostgrestResponseFailure {
  error: PostgrestError;
  data: null;
  count: null;
  status: number;
  statusText: string;
}

Error Handling

Types

// Response Types
interface PostgrestResponseSuccess<T> {
  error: null;
  data: T;
  count: number | null;
  status: number;
  statusText: string;
}

interface PostgrestResponseFailure {
  error: PostgrestError;
  data: null;
  count: null;
  status: number;
  statusText: string;
}

type PostgrestSingleResponse<T> = PostgrestResponseSuccess<T> | PostgrestResponseFailure;
type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>;
type PostgrestResponse<T> = PostgrestSingleResponse<T[]>;

// Configuration Types
type PostgrestClientOptions = {
  PostgrestVersion?: string;
};

type Fetch = typeof fetch;

// Database Schema Types
interface GenericTable {
  Row: Record<string, unknown>;
  Insert: Record<string, unknown>;
  Update: Record<string, unknown>;
  Relationships: GenericRelationship[];
}

interface GenericView {
  Row: Record<string, unknown>;
  Relationships: GenericRelationship[];
}

interface GenericFunction {
  Args: Record<string, unknown>;
  Returns: unknown;
}

interface GenericSchema {
  Tables: Record<string, GenericTable>;
  Views: Record<string, GenericView>;
  Functions: Record<string, GenericFunction>;
}