fix: add support for includeMutations listen parameter (#872)

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.

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}`
 }

src/data/listen.ts

@@ -15,6 +15,7 @@ const MAX_URL_LENGTH = 16000 - 1200
 const possibleOptions = [
   'includePreviousRevision',
   'includeResult',
+  'includeMutations',
   'visibility',
   'effectFormat',
   'tag',

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,

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')
 })