@sanity/sdk 3.0.0-rc.1 → 3.0.0-rc.2

package/src/document/util.test.ts

@@ -0,0 +1,46 @@
+import {describe, expect, it} from 'vitest'
+
+import {getEditingDocumentId, getEffectiveDocumentId} from './util'
+
+const PUBLISHED = 'movie-1'
+const DRAFT = 'drafts.movie-1'
+const VERSION = 'versions.autumn.movie-1'
+
+describe('getEditingDocumentId', () => {
+  it('resolves the draft by default, which is what the Studio edits', () => {
+    expect(getEditingDocumentId({documentId: PUBLISHED})).toBe(DRAFT)
+  })
+
+  it("resolves the draft under the 'drafts' perspective", () => {
+    expect(getEditingDocumentId({documentId: PUBLISHED, perspective: 'drafts'})).toBe(DRAFT)
+  })
+
+  it("resolves the published document under the 'published' perspective", () => {
+    expect(getEditingDocumentId({documentId: PUBLISHED, perspective: 'published'})).toBe(PUBLISHED)
+  })
+
+  it('resolves the version under a release perspective', () => {
+    expect(
+      getEditingDocumentId({documentId: PUBLISHED, perspective: {releaseName: 'autumn'}}),
+    ).toBe(VERSION)
+  })
+
+  it('resolves the published document for live edit, which has no draft', () => {
+    expect(getEditingDocumentId({documentId: PUBLISHED, liveEdit: true})).toBe(PUBLISHED)
+  })
+
+  it('is idempotent when handed an already-specific id', () => {
+    expect(getEditingDocumentId({documentId: DRAFT})).toBe(DRAFT)
+    expect(getEditingDocumentId({documentId: VERSION, perspective: 'published'})).toBe(PUBLISHED)
+    expect(getEditingDocumentId({documentId: DRAFT, perspective: {releaseName: 'autumn'}})).toBe(
+      VERSION,
+    )
+  })
+
+  it('differs from getEffectiveDocumentId precisely where it has to', () => {
+    // The canonical key collapses a draft onto its published id, which is right for
+    // storing state and wrong for anything comparing exact ids.
+    expect(getEffectiveDocumentId({documentId: DRAFT, documentType: 'movie'})).toBe(PUBLISHED)
+    expect(getEditingDocumentId({documentId: DRAFT})).toBe(DRAFT)
+  })
+})

package/src/document/util.ts

@@ -1,8 +1,44 @@
-import {DocumentId, getPublishedId, getVersionId} from '@sanity/id-utils'
+import {DocumentId, getDraftId, getPublishedId, getVersionId} from '@sanity/id-utils'
 
 import {type DocumentHandle} from '../config/sanityConfig'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 
