@supabase/postgrest-js - npm Package Compare versions

Comparing version 1.0.0-rc.5 to 1.0.0-rc.6

dist/main/PostgrestBuilder.js

@@ -49,3 +49,3 @@ "use strict";
         // https://postgrest.org/en/stable/api.html#switching-schemas
-        if (typeof this.schema === 'undefined') {
+        if (this.schema === undefined) {
             // skip
@@ -71,28 +71,27 @@ }
         }).then((res) => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
-            let error = undefined;
-            let data = undefined;
-            let count = undefined;
+            var _a, _b, _c;
+            let error = null;
+            let data = null;
+            let count = null;
             let status = res.status;
             let statusText = res.statusText;
             if (res.ok) {
-                const isReturnMinimal = (_a = this.headers['Prefer']) === null || _a === void 0 ? void 0 : _a.split(',').includes('return=minimal');
-                if (this.method !== 'HEAD' && !isReturnMinimal) {
-                    const text = yield res.text();
-                    if (!text) {
-                        // discard `text`
+                if (this.method !== 'HEAD') {
+                    const body = yield res.text();
+                    if (body === '') {
+                        // Prefer: return=minimal
                     }
                     else if (this.headers['Accept'] === 'text/csv') {
-                        data = text;
+                        data = body;
                     }
                     else if (this.headers['Accept'] &&
-                        this.headers['Accept'].indexOf('application/vnd.pgrst.plan+text') !== -1) {
-                        data = text;
+                        this.headers['Accept'].includes('application/vnd.pgrst.plan+text')) {
+                        data = body;
                     }
                     else {
-                        data = JSON.parse(text);
+                        data = JSON.parse(body);
                     }
                 }
-                const countHeader = (_b = this.headers['Prefer']) === null || _b === void 0 ? void 0 : _b.match(/count=(exact|planned|estimated)/);
-                const contentRange = (_c = res.headers.get('content-range')) === null || _c === void 0 ? void 0 : _c.split('/');
+                const countHeader = (_a = this.headers['Prefer']) === null || _a === void 0 ? void 0 : _a.match(/count=(exact|planned|estimated)/);
+                const contentRange = (_b = res.headers.get('content-range')) === null || _b === void 0 ? void 0 : _b.split('/');
                 if (countHeader && contentRange && contentRange.length > 1) {
@@ -107,3 +106,3 @@ count = parseInt(contentRange[1]);
                 }
-                catch (_e) {
+                catch (_d) {
                     error = {
@@ -113,4 +112,4 @@ message: body,
                 }
-                if (error && this.allowEmpty && ((_d = error === null || error === void 0 ? void 0 : error.details) === null || _d === void 0 ? void 0 : _d.includes('Results contain 0 rows'))) {
-                    error = undefined;
+                if (error && this.allowEmpty && ((_c = error === null || error === void 0 ? void 0 : error.details) === null || _c === void 0 ? void 0 : _c.includes('Results contain 0 rows'))) {
+                    error = null;
                     status = 200;
@@ -140,6 +139,6 @@ statusText = 'OK';
                 },
-                data: undefined,
-                count: undefined,
-                status: 400,
-                statusText: 'Bad Request',
+                data: null,
+                count: null,
+                status: 0,
+                statusText: '',
             }));
@@ -146,0 +145,0 @@ }

dist/main/PostgrestClient.d.ts

 import PostgrestQueryBuilder from './PostgrestQueryBuilder';
 import PostgrestFilterBuilder from './PostgrestFilterBuilder';
 import { Fetch, GenericSchema } from './types';
+/**
+ * PostgREST client.
+ *
+ * @typeParam Database - Types for the schema from the [type
+ * generator](https://supabase.com/docs/reference/javascript/next/typescript-support)
+ *
+ * @typeParam SchemaName - Postgres schema to switch to. Must be a string
+ * literal, the same one passed to the constructor. If the schema is not
+ * `"public"`, this must be supplied manually.
+ */
 export default class PostgrestClient<Database = any, SchemaName extends string & keyof Database = 'public' extends keyof Database ? 'public' : string & keyof Database, Schema extends GenericSchema = Database[SchemaName] extends GenericSchema ? Database[SchemaName] : any> {
@@ -12,5 +22,7 @@ url: string;
      *
-     * @param url  URL of the PostgREST endpoint.
-     * @param headers  Custom headers.
-     * @param schema  Postgres schema to switch to.
+     * @param url - URL of the PostgREST endpoint
+     * @param options - Named parameters
+     * @param options.headers - Custom headers
+     * @param options.schema - Postgres schema to switch to
+     * @param options.fetch - Custom fetch
      */
@@ -25,3 +37,3 @@ constructor(url: string, { headers, schema, fetch, }?: {
      *
-     * @param relation  The table or view name to query.
+     * @param relation - The table or view name to query
      */
@@ -34,10 +46,22 @@ from<TableName extends string & keyof Schema['Tables'], Table extends Schema['Tables'][TableName]>(relation: TableName): PostgrestQueryBuilder<Table>;
      *
-     * @param fn  The function name to call.
-     * @param args  The parameters to pass to the function call.
-     * @param options  Named parameters.
+     * @param fn - The function name to call
+     * @param args - The arguments to pass to the function call
+     * @param options - Named parameters
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     * @param options.count - Count algorithm to use to count rows returned by the
+     * function. Only applicable for [set-returning
+     * functions](https://www.postgresql.org/docs/current/functions-srf.html).
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     rpc<FunctionName extends string & keyof Schema['Functions'], Function_ extends Schema['Functions'][FunctionName]>(fn: FunctionName, args?: Function_['Args'], { head, count, }?: {
-        /** When set to true, no data will be returned. */
         head?: boolean;
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
@@ -44,0 +68,0 @@ }): PostgrestFilterBuilder<Function_['Returns'] extends any[] ? Function_['Returns'][number] extends Record<string, unknown> ? Function_['Returns'][number] : never : never, Function_['Returns']>;

dist/main/PostgrestClient.js

@@ -9,2 +9,12 @@ "use strict";
 const constants_1 = require("./constants");
+/**
+ * PostgREST client.
+ *
+ * @typeParam Database - Types for the schema from the [type
+ * generator](https://supabase.com/docs/reference/javascript/next/typescript-support)
+ *
+ * @typeParam SchemaName - Postgres schema to switch to. Must be a string
+ * literal, the same one passed to the constructor. If the schema is not
+ * `"public"`, this must be supplied manually.
+ */
 class PostgrestClient {
@@ -15,5 +25,7 @@ // TODO: Add back shouldThrowOnError once we figure out the typings
      *
-     * @param url  URL of the PostgREST endpoint.
-     * @param headers  Custom headers.
-     * @param schema  Postgres schema to switch to.
+     * @param url - URL of the PostgREST endpoint
+     * @param options - Named parameters
+     * @param options.headers - Custom headers
+     * @param options.schema - Postgres schema to switch to
+     * @param options.fetch - Custom fetch
      */
@@ -37,5 +49,19 @@ constructor(url, { headers = {}, schema, fetch, } = {}) {
      *
-     * @param fn  The function name to call.
-     * @param args  The parameters to pass to the function call.
-     * @param options  Named parameters.
+     * @param fn - The function name to call
+     * @param args - The arguments to pass to the function call
+     * @param options - Named parameters
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     * @param options.count - Count algorithm to use to count rows returned by the
+     * function. Only applicable for [set-returning
+     * functions](https://www.postgresql.org/docs/current/functions-srf.html).
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -42,0 +68,0 @@ rpc(fn, args = {}, { head = false, count, } = {}) {

dist/main/PostgrestFilterBuilder.d.ts

 import PostgrestTransformBuilder from './PostgrestTransformBuilder';
-/**
- * Filters
- */
 declare type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'cs' | 'cd' | 'sl' | 'sr' | 'nxl' | 'nxr' | 'adj' | 'ov' | 'fts' | 'plfts' | 'phfts' | 'wfts';
 export default class PostgrestFilterBuilder<Row extends Record<string, unknown>, Result> extends PostgrestTransformBuilder<Row, Result> {
     /**
-     * Finds all rows which doesn't satisfy the filter.
+     * Match only rows where `column` is equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param operator  The operator to filter with.
-     * @param value  The value to filter with.
-     */
-    not<ColumnName extends string & keyof Row>(column: ColumnName, operator: FilterOperator, value: Row[ColumnName]): this;
-    not(column: string, operator: string, value: unknown): this;
-    /**
-     * Finds all rows satisfying at least one of the filters.
+     * To check if the value of `column` is NULL, you should use `.is()` instead.
      *
-     * @param filters  The filters to use, separated by commas.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
-    or(filters: string, { foreignTable }?: {
-        foreignTable?: string;
-    }): this;
-    /**
-     * Finds all rows whose value on the stated `column` exactly matches the
-     * specified `value`.
-     *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
-     */
     eq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     eq(column: string, value: unknown): this;
     /**
-     * Finds all rows whose value on the stated `column` doesn't match the
-     * specified `value`.
+     * Match only rows where `column` is not equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -44,7 +23,6 @@ neq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is greater than the
-     * specified `value`.
+     * Match only rows where `column` is greater than `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -54,7 +32,6 @@ gt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is greater than or
-     * equal to the specified `value`.
+     * Match only rows where `column` is greater than or equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -64,7 +41,6 @@ gte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is less than the
-     * specified `value`.
+     * Match only rows where `column` is less than `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -74,7 +50,6 @@ lt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is less than or equal
-     * to the specified `value`.
+     * Match only rows where `column` is less than or equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -84,7 +59,6 @@ lte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value in the stated `column` matches the supplied
-     * `pattern` (case sensitive).
+     * Match only rows where `column` matches `pattern` case-sensitively.
      *
-     * @param column  The column to filter on.
-     * @param pattern  The pattern to filter with.
+     * @param column - The column to filter on
+     * @param pattern - The pattern to match with
      */
@@ -94,7 +68,6 @@ like<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this;
     /**
-     * Finds all rows whose value in the stated `column` matches the supplied
-     * `pattern` (case insensitive).
+     * Match only rows where `column` matches `pattern` case-insensitively.
      *
-     * @param column  The column to filter on.
-     * @param pattern  The pattern to filter with.
+     * @param column - The column to filter on
+     * @param pattern - The pattern to match with
      */
@@ -104,7 +77,12 @@ ilike<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this;
     /**
-     * A check for exact equality (null, true, false), finds all rows whose
-     * value on the stated `column` exactly match the specified `value`.
+     * Match only rows where `column` IS `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * For non-boolean columns, this is only relevant for checking if the value of
+     * `column` is NULL by setting `value` to `null`.
+     *
+     * For boolean columns, you can also set `value` to `true` or `false` and it
+     * will behave the same way as `.eq()`.
+     *
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -114,7 +92,6 @@ is<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName] & (boolean | null)): this;
     /**
-     * Finds all rows whose value on the stated `column` is found on the
-     * specified `values`.
+     * Match only rows where `column` is included in the `values` array.
      *
-     * @param column  The column to filter on.
-     * @param values  The values to filter with.
+     * @param column - The column to filter on
+     * @param values - The values array to filter with
      */
@@ -124,7 +101,7 @@ in<ColumnName extends string & keyof Row>(column: ColumnName, values: Row[ColumnName][]): this;
     /**
-     * Finds all rows whose json, array, or range value on the stated `column`
-     * contains the values specified in `value`.
+     * Only relevant for jsonb, array, and range columns. Match only rows where
+     * `column` contains every element appearing in `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The jsonb, array, or range column to filter on
+     * @param value - The jsonb, array, or range value to filter with
      */
@@ -134,7 +111,7 @@ contains<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][] | Record<string, unknown>): this;
     /**
-     * Finds all rows whose json, array, or range value on the stated `column` is
-     * contained by the specified `value`.
+     * Only relevant for jsonb, array, and range columns. Match only rows where
+     * every element appearing in `column` is contained by `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The jsonb, array, or range column to filter on
+     * @param value - The jsonb, array, or range value to filter with
      */
@@ -144,25 +121,17 @@ containedBy<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][] | Record<string, unknown>): this;
     /**
-     * Finds all rows whose range value on the stated `column` is strictly to the
-     * left of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is greater than any element in `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
-    rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
-    rangeLt(column: string, range: string): this;
-    /**
-     * Finds all rows whose range value on the stated `column` is strictly to
-     * the right of the specified `range`.
-     *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
-     */
     rangeGt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     rangeGt(column: string, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` does not extend
-     * to the left of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is either contained in `range` or greater than any element in
+     * `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
@@ -172,16 +141,27 @@ rangeGte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` does not extend
-     * to the right of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is less than any element in `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
+    rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
+    rangeLt(column: string, range: string): this;
+    /**
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is either contained in `range` or less than any element in
+     * `range`.
+     *
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
+     */
     rangeLte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     rangeLte(column: string, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` is adjacent to
-     * the specified `range`.
+     * Only relevant for range columns. Match only rows where `column` is
+     * mutually exclusive to `range` and there can be no element between the two
+     * ranges.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
@@ -191,7 +171,7 @@ rangeAdjacent<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     /**
-     * Finds all rows whose array or range value on the stated `column` overlaps
-     * (has a value in common) with the specified `value`.
+     * Only relevant for array and range columns. Match only rows where
+     * `column` and `value` have an element in common.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The array or range column to filter on
+     * @param value - The array or range value to filter with
      */
@@ -201,9 +181,10 @@ overlaps<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][]): this;
     /**
-     * Finds all rows whose text or tsvector value on the stated `column` matches
-     * the tsquery in `query`.
+     * Only relevant for text and tsvector columns. Match only rows where
+     * `column` matches the query string in `query`.
      *
-     * @param column  The column to filter on.
-     * @param query  The Postgres tsquery string to filter with.
-     * @param config  The text search configuration to use.
-     * @param type  The type of tsquery conversion to use on `query`.
+     * @param column - The text or tsvector column to filter on
+     * @param query - The query text to match with
+     * @param options - Named parameters
+     * @param options.config - The text search configuration to use
+     * @param options.type - Change how the `query` text is interpreted
      */
@@ -219,20 +200,58 @@ textSearch<ColumnName extends string & keyof Row>(column: ColumnName, query: string, options?: {
     /**
-     * Finds all rows whose `column` satisfies the filter.
+     * Match only rows where each column in `query` keys is equal to its
+     * associated value. Shorthand for multiple `.eq()`s.
      *
-     * @param column  The column to filter on.
-     * @param operator  The operator to filter with.
-     * @param value  The value to filter with.
+     * @param query - The object to filter with, with column names as keys mapped
+     * to their filter values
      */
-    filter<ColumnName extends string & keyof Row>(column: ColumnName, operator: `${'' | 'not.'}${FilterOperator}`, value: unknown): this;
-    filter(column: string, operator: string, value: unknown): this;
+    match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this;
+    match(query: Record<string, unknown>): this;
     /**
-     * Finds all rows whose columns match the specified `query` object.
+     * Match only rows which doesn't satisfy the filter.
      *
-     * @param query  The object to filter with, with column names as keys mapped
-     *               to their filter values.
+     * Unlike most filters, `opearator` and `value` are used as-is and need to
+     * follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure they are properly sanitized.
+     *
+     * @param column - The column to filter on
+     * @param operator - The operator to be negated to filter with, following
+     * PostgREST syntax
+     * @param value - The value to filter with, following PostgREST syntax
      */
-    match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this;
-    match(query: Record<string, unknown>): this;
+    not<ColumnName extends string & keyof Row>(column: ColumnName, operator: FilterOperator, value: Row[ColumnName]): this;
+    not(column: string, operator: string, value: unknown): this;
+    /**
+     * Match only rows which satisfy at least one of the filters.
+     *
+     * Unlike most filters, `filters` is used as-is and needs to follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure it's properly sanitized.
+     *
+     * It's currently not possible to do an `.or()` filter across multiple tables.
+     *
+     * @param filters - The filters to use, following PostgREST syntax
+     * @param foreignTable - Set this to filter on foreign tables instead of the
+     * current table
+     */
+    or(filters: string, { foreignTable }?: {
+        foreignTable?: string;
+    }): this;
+    /**
+     * Match only rows which satisfy the filter. This is an escape hatch - you
+     * should use the specific filter methods wherever possible.
+     *
+     * Unlike most filters, `opearator` and `value` are used as-is and need to
+     * follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure they are properly sanitized.
+     *
+     * @param column - The column to filter on
+     * @param operator - The operator to filter with, following PostgREST syntax
+     * @param value - The value to filter with, following PostgREST syntax
+     */
+    filter<ColumnName extends string & keyof Row>(column: ColumnName, operator: `${'' | 'not.'}${FilterOperator}`, value: unknown): this;
+    filter(column: string, operator: string, value: unknown): this;
 }
 export {};
 //# sourceMappingURL=PostgrestFilterBuilder.d.ts.map

dist/main/PostgrestFilterBuilder.js

@@ -8,17 +8,2 @@ "use strict";
 class PostgrestFilterBuilder extends PostgrestTransformBuilder_1.default {
-    not(column, operator, value) {
-        this.url.searchParams.append(column, `not.${operator}.${value}`);
-        return this;
-    }
-    /**
-     * Finds all rows satisfying at least one of the filters.
-     *
-     * @param filters  The filters to use, separated by commas.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
-     */
-    or(filters, { foreignTable } = {}) {
-        const key = foreignTable ? `${foreignTable}.or` : 'or';
-        this.url.searchParams.append(key, `(${filters})`);
-        return this;
-    }
     eq(column, value) {
@@ -105,6 +90,2 @@ this.url.searchParams.append(column, `eq.${value}`);
     }
-    rangeLt(column, range) {
-        this.url.searchParams.append(column, `sl.${range}`);
-        return this;
-    }
     rangeGt(column, range) {
@@ -118,2 +99,6 @@ this.url.searchParams.append(column, `sr.${range}`);
     }
+    rangeLt(column, range) {
+        this.url.searchParams.append(column, `sl.${range}`);
+        return this;
+    }
     rangeLte(column, range) {
@@ -153,6 +138,2 @@ this.url.searchParams.append(column, `nxr.${range}`);
     }
-    filter(column, operator, value) {
-        this.url.searchParams.append(column, `${operator}.${value}`);
-        return this;
-    }
     match(query) {
@@ -164,4 +145,30 @@ Object.entries(query).forEach(([column, value]) => {
     }
+    not(column, operator, value) {
+        this.url.searchParams.append(column, `not.${operator}.${value}`);
+        return this;
+    }
+    /**
+     * Match only rows which satisfy at least one of the filters.
+     *
+     * Unlike most filters, `filters` is used as-is and needs to follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure it's properly sanitized.
+     *
+     * It's currently not possible to do an `.or()` filter across multiple tables.
+     *
+     * @param filters - The filters to use, following PostgREST syntax
+     * @param foreignTable - Set this to filter on foreign tables instead of the
+     * current table
+     */
+    or(filters, { foreignTable } = {}) {
+        const key = foreignTable ? `${foreignTable}.or` : 'or';
+        this.url.searchParams.append(key, `(${filters})`);
+        return this;
+    }
+    filter(column, operator, value) {
+        this.url.searchParams.append(column, `${operator}.${value}`);
+        return this;
+    }
 }
 exports.default = PostgrestFilterBuilder;
 //# sourceMappingURL=PostgrestFilterBuilder.js.map

dist/main/PostgrestQueryBuilder.d.ts

@@ -16,16 +16,47 @@ import PostgrestFilterBuilder from './PostgrestFilterBuilder';
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT query on the table or view.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * @param columns - The columns to retrieve, separated by commas
+     *
+     * @param options - Named parameters
+     *
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     *
+     * @param options.count - Count algorithm to use to count rows in the table or view.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     select<Query extends string = '*', Result = GetResult<Relation['Row'], Query extends '*' ? '*' : Query>>(columns?: Query, { head, count, }?: {
-        /** When set to true, select will void data. */
         head?: boolean;
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], Result>;
     /**
-     * Performs an INSERT into the table.
+     * Perform an INSERT into the table or view.
      *
-     * @param values    The values to insert.
+     * By default, inserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to insert. Pass an object to insert a single row
+     * or an array to insert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count inserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -35,24 +66,64 @@ insert<Row extends Relation extends {
     } ? Relation['Insert'] : never>(values: Row | Row[], { count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs an UPSERT into the table.
+     * Perform an UPSERT on the table or view. Depending on the column(s) passed
+     * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+     * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+     * exist, or if it does exist, perform an alternative action depending on
+     * `ignoreDuplicates`.
      *
-     * @param values  The values to insert.
+     * By default, upserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to upsert with. Pass an object to upsert a
+     * single row or an array to upsert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+     * duplicate rows are determined. Two rows are duplicates if all the
+     * `onConflict` columns are equal.
+     *
+     * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+     * `false`, duplicate rows are merged with existing rows.
+     *
+     * @param options.count - Count algorithm to use to count upserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     upsert<Row extends Relation extends {
         Insert: unknown;
-    } ? Relation['Insert'] : never>(values: Row | Row[], { onConflict, count, ignoreDuplicates, }?: {
-        /** By specifying the `on_conflict` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint. */
+    } ? Relation['Insert'] : never>(values: Row | Row[], { onConflict, ignoreDuplicates, count, }?: {
         onConflict?: string;
-        /** Count algorithm to use to count rows in a table. */
+        ignoreDuplicates?: boolean;
         count?: 'exact' | 'planned' | 'estimated';
-        /** Specifies if duplicate rows should be ignored and not inserted. */
-        ignoreDuplicates?: boolean;
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs an UPDATE on the table.
+     * Perform an UPDATE on the table or view.
      *
-     * @param values  The values to update.
+     * By default, updated rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param values - The values to update with
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count updated rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -62,10 +133,24 @@ update<Row extends Relation extends {
     } ? Relation['Update'] : never>(values: Row, { count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs a DELETE on the table.
+     * Perform a DELETE on the table or view.
+     *
+     * By default, deleted rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count deleted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     delete({ count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
@@ -72,0 +157,0 @@ }): PostgrestFilterBuilder<Relation['Row'], undefined>;

dist/main/PostgrestQueryBuilder.js

@@ -15,5 +15,21 @@ "use strict";
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT query on the table or view.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * @param columns - The columns to retrieve, separated by commas
+     *
+     * @param options - Named parameters
+     *
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     *
+     * @param options.count - Count algorithm to use to count rows in the table or view.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -50,5 +66,22 @@ select(columns, { head = false, count, } = {}) {
     /**
-     * Performs an INSERT into the table.
+     * Perform an INSERT into the table or view.
      *
-     * @param values    The values to insert.
+     * By default, inserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to insert. Pass an object to insert a single row
+     * or an array to insert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count inserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -84,7 +117,35 @@ insert(values, { count, } = {}) {
     /**
-     * Performs an UPSERT into the table.
+     * Perform an UPSERT on the table or view. Depending on the column(s) passed
+     * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+     * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+     * exist, or if it does exist, perform an alternative action depending on
+     * `ignoreDuplicates`.
      *
-     * @param values  The values to insert.
+     * By default, upserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to upsert with. Pass an object to upsert a
+     * single row or an array to upsert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+     * duplicate rows are determined. Two rows are duplicates if all the
+     * `onConflict` columns are equal.
+     *
+     * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+     * `false`, duplicate rows are merged with existing rows.
+     *
+     * @param options.count - Count algorithm to use to count upserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
-    upsert(values, { onConflict, count, ignoreDuplicates = false, } = {}) {
+    upsert(values, { onConflict, ignoreDuplicates = false, count, } = {}) {
         const method = 'POST';
@@ -113,5 +174,21 @@ const prefersHeaders = [`resolution=${ignoreDuplicates ? 'ignore' : 'merge'}-duplicates`];
     /**
-     * Performs an UPDATE on the table.
+     * Perform an UPDATE on the table or view.
      *
-     * @param values  The values to update.
+     * By default, updated rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param values - The values to update with
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count updated rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -140,3 +217,19 @@ update(values, { count, } = {}) {
     /**
-     * Performs a DELETE on the table.
+     * Perform a DELETE on the table or view.
+     *
+     * By default, deleted rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count deleted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -143,0 +236,0 @@ delete({ count, } = {}) {

dist/main/PostgrestTransformBuilder.d.ts

 import PostgrestBuilder from './PostgrestBuilder';
 import { GetResult } from './select-query-parser';
 import { PostgrestMaybeSingleResponse, PostgrestResponse, PostgrestSingleResponse } from './types';
-/**
- * Post-filters (transforms)
- */
 export default class PostgrestTransformBuilder<Row extends Record<string, unknown>, Result> extends PostgrestBuilder<Result> {
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT on the query result.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * By default, `.insert()`, `.update()`, `.upsert()`, and `.delete()` do not
+     * return modified rows. By calling this method, modified rows are returned in
+     * `data`.
+     *
+     * @param columns - The columns to retrieve, separated by commas
      */
     select<Query extends string = '*', NewResult = GetResult<Row, Query extends '*' ? '*' : Query>>(columns?: Query): PostgrestTransformBuilder<Row, NewResult>;
     /**
-     * Orders the result with the specified `column`.
+     * Order the query result by `column`.
      *
-     * @param column  The column to order on.
-     * @param ascending  If `true`, the result will be in ascending order.
-     * @param nullsFirst  If `true`, `null`s appear first.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+     * You can call this method multiple times to order by multiple columns.
+     *
+     * You can order foreign tables, but it doesn't affect the ordering of the
+     * current table.
+     *
+     * @param column - The column to order by
+     * @param options - Named parameters
+     * @param options.ascending - If `true`, the result will be in ascending order
+     * @param options.nullsFirst - If `true`, `null`s appear first. If `false`,
+     * `null`s appear last.
+     * @param options.foreignTable - Set this to order a foreign table by foreign
+     * columns
      */
@@ -33,6 +42,8 @@ order<ColumnName extends string & keyof Row>(column: ColumnName, options?: {
     /**
-     * Limits the result with the specified `count`.
+     * Limit the query result by `count`.
      *
-     * @param count  The maximum no. of rows to limit to.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param count - The maximum number of rows to return
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -43,7 +54,9 @@ limit(count: number, { foreignTable }?: {
     /**
-     * Limits the result to rows within the specified range, inclusive.
+     * Limit the query result by `from` and `to` inclusively.
      *
-     * @param from  The starting index from which to limit the result, inclusive.
-     * @param to  The last index to which to limit the result, inclusive.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param from - The starting index from which to limit the result
+     * @param to - The last index to which to limit the result
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -54,33 +67,49 @@ range(from: number, to: number, { foreignTable }?: {
     /**
-     * Sets the AbortSignal for the fetch request.
+     * Set the AbortSignal for the fetch request.
+     *
+     * @param signal - The AbortSignal to use for the fetch request
      */
     abortSignal(signal: AbortSignal): this;
     /**
-     * Retrieves only one row from the result. Result must be one row (e.g. using
-     * `limit`), otherwise this will result in an error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be one row (e.g. using `.limit(1)`), otherwise this
+     * returns an error.
      */
     single(): PromiseLike<PostgrestSingleResponse<Result>>;
     /**
-     * Retrieves at most one row from the result. Result must be at most one row
-     * (e.g. using `eq` on a UNIQUE column), otherwise this will result in an
-     * error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
+     * this returns an error.
      */
     maybeSingle(): PromiseLike<PostgrestMaybeSingleResponse<Result>>;
     /**
-     * Set the response type to CSV.
+     * Return `data` as a string in CSV format.
      */
     csv(): PromiseLike<PostgrestSingleResponse<string>>;
     /**
-     * Set the response type to GeoJSON.
+     * Return `data` as an object in [GeoJSON](https://geojson.org) format.
      */
     geojson(): PromiseLike<PostgrestSingleResponse<Record<string, unknown>>>;
     /**
-     * Obtains the EXPLAIN plan for this request.
+     * Return `data` as the EXPLAIN plan for the query.
      *
-     * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
-     * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
-     * @param settings  If `true`, include information on configuration parameters that affect query planning.
-     * @param buffers  If `true`, include information on buffer usage.
-     * @param wal     If `true`, include information on WAL record generation
-     * @param format  The format of the output, can be 'text'(default) or `json`
+     * @param options - Named parameters
+     *
+     * @param options.analyze - If `true`, the query will be executed and the
+     * actual run time will be returned
+     *
+     * @param options.verbose - If `true`, the query identifier will be returned
+     * and `data` will include the output columns of the query
+     *
+     * @param options.settings - If `true`, include information on configuration
+     * parameters that affect query planning
+     *
+     * @param options.buffers - If `true`, include information on buffer usage
+     *
+     * @param options.wal - If `true`, include information on WAL record generation
+     *
+     * @param options.format - The format of the output, can be `"text"` (default)
+     * or `"json"`
      */
@@ -95,4 +124,9 @@ explain({ analyze, verbose, settings, buffers, wal, format, }?: {
     }): PromiseLike<PostgrestResponse<Record<string, unknown>>> | PromiseLike<PostgrestSingleResponse<string>>;
+    /**
+     * Rollback the query.
+     *
+     * `data` will still be returned, but the query is not committed.
+     */
     rollback(): this;
 }
 //# sourceMappingURL=PostgrestTransformBuilder.d.ts.map

dist/main/PostgrestTransformBuilder.js

@@ -7,10 +7,11 @@ "use strict";
 const PostgrestBuilder_1 = __importDefault(require("./PostgrestBuilder"));
-/**
- * Post-filters (transforms)
- */
 class PostgrestTransformBuilder extends PostgrestBuilder_1.default {
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT on the query result.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * By default, `.insert()`, `.update()`, `.upsert()`, and `.delete()` do not
+     * return modified rows. By calling this method, modified rows are returned in
+     * `data`.
+     *
+     * @param columns - The columns to retrieve, separated by commas
      */
@@ -46,6 +47,8 @@ select(columns) {
     /**
-     * Limits the result with the specified `count`.
+     * Limit the query result by `count`.
      *
-     * @param count  The maximum no. of rows to limit to.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param count - The maximum number of rows to return
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -58,7 +61,9 @@ limit(count, { foreignTable } = {}) {
     /**
-     * Limits the result to rows within the specified range, inclusive.
+     * Limit the query result by `from` and `to` inclusively.
      *
-     * @param from  The starting index from which to limit the result, inclusive.
-     * @param to  The last index to which to limit the result, inclusive.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param from - The starting index from which to limit the result
+     * @param to - The last index to which to limit the result
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -74,3 +79,5 @@ range(from, to, { foreignTable } = {}) {
     /**
-     * Sets the AbortSignal for the fetch request.
+     * Set the AbortSignal for the fetch request.
+     *
+     * @param signal - The AbortSignal to use for the fetch request
      */
@@ -82,4 +89,6 @@ abortSignal(signal) {
     /**
-     * Retrieves only one row from the result. Result must be one row (e.g. using
-     * `limit`), otherwise this will result in an error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be one row (e.g. using `.limit(1)`), otherwise this
+     * returns an error.
      */
@@ -91,5 +100,6 @@ single() {
     /**
-     * Retrieves at most one row from the result. Result must be at most one row
-     * (e.g. using `eq` on a UNIQUE column), otherwise this will result in an
-     * error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
+     * this returns an error.
      */
@@ -102,3 +112,3 @@ maybeSingle() {
     /**
-     * Set the response type to CSV.
+     * Return `data` as a string in CSV format.
      */
@@ -110,3 +120,3 @@ csv() {
     /**
-     * Set the response type to GeoJSON.
+     * Return `data` as an object in [GeoJSON](https://geojson.org) format.
      */
@@ -118,10 +128,21 @@ geojson() {
     /**
-     * Obtains the EXPLAIN plan for this request.
+     * Return `data` as the EXPLAIN plan for the query.
      *
-     * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
-     * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
-     * @param settings  If `true`, include information on configuration parameters that affect query planning.
-     * @param buffers  If `true`, include information on buffer usage.
-     * @param wal     If `true`, include information on WAL record generation
-     * @param format  The format of the output, can be 'text'(default) or `json`
+     * @param options - Named parameters
+     *
+     * @param options.analyze - If `true`, the query will be executed and the
+     * actual run time will be returned
+     *
+     * @param options.verbose - If `true`, the query identifier will be returned
+     * and `data` will include the output columns of the query
+     *
+     * @param options.settings - If `true`, include information on configuration
+     * parameters that affect query planning
+     *
+     * @param options.buffers - If `true`, include information on buffer usage
+     *
+     * @param options.wal - If `true`, include information on WAL record generation
+     *
+     * @param options.format - The format of the output, can be `"text"` (default)
+     * or `"json"`
      */
@@ -146,2 +167,7 @@ explain({ analyze = false, verbose = false, settings = false, buffers = false, wal = false, format = 'text', } = {}) {
     }
+    /**
+     * Rollback the query.
+     *
+     * `data` will still be returned, but the query is not committed.
+     */
     rollback() {
@@ -148,0 +174,0 @@ var _a;

dist/main/types.d.ts

@@ -23,19 +23,19 @@ export declare type Fetch = typeof fetch;
 interface PostgrestResponseSuccess<T> extends PostgrestResponseBase {
-    error: undefined;
+    error: null;
     data: T[];
-    count: number | undefined;
+    count: number | null;
 }
 interface PostgrestResponseFailure extends PostgrestResponseBase {
     error: PostgrestError;
-    data: undefined;
-    count: undefined;
+    data: null;
+    count: null;
 }
 export declare type PostgrestResponse<T> = PostgrestResponseSuccess<T> | PostgrestResponseFailure;
 interface PostgrestSingleResponseSuccess<T> extends PostgrestResponseBase {
-    error: undefined;
+    error: null;
     data: T;
-    count: number | undefined;
+    count: number | null;
 }
 export declare type PostgrestSingleResponse<T> = PostgrestSingleResponseSuccess<T> | PostgrestResponseFailure;
-export declare type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | undefined>;
+export declare type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>;
 export declare type GenericTable = {
@@ -42,0 +42,0 @@ Row: Record<string, unknown>;

dist/main/version.d.ts

@@ -1,2 +0,2 @@
-export declare const version = "1.0.0-rc.5";
+export declare const version = "1.0.0-rc.6";
 //# sourceMappingURL=version.d.ts.map

dist/main/version.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
-exports.version = '1.0.0-rc.5';
+exports.version = '1.0.0-rc.6';
 //# sourceMappingURL=version.js.map

dist/module/PostgrestBuilder.js

@@ -44,3 +44,3 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
         // https://postgrest.org/en/stable/api.html#switching-schemas
-        if (typeof this.schema === 'undefined') {
+        if (this.schema === undefined) {
             // skip
@@ -66,28 +66,27 @@ }
         }).then((res) => __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
-            let error = undefined;
-            let data = undefined;
-            let count = undefined;
+            var _a, _b, _c;
+            let error = null;
+            let data = null;
+            let count = null;
             let status = res.status;
             let statusText = res.statusText;
             if (res.ok) {
-                const isReturnMinimal = (_a = this.headers['Prefer']) === null || _a === void 0 ? void 0 : _a.split(',').includes('return=minimal');
-                if (this.method !== 'HEAD' && !isReturnMinimal) {
-                    const text = yield res.text();
-                    if (!text) {
-                        // discard `text`
+                if (this.method !== 'HEAD') {
+                    const body = yield res.text();
+                    if (body === '') {
+                        // Prefer: return=minimal
                     }
                     else if (this.headers['Accept'] === 'text/csv') {
-                        data = text;
+                        data = body;
                     }
                     else if (this.headers['Accept'] &&
-                        this.headers['Accept'].indexOf('application/vnd.pgrst.plan+text') !== -1) {
-                        data = text;
+                        this.headers['Accept'].includes('application/vnd.pgrst.plan+text')) {
+                        data = body;
                     }
                     else {
-                        data = JSON.parse(text);
+                        data = JSON.parse(body);
                     }
                 }
-                const countHeader = (_b = this.headers['Prefer']) === null || _b === void 0 ? void 0 : _b.match(/count=(exact|planned|estimated)/);
-                const contentRange = (_c = res.headers.get('content-range')) === null || _c === void 0 ? void 0 : _c.split('/');
+                const countHeader = (_a = this.headers['Prefer']) === null || _a === void 0 ? void 0 : _a.match(/count=(exact|planned|estimated)/);
+                const contentRange = (_b = res.headers.get('content-range')) === null || _b === void 0 ? void 0 : _b.split('/');
                 if (countHeader && contentRange && contentRange.length > 1) {
@@ -102,3 +101,3 @@ count = parseInt(contentRange[1]);
                 }
-                catch (_e) {
+                catch (_d) {
                     error = {
@@ -108,4 +107,4 @@ message: body,
                 }
-                if (error && this.allowEmpty && ((_d = error === null || error === void 0 ? void 0 : error.details) === null || _d === void 0 ? void 0 : _d.includes('Results contain 0 rows'))) {
-                    error = undefined;
+                if (error && this.allowEmpty && ((_c = error === null || error === void 0 ? void 0 : error.details) === null || _c === void 0 ? void 0 : _c.includes('Results contain 0 rows'))) {
+                    error = null;
                     status = 200;
@@ -135,6 +134,6 @@ statusText = 'OK';
                 },
-                data: undefined,
-                count: undefined,
-                status: 400,
-                statusText: 'Bad Request',
+                data: null,
+                count: null,
+                status: 0,
+                statusText: '',
             }));
@@ -141,0 +140,0 @@ }

dist/module/PostgrestClient.d.ts

 import PostgrestQueryBuilder from './PostgrestQueryBuilder';
 import PostgrestFilterBuilder from './PostgrestFilterBuilder';
 import { Fetch, GenericSchema } from './types';
+/**
+ * PostgREST client.
+ *
+ * @typeParam Database - Types for the schema from the [type
+ * generator](https://supabase.com/docs/reference/javascript/next/typescript-support)
+ *
+ * @typeParam SchemaName - Postgres schema to switch to. Must be a string
+ * literal, the same one passed to the constructor. If the schema is not
+ * `"public"`, this must be supplied manually.
+ */
 export default class PostgrestClient<Database = any, SchemaName extends string & keyof Database = 'public' extends keyof Database ? 'public' : string & keyof Database, Schema extends GenericSchema = Database[SchemaName] extends GenericSchema ? Database[SchemaName] : any> {
@@ -12,5 +22,7 @@ url: string;
      *
-     * @param url  URL of the PostgREST endpoint.
-     * @param headers  Custom headers.
-     * @param schema  Postgres schema to switch to.
+     * @param url - URL of the PostgREST endpoint
+     * @param options - Named parameters
+     * @param options.headers - Custom headers
+     * @param options.schema - Postgres schema to switch to
+     * @param options.fetch - Custom fetch
      */
@@ -25,3 +37,3 @@ constructor(url: string, { headers, schema, fetch, }?: {
      *
-     * @param relation  The table or view name to query.
+     * @param relation - The table or view name to query
      */
@@ -34,10 +46,22 @@ from<TableName extends string & keyof Schema['Tables'], Table extends Schema['Tables'][TableName]>(relation: TableName): PostgrestQueryBuilder<Table>;
      *
-     * @param fn  The function name to call.
-     * @param args  The parameters to pass to the function call.
-     * @param options  Named parameters.
+     * @param fn - The function name to call
+     * @param args - The arguments to pass to the function call
+     * @param options - Named parameters
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     * @param options.count - Count algorithm to use to count rows returned by the
+     * function. Only applicable for [set-returning
+     * functions](https://www.postgresql.org/docs/current/functions-srf.html).
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     rpc<FunctionName extends string & keyof Schema['Functions'], Function_ extends Schema['Functions'][FunctionName]>(fn: FunctionName, args?: Function_['Args'], { head, count, }?: {
-        /** When set to true, no data will be returned. */
         head?: boolean;
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
@@ -44,0 +68,0 @@ }): PostgrestFilterBuilder<Function_['Returns'] extends any[] ? Function_['Returns'][number] extends Record<string, unknown> ? Function_['Returns'][number] : never : never, Function_['Returns']>;

dist/module/PostgrestClient.js

 import PostgrestQueryBuilder from './PostgrestQueryBuilder';
 import PostgrestFilterBuilder from './PostgrestFilterBuilder';
 import { DEFAULT_HEADERS } from './constants';
+/**
+ * PostgREST client.
+ *
+ * @typeParam Database - Types for the schema from the [type
+ * generator](https://supabase.com/docs/reference/javascript/next/typescript-support)
+ *
+ * @typeParam SchemaName - Postgres schema to switch to. Must be a string
+ * literal, the same one passed to the constructor. If the schema is not
+ * `"public"`, this must be supplied manually.
+ */
 export default class PostgrestClient {
@@ -9,5 +19,7 @@ // TODO: Add back shouldThrowOnError once we figure out the typings
      *
-     * @param url  URL of the PostgREST endpoint.
-     * @param headers  Custom headers.
-     * @param schema  Postgres schema to switch to.
+     * @param url - URL of the PostgREST endpoint
+     * @param options - Named parameters
+     * @param options.headers - Custom headers
+     * @param options.schema - Postgres schema to switch to
+     * @param options.fetch - Custom fetch
      */
@@ -31,5 +43,19 @@ constructor(url, { headers = {}, schema, fetch, } = {}) {
      *
-     * @param fn  The function name to call.
-     * @param args  The parameters to pass to the function call.
-     * @param options  Named parameters.
+     * @param fn - The function name to call
+     * @param args - The arguments to pass to the function call
+     * @param options - Named parameters
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     * @param options.count - Count algorithm to use to count rows returned by the
+     * function. Only applicable for [set-returning
+     * functions](https://www.postgresql.org/docs/current/functions-srf.html).
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -36,0 +62,0 @@ rpc(fn, args = {}, { head = false, count, } = {}) {

dist/module/PostgrestFilterBuilder.d.ts

 import PostgrestTransformBuilder from './PostgrestTransformBuilder';
-/**
- * Filters
- */
 declare type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'cs' | 'cd' | 'sl' | 'sr' | 'nxl' | 'nxr' | 'adj' | 'ov' | 'fts' | 'plfts' | 'phfts' | 'wfts';
 export default class PostgrestFilterBuilder<Row extends Record<string, unknown>, Result> extends PostgrestTransformBuilder<Row, Result> {
     /**
-     * Finds all rows which doesn't satisfy the filter.
+     * Match only rows where `column` is equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param operator  The operator to filter with.
-     * @param value  The value to filter with.
-     */
-    not<ColumnName extends string & keyof Row>(column: ColumnName, operator: FilterOperator, value: Row[ColumnName]): this;
-    not(column: string, operator: string, value: unknown): this;
-    /**
-     * Finds all rows satisfying at least one of the filters.
+     * To check if the value of `column` is NULL, you should use `.is()` instead.
      *
-     * @param filters  The filters to use, separated by commas.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
-    or(filters: string, { foreignTable }?: {
-        foreignTable?: string;
-    }): this;
-    /**
-     * Finds all rows whose value on the stated `column` exactly matches the
-     * specified `value`.
-     *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
-     */
     eq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     eq(column: string, value: unknown): this;
     /**
-     * Finds all rows whose value on the stated `column` doesn't match the
-     * specified `value`.
+     * Match only rows where `column` is not equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -44,7 +23,6 @@ neq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is greater than the
-     * specified `value`.
+     * Match only rows where `column` is greater than `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -54,7 +32,6 @@ gt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is greater than or
-     * equal to the specified `value`.
+     * Match only rows where `column` is greater than or equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -64,7 +41,6 @@ gte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is less than the
-     * specified `value`.
+     * Match only rows where `column` is less than `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -74,7 +50,6 @@ lt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value on the stated `column` is less than or equal
-     * to the specified `value`.
+     * Match only rows where `column` is less than or equal to `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -84,7 +59,6 @@ lte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
     /**
-     * Finds all rows whose value in the stated `column` matches the supplied
-     * `pattern` (case sensitive).
+     * Match only rows where `column` matches `pattern` case-sensitively.
      *
-     * @param column  The column to filter on.
-     * @param pattern  The pattern to filter with.
+     * @param column - The column to filter on
+     * @param pattern - The pattern to match with
      */
@@ -94,7 +68,6 @@ like<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this;
     /**
-     * Finds all rows whose value in the stated `column` matches the supplied
-     * `pattern` (case insensitive).
+     * Match only rows where `column` matches `pattern` case-insensitively.
      *
-     * @param column  The column to filter on.
-     * @param pattern  The pattern to filter with.
+     * @param column - The column to filter on
+     * @param pattern - The pattern to match with
      */
@@ -104,7 +77,12 @@ ilike<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this;
     /**
-     * A check for exact equality (null, true, false), finds all rows whose
-     * value on the stated `column` exactly match the specified `value`.
+     * Match only rows where `column` IS `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * For non-boolean columns, this is only relevant for checking if the value of
+     * `column` is NULL by setting `value` to `null`.
+     *
+     * For boolean columns, you can also set `value` to `true` or `false` and it
+     * will behave the same way as `.eq()`.
+     *
+     * @param column - The column to filter on
+     * @param value - The value to filter with
      */
@@ -114,7 +92,6 @@ is<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName] & (boolean | null)): this;
     /**
-     * Finds all rows whose value on the stated `column` is found on the
-     * specified `values`.
+     * Match only rows where `column` is included in the `values` array.
      *
-     * @param column  The column to filter on.
-     * @param values  The values to filter with.
+     * @param column - The column to filter on
+     * @param values - The values array to filter with
      */
@@ -124,7 +101,7 @@ in<ColumnName extends string & keyof Row>(column: ColumnName, values: Row[ColumnName][]): this;
     /**
-     * Finds all rows whose json, array, or range value on the stated `column`
-     * contains the values specified in `value`.
+     * Only relevant for jsonb, array, and range columns. Match only rows where
+     * `column` contains every element appearing in `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The jsonb, array, or range column to filter on
+     * @param value - The jsonb, array, or range value to filter with
      */
@@ -134,7 +111,7 @@ contains<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][] | Record<string, unknown>): this;
     /**
-     * Finds all rows whose json, array, or range value on the stated `column` is
-     * contained by the specified `value`.
+     * Only relevant for jsonb, array, and range columns. Match only rows where
+     * every element appearing in `column` is contained by `value`.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The jsonb, array, or range column to filter on
+     * @param value - The jsonb, array, or range value to filter with
      */
@@ -144,25 +121,17 @@ containedBy<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][] | Record<string, unknown>): this;
     /**
-     * Finds all rows whose range value on the stated `column` is strictly to the
-     * left of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is greater than any element in `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
-    rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
-    rangeLt(column: string, range: string): this;
-    /**
-     * Finds all rows whose range value on the stated `column` is strictly to
-     * the right of the specified `range`.
-     *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
-     */
     rangeGt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     rangeGt(column: string, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` does not extend
-     * to the left of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is either contained in `range` or greater than any element in
+     * `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
@@ -172,16 +141,27 @@ rangeGte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` does not extend
-     * to the right of the specified `range`.
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is less than any element in `range`.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
+    rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
+    rangeLt(column: string, range: string): this;
+    /**
+     * Only relevant for range columns. Match only rows where every element in
+     * `column` is either contained in `range` or less than any element in
+     * `range`.
+     *
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
+     */
     rangeLte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     rangeLte(column: string, range: string): this;
     /**
-     * Finds all rows whose range value on the stated `column` is adjacent to
-     * the specified `range`.
+     * Only relevant for range columns. Match only rows where `column` is
+     * mutually exclusive to `range` and there can be no element between the two
+     * ranges.
      *
-     * @param column  The column to filter on.
-     * @param range  The range to filter with.
+     * @param column - The range column to filter on
+     * @param range - The range to filter with
      */
@@ -191,7 +171,7 @@ rangeAdjacent<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this;
     /**
-     * Finds all rows whose array or range value on the stated `column` overlaps
-     * (has a value in common) with the specified `value`.
+     * Only relevant for array and range columns. Match only rows where
+     * `column` and `value` have an element in common.
      *
-     * @param column  The column to filter on.
-     * @param value  The value to filter with.
+     * @param column - The array or range column to filter on
+     * @param value - The array or range value to filter with
      */
@@ -201,9 +181,10 @@ overlaps<ColumnName extends string & keyof Row>(column: ColumnName, value: string | Row[ColumnName][]): this;
     /**
-     * Finds all rows whose text or tsvector value on the stated `column` matches
-     * the tsquery in `query`.
+     * Only relevant for text and tsvector columns. Match only rows where
+     * `column` matches the query string in `query`.
      *
-     * @param column  The column to filter on.
-     * @param query  The Postgres tsquery string to filter with.
-     * @param config  The text search configuration to use.
-     * @param type  The type of tsquery conversion to use on `query`.
+     * @param column - The text or tsvector column to filter on
+     * @param query - The query text to match with
+     * @param options - Named parameters
+     * @param options.config - The text search configuration to use
+     * @param options.type - Change how the `query` text is interpreted
      */
@@ -219,20 +200,58 @@ textSearch<ColumnName extends string & keyof Row>(column: ColumnName, query: string, options?: {
     /**
-     * Finds all rows whose `column` satisfies the filter.
+     * Match only rows where each column in `query` keys is equal to its
+     * associated value. Shorthand for multiple `.eq()`s.
      *
-     * @param column  The column to filter on.
-     * @param operator  The operator to filter with.
-     * @param value  The value to filter with.
+     * @param query - The object to filter with, with column names as keys mapped
+     * to their filter values
      */
-    filter<ColumnName extends string & keyof Row>(column: ColumnName, operator: `${'' | 'not.'}${FilterOperator}`, value: unknown): this;
-    filter(column: string, operator: string, value: unknown): this;
+    match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this;
+    match(query: Record<string, unknown>): this;
     /**
-     * Finds all rows whose columns match the specified `query` object.
+     * Match only rows which doesn't satisfy the filter.
      *
-     * @param query  The object to filter with, with column names as keys mapped
-     *               to their filter values.
+     * Unlike most filters, `opearator` and `value` are used as-is and need to
+     * follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure they are properly sanitized.
+     *
+     * @param column - The column to filter on
+     * @param operator - The operator to be negated to filter with, following
+     * PostgREST syntax
+     * @param value - The value to filter with, following PostgREST syntax
      */
-    match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this;
-    match(query: Record<string, unknown>): this;
+    not<ColumnName extends string & keyof Row>(column: ColumnName, operator: FilterOperator, value: Row[ColumnName]): this;
+    not(column: string, operator: string, value: unknown): this;
+    /**
+     * Match only rows which satisfy at least one of the filters.
+     *
+     * Unlike most filters, `filters` is used as-is and needs to follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure it's properly sanitized.
+     *
+     * It's currently not possible to do an `.or()` filter across multiple tables.
+     *
+     * @param filters - The filters to use, following PostgREST syntax
+     * @param foreignTable - Set this to filter on foreign tables instead of the
+     * current table
+     */
+    or(filters: string, { foreignTable }?: {
+        foreignTable?: string;
+    }): this;
+    /**
+     * Match only rows which satisfy the filter. This is an escape hatch - you
+     * should use the specific filter methods wherever possible.
+     *
+     * Unlike most filters, `opearator` and `value` are used as-is and need to
+     * follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure they are properly sanitized.
+     *
+     * @param column - The column to filter on
+     * @param operator - The operator to filter with, following PostgREST syntax
+     * @param value - The value to filter with, following PostgREST syntax
+     */
+    filter<ColumnName extends string & keyof Row>(column: ColumnName, operator: `${'' | 'not.'}${FilterOperator}`, value: unknown): this;
+    filter(column: string, operator: string, value: unknown): this;
 }
 export {};
 //# sourceMappingURL=PostgrestFilterBuilder.d.ts.map

dist/module/PostgrestFilterBuilder.js

 import PostgrestTransformBuilder from './PostgrestTransformBuilder';
 export default class PostgrestFilterBuilder extends PostgrestTransformBuilder {
-    not(column, operator, value) {
-        this.url.searchParams.append(column, `not.${operator}.${value}`);
-        return this;
-    }
-    /**
-     * Finds all rows satisfying at least one of the filters.
-     *
-     * @param filters  The filters to use, separated by commas.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
-     */
-    or(filters, { foreignTable } = {}) {
-        const key = foreignTable ? `${foreignTable}.or` : 'or';
-        this.url.searchParams.append(key, `(${filters})`);
-        return this;
-    }
     eq(column, value) {
@@ -99,6 +84,2 @@ this.url.searchParams.append(column, `eq.${value}`);
     }
-    rangeLt(column, range) {
-        this.url.searchParams.append(column, `sl.${range}`);
-        return this;
-    }
     rangeGt(column, range) {
@@ -112,2 +93,6 @@ this.url.searchParams.append(column, `sr.${range}`);
     }
+    rangeLt(column, range) {
+        this.url.searchParams.append(column, `sl.${range}`);
+        return this;
+    }
     rangeLte(column, range) {
@@ -147,6 +132,2 @@ this.url.searchParams.append(column, `nxr.${range}`);
     }
-    filter(column, operator, value) {
-        this.url.searchParams.append(column, `${operator}.${value}`);
-        return this;
-    }
     match(query) {
@@ -158,3 +139,29 @@ Object.entries(query).forEach(([column, value]) => {
     }
+    not(column, operator, value) {
+        this.url.searchParams.append(column, `not.${operator}.${value}`);
+        return this;
+    }
+    /**
+     * Match only rows which satisfy at least one of the filters.
+     *
+     * Unlike most filters, `filters` is used as-is and needs to follow [PostgREST
+     * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+     * to make sure it's properly sanitized.
+     *
+     * It's currently not possible to do an `.or()` filter across multiple tables.
+     *
+     * @param filters - The filters to use, following PostgREST syntax
+     * @param foreignTable - Set this to filter on foreign tables instead of the
+     * current table
+     */
+    or(filters, { foreignTable } = {}) {
+        const key = foreignTable ? `${foreignTable}.or` : 'or';
+        this.url.searchParams.append(key, `(${filters})`);
+        return this;
+    }
+    filter(column, operator, value) {
+        this.url.searchParams.append(column, `${operator}.${value}`);
+        return this;
+    }
 }
 //# sourceMappingURL=PostgrestFilterBuilder.js.map

dist/module/PostgrestQueryBuilder.d.ts

@@ -16,16 +16,47 @@ import PostgrestFilterBuilder from './PostgrestFilterBuilder';
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT query on the table or view.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * @param columns - The columns to retrieve, separated by commas
+     *
+     * @param options - Named parameters
+     *
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     *
+     * @param options.count - Count algorithm to use to count rows in the table or view.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     select<Query extends string = '*', Result = GetResult<Relation['Row'], Query extends '*' ? '*' : Query>>(columns?: Query, { head, count, }?: {
-        /** When set to true, select will void data. */
         head?: boolean;
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], Result>;
     /**
-     * Performs an INSERT into the table.
+     * Perform an INSERT into the table or view.
      *
-     * @param values    The values to insert.
+     * By default, inserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to insert. Pass an object to insert a single row
+     * or an array to insert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count inserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -35,24 +66,64 @@ insert<Row extends Relation extends {
     } ? Relation['Insert'] : never>(values: Row | Row[], { count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs an UPSERT into the table.
+     * Perform an UPSERT on the table or view. Depending on the column(s) passed
+     * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+     * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+     * exist, or if it does exist, perform an alternative action depending on
+     * `ignoreDuplicates`.
      *
-     * @param values  The values to insert.
+     * By default, upserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to upsert with. Pass an object to upsert a
+     * single row or an array to upsert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+     * duplicate rows are determined. Two rows are duplicates if all the
+     * `onConflict` columns are equal.
+     *
+     * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+     * `false`, duplicate rows are merged with existing rows.
+     *
+     * @param options.count - Count algorithm to use to count upserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     upsert<Row extends Relation extends {
         Insert: unknown;
-    } ? Relation['Insert'] : never>(values: Row | Row[], { onConflict, count, ignoreDuplicates, }?: {
-        /** By specifying the `on_conflict` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint. */
+    } ? Relation['Insert'] : never>(values: Row | Row[], { onConflict, ignoreDuplicates, count, }?: {
         onConflict?: string;
-        /** Count algorithm to use to count rows in a table. */
+        ignoreDuplicates?: boolean;
         count?: 'exact' | 'planned' | 'estimated';
-        /** Specifies if duplicate rows should be ignored and not inserted. */
-        ignoreDuplicates?: boolean;
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs an UPDATE on the table.
+     * Perform an UPDATE on the table or view.
      *
-     * @param values  The values to update.
+     * By default, updated rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param values - The values to update with
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count updated rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -62,10 +133,24 @@ update<Row extends Relation extends {
     } ? Relation['Update'] : never>(values: Row, { count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
     }): PostgrestFilterBuilder<Relation['Row'], undefined>;
     /**
-     * Performs a DELETE on the table.
+     * Perform a DELETE on the table or view.
+     *
+     * By default, deleted rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count deleted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
     delete({ count, }?: {
-        /** Count algorithm to use to count rows in a table. */
         count?: 'exact' | 'planned' | 'estimated';
@@ -72,0 +157,0 @@ }): PostgrestFilterBuilder<Relation['Row'], undefined>;

dist/module/PostgrestQueryBuilder.js

@@ -10,5 +10,21 @@ import PostgrestFilterBuilder from './PostgrestFilterBuilder';
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT query on the table or view.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * @param columns - The columns to retrieve, separated by commas
+     *
+     * @param options - Named parameters
+     *
+     * @param options.head - When set to `true`, `data` will not be returned.
+     * Useful if you only need the count.
+     *
+     * @param options.count - Count algorithm to use to count rows in the table or view.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -45,5 +61,22 @@ select(columns, { head = false, count, } = {}) {
     /**
-     * Performs an INSERT into the table.
+     * Perform an INSERT into the table or view.
      *
-     * @param values    The values to insert.
+     * By default, inserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to insert. Pass an object to insert a single row
+     * or an array to insert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count inserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -79,7 +112,35 @@ insert(values, { count, } = {}) {
     /**
-     * Performs an UPSERT into the table.
+     * Perform an UPSERT on the table or view. Depending on the column(s) passed
+     * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+     * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+     * exist, or if it does exist, perform an alternative action depending on
+     * `ignoreDuplicates`.
      *
-     * @param values  The values to insert.
+     * By default, upserted rows are not returned. To return it, chain the call
+     * with `.select()`.
+     *
+     * @param values - The values to upsert with. Pass an object to upsert a
+     * single row or an array to upsert multiple rows.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+     * duplicate rows are determined. Two rows are duplicates if all the
+     * `onConflict` columns are equal.
+     *
+     * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+     * `false`, duplicate rows are merged with existing rows.
+     *
+     * @param options.count - Count algorithm to use to count upserted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
-    upsert(values, { onConflict, count, ignoreDuplicates = false, } = {}) {
+    upsert(values, { onConflict, ignoreDuplicates = false, count, } = {}) {
         const method = 'POST';
@@ -108,5 +169,21 @@ const prefersHeaders = [`resolution=${ignoreDuplicates ? 'ignore' : 'merge'}-duplicates`];
     /**
-     * Performs an UPDATE on the table.
+     * Perform an UPDATE on the table or view.
      *
-     * @param values  The values to update.
+     * By default, updated rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param values - The values to update with
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count updated rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -135,3 +212,19 @@ update(values, { count, } = {}) {
     /**
-     * Performs a DELETE on the table.
+     * Perform a DELETE on the table or view.
+     *
+     * By default, deleted rows are not returned. To return it, chain the call
+     * with `.select()` after filters.
+     *
+     * @param options - Named parameters
+     *
+     * @param options.count - Count algorithm to use to count deleted rows.
+     *
+     * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+     * hood.
+     *
+     * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+     * statistics under the hood.
+     *
+     * `"estimated"`: Uses exact count for low numbers and planned count for high
+     * numbers.
      */
@@ -138,0 +231,0 @@ delete({ count, } = {}) {

dist/module/PostgrestTransformBuilder.d.ts

 import PostgrestBuilder from './PostgrestBuilder';
 import { GetResult } from './select-query-parser';
 import { PostgrestMaybeSingleResponse, PostgrestResponse, PostgrestSingleResponse } from './types';
-/**
- * Post-filters (transforms)
- */
 export default class PostgrestTransformBuilder<Row extends Record<string, unknown>, Result> extends PostgrestBuilder<Result> {
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT on the query result.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * By default, `.insert()`, `.update()`, `.upsert()`, and `.delete()` do not
+     * return modified rows. By calling this method, modified rows are returned in
+     * `data`.
+     *
+     * @param columns - The columns to retrieve, separated by commas
      */
     select<Query extends string = '*', NewResult = GetResult<Row, Query extends '*' ? '*' : Query>>(columns?: Query): PostgrestTransformBuilder<Row, NewResult>;
     /**
-     * Orders the result with the specified `column`.
+     * Order the query result by `column`.
      *
-     * @param column  The column to order on.
-     * @param ascending  If `true`, the result will be in ascending order.
-     * @param nullsFirst  If `true`, `null`s appear first.
-     * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+     * You can call this method multiple times to order by multiple columns.
+     *
+     * You can order foreign tables, but it doesn't affect the ordering of the
+     * current table.
+     *
+     * @param column - The column to order by
+     * @param options - Named parameters
+     * @param options.ascending - If `true`, the result will be in ascending order
+     * @param options.nullsFirst - If `true`, `null`s appear first. If `false`,
+     * `null`s appear last.
+     * @param options.foreignTable - Set this to order a foreign table by foreign
+     * columns
      */
@@ -33,6 +42,8 @@ order<ColumnName extends string & keyof Row>(column: ColumnName, options?: {
     /**
-     * Limits the result with the specified `count`.
+     * Limit the query result by `count`.
      *
-     * @param count  The maximum no. of rows to limit to.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param count - The maximum number of rows to return
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -43,7 +54,9 @@ limit(count: number, { foreignTable }?: {
     /**
-     * Limits the result to rows within the specified range, inclusive.
+     * Limit the query result by `from` and `to` inclusively.
      *
-     * @param from  The starting index from which to limit the result, inclusive.
-     * @param to  The last index to which to limit the result, inclusive.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param from - The starting index from which to limit the result
+     * @param to - The last index to which to limit the result
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -54,33 +67,49 @@ range(from: number, to: number, { foreignTable }?: {
     /**
-     * Sets the AbortSignal for the fetch request.
+     * Set the AbortSignal for the fetch request.
+     *
+     * @param signal - The AbortSignal to use for the fetch request
      */
     abortSignal(signal: AbortSignal): this;
     /**
-     * Retrieves only one row from the result. Result must be one row (e.g. using
-     * `limit`), otherwise this will result in an error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be one row (e.g. using `.limit(1)`), otherwise this
+     * returns an error.
      */
     single(): PromiseLike<PostgrestSingleResponse<Result>>;
     /**
-     * Retrieves at most one row from the result. Result must be at most one row
-     * (e.g. using `eq` on a UNIQUE column), otherwise this will result in an
-     * error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
+     * this returns an error.
      */
     maybeSingle(): PromiseLike<PostgrestMaybeSingleResponse<Result>>;
     /**
-     * Set the response type to CSV.
+     * Return `data` as a string in CSV format.
      */
     csv(): PromiseLike<PostgrestSingleResponse<string>>;
     /**
-     * Set the response type to GeoJSON.
+     * Return `data` as an object in [GeoJSON](https://geojson.org) format.
      */
     geojson(): PromiseLike<PostgrestSingleResponse<Record<string, unknown>>>;
     /**
-     * Obtains the EXPLAIN plan for this request.
+     * Return `data` as the EXPLAIN plan for the query.
      *
-     * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
-     * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
-     * @param settings  If `true`, include information on configuration parameters that affect query planning.
-     * @param buffers  If `true`, include information on buffer usage.
-     * @param wal     If `true`, include information on WAL record generation
-     * @param format  The format of the output, can be 'text'(default) or `json`
+     * @param options - Named parameters
+     *
+     * @param options.analyze - If `true`, the query will be executed and the
+     * actual run time will be returned
+     *
+     * @param options.verbose - If `true`, the query identifier will be returned
+     * and `data` will include the output columns of the query
+     *
+     * @param options.settings - If `true`, include information on configuration
+     * parameters that affect query planning
+     *
+     * @param options.buffers - If `true`, include information on buffer usage
+     *
+     * @param options.wal - If `true`, include information on WAL record generation
+     *
+     * @param options.format - The format of the output, can be `"text"` (default)
+     * or `"json"`
      */
@@ -95,4 +124,9 @@ explain({ analyze, verbose, settings, buffers, wal, format, }?: {
     }): PromiseLike<PostgrestResponse<Record<string, unknown>>> | PromiseLike<PostgrestSingleResponse<string>>;
+    /**
+     * Rollback the query.
+     *
+     * `data` will still be returned, but the query is not committed.
+     */
     rollback(): this;
 }
 //# sourceMappingURL=PostgrestTransformBuilder.d.ts.map

dist/module/PostgrestTransformBuilder.js

 import PostgrestBuilder from './PostgrestBuilder';
-/**
- * Post-filters (transforms)
- */
 export default class PostgrestTransformBuilder extends PostgrestBuilder {
     /**
-     * Performs vertical filtering with SELECT.
+     * Perform a SELECT on the query result.
      *
-     * @param columns  The columns to retrieve, separated by commas.
+     * By default, `.insert()`, `.update()`, `.upsert()`, and `.delete()` do not
+     * return modified rows. By calling this method, modified rows are returned in
+     * `data`.
+     *
+     * @param columns - The columns to retrieve, separated by commas
      */
@@ -40,6 +41,8 @@ select(columns) {
     /**
-     * Limits the result with the specified `count`.
+     * Limit the query result by `count`.
      *
-     * @param count  The maximum no. of rows to limit to.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param count - The maximum number of rows to return
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -52,7 +55,9 @@ limit(count, { foreignTable } = {}) {
     /**
-     * Limits the result to rows within the specified range, inclusive.
+     * Limit the query result by `from` and `to` inclusively.
      *
-     * @param from  The starting index from which to limit the result, inclusive.
-     * @param to  The last index to which to limit the result, inclusive.
-     * @param foreignTable  The foreign table to use (for foreign columns).
+     * @param from - The starting index from which to limit the result
+     * @param to - The last index to which to limit the result
+     * @param options - Named parameters
+     * @param options.foreignTable - Set this to limit rows of foreign tables
+     * instead of the current table
      */
@@ -68,3 +73,5 @@ range(from, to, { foreignTable } = {}) {
     /**
-     * Sets the AbortSignal for the fetch request.
+     * Set the AbortSignal for the fetch request.
+     *
+     * @param signal - The AbortSignal to use for the fetch request
      */
@@ -76,4 +83,6 @@ abortSignal(signal) {
     /**
-     * Retrieves only one row from the result. Result must be one row (e.g. using
-     * `limit`), otherwise this will result in an error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be one row (e.g. using `.limit(1)`), otherwise this
+     * returns an error.
      */
@@ -85,5 +94,6 @@ single() {
     /**
-     * Retrieves at most one row from the result. Result must be at most one row
-     * (e.g. using `eq` on a UNIQUE column), otherwise this will result in an
-     * error.
+     * Return `data` as a single object instead of an array of objects.
+     *
+     * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
+     * this returns an error.
      */
@@ -96,3 +106,3 @@ maybeSingle() {
     /**
-     * Set the response type to CSV.
+     * Return `data` as a string in CSV format.
      */
@@ -104,3 +114,3 @@ csv() {
     /**
-     * Set the response type to GeoJSON.
+     * Return `data` as an object in [GeoJSON](https://geojson.org) format.
      */
@@ -112,10 +122,21 @@ geojson() {
     /**
-     * Obtains the EXPLAIN plan for this request.
+     * Return `data` as the EXPLAIN plan for the query.
      *
-     * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
-     * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
-     * @param settings  If `true`, include information on configuration parameters that affect query planning.
-     * @param buffers  If `true`, include information on buffer usage.
-     * @param wal     If `true`, include information on WAL record generation
-     * @param format  The format of the output, can be 'text'(default) or `json`
+     * @param options - Named parameters
+     *
+     * @param options.analyze - If `true`, the query will be executed and the
+     * actual run time will be returned
+     *
+     * @param options.verbose - If `true`, the query identifier will be returned
+     * and `data` will include the output columns of the query
+     *
+     * @param options.settings - If `true`, include information on configuration
+     * parameters that affect query planning
+     *
+     * @param options.buffers - If `true`, include information on buffer usage
+     *
+     * @param options.wal - If `true`, include information on WAL record generation
+     *
+     * @param options.format - The format of the output, can be `"text"` (default)
+     * or `"json"`
      */
@@ -140,2 +161,7 @@ explain({ analyze = false, verbose = false, settings = false, buffers = false, wal = false, format = 'text', } = {}) {
     }
+    /**
+     * Rollback the query.
+     *
+     * `data` will still be returned, but the query is not committed.
+     */
     rollback() {
@@ -142,0 +168,0 @@ var _a;

dist/module/types.d.ts

@@ -23,19 +23,19 @@ export declare type Fetch = typeof fetch;
 interface PostgrestResponseSuccess<T> extends PostgrestResponseBase {
-    error: undefined;
+    error: null;
     data: T[];
-    count: number | undefined;
+    count: number | null;
 }
 interface PostgrestResponseFailure extends PostgrestResponseBase {
     error: PostgrestError;
-    data: undefined;
-    count: undefined;
+    data: null;
+    count: null;
 }
 export declare type PostgrestResponse<T> = PostgrestResponseSuccess<T> | PostgrestResponseFailure;
 interface PostgrestSingleResponseSuccess<T> extends PostgrestResponseBase {
-    error: undefined;
+    error: null;
     data: T;
-    count: number | undefined;
+    count: number | null;
 }
 export declare type PostgrestSingleResponse<T> = PostgrestSingleResponseSuccess<T> | PostgrestResponseFailure;
-export declare type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | undefined>;
+export declare type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>;
 export declare type GenericTable = {
@@ -42,0 +42,0 @@ Row: Record<string, unknown>;

dist/module/version.d.ts

@@ -1,2 +0,2 @@
-export declare const version = "1.0.0-rc.5";
+export declare const version = "1.0.0-rc.6";
 //# sourceMappingURL=version.d.ts.map

dist/module/version.js

@@ -1,2 +0,2 @@
-export const version = '1.0.0-rc.5';
+export const version = '1.0.0-rc.6';
 //# sourceMappingURL=version.js.map

package.json

 {
   "name": "@supabase/postgrest-js",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "description": "Isomorphic PostgREST client",
@@ -27,4 +27,5 @@ "keywords": [
     "build:module": "tsc -p tsconfig.module.json",
-    "test": "run-s db:clean db:run && jest --runInBand; run-s db:clean",
-    "test:update": "run-s db:clean db:run && jest --runInBand --updateSnapshot; run-s db:clean",
+    "test": "run-s db:clean db:run test:run db:clean",
+    "test:run": "jest --runInBand",
+    "test:update": "run-s db:clean db:run && jest --runInBand --updateSnapshot && run-s db:clean",
     "db:clean": "cd test/db && docker-compose down --volumes",
@@ -40,3 +41,2 @@ "db:run": "cd test/db && docker-compose up --detach && wait-for-localhost 3000",
     "@types/jest": "^27.5.1",
-    "@types/node-fetch": "^2.6.1",
     "jest": "^28.1.0",
@@ -50,5 +50,5 @@ "node-abort-controller": "^3.0.1",
     "typedoc": "^0.22.16",
-    "typescript": "~4.6.4",
+    "typescript": "~4.7",
     "wait-for-localhost-cli": "^3.0.0"
   }
 }

src/PostgrestBuilder.ts

@@ -56,3 +56,3 @@ import crossFetch from 'cross-fetch'
     // https://postgrest.org/en/stable/api.html#switching-schemas
-    if (typeof this.schema === 'undefined') {
+    if (this.schema === undefined) {
       // skip
@@ -77,5 +77,5 @@ } else if (['GET', 'HEAD'].includes(this.method)) {
     }).then(async (res) => {
-      let error = undefined
-      let data = undefined
-      let count = undefined
+      let error = null
+      let data = null
+      let count: number | null = null
       let status = res.status
@@ -85,16 +85,15 @@ let statusText = res.statusText
       if (res.ok) {
-        const isReturnMinimal = this.headers['Prefer']?.split(',').includes('return=minimal')
-        if (this.method !== 'HEAD' && !isReturnMinimal) {
-          const text = await res.text()
-          if (!text) {
-            // discard `text`
+        if (this.method !== 'HEAD') {
+          const body = await res.text()
+          if (body === '') {
+            // Prefer: return=minimal
           } else if (this.headers['Accept'] === 'text/csv') {
-            data = text
+            data = body
           } else if (
             this.headers['Accept'] &&
-            this.headers['Accept'].indexOf('application/vnd.pgrst.plan+text') !== -1
+            this.headers['Accept'].includes('application/vnd.pgrst.plan+text')
           ) {
-            data = text
+            data = body
           } else {
-            data = JSON.parse(text)
+            data = JSON.parse(body)
           }
@@ -120,3 +119,3 @@ }
         if (error && this.allowEmpty && error?.details?.includes('Results contain 0 rows')) {
-          error = undefined
+          error = null
           status = 200
@@ -149,6 +148,6 @@ statusText = 'OK'
         },
-        data: undefined,
-        count: undefined,
-        status: 400,
-        statusText: 'Bad Request',
+        data: null,
+        count: null,
+        status: 0,
+        statusText: '',
       }))
@@ -155,0 +154,0 @@ }

src/PostgrestClient.ts

@@ -7,2 +7,12 @@ import PostgrestQueryBuilder from './PostgrestQueryBuilder'
 
+/**
+ * PostgREST client.
+ *
+ * @typeParam Database - Types for the schema from the [type
+ * generator](https://supabase.com/docs/reference/javascript/next/typescript-support)
+ *
+ * @typeParam SchemaName - Postgres schema to switch to. Must be a string
+ * literal, the same one passed to the constructor. If the schema is not
+ * `"public"`, this must be supplied manually.
+ */
 export default class PostgrestClient<
@@ -26,5 +36,7 @@ Database = any,
    *
-   * @param url  URL of the PostgREST endpoint.
-   * @param headers  Custom headers.
-   * @param schema  Postgres schema to switch to.
+   * @param url - URL of the PostgREST endpoint
+   * @param options - Named parameters
+   * @param options.headers - Custom headers
+   * @param options.schema - Postgres schema to switch to
+   * @param options.fetch - Custom fetch
    */
@@ -52,3 +64,3 @@ constructor(
    *
-   * @param relation  The table or view name to query.
+   * @param relation - The table or view name to query
    */
@@ -75,5 +87,19 @@ from<
    *
-   * @param fn  The function name to call.
-   * @param args  The parameters to pass to the function call.
-   * @param options  Named parameters.
+   * @param fn - The function name to call
+   * @param args - The arguments to pass to the function call
+   * @param options - Named parameters
+   * @param options.head - When set to `true`, `data` will not be returned.
+   * Useful if you only need the count.
+   * @param options.count - Count algorithm to use to count rows returned by the
+   * function. Only applicable for [set-returning
+   * functions](https://www.postgresql.org/docs/current/functions-srf.html).
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -90,5 +116,3 @@ rpc<
     }: {
-      /** When set to true, no data will be returned. */
       head?: boolean
-      /** Count algorithm to use to count rows in a table. */
       count?: 'exact' | 'planned' | 'estimated'
@@ -95,0 +119,0 @@ } = {}

src/PostgrestFilterBuilder.ts

 import PostgrestTransformBuilder from './PostgrestTransformBuilder'
 
-/**
- * Filters
- */
-
 type FilterOperator =
@@ -36,38 +32,9 @@ | 'eq'
   /**
-   * Finds all rows which doesn't satisfy the filter.
+   * Match only rows where `column` is equal to `value`.
    *
-   * @param column  The column to filter on.
-   * @param operator  The operator to filter with.
-   * @param value  The value to filter with.
-   */
-  not<ColumnName extends string & keyof Row>(
-    column: ColumnName,
-    operator: FilterOperator,
-    value: Row[ColumnName]
-  ): this
-  not(column: string, operator: string, value: unknown): this
-  not(column: string, operator: string, value: unknown): this {
-    this.url.searchParams.append(column, `not.${operator}.${value}`)
-    return this
-  }
-
-  /**
-   * Finds all rows satisfying at least one of the filters.
+   * To check if the value of `column` is NULL, you should use `.is()` instead.
    *
-   * @param filters  The filters to use, separated by commas.
-   * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
-  or(filters: string, { foreignTable }: { foreignTable?: string } = {}): this {
-    const key = foreignTable ? `${foreignTable}.or` : 'or'
-    this.url.searchParams.append(key, `(${filters})`)
-    return this
-  }
-
-  /**
-   * Finds all rows whose value on the stated `column` exactly matches the
-   * specified `value`.
-   *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
-   */
   eq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
@@ -81,7 +48,6 @@ eq(column: string, value: unknown): this
   /**
-   * Finds all rows whose value on the stated `column` doesn't match the
-   * specified `value`.
+   * Match only rows where `column` is not equal to `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -96,7 +62,6 @@ neq<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
   /**
-   * Finds all rows whose value on the stated `column` is greater than the
-   * specified `value`.
+   * Match only rows where `column` is greater than `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -111,7 +76,6 @@ gt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
   /**
-   * Finds all rows whose value on the stated `column` is greater than or
-   * equal to the specified `value`.
+   * Match only rows where `column` is greater than or equal to `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -126,7 +90,6 @@ gte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
   /**
-   * Finds all rows whose value on the stated `column` is less than the
-   * specified `value`.
+   * Match only rows where `column` is less than `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -141,7 +104,6 @@ lt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
   /**
-   * Finds all rows whose value on the stated `column` is less than or equal
-   * to the specified `value`.
+   * Match only rows where `column` is less than or equal to `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -156,7 +118,6 @@ lte<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this
   /**
-   * Finds all rows whose value in the stated `column` matches the supplied
-   * `pattern` (case sensitive).
+   * Match only rows where `column` matches `pattern` case-sensitively.
    *
-   * @param column  The column to filter on.
-   * @param pattern  The pattern to filter with.
+   * @param column - The column to filter on
+   * @param pattern - The pattern to match with
    */
@@ -171,7 +132,6 @@ like<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this
   /**
-   * Finds all rows whose value in the stated `column` matches the supplied
-   * `pattern` (case insensitive).
+   * Match only rows where `column` matches `pattern` case-insensitively.
    *
-   * @param column  The column to filter on.
-   * @param pattern  The pattern to filter with.
+   * @param column - The column to filter on
+   * @param pattern - The pattern to match with
    */
@@ -186,7 +146,12 @@ ilike<ColumnName extends string & keyof Row>(column: ColumnName, pattern: string): this
   /**
-   * A check for exact equality (null, true, false), finds all rows whose
-   * value on the stated `column` exactly match the specified `value`.
+   * Match only rows where `column` IS `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * For non-boolean columns, this is only relevant for checking if the value of
+   * `column` is NULL by setting `value` to `null`.
+   *
+   * For boolean columns, you can also set `value` to `true` or `false` and it
+   * will behave the same way as `.eq()`.
+   *
+   * @param column - The column to filter on
+   * @param value - The value to filter with
    */
@@ -204,7 +169,6 @@ is<ColumnName extends string & keyof Row>(
   /**
-   * Finds all rows whose value on the stated `column` is found on the
-   * specified `values`.
+   * Match only rows where `column` is included in the `values` array.
    *
-   * @param column  The column to filter on.
-   * @param values  The values to filter with.
+   * @param column - The column to filter on
+   * @param values - The values array to filter with
    */
@@ -227,7 +191,7 @@ in<ColumnName extends string & keyof Row>(column: ColumnName, values: Row[ColumnName][]): this
   /**
-   * Finds all rows whose json, array, or range value on the stated `column`
-   * contains the values specified in `value`.
+   * Only relevant for jsonb, array, and range columns. Match only rows where
+   * `column` contains every element appearing in `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The jsonb, array, or range column to filter on
+   * @param value - The jsonb, array, or range value to filter with
    */
@@ -255,7 +219,7 @@ contains<ColumnName extends string & keyof Row>(
   /**
-   * Finds all rows whose json, array, or range value on the stated `column` is
-   * contained by the specified `value`.
+   * Only relevant for jsonb, array, and range columns. Match only rows where
+   * every element appearing in `column` is contained by `value`.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The jsonb, array, or range column to filter on
+   * @param value - The jsonb, array, or range value to filter with
    */
@@ -282,22 +246,8 @@ containedBy<ColumnName extends string & keyof Row>(
   /**
-   * Finds all rows whose range value on the stated `column` is strictly to the
-   * left of the specified `range`.
+   * Only relevant for range columns. Match only rows where every element in
+   * `column` is greater than any element in `range`.
    *
-   * @param column  The column to filter on.
-   * @param range  The range to filter with.
+   * @param column - The range column to filter on
+   * @param range - The range to filter with
    */
-  rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
-  rangeLt(column: string, range: string): this
-  rangeLt(column: string, range: string): this {
-    this.url.searchParams.append(column, `sl.${range}`)
-    return this
-  }
-
-  /**
-   * Finds all rows whose range value on the stated `column` is strictly to
-   * the right of the specified `range`.
-   *
-   * @param column  The column to filter on.
-   * @param range  The range to filter with.
-   */
   rangeGt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
@@ -311,7 +261,8 @@ rangeGt(column: string, range: string): this
   /**
-   * Finds all rows whose range value on the stated `column` does not extend
-   * to the left of the specified `range`.
+   * Only relevant for range columns. Match only rows where every element in
+   * `column` is either contained in `range` or greater than any element in
+   * `range`.
    *
-   * @param column  The column to filter on.
-   * @param range  The range to filter with.
+   * @param column - The range column to filter on
+   * @param range - The range to filter with
    */
@@ -326,8 +277,23 @@ rangeGte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
   /**
-   * Finds all rows whose range value on the stated `column` does not extend
-   * to the right of the specified `range`.
+   * Only relevant for range columns. Match only rows where every element in
+   * `column` is less than any element in `range`.
    *
-   * @param column  The column to filter on.
-   * @param range  The range to filter with.
+   * @param column - The range column to filter on
+   * @param range - The range to filter with
    */
+  rangeLt<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
+  rangeLt(column: string, range: string): this
+  rangeLt(column: string, range: string): this {
+    this.url.searchParams.append(column, `sl.${range}`)
+    return this
+  }
+
+  /**
+   * Only relevant for range columns. Match only rows where every element in
+   * `column` is either contained in `range` or less than any element in
+   * `range`.
+   *
+   * @param column - The range column to filter on
+   * @param range - The range to filter with
+   */
   rangeLte<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
@@ -341,7 +307,8 @@ rangeLte(column: string, range: string): this
   /**
-   * Finds all rows whose range value on the stated `column` is adjacent to
-   * the specified `range`.
+   * Only relevant for range columns. Match only rows where `column` is
+   * mutually exclusive to `range` and there can be no element between the two
+   * ranges.
    *
-   * @param column  The column to filter on.
-   * @param range  The range to filter with.
+   * @param column - The range column to filter on
+   * @param range - The range to filter with
    */
@@ -356,7 +323,7 @@ rangeAdjacent<ColumnName extends string & keyof Row>(column: ColumnName, range: string): this
   /**
-   * Finds all rows whose array or range value on the stated `column` overlaps
-   * (has a value in common) with the specified `value`.
+   * Only relevant for array and range columns. Match only rows where
+   * `column` and `value` have an element in common.
    *
-   * @param column  The column to filter on.
-   * @param value  The value to filter with.
+   * @param column - The array or range column to filter on
+   * @param value - The array or range value to filter with
    */
@@ -380,9 +347,10 @@ overlaps<ColumnName extends string & keyof Row>(
   /**
-   * Finds all rows whose text or tsvector value on the stated `column` matches
-   * the tsquery in `query`.
+   * Only relevant for text and tsvector columns. Match only rows where
+   * `column` matches the query string in `query`.
    *
-   * @param column  The column to filter on.
-   * @param query  The Postgres tsquery string to filter with.
-   * @param config  The text search configuration to use.
-   * @param type  The type of tsquery conversion to use on `query`.
+   * @param column - The text or tsvector column to filter on
+   * @param query - The query text to match with
+   * @param options - Named parameters
+   * @param options.config - The text search configuration to use
+   * @param options.type - Change how the `query` text is interpreted
    */
@@ -418,8 +386,73 @@ textSearch<ColumnName extends string & keyof Row>(
   /**
-   * Finds all rows whose `column` satisfies the filter.
+   * Match only rows where each column in `query` keys is equal to its
+   * associated value. Shorthand for multiple `.eq()`s.
    *
-   * @param column  The column to filter on.
-   * @param operator  The operator to filter with.
-   * @param value  The value to filter with.
+   * @param query - The object to filter with, with column names as keys mapped
+   * to their filter values
    */
+  match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this
+  match(query: Record<string, unknown>): this
+  match(query: Record<string, unknown>): this {
+    Object.entries(query).forEach(([column, value]) => {
+      this.url.searchParams.append(column, `eq.${value}`)
+    })
+    return this
+  }
+
+  /**
+   * Match only rows which doesn't satisfy the filter.
+   *
+   * Unlike most filters, `opearator` and `value` are used as-is and need to
+   * follow [PostgREST
+   * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+   * to make sure they are properly sanitized.
+   *
+   * @param column - The column to filter on
+   * @param operator - The operator to be negated to filter with, following
+   * PostgREST syntax
+   * @param value - The value to filter with, following PostgREST syntax
+   */
+  not<ColumnName extends string & keyof Row>(
+    column: ColumnName,
+    operator: FilterOperator,
+    value: Row[ColumnName]
+  ): this
+  not(column: string, operator: string, value: unknown): this
+  not(column: string, operator: string, value: unknown): this {
+    this.url.searchParams.append(column, `not.${operator}.${value}`)
+    return this
+  }
+
+  /**
+   * Match only rows which satisfy at least one of the filters.
+   *
+   * Unlike most filters, `filters` is used as-is and needs to follow [PostgREST
+   * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+   * to make sure it's properly sanitized.
+   *
+   * It's currently not possible to do an `.or()` filter across multiple tables.
+   *
+   * @param filters - The filters to use, following PostgREST syntax
+   * @param foreignTable - Set this to filter on foreign tables instead of the
+   * current table
+   */
+  or(filters: string, { foreignTable }: { foreignTable?: string } = {}): this {
+    const key = foreignTable ? `${foreignTable}.or` : 'or'
+    this.url.searchParams.append(key, `(${filters})`)
+    return this
+  }
+
+  /**
+   * Match only rows which satisfy the filter. This is an escape hatch - you
+   * should use the specific filter methods wherever possible.
+   *
+   * Unlike most filters, `opearator` and `value` are used as-is and need to
+   * follow [PostgREST
+   * syntax](https://postgrest.org/en/stable/api.html#operators). You also need
+   * to make sure they are properly sanitized.
+   *
+   * @param column - The column to filter on
+   * @param operator - The operator to filter with, following PostgREST syntax
+   * @param value - The value to filter with, following PostgREST syntax
+   */
   filter<ColumnName extends string & keyof Row>(
@@ -435,17 +468,2 @@ column: ColumnName,
   }
-
-  /**
-   * Finds all rows whose columns match the specified `query` object.
-   *
-   * @param query  The object to filter with, with column names as keys mapped
-   *               to their filter values.
-   */
-  match<ColumnName extends string & keyof Row>(query: Record<ColumnName, Row[ColumnName]>): this
-  match(query: Record<string, unknown>): this
-  match(query: Record<string, unknown>): this {
-    Object.entries(query).forEach(([column, value]) => {
-      this.url.searchParams.append(column, `eq.${value}`)
-    })
-    return this
-  }
 }

src/PostgrestQueryBuilder.ts

@@ -32,5 +32,21 @@ import PostgrestBuilder from './PostgrestBuilder'
   /**
-   * Performs vertical filtering with SELECT.
+   * Perform a SELECT query on the table or view.
    *
-   * @param columns  The columns to retrieve, separated by commas.
+   * @param columns - The columns to retrieve, separated by commas
+   *
+   * @param options - Named parameters
+   *
+   * @param options.head - When set to `true`, `data` will not be returned.
+   * Useful if you only need the count.
+   *
+   * @param options.count - Count algorithm to use to count rows in the table or view.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -46,5 +62,3 @@ select<
     }: {
-      /** When set to true, select will void data. */
       head?: boolean
-      /** Count algorithm to use to count rows in a table. */
       count?: 'exact' | 'planned' | 'estimated'
@@ -84,5 +98,22 @@ } = {}
   /**
-   * Performs an INSERT into the table.
+   * Perform an INSERT into the table or view.
    *
-   * @param values    The values to insert.
+   * By default, inserted rows are not returned. To return it, chain the call
+   * with `.select()`.
+   *
+   * @param values - The values to insert. Pass an object to insert a single row
+   * or an array to insert multiple rows.
+   *
+   * @param options - Named parameters
+   *
+   * @param options.count - Count algorithm to use to count inserted rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -94,3 +125,2 @@ insert<Row extends Relation extends { Insert: unknown } ? Relation['Insert'] : never>(
     }: {
-      /** Count algorithm to use to count rows in a table. */
       count?: 'exact' | 'planned' | 'estimated'
@@ -131,5 +161,33 @@ } = {}
   /**
-   * Performs an UPSERT into the table.
+   * Perform an UPSERT on the table or view. Depending on the column(s) passed
+   * to `onConflict`, `.upsert()` allows you to perform the equivalent of
+   * `.insert()` if a row with the corresponding `onConflict` columns doesn't
+   * exist, or if it does exist, perform an alternative action depending on
+   * `ignoreDuplicates`.
    *
-   * @param values  The values to insert.
+   * By default, upserted rows are not returned. To return it, chain the call
+   * with `.select()`.
+   *
+   * @param values - The values to upsert with. Pass an object to upsert a
+   * single row or an array to upsert multiple rows.
+   *
+   * @param options - Named parameters
+   *
+   * @param options.onConflict - Comma-separated UNIQUE column(s) to specify how
+   * duplicate rows are determined. Two rows are duplicates if all the
+   * `onConflict` columns are equal.
+   *
+   * @param options.ignoreDuplicates - If `true`, duplicate rows are ignored. If
+   * `false`, duplicate rows are merged with existing rows.
+   *
+   * @param options.count - Count algorithm to use to count upserted rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -140,11 +198,8 @@ upsert<Row extends Relation extends { Insert: unknown } ? Relation['Insert'] : never>(
       onConflict,
+      ignoreDuplicates = false,
       count,
-      ignoreDuplicates = false,
     }: {
-      /** By specifying the `on_conflict` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint. */
       onConflict?: string
-      /** Count algorithm to use to count rows in a table. */
+      ignoreDuplicates?: boolean
       count?: 'exact' | 'planned' | 'estimated'
-      /** Specifies if duplicate rows should be ignored and not inserted. */
-      ignoreDuplicates?: boolean
     } = {}
@@ -178,5 +233,21 @@ ): PostgrestFilterBuilder<Relation['Row'], undefined> {
   /**
-   * Performs an UPDATE on the table.
+   * Perform an UPDATE on the table or view.
    *
-   * @param values  The values to update.
+   * By default, updated rows are not returned. To return it, chain the call
+   * with `.select()` after filters.
+   *
+   * @param values - The values to update with
+   *
+   * @param options - Named parameters
+   *
+   * @param options.count - Count algorithm to use to count updated rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -188,3 +259,2 @@ update<Row extends Relation extends { Update: unknown } ? Relation['Update'] : never>(
     }: {
-      /** Count algorithm to use to count rows in a table. */
       count?: 'exact' | 'planned' | 'estimated'
@@ -216,3 +286,19 @@ } = {}
   /**
-   * Performs a DELETE on the table.
+   * Perform a DELETE on the table or view.
+   *
+   * By default, deleted rows are not returned. To return it, chain the call
+   * with `.select()` after filters.
+   *
+   * @param options - Named parameters
+   *
+   * @param options.count - Count algorithm to use to count deleted rows.
+   *
+   * `"exact"`: Exact but slow count algorithm. Performs a `COUNT(*)` under the
+   * hood.
+   *
+   * `"planned"`: Approximated but fast count algorithm. Uses the Postgres
+   * statistics under the hood.
+   *
+   * `"estimated"`: Uses exact count for low numbers and planned count for high
+   * numbers.
    */
@@ -222,3 +308,2 @@ delete({
   }: {
-    /** Count algorithm to use to count rows in a table. */
     count?: 'exact' | 'planned' | 'estimated'
@@ -225,0 +310,0 @@ } = {}): PostgrestFilterBuilder<Relation['Row'], undefined> {

src/PostgrestTransformBuilder.ts

@@ -5,6 +5,2 @@ import PostgrestBuilder from './PostgrestBuilder'
 
-/**
- * Post-filters (transforms)
- */
-
 export default class PostgrestTransformBuilder<
@@ -15,5 +11,9 @@ Row extends Record<string, unknown>,
   /**
-   * Performs vertical filtering with SELECT.
+   * Perform a SELECT on the query result.
    *
-   * @param columns  The columns to retrieve, separated by commas.
+   * By default, `.insert()`, `.update()`, `.upsert()`, and `.delete()` do not
+   * return modified rows. By calling this method, modified rows are returned in
+   * `data`.
+   *
+   * @param columns - The columns to retrieve, separated by commas
    */
@@ -46,8 +46,16 @@ select<Query extends string = '*', NewResult = GetResult<Row, Query extends '*' ? '*' : Query>>(
   /**
-   * Orders the result with the specified `column`.
+   * Order the query result by `column`.
    *
-   * @param column  The column to order on.
-   * @param ascending  If `true`, the result will be in ascending order.
-   * @param nullsFirst  If `true`, `null`s appear first.
-   * @param foreignTable  The foreign table to use (if `column` is a foreign column).
+   * You can call this method multiple times to order by multiple columns.
+   *
+   * You can order foreign tables, but it doesn't affect the ordering of the
+   * current table.
+   *
+   * @param column - The column to order by
+   * @param options - Named parameters
+   * @param options.ascending - If `true`, the result will be in ascending order
+   * @param options.nullsFirst - If `true`, `null`s appear first. If `false`,
+   * `null`s appear last.
+   * @param options.foreignTable - Set this to order a foreign table by foreign
+   * columns
    */
@@ -83,6 +91,8 @@ order<ColumnName extends string & keyof Row>(
   /**
-   * Limits the result with the specified `count`.
+   * Limit the query result by `count`.
    *
-   * @param count  The maximum no. of rows to limit to.
-   * @param foreignTable  The foreign table to use (for foreign columns).
+   * @param count - The maximum number of rows to return
+   * @param options - Named parameters
+   * @param options.foreignTable - Set this to limit rows of foreign tables
+   * instead of the current table
    */
@@ -96,7 +106,9 @@ limit(count: number, { foreignTable }: { foreignTable?: string } = {}): this {
   /**
-   * Limits the result to rows within the specified range, inclusive.
+   * Limit the query result by `from` and `to` inclusively.
    *
-   * @param from  The starting index from which to limit the result, inclusive.
-   * @param to  The last index to which to limit the result, inclusive.
-   * @param foreignTable  The foreign table to use (for foreign columns).
+   * @param from - The starting index from which to limit the result
+   * @param to - The last index to which to limit the result
+   * @param options - Named parameters
+   * @param options.foreignTable - Set this to limit rows of foreign tables
+   * instead of the current table
    */
@@ -113,3 +125,5 @@ range(from: number, to: number, { foreignTable }: { foreignTable?: string } = {}): this {
   /**
-   * Sets the AbortSignal for the fetch request.
+   * Set the AbortSignal for the fetch request.
+   *
+   * @param signal - The AbortSignal to use for the fetch request
    */
@@ -122,4 +136,6 @@ abortSignal(signal: AbortSignal): this {
   /**
-   * Retrieves only one row from the result. Result must be one row (e.g. using
-   * `limit`), otherwise this will result in an error.
+   * Return `data` as a single object instead of an array of objects.
+   *
+   * Query result must be one row (e.g. using `.limit(1)`), otherwise this
+   * returns an error.
    */
@@ -132,5 +148,6 @@ single(): PromiseLike<PostgrestSingleResponse<Result>> {
   /**
-   * Retrieves at most one row from the result. Result must be at most one row
-   * (e.g. using `eq` on a UNIQUE column), otherwise this will result in an
-   * error.
+   * Return `data` as a single object instead of an array of objects.
+   *
+   * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
+   * this returns an error.
    */
@@ -144,3 +161,3 @@ maybeSingle(): PromiseLike<PostgrestMaybeSingleResponse<Result>> {
   /**
-   * Set the response type to CSV.
+   * Return `data` as a string in CSV format.
    */
@@ -153,3 +170,3 @@ csv(): PromiseLike<PostgrestSingleResponse<string>> {
   /**
-   * Set the response type to GeoJSON.
+   * Return `data` as an object in [GeoJSON](https://geojson.org) format.
    */
@@ -162,10 +179,21 @@ geojson(): PromiseLike<PostgrestSingleResponse<Record<string, unknown>>> {
   /**
-   * Obtains the EXPLAIN plan for this request.
+   * Return `data` as the EXPLAIN plan for the query.
    *
-   * @param analyze  If `true`, the query will be executed and the actual run time will be displayed.
-   * @param verbose  If `true`, the query identifier will be displayed and the result will include the output columns of the query.
-   * @param settings  If `true`, include information on configuration parameters that affect query planning.
-   * @param buffers  If `true`, include information on buffer usage.
-   * @param wal     If `true`, include information on WAL record generation
-   * @param format  The format of the output, can be 'text'(default) or `json`
+   * @param options - Named parameters
+   *
+   * @param options.analyze - If `true`, the query will be executed and the
+   * actual run time will be returned
+   *
+   * @param options.verbose - If `true`, the query identifier will be returned
+   * and `data` will include the output columns of the query
+   *
+   * @param options.settings - If `true`, include information on configuration
+   * parameters that affect query planning
+   *
+   * @param options.buffers - If `true`, include information on buffer usage
+   *
+   * @param options.wal - If `true`, include information on WAL record generation
+   *
+   * @param options.format - The format of the output, can be `"text"` (default)
+   * or `"json"`
    */
@@ -207,2 +235,7 @@ explain({
 
+  /**
+   * Rollback the query.
+   *
+   * `data` will still be returned, but the query is not committed.
+   */
   rollback(): this {
@@ -209,0 +242,0 @@ if ((this.headers['Prefer'] ?? '').trim().length > 0) {

src/types.ts

@@ -26,10 +26,10 @@ export type Fetch = typeof fetch
 interface PostgrestResponseSuccess<T> extends PostgrestResponseBase {
-  error: undefined
+  error: null
   data: T[]
-  count: number | undefined
+  count: number | null
 }
 interface PostgrestResponseFailure extends PostgrestResponseBase {
   error: PostgrestError
-  data: undefined
-  count: undefined
+  data: null
+  count: null
 }
@@ -39,5 +39,5 @@ export type PostgrestResponse<T> = PostgrestResponseSuccess<T> | PostgrestResponseFailure
 interface PostgrestSingleResponseSuccess<T> extends PostgrestResponseBase {
-  error: undefined
+  error: null
   data: T
-  count: number | undefined
+  count: number | null
 }
@@ -47,3 +47,3 @@ export type PostgrestSingleResponse<T> =
   | PostgrestResponseFailure
-export type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | undefined>
+export type PostgrestMaybeSingleResponse<T> = PostgrestSingleResponse<T | null>
 
@@ -50,0 +50,0 @@ export type GenericTable = {

src/version.ts

@@ -1,1 +0,1 @@
-export const version = '1.0.0-rc.5'
+export const version = '1.0.0-rc.6'

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

285770

increased by12.07%

Dev dependency count

11

decreased by-8.33%

Lines of code

5023

increased by18.58%

No dependency changes