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

package/src/comlink/controller/actions/getOrCreateChannel.ts

@@ -1,7 +1,7 @@
 import {type ChannelInput, type ChannelInstance} from '@sanity/comlink'
-import {isEqual} from 'lodash-es'
 
 import {type StoreContext} from '../../../store/defineStore'
+import {isDeepEqual} from '../../../utils/object'
 import {type FrameMessage, type WindowMessage} from '../../types'
 import {type ComlinkControllerState} from '../comlinkControllerStore'
 
@@ -25,7 +25,7 @@ export const getOrCreateChannel = (
 
   // limit channels to one per name
   if (existing) {
-    if (!isEqual(existing.options, options)) {
+    if (!isDeepEqual(existing.options, options)) {
       throw new Error(`Channel "${options.name}" already exists with different options`)
     }
 

package/src/comlink/controller/actions/getOrCreateController.test.ts

@@ -21,7 +21,10 @@ describe('getOrCreateController', () => {
   let state: ReturnType<typeof createStoreState<ComlinkControllerState>>
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({
+      projectId: 'test-project-id',
+      dataset: 'test-dataset',
+    })
 
     state = createStoreState<ComlinkControllerState>({
       controller: null,

package/src/comlink/controller/actions/releaseChannel.test.ts

@@ -29,7 +29,7 @@ describe('releaseChannel', () => {
   let releaseChannel: (inst: SanityInstance, channelName: string) => void
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
     store = createStoreInstance(instance, key, comlinkControllerStore)
 
     const bind =

package/src/comlink/controller/comlinkControllerStore.test.ts

@@ -16,7 +16,10 @@ describe('comlinkControllerStore', () => {
   let instance: SanityInstance
   beforeEach(() => {
     vi.resetModules()
-    instance = createSanityInstance()
+    instance = createSanityInstance({
+      projectId: 'test-project-id',
+      dataset: 'test-dataset',
+    })
   })
 
   afterEach(() => {

package/src/comlink/node/actions/getOrCreateNode.test.ts

@@ -22,16 +22,22 @@ const nodeConfig = {
 }
 
 describe('getOrCreateNode', () => {
-  const instance = createSanityInstance()
+  const instance = createSanityInstance({
+    projectId: 'test-project-id',
+    dataset: 'test-dataset',
+  })
   let state: ReturnType<typeof createStoreState<ComlinkNodeState>>
-  let mockNode: Partial<Node<WindowMessage, FrameMessage>> & {
+  let mockNode: {
     start: ReturnType<typeof vi.fn>
     stop: ReturnType<typeof vi.fn>
+    onStatus: ReturnType<typeof vi.fn>
   }
 
   beforeEach(() => {
     mockNode = {start: vi.fn(), stop: vi.fn(), onStatus: vi.fn()}
-    vi.mocked(comlink.createNode).mockReturnValue(mockNode as Node<WindowMessage, FrameMessage>)
+    vi.mocked(comlink.createNode).mockReturnValue(
+      mockNode as unknown as Node<WindowMessage, FrameMessage>,
+    )
     state = createStoreState<ComlinkNodeState>({nodes: new Map(), subscriptions: new Map()})
     vi.clearAllMocks()
   })

package/src/comlink/node/actions/getOrCreateNode.ts

@@ -1,7 +1,7 @@
 import {createNode, type Node, type NodeInput} from '@sanity/comlink'
-import {isEqual} from 'lodash-es'
 
 import {type StoreContext} from '../../../store/defineStore'
+import {isDeepEqual} from '../../../utils/object'
 import {type FrameMessage, type WindowMessage} from '../../types'
 import {type ComlinkNodeState} from '../comlinkNodeStore'
 
@@ -14,7 +14,7 @@ export const getOrCreateNode = (
 
   // limit nodes to one per name
   if (existing) {
-    if (!isEqual(existing.options, options)) {
+    if (!isDeepEqual(existing.options, options)) {
       throw new Error(`Node "${options.name}" already exists with different options`)
     }
 

package/src/comlink/node/actions/releaseNode.test.ts

@@ -15,14 +15,17 @@ const nodeConfig = {
 describe('releaseNode', () => {
   let instance: SanityInstance
   let state: ReturnType<typeof createStoreState<ComlinkNodeState>>
-  let mockNode: Partial<Node<WindowMessage, FrameMessage>> & {
+  let mockNode: {
     start: ReturnType<typeof vi.fn>
     stop: ReturnType<typeof vi.fn>
     onStatus: ReturnType<typeof vi.fn>
   }
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({
+      projectId: 'test-project-id',
+      dataset: 'test-dataset',
+    })
     mockNode = {start: vi.fn(), stop: vi.fn(), onStatus: vi.fn()}
     state = createStoreState<ComlinkNodeState>({nodes: new Map(), subscriptions: new Map()})
     vi.clearAllMocks()
@@ -36,7 +39,7 @@ describe('releaseNode', () => {
     // Set up a node in the state
     const nodes = new Map()
     nodes.set('test-node', {
-      node: mockNode as Node<WindowMessage, FrameMessage>,
+      node: mockNode as unknown as Node<WindowMessage, FrameMessage>,
       options: nodeConfig,
     })
     state.set('setup', {nodes})
@@ -55,7 +58,7 @@ describe('releaseNode', () => {
     const statusUnsub = vi.fn()
     const nodes = new Map()
     nodes.set('test-node', {
-      node: mockNode as Node<WindowMessage, FrameMessage>,
+      node: mockNode as unknown as Node<WindowMessage, FrameMessage>,
       options: nodeConfig,
       statusUnsub,
     })

package/src/comlink/node/comlinkNodeStore.test.ts

@@ -1,5 +1,5 @@
 import {type Node} from '@sanity/comlink'
-import {beforeEach, describe, expect, it, vi} from 'vitest'
+import {beforeEach, describe, expect, it} from 'vitest'
 
 import {createSanityInstance, type SanityInstance} from '../../store/createSanityInstance'
 import {createStoreState} from '../../store/createStoreState'
@@ -10,7 +10,7 @@ describe('nodeStore', () => {
   let instance: SanityInstance
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test-project-id', dataset: 'test-dataset'})
   })
 
   it('should have correct initial state', () => {

package/src/comlink/node/getNodeState.test.ts

@@ -23,7 +23,7 @@ describe('getNodeState', () => {
   let instance: ReturnType<typeof createSanityInstance>
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
   })
 
   afterEach(() => {

package/src/comlink/node/getNodeState.ts

@@ -3,6 +3,7 @@ import {createSelector} from 'reselect'
 
 import {bindActionGlobally} from '../../store/createActionBinder'
 import {createStateSourceAction, type SelectorContext} from '../../store/createStateSourceAction'
+import {setCleanupTimeout} from '../../utils/setCleanupTimeout'
 import {type FrameMessage, type WindowMessage} from '../types'
 import {
   type ComlinkNodeState,
@@ -57,7 +58,7 @@ export const getNodeState = bindActionGlobally(
       subs.add(subscriberId)
 
       return () => {
-        setTimeout(() => {
+        setCleanupTimeout(() => {
           const activeSubs = state.get().subscriptions.get(nodeName)
           if (activeSubs) {
             activeSubs.delete(subscriberId)

package/src/config/__tests__/handles.test.ts

@@ -1,24 +1,30 @@
 import {describe, expect, it} from 'vitest'
 
-import {createDocumentHandle, createDocumentTypeHandle, createResourceHandle} from '../handles'
+import {
+  createDatasetHandle,
+  createDocumentHandle,
+  createDocumentTypeHandle,
+  createProjectHandle,
+} from '../handles'
 
 describe('handle creation functions', () => {
+  it('createProjectHandle returns input', () => {
+    const input = {projectId: 'test'}
+    expect(createProjectHandle(input)).toBe(input)
+  })
+
+  it('createDatasetHandle returns input', () => {
+    const input = {projectId: 'test', dataset: 'prod'}
+    expect(createDatasetHandle(input)).toBe(input)
+  })
+
   it('createDocumentTypeHandle returns input', () => {
-    const input = {documentType: 'movie', resource: {projectId: 'p', dataset: 'd'}}
+    const input = {documentType: 'movie'}
     expect(createDocumentTypeHandle(input)).toBe(input)
   })
 
   it('createDocumentHandle returns input', () => {
-    const input = {
-      documentType: 'movie',
-      documentId: '123',
-      resource: {projectId: 'p', dataset: 'd'},
-    }
+    const input = {documentType: 'movie', documentId: '123'}
     expect(createDocumentHandle(input)).toBe(input)
   })
-
-  it('createResourceHandle returns input', () => {
-    const input = {resource: {projectId: 'p', dataset: 'd'}}
-    expect(createResourceHandle(input)).toBe(input)
-  })
 })

package/src/config/handles.ts

@@ -1,4 +1,9 @@
-import {type DocumentHandle, type DocumentTypeHandle, type ResourceHandle} from './sanityConfig'
+import {
+  type DatasetHandle,
+  type DocumentHandle,
+  type DocumentTypeHandle,
+  type ProjectHandle,
+} from './sanityConfig'
 
 /**
  * Creates or validates a `DocumentHandle` object.
@@ -35,15 +40,28 @@ export function createDocumentTypeHandle<
 }
 
 /**
- * Creates or validates a `ResourceHandle` object.
- * Ensures the provided object conforms to the `ResourceHandle` interface.
- * @param handle - The object containing resource identification properties.
- * @returns The validated `ResourceHandle` object.
+ * Creates or validates a `ProjectHandle` object.
+ * Ensures the provided object conforms to the `ProjectHandle` interface.
+ * @param handle - The object containing project identification properties.
+ * @returns The validated `ProjectHandle` object.
  * @public
  */
-export function createResourceHandle<
+export function createProjectHandle<TProjectId extends string = string>(
+  handle: ProjectHandle<TProjectId>,
+): ProjectHandle<TProjectId> {
+  return handle
+}
+
+/**
+ * Creates or validates a `DatasetHandle` object.
+ * Ensures the provided object conforms to the `DatasetHandle` interface.
+ * @param handle - The object containing dataset identification properties.
+ * @returns The validated `DatasetHandle` object.
+ * @public
+ */
+export function createDatasetHandle<
   TDataset extends string = string,
   TProjectId extends string = string,
->(handle: ResourceHandle<TProjectId, TDataset>): ResourceHandle<TProjectId, TDataset> {
+>(handle: DatasetHandle<TDataset, TProjectId>): DatasetHandle<TDataset, TProjectId> {
   return handle
 }

package/src/config/sanityConfig.ts

@@ -40,12 +40,14 @@ export interface StudioConfig {
      */
     token?: TokenSource
   }
-  /**
-   * The project ID for this Studio workspace.
-   * Used to derive the localStorage key for studio auth token discovery
-   * (`__studio_auth_token_<projectId>`) and for project-specific API hostname requests.
-   */
-  projectId?: string
+}
+
+/**
+ * Represents the minimal configuration required to identify a Sanity project.
+ * @public
+ */
+export interface ProjectHandle<TProjectId extends string = string> {
+  projectId?: TProjectId
 }
 
 /**
@@ -60,27 +62,25 @@ export type ReleasePerspective = {
  * @public
  */
 export interface PerspectiveHandle {
-  /**
-   * The perspective to use for this operation.
-   * Note that the SDK stacks perspectives for you when querying.
-   * The SDK automatically fetches all of your content releases, and orders them the way the Sanity Studio does: usually by scheduled date, with ASAP releases coming first.
-   * @public
-   */
-  perspective?: Exclude<ClientPerspective, readonly unknown[]> | ReleasePerspective
+  perspective?: ClientPerspective | ReleasePerspective
 }
 
 /**
  * @public
  */
-export interface ResourceHandle<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> extends PerspectiveHandle {
+export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
+  extends ProjectHandle<TProjectId>, PerspectiveHandle {
+  dataset?: TDataset
   /**
+   * @beta
    * Explicit resource object to use for this operation.
-   * @public
    */
-  resource: DocumentResource<TProjectId, TDataset>
+  resource?: DocumentResource
+  /**
+   * @deprecated Use `resource` instead.
+   * @beta
+   */
+  source?: DocumentResource
 }
 
 /**
@@ -93,7 +93,7 @@ export interface DocumentTypeHandle<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends ResourceHandle<TDataset, TProjectId> {
+> extends DatasetHandle<TDataset, TProjectId> {
   documentId?: string
   documentType: TDocumentType
   /**
@@ -119,42 +119,22 @@ export interface DocumentHandle<
 }
 
 /**
- * The key used to identify the default resource in a resources map.
- * When no `resource` or `resourceName` is specified, the SDK resolves
- * the resource registered under this name.
- *
- * @public
+ * Identifies a release within a Sanity dataset and project. `releaseId` is the
+ * `name` parameter on the release document (e.g. `{name: 'r41035a4'}`).
+ * The underlying release document ID is `_.releases.<releaseId>`.
+ * It's also the `id` parameter sent to the Actions API.
+ * (This type doesn't need to have ProjectId / Dataset generics since it's always the same shape)
+ * @beta
  */
-export const DEFAULT_RESOURCE_NAME = 'default'
+export interface ReleaseHandle extends DatasetHandle {
+  releaseId: string
+}
 
 /**
- * Represents the complete configuration for a Sanity SDK instance.
- *
- * Most apps configure resources via the `resources` prop on `SanityApp`:
- *
- * @example Typical React usage
- * ```tsx
- * <SanityApp
- *   resources={{ default: { projectId: 'abc123', dataset: 'production' } }}
- *   fallback={<Loading />}
- * >
- *   <App />
- * </SanityApp>
- * ```
- *
- * The `defaultResource` field is set automatically by the React layer from
- * `resources['default']`. It can also be set directly when using the core
- * SDK without React (e.g. in a Node.js script):
- *
- * @example Direct core usage (without React)
- * ```ts
- * const instance = createSanityInstance({
- *   defaultResource: { projectId: 'abc123', dataset: 'production' },
- * })
- * ```
+ * Represents the complete configuration for a Sanity SDK instance
  * @public
  */
-export interface SanityConfig extends PerspectiveHandle {
+export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
   /**
    * Authentication configuration for the instance
    */
@@ -168,58 +148,61 @@ export interface SanityConfig extends PerspectiveHandle {
    * `SDKStudioContext` provider. Can also be set explicitly for programmatic use.
    */
   studio?: StudioConfig
+
   /**
-   * The default document resource for this instance. Used by bound actions
-   * when no explicit resource is provided.
-   *
-   * @public
+   * Studio mode configuration for use of the SDK in a Sanity Studio.
+   * @remarks Controls whether studio mode features are enabled.
+   * @deprecated Use `studio` instead, which provides richer integration
+   * with the Studio's workspace (auth token sync, etc.).
+   */
+  studioMode?: {
+    enabled: boolean
+  }
+
+  /**
+   * @beta
+   * A list of named resources to use for this instance.
+   */
+  resources?: Record<string, DocumentResource>
+  /**
+   * @deprecated Use `resources` instead.
+   * @beta
    */
-  defaultResource?: DocumentResource
+  sources?: Record<string, DocumentResource>
 }
 
 /**
- * A document resource identifies where data is stored and queried from.
- * Can be a dataset (project + dataset pair), a media library, or a canvas.
+ * A document resource can be used for querying.
+ * This will soon be the default way to identify where you are querying from.
  *
- * @public
+ * @beta
  */
-export type DocumentResource<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> = DatasetResource<TProjectId, TDataset> | MediaLibraryResource | CanvasResource
+export type DocumentResource = DatasetResource | MediaLibraryResource | CanvasResource
 
 /**
- * A resource that targets a specific project and dataset.
- * @public
+ * @beta
  */
-export type DatasetResource<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> = {projectId: TProjectId; dataset: TDataset}
+export type DatasetResource = {projectId: string; dataset: string}
 
 /**
- * A resource that targets a media library.
- * @public
+ * @beta
  */
 export type MediaLibraryResource = {mediaLibraryId: string}
 
 /**
- * A resource that targets a canvas.
- * @public
+ * @beta
  */
 export type CanvasResource = {canvasId: string}
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link DatasetResource}.
- * @public
+ * @beta
  */
 export function isDatasetResource(resource: DocumentResource): resource is DatasetResource {
   return 'projectId' in resource && 'dataset' in resource
 }
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link MediaLibraryResource}.
- * @public
+ * @beta
  */
 export function isMediaLibraryResource(
   resource: DocumentResource,
@@ -228,9 +211,56 @@ export function isMediaLibraryResource(
 }
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link CanvasResource}.
- * @public
+ * @beta
  */
 export function isCanvasResource(resource: DocumentResource): resource is CanvasResource {
   return 'canvasId' in resource
 }
+
+/**
+ * @deprecated Use `DocumentResource` instead.
+ * @beta
+ */
+export type DocumentSource = DocumentResource
+
+/**
+ * @deprecated Use `DatasetResource` instead.
+ * @beta
+ */
+export type DatasetSource = DatasetResource
+
+/**
+ * @deprecated Use `MediaLibraryResource` instead.
+ * @beta
+ */
+export type MediaLibrarySource = MediaLibraryResource
+
+/**
+ * @deprecated Use `CanvasResource` instead.
+ * @beta
+ */
+export type CanvasSource = CanvasResource
+
+/**
+ * @deprecated Use `isDatasetResource` instead.
+ * @beta
+ */
+export function isDatasetSource(source: DocumentSource): source is DatasetSource {
+  return isDatasetResource(source)
+}
+
+/**
+ * @deprecated Use `isMediaLibraryResource` instead.
+ * @beta
+ */
+export function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource {
+  return isMediaLibraryResource(source)
+}
+
+/**
+ * @deprecated Use `isCanvasResource` instead.
+ * @beta
+ */
+export function isCanvasSource(source: DocumentSource): source is CanvasSource {
+  return isCanvasResource(source)
+}

package/src/datasets/datasets.test.ts

@@ -11,7 +11,7 @@ vi.mock('../client/clientStore')
 
 describe('datasets', () => {
   it('calls the `client.observable.datasets.list` method on the client and returns the result', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
     const datasets = [{id: 'a'}, {id: 'b'}]
     const list = vi.fn().mockReturnValue(of(datasets))
 
@@ -25,7 +25,7 @@ describe('datasets', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveDatasets(instance, {projectId: 'p'})
+    const result = await resolveDatasets(instance)
     expect(result).toEqual(datasets)
     expect(list).toHaveBeenCalled()
   })

package/src/datasets/datasets.ts

@@ -1,6 +1,7 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
+import {type ProjectHandle} from '../config/sanityConfig'
 import {createFetcherStore} from '../utils/createFetcherStore'
 
 const API_VERSION = 'v2025-02-19'
@@ -8,13 +9,18 @@ const API_VERSION = 'v2025-02-19'
 /** @public */
 export const datasets = createFetcherStore({
   name: 'Datasets',
-  getKey: (_instance, options: {projectId: string}) => {
-    return options.projectId
+  getKey: (instance, options?: ProjectHandle) => {
+    const projectId = options?.projectId ?? instance.config.projectId
+    if (!projectId) {
+      throw new Error('A projectId is required to use the project API.')
+    }
+    return projectId
   },
-  fetcher: (instance) => (options: {projectId: string}) => {
+  fetcher: (instance) => (options?: ProjectHandle) => {
     return getClientState(instance, {
       apiVersion: API_VERSION,
-      projectId: options.projectId,
+      // non-null assertion is fine because we check above
+      projectId: (options?.projectId ?? instance.config.projectId)!,
       useProjectHostname: true,
     }).observable.pipe(switchMap((client) => client.observable.datasets.list()))
   },