@sanity/sdk 2.17.0 → 2.18.0

package/src/document/processActions.test.ts

@@ -4,7 +4,7 @@ import {describe, expect, it} from 'vitest'
 
 import {type Action, type DocumentAction} from './actions'
 import {ActionError, processActions} from './processActions/processActions'
-import {type DocumentSet} from './processMutations'
+import {type DocumentSet, processMutations} from './processMutations'
 
 // Helper: Create a sample document that conforms to SanityDocument.
 const createDoc = (id: string, title: string, rev: string = 'initial'): SanityDocument => ({
@@ -443,6 +443,190 @@ describe('processActions', () => {
       expect(result.outgoingActions[0].actionType).toBe('sanity.action.document.edit')
     })
 
+    it('preserves inc/dec operations instead of collapsing them into sets', () => {
+      const draft = {...createDoc('drafts.doc1', 'Title', '1'), count: 5, score: 10}
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches: [{inc: {count: 1}, dec: {score: 3}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      // the local working copy reflects the applied increments
+      expect(result.working['drafts.doc1']).toMatchObject({count: 6, score: 7})
+      // the outgoing patch keeps the operational inc/dec instead of a set.
+      // the setIfMissing seeds the base value in case the field was removed
+      // concurrently: the server runs setIfMissing before inc/dec, and inc on
+      // a missing path would otherwise fail the whole transaction
+      const patches = result.outgoingActions.map((action) => 'patch' in action && action.patch)
+      expect(patches).toEqual([
+        {setIfMissing: {count: 5, score: 10}, inc: {count: 1}, dec: {score: 3}},
+      ])
+    })
+
+    it('accumulates multiple inc/dec records on the same path into one operation', () => {
+      const draft = {...createDoc('drafts.doc1', 'Title', '1'), count: 5}
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches: [{inc: {count: 1}}, {inc: {count: 2}}, {dec: {count: 4}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      // 5 + 1 + 2 - 4 = 4 locally
+      expect(result.working['drafts.doc1']).toMatchObject({count: 4})
+      // the three records collapse into one accumulated dec (net -1) with the
+      // base value seeded for the concurrent-removal degradation path
+      const patches = result.outgoingActions.map((action) => 'patch' in action && action.patch)
+      expect(patches).toEqual([{setIfMissing: {count: 5}, dec: {count: 1}}])
+    })
+
+    it('keeps the diffed set when an inc is combined with a set of the same field', () => {
+      const draft = {...createDoc('drafts.doc1', 'Title', '1'), count: 5}
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          // set to 100 first, then inc: the final value (101) is not
+          // explainable by the inc alone, so it must remain a set
+          patches: [{set: {count: 100}}, {inc: {count: 1}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      expect(result.working['drafts.doc1']).toMatchObject({count: 101})
+      const patches = result.outgoingActions.map((action) => 'patch' in action && action.patch)
+      expect(patches).toEqual([{set: {count: 101}}])
+    })
+
+    it('preserves inc operations targeting keyed array items', () => {
+      const draft = {
+        ...createDoc('drafts.doc1', 'Title', '1'),
+        items: [{_key: 'itemA', qty: 2}],
+      }
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches: [{inc: {'items[_key=="itemA"].qty': 3}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      expect(result.working['drafts.doc1']?.['items']).toEqual([{_key: 'itemA', qty: 5}])
+      const patches = result.outgoingActions.map((action) => 'patch' in action && action.patch)
+      expect(patches).toEqual([
+        {setIfMissing: {'items[_key=="itemA"].qty': 2}, inc: {'items[_key=="itemA"].qty': 3}},
+      ])
+    })
+
+    it('preserves inc operations through the liveEdit mutation path', () => {
+      const liveDoc = {...createLiveEditDoc('live-doc', 'Title', '1'), count: 5}
+      const base: DocumentSet = {'live-doc': liveDoc}
+      const working: DocumentSet = {'live-doc': liveDoc}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'live-doc',
+          documentType: 'liveArticle',
+          type: 'document.edit',
+          liveEdit: true,
+          patches: [{inc: {count: 2}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      expect(result.working['live-doc']).toMatchObject({count: 7})
+      expect(result.outgoingMutations).toEqual([
+        {patch: {id: 'live-doc', setIfMissing: {count: 5}, inc: {count: 2}}},
+      ])
+    })
+
+    it('degrades to the diffed set result when the inc target was removed concurrently', () => {
+      const draft = {...createDoc('drafts.doc1', 'Title', '1'), count: 5}
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches: [{inc: {count: 1}}],
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+      const patch = result.outgoingActions.map((action) => 'patch' in action && action.patch)[0]
+
+      // simulate the server applying the emitted patch to a document where
+      // another client removed the counter in the meantime: setIfMissing
+      // seeds the base value, then inc applies, matching what the collapsed
+      // set would have written (instead of inc failing the transaction)
+      const {count: _count, ...draftWithoutCount} = draft
+      const serverResult = processMutations({
+        documents: {'drafts.doc1': draftWithoutCount as SanityDocument},
+        mutations: [{patch: {id: 'drafts.doc1', ...(patch as object)}}],
+        transactionId: 'txn-server',
+      })
+      expect(serverResult['drafts.doc1']).toMatchObject({count: 6})
+    })
+
     it('should edit a document when base and working diverge', () => {
       const publishedBase = createDoc('doc1', 'Original Boring Title')
       const publishedWorking = createDoc('doc1', 'Local Boring Title')

package/src/document/reducers.test.ts

@@ -696,6 +696,129 @@ describe('applyRemoteDocument', () => {
     expect(newDocState?.unverifiedRevisions?.['txn10']).toBeUndefined()
   })
 
+  describe('fast-forward convergence of local', () => {
+    const docId = getDraftId(DocumentId('doc1'))
+    const otherDocId = getDraftId(DocumentId('doc2'))
+
+    const makeApplied = (overrides: Partial<AppliedTransaction>): AppliedTransaction => ({
+      transactionId: 'txnPending',
+      actions: [],
+      working: {},
+      previous: {},
+      base: {},
+      previousRevs: {},
+      timestamp: '2025-02-06T00:06:30.000Z',
+      outgoingActions: [],
+      outgoingMutations: [],
+      ...overrides,
+    })
+
+    const makeState = (applied: AppliedTransaction[]): SyncTransactionState => ({
+      queued: [],
+      applied,
+      outgoing: undefined,
+      grants,
+      documentStates: {
+        [docId]: {
+          id: docId,
+          subscriptions: ['sub1'],
+          local: {...exampleDoc, _id: docId, foo: 'optimistic'},
+          remote: {...exampleDoc, _id: docId, foo: 'old'},
+          unverifiedRevisions: {
+            txn10: {
+              transactionId: 'txn10',
+              documentId: docId,
+              previousRev: 'revOld',
+              timestamp: '2025-02-06T00:06:00.000Z',
+            },
+          },
+        },
+      },
+    })
+
+    const remote: RemoteDocument = {
+      type: 'sync',
+      documentId: docId,
+      document: {...exampleDoc, _id: docId, foo: 'server-truth'},
+      revision: 'txn10',
+      previousRev: 'revOld',
+      timestamp: '2025-02-06T00:07:00.000Z',
+    }
+
+    it('converges local to the server document when nothing else is pending', () => {
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('converges local when pending work modifies only other documents', () => {
+      // a pending applied transaction on doc2 must not block convergence of
+      // doc1: nothing would ever revisit doc1's local otherwise
+      const otherDoc = {...exampleDoc, _id: otherDocId}
+      const pendingOnOtherDoc = makeApplied({
+        working: {[otherDocId]: {...otherDoc, _rev: 'txnPending'}},
+        previous: {[otherDocId]: otherDoc},
+        base: {[otherDocId]: otherDoc},
+        previousRevs: {[otherDocId]: 'txn0'},
+      })
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([pendingOnOtherDoc]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('converges local when pending work carries this document unmodified', () => {
+      // a draft edit carries the published document in its working set
+      // without changing it; presence alone must not block convergence
+      const thisDoc = {...exampleDoc, _id: docId}
+      const pendingCarryingUnmodified = makeApplied({
+        working: {
+          [docId]: thisDoc,
+          [otherDocId]: {...exampleDoc, _id: otherDocId, _rev: 'txnPending'},
+        },
+        previous: {[docId]: thisDoc, [otherDocId]: {...exampleDoc, _id: otherDocId}},
+        base: {[docId]: thisDoc, [otherDocId]: {...exampleDoc, _id: otherDocId}},
+        previousRevs: {[docId]: thisDoc._rev, [otherDocId]: 'txn0'},
+      })
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(makeState([pendingCarryingUnmodified]), remote, events)
+      expect(newState.documentStates[docId]?.local).toEqual(remote.document)
+    })
+
+    it('keeps the optimistic local when pending work modifies this document', () => {
+      const optimistic = {...exampleDoc, _id: docId, _rev: 'txnPending', foo: 'optimistic'}
+      const pendingOnThisDoc = makeApplied({
+        working: {[docId]: optimistic},
+        previous: {[docId]: {...exampleDoc, _id: docId}},
+        base: {[docId]: {...exampleDoc, _id: docId}},
+        previousRevs: {[docId]: 'txn0'},
+      })
+      const state = makeState([pendingOnThisDoc])
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(state, remote, events)
+      expect(newState.documentStates[docId]?.local).toBe(state.documentStates[docId]?.local)
+      expect(newState.documentStates[docId]?.remote).toEqual(remote.document)
+    })
+
+    it('keeps the optimistic local when a different in-flight transaction modifies this document', () => {
+      const optimistic = {...exampleDoc, _id: docId, _rev: 'txnOutgoing', foo: 'optimistic'}
+      const outgoing = {
+        ...makeApplied({
+          transactionId: 'txnOutgoing',
+          working: {[docId]: optimistic},
+          previous: {[docId]: {...exampleDoc, _id: docId}},
+          base: {[docId]: {...exampleDoc, _id: docId}},
+          previousRevs: {[docId]: 'txn0'},
+        }),
+        disableBatching: false,
+        batchedTransactionIds: ['txnOutgoing'],
+      }
+      const state = {...makeState([]), outgoing}
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(state, remote, events)
+      expect(newState.documentStates[docId]?.local).toBe(state.documentStates[docId]?.local)
+    })
+  })
+
   it('rebases local changes when no matching unverified revision is found', () => {
     // In this branch we simply let processActions rebase so that the local becomes the remote.
     const docId = getDraftId(DocumentId('doc1'))

package/src/document/reducers.ts

@@ -5,7 +5,7 @@ import {type DocumentHandle} from '../config/sanityConfig'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
-import {omitProperty} from '../utils/object'
+import {isDeepEqual, omitProperty} from '../utils/object'
 import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {type Action} from './actions'
 import {DOCUMENT_STATE_CLEAR_DELAY} from './documentConstants'
@@ -534,6 +534,34 @@ export function applyRemoteDocument(
   // matches the previous revision we expected, we can "fast-forward" and skip
   // rebasing local changes on top of this new base
   if (revisionToVerify && revisionToVerify.previousRev === previousRev) {
+    // even on a clean fast-forward, the server's result can differ from our
+    // optimistic prediction: a publish derives the published content from the
+    // server's copy of the draft, which may carry concurrent edits our
+    // prediction never saw. once nothing else is pending locally for this
+    // document (no applied transaction and no in-flight transaction, other
+    // than the one this event just confirmed, modifies it), converge `local`
+    // to the server's document. while local work that modifies this document
+    // is pending, keep the optimistic `local` so those changes stay visible;
+    // that work's own echo (or rebase) recomputes `local` later.
+    //
+    // "modifies" matters: pending work on other documents must not block
+    // convergence here (nothing would ever revisit this document's `local`),
+    // and a pending draft edit carries the published document in its working
+    // set without changing it, so a presence check would block published-doc
+    // convergence whenever a draft edit is pending. this is the same
+    // modified-test `transitionAppliedTransactionsToOutgoing` uses
+    const modifiesDocument = (transaction: AppliedTransaction) =>
+      transaction.working[documentId]?._rev !== transaction.previousRevs[documentId]
+    const nothingElsePending =
+      !prev.applied.some(modifiesDocument) &&
+      (!prev.outgoing ||
+        prev.outgoing.transactionId === revision ||
+        !modifiesDocument(prev.outgoing))
+    const local =
+      nothingElsePending && !isDeepEqual(prevDocState.local, document)
+        ? document
+        : prevDocState.local
+
     return {
       ...prev,
       documentStates: {
@@ -542,6 +570,7 @@ export function applyRemoteDocument(
           ...prevDocState,
           remote: document,
           remoteRev: revision,
+          local,
           unverifiedRevisions,
         },
       },
@@ -592,6 +621,12 @@ export function applyRemoteDocument(
     }
   }
 
+  // when the recompute lands on a value deep-equal to the current local
+  // (the common case for echoes of our own transactions), keep the previous
+  // reference so subscribers don't re-render for an identical value
+  const nextLocal = working[documentId]
+  const local = isDeepEqual(prevDocState.local, nextLocal) ? prevDocState.local : nextLocal
+
   return {
     ...prev,
     applied: nextApplied,
@@ -601,7 +636,7 @@ export function applyRemoteDocument(
         ...prevDocState,
         remote: document,
         remoteRev: revision,
-        local: working[documentId],
+        local,
         unverifiedRevisions,
       },
     },

package/src/document/sharedListener.test.ts

@@ -49,7 +49,8 @@ describe('createSharedListener', () => {
       '*',
       {},
       {
-        events: ['mutation', 'welcome', 'reconnect'],
+        events: ['mutation', 'welcome', 'welcomeback', 'reconnect', 'reset'],
+        enableResume: true,
         includeResult: false,
         includeAllVersions: true,
         tag: 'document-listener',

package/src/document/sharedListener.ts

@@ -16,6 +16,7 @@ import {
 import {getClientState} from '../client/clientStore'
 import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
+import {dedupeListenerEvents, groupTransactionEvents} from './listenerEventOperators'
 
 const API_VERSION = 'v2025-05-06'
 
@@ -41,7 +42,12 @@ export function createSharedListener(
         '*',
         {},
         {
-          events: ['mutation', 'welcome', 'reconnect'],
+          // with `enableResume`, a reconnect replays the events missed while
+          // offline (emitting `welcomeback`) instead of forcing a refetch of
+          // every subscribed document. when the backend cannot resume, it
+          // emits `welcome` or `reset`, both of which trigger a refetch
+          events: ['mutation', 'welcome', 'welcomeback', 'reconnect', 'reset'],
+          enableResume: true,
           includeResult: false,
           // the document store handles version documents, so we need to include all versions
           includeAllVersions: true,
@@ -53,6 +59,11 @@ export function createSharedListener(
         },
       ),
     ),
+    // resumed events are delivered at-least-once, so drop replayed duplicates
+    dedupeListenerEvents(),
+    // hold multi-document transactions (e.g. publish) until complete so
+    // per-document processing never observes half a transaction
+    groupTransactionEvents(),
     takeUntil(dispose$),
     share(),
   )