From 5f0a991a2f72632454be7489146c973399008c5d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B8rge=20N=C3=A6ss?= <bjoerge@gmail.com>
Date: Fri, 19 Jul 2024 17:49:37 +0200
Subject: [PATCH] fix: add support for includeMutations listen parameter (#872)

---
 README.md                      | 2 ++
 src/data/encodeQueryString.ts  | 5 ++++-
 src/data/listen.ts             | 1 +
 src/types.ts                   | 7 +++++++
 test/encodeQueryString.test.ts | 7 +++++--
 5 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e0a7253a..03a606d5 100644
--- a/README.md
+++ b/README.md
@@ -851,6 +851,8 @@ By default, the emitted update event will also contain a `result` property, whic
 
 Likewise, you can also have the client return the document _before_ the mutation was applied, by setting `includePreviousRevision` to `true` in the options, which will include a `previous` property in each emitted object.
 
+If it's not relevant to know what mutations that was applied, you can also set `includeMutation` to `false` in the options, which will save some additional bandwidth by omitting the `mutation` property from the received events.
+
 ### Fetch a single document
 
 This will fetch a document from the [Doc endpoint](https://www.sanity.io/docs/http-doc). This endpoint cuts through any caching/indexing middleware that may involve delayed processing. As it is less scalable/performant than the other query mechanisms, it should be used sparingly. Performing a query is usually a better option.
diff --git a/src/data/encodeQueryString.ts b/src/data/encodeQueryString.ts
index 613d8eaf..8014ae3d 100644
--- a/src/data/encodeQueryString.ts
+++ b/src/data/encodeQueryString.ts
@@ -11,7 +11,7 @@ export const encodeQueryString = ({
 }) => {
   const searchParams = new URLSearchParams()
   // We generally want tag at the start of the query string
-  const {tag, returnQuery, ...opts} = options
+  const {tag, includeMutations, returnQuery, ...opts} = options
   // We're using `append` instead of `set` to support React Native: https://github.com/facebook/react-native/blob/1982c4722fcc51aa87e34cf562672ee4aff540f1/packages/react-native/Libraries/Blob/URL.js#L86-L88
   if (tag) searchParams.append('tag', tag)
   searchParams.append('query', query)
@@ -29,5 +29,8 @@ export const encodeQueryString = ({
   // `returnQuery` is default `true`, so needs an explicit `false` handling
   if (returnQuery === false) searchParams.append('returnQuery', 'false')
 
+  // `includeMutations` is default `true`, so needs an explicit `false` handling
+  if (includeMutations === false) searchParams.append('includeMutations', 'false')
+
   return `?${searchParams}`
 }
diff --git a/src/data/listen.ts b/src/data/listen.ts
index 52ffe86d..f2a06f41 100644
--- a/src/data/listen.ts
+++ b/src/data/listen.ts
@@ -15,6 +15,7 @@ const MAX_URL_LENGTH = 16000 - 1200
 const possibleOptions = [
   'includePreviousRevision',
   'includeResult',
+  'includeMutations',
   'visibility',
   'effectFormat',
   'tag',
diff --git a/src/types.ts b/src/types.ts
index 4b4d1f01..793463b6 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -874,6 +874,13 @@ export interface ListenOptions {
    */
   includeResult?: boolean
 
+  /**
+   * Whether or not to include the mutations that was performed.
+   * If you do not need the mutations, set this to `false` to reduce bandwidth usage.
+   * @defaultValue `true`
+   */
+  includeMutations?: boolean
+
   /**
    * Whether or not to include the document as it looked before the mutation event.
    * The previous revision will be available on the `.previous` property of the events,
diff --git a/test/encodeQueryString.test.ts b/test/encodeQueryString.test.ts
index 37cc2d69..ebfdb5ba 100644
--- a/test/encodeQueryString.test.ts
+++ b/test/encodeQueryString.test.ts
@@ -36,7 +36,7 @@ test('handles options', () => {
   )
 })
 
-test('skips falsy options', () => {
+test('skips falsy options unless they override server side defaults', () => {
   const query = 'gamedb.game[maxPlayers == 64]'
   expect(
     encodeQueryString({
@@ -47,7 +47,10 @@ test('skips falsy options', () => {
         includePreviousRevision: undefined,
         visibility: 0,
         tag: '',
+        // these defaults to 'true' server side
+        returnQuery: false,
+        includeMutations: false,
       },
     }),
-  ).toEqual('?query=gamedb.game%5BmaxPlayers+%3D%3D+64%5D')
+  ).toEqual('?query=gamedb.game%5BmaxPlayers+%3D%3D+64%5D&returnQuery=false&includeMutations=false')
 })