@sanity/sdk 2.16.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -78,11 +78,11 @@
     "typescript": "^6.0.3",
     "vite": "^8.1.4",
     "vitest": "^4.1.10",
+    "@repo/config-test": "0.0.1",
     "@repo/config-eslint": "0.0.0",
     "@repo/package.bundle": "3.82.0",
-    "@repo/package.config": "0.0.1",
     "@repo/tsconfig": "0.0.1",
-    "@repo/config-test": "0.0.1"
+    "@repo/package.config": "0.0.1"
   },
   "browserslist": "extends @sanity/browserslist-config",
   "scripts": {

package/src/_exports/index.ts

@@ -129,6 +129,7 @@ export {
   type DocumentAction,
   editDocument,
   type EditDocumentAction,
+  type EditDocumentOptions,
   editRelease,
   type EditReleaseAction,
   publishDocument,
@@ -167,6 +168,7 @@ export {
   type DocumentEditedEvent,
   type DocumentEvent,
   type DocumentPublishedEvent,
+  type DocumentRemotePatchesEvent,
   type DocumentTransactionSubmissionResult,
   type DocumentUnpublishedEvent,
   type TransactionAcceptedEvent,

package/src/document/actions.ts

@@ -68,6 +68,21 @@ export interface EditDocumentAction<
 > extends DocumentHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.edit'
   patches?: PatchOperations[]
+  /**
+   * When `true`, the given `patches` are forwarded verbatim to the server and
+   * applied as-is locally, instead of being re-derived by diffing document
+   * snapshots. This preserves the operational intent of the patches (e.g.
+   * keyed array inserts/unsets), which lets concurrent edits from other
+   * clients interleave coherently instead of being overwritten by
+   * position-based patches computed from a stale snapshot.
+   *
+   * Use this when the patches were produced by an editor that tracks its own
+   * operations (e.g. a collaborative text editor). During a rebase onto a
+   * changed remote document, preserved patches are re-applied operationally;
+   * if a patch can no longer apply, the transaction is skipped and reported
+   * as a `rebase-error` document event.
+   */
+  preserveOperations?: boolean
 }
 
 /**
@@ -201,12 +216,25 @@ function convertSanityMutatePatch(
   })
 }
 
+/**
+ * Options for creating an `EditDocumentAction`.
+ * @beta
+ */
+export interface EditDocumentOptions {
+  /**
+   * Forward the given patches verbatim instead of re-deriving them by
+   * diffing document snapshots. See {@link EditDocumentAction.preserveOperations}.
+   */
+  preserveOperations?: boolean
+}
+
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  * Accepts patches in either the standard `PatchOperations` format or as a `SanityMutatePatchMutation` from `@sanity/mutate`.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param sanityMutatePatch - A patch mutation object from `@sanity/mutate`.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -217,12 +245,14 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   sanityMutatePatch: SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - A single patch operation or an array of patch operations.
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -233,6 +263,7 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[],
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId>
 /**
  * Creates an `EditDocumentAction` object with patches for modifying a document.
@@ -240,6 +271,7 @@ export function editDocument<
  *
  * @param doc - A handle uniquely identifying the document to be edited.
  * @param patches - Patches in various formats (`PatchOperations`, `PatchOperations[]`, or `SanityMutatePatchMutation`).
+ * @param options - Options controlling how the patches are processed.
  * @returns An `EditDocumentAction` object ready for dispatch.
  */
 export function editDocument<
@@ -249,8 +281,10 @@ export function editDocument<
 >(
   doc: DocumentHandle<TDocumentType, TDataset, TProjectId>,
   patches?: PatchOperations | PatchOperations[] | SanityMutatePatchMutation,
+  options?: EditDocumentOptions,
 ): EditDocumentAction<TDocumentType, TDataset, TProjectId> {
   const effectiveDocumentId = getEffectiveDocumentId(doc)
+  const preserveOperations = options?.preserveOperations && {preserveOperations: true as const}
 
   if (isSanityMutatePatch(patches)) {
     const converted = convertSanityMutatePatch(patches) ?? []
@@ -259,6 +293,7 @@ export function editDocument<
       type: 'document.edit',
       documentId: effectiveDocumentId,
       patches: converted,
+      ...preserveOperations,
     }
   }
 
@@ -267,6 +302,7 @@ export function editDocument<
     type: 'document.edit',
     documentId: effectiveDocumentId,
     ...(patches && {patches: Array.isArray(patches) ? patches : [patches]}),
+    ...preserveOperations,
   }
 }
 

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