@sanity/sdk 3.0.0-rc.1 → 3.0.0

package/src/comments/observeComments.test.ts

@@ -0,0 +1,193 @@
+import {type ListenEvent, type SanityClient} from '@sanity/client'
+import {Subject} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {type CommentsEvent, observeComments} from './observeComments'
+import {type StoredComment} from './types'
+
+function comment(overrides: Partial<StoredComment> & Pick<StoredComment, '_id'>) {
+  return {
+    _type: 'comment',
+    _createdAt: '2026-01-01T00:00:00Z',
+    _rev: 'rev',
+    authorId: 'user-1',
+    message: null,
+    threadId: 'thread-1',
+    status: 'open',
+    reactions: null,
+    target: {documentType: 'author', document: {_ref: 'doc-1', _type: 'reference', _weak: true}},
+    ...overrides,
+  } satisfies StoredComment as StoredComment
+}
+
+const WELCOME = {type: 'welcome'} as ListenEvent<StoredComment>
+
+let listen$: Subject<ListenEvent<StoredComment>>
+let fetches: Subject<StoredComment[]>[]
+let client: SanityClient
+
+beforeEach(() => {
+  listen$ = new Subject()
+  fetches = []
+  client = {
+    observable: {
+      listen: vi.fn(() => listen$),
+      fetch: vi.fn(() => {
+        const fetch$ = new Subject<StoredComment[]>()
+        fetches.push(fetch$)
+        return fetch$
+      }),
+    },
+  } as unknown as SanityClient
+})
+
+function collect(documentVersionId?: string) {
+  const events: CommentsEvent[] = []
+  const subscription = observeComments({client, documentId: 'doc-1', documentVersionId}).subscribe(
+    (event) => events.push(event),
+  )
+  return {events, subscription}
+}
+
+describe('observeComments', () => {
+  it('fetches a snapshot when the listener connects', () => {
+    const {events} = collect()
+
+    listen$.next(WELCOME)
+    fetches[0].next([comment({_id: 'a'})])
+
+    expect(events).toEqual([{type: 'snapshot', comments: [comment({_id: 'a'})]}])
+    expect(client.observable.fetch).toHaveBeenCalledWith(
+      expect.stringContaining('_type == "comment"'),
+      {documentId: 'doc-1'},
+      {tag: 'comments.list'},
+    )
+  })
+
+  it('passes the release id when reading a release', () => {
+    collect('summer')
+
+    expect(client.observable.listen).toHaveBeenCalledWith(
+      expect.stringContaining('target.documentVersionId == $documentVersionId'),
+      {documentId: 'doc-1', documentVersionId: 'summer'},
+      expect.objectContaining({tag: 'comments.listen'}),
+    )
+  })
+
+  it('maps appear, update, and disappear events', () => {
+    const {events} = collect()
+    listen$.next(WELCOME)
+    fetches[0].next([])
+    fetches[0].complete()
+
+    const created = comment({_id: 'a'})
+    const edited = comment({_id: 'a', status: 'resolved'})
+
+    listen$.next({
+      type: 'mutation',
+      transition: 'appear',
+      documentId: 'a',
+      result: created,
+      transactionId: 'tx-1',
+    } as ListenEvent<StoredComment>)
+    listen$.next({
+      type: 'mutation',
+      transition: 'update',
+      documentId: 'a',
+      result: edited,
+      transactionId: 'tx-2',
+    } as ListenEvent<StoredComment>)
+    listen$.next({
+      type: 'mutation',
+      transition: 'disappear',
+      documentId: 'a',
+    } as ListenEvent<StoredComment>)
+
+    expect(events.slice(1)).toEqual([
+      {type: 'appear', comment: created},
+      {type: 'update', comment: edited, transactionId: 'tx-2'},
+      {type: 'disappear', commentId: 'a'},
+    ])
+  })
+
+  it('ignores a mutation that carries no document', () => {
+    const {events} = collect()
+    listen$.next(WELCOME)
+    fetches[0].next([])
+
+    listen$.next({
+      type: 'mutation',
+      transition: 'update',
+      documentId: 'a',
+      transactionId: 'tx-1',
+    } as ListenEvent<StoredComment>)
+
+    expect(events).toHaveLength(1)
+  })
+
+  it('keeps a mutation that arrives while the snapshot is still loading', () => {
+    // The Studio loses this one: it awaits the fetch inside the event handler,
+    // so the older snapshot overwrites the newer comment.
+    const {events} = collect()
+    listen$.next(WELCOME)
+
+    const created = comment({_id: 'late'})
+    listen$.next({
+      type: 'mutation',
+      transition: 'appear',
+      documentId: 'late',
+      result: created,
+      transactionId: 'tx-1',
+    } as ListenEvent<StoredComment>)
+
+    expect(events).toEqual([])
+
+    fetches[0].next([comment({_id: 'a'})])
+
+    expect(events).toEqual([
+      {type: 'snapshot', comments: [comment({_id: 'a'})]},
+      {type: 'appear', comment: created},
+    ])
+  })
+
+  it('abandons an in-flight fetch when the listener reconnects', () => {
+    const {events} = collect()
+    listen$.next(WELCOME)
+    expect(fetches).toHaveLength(1)
+
+    listen$.next(WELCOME)
+    expect(fetches).toHaveLength(2)
+
+    // The first connection's snapshot is stale by now and must not be applied.
+    expect(fetches[0].observed).toBe(false)
+
+    fetches[0].next([comment({_id: 'stale'})])
+    expect(events).toEqual([])
+
+    fetches[1].next([comment({_id: 'fresh'})])
+    expect(events).toEqual([{type: 'snapshot', comments: [comment({_id: 'fresh'})]}])
+  })
+
+  it('reports a failed snapshot without killing the stream', () => {
+    const {events} = collect()
+    listen$.next(WELCOME)
+
+    const error = new Error('boom')
+    fetches[0].error(error)
+
+    expect(events).toEqual([{type: 'error', error}])
+
+    // A later reconnect still recovers.
+    listen$.next(WELCOME)
+    fetches[1].next([])
+    expect(events).toHaveLength(2)
+  })
+
+  it('stops listening when unsubscribed', () => {
+    const {subscription} = collect()
+    listen$.next(WELCOME)
+    subscription.unsubscribe()
+
+    expect(listen$.observed).toBe(false)
+  })
+})

