@sanity/sdk 2.16.0 → 2.17.0

package/src/document/processActions.test.ts

@@ -527,6 +527,151 @@ describe('processActions', () => {
     })
   })
 
+  describe('document.edit with preserveOperations', () => {
+    const createKeyedDoc = (): SanityDocument => ({
+      _id: 'drafts.doc1',
+      _type: 'article',
+      _createdAt: '2025-01-01T00:00:00.000Z',
+      _updatedAt: '2025-01-01T00:00:00.000Z',
+      _rev: 'initial',
+      items: [
+        {_key: 'a', value: 'first'},
+        {_key: 'b', value: 'second'},
+      ],
+    })
+
+    it('forwards the given patches verbatim instead of re-diffing', () => {
+      const draft = createKeyedDoc()
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const patches = [
+        {insert: {after: 'items[_key=="a"]', items: [{_key: 'c', value: 'in between'}]}},
+      ]
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches,
+          preserveOperations: true,
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      // the outgoing action carries the caller's keyed patch untouched
+      expect(result.outgoingActions).toEqual([
+        {
+          actionType: 'sanity.action.document.edit',
+          draftId: 'drafts.doc1',
+          publishedId: 'doc1',
+          patch: patches[0],
+        },
+      ])
+
+      // and it still applies to the local working copy
+      expect(result.working['drafts.doc1']?.['items']).toEqual([
+        {_key: 'a', value: 'first'},
+        {_key: 'c', value: 'in between'},
+        {_key: 'b', value: 'second'},
+      ])
+    })
+
+    it('applies keyed unsets and sets to the local working copy', () => {
+      const draft = createKeyedDoc()
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          patches: [
+            {unset: ['items[_key=="a"]']},
+            {set: {'items[_key=="b"].value': 'updated second'}},
+          ],
+          preserveOperations: true,
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      expect(result.working['drafts.doc1']?.['items']).toEqual([
+        {_key: 'b', value: 'updated second'},
+      ])
+      expect(result.outgoingActions.map((action) => 'patch' in action && action.patch)).toEqual([
+        {unset: ['items[_key=="a"]']},
+        {set: {'items[_key=="b"].value': 'updated second'}},
+      ])
+    })
+
+    it('surfaces patch application failures as ActionError', () => {
+      const draft = {...createKeyedDoc(), count: 5}
+      const base: DocumentSet = {'drafts.doc1': draft}
+      const working: DocumentSet = {'drafts.doc1': draft}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          documentType: 'article',
+          type: 'document.edit',
+          // diff-match-patch on a non-string value cannot apply
+          patches: [{diffMatchPatch: {count: '@@ -1,3 +1,3 @@\n-foo\n+bar\n'}}],
+          preserveOperations: true,
+        },
+      ]
+      expect(() =>
+        processActions({actions, transactionId, base, working, timestamp, grants: defaultGrants}),
+      ).toThrow(ActionError)
+      expect(() =>
+        processActions({actions, transactionId, base, working, timestamp, grants: defaultGrants}),
+      ).toThrow(/Failed to apply patches to the base document/)
+    })
+
+    it('forwards patches verbatim through the liveEdit mutation path', () => {
+      const liveDoc = {...createKeyedDoc(), _id: 'live-doc'}
+      const base: DocumentSet = {'live-doc': liveDoc}
+      const working: DocumentSet = {'live-doc': liveDoc}
+      const patches = [{insert: {before: 'items[_key=="a"]', items: [{_key: 'z', value: 'start'}]}}]
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'live-doc',
+          documentType: 'liveArticle',
+          type: 'document.edit',
+          liveEdit: true,
+          patches,
+          preserveOperations: true,
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      expect(result.outgoingMutations).toEqual([{patch: {id: 'live-doc', ...patches[0]}}])
+      expect(result.working['live-doc']?.['items']).toEqual([
+        {_key: 'z', value: 'start'},
+        {_key: 'a', value: 'first'},
+        {_key: 'b', value: 'second'},
+      ])
+    })
+  })
+
   describe('document.publish', () => {
     it('should publish a draft document', () => {
       const draft = createDoc('drafts.doc1', 'Draft Title', '1')

package/src/document/reducers.test.ts

@@ -497,6 +497,9 @@ describe('transitionAppliedTransactionsToOutgoing', () => {
     expect(docState?.unverifiedRevisions).toBeDefined()
     expect(docState?.unverifiedRevisions?.['txn7']).toBeDefined()
     expect(docState?.unverifiedRevisions?.['txn7']?.previousRev).toEqual('rev1')
+    // the transaction ID is also tracked durably for remote-patches origin
+    // labeling, surviving unverified-revision pruning
+    expect(docState?.recentOwnTransactionIds).toEqual(['txn7'])
   })
 })
 
@@ -794,6 +797,399 @@ describe('applyRemoteDocument', () => {
     expect(newDocState?.remote).toEqual(remote.document)
     expect(newDocState?.remoteRev).toBe('currentRev')
   })
+
+  describe('remote-patches events', () => {
+    const docId = getDraftId(DocumentId('doc1'))
+
+    function createInitialState(
+      unverifiedRevisions: NonNullable<
+        SyncTransactionState['documentStates'][string]
+      >['unverifiedRevisions'] = {},
+      recentOwnTransactionIds?: string[],
+    ): SyncTransactionState {
+      return {
+        queued: [],
+        applied: [],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: {...exampleDoc, _id: docId, foo: 'old'},
+            remote: {...exampleDoc, _id: docId, foo: 'old'},
+            unverifiedRevisions,
+            ...(recentOwnTransactionIds && {recentOwnTransactionIds}),
+          },
+        },
+      }
+    }
+
+    it('emits a remote-patches event with origin "remote" for foreign transactions', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnForeign',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:12:00.000Z',
+        mutations: [
+          {
+            patch: {
+              id: docId,
+              unset: ['blocks[_key=="a"].children[_key=="b"].marks[0]'],
+            },
+          },
+          {
+            patch: {
+              id: docId,
+              insert: {after: 'blocks[_key=="a"].markDefs[-1]', items: [{_key: 'link1'}]},
+            },
+          },
+        ],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+
+      expect(received).toEqual([
+        {
+          type: 'remote-patches',
+          documentId: docId,
+          transactionId: 'txnForeign',
+          previousRev: 'txn0',
+          timestamp: '2025-02-06T00:12:00.000Z',
+          origin: 'remote',
+          patches: [
+            {unset: ['blocks[_key=="a"].children[_key=="b"].marks[0]']},
+            {insert: {after: 'blocks[_key=="a"].markDefs[-1]', items: [{_key: 'link1'}]}},
+          ],
+        },
+      ])
+    })
+
+    it('emits origin "local" when the transaction is one of our own unverified revisions', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnOwn',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:13:00.000Z',
+        mutations: [{patch: {id: docId, set: {foo: 'new'}}}],
+      }
+
+      applyRemoteDocument(
+        createInitialState({
+          txnOwn: {
+            transactionId: 'txnOwn',
+            documentId: docId,
+            previousRev: 'txn0',
+            timestamp: '2025-02-06T00:13:00.000Z',
+          },
+        }),
+        remote,
+        events,
+      )
+
+      expect(received).toEqual([
+        {
+          type: 'remote-patches',
+          documentId: docId,
+          transactionId: 'txnOwn',
+          previousRev: 'txn0',
+          timestamp: '2025-02-06T00:13:00.000Z',
+          origin: 'local',
+          patches: [{set: {foo: 'new'}}],
+        },
+      ])
+    })
+
+    it('does not emit for sync events', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'sync',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'revSync',
+        timestamp: '2025-02-06T00:14:00.000Z',
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+      expect(received).toEqual([])
+    })
+
+    it('does not emit when the mutations contain no patches', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnCreate',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:15:00.000Z',
+        mutations: [{createOrReplace: {...exampleDoc, _id: docId, foo: 'new'}}],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+      expect(received).toEqual([])
+    })
+
+    it('excludes patches addressed to other documents in the same transaction', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnMulti',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:20:00.000Z',
+        mutations: [
+          {patch: {id: docId, set: {foo: 'new'}}},
+          {patch: {id: 'some-other-doc', set: {foo: 'other'}}},
+          {patch: {query: '*[_type == "author"]', set: {foo: 'queried'}}},
+        ],
+      }
+
+      applyRemoteDocument(createInitialState(), remote, events)
+
+      expect(received).toHaveLength(1)
+      expect((received[0] as {patches: unknown}).patches).toEqual([{set: {foo: 'new'}}])
+    })
+
+    it('labels origin "local" via recentOwnTransactionIds when the unverified revision was pruned', () => {
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: {...exampleDoc, _id: docId, foo: 'new'},
+        revision: 'txnPruned',
+        previousRev: 'txn0',
+        timestamp: '2025-02-06T00:21:00.000Z',
+        mutations: [{patch: {id: docId, set: {foo: 'new'}}}],
+      }
+
+      // a sync event racing the listener echo pruned the unverified revision,
+      // but the transaction ID is still tracked as one of our own
+      applyRemoteDocument(createInitialState({}, ['txnPruned']), remote, events)
+
+      expect(received).toHaveLength(1)
+      expect(received[0]).toMatchObject({
+        type: 'remote-patches',
+        transactionId: 'txnPruned',
+        origin: 'local',
+      })
+    })
+  })
+
+  describe('rebase with preserved operations', () => {
+    it('skips a preserved-operations transaction that fails to re-apply and emits rebase-error', () => {
+      const docId = getDraftId(DocumentId('doc1'))
+      const originalDoc: SanityDocument = {
+        ...exampleDoc,
+        _id: docId,
+        _rev: 'rev1',
+        title: 'The quick brown fox',
+      }
+      const locallyEditedDoc: SanityDocument = {
+        ...originalDoc,
+        title: 'The quick brown cat',
+        _rev: 'txnLocal',
+      }
+
+      const appliedTransaction: AppliedTransaction = {
+        transactionId: 'txnLocal',
+        actions: [
+          {
+            type: 'document.edit',
+            documentId: 'doc1',
+            documentType: 'author',
+            patches: [{diffMatchPatch: {title: '@@ -13,7 +13,7 @@\n own \n-fox\n+cat\n'}}],
+            preserveOperations: true,
+          },
+        ],
+        previous: {[docId]: originalDoc},
+        base: {[docId]: originalDoc},
+        working: {[docId]: locallyEditedDoc},
+        previousRevs: {[docId]: 'rev1'},
+        timestamp: '2025-02-06T00:16:00.000Z',
+        outgoingActions: [],
+        outgoingMutations: [],
+      }
+
+      const initialState: SyncTransactionState = {
+        queued: [],
+        applied: [appliedTransaction],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: locallyEditedDoc,
+            remote: originalDoc,
+            unverifiedRevisions: {},
+          },
+        },
+      }
+
+      // a foreign transaction replaced the title with a non-string, so our
+      // diffMatchPatch can no longer re-apply during the rebase
+      const remoteDoc: SanityDocument = {
+        ...originalDoc,
+        title: 42 as unknown as string,
+        _rev: 'txnForeign',
+      }
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: remoteDoc,
+        revision: 'txnForeign',
+        previousRev: 'rev1',
+        timestamp: '2025-02-06T00:17:00.000Z',
+        mutations: [{patch: {id: docId, set: {title: 42}}}],
+      }
+
+      const events = new Subject<DocumentEvent>()
+      const received: DocumentEvent[] = []
+      events.subscribe((e) => received.push(e))
+
+      const newState = applyRemoteDocument(initialState, remote, events)
+
+      const rebaseErrors = received.filter((e) => e.type === 'rebase-error')
+      expect(rebaseErrors).toHaveLength(1)
+      expect(rebaseErrors[0]).toMatchObject({
+        type: 'rebase-error',
+        transactionId: 'txnLocal',
+        documentId: 'doc1',
+        message: expect.stringMatching(/Failed to apply patches to the working document/),
+      })
+
+      // the failing transaction is dropped and local converges to remote
+      expect(newState.applied).toEqual([])
+      expect(newState.documentStates[docId]?.local).toEqual(remoteDoc)
+      expect(newState.documentStates[docId]?.remote).toEqual(remoteDoc)
+    })
+
+    it('re-applies preserved keyed patches onto a diverged remote document', () => {
+      const docId = getDraftId(DocumentId('doc1'))
+      const originalDoc: SanityDocument = {
+        ...exampleDoc,
+        _id: docId,
+        _rev: 'rev1',
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'b', value: 'second'},
+        ],
+      }
+      const locallyEditedDoc: SanityDocument = {
+        ...originalDoc,
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'c', value: 'in between'},
+          {_key: 'b', value: 'second'},
+        ],
+        _rev: 'txnLocal',
+      }
+
+      const appliedTransaction: AppliedTransaction = {
+        transactionId: 'txnLocal',
+        actions: [
+          {
+            type: 'document.edit',
+            documentId: 'doc1',
+            documentType: 'author',
+            patches: [
+              {insert: {after: 'items[_key=="a"]', items: [{_key: 'c', value: 'in between'}]}},
+            ],
+            preserveOperations: true,
+          },
+        ],
+        previous: {[docId]: originalDoc},
+        base: {[docId]: originalDoc},
+        working: {[docId]: locallyEditedDoc},
+        previousRevs: {[docId]: 'rev1'},
+        timestamp: '2025-02-06T00:18:00.000Z',
+        outgoingActions: [],
+        outgoingMutations: [],
+      }
+
+      const initialState: SyncTransactionState = {
+        queued: [],
+        applied: [appliedTransaction],
+        outgoing: undefined,
+        grants,
+        documentStates: {
+          [docId]: {
+            id: docId,
+            subscriptions: ['sub1'],
+            local: locallyEditedDoc,
+            remote: originalDoc,
+            unverifiedRevisions: {},
+          },
+        },
+      }
+
+      // a foreign transaction appended a new item concurrently
+      const remoteDoc: SanityDocument = {
+        ...originalDoc,
+        items: [
+          {_key: 'a', value: 'first'},
+          {_key: 'b', value: 'second'},
+          {_key: 'd', value: 'appended remotely'},
+        ],
+        _rev: 'txnForeign',
+      }
+      const remote: RemoteDocument = {
+        type: 'mutation',
+        documentId: docId,
+        document: remoteDoc,
+        revision: 'txnForeign',
+        previousRev: 'rev1',
+        timestamp: '2025-02-06T00:19:00.000Z',
+        mutations: [
+          {
+            patch: {
+              id: docId,
+              insert: {after: 'items[-1]', items: [{_key: 'd', value: 'appended remotely'}]},
+            },
+          },
+        ],
+      }
+
+      const events = new Subject<DocumentEvent>()
+      const newState = applyRemoteDocument(initialState, remote, events)
+
+      // both edits survive: our keyed insert re-anchors after item "a" while
+      // the remote append is preserved
+      expect(newState.documentStates[docId]?.local?.['items']).toEqual([
+        {_key: 'a', value: 'first'},
+        {_key: 'c', value: 'in between'},
+        {_key: 'b', value: 'second'},
+        {_key: 'd', value: 'appended remotely'},
+      ])
+      expect(newState.applied).toHaveLength(1)
+    })
+  })
 })
 
 describe('addSubscriptionIdToDocument', () => {

package/src/document/reducers.ts

@@ -17,6 +17,13 @@ import {type DocumentSet} from './processMutations'
 
 const EMPTY_REVISIONS: NonNullable<Required<DocumentState['unverifiedRevisions']>> = {}
 
+/**
+ * How many of this client's own transaction IDs to remember per document for
+ * `remote-patches` origin labeling. Sized to comfortably outlast the window
+ * between submitting a transaction and observing its listener echo.
+ */
+const MAX_RECENT_OWN_TRANSACTION_IDS = 50
+
 export type SyncTransactionState = Pick<
   DocumentStoreState,
   'queued' | 'applied' | 'documentStates' | 'outgoing' | 'grants' | 'identity'
@@ -364,6 +371,15 @@ export function transitionAppliedTransactionsToOutgoing(
             // add unverified revision
             [transactionId]: {documentId, previousRev, transactionId, timestamp},
           },
+          // also track the transaction ID durably (unverified revisions can be
+          // pruned by sync events before the listener echo arrives) so
+          // `remote-patches` events label our own transactions correctly
+          recentOwnTransactionIds: [
+            ...(documentState.recentOwnTransactionIds ?? []).slice(
+              -(MAX_RECENT_OWN_TRANSACTION_IDS - 1),
+            ),
+            transactionId,
+          ],
         }
 
         return acc
@@ -433,9 +449,29 @@ export function revertOutgoingTransaction(prev: SyncTransactionState): SyncTrans
   }
 }
 
