@sanity/sdk 2.16.0 → 2.18.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'})
@@ -775,6 +906,17 @@ it('fetches dataset ACL and updates grants in the document store state', async (
   })
 })
 
+it('does not send credentials with the dataset ACL request', async () => {
+  const doc = createDocumentHandle({documentId: crypto.randomUUID(), documentType: 'article'})
+  await resolvePermissions(instance, {actions: [createDocument(doc)]})
+
+  const aclCall = vi
+    .mocked(client.request)
+    .mock.calls.find(([options]) => options.uri?.endsWith('/acl'))
+  expect(aclCall).toBeDefined()
+  expect(aclCall![0]).not.toHaveProperty('withCredentials')
+})
+
 it('fetches ACL for MediaLibraryResource', async () => {
   const mediaLibraryInstance = createSanityInstance({
     projectId: 'p',

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>({
@@ -557,7 +565,6 @@ const subscribeToClientAndFetchDatasetAcl = ({
         client.observable.request<DatasetAcl>({
           uri,
           tag: 'acl.get',
-          withCredentials: true,
         }),
       ),
       tap((datasetAcl) => state.set('setGrants', {grants: createGrantsLookup(datasetAcl)})),

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.test.ts

@@ -205,4 +205,60 @@ describe('sortListenerEvents operator', () => {
     const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
     expect(events).toEqual([other])
   })
+
+  it('should discard replayed events already reflected in the base', async () => {
+    // The snapshot is at rev2; a resumed listener replays the event that
+    // produced rev2. It should be discarded instead of clogging the buffer.
+    const sync = createSyncEvent('rev2')
+    const replayed = createMutationEvent({
+      id: 'replayed',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const source$ = of(sync, replayed)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync])
+  })
+
+  it('should discard the replayed part of a chain and apply the rest', async () => {
+    // The snapshot is at rev2; the listener replays rev1->rev2 followed by a
+    // genuinely new rev2->rev3. Only the new event should be emitted.
+    const sync = createSyncEvent('rev2')
+    const replayed = createMutationEvent({
+      id: 'replayed',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const fresh = createMutationEvent({
+      id: 'fresh',
+      previousRev: 'rev2',
+      resultRev: 'rev3',
+    })
+    const source$ = of(sync, replayed, fresh)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync, fresh])
+  })
+
+  it('should discard a multi-event replayed chain that leads up to the base', async () => {
+    const sync = createSyncEvent('rev3')
+    // two replayed events that together lead up to the base revision
+    const replayedA = createMutationEvent({
+      id: 'replayedA',
+      previousRev: 'rev1',
+      resultRev: 'rev2',
+    })
+    const replayedB = createMutationEvent({
+      id: 'replayedB',
+      previousRev: 'rev2',
+      resultRev: 'rev3',
+    })
+    const fresh = createMutationEvent({
+      id: 'fresh',
+      previousRev: 'rev3',
+      resultRev: 'rev4',
+    })
+    const source$ = of(sync, replayedA, replayedB, fresh)
+    const events = await lastValueFrom(source$.pipe(sortListenerEvents(), toArray()))
+    expect(events).toEqual([sync, fresh])
+  })
 })

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 {
@@ -90,11 +97,50 @@ interface SortListenerEventsOptions {
   resolveChainDeadline?: number
 }
 
+/**
+ * Orders the given mutation events into chains where each event's
+ * `previousRev` points at another event's `resultRev`. Events whose
+ * `previousRev` matches no other event start a new chain. The buffer may have
+ * multiple holes in it, so multiple chains can exist at once.
+ */
+function toOrderedChains(events: MutationEvent[]): MutationEvent[][] {
+  const chainStarts = events.filter(
+    (event) => !events.some((other) => other.resultRev === event.previousRev),
+  )
+
+  return chainStarts.map((start) => {
+    const chain: MutationEvent[] = []
+    let current: MutationEvent | undefined = start
+    while (current) {
+      chain.push(current)
+      const currentResultRev: string | undefined = current.resultRev
+      current = events.find((event) => event.previousRev === currentResultRev)
+    }
+    return chain
+  })
+}
+
+/**
+ * Discards the leading events of a chain up to and including the event whose
+ * `resultRev` equals the given revision. These events describe changes that
+ * are already reflected in the current base (e.g. events replayed by a
+ * resumed listener after the snapshot was refetched).
+ */
+function discardChainTo(chain: MutationEvent[], revision: string | undefined): MutationEvent[] {
+  const revisionIndex = chain.findIndex((event) => event.resultRev === revision)
+  if (revisionIndex === -1) return chain
+  return chain.slice(revisionIndex + 1)
+}
+
 /**
  * Takes an input observable of listener events that might arrive out of order, and emits them in sequence
  * If we receive mutation events that doesn't line up in [previousRev, resultRev] pairs we'll put them in a buffer and
  * check if we have an unbroken chain every time we receive a new event
  *
+ * Buffered chains that lead up to the current base revision are discarded:
+ * they describe changes already reflected in the base (e.g. events replayed
+ * by a resumed listener after the snapshot was refetched)
+ *
  * If the buffer grows beyond `maxBufferSize`, or if `resolveChainDeadline` milliseconds passes before the chain resolves
  * an OutOfSyncError will be thrown on the stream
  *
@@ -125,38 +171,40 @@ export function sortListenerEvents(options?: SortListenerEventsOptions) {
                 'Invalid state. Cannot process mutation event without a base sync event',
               )
             }
-            // Add the new mutation event into the buffer
-            const buffer = state.buffer.concat(event)
-            const emitEvents: MutationEvent[] = []
-            let baseRevision = state.base.revision
-            let progress = true
+            const baseRevision = state.base.revision
+
+            // Order the buffered events (plus the new one) into chains, then
+            // drop the parts of each chain the base already reflects.
+            const chains = toOrderedChains(state.buffer.concat(event))
+              .map((chain) => discardChainTo(chain, baseRevision))
+              .filter((chain) => chain.length > 0)
+
+            // A chain whose head continues the current base revision can be
+            // applied. There can be at most one; anything else stays buffered.
+            const applicable = chains.find((chain) => chain[0].previousRev === baseRevision)
+            const buffer = chains.filter((chain) => chain !== applicable).flat()
 
-            // Try to apply as many buffered mutations as possible.
-            while (progress) {
-              progress = false
-              // Look for a mutation whose previousRev matches the current base.
-              const idx = buffer.findIndex((e) => e.previousRev === baseRevision)
-              if (idx !== -1) {
-                // Remove the event from the buffer and “apply” it.
-                const [next] = buffer.splice(idx, 1)
-                emitEvents.push(next)
-                // If the mutation is a deletion, the new base revision is undefined.
-                baseRevision = next.transition === 'disappear' ? undefined : next.resultRev
-                progress = true
+            if (applicable) {
+              const last = applicable[applicable.length - 1]
+              return {
+                // If the chain ends in a deletion, the new base revision is undefined.
+                base: {revision: last.transition === 'disappear' ? undefined : last.resultRev},
+                buffer,
+                emitEvents: applicable,
               }
             }
 
             if (buffer.length >= maxBufferSize) {
               throw new MaxBufferExceededError(
                 `Too many unchainable mutation events (${buffer.length}) waiting to resolve.`,
-                {base: {revision: baseRevision}, buffer, emitEvents},
+                {base: {revision: baseRevision}, buffer, emitEvents: []},
               )
             }
 
             return {
               base: {revision: baseRevision},
               buffer,
-              emitEvents,
+              emitEvents: [],
             }
           }
           // Any other event is simply forwarded.
@@ -201,7 +249,11 @@ export const listen = (
 
   return sharedListener.events.pipe(
     concatMap((e) => {
-      if (e.type === 'welcome') {
+      // `welcome` means a fresh listener connection and `reset` means a
+      // resumed listener could not replay what was missed; both require
+      // refetching the snapshot. a `welcomeback` means the resume succeeded
+      // and the missed events were replayed, so no refetch is needed
+      if (e.type === 'welcome' || e.type === 'reset') {
         return fetchDocument(documentId).pipe(
           map((document): SyncEvent => ({type: 'sync', document})),
         )
@@ -251,6 +303,7 @@ export const listen = (
         document: document ?? null,
         revision: transactionId,
         timestamp,
+        mutations: next.mutations as Mutation[],
         ...(previousRev && {previousRev}),
       }
     }),