package/src/comments/observeComments.ts

@@ -0,0 +1,113 @@
+import {type ListenEvent, type SanityClient} from '@sanity/client'
+import {filter, map, Observable, share, switchMap, take} from 'rxjs'
+
+import {buildCommentsListenQuery, buildCommentsQuery, LISTEN_OPTIONS} from './commentsConstants'
+import {type StoredComment} from './types'
+
+/** What the listener saw, in terms the store can apply. */
+export type CommentsEvent =
+  | {type: 'snapshot'; comments: StoredComment[]}
+  | {type: 'appear'; comment: StoredComment}
+  | {type: 'disappear'; commentId: string}
+  | {type: 'update'; comment: StoredComment; transactionId: string}
+  | {type: 'error'; error: unknown}
+
+function toCommentsEvent(event: ListenEvent<StoredComment>): CommentsEvent | undefined {
+  if (event.type !== 'mutation') return undefined
+
+  if (event.transition === 'disappear') {
+    return {type: 'disappear', commentId: event.documentId}
+  }
+
+  // `includeResult` is on, so a create or update carries the whole comment. An
+  // event without one is nothing we can apply.
+  if (!event.result) return undefined
+
+  if (event.transition === 'appear') {
+    return {type: 'appear', comment: event.result}
+  }
+
+  return {type: 'update', comment: event.result, transactionId: event.transactionId}
+}
+
+/**
+ * Watches one document's comments: a snapshot on connect, then live changes.
+ *
+ * The Studio awaits its snapshot inside the event handler, which loses any
+ * mutation that arrives while the fetch is in flight, because the older
+ * snapshot overwrites it. Here the mutations that arrive during a fetch are
+ * held and replayed straight after the snapshot, so nothing is dropped.
+ *
+ * A reconnect produces a fresh `welcome`, which cancels any fetch still running
+ * and starts a new one. Reconnects emit nothing themselves: dropping the list
+ * while reconnecting would only make readers suspend again for data we still
+ * have.
+ *
+ * @internal
+ */
+export function observeComments(options: {
+  client: SanityClient
+  documentId: string
+  documentVersionId?: string
+}): Observable<CommentsEvent> {
+  const {client, documentId, documentVersionId} = options
+
+  const params = {
+    documentId,
+    ...(documentVersionId ? {documentVersionId} : {}),
+  }
+
+  const events$ = client.observable
+    .listen<StoredComment>(buildCommentsListenQuery(documentVersionId), params, LISTEN_OPTIONS)
+    .pipe(share())
+
+  const mutations$ = events$.pipe(
+    map(toCommentsEvent),
+    filter((event): event is CommentsEvent => event !== undefined),
+  )
+
+  return events$.pipe(
+    filter((event) => event.type === 'welcome'),
+    switchMap(
+      () =>
+        new Observable<CommentsEvent>((observer) => {
+          // Subscribe before the fetch starts so nothing between the two is missed.
+          // The array only exists while the snapshot is in flight. Once flushed,
+          // live mutations pass through without retaining their history.
+          const buffered: CommentsEvent[] = []
+          let snapshotReceived = false
+          const mutationSubscription = mutations$.subscribe({
+            next: (event) => {
+              if (snapshotReceived) observer.next(event)
+              else buffered.push(event)
+            },
+            error: (error: unknown) => observer.error(error),
+          })
+
+          const snapshotSubscription = client.observable
+            .fetch<StoredComment[]>(buildCommentsQuery(documentVersionId), params, {
+              tag: 'comments.list',
+            })
+            .pipe(take(1))
+            .subscribe({
+              next: (comments) => {
+                observer.next({type: 'snapshot', comments})
+                snapshotReceived = true
+                for (const event of buffered) observer.next(event)
+                buffered.length = 0
+              },
+              error: (error: unknown) => {
+                observer.next({type: 'error', error})
+                observer.complete()
+              },
+            })
+
+          return () => {
+            mutationSubscription.unsubscribe()
+            snapshotSubscription.unsubscribe()
+            buffered.length = 0
+          }
+        }),
+    ),
+  )
+}