+/**
+ * Extracts the patch operations addressed to the given document from a set of
+ * raw listener mutations, stripping the mutation-level `id` addressing so the
+ * patches are rooted at the document. A transaction can carry mutations for
+ * other documents, so anything not explicitly id-addressed to this document
+ * (including query-addressed patches) is dropped.
+ */
+function extractPatchOperations(
+  mutations: Mutation[] | undefined,
+  documentId: string,
+): PatchOperations[] {
+  if (!mutations) return []
+  return mutations.flatMap((mutation) => {
+    if (!('patch' in mutation) || !mutation.patch) return []
+    const {id, ...operations} = mutation.patch as PatchOperations & {id?: string}
+    if (id !== documentId) return []
+    return [operations]
+  })
+}
+
 export function applyRemoteDocument(
   prev: SyncTransactionState,
-  {document, documentId, previousRev, revision, timestamp, type}: RemoteDocument,
+  {document, documentId, previousRev, revision, timestamp, type, mutations}: RemoteDocument,
   events: DocumentStoreState['events'],
 ): SyncTransactionState {
   if (!prev.grants) return prev
@@ -455,6 +491,31 @@ export function applyRemoteDocument(
     unverifiedRevisions = omitProperty(prevUnverifiedRevisions, revision)
   }
 
+  // surface the operational patches from this transaction before they are
+  // collapsed into the whole-document snapshot below. consumers that keep
+  // their own state (e.g. collaborative text editors) rely on these to apply
+  // remote changes without re-diffing document snapshots
+  if (type === 'mutation' && revision) {
+    const patches = extractPatchOperations(mutations, documentId)
+    if (patches.length) {
+      // `unverifiedRevisions` alone isn't a reliable origin marker: a sync
+      // event can prune an in-flight transaction's entry before its listener
+      // echo arrives. `recentOwnTransactionIds` survives that race
+      const isOwnTransaction =
+        Boolean(revisionToVerify) ||
+        (prevDocState.recentOwnTransactionIds?.includes(revision) ?? false)
+      events.next({
+        type: 'remote-patches',
+        documentId,
+        transactionId: revision,
+        previousRev,
+        timestamp,
+        patches,
+        origin: isOwnTransaction ? 'local' : 'remote',
+      })
+    }
+  }
+
   // if this remote document is from a `'sync'` event (meaning that the whole
   // thing was just fetched and not re-created from mutations)
   if (type === 'sync') {