@sanity/sdk 2.16.0 → 2.18.0

package/src/document/processActions/edit.ts

@@ -4,14 +4,16 @@ 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,
+  preserveNumericOperations,
 } from './shared'
 
 export function handleEdit(
@@ -33,6 +35,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 +74,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 +94,23 @@ 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. otherwise, diff the
+  // snapshots but swap back any `inc`/`dec` the diff collapsed into a `set`,
+  // so concurrent increments accumulate instead of last-write-winning
+  const patches = action.preserveOperations
+    ? (action.patches ?? [])
+    : preserveNumericOperations(
+        baseBefore,
+        action.patches,
+        diffValue(baseBefore, baseAfter) as PatchOperations[],
+      )
 
   const workingMutations: Mutation[] = []
   if (!isReleasePerspective(action.perspective) && !working[draftId] && working[publishedId]) {
@@ -121,12 +138,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

@@ -1,4 +1,5 @@
 import {diffValue} from '@sanity/diff-patch'
+import {jsonMatch, stringifyPath} from '@sanity/json-match'
 import {type Mutation, type PatchOperations, type SanityDocument} from '@sanity/types'
 import {evaluateSync, type ExprNode} from 'groq-js'
 
@@ -57,6 +58,146 @@ 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'
+        }`,
+      })
+    }
+  }
+}
+
+/**
+ * Re-applies the operational intent of user-supplied `inc`/`dec` patches to a
+ * set of snapshot-diffed patches.
+ *
+ * The outgoing patches sent to Content Lake are re-derived by diffing the
+ * base document before and after the user's patches were applied. That diff
+ * collapses an `inc` into a `set` of the resulting number, which turns
+ * concurrent increments from different clients into last-write-wins. This
+ * helper finds diffed `set` operations that are exactly explained by the
+ * user's `inc`/`dec` operations and swaps them back, so the server applies
+ * the increment against whatever value is current at commit time.
+ *
+ * A `set` is only swapped when its value equals the base value plus the
+ * accumulated user deltas for that exact path; anything else (e.g. an `inc`
+ * combined with a `set` of the same field) keeps the diffed `set`.
+ *
+ * Content Lake fails the whole transaction when `inc`/`dec` targets a missing
+ * path (unlike `set`, which always succeeds). To avoid turning a concurrent
+ * field removal into a transaction revert, the emitted patch seeds the target
+ * with a `setIfMissing` of the base value; the server executes `setIfMissing`
+ * before `inc`/`dec` within a single patch, so a concurrently removed field
+ * degrades to the same result the diffed `set` would have produced. A path
+ * into a concurrently removed keyed array item can still fail the
+ * transaction (`setIfMissing` cannot create array items); the transaction is
+ * then reverted and reported, which is preferable to silently resurrecting
+ * the item.
+ */
+export function preserveNumericOperations(
+  baseBefore: SanityDocument | null | undefined,
+  userPatches: PatchOperations[] | undefined,
+  diffedPatches: PatchOperations[],
+): PatchOperations[] {
+  if (!baseBefore || !userPatches?.length) return diffedPatches
+
+  // accumulate the user's inc/dec deltas per concrete (stringified) path,
+  // tracking the expected final value by replaying the additions in order
+  const targets = new Map<string, {baseValue: number; expectedValue: number; delta: number}>()
+  for (const patch of userPatches) {
+    for (const [op, sign] of [
+      ['inc', 1],
+      ['dec', -1],
+    ] as const) {
+      const record = patch[op]
+      if (!record) continue
+      for (const [pathExpression, amount] of Object.entries(record)) {
+        if (typeof amount !== 'number') continue
+        for (const match of jsonMatch(baseBefore, pathExpression)) {
+          const path = stringifyPath(match.path)
+          const existing = targets.get(path)
+          if (existing) {
+            existing.expectedValue += sign * amount
+            existing.delta += sign * amount
+          } else if (typeof match.value === 'number') {
+            targets.set(path, {
+              baseValue: match.value,
+              expectedValue: match.value + sign * amount,
+              delta: sign * amount,
+            })
+          }
+        }
+      }
+    }
+  }
+  if (!targets.size) return diffedPatches
+
+  const preserved = new Map<string, {delta: number; baseValue: number}>()
+  const next = diffedPatches.flatMap((patch) => {
+    if (!patch.set) return [patch]
+
+    const keptSet: Record<string, unknown> = {}
+    for (const [path, value] of Object.entries(patch.set)) {
+      const target = targets.get(path)
+      if (target && typeof value === 'number' && value === target.expectedValue) {
+        preserved.set(path, {delta: target.delta, baseValue: target.baseValue})
+      } else {
+        keptSet[path] = value
+      }
+    }
+
+    if (Object.keys(keptSet).length === Object.keys(patch.set).length) return [patch]
+    const {set: _set, ...rest} = patch
+    const withKept = Object.keys(keptSet).length ? {...rest, set: keptSet} : rest
+    return Object.keys(withKept).length ? [withKept] : []
+  })
+
+  if (!preserved.size) return next
+
+  const setIfMissing: Record<string, unknown> = {}
+  const inc: Record<string, number> = {}
+  const dec: Record<string, number> = {}
+  for (const [path, {delta, baseValue}] of preserved) {
+    setIfMissing[path] = baseValue
+    if (delta >= 0) inc[path] = delta
+    else dec[path] = -delta
+  }
+  return [
+    ...next,
+    {
+      setIfMissing,
+      ...(Object.keys(inc).length && {inc}),
+      ...(Object.keys(dec).length && {dec}),
+    },
+  ]
+}
+
 interface ApplySingleDocPatchOptions {
   base: DocumentSet
   working: DocumentSet
@@ -75,6 +216,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 +260,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 +275,23 @@ 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[])
+    : preserveNumericOperations(
+        baseBefore,
+        patches,
+        diffValue(baseBefore, baseAfter) as PatchOperations[],
+      )
 
   const workingBefore = working[documentId] as SanityDocument
   if (!checkGrant(grants.update, workingBefore, identity)) {
@@ -140,12 +302,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

@@ -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')
@@ -527,6 +711,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')