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

package/src/project/project.ts

@@ -1,35 +1,148 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {createFetcherStore} from '../utils/createFetcherStore'
+import {type ProjectHandle} from '../config/sanityConfig'
+import {projects} from '../projects/projects'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {defineFetcher} from '../store/fetcherStore'
+import {buildQuery} from '../utils/buildQuery'
 
 const API_VERSION = 'v2025-02-19'
 
 /** @public */
-export type ProjectHandle = {
-  projectId: string
-}
-const project = createFetcherStore({
-  name: 'Project',
-  getKey: (_instance, options: ProjectHandle) => {
-    const projectId = options?.projectId
-    if (!projectId) {
-      throw new Error('A projectId is required to use the project API.')
-    }
-    return projectId
-  },
-  fetcher: (instance) => (options: ProjectHandle) => {
-    const projectId = options.projectId
-
-    return getClientState(instance, {
-      apiVersion: API_VERSION,
-      scope: 'global',
-      projectId,
-    }).observable.pipe(switchMap((client) => client.observable.projects.getById(projectId!)))
-  },
-})
+export interface ProjectMemberRole {
+  name: string
+  title: string
+  description: string
+}
 
 /** @public */
-export const getProjectState = project.getState
+export interface ProjectMember {
+  id: string
+  createdAt: string
+  updatedAt: string
+  isCurrentUser: boolean
+  isRobot: boolean
+  roles: ProjectMemberRole[]
+}
+
+/** @public */
+export interface ProjectMetadata {
+  color?: string
+  externalStudioHost?: string
+  initialTemplate?: string
+  cliInitializedAt?: string
+  integration: 'manage' | 'cli'
+}
+
+/**
+ * The base fields returned from `/projects` for every project.
+ * @public
+ */
+export interface ProjectBase {
+  id: string
+  displayName: string
+  studioHost: string | null
+  organizationId: string
+  metadata: ProjectMetadata
+  isBlocked: boolean
+  isDisabled: boolean
+  isDisabledByUser: boolean
+  activityFeedEnabled: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * A `Project` with `members` and/or `features` conditionally included
+ * based on the query options used to fetch it.
+ * @public
+ */
+export type Project<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = ProjectBase &
+  // `boolean extends T` is non-distributive — true only when T is the wide
+  // `boolean`, in which case the field is optional. Literal `true`/`false`
+  // fall through to the strict branch.
+  (boolean extends IncludeMembers
+    ? {members?: ProjectMember[]}
+    : IncludeMembers extends true
+      ? {members: ProjectMember[]}
+      : unknown) &
+  (boolean extends IncludeFeatures
+    ? {features?: string[]}
+    : IncludeFeatures extends true
+      ? {features: string[]}
+      : unknown)
+
 /** @public */
-export const resolveProject = project.resolveState
+export interface ProjectOptions<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> extends ProjectHandle {
+  includeMembers?: IncludeMembers
+  includeFeatures?: IncludeFeatures
+}
+
+function normalizeProjectOptions(options?: ProjectOptions<boolean, boolean>) {
+  return {
+    includeMembers: options?.includeMembers ?? true,
+    includeFeatures: options?.includeFeatures ?? true,
+  }
+}
+
+function resolveProjectId(instance: SanityInstance, options?: ProjectOptions<boolean, boolean>) {
+  const projectId = options?.projectId ?? instance.config.projectId
+  if (!projectId) {
+    throw new Error('A projectId is required to use the project API.')
+  }
+  return projectId
+}
+
+/** @internal */
+export function getProjectCacheKey(
+  instance: SanityInstance,
+  options?: ProjectOptions<boolean, boolean>,
+): string {
+  const projectId = resolveProjectId(instance, options)
+  const {includeMembers, includeFeatures} = normalizeProjectOptions(options)
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  return `project:${projectId}${membersKey}${featuresKey}`
+}
+
+/**
+ * Fetcher for a single project (`GET /projects/:id`), on the shared fetcher
+ * cache. Pre-seeds from the default {@link projects} list entry when it can
+ * satisfy the read — the default list carries features but not members, so
+ * only `includeMembers: false` reads seed.
+ *
+ * @internal
+ */
+export const project = defineFetcher<
+  [options?: ProjectOptions<boolean, boolean>],
+  Project<boolean, boolean>
+>({
+  name: 'project',
+  getKey: getProjectCacheKey,
+  fetch: (instance) => (options) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable.request<Project<boolean, boolean>>({
+          uri: `/projects/${resolveProjectId(instance, options)}`,
+          query: buildQuery(normalizeProjectOptions(options)),
+          tag: 'projects.get',
+        }),
+      ),
+    ),
+  tags: (data) => [{type: 'project', id: data.id}],
+  initialData: (instance, options) => {
+    if (normalizeProjectOptions(options).includeMembers) return undefined
+    const snapshot = projects.getState(instance).getCurrent()
+    if (snapshot.status !== 'success') return undefined
+    const projectId = resolveProjectId(instance, options)
+    const match = snapshot.data.find((item) => item.id === projectId)
+    return match && {data: match, dataUpdatedAt: snapshot.dataUpdatedAt}
+  },
+})

