@supabase/postgrest-js 3.0.0-next.2 → 3.0.0-next.21

package/dist/index.d.mts

@@ -672,7 +672,7 @@ declare abstract class PostgrestBuilder<ClientOptions extends ClientServerOption
    * ```ts
    * import { createClient } from '@supabase/supabase-js'
    *
-   * const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key')
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
    * const { data, error } = await supabase.from('users').select('*')
    * ```
    *
@@ -684,7 +684,7 @@ declare abstract class PostgrestBuilder<ClientOptions extends ClientServerOption
    *
    * const builder = new PostgrestQueryBuilder(
    *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
-   *   { headers: new Headers({ apikey: 'publishable-or-anon-key' }) }
+   *   { headers: new Headers({ apikey: 'your-publishable-key' }) }
    * )
    * ```
    */
@@ -1649,6 +1649,8 @@ type ResolveFilterRelationshipValue<Schema extends GenericSchema, RelationshipTa
 type InvalidMethodError<S extends string> = {
   Error: S;
 };
+type NonNullableColumn<T extends Record<string, unknown>, Col extends string> = Col extends keyof T ? { [K in keyof T]: K extends Col ? NonNullable<T[K]> : T[K] } : T;
+type NarrowResultColumn<T, Col extends string> = T extends (infer Item)[] ? Item extends Record<string, unknown> ? Col extends keyof Item ? { [K in keyof Item]: K extends Col ? NonNullable<Item[K]> : Item[K] }[] : T : T : T extends Record<string, unknown> ? Col extends keyof T ? { [K in keyof T]: K extends Col ? NonNullable<T[K]> : T[K] } : T : T;
 declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions, Schema extends GenericSchema, Row extends Record<string, unknown>, Result$1, RelationName = unknown, Relationships = unknown, Method = unknown> extends PostgrestTransformBuilder<ClientOptions, Schema, Row, Result$1, RelationName, Relationships, Method> {
   /**
    * Match only rows where `column` is equal to `value`.
@@ -1862,6 +1864,7 @@ declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions,
   }): this;
   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: 'is', value: null): PostgrestFilterBuilder<ClientOptions, Schema, NonNullableColumn<Row, ColumnName>, NarrowResultColumn<Result$1, ColumnName>, RelationName, Relationships, Method> & this;
   not<ColumnName extends string & keyof Row>(column: ColumnName, operator: FilterOperator, value: Row[ColumnName]): this;
   not(column: string, operator: string, value: unknown): this;
   /**
@@ -2059,7 +2062,7 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
    * ```ts
    * import { createClient } from '@supabase/supabase-js'
    *
-   * const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key')
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
    * const { data, error } = await supabase.from('users').select('*')
    * ```
    *
@@ -2069,7 +2072,7 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
    *
    * const query = new PostgrestQueryBuilder(
    *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
-   *   { headers: { apikey: 'publishable-or-anon-key' }, retry: true }
+   *   { headers: { apikey: 'your-publishable-key' }, retry: true }
    * )
    * ```
    */
