0
# Supabase PostgREST-JS
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @supabase/postgrest-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @supabase/postgrest-js`
10

11
## Core Imports
12

13
```typescript
14
import { PostgrestClient, PostgrestError } from "@supabase/postgrest-js";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PostgrestClient, PostgrestError } = require("@supabase/postgrest-js");
21
```
22

23
Named imports for specific builders:
24

25
```typescript
26
import { 
27
  PostgrestClient,
28
  PostgrestQueryBuilder,
29
  PostgrestFilterBuilder,
30
  PostgrestTransformBuilder,
31
  PostgrestBuilder,
32
  PostgrestError
33
} from "@supabase/postgrest-js";
34
```
35

36
Type imports:
37

38
```typescript
39
import type {
40
  PostgrestResponse,
41
  PostgrestSingleResponse,
42
  PostgrestMaybeSingleResponse,
43
  PostgrestResponseSuccess,
44
  PostgrestResponseFailure,
45
  PostgrestClientOptions
46
} from "@supabase/postgrest-js";
47
```
48

49
## Basic Usage
50

51
```typescript
52
import { PostgrestClient } from "@supabase/postgrest-js";
53

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

57
// Simple select query
58
const { data, error } = await client
59
  .from("users")
60
  .select("*")
61
  .eq("active", true)
62
  .limit(10);
63

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

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

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

83
## Architecture
84

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

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

94
## Capabilities
95

96
### Client Configuration
97

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

100
```typescript { .api }
101
class PostgrestClient<Database = any, ClientOptions = {}, SchemaName = 'public', Schema = any> {
102
  constructor(
103
    url: string,
104
    options?: {
105
      headers?: HeadersInit;
106
      schema?: SchemaName;
107
      fetch?: Fetch;
108
    }
109
  );
110
}
111
```
112

113
[Client Configuration](./client-configuration.md)
114

115
### Query Operations
116

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

119
```typescript { .api }
120
class PostgrestQueryBuilder<ClientOptions, Schema, Relation, RelationName, Relationships> {
121
  select<Query extends string = '*'>(
122
    columns?: Query,
123
    options?: {
124
      head?: boolean;
125
      count?: 'exact' | 'planned' | 'estimated';
126
    }
127
  ): PostgrestFilterBuilder<...>;
128
  
129
  insert(
130
    values: Row | Row[],
131
    options?: {
132
      count?: 'exact' | 'planned' | 'estimated';
133
      defaultToNull?: boolean;
134
    }
135
  ): PostgrestFilterBuilder<...>;
136
  
137
  update(
138
    values: Partial<Row>,
139
    options?: {
140
      count?: 'exact' | 'planned' | 'estimated';
141
    }
142
  ): PostgrestFilterBuilder<...>;
143
}
144
```
145

146
[Query Operations](./query-operations.md)
147

148
### Filtering and Conditions
149

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

152
```typescript { .api }
153
class PostgrestFilterBuilder<ClientOptions, Schema, Row, Result, RelationName, Relationships, Method> {
154
  eq<ColumnName extends string>(column: ColumnName, value: any): this;
155
  neq<ColumnName extends string>(column: ColumnName, value: any): this;
156
  gt(column: string, value: unknown): this;
157
  like(column: string, pattern: string): this;
158
  in<ColumnName extends string>(column: ColumnName, values: readonly any[]): this;
159
  contains(column: string, value: string | readonly unknown[] | Record<string, unknown>): this;
160
  textSearch(column: string, query: string, options?: {
161
    config?: string;
162
    type?: 'plain' | 'phrase' | 'websearch';
163
  }): this;
164
}
165
```
166

167
[Filtering and Conditions](./filtering-conditions.md)
168

169
### Result Transformation
170

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

173
```typescript { .api }
174
class PostgrestTransformBuilder<ClientOptions, Schema, Row, Result, RelationName, Relationships, Method> {
175
  select<Query extends string = '*'>(columns?: Query): PostgrestTransformBuilder<...>;
176
  order(column: string, options?: {
177
    ascending?: boolean;
178
    nullsFirst?: boolean;
179
    referencedTable?: string;
180
  }): this;
181
  limit(count: number, options?: {
182
    referencedTable?: string;
183
  }): this;
184
  range(from: number, to: number, options?: {
185
    referencedTable?: string;
186
  }): this;
187
  single(): PostgrestBuilder<ClientOptions, ResultOne>;
188
  maybeSingle(): PostgrestBuilder<ClientOptions, ResultOne | null>;
189
}
190
```
191

192
[Result Transformation](./result-transformation.md)
193

194
### Stored Procedures
195

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

198
```typescript { .api }
199
rpc<FnName extends string & keyof Schema['Functions']>(
200
  fn: FnName,
201
  args?: Fn['Args'],
202
  options?: {
203
    head?: boolean;
204
    get?: boolean;
205
    count?: 'exact' | 'planned' | 'estimated';
206
  }
207
): PostgrestFilterBuilder<...>;
208
```
209

210
[Stored Procedures](./stored-procedures.md)
211

212
### Error Handling
213

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

216
```typescript { .api }
217
class PostgrestError extends Error {
218
  name: 'PostgrestError';
219
  details: string;
220
  hint: string;
221
  code: string;
222
  
223
  constructor(context: {
224
    message: string;
225
    details: string;
226
    hint: string;
227
    code: string;
228
  });
229
}
230

231
interface PostgrestResponseFailure {
232
  error: PostgrestError;
233
  data: null;
234
  count: null;
235
  status: number;
236
  statusText: string;
237
}
238
```
239

240
[Error Handling](./error-handling.md)
241

242
## Types
243

244
```typescript { .api }
245
// Response Types
246
interface PostgrestResponseSuccess<T> {
247
  error: null;
248
  data: T;
249
  count: number | null;
250
  status: number;
251
  statusText: string;
252
}
253

254
interface PostgrestResponseFailure {
255
  error: PostgrestError;
256
  data: null;
257
  count: null;
258
  status: number;
259
  statusText: string;
260
}
261

262
type PostgrestSingleResponse<T> = PostgrestResponseSuccess<T> | PostgrestResponseFailure;
263
type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>;
264
type PostgrestResponse<T> = PostgrestSingleResponse<T[]>;
265

266
// Configuration Types
267
type PostgrestClientOptions = {
268
  PostgrestVersion?: string;
269
};
270

271
type Fetch = typeof fetch;
272

273
// Database Schema Types
274
interface GenericTable {
275
  Row: Record<string, unknown>;
276
  Insert: Record<string, unknown>;
277
  Update: Record<string, unknown>;
278
  Relationships: GenericRelationship[];
279
}
280

281
interface GenericView {
282
  Row: Record<string, unknown>;
283
  Relationships: GenericRelationship[];
284
}
285

286
interface GenericFunction {
287
  Args: Record<string, unknown>;
288
  Returns: unknown;
289
}
290

291
interface GenericSchema {
292
  Tables: Record<string, GenericTable>;
293
  Views: Record<string, GenericView>;
294
  Functions: Record<string, GenericFunction>;
295
}
296
```