@sanity/sdk 0.0.0-rc.6 → 0.0.0

package/src/releases/getPerspectiveState.test.ts

@@ -0,0 +1,192 @@
+import {filter, firstValueFrom, of, Subject, take} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {type PerspectiveHandle, type ReleasePerspective} from '../config/sanityConfig'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {listenQuery as mockListenQuery} from '../utils/listenQuery'
+import {getPerspectiveState} from './getPerspectiveState'
+import {type ReleaseDocument} from './releasesStore'
+
+vi.mock('../utils/listenQuery', () => ({
+  listenQuery: vi.fn(),
+}))
+
+vi.mock('../client/clientStore', () => ({
+  getClientState: vi.fn(() => ({
+    observable: of({}),
+    getCurrent: vi.fn(),
+    subscribe: vi.fn(),
+  })),
+}))
+
+describe('getPerspectiveState', () => {
+  let instance: SanityInstance
+  let mockReleasesQuerySubject: Subject<ReleaseDocument[]>
+
+  const release1 = {
+    _id: 'release-1',
+    _type: 'sanity.release',
+    name: 'release1',
+    metadata: {title: 'Release 1', releaseType: 'asap'},
+    status: 'active',
+  } as unknown as ReleaseDocument
+  const release2: ReleaseDocument = {
+    ...release1,
+    _id: 'release-2',
+    _rev: 'rev2',
+    name: 'release2',
+    metadata: {title: 'Release 2', releaseType: 'asap'},
+  }
+
+  const activeReleases = [release1, release2]
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+
+    mockReleasesQuerySubject = new Subject<ReleaseDocument[]>()
+    vi.mocked(mockListenQuery).mockReturnValue(mockReleasesQuerySubject.asObservable())
+  })
+
+  afterEach(() => {
+    instance.dispose()
+    vi.clearAllMocks()
+  })
+
+  it('should return default perspective if no options or instance perspective is provided', async () => {
+    const state = getPerspectiveState(instance)
+    mockReleasesQuerySubject.next([])
+    const perspective = await firstValueFrom(state.observable)
+    expect(perspective).toBe('drafts')
+  })
+
+  it('should return instance perspective if provided and no options perspective', async () => {
+    instance.config.perspective = 'published'
+    const state = getPerspectiveState(instance)
+    mockReleasesQuerySubject.next([])
+    const perspective = await firstValueFrom(state.observable)
+    expect(perspective).toBe('published')
+  })
+
+  it('should return options perspective if provided', async () => {
+    const options: PerspectiveHandle = {perspective: 'raw'}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next([])
+    const perspective = await firstValueFrom(state.observable)
+    expect(perspective).toBe('raw')
+  })
+
+  it('should return undefined if release perspective is requested but no active releases', async () => {
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next([])
+    const perspective = await firstValueFrom(state.observable)
+    expect(perspective).toBeUndefined()
+  })
+
+  it('should calculate perspective based on active releases and releaseName', async () => {
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next(activeReleases)
+
+    const perspective = await firstValueFrom(
+      state.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+    expect(perspective).toEqual(['drafts', 'release1'])
+  })
+
+  it('should calculate perspective including multiple releases up to the specified releaseName', async () => {
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release2'}}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next(activeReleases)
+    const perspective = await firstValueFrom(
+      state.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+    expect(perspective).toEqual(['drafts', 'release1', 'release2'])
+  })
+
+  it('should filter excluded perspectives', async () => {
+    const perspectiveConfig: ReleasePerspective = {
+      releaseName: 'release2',
+      excludedPerspectives: ['drafts', 'release1'],
+    }
+    const options: PerspectiveHandle = {perspective: perspectiveConfig}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next(activeReleases)
+    const perspective = await firstValueFrom(
+      state.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+    expect(perspective).toEqual(['release2'])
+  })
+
+  it('should throw if the specified releaseName is not found in active releases', async () => {
+    const options: PerspectiveHandle = {perspective: {releaseName: 'nonexistent'}}
+    const state = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next(activeReleases)
+
+    await expect(
+      firstValueFrom(
+        state.observable.pipe(
+          filter((p): p is NonNullable<typeof p> => p !== undefined),
+          take(1),
+        ),
+      ),
+    ).rejects.toThrow('Release "nonexistent" not found in active releases')
+  })
+
+  it('should reuse the same options object for identical inputs (cache test)', async () => {
+    const options1: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+    const options2: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+
+    const state1 = getPerspectiveState(instance, options1)
+    mockReleasesQuerySubject.next(activeReleases)
+    await firstValueFrom(
+      state1.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+
+    const state2 = getPerspectiveState(instance, options2)
+    const perspective2 = state2.getCurrent()
+
+    expect(perspective2).toEqual(['drafts', 'release1'])
+  })
+
+  it('should handle changes in activeReleases (cache test)', async () => {
+    const options: PerspectiveHandle = {perspective: {releaseName: 'release1'}}
+
+    const state1 = getPerspectiveState(instance, options)
+    mockReleasesQuerySubject.next(activeReleases)
+    const perspective1 = await firstValueFrom(
+      state1.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+    expect(perspective1).toEqual(['drafts', 'release1'])
+
+    const updatedActiveReleases = [release1]
+    mockReleasesQuerySubject.next(updatedActiveReleases)
+
+    const perspectiveAfterUpdate = await firstValueFrom(
+      state1.observable.pipe(
+        filter((p): p is NonNullable<typeof p> => p !== undefined),
+        take(1),
+      ),
+    )
+    expect(perspectiveAfterUpdate).toEqual(['drafts', 'release1'])
+
+    const state2 = getPerspectiveState(instance, options)
+    const perspectiveNewCall = state2.getCurrent()
+    expect(perspectiveNewCall).toEqual(['drafts', 'release1'])
+  })
+})

package/src/releases/getPerspectiveState.ts

@@ -0,0 +1,93 @@
+import {createSelector} from 'reselect'
+
+import {type PerspectiveHandle, type ReleasePerspective} from '../config/sanityConfig'
+import {bindActionByDataset} from '../store/createActionBinder'
+import {createStateSourceAction, type SelectorContext} from '../store/createStateSourceAction'
+import {releasesStore, type ReleasesStoreState} from './releasesStore'
+
+function isReleasePerspective(
+  perspective: PerspectiveHandle['perspective'],
+): perspective is ReleasePerspective {
+  return typeof perspective === 'object' && perspective !== null && 'releaseName' in perspective
+}
+
+const DEFAULT_PERSPECTIVE = 'drafts'
+
+// Cache for options
+const optionsCache = new Map<string, Map<string, PerspectiveHandle>>()
+
+const selectInstancePerspective = (context: SelectorContext<ReleasesStoreState>) =>
+  context.instance.config.perspective
+const selectActiveReleases = (context: SelectorContext<ReleasesStoreState>) =>
+  context.state.activeReleases
+const selectOptions = (
+  _context: SelectorContext<ReleasesStoreState>,
+  options?: PerspectiveHandle,
+) => options
+
+const memoizedOptionsSelector = createSelector(
+  [selectActiveReleases, selectOptions],
+  (activeReleases, options) => {
+    if (!options || !activeReleases) return options
+
+    // Use release document IDs as the cache key
+    const releaseIds = activeReleases.map((release) => release._id).join(',')
+    let nestedCache = optionsCache.get(releaseIds)
+    if (!nestedCache) {
+      nestedCache = new Map<string, PerspectiveHandle>()
+      optionsCache.set(releaseIds, nestedCache)
+    }
+
+    const optionsKey = JSON.stringify(options)
+    let cachedOptions = nestedCache.get(optionsKey)
+
+    if (!cachedOptions) {
+      cachedOptions = options
+      nestedCache.set(optionsKey, cachedOptions)
+    }
+    return cachedOptions
+  },
+)
+
+/**
+ * Provides a subscribable state source for a "perspective" for the Sanity client,
+ * which is used to fetch documents as though certain Content Releases are active.
+ *
+ * @param instance - The Sanity instance to get the perspective for
+ * @param options - The options for the perspective -- usually a release name
+ *
+ * @returns A subscribable perspective value, usually a list of applicable release names,
+ * or a single release name / default perspective (such as 'drafts').
+ *
+ * @public
+ */
+export const getPerspectiveState = bindActionByDataset(
+  releasesStore,
+  createStateSourceAction({
+    selector: createSelector(
+      [selectInstancePerspective, selectActiveReleases, memoizedOptionsSelector],
+      (instancePerspective, activeReleases, memoizedOptions) => {
+        const perspective =
+          memoizedOptions?.perspective ?? instancePerspective ?? DEFAULT_PERSPECTIVE
+
+        if (!isReleasePerspective(perspective)) return perspective
+
+        // if there are no active releases we can't compute the release perspective
+        if (!activeReleases || activeReleases.length === 0) return undefined
+
+        const releaseNames = activeReleases.map((release) => release.name)
+        const index = releaseNames.findIndex((name) => name === perspective.releaseName)
+
+        if (index < 0) {
+          throw new Error(`Release "${perspective.releaseName}" not found in active releases`)
+        }
+
+        const filteredReleases = releaseNames.slice(0, index + 1) // Include the release itself
+
+        return ['drafts', ...filteredReleases].filter(
+          (name) => !perspective.excludedPerspectives?.includes(name),
+        )
+      },
+    ),
+  }),
+)

package/src/releases/releasesStore.test.ts

@@ -0,0 +1,170 @@
+import {type SanityClient} from '@sanity/client'
+import {of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {listenQuery} from '../utils/listenQuery'
+import {getActiveReleasesState, type ReleaseDocument} from './releasesStore'
+
+// Mock dependencies
+vi.mock('../client/clientStore', () => ({
+  getClientState: vi.fn(),
+}))
+vi.mock('../utils/listenQuery', () => ({
+  listenQuery: vi.fn(),
+}))
+
+// Mock console.error to prevent test runner noise and allow verification
+const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+describe('releasesStore', () => {
+  let instance: SanityInstance
+  const mockClient = {} as SanityClient
+
+  beforeEach(() => {
+    vi.resetAllMocks()
+    consoleErrorSpy.mockClear()
+
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('should set active releases state when listenQuery succeeds', async () => {
+    // note that the order of the releases is important here -- they get sorted
+    const mockReleases: ReleaseDocument[] = [
+      {
+        _id: 'r2',
+        _type: 'system.release',
+        name: 'Release 2',
+        metadata: {title: 'R2', releaseType: 'scheduled'},
+      } as ReleaseDocument,
+      {
+        _id: 'r1',
+        _type: 'system.release',
+        name: 'Release 1',
+        metadata: {title: 'R1', releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+
+    vi.mocked(listenQuery).mockReturnValue(of(mockReleases))
+
+    const state = getActiveReleasesState(instance)
+
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(state.getCurrent()).toEqual(mockReleases)
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+  })
+
+  it('should update active releases state when listenQuery emits new data', async () => {
+    const releasesSubject = new Subject<ReleaseDocument[]>()
+    vi.mocked(listenQuery).mockReturnValue(releasesSubject.asObservable())
+
+    const state = getActiveReleasesState(instance)
+
+    // Initial state should be default
+    expect(state.getCurrent()).toBeUndefined() // Default initial state
+
+    // Emit initial data
+    const initialReleases: ReleaseDocument[] = [
+      {
+        _id: 'r1',
+        _type: 'system.release',
+        name: 'Initial Release 1',
+        metadata: {title: 'IR1', releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+    releasesSubject.next(initialReleases)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(state.getCurrent()).toEqual(initialReleases)
+
+    const updatedReleases: ReleaseDocument[] = [
+      {
+        _id: 'r2',
+        _type: 'system.release',
+        name: 'New Release 2',
+        metadata: {title: 'NR2', releaseType: 'scheduled'},
+      } as ReleaseDocument,
+      {
+        _id: 'r1',
+        _type: 'system.release',
+        name: 'Updated Release 1',
+        metadata: {title: 'UR1', releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+    releasesSubject.next(updatedReleases)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(state.getCurrent()).toEqual(updatedReleases)
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+  })
+
+  it('should handle empty array from listenQuery', async () => {
+    // Configure listenQuery to return an empty array
+    vi.mocked(listenQuery).mockReturnValue(of([]))
+
+    const state = getActiveReleasesState(instance)
+
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(state.getCurrent()).toEqual([]) // Should be set to empty array
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+  })
+
+  it('should handle null/undefined from listenQuery by defaulting to empty array', async () => {
+    // Test null case
+    vi.mocked(listenQuery).mockReturnValue(of(null))
+    const state = getActiveReleasesState(instance)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(state.getCurrent()).toEqual([])
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+
+    // Test undefined case
+    vi.mocked(listenQuery).mockReturnValue(of(undefined))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(state.getCurrent()).toEqual([])
+    expect(consoleErrorSpy).not.toHaveBeenCalled()
+  })
+
+  it('should handle errors from listenQuery by retrying and eventually setting error state', async () => {
+    vi.useFakeTimers()
+    const error = new Error('Query failed')
+    const subject = new Subject<ReleaseDocument[]>()
+    vi.mocked(listenQuery).mockReturnValue(subject.asObservable())
+
+    // initialize the store
+    const state = getActiveReleasesState(instance)
+
+    // Error the subject
+    subject.error(error)
+
+    // Advance enough to cover the retry attempts (exponential backoff: 1s, 2s, 4s)
+    for (let i = 0; i < 3; i++) {
+      const delay = Math.pow(2, i) * 1000
+      await vi.advanceTimersByTimeAsync(delay)
+    }
+
+    // Verify error was logged at least once during retries
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '[releases] Error in subscription:',
+      error,
+      'Retry count:',
+      expect.any(Number),
+    )
+
+    // not sure how to test state.setError()
+    expect(state.getCurrent()).toEqual(undefined)
+
+    vi.useRealTimers()
+  })
+})

package/src/releases/releasesStore.ts

@@ -0,0 +1,89 @@
+import {type SanityClient} from '@sanity/client'
+import {type SanityDocument} from '@sanity/types'
+import {catchError, EMPTY, retry, switchMap, timer} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {bindActionByDataset} from '../store/createActionBinder'
+import {createStateSourceAction} from '../store/createStateSourceAction'
+import {defineStore, type StoreContext} from '../store/defineStore'
+import {listenQuery} from '../utils/listenQuery'
+import {sortReleases} from './utils/sortReleases'
+
+/**
+ * Represents a document in a Sanity dataset that represents release options.
+ * @internal
+ */
+export type ReleaseDocument = SanityDocument & {
+  name: string
+  publishAt?: string
+  metadata: {
+    title: string
+    releaseType: 'asap' | 'scheduled' | 'undecided'
+    intendedPublishAt?: string
+  }
+}
+
+export interface ReleasesStoreState {
+  activeReleases?: ReleaseDocument[]
+  error?: unknown
+}
+
+export const releasesStore = defineStore<ReleasesStoreState>({
+  name: 'Releases',
+  getInitialState: (): ReleasesStoreState => ({
+    activeReleases: undefined,
+  }),
+  initialize: (context) => {
+    const subscription = subscribeToReleases(context)
+    return () => subscription.unsubscribe()
+  },
+})
+
+/**
+ * Get the active releases from the store.
+ * @internal
+ */
+export const getActiveReleasesState = bindActionByDataset(
+  releasesStore,
+  createStateSourceAction({
+    selector: ({state}) => state.activeReleases,
+  }),
+)
+
+const RELEASES_QUERY = 'releases::all()[state == "active"]'
+const QUERY_PARAMS = {}
+
+const subscribeToReleases = ({instance, state}: StoreContext<ReleasesStoreState>) => {
+  return getClientState(instance, {
+    apiVersion: '2025-04-10',
+    perspective: 'raw',
+  })
+    .observable.pipe(
+      switchMap((client: SanityClient) =>
+        // releases are system documents, and are not supported by useQueryState
+        listenQuery<ReleaseDocument[]>(client, RELEASES_QUERY, QUERY_PARAMS, {
+          tag: 'releases-listener',
+          throttleTime: 1000,
+          transitions: ['update', 'appear', 'disappear'],
+        }).pipe(
+          retry({
+            count: 3,
+            delay: (error, retryCount) => {
+              // eslint-disable-next-line no-console
+              console.error('[releases] Error in subscription:', error, 'Retry count:', retryCount)
+              return timer(Math.min(1000 * Math.pow(2, retryCount), 10000))
+            },
+          }),
+          catchError((error) => {
+            state.set('setError', {error})
+            return EMPTY
+          }),
+        ),
+      ),
+    )
+    .subscribe({
+      next: (releases) => {
+        state.set('setActiveReleases', {activeReleases: sortReleases(releases ?? [])})
+      },
+    })
+}