@@ -2871,40 +2874,355 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
        */
   select<Query extends string = '*', ResultOne = GetResult<Schema, Relation$1['Row'], RelationName, Relationships, Query, ClientOptions>>(columns?: Query, options?: {
     head?: boolean;
-    count?: 'exact' | 'planned' | 'estimated';
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], ResultOne[], RelationName, Relationships, 'GET'>;
+  /**
+   * Perform an INSERT into the table or view.
+   *
+   * 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.
+   *
+   * @param options.defaultToNull - Make missing fields default to `null`.
+   * Otherwise, use the default value for the column. Only applies for bulk
+   * inserts.
+   *
+   * @category Database
+   *
+   * @example Create a record
+   * ```ts
+   * const { error } = await supabase
+   *   .from('countries')
+   *   .insert({ id: 1, name: 'Mordor' })
+   * ```
+   *
+   * @exampleSql Create a record
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Create a record
+   * ```json
+   * {
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @example Create a record and return it
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('countries')
+   *   .insert({ id: 1, name: 'Mordor' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Create a record and return it
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Create a record and return it
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "Mordor"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @exampleDescription Bulk create
+   * A bulk create operation is handled in a single transaction.
+   * If any of the inserts fail, none of the rows are inserted.
+   *
+   * @example Bulk create
+   * ```ts
+   * const { error } = await supabase
+   *   .from('countries')
+   *   .insert([
+   *     { id: 1, name: 'Mordor' },
+   *     { id: 1, name: 'The Shire' },
+   *   ])
+   * ```
+   *
+   * @exampleSql Bulk create
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   * ```
+   *
+   * @exampleResponse Bulk create
+   * ```json
+   * {
+   *   "error": {
+   *     "code": "23505",
+   *     "details": "Key (id)=(1) already exists.",
+   *     "hint": null,
+   *     "message": "duplicate key value violates unique constraint \"countries_pkey\""
+   *   },
+   *   "status": 409,
+   *   "statusText": "Conflict"
+   * }
+   * ```
+   */
   insert<Row extends (Relation$1 extends {
     Insert: unknown;
   } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>, options?: {
-    count?: 'exact' | 'planned' | 'estimated';
-  }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
-  insert<Row extends (Relation$1 extends {
-    Insert: unknown;
-  } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
+  } ? Relation$1['Insert'] : never, Row> | RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>[], options?: {
-    count?: 'exact' | 'planned' | 'estimated';
+  } ? Relation$1['Insert'] : never, Row>[], {
+    count,
+    defaultToNull
+  }?: {
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
     defaultToNull?: boolean;
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
+  /**
+   * 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`.
+   *
+   * 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.
+   *
+   * @param options.defaultToNull - Make missing fields default to `null`.
+   * Otherwise, use the default value for the column. This only applies when
+   * inserting new rows, not when merging with existing rows under
+   * `ignoreDuplicates: false`. This also only applies when doing bulk upserts.
+   *
+   * @example Upsert a single row using a unique key
+   * ```ts
+   * // Upserting a single row, overwriting based on the 'username' unique column
+   * const { data, error } = await supabase
+   *   .from('users')
+   *   .upsert({ username: 'supabot' }, { onConflict: 'username' })
+   *
+   * // Example response:
+   * // {
+   * //   data: [
+   * //     { id: 4, message: 'bar', username: 'supabot' }
+   * //   ],
+   * //   error: null
+   * // }
+   * ```
+   *
+   * @example Upsert with conflict resolution and exact row counting
+   * ```ts
+   * // Upserting and returning exact count
+   * const { data, error, count } = await supabase
+   *   .from('users')
+   *   .upsert(
+   *     {
+   *       id: 3,
+   *       message: 'foo',
+   *       username: 'supabot'
+   *     },
+   *     {
+   *       onConflict: 'username',
+   *       count: 'exact'
+   *     }
+   *   )
+   *
+   * // Example response:
+   * // {
+   * //   data: [
+   * //     {
+   * //       id: 42,
+   * //       handle: "saoirse",
+   * //       display_name: "Saoirse"
+   * //     }
+   * //   ],
+   * //   count: 1,
+   * //   error: null
+   * // }
+   * ```
+   *
+   * @category Database
+   *
+   * @remarks
+   * - Primary keys must be included in `values` to use upsert.
+   *
+   * @example Upsert your data
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('instruments')
+   *   .upsert({ id: 1, name: 'piano' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Upsert your data
+   * ```sql
+   * create table
+   *   instruments (id int8 primary key, name text);
+   *
+   * insert into
+   *   instruments (id, name)
+   * values
+   *   (1, 'harpsichord');
+   * ```
+   *
+   * @exampleResponse Upsert your data
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "piano"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @example Bulk Upsert your data
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('instruments')
+   *   .upsert([
+   *     { id: 1, name: 'piano' },
+   *     { id: 2, name: 'harp' },
+   *   ])
+   *   .select()
+   * ```
+   *
+   * @exampleSql Bulk Upsert your data
+   * ```sql
+   * create table
+   *   instruments (id int8 primary key, name text);
+   *
+   * insert into
+   *   instruments (id, name)
+   * values
+   *   (1, 'harpsichord');
+   * ```
+   *
+   * @exampleResponse Bulk Upsert your data
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "piano"
+   *     },
+   *     {
+   *       "id": 2,
+   *       "name": "harp"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
+   *
+   * @exampleDescription Upserting into tables with constraints
+   * In the following query, `upsert()` implicitly uses the `id`
+   * (primary key) column to determine conflicts. If there is no existing
+   * row with the same `id`, `upsert()` inserts a new row, which
+   * will fail in this case as there is already a row with `handle` `"saoirse"`.
+   * Using the `onConflict` option, you can instruct `upsert()` to use
+   * another column with a unique constraint to determine conflicts.
+   *
+   * @example Upserting into tables with constraints
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('users')
+   *   .upsert({ id: 42, handle: 'saoirse', display_name: 'Saoirse' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql Upserting into tables with constraints
+   * ```sql
+   * create table
+   *   users (
+   *     id int8 generated by default as identity primary key,
+   *     handle text not null unique,
+   *     display_name text
+   *   );
+   *
+   * insert into
+   *   users (id, handle, display_name)
+   * values
+   *   (1, 'saoirse', null);
+   * ```
+   *
+   * @exampleResponse Upserting into tables with constraints
+   * ```json
+   * {
+   *   "error": {
+   *     "code": "23505",
+   *     "details": "Key (handle)=(saoirse) already exists.",
+   *     "hint": null,
+   *     "message": "duplicate key value violates unique constraint \"users_handle_key\""
+   *   },
+   *   "status": 409,
+   *   "statusText": "Conflict"
+   * }
+   * ```
+   */
   upsert<Row extends (Relation$1 extends {
     Insert: unknown;
   } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>, options?: {
-    onConflict?: string;
-    ignoreDuplicates?: boolean;
-    count?: 'exact' | 'planned' | 'estimated';
-  }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
-  upsert<Row extends (Relation$1 extends {
+  } ? Relation$1['Insert'] : never, Row> | RejectExcessProperties<Relation$1 extends {
     Insert: unknown;
-  } ? Relation$1['Insert'] : never)>(values: RejectExcessProperties<Relation$1 extends {
-    Insert: unknown;
-  } ? Relation$1['Insert'] : never, Row>[], options?: {
+  } ? Relation$1['Insert'] : never, Row>[], {
+    onConflict,
+    ignoreDuplicates,
+    count,
+    defaultToNull
+  }?: {
     onConflict?: string;
     ignoreDuplicates?: boolean;
-    count?: 'exact' | 'planned' | 'estimated';
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
     defaultToNull?: boolean;
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'POST'>;
   /**
@@ -3053,7 +3371,7 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
   } ? Relation$1['Update'] : never, Row>, {
     count
   }?: {
-    count?: 'exact' | 'planned' | 'estimated';
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'PATCH'>;
   /**
    * Perform a DELETE on the table or view.
@@ -3176,7 +3494,7 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
   delete({
     count
   }?: {
-    count?: 'exact' | 'planned' | 'estimated';
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
   }): PostgrestFilterBuilder<ClientOptions, Schema, Relation$1['Row'], null, RelationName, Relationships, 'DELETE'>;
 }
 //#endregion
@@ -3257,7 +3575,7 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
    * ```ts
    * import { createClient } from '@supabase/supabase-js'
    *
-   * const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key')
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
    * const { data, error } = await supabase.from('profiles').select('*')
    * ```
    *
@@ -3272,7 +3590,7 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
    * import { PostgrestClient } from '@supabase/postgrest-js'
    *
    * const postgrest = new PostgrestClient('https://xyzcompany.supabase.co/rest/v1', {
-   *   headers: { apikey: 'publishable-or-anon-key' },
+   *   headers: { apikey: 'your-publishable-key' },
    *   schema: 'public',
    *   timeout: 30000, // 30 second timeout
    * })
@@ -3477,7 +3795,7 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
   }?: {
     head?: boolean;
     get?: boolean;
-    count?: 'exact' | 'planned' | 'estimated';
+    count?: 'exact' | 'planned' | 'estimated' | (string & {});
   }): PostgrestFilterBuilder<ClientOptions, Schema, FilterBuilder['Row'], FilterBuilder['Result'], FilterBuilder['RelationName'], FilterBuilder['Relationships'], 'RPC'>;
 }
 //#endregion