package/src/projection/getProjectionState.test.ts

@@ -1,7 +1,6 @@
 import {NEVER} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {type DocumentResource} from '../config/sanityConfig'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StoreState} from '../store/createStoreState'
 import {hashString} from '../utils/hashString'
@@ -31,8 +30,7 @@ vi.mock('./subscribeToStateAndFetchBatches.ts')
 
 describe('getProjectionState', () => {
   let instance: SanityInstance
-  const resource: DocumentResource = {projectId: 'p', dataset: 'd'}
-  const docHandle = {documentId: 'exampleId', documentType: 'exampleType', resource}
+  const docHandle = {documentId: 'exampleId', documentType: 'exampleType'}
   const projection1 = '{exampleProjection1}'
   const hash1 = hashString(projection1)
   const projection2 = '{exampleProjection2}'
@@ -50,7 +48,7 @@ describe('getProjectionState', () => {
       return NEVER.subscribe()
     })
 
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'exampleProject', dataset: 'exampleDataset'})
     vi.useFakeTimers() // Enable fake timers for each test
   })
 
@@ -128,7 +126,7 @@ describe('getProjectionState', () => {
     expect(state.get().subscriptions).toEqual({})
     expect(state.get().documentProjections).toEqual({})
 
-    const unsubscribe1 = projectionState1.subscribe(vi.fn()) // Should use ID 3
+    const unsubscribe1 = projectionState1.subscribe(vi.fn()) // Should use ID 2
     expect(state.get().subscriptions).toEqual({
       [docHandle.documentId]: {[hash1]: {testSubId_2: true}},
     })
@@ -136,7 +134,7 @@ describe('getProjectionState', () => {
       [docHandle.documentId]: {[hash1]: projection1},
     })
 
-    const unsubscribe2 = projectionState2.subscribe(vi.fn()) // Should use ID 4
+    const unsubscribe2 = projectionState2.subscribe(vi.fn()) // Should use ID 3
     expect(state.get().subscriptions).toEqual({
       [docHandle.documentId]: {
         [hash1]: {testSubId_2: true},
@@ -150,10 +148,12 @@ describe('getProjectionState', () => {
       },
     })
 
-    const unsubscribe3 = projectionState1.subscribe(vi.fn()) // Should use ID 5
+    // should share ID 2 from the first subscription -- we only care if ANY subscription exists
+    // so we can include the document / projection in a bulk fetch
+    const unsubscribe3 = projectionState1.subscribe(vi.fn())
     expect(state.get().subscriptions).toEqual({
       [docHandle.documentId]: {
-        [hash1]: {testSubId_2: true, testSubId_4: true},
+        [hash1]: {testSubId_2: true},
         [hash2]: {testSubId_3: true},
       },
     })
@@ -167,23 +167,20 @@ describe('getProjectionState', () => {
     })
 
     // --- Test Unsubscribe ---
-    unsubscribe1() // Unsubscribes ID 3
-    expect(state.get().subscriptions[docHandle.documentId]?.[hash1]).toEqual({
-      testSubId_2: true,
-      testSubId_4: true,
-    })
+    unsubscribe1() // Unsubscribes first subscription consumer
+    expect(state.get().subscriptions[docHandle.documentId]?.[hash1]).toEqual({testSubId_2: true})
     vi.advanceTimersByTime(PROJECTION_STATE_CLEAR_DELAY)
-    expect(state.get().subscriptions[docHandle.documentId]?.[hash1]).toEqual({testSubId_4: true})
+    expect(state.get().subscriptions[docHandle.documentId]?.[hash1]).toEqual({testSubId_2: true})
     expect(state.get().documentProjections[docHandle.documentId]?.[hash1]).toEqual(projection1)
 
-    unsubscribe3() // Unsubscribes ID 5
+    unsubscribe3() // Also unsubscibes first projection subscription, should be removed
     vi.advanceTimersByTime(PROJECTION_STATE_CLEAR_DELAY)
     expect(state.get().subscriptions[docHandle.documentId]?.[hash1]).toBeUndefined()
     expect(state.get().documentProjections[docHandle.documentId]?.[hash1]).toBeUndefined()
     expect(state.get().subscriptions[docHandle.documentId]?.[hash2]).toEqual({testSubId_3: true})
     expect(state.get().documentProjections[docHandle.documentId]?.[hash2]).toEqual(projection2)
 
-    unsubscribe2() // Unsubscribes ID 4
+    unsubscribe2() // Unsubscribes second projection subscription, should be removed
     vi.advanceTimersByTime(PROJECTION_STATE_CLEAR_DELAY)
     expect(state.get().subscriptions[docHandle.documentId]).toBeUndefined()
     expect(state.get().documentProjections[docHandle.documentId]).toBeUndefined()
@@ -205,14 +202,14 @@ describe('getProjectionState', () => {
     }))
 
     const unsubscribe1 = projectionState.subscribe(vi.fn()) // Should use ID 2
-    const unsubscribe2 = projectionState.subscribe(vi.fn()) // Should use ID 3
+    const unsubscribe2 = projectionState.subscribe(vi.fn()) // Should reuse ID 2
 
     expect(state.get().values[docHandle.documentId]?.[hash]).toEqual({
       data: initialData,
       isPending: true,
     })
 
-    unsubscribe1() // Unsubscribes ID 2
+    unsubscribe1() // Unsubscribes first subscription consumer
     vi.advanceTimersByTime(PROJECTION_STATE_CLEAR_DELAY)
     expect(state.get().values[docHandle.documentId]?.[hash]).toEqual({
       data: initialData,
@@ -221,9 +218,10 @@ describe('getProjectionState', () => {
     expect(Object.keys(state.get().subscriptions[docHandle.documentId]?.[hash] ?? {}).length).toBe(
       1,
     )
-    expect(state.get().subscriptions[docHandle.documentId]?.[hash]).toEqual({testSubId_3: true})
+    // should still have the same subscription ID since we're not unsubscribing the second consumer
+    expect(state.get().subscriptions[docHandle.documentId]?.[hash]).toEqual({testSubId_2: true})
 
-    unsubscribe2() // Unsubscribes ID 3
+    unsubscribe2() // Unsubscribes second subscription consumer
     expect(state.get().values[docHandle.documentId]?.[hash]).toEqual({
       data: initialData,
       isPending: true,

package/src/projection/getProjectionState.ts

@@ -1,5 +1,5 @@
 import {DocumentId, getPublishedId} from '@sanity/id-utils'
-import {omit} from 'lodash-es'
+import {type SanityProjectionResult} from 'groq'
 
 import {type DocumentHandle} from '../config/sanityConfig'
 import {bindActionByResourceAndPerspective} from '../store/createActionBinder'
@@ -11,6 +11,8 @@ import {
 } from '../store/createStateSourceAction'
 import {hashString} from '../utils/hashString'
 import {insecureRandomId} from '../utils/ids'
+import {omitProperty} from '../utils/object'
+import {setCleanupTimeout} from '../utils/setCleanupTimeout'
 import {projectionStore} from './projectionStore'
 import {type ProjectionStoreState, type ProjectionValuePending} from './types'
 import {PROJECTION_STATE_CLEAR_DELAY, STABLE_EMPTY_PROJECTION, validateProjection} from './util'
@@ -24,6 +26,24 @@ export interface ProjectionOptions<
   projection: TProjection
 }
 
+/**
+ * @beta
+ */
+export function getProjectionState<
+  TProjection extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  options: ProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
+): StateSource<
+  | ProjectionValuePending<
+      SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
+    >
+  | undefined
+>
+
 /**
  * @beta
  */
@@ -91,9 +111,9 @@ export const _getProjectionState = bindActionByResourceAndPerspective(
       }))
 
       return () => {
-        setTimeout(() => {
+        setCleanupTimeout(() => {
           state.set('removeSubscription', (prev): Partial<ProjectionStoreState> => {
-            const documentSubscriptionsForHash = omit(
+            const documentSubscriptionsForHash = omitProperty(
               prev.subscriptions[documentId]?.[projectionHash],
               subscriptionId,
             )

package/src/projection/projectionQuery.ts

@@ -1,7 +1,7 @@
-import {DocumentId} from '@sanity/id-utils'
+import {type ClientPerspective} from '@sanity/client'
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
 
-import {type PerspectiveHandle} from '../config/sanityConfig'
-import {getPublishedId} from '../utils/ids'
+import {type ReleasePerspective} from '../config/sanityConfig'
 import {
   type DocumentProjections,
   type DocumentProjectionValues,
@@ -67,7 +67,7 @@ interface ProcessProjectionQueryOptions {
   ids: Set<string>
   results: ProjectionQueryResult[]
   documentStatuses?: ProjectionStoreState['documentStatuses']
-  perspective: NonNullable<PerspectiveHandle['perspective']>
+  perspective: ClientPerspective | ReleasePerspective
 }
 
 export function processProjectionQuery({
@@ -84,7 +84,7 @@ export function processProjectionQuery({
   } = {}
 
   for (const result of results) {
-    const originalId = getPublishedId(result._id)
+    const originalId = getPublishedId(DocumentId(result._id))
     const hash = result.__projectionHash
 
     if (!ids.has(originalId)) continue

package/src/projection/projectionStore.test.ts

@@ -6,14 +6,6 @@ import {createStoreInstance} from '../store/createStoreInstance'
 import {projectionStore} from './projectionStore'
 import {subscribeToStateAndFetchBatches} from './subscribeToStateAndFetchBatches'
 
-// Mock the module with a factory function
-vi.mock('../common/createLiveEventSubscriber', () => {
-  const mockLiveSubscriber = vi.fn()
-  return {
-    createLiveEventSubscriber: vi.fn(() => mockLiveSubscriber),
-  }
-})
-
 vi.mock('./subscribeToStateAndFetchBatches')
 
 describe('projectionStore', () => {
@@ -24,7 +16,7 @@ describe('projectionStore', () => {
       new Observable(subscriber).subscribe(),
     )
 
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
 
     const {state, dispose} = createStoreInstance(
       instance,

package/src/projection/resolveProjection.test.ts

@@ -23,7 +23,7 @@ describe('resolveProjection', () => {
       } as ProjectionValuePending<Record<string, unknown>>),
     } as StateSource<ProjectionValuePending<Record<string, unknown>>>)
 
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
   })
 
   afterEach(() => {
@@ -34,7 +34,6 @@ describe('resolveProjection', () => {
     const docHandle = createDocumentHandle({
       documentId: 'doc123',
       documentType: 'movie',
-      resource: {projectId: 'p', dataset: 'd'},
     })
     const projection = '{title}'
 

package/src/projection/resolveProjection.ts

@@ -1,3 +1,4 @@
+import {type SanityProjectionResult} from 'groq'
 import {filter, firstValueFrom} from 'rxjs'
 
 import {bindActionByResourceAndPerspective} from '../store/createActionBinder'
@@ -6,6 +7,21 @@ import {getProjectionState, type ProjectionOptions} from './getProjectionState'
 import {projectionStore} from './projectionStore'
 import {type ProjectionValuePending} from './types'
 
+/** @beta */
+export function resolveProjection<
+  TProjection extends string = string,
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+>(
+  instance: SanityInstance,
+  options: ProjectionOptions<TProjection, TDocumentType, TDataset, TProjectId>,
+): Promise<
+  ProjectionValuePending<
+    SanityProjectionResult<TProjection, TDocumentType, `${TProjectId}.${TDataset}`>
+  >
+>
+
 /** @beta */
 export function resolveProjection<TData extends object>(
   instance: SanityInstance,

package/src/projection/subscribeToStateAndFetchBatches.test.ts

@@ -23,7 +23,7 @@ describe('subscribeToStateAndFetchBatches', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     state = createStoreState<ProjectionStoreState>({
       documentProjections: {},
       documentStatuses: {},

package/src/projection/subscribeToStateAndFetchBatches.ts

@@ -1,4 +1,4 @@
-import {isEqual} from 'lodash-es'
+import {DocumentId} from '@sanity/id-utils'
 import {
   combineLatest,
   debounceTime,
@@ -19,6 +19,7 @@ import {
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {type BoundPerspectiveKey} from '../store/createActionBinder'
 import {type StoreContext} from '../store/defineStore'
+import {isDeepEqual} from '../utils/object'
 import {
   createProjectionQuery,
   processProjectionQuery,
@@ -45,18 +46,18 @@ export const subscribeToStateAndFetchBatches = ({
 }: StoreContext<ProjectionStoreState, BoundPerspectiveKey>): Subscription => {
   const documentProjections$ = state.observable.pipe(
     map((s) => s.documentProjections),
-    distinctUntilChanged(isEqual),
+    distinctUntilChanged(isDeepEqual),
   )
 
   const activeDocumentIds$ = state.observable.pipe(
-    map(({subscriptions}) => new Set(Object.keys(subscriptions))),
+    map(({subscriptions}) => new Set(Object.keys(subscriptions).map((id) => DocumentId(id)))),
     distinctUntilChanged(isSetEqual),
   )
 
   const pendingUpdateSubscription = activeDocumentIds$
     .pipe(
       debounceTime(BATCH_DEBOUNCE_TIME),
-      startWith(new Set<string>()),
+      startWith(new Set<DocumentId>()),
       pairwise(),
       tap(([prevIds, currIds]) => {
         const newIds = [...currIds].filter((id) => !prevIds.has(id))
@@ -88,7 +89,7 @@ export const subscribeToStateAndFetchBatches = ({
 
   const queryTrigger$ = combineLatest([activeDocumentIds$, documentProjections$]).pipe(
     debounceTime(BATCH_DEBOUNCE_TIME),
-    distinctUntilChanged(isEqual),
+    distinctUntilChanged(isDeepEqual),
   )
 
   const queryExecutionSubscription = queryTrigger$
@@ -105,10 +106,12 @@ export const subscribeToStateAndFetchBatches = ({
 
         const projectionQuery$ = new Observable<ProjectionQueryResult[]>((observer) => {
           const {getCurrent, observable} = getQueryState<ProjectionQueryResult[]>(instance, {
-            query,
-            params,
-            tag: PROJECTION_TAG,
-            perspective,
+            ...{
+              query,
+              params,
+              tag: PROJECTION_TAG,
+              perspective,
+            },
             resource,
           })
 
@@ -116,11 +119,13 @@ export const subscribeToStateAndFetchBatches = ({
             if (getCurrent() === undefined) {
               return from(
                 resolveQuery<ProjectionQueryResult[]>(instance, {
-                  query,
-                  params,
-                  tag: PROJECTION_TAG,
-                  signal: controller.signal,
-                  perspective,
+                  ...{
+                    query,
+                    params,
+                    tag: PROJECTION_TAG,
+                    signal: controller.signal,
+                    perspective,
+                  },
                   resource,
                 }),
               ).pipe(switchMap(() => observable))
@@ -140,10 +145,12 @@ export const subscribeToStateAndFetchBatches = ({
 
         const statusQuery$ = new Observable<StatusQueryResult[]>((observer) => {
           const {getCurrent, observable} = getQueryState<StatusQueryResult[]>(instance, {
-            query: statusQuery,
-            params: statusParams,
-            tag: PROJECTION_TAG,
-            perspective: 'raw',
+            ...{
+              query: statusQuery,
+              params: statusParams,
+              tag: PROJECTION_TAG,
+              perspective: 'raw',
+            },
             resource,
           })
 
@@ -151,11 +158,13 @@ export const subscribeToStateAndFetchBatches = ({
             if (getCurrent() === undefined) {
               return from(
                 resolveQuery<StatusQueryResult[]>(instance, {
-                  query: statusQuery,
-                  params: statusParams,
-                  tag: PROJECTION_TAG,
-                  signal: controller.signal,
-                  perspective: 'raw',
+                  ...{
+                    query: statusQuery,
+                    params: statusParams,
+                    tag: PROJECTION_TAG,
+                    signal: controller.signal,
+                    perspective: 'raw',
+                  },
                   resource,
                 }),
               ).pipe(switchMap(() => observable))

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

@@ -0,0 +1,32 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type Project, type ProjectMember} from '../project/project'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {projects} from './projects'
+
+const instance = {} as SanityInstance
+
+test('projects.resolveState — resolves the wide-boolean list shape', () => {
+  expectTypeOf(projects.resolveState(instance)).resolves.toEqualTypeOf<
+    Project<boolean, boolean>[]
+  >()
+})
+
+test('Project<boolean, boolean> — members and features are optional', () => {
+  type Item = Project<boolean, boolean>
+  expectTypeOf<Item['members']>().toEqualTypeOf<ProjectMember[] | undefined>()
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[] | undefined>()
+})
+
+test('projects.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(projects.getState(instance)).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Project<boolean, boolean>[]>>
+  >()
+})
+
+test('projects — rejects non-boolean flag values', () => {
+  // @ts-expect-error includeMembers must be a boolean
+  void projects.resolveState(instance, {includeMembers: 'yes'})
+})