@supabase/postgrest-js 2.99.2 → 2.99.3

package/dist/index.d.mts

@@ -638,7 +638,19 @@ declare abstract class PostgrestBuilder<ClientOptions extends ClientServerOption
    *
    * @example
    * ```ts
-   * import PostgrestQueryBuilder from '@supabase/postgrest-js'
+   * import { PostgrestQueryBuilder } from '@supabase/postgrest-js'
+   *
+   * const builder = new PostgrestQueryBuilder(
+   *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
+   *   { headers: new Headers({ apikey: 'public-anon-key' }) }
+   * )
+   * ```
+   *
+   * @category Database
+   *
+   * @example Example 1
+   * ```ts
+   * import { PostgrestQueryBuilder } from '@supabase/postgrest-js'
    *
    * const builder = new PostgrestQueryBuilder(
    *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
@@ -663,18 +675,27 @@ declare abstract class PostgrestBuilder<ClientOptions extends ClientServerOption
    * throwing the error instead of returning it as part of a successful response.
    *
    * {@link https://github.com/supabase/supabase-js/issues/92}
+   *
+   * @category Database
    */
   throwOnError(): this & PostgrestBuilder<ClientOptions, Result$1, true>;
   /**
    * Set an HTTP header for the request.
+   *
+   * @category Database
    */
   setHeader(name: string, value: string): this;
+  /**  *
+   * @category Database
+   */
   then<TResult1 = (ThrowOnError extends true ? PostgrestResponseSuccess<Result$1> : PostgrestSingleResponse<Result$1>), TResult2 = never>(onfulfilled?: ((value: ThrowOnError extends true ? PostgrestResponseSuccess<Result$1> : PostgrestSingleResponse<Result$1>) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
   /**
    * Override the type of the returned `data`.
    *
    * @typeParam NewResult - The new result type to override with
    * @deprecated Use overrideTypes<yourType, { merge: false }>() method at the end of your call chain instead
+   *
+   * @category Database
    */
   returns<NewResult>(): PostgrestBuilder<ClientOptions, CheckMatchingArrayTypes<Result$1, NewResult>, ThrowOnError>;
   /**
@@ -698,6 +719,77 @@ declare abstract class PostgrestBuilder<ClientOptions extends ClientServerOption
    *   .overrideTypes<{ id: number; name: string }, { merge: false }>()
    * ```
    * @returns A PostgrestBuilder instance with the new type
