@sanity/sdk 2.6.0 → 2.7.0

package/src/store/createActionBinder.test.ts

@@ -1,6 +1,13 @@
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {bindActionByDataset, bindActionGlobally, createActionBinder} from './createActionBinder'
+import {type DocumentSource} from '../config/sanityConfig'
+import {
+  bindActionByDataset,
+  bindActionBySource,
+  bindActionBySourceAndPerspective,
+  bindActionGlobally,
+  createActionBinder,
+} from './createActionBinder'
 import {createSanityInstance} from './createSanityInstance'
 import {createStoreInstance} from './createStoreInstance'
 
@@ -153,3 +160,206 @@ describe('bindActionGlobally', () => {
     expect(storeInstance.dispose).toHaveBeenCalledTimes(1)
   })
 })
+
+describe('bindActionBySource', () => {
+  it('should throw an error when provided an invalid source', () => {
+    const storeDefinition = {
+      name: 'SourceStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySource(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    expect(() =>
+      boundAction(instance, {source: {invalid: 'source'} as unknown as DocumentSource}),
+    ).toThrow('Received invalid source:')
+  })
+
+  it('should throw an error when no source provided and projectId/dataset are missing', () => {
+    const storeDefinition = {
+      name: 'SourceStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySource(storeDefinition, action)
+    const instance = createSanityInstance({projectId: '', dataset: ''})
+
+    expect(() => boundAction(instance, {})).toThrow(
+      'This API requires a project ID and dataset configured.',
+    )
+  })
+
+  it('should work correctly with a valid dataset source', () => {
+    const storeDefinition = {
+      name: 'SourceStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySource(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    const result = boundAction(instance, {
+      source: {projectId: 'proj2', dataset: 'ds2'},
+    })
+    expect(result).toBe('success')
+  })
+})
+
+describe('bindActionBySourceAndPerspective', () => {
+  it('should throw an error when provided an invalid source', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    expect(() =>
+      boundAction(instance, {
+        source: {invalid: 'source'} as unknown as DocumentSource,
+        perspective: 'drafts',
+      }),
+    ).toThrow('Received invalid source:')
+  })
+
+  it('should throw an error when no source provided and projectId/dataset are missing', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({projectId: '', dataset: ''})
+
+    expect(() => boundAction(instance, {perspective: 'drafts'})).toThrow(
+      'This API requires a project ID and dataset configured.',
+    )
+  })
+
+  it('should work correctly with a valid dataset source and explicit perspective', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    const result = boundAction(instance, {
+      source: {projectId: 'proj2', dataset: 'ds2'},
+      perspective: 'drafts',
+    })
+    expect(result).toBe('success')
+  })
+
+  it('should work correctly with valid dataset source and no perspective (falls back to drafts)', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    const result = boundAction(instance, {
+      source: {projectId: 'proj1', dataset: 'ds1'},
+    })
+    expect(result).toBe('success')
+  })
+
+  it('should use instance.config.perspective when options.perspective is not provided', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((context) => context.key)
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({
+      projectId: 'proj1',
+      dataset: 'ds1',
+      perspective: 'published',
+    })
+
+    const result = boundAction(instance, {})
+    expect(result).toEqual(
+      expect.objectContaining({
+        name: 'proj1.ds1:published',
+        perspective: 'published',
+      }),
+    )
+  })
+
+  it('should create separate store instances for different perspectives', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((context, _options, increment: number) => {
+      context.state.counter += increment
+      return context.state.counter
+    })
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    // Use unique project/dataset so we don't reuse stores from other tests
+    const instance = createSanityInstance({
+      projectId: 'perspective-isolation',
+      dataset: 'ds1',
+    })
+
+    const resultDrafts = boundAction(instance, {perspective: 'drafts'}, 3)
+    const resultPublished = boundAction(instance, {perspective: 'published'}, 4)
+
+    expect(resultDrafts).toBe(3)
+    expect(resultPublished).toBe(4)
+    // Two stores: one for drafts, one for published
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(2)
+  })
+
+  it('should create separate store instance for release perspective', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((_context) => 'success')
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
+
+    const result = boundAction(instance, {
+      perspective: {releaseName: 'release1'},
+    })
+    expect(result).toBe('success')
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledWith(
+      instance,
+      expect.objectContaining({
+        name: 'proj1.ds1:release1',
+        perspective: {releaseName: 'release1'},
+      }),
+      storeDefinition,
+    )
+  })
+
+  it('should reuse same store when same source and perspective are used', () => {
+    const storeDefinition = {
+      name: 'PerspectiveStore',
+      getInitialState: () => ({counter: 0}),
+    }
+    const action = vi.fn((context, _options, increment: number) => {
+      context.state.counter += increment
+      return context.state.counter
+    })
+    const boundAction = bindActionBySourceAndPerspective(storeDefinition, action)
+    // Use unique project/dataset so we don't reuse stores from other tests
+    const instance = createSanityInstance({
+      projectId: 'perspective-reuse',
+      dataset: 'ds1',
+    })
+
+    const result1 = boundAction(instance, {perspective: 'drafts'}, 2)
+    const result2 = boundAction(instance, {perspective: 'drafts'}, 3)
+
+    expect(result1).toBe(2)
+    expect(result2).toBe(5)
+    expect(vi.mocked(createStoreInstance)).toHaveBeenCalledTimes(1)
+  })
+})

