@sanity/sdk 2.15.0 → 2.17.0

package/src/document/documentStore.test.ts

@@ -41,7 +41,11 @@ import {
   resolvePermissions,
   subscribeDocumentEvents,
 } from './documentStore'
-import {type ActionErrorEvent, type TransactionRevertedEvent} from './events'
+import {
+  type ActionErrorEvent,
+  type DocumentRemotePatchesEvent,
+  type TransactionRevertedEvent,
+} from './events'
 import {DEFAULT_MAX_BUFFER_SIZE} from './listen'
 import {type DatasetAcl} from './permissions'
 import {type DocumentSet, processMutations} from './processMutations'
@@ -281,6 +285,66 @@ it('propagates changes between two instances', async () => {
   state2Unsubscribe()
 })
 
+it('emits remote-patches events distinguishing own and foreign transactions', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-remote-patches', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
+
+  const state1Unsubscribe = state1.subscribe()
+  const state2Unsubscribe = state2.subscribe()
+
+  await applyDocumentActions(instance1, {actions: [createDocument(doc)], resource: source1}).then(
+    (r) => r.submitted(),
+  )
+
+  const events1: DocumentRemotePatchesEvent[] = []
+  const events2: DocumentRemotePatchesEvent[] = []
+  const unsubscribeEvents1 = subscribeDocumentEvents(instance1, {
+    resource: source1,
+    eventHandler: (e) => {
+      if (e.type === 'remote-patches') events1.push(e)
+    },
+  })
+  const unsubscribeEvents2 = subscribeDocumentEvents(instance2, {
+    resource: source2,
+    eventHandler: (e) => {
+      if (e.type === 'remote-patches') events2.push(e)
+    },
+  })
+
+  // edit from instance2: an own transaction for instance2, a foreign one for instance1
+  const result = await applyDocumentActions(instance2, {
+    actions: [editDocument(doc, {set: {title: 'Hello world!'}})],
+    resource: source2,
+  }).then((r) => r.submitted())
+
+  const draftId = getDraftId(DocumentId(doc.documentId))
+
+  expect(events1).toHaveLength(1)
+  expect(events1[0]).toMatchObject({
+    type: 'remote-patches',
+    documentId: draftId,
+    transactionId: result.transactionId,
+    origin: 'remote',
+  })
+  expect(events1[0].patches).toEqual(
+    expect.arrayContaining([{set: expect.objectContaining({title: 'Hello world!'})}]),
+  )
+
+  expect(events2).toHaveLength(1)
+  expect(events2[0]).toMatchObject({
+    type: 'remote-patches',
+    documentId: draftId,
+    transactionId: result.transactionId,
+    origin: 'local',
+  })
+
+  unsubscribeEvents1()
+  unsubscribeEvents2()
+  state1Unsubscribe()
+  state2Unsubscribe()
+})
+
 it('handles concurrent edits and resolves conflicts', async () => {
   const doc = createDocumentHandle({documentId: 'doc-concurrent', documentType: 'article'})
   const state1 = getDocumentState(instance1, doc)
@@ -325,6 +389,73 @@ it('handles concurrent edits and resolves conflicts', async () => {
   oneOffInstance.dispose()
 })
 
+it('interleaves concurrent keyed-array edits when operations are preserved', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-preserve-ops', documentType: 'article'})
+  const state1 = getDocumentState(instance1, doc)
+  const state2 = getDocumentState(instance2, doc)
+
+  const state1Unsubscribe = state1.subscribe()
+  const state2Unsubscribe = state2.subscribe()
+
+  const oneOffInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  await applyDocumentActions(oneOffInstance, {
+    actions: [
+      createDocument(doc),
+      editDocument(doc, {
+        set: {
+          items: [
+            {_key: 'a', value: 'first'},
+            {_key: 'b', value: 'second'},
+          ],
+        },
+      }),
+    ],
+    resource,
+  }).then((r) => r.submitted())
+
+  // both instances insert into the same keyed array simultaneously, each
+  // preserving their operational patches instead of re-diffing snapshots
+  const p1 = applyDocumentActions(instance1, {
+    actions: [
+      editDocument(
+        doc,
+        {insert: {after: 'items[_key=="a"]', items: [{_key: 'c', value: 'from instance1'}]}},
+        {preserveOperations: true},
+      ),
+    ],
+    resource: source1,
+  }).then((r) => r.submitted())
+  const p2 = applyDocumentActions(instance2, {
+    actions: [
+      editDocument(
+        doc,
+        {insert: {after: 'items[_key=="b"]', items: [{_key: 'd', value: 'from instance2'}]}},
+        {preserveOperations: true},
+      ),
+    ],
+    resource: source2,
+  }).then((r) => r.submitted())
+
+  await Promise.allSettled([p1, p2])
+
+  const finalDoc1 = state1.getCurrent()
+  const finalDoc2 = state2.getCurrent()
+
+  // neither edit overwrote the other: both keyed inserts landed and both
+  // instances converged on the same interleaved result
+  expect(finalDoc1?.['items']).toEqual(finalDoc2?.['items'])
+  expect(finalDoc1?.['items']).toEqual([
+    {_key: 'a', value: 'first'},
+    {_key: 'c', value: 'from instance1'},
+    {_key: 'b', value: 'second'},
+    {_key: 'd', value: 'from instance2'},
+  ])
+
+  state1Unsubscribe()
+  state2Unsubscribe()
+  oneOffInstance.dispose()
+})
+
 it('unpublishes and discards a document', async () => {
   const documentId = DocumentId('doc-pub-unpub')
   const doc = createDocumentHandle({documentId, documentType: 'article'})

package/src/document/documentStore.ts

@@ -133,6 +133,14 @@ export interface DocumentState {
    * local transactions on top of this new remote.
    */
   unverifiedRevisions?: {[TTransactionId in string]?: UnverifiedDocumentRevision}
+  /**
+   * transaction IDs recently submitted by this client for this document,
+   * newest last. used to label `remote-patches` events with the correct
+   * `origin` even after the corresponding `unverifiedRevisions` entry has
+   * been pruned (e.g. by a sync event that raced the listener echo). capped
+   * to the most recent entries.
+   */
+  recentOwnTransactionIds?: string[]
 }
 
 export const documentStore = defineStore<DocumentStoreState, BoundResourceKey>({

package/src/document/events.ts

@@ -1,4 +1,5 @@
 import {type MultipleMutationResult, type SanityClient} from '@sanity/client'
+import {type PatchOperations} from '@sanity/types'
 
 import {type DocumentAction, type ReleaseAction} from './actions'
 import {getReleaseDocumentId, isReleaseAction} from './processActions/releaseUtil'
@@ -21,6 +22,7 @@ export type DocumentEvent =
   | DocumentPublishedEvent
   | DocumentUnpublishedEvent
   | DocumentDiscardedEvent
+  | DocumentRemotePatchesEvent
 
 /**
  * @beta
@@ -119,6 +121,36 @@ export interface DocumentDiscardedEvent {
   outgoing: OutgoingTransaction
 }
 
+/**
+ * @beta
+ * Event emitted when patches for a document are observed through the listener.
+ *
+ * Unlike the whole-document snapshots the store keeps, these are the raw patch
+ * operations from the transaction that produced the change, preserving the
+ * operational intent of the edit (e.g. keyed array inserts/unsets). Consumers
+ * that maintain their own local state, like collaborative text editors, can
+ * apply these directly instead of diffing document snapshots.
+ *
+ * `origin` is `'local'` when the transaction was submitted by this document
+ * store instance (an own edit observed back through the listener) and
+ * `'remote'` when it came from another client.
+ */
+export interface DocumentRemotePatchesEvent {
+  type: 'remote-patches'
+  /** The ID of the document version the patches apply to (e.g. a draft ID). */
+  documentId: string
+  /** The transaction ID that carried these patches. */
+  transactionId: string
+  /** The revision the document was at before this transaction. */
+  previousRev?: string
+  /** The timestamp of the transaction. */
+  timestamp: string
+  /** The patch operations, rooted at the document. */
+  patches: PatchOperations[]
+  /** Whether the transaction originated from this client or another one. */
+  origin: 'local' | 'remote'
+}
+
 // Release actions that write a mutation to the local release doc map onto
 // the regular per-document events with `documentId = '_.releases.<releaseId>'`.
 // The other release actions (publish/schedule/unschedule/archive/unarchive)

package/src/document/listen.ts

@@ -30,6 +30,13 @@ export interface RemoteDocument {
   revision?: string
   previousRev?: string
   timestamp: string
+  /**
+   * The raw mutations from the listener event that produced this document.
+   * Only present for `'mutation'` events. These carry the operational intent
+   * of the remote change (e.g. keyed patches) before it is collapsed into a
+   * whole document snapshot.
+   */
+  mutations?: Mutation[]
 }
 
 export interface SyncEvent {
@@ -251,6 +258,7 @@ export const listen = (
         document: document ?? null,
         revision: transactionId,
         timestamp,
+        mutations: next.mutations as Mutation[],
         ...(previousRev && {previousRev}),
       }
     }),

package/src/document/processActions/edit.ts

@@ -4,13 +4,14 @@ import {type Mutation, type PatchOperations, type SanityDocument} from '@sanity/
 
 import {isReleasePerspective} from '../../releases/utils/isReleasePerspective'
 import {type EditDocumentAction} from '../actions'
-import {getId, processMutations} from '../processMutations'
+import {getId} from '../processMutations'
 import {
   ActionError,
   type ActionHandlerContext,
   type ActionHandlerResult,
   applySingleDocPatch,
   checkGrant,
+  createMutationApplier,
   PermissionActionError,
 } from './shared'
 
@@ -33,6 +34,7 @@ export function handleEdit(
       timestamp,
       grants,
       identity,
+      preserveOperations: action.preserveOperations,
     })
     // liveEdit documents use the mutation endpoint directly -- we don't send actions
     outgoingMutations.push(...result.workingMutations)
@@ -71,6 +73,13 @@ export function handleEdit(
     })
   }
 
+  const applyMutations = createMutationApplier({
+    documentId,
+    transactionId,
+    timestamp,
+    preserveOperations: action.preserveOperations,
+  })
+
   const baseMutations: Mutation[] = []
   // don't create a draft from the published version in a release perspective
   if (!isReleasePerspective(action.perspective) && !base[draftId] && base[publishedId]) {
@@ -84,16 +93,17 @@ export function handleEdit(
     baseMutations.push(...userPatches)
   }
 
-  base = processMutations({
-    documents: base,
-    transactionId,
-    mutations: baseMutations,
-    timestamp,
-  })
+  base = applyMutations(base, baseMutations, 'base')
   // this one will always be defined because a patch mutation will never
   // delete an input document
   const baseAfter = base[patchDocumentId] as SanityDocument
-  const patches = diffValue(baseBefore, baseAfter)
+  // when the caller asked us to preserve their operations, forward their
+  // patches verbatim instead of re-deriving them from a snapshot diff. this
+  // keeps keyed array operations addressable so concurrent edits from other
+  // clients interleave instead of being overwritten
+  const patches = action.preserveOperations
+    ? (action.patches ?? [])
+    : diffValue(baseBefore, baseAfter)
 
   const workingMutations: Mutation[] = []
   if (!isReleasePerspective(action.perspective) && !working[draftId] && working[publishedId]) {
@@ -121,12 +131,7 @@ export function handleEdit(
   }
   workingMutations.push(...patches.map((patch) => ({patch: {id: patchDocumentId, ...patch}})))
 
-  working = processMutations({
-    documents: working,
-    transactionId,
-    mutations: workingMutations,
-    timestamp,
-  })
+  working = applyMutations(working, workingMutations, 'working')
 
   outgoingMutations.push(...workingMutations)
   outgoingActions.push(

package/src/document/processActions/shared.ts

@@ -57,6 +57,41 @@ export class ActionError extends Error implements ActionErrorOptions {
 
 export class PermissionActionError extends ActionError {}
 
+/**
+ * Creates a `processMutations` wrapper that surfaces application failures as
+ * `ActionError`s when the caller asked to preserve their patch operations.
+ * With preserved operations, patches can legitimately fail to apply (e.g.
+ * re-applied onto a diverged document during a rebase), so wrapping lets a
+ * rebase skip the transaction instead of failing the store. Without
+ * `preserveOperations`, errors are rethrown untouched.
+ */
+export function createMutationApplier(options: {
+  documentId: string
+  transactionId: string
+  timestamp: string
+  preserveOperations: boolean | undefined
+}): (
+  documents: DocumentSet,
+  mutations: Mutation[],
+  documentSetName: 'base' | 'working',
+) => DocumentSet {
+  const {documentId, transactionId, timestamp, preserveOperations} = options
+  return (documents, mutations, documentSetName) => {
+    try {
+      return processMutations({documents, transactionId, mutations, timestamp})
+    } catch (error) {
+      if (!preserveOperations) throw error
+      throw new ActionError({
+        documentId,
+        transactionId,
+        message: `Failed to apply patches to the ${documentSetName} document: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      })
+    }
+  }
+}
+
 interface ApplySingleDocPatchOptions {
   base: DocumentSet
   working: DocumentSet
@@ -75,6 +110,13 @@ interface ApplySingleDocPatchOptions {
    * Error message thrown when the working document fails the `update` grant.
    */
   permissionMessage?: string
+  /**
+   * When `true`, the given patches are used verbatim instead of being
+   * re-derived by diffing the base document before and after application.
+   * Patch application failures are surfaced as `ActionError`s so a rebase
+   * can skip the transaction instead of failing the store.
+   */
+  preserveOperations?: boolean
 }
 
 interface ApplySingleDocPatchResult {
@@ -112,6 +154,7 @@ export function applySingleDocPatch({
   identity,
   notFoundMessage = 'Cannot edit document because it does not exist.',
   permissionMessage = `You do not have permission to edit document "${documentId}".`,
+  preserveOperations,
 }: ApplySingleDocPatchOptions): ApplySingleDocPatchResult {
   let base = initialBase
   let working = initialWorking
@@ -126,10 +169,19 @@ export function applySingleDocPatch({
     throw new ActionError({documentId, transactionId, message: notFoundMessage})
   }
 
+  const applyMutations = createMutationApplier({
+    documentId,
+    transactionId,
+    timestamp,
+    preserveOperations,
+  })
+
   const baseBefore = base[documentId]
-  base = processMutations({documents: base, transactionId, mutations: userPatches, timestamp})
+  base = applyMutations(base, userPatches, 'base')
   const baseAfter = base[documentId]
-  const diffedPatches = diffValue(baseBefore, baseAfter) as PatchOperations[]
+  const diffedPatches = preserveOperations
+    ? (patches as PatchOperations[])
+    : (diffValue(baseBefore, baseAfter) as PatchOperations[])
 
   const workingBefore = working[documentId] as SanityDocument
   if (!checkGrant(grants.update, workingBefore, identity)) {
@@ -140,12 +192,7 @@ export function applySingleDocPatch({
     patch: {id: documentId, ...patch},
   }))
 
-  working = processMutations({
-    documents: working,
-    transactionId,
-    mutations: workingMutations,
-    timestamp,
-  })
+  working = applyMutations(working, workingMutations, 'working')
 
   return {base, working, diffedPatches, workingMutations}
 }

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