+   *
+   * @category Database
+   *
+   * @example Complete Override type of successful response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .overrideTypes<Array<MyType>, { merge: false }>()
+   * ```
+   *
+   * @exampleResponse Complete Override type of successful response
+   * ```ts
+   * let x: typeof data // MyType[]
+   * ```
+   *
+   * @example Complete Override type of object response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .maybeSingle()
+   *   .overrideTypes<MyType, { merge: false }>()
+   * ```
+   *
+   * @exampleResponse Complete Override type of object response
+   * ```ts
+   * let x: typeof data // MyType | null
+   * ```
+   *
+   * @example Partial Override type of successful response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .overrideTypes<Array<{ status: "A" | "B" }>>()
+   * ```
+   *
+   * @exampleResponse Partial Override type of successful response
+   * ```ts
+   * let x: typeof data // Array<CountryRowProperties & { status: "A" | "B" }>
+   * ```
+   *
+   * @example Partial Override type of object response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .maybeSingle()
+   *   .overrideTypes<{ status: "A" | "B" }>()
+   * ```
+   *
+   * @exampleResponse Partial Override type of object response
+   * ```ts
+   * let x: typeof data // CountryRowProperties & { status: "A" | "B" } | null
+   * ```
+   *
+   * @example Example 5
+   * ```typescript
+   * // Merge with existing types (default behavior)
+   * const query = supabase
+   *   .from('users')
+   *   .select()
+   *   .overrideTypes<{ custom_field: string }>()
+   *
+   * // Replace existing types completely
+   * const replaceQuery = supabase
+   *   .from('users')
+   *   .select()
+   *   .overrideTypes<{ id: number; name: string }, { merge: false }>()
+   * ```
    */
   overrideTypes<NewResult, Options extends {
     merge?: boolean;
@@ -849,6 +941,41 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * `data`.
    *
    * @param columns - The columns to retrieve, separated by commas
+   *
+   * @category Database
+   *
+   * @example With `upsert()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .upsert({ id: 1, name: 'Han Solo' })
+   *   .select()
+   * ```
+   *
+   * @exampleSql With `upsert()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Han');
+   * ```
+   *
+   * @exampleResponse With `upsert()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "Han Solo"
+   *     }
+   *   ],
+   *   "status": 201,
+   *   "statusText": "Created"
+   * }
+   * ```
    */
   select<Query extends string = '*', NewResultOne = GetResult<Schema, Row, RelationName, Relationships, Query, ClientOptions>>(columns?: Query): PostgrestFilterBuilder<ClientOptions, Schema, Row, Method extends 'RPC' ? Result$1 extends unknown[] ? NewResultOne[] : NewResultOne : NewResultOne[], RelationName, Relationships, Method>;
   order<ColumnName extends string & keyof Row>(column: ColumnName, options?: {
@@ -886,6 +1013,95 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * tables instead of the parent table
    * @param options.foreignTable - Deprecated, use `options.referencedTable`
    * instead
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('name')
+   *   .limit(1)
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "Luke"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example On a referenced table
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('orchestral_sections')
+   *   .select(`
+   *     name,
+   *     instruments (
+   *       name
+   *     )
+   *   `)
+   *   .limit(1, { referencedTable: 'instruments' })
+   * ```
+   *
+   * @exampleSql On a referenced table
+   * ```sql
+   * create table
+   *   orchestral_sections (id int8 primary key, name text);
+   * create table
+   *   instruments (
+   *     id int8 primary key,
+   *     section_id int8 not null references orchestral_sections,
+   *     name text
+   *   );
+   *
+   * insert into
+   *   orchestral_sections (id, name)
+   * values
+   *   (1, 'strings');
+   * insert into
+   *   instruments (id, section_id, name)
+   * values
+   *   (1, 1, 'harp'),
+   *   (2, 1, 'violin');
+   * ```
+   *
+   * @exampleResponse On a referenced table
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "strings",
+   *       "instruments": [
+   *         {
+   *           "name": "violin"
+   *         }
+   *       ]
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   limit(count: number, {
     foreignTable,
@@ -908,6 +1124,45 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * tables instead of the parent table
    * @param options.foreignTable - Deprecated, use `options.referencedTable`
    * instead
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('name')
+   *   .range(0, 1)
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "Luke"
+   *     },
+   *     {
+   *       "name": "Leia"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   range(from: number, to: number, {
     foreignTable,
@@ -920,6 +1175,66 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * Set the AbortSignal for the fetch request.
    *
    * @param signal - The AbortSignal to use for the fetch request
+   *
+   * @category Database
+   *
+   * @remarks
+   * You can use this to set a timeout for the request.
+   *
+   * @exampleDescription Aborting requests in-flight
+   * You can use an [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) to abort requests.
+   * Note that `status` and `statusText` don't mean anything for aborted requests as the request wasn't fulfilled.
+   *
+   * @example Aborting requests in-flight
+   * ```ts
+   * const ac = new AbortController()
+   *
+   * const { data, error } = await supabase
+   *   .from('very_big_table')
+   *   .select()
+   *   .abortSignal(ac.signal)
+   *
+   * // Abort the request after 100 ms
+   * setTimeout(() => ac.abort(), 100)
+   * ```
+   *
+   * @exampleResponse Aborting requests in-flight
+   * ```json
+   *   {
+   *     "error": {
+   *       "message": "AbortError: The user aborted a request.",
+   *       "details": "",
+   *       "hint": "The request was aborted locally via the provided AbortSignal.",
+   *       "code": ""
+   *     },
+   *     "status": 0,
+   *     "statusText": ""
+   *   }
+   *
+   * ```
+   *
+   * @example Set a timeout
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('very_big_table')
+   *   .select()
+   *   .abortSignal(AbortSignal.timeout(1000 /* ms *\/))
+   * ```
+   *
+   * @exampleResponse Set a timeout
+   * ```json
+   *   {
+   *     "error": {
+   *       "message": "FetchError: The user aborted a request.",
+   *       "details": "",
+   *       "hint": "",
+   *       "code": ""
+   *     },
+   *     "status": 400,
+   *     "statusText": "Bad Request"
+   *   }
+   *
+   * ```
    */
   abortSignal(signal: AbortSignal): this;
   /**
@@ -927,6 +1242,41 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    *
    * Query result must be one row (e.g. using `.limit(1)`), otherwise this
    * returns an error.
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('name')
+   *   .limit(1)
+   *   .single()
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": {
+   *     "name": "Luke"
+   *   },
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   single<ResultOne = (Result$1 extends (infer ResultOne)[] ? ResultOne : never)>(): PostgrestBuilder<ClientOptions, ResultOne>;
   /**
@@ -934,14 +1284,83 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    *
    * Query result must be zero or one row (e.g. using `.limit(1)`), otherwise
    * this returns an error.
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .eq('name', 'Katniss')
+   *   .maybeSingle()
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   maybeSingle<ResultOne = (Result$1 extends (infer ResultOne)[] ? ResultOne : never)>(): PostgrestBuilder<ClientOptions, ResultOne | null>;
   /**
    * Return `data` as a string in CSV format.
+   *
+   * @category Database
+   *
+   * @exampleDescription Return data as CSV
+   * By default, the data is returned in JSON format, but can also be returned as Comma Separated Values.
+   *
+   * @example Return data as CSV
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .csv()
+   * ```
+   *
+   * @exampleSql Return data as CSV
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse Return data as CSV
+   * ```json
+   * {
+   *   "data": "id,name\n1,Luke\n2,Leia\n3,Han",
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   csv(): PostgrestBuilder<ClientOptions, string>;
   /**
    * Return `data` as an object in [GeoJSON](https://geojson.org) format.
+   *
+   * @category Database
    */
   geojson(): PostgrestBuilder<ClientOptions, Record<string, unknown>>;
   /**
@@ -968,6 +1387,76 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    *
    * @param options.format - The format of the output, can be `"text"` (default)
    * or `"json"`
+   *
+   * @category Database
+   *
+   * @exampleDescription Get the execution plan
+   * By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
+   *
+   * @example Get the execution plan
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .explain()
+   * ```
+   *
+   * @exampleSql Get the execution plan
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse Get the execution plan
+   * ```js
+   * Aggregate  (cost=33.34..33.36 rows=1 width=112)
+   *   ->  Limit  (cost=0.00..18.33 rows=1000 width=40)
+   *         ->  Seq Scan on characters  (cost=0.00..22.00 rows=1200 width=40)
+   * ```
+   *
+   * @exampleDescription Get the execution plan with analyze and verbose
+   * By default, the data is returned in TEXT format, but can also be returned as JSON by using the `format` parameter.
+   *
+   * @example Get the execution plan with analyze and verbose
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .explain({analyze:true,verbose:true})
+   * ```
+   *
+   * @exampleSql Get the execution plan with analyze and verbose
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse Get the execution plan with analyze and verbose
+   * ```js
+   * Aggregate  (cost=33.34..33.36 rows=1 width=112) (actual time=0.041..0.041 rows=1 loops=1)
+   *   Output: NULL::bigint, count(ROW(characters.id, characters.name)), COALESCE(json_agg(ROW(characters.id, characters.name)), '[]'::json), NULLIF(current_setting('response.headers'::text, true), ''::text), NULLIF(current_setting('response.status'::text, true), ''::text)
+   *   ->  Limit  (cost=0.00..18.33 rows=1000 width=40) (actual time=0.005..0.006 rows=3 loops=1)
+   *         Output: characters.id, characters.name
+   *         ->  Seq Scan on public.characters  (cost=0.00..22.00 rows=1200 width=40) (actual time=0.004..0.005 rows=3 loops=1)
+   *               Output: characters.id, characters.name
+   * Query Identifier: -4730654291623321173
+   * Planning Time: 0.407 ms
+   * Execution Time: 0.119 ms
+   * ```
    */
   explain({
     analyze,
@@ -988,6 +1477,8 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * Rollback the query.
    *
    * `data` will still be returned, but the query is not committed.
+   *
+   * @category Database
    */
   rollback(): this;
   /**
@@ -995,6 +1486,38 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    *
    * @typeParam NewResult - The new result type to override with
    * @deprecated Use overrideTypes<yourType, { merge: false }>() method at the end of your call chain instead
+   *
+   * @category Database
+   *
+   * @remarks
+   * - Deprecated: use overrideTypes method instead
+   *
+   * @example Override type of successful response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .returns<Array<MyType>>()
+   * ```
+   *
+   * @exampleResponse Override type of successful response
+   * ```js
+   * let x: typeof data // MyType[]
+   * ```
+   *
+   * @example Override type of object response
+   * ```ts
+   * const { data } = await supabase
+   *   .from('countries')
+   *   .select()
+   *   .maybeSingle()
+   *   .returns<MyType>()
+   * ```
+   *
+   * @exampleResponse Override type of object response
+   * ```js
+   * let x: typeof data // MyType | null
+   * ```
    */
   returns<NewResult>(): PostgrestTransformBuilder<ClientOptions, Schema, Row, CheckMatchingArrayTypes<Result$1, NewResult>, RelationName, Relationships, Method>;
   /**
@@ -1002,6 +1525,8 @@ declare class PostgrestTransformBuilder<ClientOptions extends ClientServerOption
    * Only available in PostgREST v13+ and only works with PATCH and DELETE methods.
    *
    * @param value - The maximum number of rows that can be affected
+   *
+   * @category Database
    */
   maxAffected(value: number): MaxAffectedEnabled<ClientOptions['PostgrestVersion']> extends true ? Method extends 'PATCH' | 'DELETE' | 'RPC' ? this : InvalidMethodError<'maxAffected method only available on update or delete'> : InvalidMethodError<'maxAffected method only available on postgrest 13+'>;
 }
@@ -1022,6 +1547,43 @@ declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions,
    *
    * @param column - The column to filter on
    * @param value - The value to filter with
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .eq('name', 'Leia')
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 2,
+   *       "name": "Leia"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   eq<ColumnName extends string>(column: ColumnName, value: ResolveFilterValue<Schema, Row, ColumnName> extends never ? NonNullable<unknown> : ResolveFilterValue<Schema, Row, ColumnName> extends infer ResolvedFilterValue ? NonNullable<ResolvedFilterValue> : never): this;
   /**
@@ -1029,6 +1591,47 @@ declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions,
    *
    * @param column - The column to filter on
    * @param value - The value to filter with
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .neq('name', 'Leia')
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "Luke"
+   *     },
+   *     {
+   *       "id": 3,
+   *       "name": "Han"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   neq<ColumnName extends string>(column: ColumnName, value: ResolveFilterValue<Schema, Row, ColumnName> extends never ? unknown : ResolveFilterValue<Schema, Row, ColumnName> extends infer ResolvedFilterValue ? ResolvedFilterValue : never): this;
   gt<ColumnName extends string & keyof Row>(column: ColumnName, value: Row[ColumnName]): this;
@@ -1073,6 +1676,47 @@ declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions,
    *
    * @param column - The column to filter on
    * @param values - The values array to filter with
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select()
+   *   .in('name', ['Leia', 'Han'])
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 2,
+   *       "name": "Leia"
+   *     },
+   *     {
+   *       "id": 3,
+   *       "name": "Han"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   in<ColumnName extends string>(column: ColumnName, values: ReadonlyArray<ResolveFilterValue<Schema, Row, ColumnName> extends never ? unknown : ResolveFilterValue<Schema, Row, ColumnName> extends infer ResolvedFilterValue ? ResolvedFilterValue : never>): this;
   /**
@@ -1124,6 +1768,141 @@ declare class PostgrestFilterBuilder<ClientOptions extends ClientServerOptions,
    * @param options.referencedTable - Set this to filter on referenced tables
    * instead of the parent table
    * @param options.foreignTable - Deprecated, use `referencedTable` instead
+   *
+   * @category Database
+   *
+   * @remarks
+   * or() expects you to use the raw PostgREST syntax for the filter names and values.
+   *
+   * ```ts
+   * .or('id.in.(5,6,7), arraycol.cs.{"a","b"}')  // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
+   * .or('id.in.(5,6,7), arraycol.cd.{"a","b"}')  // Use `cd` for `containedBy()`
+   * ```
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('name')
+   *   .or('id.eq.2,name.eq.Han')
+   * ```
+   *
+   * @exampleSql With `select()`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse With `select()`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "Leia"
+   *     },
+   *     {
+   *       "name": "Han"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example Use `or` with `and`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('name')
+   *   .or('id.gt.3,and(id.eq.1,name.eq.Luke)')
+   * ```
+   *
+   * @exampleSql Use `or` with `and`
+   * ```sql
+   * create table
+   *   characters (id int8 primary key, name text);
+   *
+   * insert into
+   *   characters (id, name)
+   * values
+   *   (1, 'Luke'),
+   *   (2, 'Leia'),
+   *   (3, 'Han');
+   * ```
+   *
+   * @exampleResponse Use `or` with `and`
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "Luke"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example Use `or` on referenced tables
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('orchestral_sections')
+   *   .select(`
+   *     name,
+   *     instruments!inner (
+   *       name
+   *     )
+   *   `)
+   *   .or('section_id.eq.1,name.eq.guzheng', { referencedTable: 'instruments' })
+   * ```
+   *
+   * @exampleSql Use `or` on referenced tables
+   * ```sql
+   * create table
+   *   orchestral_sections (id int8 primary key, name text);
+   * create table
+   *   instruments (
+   *     id int8 primary key,
+   *     section_id int8 not null references orchestral_sections,
+   *     name text
+   *   );
+   *
+   * insert into
+   *   orchestral_sections (id, name)
+   * values
+   *   (1, 'strings'),
+   *   (2, 'woodwinds');
+   * insert into
+   *   instruments (id, section_id, name)
+   * values
+   *   (1, 2, 'flute'),
+   *   (2, 1, 'violin');
+   * ```
+   *
+   * @exampleResponse Use `or` on referenced tables
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "strings",
+   *       "instruments": [
+   *         {
+   *           "name": "violin"
+   *         }
+   *       ]
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   or(filters: string, {
     foreignTable,
@@ -1151,7 +1930,19 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
    *
    * @example
    * ```ts
-   * import PostgrestQueryBuilder from '@supabase/postgrest-js'
+   * import { PostgrestQueryBuilder } from '@supabase/postgrest-js'
+   *
+   * const query = new PostgrestQueryBuilder(
+   *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
+   *   { headers: { apikey: 'public-anon-key' } }
+   * )
+   * ```
+   *
+   * @category Database
+   *
+   * @example Example 1
+   * ```ts
+   * import { PostgrestQueryBuilder } from '@supabase/postgrest-js'
    *
    * const query = new PostgrestQueryBuilder(
    *   new URL('https://xyzcompany.supabase.co/rest/v1/users'),
@@ -2147,6 +2938,105 @@ declare class PostgrestQueryBuilder<ClientOptions extends ClientServerOptions, S
    *
    * `"estimated"`: Uses exact count for low numbers and planned count for high
    * numbers.
+   *
+   * @category Database
+   *
+   * @remarks
+   * - `delete()` should always be combined with [filters](/docs/reference/javascript/using-filters) to target the item(s) you wish to delete.
+   * - If you use `delete()` with filters and you have
+   *   [RLS](/docs/learn/auth-deep-dive/auth-row-level-security) enabled, only
+   *   rows visible through `SELECT` policies are deleted. Note that by default
+   *   no rows are visible, so you need at least one `SELECT`/`ALL` policy that
+   *   makes the rows visible.
+   * - When using `delete().in()`, specify an array of values to target multiple rows with a single query. This is particularly useful for batch deleting entries that share common criteria, such as deleting users by their IDs. Ensure that the array you provide accurately represents all records you intend to delete to avoid unintended data removal.
+   *
+   * @example Delete a single record
+   * ```ts
+   * const response = await supabase
+   *   .from('countries')
+   *   .delete()
+   *   .eq('id', 1)
+   * ```
+   *
+   * @exampleSql Delete a single record
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   *
+   * insert into
+   *   countries (id, name)
+   * values
+   *   (1, 'Mordor');
+   * ```
+   *
+   * @exampleResponse Delete a single record
+   * ```json
+   * {
+   *   "status": 204,
+   *   "statusText": "No Content"
+   * }
+   * ```
+   *
+   * @example Delete a record and return it
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('countries')
+   *   .delete()
+   *   .eq('id', 1)
+   *   .select()
+   * ```
+   *
+   * @exampleSql Delete a record and return it
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   *
+   * insert into
+   *   countries (id, name)
+   * values
+   *   (1, 'Mordor');
+   * ```
+   *
+   * @exampleResponse Delete a record and return it
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": 1,
+   *       "name": "Mordor"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example Delete multiple records
+   * ```ts
+   * const response = await supabase
+   *   .from('countries')
+   *   .delete()
+   *   .in('id', [1, 2, 3])
+   * ```
+   *
+   * @exampleSql Delete multiple records
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   *
+   * insert into
+   *   countries (id, name)
+   * values
+   *   (1, 'Rohan'), (2, 'The Shire'), (3, 'Mordor');
+   * ```
+   *
+   * @exampleResponse Delete multiple records
+   * ```json
+   * {
+   *   "status": 204,
+   *   "statusText": "No Content"
+   * }
+   * ```
    */
   delete({
     count
@@ -2225,7 +3115,34 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
    * @param options.urlLengthLimit - Maximum URL length in characters before warnings/errors are triggered. Defaults to 8000.
    * @example
    * ```ts
-   * import PostgrestClient from '@supabase/postgrest-js'
+   * import { PostgrestClient } from '@supabase/postgrest-js'
+   *
+   * const postgrest = new PostgrestClient('https://xyzcompany.supabase.co/rest/v1', {
+   *   headers: { apikey: 'public-anon-key' },
+   *   schema: 'public',
+   *   timeout: 30000, // 30 second timeout
+   * })
+   * ```
+   *
+   * @category Database
+   *
+   * @remarks
+   * - A `timeout` option (in milliseconds) can be set to automatically abort requests that take too long.
+   * - A `urlLengthLimit` option (default: 8000) can be set to control when URL length warnings are included in error messages for aborted requests.
+   *
+   * @example Example 1
+   * ```ts
+   * import { PostgrestClient } from '@supabase/postgrest-js'
+   *
+   * const postgrest = new PostgrestClient('https://xyzcompany.supabase.co/rest/v1', {
+   *   headers: { apikey: 'public-anon-key' },
+   *   schema: 'public',
+   * })
+   * ```
+   *
+   * @example With timeout
+   * ```ts
+   * import { PostgrestClient } from '@supabase/postgrest-js'
    *
    * const postgrest = new PostgrestClient('https://xyzcompany.supabase.co/rest/v1', {
    *   headers: { apikey: 'public-anon-key' },
@@ -2255,6 +3172,8 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
    * The schema needs to be on the list of exposed schemas inside Supabase.
    *
    * @param schema - The schema to query
+   *
+   * @category Database
    */
   schema<DynamicSchema extends string & keyof Omit<Database, '__InternalSupabase'>>(schema: DynamicSchema): PostgrestClient<Database, ClientOptions, DynamicSchema, Database[DynamicSchema] extends GenericSchema ? Database[DynamicSchema] : any>;
   /**
@@ -2288,6 +3207,139 @@ declare class PostgrestClient<Database = any, ClientOptions extends ClientServer
    *   .rpc('function_a', {})
    *   .overrideTypes<{ id: string; user_id: string }[]>()
    * ```
+   *
+   * @category Database
+   *
+   * @example Call a Postgres function without arguments
+   * ```ts
+   * const { data, error } = await supabase.rpc('hello_world')
+   * ```
+   *
+   * @exampleSql Call a Postgres function without arguments
+   * ```sql
+   * create function hello_world() returns text as $$
+   *   select 'Hello world';
+   * $$ language sql;
+   * ```
+   *
+   * @exampleResponse Call a Postgres function without arguments
+   * ```json
+   * {
+   *   "data": "Hello world",
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example Call a Postgres function with arguments
+   * ```ts
+   * const { data, error } = await supabase.rpc('echo', { say: '👋' })
+   * ```
+   *
+   * @exampleSql Call a Postgres function with arguments
+   * ```sql
+   * create function echo(say text) returns text as $$
+   *   select say;
+   * $$ language sql;
+   * ```
+   *
+   * @exampleResponse Call a Postgres function with arguments
+   * ```json
+   *   {
+   *     "data": "👋",
+   *     "status": 200,
+   *     "statusText": "OK"
+   *   }
+   *
+   * ```
+   *
+   * @exampleDescription Bulk processing
+   * You can process large payloads by passing in an array as an argument.
+   *
+   * @example Bulk processing
+   * ```ts
+   * const { data, error } = await supabase.rpc('add_one_each', { arr: [1, 2, 3] })
+   * ```
+   *
+   * @exampleSql Bulk processing
+   * ```sql
+   * create function add_one_each(arr int[]) returns int[] as $$
+   *   select array_agg(n + 1) from unnest(arr) as n;
+   * $$ language sql;
+   * ```
+   *
+   * @exampleResponse Bulk processing
+   * ```json
+   * {
+   *   "data": [
+   *     2,
+   *     3,
+   *     4
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @exampleDescription Call a Postgres function with filters
+   * Postgres functions that return tables can also be combined with [Filters](/docs/reference/javascript/using-filters) and [Modifiers](/docs/reference/javascript/using-modifiers).
+   *
+   * @example Call a Postgres function with filters
+   * ```ts
+   * const { data, error } = await supabase
+   *   .rpc('list_stored_countries')
+   *   .eq('id', 1)
+   *   .single()
+   * ```
+   *
+   * @exampleSql Call a Postgres function with filters
+   * ```sql
+   * create table
+   *   countries (id int8 primary key, name text);
+   *
+   * insert into
+   *   countries (id, name)
+   * values
+   *   (1, 'Rohan'),
+   *   (2, 'The Shire');
+   *
+   * create function list_stored_countries() returns setof countries as $$
+   *   select * from countries;
+   * $$ language sql;
+   * ```
+   *
+   * @exampleResponse Call a Postgres function with filters
+   * ```json
+   * {
+   *   "data": {
+   *     "id": 1,
+   *     "name": "Rohan"
+   *   },
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @example Call a read-only Postgres function
+   * ```ts
+   * const { data, error } = await supabase.rpc('hello_world', undefined, { get: true })
+   * ```
+   *
+   * @exampleSql Call a read-only Postgres function
+   * ```sql
+   * create function hello_world() returns text as $$
+   *   select 'Hello world';
+   * $$ language sql;
+   * ```
+   *
+   * @exampleResponse Call a read-only Postgres function
+   * ```json
+   * {
+   *   "data": "Hello world",
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   rpc<FnName extends string & keyof Schema['Functions'], Args extends Schema['Functions'][FnName]['Args'] = never, FilterBuilder extends GetRpcFunctionFilterBuilderByArgs<Schema, FnName, Args> = GetRpcFunctionFilterBuilderByArgs<Schema, FnName, Args>>(fn: FnName, args?: Args, {
     head,