feat: Allow Prefer: return=minimal for C(R)UD (#133)

* style: run prettier

* feat: allow Prefer return=minimal in C(R)UD

`Prefer return` is set to `representation` by default, but this gives an
error when inserting/updating/deleting on, say, a write-only table.
Allow the users to set it to `minimal` by setting `returning`.

* test: reorganize tests to have deterministic order

Co-authored-by: Paul Copplestone <[email protected]>
Co-authored-by: Steve Chavez <[email protected]>

Author: 3 people

src/lib/PostgrestQueryBuilder.ts

@@ -46,16 +46,28 @@ export default class PostgrestQueryBuilder<T> extends PostgrestBuilder<T> {
    *
    * @param values  The values to insert.
    * @param upsert  If `true`, performs an UPSERT.
-   * @param onConflict By specifying the `on_conflict` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint.
+   * @param onConflict  By specifying the `on_conflict` query parameter, you can make UPSERT work on a column(s) that has a UNIQUE constraint.
+   * @param returning  By default the new record is returned. Set this to 'minimal' if you don't need this value.
    */
   insert(
     values: Partial<T> | Partial<T>[],
-    { upsert = false, onConflict }: { upsert?: boolean; onConflict?: string } = {}
+    {
+      upsert = false,
+      onConflict,
+      returning = 'representation',
+    }: {
+      upsert?: boolean
+      onConflict?: string
+      returning?: 'minimal' | 'representation'
+    } = {}
   ): PostgrestFilterBuilder<T> {
     this.method = 'POST'
-    this.headers['Prefer'] = upsert
-      ? 'return=representation,resolution=merge-duplicates'
-      : 'return=representation'
+
+    let prefersHeaders = []
+    prefersHeaders.push(`return=${returning}`)
+    if (upsert) prefersHeaders.push('resolution=merge-duplicates')
+    this.headers['Prefer'] = prefersHeaders.join(',')
+
     if (upsert && onConflict !== undefined) this.url.searchParams.set('on_conflict', onConflict)
     this.body = values
     return new PostgrestFilterBuilder(this)
@@ -65,20 +77,28 @@ export default class PostgrestQueryBuilder<T> extends PostgrestBuilder<T> {
    * Performs an UPDATE on the table.
    *
    * @param values  The values to update.
+   * @param returning  By default the updated record is returned. Set this to 'minimal' if you don't need this value.
    */
-  update(values: Partial<T>): PostgrestFilterBuilder<T> {
+  update(
+    values: Partial<T>,
+    { returning = 'representation' }: { returning?: 'minimal' | 'representation' } = {}
+  ): PostgrestFilterBuilder<T> {
     this.method = 'PATCH'
-    this.headers['Prefer'] = 'return=representation'
+    this.headers['Prefer'] = `return=${returning}`
     this.body = values
     return new PostgrestFilterBuilder(this)
   }
 
   /**
    * Performs a DELETE on the table.
+   *
+   * @param returning  If `true`, return the deleted row(s) in the response.
    */
-  delete(): PostgrestFilterBuilder<T> {
+  delete({
+    returning = 'representation',
+  }: { returning?: 'minimal' | 'representation' } = {}): PostgrestFilterBuilder<T> {
     this.method = 'DELETE'
-    this.headers['Prefer'] = 'return=representation'
+    this.headers['Prefer'] = `return=${returning}`
     return new PostgrestFilterBuilder(this)
   }
 

src/lib/types.ts

@@ -40,7 +40,9 @@ interface PostgrestSingleResponseSuccess<T> extends PostgrestResponseBase {
   // For backward compatibility: body === data
   body: T
 }
-export type PostgrestSingleResponse<T> = PostgrestSingleResponseSuccess<T> | PostgrestResponseFailure
+export type PostgrestSingleResponse<T> =
+  | PostgrestSingleResponseSuccess<T>
+  | PostgrestResponseFailure
 
 export abstract class PostgrestBuilder<T> implements PromiseLike<PostgrestResponse<T>> {
   protected method!: 'GET' | 'HEAD' | 'POST' | 'PATCH' | 'DELETE'
@@ -81,7 +83,8 @@ export abstract class PostgrestBuilder<T> implements PromiseLike<PostgrestRespon
         let error, data
         if (res.ok) {
           error = null
-          data = await res.json()
+          const isReturnMinimal = this.headers['Prefer']?.split(',').includes('return=minimal')
+          data = isReturnMinimal ? null : await res.json()
         } else {
           error = await res.json()
           data = null