@supabase/postgrest-js 2.99.2 → 2.99.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/postgrest-js",
-  "version": "2.99.2",
+  "version": "2.99.3",
   "description": "Isomorphic PostgREST client",
   "keywords": [
     "postgrest",

package/src/PostgrestBuilder.ts

@@ -34,7 +34,19 @@ export default abstract class PostgrestBuilder<
    *
    * @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'),
@@ -76,6 +88,8 @@ export default abstract class PostgrestBuilder<
    * 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, true> {
     this.shouldThrowOnError = true
@@ -84,6 +98,8 @@ export default abstract class PostgrestBuilder<
 
   /**
    * Set an HTTP header for the request.
+   *
+   * @category Database
    */
   setHeader(name: string, value: string): this {
     this.headers = new Headers(this.headers)
@@ -91,6 +107,9 @@ export default abstract class PostgrestBuilder<
     return this
   }
 
+  /**  *
+   * @category Database
+   */
   then<
     TResult1 = ThrowOnError extends true
       ? PostgrestResponseSuccess<Result>
@@ -300,6 +319,8 @@ export default abstract class PostgrestBuilder<
    *
    * @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,
@@ -335,6 +356,77 @@ export default abstract class PostgrestBuilder<
    *   .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,

package/src/PostgrestClient.ts

@@ -53,7 +53,34 @@ export default class PostgrestClient<
    * @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' },
@@ -136,6 +163,8 @@ export default class PostgrestClient<
    * Perform a query on a table or a view.
    *
    * @param relation - The table or view name to query
+   *
+   * @category Database
    */
   from(
     relation: (string & keyof Schema['Tables']) | (string & keyof Schema['Views'])
@@ -159,6 +188,8 @@ export default class PostgrestClient<
    * 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
@@ -207,6 +238,139 @@ export default class PostgrestClient<
    *   .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'],