docs(repo): more description and examples

Author: mandarini

packages/core/auth-js/src/lib/locks.ts

@@ -86,6 +86,12 @@ export class ProcessLockAcquireTimeoutError extends LockAcquireTimeoutError {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
+ * @example
+ * ```ts
+ * await navigatorLock('sync-user', 1000, async () => {
+ *   await refreshSession()
+ * })
+ * ```
  */
 export async function navigatorLock<R>(
   name: string,
@@ -198,6 +204,12 @@ const PROCESS_LOCKS: { [name: string]: Promise<any> } = {}
  *                       will time out after so many milliseconds. An error is
  *                       a timeout if it has `isAcquireTimeout` set to true.
  * @param fn The operation to run once the lock is acquired.
+ * @example
+ * ```ts
+ * await processLock('migrate', 5000, async () => {
+ *   await runMigration()
+ * })
+ * ```
  */
 export async function processLock<R>(
   name: string,

packages/core/functions-js/src/FunctionsClient.ts

@@ -9,12 +9,28 @@ import {
   FunctionsResponse,
 } from './types'
 
+/**
+ * Client for invoking Supabase Edge Functions.
+ */
 export class FunctionsClient {
   protected url: string
   protected headers: Record<string, string>
   protected region: FunctionRegion
   protected fetch: Fetch
 
+  /**
+   * Creates a new Functions client bound to an Edge Functions URL.
+   *
+   * @example
+   * ```ts
+   * import { FunctionsClient, FunctionRegion } from '@supabase/functions-js'
+   *
+   * const functions = new FunctionsClient('https://xyzcompany.supabase.co/functions/v1', {
+   *   headers: { apikey: 'public-anon-key' },
+   *   region: FunctionRegion.UsEast1,
+   * })
+   * ```
+   */
   constructor(
     url: string,
     {
@@ -36,6 +52,10 @@ export class FunctionsClient {
   /**
    * Updates the authorization header
    * @param token - the new jwt token sent in the authorisation header
+   * @example
+   * ```ts
+   * functions.setAuth(session.access_token)
+   * ```
    */
   setAuth(token: string) {
     this.headers.Authorization = `Bearer ${token}`
@@ -45,6 +65,12 @@ export class FunctionsClient {
    * Invokes a function
    * @param functionName - The name of the Function to invoke.
    * @param options - Options for invoking the Function.
+   * @example
+   * ```ts
+   * const { data, error } = await functions.invoke('hello-world', {
+   *   body: { name: 'Ada' },
+   * })
+   * ```
    */
   async invoke<T = any>(
     functionName: string,

packages/core/postgrest-js/src/PostgrestBuilder.ts

@@ -29,6 +29,8 @@ export default abstract class PostgrestBuilder<
   protected isMaybeSingle: boolean
 
   /**
+   * Creates a builder configured for a specific PostgREST request.
+   *
    * @example
    * ```ts
    * import PostgrestQueryBuilder from '@supabase/postgrest-js'

packages/core/postgrest-js/src/PostgrestQueryBuilder.ts

@@ -22,6 +22,8 @@ export default class PostgrestQueryBuilder<
   fetch?: Fetch
 
   /**
+   * Creates a query builder scoped to a Postgres table or view.
+   *
    * @example
    * ```ts
    * import PostgrestQueryBuilder from '@supabase/postgrest-js'

packages/core/realtime-js/src/lib/websocket-factory.ts

@@ -32,6 +32,9 @@ export interface WebSocketEnvironment {
   workaround?: string
 }
 
+/**
+ * Utilities for creating WebSocket instances across runtimes.
+ */
 export class WebSocketFactory {
   private static detectEnvironment(): WebSocketEnvironment {
     if (typeof WebSocket !== 'undefined') {
@@ -115,6 +118,15 @@ export class WebSocketFactory {
     }
   }
 
+  /**
+   * Returns the best available WebSocket constructor for the current runtime.
+   *
+   * @example
+   * ```ts
+   * const WS = WebSocketFactory.getWebSocketConstructor()
+   * const socket = new WS('wss://realtime.supabase.co/socket')
+   * ```
+   */
   public static getWebSocketConstructor(): typeof WebSocket {
     const env = this.detectEnvironment()
     if (env.constructor) {
@@ -127,11 +139,29 @@ export class WebSocketFactory {
     throw new Error(errorMessage)
   }
 
+  /**
+   * Creates a WebSocket using the detected constructor.
+   *
+   * @example
+   * ```ts
+   * const socket = WebSocketFactory.createWebSocket('wss://realtime.supabase.co/socket')
+   * ```
+   */
   public static createWebSocket(url: string | URL, protocols?: string | string[]): WebSocketLike {
     const WS = this.getWebSocketConstructor()
     return new WS(url, protocols)
   }
 
+  /**
+   * Detects whether the runtime can establish WebSocket connections.
+   *
+   * @example
+   * ```ts
+   * if (!WebSocketFactory.isWebSocketSupported()) {
+   *   console.warn('Falling back to long polling')
+   * }
+   * ```
+   */
   public static isWebSocketSupported(): boolean {
     try {
       const env = this.detectEnvironment()

packages/core/storage-js/src/StorageClient.ts

@@ -9,6 +9,19 @@ export interface StorageClientOptions {
 }
 
 export class StorageClient extends StorageBucketApi {
+  /**
+   * Creates a client for Storage buckets, files, analytics, and vectors.
+   *
+   * @example
+   * ```ts
+   * import { StorageClient } from '@supabase/storage-js'
+   *
+   * const storage = new StorageClient('https://xyzcompany.supabase.co/storage/v1', {
+   *   apikey: 'public-anon-key',
+   * })
+   * const avatars = storage.from('avatars')
+   * ```
+   */
   constructor(
     url: string,
     headers: { [key: string]: string } = {},

packages/core/supabase-js/src/index.ts

@@ -23,6 +23,14 @@ export type { SupabaseClientOptions, QueryResult, QueryData, QueryError } from '
 
 /**
  * Creates a new Supabase Client.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@supabase/supabase-js'
+ *
+ * const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')
+ * const { data, error } = await supabase.from('profiles').select('*')
+ * ```
  */
 export const createClient = <
   Database = any,