package/src/comments/reducers.test.ts

@@ -0,0 +1,277 @@
+import {describe, expect, it} from 'vitest'
+
+import {
+  addComment,
+  addSubscriber,
+  applyCommentUpdate,
+  clearPendingTransaction,
+  type CommentsStoreState,
+  getCommentsKey,
+  parseCommentsKey,
+  receiveComment,
+  removeCommentById,
+  removeSubscriber,
+  rollbackCommentUpdate,
+  setComments,
+  setCommentsError,
+  setPendingTransaction,
+} from './reducers'
+import {type StoredComment} from './types'
+
+const KEY = getCommentsKey({documentId: 'doc-1'})
+
+function comment(overrides: Partial<StoredComment> & Pick<StoredComment, '_id'>) {
+  return {
+    _type: 'comment',
+    _createdAt: '2026-01-01T00:00:00Z',
+    _rev: 'rev',
+    authorId: 'user-1',
+    message: null,
+    threadId: 'thread-1',
+    status: 'open',
+    reactions: null,
+    target: {documentType: 'author', document: {_ref: 'doc-1', _type: 'reference', _weak: true}},
+    ...overrides,
+  } satisfies StoredComment as StoredComment
+}
+
+function stateWith(comments: StoredComment[]): CommentsStoreState {
+  const base: CommentsStoreState = {
+    entries: {[KEY]: {subscribers: ['sub-1']}},
+    pendingCreates: {},
+    pendingTransactions: {},
+  }
+  return setComments(KEY, comments)(base)
+}
+
+const emptyState = (): CommentsStoreState => ({
+  entries: {},
+  pendingCreates: {},
+  pendingTransactions: {},
+})
+
+describe('comment list keys', () => {
+  it('round-trips a document id', () => {
+    expect(parseCommentsKey(getCommentsKey({documentId: 'doc-1'}))).toEqual({documentId: 'doc-1'})
+  })
+
+  it('round-trips a release version', () => {
+    const key = getCommentsKey({documentId: 'doc-1', documentVersionId: 'summer'})
+    expect(parseCommentsKey(key)).toEqual({documentId: 'doc-1', documentVersionId: 'summer'})
+  })
+
+  it('separates a release from the default list', () => {
+    expect(getCommentsKey({documentId: 'doc-1'})).not.toBe(
+      getCommentsKey({documentId: 'doc-1', documentVersionId: 'summer'}),
+    )
+  })
+})
+
+describe('subscribers', () => {
+  const empty = emptyState()
+
+  it('creates an entry for the first subscriber', () => {
+    expect(addSubscriber(KEY, 'sub-1')(empty).entries[KEY]).toEqual({subscribers: ['sub-1']})
+  })
+
+  it('drops the entry when the last subscriber leaves', () => {
+    const one = addSubscriber(KEY, 'sub-1')(empty)
+    expect(removeSubscriber(KEY, 'sub-1')(one).entries).toEqual({})
+  })
+
+  it('keeps the entry while another subscriber remains', () => {
+    const two = addSubscriber(KEY, 'sub-2')(addSubscriber(KEY, 'sub-1')(empty))
+    expect(removeSubscriber(KEY, 'sub-1')(two).entries[KEY]).toEqual({subscribers: ['sub-2']})
+  })
+
+  it('drops reconciliation state when the last listener leaves', () => {
+    const before = {
+      ...stateWith([comment({_id: 'a'})]),
+      pendingCreates: {a: true as const},
+      pendingTransactions: {a: 'tx-1'},
+    }
+
+    const next = removeSubscriber(KEY, 'sub-1')(before)
+
+    expect(next.entries).toEqual({})
+    expect(next.pendingCreates).toEqual({})
+    expect(next.pendingTransactions).toEqual({})
+  })
+
+  it('ignores removal for an unknown key', () => {
+    expect(removeSubscriber('missing', 'sub-1')(empty)).toBe(empty)
+  })
+})
+
+describe('setComments', () => {
+  it('keys the snapshot by comment id and clears any previous error', () => {
+    const withError = setCommentsError(
+      KEY,
+      new Error('boom'),
+    )({...emptyState(), entries: {[KEY]: {subscribers: ['sub-1']}}})
+
+    const next = setComments(KEY, [comment({_id: 'a'})])(withError)
+
+    expect(Object.keys(next.entries[KEY]!.comments!)).toEqual(['a'])
+    expect(next.entries[KEY]!.error).toBe(undefined)
+  })
+
+  it('ignores a snapshot for an entry nobody is reading', () => {
+    const empty = emptyState()
+    expect(setComments(KEY, [comment({_id: 'a'})])(empty)).toBe(empty)
+  })
+
+  it('keeps a failed local create that is absent from the snapshot', () => {
+    const failed = comment({
+      _id: 'failed',
+      message: [{_type: 'block', _key: 'block-1', children: [{_type: 'span', text: 'unsent'}]}],
+      _state: {type: 'createError', error: new Error('nope')},
+    })
+
+    const next = setComments(KEY, [])(stateWith([failed]))
+
+    expect(next.entries[KEY]!.comments!['failed']).toBe(failed)
+  })
+
+  it('keeps an in-flight local create that is absent from the snapshot', () => {
+    const optimistic = addComment(KEY, {
+      _id: 'pending',
+      _type: 'comment',
+      authorId: 'user-1',
+      message: null,
+      threadId: 'thread-2',
+      status: 'open',
+      reactions: null,
+      target: {documentType: 'author', document: {_ref: 'doc-1', _type: 'reference', _weak: true}},
+    })(stateWith([]))
+
+    const next = setComments(KEY, [])(optimistic)
+
+    expect(next.entries[KEY]!.comments!['pending']).toBeDefined()
+  })
+
+  it('stores comment ids such as __proto__ as ordinary keys', () => {
+    const special = comment({_id: '__proto__'})
+    const next = setComments(KEY, [special])(stateWith([]))
+
+    expect(Object.values(next.entries[KEY]!.comments!)).toEqual([special])
+  })
+})
+
+describe('addComment', () => {
+  it('stands in a createdAt so an unconfirmed comment still sorts', () => {
+    const next = addComment(KEY, {
+      _id: 'new',
+      _type: 'comment',
+      authorId: 'user-1',
+      message: null,
+      threadId: 'thread-2',
+      status: 'open',
+      reactions: null,
+      target: {documentType: 'author', document: {_ref: 'doc-1', _type: 'reference', _weak: true}},
+    })(stateWith([]))
+
+    expect(next.entries[KEY]!.comments!['new']._createdAt).toEqual(expect.any(String))
+  })
+
+  it('keeps the server createdAt once there is one', () => {
+    const existing = comment({_id: 'a', _createdAt: '2026-03-03T00:00:00Z'})
+    const next = addComment(KEY, {...existing})(stateWith([existing]))
+
+    expect(next.entries[KEY]!.comments!['a']._createdAt).toBe('2026-03-03T00:00:00Z')
+  })
+
+  it('marks a failed comment as retrying when it is added again', () => {
+    const failed = comment({
+      _id: 'a',
+      _state: {type: 'createError', error: new Error('nope')},
+    })
+    const payload = {...failed}
+    delete payload._state
+
+    const next = addComment(KEY, payload)(stateWith([failed]))
+
+    expect(next.entries[KEY]!.comments!['a']._state).toEqual({type: 'createRetrying'})
+  })
+})
+
+describe('applyCommentUpdate', () => {
+  it('merges a patch into the comment', () => {
+    const next = applyCommentUpdate('a', {status: 'resolved'})(stateWith([comment({_id: 'a'})]))
+    expect(next.entries[KEY]!.comments!['a'].status).toBe('resolved')
+  })
+
+  it('leaves state untouched for an unknown comment', () => {
+    const before = stateWith([comment({_id: 'a'})])
+    expect(applyCommentUpdate('missing', {status: 'resolved'})(before)).toBe(before)
+  })
+})
+
+describe('removeCommentById', () => {
+  it('removes the comment and its replies', () => {
+    const before = stateWith([
+      comment({_id: 'a'}),
+      comment({_id: 'b', parentCommentId: 'a'}),
+      comment({_id: 'c'}),
+    ])
+
+    expect(Object.keys(removeCommentById('a')(before).entries[KEY]!.comments!)).toEqual(['c'])
+  })
+
+  it('removes a single reply without touching its siblings', () => {
+    const before = stateWith([
+      comment({_id: 'a'}),
+      comment({_id: 'b', parentCommentId: 'a'}),
+      comment({_id: 'c', parentCommentId: 'a'}),
+    ])
+
+    expect(Object.keys(removeCommentById('b')(before).entries[KEY]!.comments!)).toEqual(['a', 'c'])
+  })
+
+  it('leaves state untouched for an unknown comment', () => {
+    const before = stateWith([comment({_id: 'a'})])
+    expect(removeCommentById('missing')(before)).toBe(before)
+  })
+})
+
+describe('receiveComment', () => {
+  it('replaces what we held with the server copy', () => {
+    const before = stateWith([comment({_id: 'a', status: 'open'})])
+    const next = receiveComment(KEY, comment({_id: 'a', status: 'resolved'}))(before)
+
+    expect(next.entries[KEY]!.comments!['a'].status).toBe('resolved')
+  })
+
+  it('clears create reconciliation after the entry has been released', () => {
+    const before: CommentsStoreState = {...emptyState(), pendingCreates: {a: true}}
+
+    expect(receiveComment(KEY, comment({_id: 'a'}))(before).pendingCreates).toEqual({})
+  })
+})
+
+describe('pending transactions', () => {
+  it('records and clears the transaction for a comment', () => {
+    const set = setPendingTransaction('a', 'tx-1')(emptyState())
+    expect(set.pendingTransactions).toEqual({a: 'tx-1'})
+    expect(clearPendingTransaction('a')(set).pendingTransactions).toEqual({})
+  })
+
+  it('rolls back an optimistic edit while its transaction is still current', () => {
+    const previous = comment({_id: 'a', status: 'open'})
+    const pending = setPendingTransaction('a', 'tx-1')(stateWith([previous]))
+    const optimistic = applyCommentUpdate('a', {status: 'resolved'})(pending)
+
+    const rolledBack = rollbackCommentUpdate('a', 'tx-1', previous)(optimistic)
+
+    expect(rolledBack.entries[KEY]!.comments!['a'].status).toBe('open')
+    expect(rolledBack.pendingTransactions).toEqual({})
+  })
+
+  it('does not roll back once a newer transaction owns the comment', () => {
+    const previous = comment({_id: 'a', status: 'open'})
+    const pending = setPendingTransaction('a', 'tx-2')(stateWith([previous]))
+    const optimistic = applyCommentUpdate('a', {status: 'resolved'})(pending)
+
+    expect(rollbackCommentUpdate('a', 'tx-1', previous)(optimistic)).toBe(optimistic)
+  })
+})