+/**
+ * The id of the specific document a user is editing under a given perspective:
+ * the draft, the published document, or a release version.
+ *
+ * Distinct from {@link getEffectiveDocumentId}, which resolves the canonical key a
+ * document's state is stored under and so collapses a draft onto its published id.
+ * This one keeps them apart, because some things compare the exact id. Presence is
+ * the motivating case: the Studio's field indicators match the id its form is on,
+ * exactly, so an app reporting the published id shows up in the Studio at document
+ * level while never lighting up a single field.
+ *
+ * @remarks
+ * Resolved from the handle alone, which is right whenever a draft or version
+ * exists, so for any document actually being edited. The Studio additionally falls
+ * back to whichever document exists, so for a published document nobody has edited
+ * yet its form sits on the published id where this returns the draft id. Matching
+ * that would mean reading document state, which presence deliberately does not
+ * depend on.
+ *
+ * @internal
+ */
+export function getEditingDocumentId(
+  doc: Pick<DocumentHandle, 'documentId' | 'liveEdit' | 'perspective'>,
+): string {
+  if (doc.liveEdit) {
+    return getPublishedId(DocumentId(doc.documentId))
+  }
+  if (isReleasePerspective(doc.perspective)) {
+    return getVersionId(DocumentId(doc.documentId), doc.perspective.releaseName)
+  }
+  if (doc.perspective === 'published') {
+    return getPublishedId(DocumentId(doc.documentId))
+  }
+  return getDraftId(DocumentId(doc.documentId))
+}
+
 export function getEffectiveDocumentId(doc: DocumentHandle): string {
   if (doc.liveEdit) {
     return doc.documentId

package/src/installations/installations.test-d.ts

@@ -29,6 +29,11 @@ test('Installation — no includes: only the base shape', () => {
   expectTypeOf<Extract<keyof Installation, IncludeKeys>>().toEqualTypeOf<never>()
 })
 
+test('InstallationBase — the application sub-object carries name and reference', () => {
+  expectTypeOf<InstallationBase['application']['name']>().toEqualTypeOf<string>()
+  expectTypeOf<InstallationBase['application']['reference']>().toEqualTypeOf<string>()
+})
+
 test('Installation — each token adds its top-level field, required, others absent', () => {
   expectTypeOf<Installation<'access'>['access']>().toEqualTypeOf<InstallationAccess[]>()
   expectTypeOf<

package/src/installations/installations.ts

@@ -79,6 +79,10 @@ export interface InstallationBase {
   updatedAt: string
   application: {
     title: string
+    /** Stable, immutable identity of the installed singleton, distinct from `slug`. */
+    name: string
+    /** Qualified, globally-unique handle of the installed singleton (e.g. `sanity/<name>`). */
+    reference: string
     slug: string | null
   }
 }

package/src/presence/bifurTransport.test.ts

@@ -1,7 +1,7 @@
 import {fromUrl} from '@sanity/bifur-client'
 import {type SanityClient} from '@sanity/client'
-import {of, Subject} from 'rxjs'
-import {beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
+import {type Observable, of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
 import {createBifurTransport} from './bifurTransport'
 import {type PresenceLocation, type TransportEvent} from './types'
@@ -39,16 +39,20 @@ describe('createBifurTransport', () => {
   let mockBifurClient: {
     listen: Mock
     request: Mock
+    heartbeats: Observable<Date>
   }
   let mockSanityClient: SanityClient
   let token$: Subject<string | null>
+  let heartbeats$: Subject<Date>
 
   beforeEach(() => {
     vi.useFakeTimers()
     vi.clearAllMocks()
+    heartbeats$ = new Subject<Date>()
     mockBifurClient = {
       listen: vi.fn(() => new Subject<never>()),
       request: vi.fn(() => of(undefined)),
+      heartbeats: heartbeats$.asObservable(),
     }
     fromUrlMock.mockReturnValue(mockBifurClient)
 
@@ -130,6 +134,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     incomingBifurEvents$.next({
       type: 'rollCall',
@@ -161,6 +167,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     const locations: PresenceLocation[] = [
       {type: 'document', documentId: 'doc1', path: ['a'], lastActiveAt: new Date().toISOString()},
@@ -200,6 +208,8 @@ describe('createBifurTransport', () => {
 
     const receivedEvents: TransportEvent[] = []
     incomingEvents$.subscribe((event) => receivedEvents.push(event))
+    // The listener is established per live connection, so bring one up first.
+    heartbeats$.next(new Date())
 
     incomingBifurEvents$.next({
       type: 'disconnect',
@@ -233,6 +243,7 @@ describe('createBifurTransport', () => {
     incomingEvents$.subscribe({
       error: (err) => errors.push(err),
     })
+    heartbeats$.next(new Date())
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     incomingBifurEvents$.next({type: 'unknown'} as any)
@@ -242,7 +253,148 @@ describe('createBifurTransport', () => {
     expect(errors[0].message).toContain('Got unknown presence event')
   })
 
-  describe('dispatchMessage', () => {
+  describe('connections', () => {
+    it('emits an incrementing generation each time the socket becomes live', () => {
+      const [, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const generations: number[] = []
+      connections$.subscribe((generation) => generations.push(generation))
+
+      // Several heartbeats on one live socket are a single generation.
+      heartbeats$.next(new Date())
+      heartbeats$.next(new Date())
+      expect(generations).toEqual([1])
+
+      // bifur-client errors the stream when the socket closes. The transport is
+      // expected to reconnect rather than give up for the life of the page.
+      const reconnected$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnected$.asObservable()
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      // First retry is scheduled 200ms out (2 ** 1 * 100).
+      vi.advanceTimersByTime(200)
+      reconnected$.next(new Date())
+
+      expect(generations).toEqual([1, 2])
+    })
+
+    it('does not resubscribe before the backoff has elapsed', () => {
+      const [, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const generations: number[] = []
+      connections$.subscribe((generation) => generations.push(generation))
+      heartbeats$.next(new Date())
+
+      const reconnected$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnected$.asObservable()
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      vi.advanceTimersByTime(199)
+      reconnected$.next(new Date())
+      expect(generations).toEqual([1])
+    })
+  })
+
+  describe('incoming events across a reconnect', () => {
+    it('keeps delivering presence after the socket drops', () => {
+      // bifur errors every stream on the same socket close, the inbound listener
+      // included. If only the heartbeat stream recovers, this client re-announces
+      // itself to peers while permanently ceasing to see any of them.
+      const firstListen$ = new Subject<IncomingBifurEvent>()
+      const secondListen$ = new Subject<IncomingBifurEvent>()
+      mockBifurClient.listen.mockReturnValueOnce(firstListen$).mockReturnValueOnce(secondListen$)
+
+      const [incomingEvents$, , connections$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      const received: TransportEvent[] = []
+      incomingEvents$.subscribe({
+        next: (event) => received.push(event),
+        error: () => received.push({type: 'rollCall', userId: 'STREAM_DIED', sessionId: ''}),
+      })
+      connections$.subscribe()
+
+      heartbeats$.next(new Date())
+      firstListen$.next({type: 'rollCall', i: 'user-1', session: 'before'})
+      expect(received.map((e) => e.sessionId)).toEqual(['before'])
+
+      // Socket closes: both streams error.
+      const reconnectedHeartbeats$ = new Subject<Date>()
+      mockBifurClient.heartbeats = reconnectedHeartbeats$.asObservable()
+      firstListen$.error(new Error('WebSocket connection error'))
+      heartbeats$.error(new Error('WebSocket connection error'))
+
+      vi.advanceTimersByTime(200)
+      reconnectedHeartbeats$.next(new Date())
+
+      // Peers answer the roll call we send on reconnect. We have to be listening.
+      secondListen$.next({type: 'rollCall', i: 'user-1', session: 'after'})
+
+      expect(received.map((e) => e.sessionId)).toEqual(['before', 'after'])
+    })
+  })
+
+  describe('unload', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('emits on beforeunload and pagehide, and removes its listeners', () => {
+      // These tests run in Node, so stand in a bare EventTarget for `window`.
+      const fakeWindow = new EventTarget()
+      vi.stubGlobal('window', fakeWindow)
+
+      const [, , , unload$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      let emissions = 0
+      const subscription = unload$.subscribe(() => {
+        emissions += 1
+      })
+
+      fakeWindow.dispatchEvent(new Event('beforeunload'))
+      expect(emissions).toBe(1)
+
+      // `pagehide` matters on its own: iOS Safari and pages entering the
+      // back/forward cache never fire `beforeunload`.
+      fakeWindow.dispatchEvent(new Event('pagehide'))
+      expect(emissions).toBe(2)
+
+      // The listeners belong to the subscription, so unsubscribing removes them
+      // instead of leaking one per transport for the life of the page.
+      subscription.unsubscribe()
+      fakeWindow.dispatchEvent(new Event('beforeunload'))
+      expect(emissions).toBe(2)
+    })
+
+    it('is inert when there is no window', () => {
+      const [, , , unload$] = createBifurTransport({
+        client: mockSanityClient,
+        token$,
+        sessionId: 'my-session',
+      })
+
+      let completed = false
+      unload$.subscribe({complete: () => (completed = true)})
+      expect(completed).toBe(true)
+    })
+  })
+
+  describe('dispatch', () => {
     it('sends a "rollCall" message', () => {
       const [, dispatchMessage] = createBifurTransport({
         client: mockSanityClient,

package/src/presence/bifurTransport.ts

@@ -1,7 +1,7 @@
 import {type BifurClient, fromUrl} from '@sanity/bifur-client'
 import {type SanityClient} from '@sanity/client'
-import {EMPTY, fromEvent, type Observable} from 'rxjs'
-import {map, share, switchMap} from 'rxjs/operators'
+import {defer, EMPTY, fromEvent, merge, type Observable, timer} from 'rxjs'
+import {catchError, distinctUntilChanged, map, retry, share, switchMap} from 'rxjs/operators'
 
 import {
   type BifurTransportOptions,
@@ -11,6 +11,12 @@ import {
   type TransportMessage,
 } from './types'
 
+/**
+ * Longest gap between reconnection attempts, matching the Studio's presence
+ * transport so both behave the same way on a flaky connection.
+ */
+const CONNECT_RETRY_MAX_DELAY = 1000 * 240
+
 type BifurStateMessage = {
   type: 'state'
   i: string
@@ -91,13 +97,80 @@ const handleIncomingMessage = (event: IncomingBifurEvent): TransportEvent => {
   }
 }
 
+/**
+ * Emits an incrementing generation number each time the socket becomes live.
+ *
+ * `@sanity/bifur-client` does not reconnect on its own — it errors the stream
+ * when the socket closes. Without the `retry` below, presence stops for the
+ * life of the page after the first dropped connection.
+ */
+const createConnections = (bifur: BifurClient): Observable<number> => {
+  let generation = 0
+
+  return defer(() => {
+    const current = ++generation
+    // `heartbeats` emits as soon as the socket is open and authorized, then on
+    // every server heartbeat and every response. Subscribing to it is also what
+    // keeps the socket alive between requests.
+    return bifur.heartbeats.pipe(map(() => current))
+  }).pipe(
+    retry({
+      delay: (_error, retryCount) =>
+        timer(Math.min(CONNECT_RETRY_MAX_DELAY, 2 ** retryCount * 100)),
+      resetOnSuccess: true,
+    }),
+    // After `retry` so that one operator instance spans reconnects, making each
+    // live socket yield exactly one emission.
+    distinctUntilChanged(),
+    share(),
+  )
+}
+
+/**
+ * Presence events from everyone else in the room, re-established on every live
+ * connection.
+ *
+ * A socket close errors this stream just as it errors the heartbeats, so without
+ * re-subscribing the client would keep announcing itself after a reconnect while
+ * never hearing from anyone again. Driving it from `connections$` rather than
+ * giving it its own `retry` keeps a single reconnect loop, instead of two
+ * independent backoffs racing over one refcounted socket.
+ */
+const createIncomingEvents = (
+  bifur: BifurClient,
+  connections$: Observable<number>,
+): Observable<TransportEvent> =>
+  connections$.pipe(
+    switchMap(() =>
+      bifur.listen<IncomingBifurEvent>('presence').pipe(
+        // Let a dead listener go quietly. The next connection replaces it, and
+        // surfacing the error here would tear down the reconnect loop with it.
+        catchError(() => EMPTY),
+      ),
+    ),
+    map(handleIncomingMessage),
+    share(),
+  )
+
+/**
+ * Emits when the page is going away. `pagehide` is needed alongside
+ * `beforeunload` because iOS Safari and pages entering the back/forward cache
+ * never fire `beforeunload`.
+ */
+const createUnload = (): Observable<void> => {
+  if (typeof window === 'undefined') return EMPTY
+
+  return merge(fromEvent(window, 'beforeunload'), fromEvent(window, 'pagehide')).pipe(
+    map(() => undefined),
+  )
+}
+
 export const createBifurTransport = (options: BifurTransportOptions): PresenceTransport => {
   const {client, token$, sessionId} = options
   const bifur = getBifurClient(client, token$)
 
-  const incomingEvents$: Observable<TransportEvent> = bifur
-    .listen<IncomingBifurEvent>('presence')
-    .pipe(map(handleIncomingMessage))
+  const connections$ = createConnections(bifur)
+  const incomingEvents$ = createIncomingEvents(bifur, connections$)
 
   const dispatchMessage = (message: TransportMessage): Observable<void> => {
     switch (message.type) {
@@ -115,11 +188,5 @@ export const createBifurTransport = (options: BifurTransportOptions): PresenceTr
     }
   }
 
-  if (typeof window !== 'undefined') {
-    fromEvent(window, 'beforeunload')
-      .pipe(switchMap(() => dispatchMessage({type: 'disconnect'})))
-      .subscribe()
-  }
-
-  return [incomingEvents$.pipe(share()), dispatchMessage]
+  return [incomingEvents$, dispatchMessage, connections$, createUnload()]
 }

package/src/presence/paths.test.ts

@@ -0,0 +1,70 @@
+import {type Path} from '@sanity/types'
+import {describe, expect, it} from 'vitest'
+
+import {startsWithPath} from './paths'
+
+describe('startsWithPath', () => {
+  it('treats the empty path as a prefix of everything, which is the document root', () => {
+    expect(startsWithPath([], ['title'])).toBe(true)
+    expect(startsWithPath([], [])).toBe(true)
+  })
+
+  it('matches a path against itself', () => {
+    expect(startsWithPath(['title'], ['title'])).toBe(true)
+  })
+
+  it('matches a descendant', () => {
+    expect(startsWithPath(['body'], ['body', 'children'])).toBe(true)
+  })
+
+  it('does not match an ancestor, since a longer prefix cannot fit', () => {
+    expect(startsWithPath(['body', 'children'], ['body'])).toBe(false)
+  })
+
+  it('does not match a sibling', () => {
+    expect(startsWithPath(['title'], ['subtitle'])).toBe(false)
+  })
+
+  it('does not match a partial segment name', () => {
+    // `title` must not be treated as a prefix of `titleImage`.
+    expect(startsWithPath(['title'], ['titleImage'])).toBe(false)
+  })
+
+  it('compares keyed segments by key rather than by identity', () => {
+    // Distinct objects with the same key, which is what arrives over the wire.
+    expect(startsWithPath(['cast', {_key: 'a'}], ['cast', {_key: 'a'}, 'name'])).toBe(true)
+    expect(startsWithPath(['cast', {_key: 'a'}], ['cast', {_key: 'b'}, 'name'])).toBe(false)
+  })
+
+  it('does not confuse a keyed segment with a string or a number', () => {
+    expect(startsWithPath([{_key: 'a'}], ['a'])).toBe(false)
+    expect(startsWithPath(['a'], [{_key: 'a'}])).toBe(false)
+    expect(startsWithPath([{_key: '0'}], [0])).toBe(false)
+  })
+
+  it('compares numeric indexes', () => {
+    expect(startsWithPath(['awards', 0], ['awards', 0])).toBe(true)
+    expect(startsWithPath(['awards', 0], ['awards', 1])).toBe(false)
+  })
+
+  it('compares index tuples structurally', () => {
+    const prefix: Path = ['body', [0, 2]]
+    expect(startsWithPath(prefix, ['body', [0, 2], 'children'])).toBe(true)
+    expect(startsWithPath(prefix, ['body', [0, 3]])).toBe(false)
+    expect(startsWithPath(prefix, ['body', [0, '']])).toBe(false)
+  })
+
+  it('does not confuse a tuple with a keyed segment', () => {
+    expect(startsWithPath([[0, 2]], [{_key: 'a'}])).toBe(false)
+    expect(startsWithPath([{_key: 'a'}], [[0, 2]])).toBe(false)
+  })
+
+  it('handles a realistic Portable Text span path', () => {
+    const field: Path = ['body']
+    const span: Path = ['body', {_key: 'block-1'}, 'children', {_key: 'span-1'}, 'text']
+
+    expect(startsWithPath(field, span)).toBe(true)
+    expect(startsWithPath(['title'], span)).toBe(false)
+    expect(startsWithPath(['body', {_key: 'block-2'}], span)).toBe(false)
+  })
+})

package/src/presence/paths.ts

@@ -0,0 +1,41 @@
+import {type IndexTuple, type KeyedSegment, type Path, type PathSegment} from '@sanity/types'
+
+/**
+ * Segments are not always strings, despite what `PresenceLocation.path` declares.
+ * Array items arrive as `{_key}` and Portable Text spans as a mix of keys and
+ * property names, because that is what the Studio sends.
+ */
+function isKeyedSegment(segment: PathSegment): segment is KeyedSegment {
+  return (
+    typeof segment === 'object' && segment !== null && !Array.isArray(segment) && '_key' in segment
+  )
+}
+
+/**
+ * Index tuples (`[from, to]`) only occur in slice selections, which presence never
+ * reports. Compared structurally rather than assumed absent.
+ */
+function isEqualTuple(a: IndexTuple, b: IndexTuple): boolean {
+  return a.length === b.length && a.every((value, index) => value === b[index])
+}
+
+/** Compares two path segments, whatever shape they arrive in. */
+function isEqualSegment(a: PathSegment, b: PathSegment): boolean {
+  if (a === b) return true
+  if (isKeyedSegment(a) && isKeyedSegment(b)) return a._key === b._key
+  if (Array.isArray(a) && Array.isArray(b)) return isEqualTuple(a, b)
+  return false
+}
+
+/**
+ * True when `candidate` is at or below `prefix` in the document tree.
+ *
+ * Equivalent to `startsWith` from the Studio's `@sanity/util/paths`, which is not
+ * an SDK dependency.
+ *
+ * @internal
+ */
+export function startsWithPath(prefix: Path, candidate: Path): boolean {
+  if (prefix.length > candidate.length) return false
+  return prefix.every((segment, index) => isEqualSegment(segment, candidate[index]))
+}