package/src/store/createActionBinder.ts

@@ -1,15 +1,27 @@
+import {type ClientPerspective} from '@sanity/client'
+
 import {
+  type DatasetHandle,
   type DocumentSource,
   isCanvasSource,
   isDatasetSource,
   isMediaLibrarySource,
+  type ReleasePerspective,
 } from '../config/sanityConfig'
+import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
 import {type SanityInstance} from './createSanityInstance'
 import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
 import {type StoreContext, type StoreDefinition} from './defineStore'
 
-export type BoundDatasetKey = {
+export interface BoundSourceKey {
+  name: string
+  source: DocumentSource
+}
+export interface BoundPerspectiveKey extends BoundSourceKey {
+  perspective: ClientPerspective | ReleasePerspective
+}
+export interface BoundDatasetKey {
   name: string
   projectId: string
   dataset: string
@@ -154,32 +166,98 @@ export const bindActionByDataset = createActionBinder<
   return {name: `${projectId}.${dataset}`, projectId, dataset}
 })
 
-/**
- * Binds an action to a store that's scoped to a specific document source.
- **/
-export const bindActionBySource = createActionBinder<
-  {name: string},
-  [{source?: DocumentSource}, ...unknown[]]
->((instance, {source}) => {
+const createSourceKey = (instance: SanityInstance, source?: DocumentSource): BoundSourceKey => {
+  let name: string | undefined
+  let sourceForKey: DocumentSource | undefined
   if (source) {
-    let id: string | undefined
+    sourceForKey = source
     if (isDatasetSource(source)) {
-      id = `${source.projectId}.${source.dataset}`
+      name = `${source.projectId}.${source.dataset}`
     } else if (isMediaLibrarySource(source)) {
-      id = `media-library:${source.mediaLibraryId}`
+      name = `media-library:${source.mediaLibraryId}`
     } else if (isCanvasSource(source)) {
-      id = `canvas:${source.canvasId}`
+      name = `canvas:${source.canvasId}`
+    } else {
+      throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
     }
-
-    if (!id) throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
-    return {name: id}
+    return {name, source: sourceForKey}
   }
-  const {projectId, dataset} = instance.config
 
+  // TODO: remove reference to instance.config when we get to v3
+  const {projectId, dataset} = instance.config
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
   }
-  return {name: `${projectId}.${dataset}`}
+  return {name: `${projectId}.${dataset}`, source: {projectId, dataset}}
+}
+
+/**
+ * Binds an action to a store that's scoped to a specific document source.
+ **/
+export const bindActionBySource = createActionBinder<
+  BoundSourceKey,
+  [{source?: DocumentSource}, ...unknown[]]
+>((instance, {source}) => {
+  return createSourceKey(instance, source)
+})
+
+/**
+ * Binds an action to a store that's scoped to a specific document source and perspective.
+ *
+ * @remarks
+ * This creates actions that operate on state isolated to a specific document source and perspective.
+ * Different document sources and perspectives will have separate states.
+ *
+ * This is mostly useful for stores that do batch fetching operations, since the query store
+ * can isolate single queries by perspective.
+ *
+ * @throws Error if source or perspective is missing from the Sanity instance config
+ *
+ * @example
+ * ```ts
+ * // Define a store
+ * const documentStore = defineStore<DocumentState>({
+ *   name: 'Document',
+ *   getInitialState: () => ({ documents: {} }),
+ *   // ...
+ * })
+ *
+ * // Create source-and-perspective-specific actions
+ * export const fetchDocuments = bindActionBySourceAndPerspective(
+ *   documentStore,
+ *   ({instance, state}, documentId) => {
+ *     // This state is isolated to the specific document source and perspective
+ *     // ...fetch logic...
+ *   }
+ * )
+ *
+ * // Usage
+ * fetchDocument(sanityInstance, 'doc123')
+ * ```
+ */
+export const bindActionBySourceAndPerspective = createActionBinder<
+  BoundPerspectiveKey,
+  [DatasetHandle, ...unknown[]]
+>((instance, options): BoundPerspectiveKey => {
+  const {source, perspective} = options
+  // TODO: remove reference to instance.config.perspective when we get to v3
+  const utilizedPerspective = perspective ?? instance.config.perspective ?? 'drafts'
+  let perspectiveKey: string
+  if (isReleasePerspective(utilizedPerspective)) {
+    perspectiveKey = utilizedPerspective.releaseName
+  } else if (typeof utilizedPerspective === 'string') {
+    perspectiveKey = utilizedPerspective
+  } else {
+    // "StackablePerspective", shouldn't be a common case, but just in case
+    perspectiveKey = JSON.stringify(utilizedPerspective)
+  }
+  const sourceKey = createSourceKey(instance, source)
+
+  return {
+    name: `${sourceKey.name}:${perspectiveKey}`,
+    source: sourceKey.source,
+    perspective: utilizedPerspective,
+  }
 })
 
 /**

package/src/store/createSanityInstance.ts

@@ -100,7 +100,9 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
     projectId: config.projectId,
     dataset: config.dataset,
     perspective: config.perspective,
-    studioMode: config.studioMode?.enabled,
+    hasStudioConfig: !!config.studio,
+    hasStudioTokenSource: !!config.studio?.auth?.token,
+    legacyStudioMode: config.studioMode?.enabled,
     hasAuthProviders: !!config.auth?.providers,
     hasAuthToken: !!config.auth?.token,
   })