@supabase/postgrest-js 2.99.2 → 2.99.3

package/src/PostgrestTransformBuilder.ts

@@ -22,6 +22,41 @@ export default class PostgrestTransformBuilder<
    * `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 = '*',
@@ -111,6 +146,176 @@ export default class PostgrestTransformBuilder<
    * its columns
    * @param options.foreignTable - Deprecated, use `options.referencedTable`
    * instead
+   *
+   * @category Database
+   *
+   * @example With `select()`
+   * ```ts
+   * const { data, error } = await supabase
+   *   .from('characters')
+   *   .select('id, name')
+   *   .order('id', { ascending: false })
+   * ```
+   *
+   * @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": 3,
+   *       "name": "Han"
+   *     },
+   *     {
+   *       "id": 2,
+   *       "name": "Leia"
+   *     },
+   *     {
+   *       "id": 1,
+   *       "name": "Luke"
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @exampleDescription On a referenced table
+   * Ordering with `referencedTable` doesn't affect the ordering of the
+   * parent table.
+   *
+   * @example On a referenced table
+   * ```ts
+   *   const { data, error } = await supabase
+   *     .from('orchestral_sections')
+   *     .select(`
+   *       name,
+   *       instruments (
+   *         name
+   *       )
+   *     `)
+   *     .order('name', { referencedTable: 'instruments', ascending: false })
+   *
+   * ```
+   *
+   * @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'),
+   *   (2, 'woodwinds');
+   * 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"
+   *         },
+   *         {
+   *           "name": "harp"
+   *         }
+   *       ]
+   *     },
+   *     {
+   *       "name": "woodwinds",
+   *       "instruments": []
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
+   *
+   * @exampleDescription Order parent table by a referenced table
+   * Ordering with `referenced_table(col)` affects the ordering of the
+   * parent table.
+   *
+   * @example Order parent table by a referenced table
+   * ```ts
+   *   const { data, error } = await supabase
+   *     .from('instruments')
+   *     .select(`
+   *       name,
+   *       section:orchestral_sections (
+   *         name
+   *       )
+   *     `)
+   *     .order('section(name)', { ascending: true })
+   *
+   * ```
+   *
+   * @exampleSql Order parent table by 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'),
+   *   (2, 'woodwinds');
+   * insert into
+   *   instruments (id, section_id, name)
+   * values
+   *   (1, 2, 'flute'),
+   *   (2, 1, 'violin');
+   * ```
+   *
+   * @exampleResponse Order parent table by a referenced table
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "violin",
+   *       "orchestral_sections": {"name": "strings"}
+   *     },
+   *     {
+   *       "name": "flute",
+   *       "orchestral_sections": {"name": "woodwinds"}
+   *     }
+   *   ],
+   *   "status": 200,
+   *   "statusText": "OK"
+   * }
+   * ```
    */
   order(
     column: string,
@@ -147,6 +352,95 @@ export default class PostgrestTransformBuilder<
    * 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,
@@ -174,6 +468,45 @@ export default class PostgrestTransformBuilder<
    * 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,
@@ -196,6 +529,66 @@ export default class PostgrestTransformBuilder<
    * 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 {
     this.signal = signal
@@ -207,6 +600,41 @@ export default class PostgrestTransformBuilder<
    *
    * 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 extends (infer ResultOne)[] ? ResultOne : never>(): PostgrestBuilder<
     ClientOptions,
@@ -221,6 +649,38 @@ export default class PostgrestTransformBuilder<
    *
    * 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 extends (infer ResultOne)[] ? ResultOne : never,
@@ -238,6 +698,41 @@ export default class PostgrestTransformBuilder<
 
   /**
    * 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> {
     this.headers.set('Accept', 'text/csv')
@@ -246,6 +741,8 @@ export default class PostgrestTransformBuilder<
 
   /**
    * Return `data` as an object in [GeoJSON](https://geojson.org) format.
+   *
+   * @category Database
    */
   geojson(): PostgrestBuilder<ClientOptions, Record<string, unknown>> {
     this.headers.set('Accept', 'application/geo+json')
@@ -276,6 +773,76 @@ export default class PostgrestTransformBuilder<
    *
    * @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 = false,
@@ -318,6 +885,8 @@ export default class PostgrestTransformBuilder<
    * Rollback the query.
    *
    * `data` will still be returned, but the query is not committed.
+   *
+   * @category Database
    */
   rollback(): this {
     this.headers.append('Prefer', 'tx=rollback')
@@ -329,6 +898,38 @@ export default class PostgrestTransformBuilder<
    *
    * @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,
@@ -355,6 +956,8 @@ export default class PostgrestTransformBuilder<
    * 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
     ? // TODO: update the RPC case to only work on RPC that returns SETOF rows

package/src/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.99.2'
+export const version = '2.99.3'