From a6c334fa1c961cdb9d80ccf6374f0052df7dc9ba Mon Sep 17 00:00:00 2001
From: Vaibhav <117663341+7ttp@users.noreply.github.com>
Date: Fri, 21 Nov 2025 22:47:59 +0530
Subject: [PATCH 1/2] docs(postgrest): add upsert tsdoc examples and fix
 response/options

Adds missing @example blocks to the upsert TSDoc in postgrest-js.

- Includes correct response example for the upsert-with-constraints case
- Adds the missing onConflict option to the exact-count example
- Replaces outdated examples in the docs repo with typedoc-native examples

This aligns the JS client documentation with the expected behavior in Supabase.
---
 .../postgrest-js/src/PostgrestQueryBuilder.ts | 51 ++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts b/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
index a8c55142f..f17c6ec10 100644
--- a/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
+++ b/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
@@ -265,7 +265,7 @@ export default class PostgrestQueryBuilder<
     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
@@ -302,7 +302,56 @@ export default class PostgrestQueryBuilder<
    * 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
+   * ```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
+   * ```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
+   * // }
+   * ```
    */
+
+
   upsert<Row extends Relation extends { Insert: unknown } ? Relation['Insert'] : never>(
     values: Row | Row[],
     {

From b22aae439d45c217c2637e01fc2ac6b55d683d28 Mon Sep 17 00:00:00 2001
From: Vaibhav <117663341+7ttp@users.noreply.github.com>
Date: Fri, 21 Nov 2025 23:12:28 +0530
Subject: [PATCH 2/2] added example titles

---
 packages/core/postgrest-js/src/PostgrestQueryBuilder.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts b/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
index f17c6ec10..25bb604b4 100644
--- a/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
+++ b/packages/core/postgrest-js/src/PostgrestQueryBuilder.ts
@@ -303,7 +303,7 @@ export default class PostgrestQueryBuilder<
    * inserting new rows, not when merging with existing rows under
    * `ignoreDuplicates: false`. This also only applies when doing bulk upserts.
    *
-   * @example
+   * @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
@@ -319,7 +319,7 @@ export default class PostgrestQueryBuilder<
    * // }
    * ```
    *
-   * @example
+   * @example Upsert with conflict resolution and exact row counting
    * ```ts
    * // Upserting and returning exact count
    * const { data, error, count } = await supabase