/** * The data API: a query builder over PostgREST at `/v1/data` (`/rest/v1` in the old vocabulary). * * A builder is a description of one request, and awaiting it sends it. Nothing is sent by * `read()` or `eq()`; they only add to the URL, which is why a builder can be passed * around, extended and awaited later. Every result is `{ data, error, count, status }`, and * a refusal is an `error` rather than a throw, unless `throwOnError()` asks for a throw. */ import { type Transport } from './http.js'; /** * A row when the client was made without a `Database` type: `any`, so untyped code reads its * rows without a cast. It was `Record` in 0.1.0-0.2.0, and moving our own four apps * across found ~100 places that stopped compiling on that alone. With a `Database` type * (`snoutdata gen types typescript`), rows are exact, which is where the safety belongs. */ export type Row = any; export interface QueryError { message: string; details: string | null; hint: string | null; code: string; } interface Base { count: number | null; status: number; statusText: string; } export type QueryResult = (Base & { data: T; error: null; }) | (Base & { data: null; error: QueryError; }); export type CountMethod = 'exact' | 'planned' | 'estimated'; type Method = 'GET' | 'HEAD' | 'POST' | 'PATCH' | 'DELETE'; interface State { transport: Transport; method: Method; url: URL; schema: string | undefined; body: unknown; prefer: Map; accept: string | undefined; cardinality: 'many' | 'one' | 'maybe-one'; signal: AbortSignal | undefined; throws: boolean; } export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'cs' | 'cd' | 'ov' | 'sl' | 'sr' | 'nxl' | 'nxr' | 'adj' | 'match' | 'imatch' | 'fts' | 'plfts' | 'phfts' | 'wfts' | 'isdistinct'; /** * One request, being described. Filters and modifiers return `this` with a narrower result * type where they change the shape (`single()`, `maybeSingle()`), so the awaited value is * typed by what was asked for. */ /** * `W` is the row a `read()` after a write returns: the table's row for `add`, `change`, `put` * and `remove`, whose own result is `null` until `read()` asks for the rows. */ export declare class QueryBuilder implements PromiseLike> { protected readonly state: State; constructor(state: State); /** @deprecated Since 0.4.0: use `read()`, the same function. Removed in 0.5.0. */ select: QueryBuilder['read']; eq(column: string, value: unknown): this; neq(column: string, value: unknown): this; gt(column: string, value: unknown): this; gte(column: string, value: unknown): this; lt(column: string, value: unknown): this; lte(column: string, value: unknown): this; like(column: string, pattern: string): this; ilike(column: string, pattern: string): this; likeAnyOf(column: string, patterns: readonly string[]): this; ilikeAnyOf(column: string, patterns: readonly string[]): this; /** `null`, `true`, `false` or `unknown`, compared with IS. */ is(column: string, value: boolean | null | 'unknown'): this; isDistinct(column: string, value: unknown): this; in(column: string, values: readonly unknown[]): this; contains(column: string, value: unknown): this; containedBy(column: string, value: unknown): this; overlaps(column: string, value: unknown): this; rangeGt(column: string, range: string): this; rangeGte(column: string, range: string): this; rangeLt(column: string, range: string): this; rangeLte(column: string, range: string): this; rangeAdjacent(column: string, range: string): this; /** Full-text search. `type` picks the tsquery parser; plain `to_tsquery` when omitted. */ textSearch(column: string, query: string, options?: { config?: string; type?: 'plain' | 'phrase' | 'websearch'; }): this; /** Equality on every key of `query`. */ match(query: Record): this; not(column: string, operator: FilterOperator, value: unknown): this; /** * Any of the conditions, in PostgREST's own syntax: `'status.eq.open,priority.gt.3'`. * `referencedTable` applies it to an embedded resource instead of the top level. */ or(conditions: string, options?: { referencedTable?: string; }): this; /** Any operator by name, for the ones without a method of their own. */ filter(column: string, operator: FilterOperator | `not.${FilterOperator}`, value: unknown): this; private operand; private raw; /** * After `add`/`change`/`put`/`remove`, return the affected rows (and only these columns). * Without it a write returns no rows, which is cheaper. */ read(columns?: string): QueryBuilder; order(column: string, options?: { ascending?: boolean; nullsFirst?: boolean; referencedTable?: string; }): this; limit(count: number, options?: { referencedTable?: string; }): this; /** Rows `from` to `to`, both inclusive and zero-based, as `range(0, 9)` is the first ten. */ range(from: number, to: number, options?: { referencedTable?: string; }): this; /** Exactly one row, or an error. */ single(): QueryBuilder; /** One row or `null`; more than one is an error. */ maybeSingle(): QueryBuilder<(T extends readonly (infer E)[] ? E : T) | null>; /** The result as CSV text instead of rows. */ csv(): QueryBuilder; /** The query plan PostgREST would run, instead of the rows. */ explain(options?: { analyze?: boolean; verbose?: boolean; format?: 'text' | 'json'; }): QueryBuilder; abortSignal(signal: AbortSignal): this; /** Throw the error instead of returning it. */ throwOnError(): this; /** The request this builder would send, for logging and tests. Sends nothing. */ toUrl(): string; then, B = never>(onfulfilled?: ((value: QueryResult) => A | PromiseLike) | null, onrejected?: ((reason: unknown) => B | PromiseLike) | null): PromiseLike; private execute; private fail; } export interface WriteOptions { count?: CountMethod; } /** What `table(name)` returns: the choice of verb. */ export declare class TableBuilder { private readonly transport; private readonly url; private readonly schema; constructor(transport: Transport, url: string, schema: string | undefined); /** @deprecated Since 0.4.0: use `read()`, the same function. Removed in 0.5.0. */ select: TableBuilder['read']; /** @deprecated Since 0.4.0: use `add()`, the same function. Removed in 0.5.0. */ insert: TableBuilder['add']; /** @deprecated Since 0.4.0: use `put()`, the same function. Removed in 0.5.0. */ upsert: TableBuilder['put']; /** @deprecated Since 0.4.0: use `change()`, the same function. Removed in 0.5.0. */ update: TableBuilder['change']; /** @deprecated Since 0.4.0: use `remove()`, the same function. Removed in 0.5.0. */ delete: TableBuilder['remove']; private start; /** Read. `head: true` sends no rows back, which with `count` is how to count cheaply. */ read(columns?: string, options?: { count?: CountMethod; head?: boolean; }): QueryBuilder; /** Add one row or many. Returns nothing unless followed by `.read()`. */ add(values: Partial | readonly Partial[], options?: WriteOptions & { defaultToNull?: boolean; }): QueryBuilder; /** * Add, or change on a conflict (an upsert). `onConflict` names the unique columns to match on * (the primary key when omitted); `ignoreDuplicates` keeps the existing row instead. */ put(values: Partial | readonly Partial[], options?: WriteOptions & { onConflict?: string; ignoreDuplicates?: boolean; defaultToNull?: boolean; }): QueryBuilder; /** Change the rows the filters that follow select. Without a filter, PostgREST refuses. */ change(values: Partial, options?: WriteOptions): QueryBuilder; /** Remove the rows the filters that follow select. */ remove(options?: WriteOptions): QueryBuilder; } /** Calls a Postgres function. `get: true` sends it as a GET with the arguments in the URL. */ export declare function procedure(transport: Transport, restUrl: string, schema: string | undefined, fn: string, args?: Record, options?: { head?: boolean; get?: boolean; count?: CountMethod; }): QueryBuilder; /** @deprecated Since 0.4.0: `procedure`, the same function. Removed in 0.5.0. */ export declare const rpc: typeof procedure; export {};