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

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/projection/types.ts

@@ -11,6 +11,14 @@ export interface DocumentProjectionValues<TValue extends object = object> {
   [projectionHash: string]: ProjectionValuePending<TValue>
 }
 
+/**
+ * @public
+ * @deprecated
+ * Template literals are a bit too limited, so this type is deprecated.
+ * Use `string` instead. Projection strings are validated at runtime.
+ */
+export type ValidProjection = string
+
 export interface DocumentProjections {
   [projectionHash: string]: string
 }

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'})
+})

package/src/projects/projects.test.ts

@@ -5,7 +5,7 @@ import {afterEach, beforeEach, describe, it} from 'vitest'
 import {getClientState} from '../client/clientStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {resolveProjects} from './projects'
+import {getProjectsCacheKey, projects} from './projects'
 
 vi.mock('../client/clientStore')
 
@@ -13,64 +13,130 @@ describe('projects', () => {
   let instance: SanityInstance
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
   })
 
   afterEach(() => {
     instance.dispose()
   })
 
-  it('calls the `client.observable.projects.list` method on the client and returns the result', async () => {
-    const projects = [{id: 'a'}, {id: 'b'}]
-    const list = vi.fn().mockReturnValue(of(projects))
+  it('calls `client.observable.request` against `/projects` and returns the result', async () => {
+    const list = [{id: 'a'}, {id: 'b'}]
+    const request = vi.fn().mockReturnValue(of(list))
 
     const mockClient = {
-      observable: {
-        projects: {list} as unknown as SanityClient['observable']['projects'],
-      },
+      observable: {request} as unknown as SanityClient['observable'],
     } as SanityClient
 
     vi.mocked(getClientState).mockReturnValue({
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveProjects(instance)
-    expect(result).toEqual(projects)
-    expect(list).toHaveBeenCalledWith({includeMembers: false, organizationId: undefined})
+    const result = await projects.resolveState(instance)
+    expect(result).toEqual(list)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects',
+      query: {includeMembers: 'false', includeFeatures: 'true', onlyExplicitMembership: 'false'},
+      tag: 'projects.list',
+    })
   })
-})
 
-describe('projects cache key generation', () => {
-  it('generates correct cache keys for different parameter combinations', async () => {
-    // Test the getKey function directly by creating a mock store
-    const mockGetKey = (
-      _instance: SanityInstance,
-      options?: {organizationId?: string; includeMembers?: boolean},
-    ) => {
-      const orgKey = options?.organizationId ? `:org:${options.organizationId}` : ''
-      const membersKey = options?.includeMembers === false ? ':no-members' : ''
-      return `projects${orgKey}${membersKey}`
-    }
-
-    const mockInstance = {} as SanityInstance
-
-    // Test default behavior (no options)
-    const defaultKey = mockGetKey(mockInstance)
-    expect(defaultKey).toBe('projects')
-
-    // Test with organizationId only
-    const orgKey = mockGetKey(mockInstance, {organizationId: 'org123'})
-    expect(orgKey).toBe('projects:org:org123')
-
-    // Test with includeMembers: false only
-    const noMembersKey = mockGetKey(mockInstance, {includeMembers: false})
-    expect(noMembersKey).toBe('projects:no-members')
-
-    // Test with both parameters
-    const bothKey = mockGetKey(mockInstance, {
+  it('serializes query params (booleans → strings) and omits undefined values', async () => {
+    const request = vi.fn().mockReturnValue(of([]))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await projects.resolveState(instance, {
       organizationId: 'org123',
-      includeMembers: false,
+      includeMembers: true,
+      includeFeatures: false,
     })
-    expect(bothKey).toBe('projects:org:org123:no-members')
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/projects',
+      query: {
+        organizationId: 'org123',
+        includeMembers: 'true',
+        includeFeatures: 'false',
+        onlyExplicitMembership: 'false',
+      },
+      tag: 'projects.list',
+    })
+  })
+})
+
+describe('projects cache key generation', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('default call includes :features (default-true) and excludes :members (default-false)', () => {
+    expect(getProjectsCacheKey(instance)).toBe('projects:features')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getProjectsCacheKey(instance)).toBe(
+      getProjectsCacheKey(instance, {includeMembers: false, includeFeatures: true}),
+    )
+  })
+
+  it('treats raw and explicit defaults equivalently', () => {
+    expect(getProjectsCacheKey(instance, {organizationId: 'org123'})).toBe(
+      getProjectsCacheKey(instance, {
+        organizationId: 'org123',
+        includeMembers: false,
+        includeFeatures: true,
+        onlyExplicitMembership: false,
+      }),
+    )
+  })
+
+  it('explicit includeFeatures: false drops the :features segment', () => {
+    expect(getProjectsCacheKey(instance, {includeFeatures: false})).toBe('projects')
+  })
+
+  it('appends an org segment when organizationId is set', () => {
+    expect(getProjectsCacheKey(instance, {organizationId: 'org123'})).toBe(
+      'projects:org:org123:features',
+    )
+  })
+
+  it('appends :members when includeMembers is true', () => {
+    expect(getProjectsCacheKey(instance, {includeMembers: true})).toBe('projects:members:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getProjectsCacheKey(instance, {
+        organizationId: 'org123',
+        includeMembers: true,
+        includeFeatures: true,
+        onlyExplicitMembership: true,
+      }),
+    ).toBe('projects:org:org123:members:features:explicit')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getProjectsCacheKey(instance),
+      getProjectsCacheKey(instance, {includeMembers: true}),
+      getProjectsCacheKey(instance, {includeFeatures: false}),
+      getProjectsCacheKey(instance, {includeMembers: true, includeFeatures: false}),
+      getProjectsCacheKey(instance, {onlyExplicitMembership: true}),
+      getProjectsCacheKey(instance, {organizationId: 'a'}),
+      getProjectsCacheKey(instance, {organizationId: 'b'}),
+    ])
+    expect(keys.size).toBe(7)
   })
 })

package/src/projects/projects.ts

@@ -1,35 +1,71 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {createFetcherStore} from '../utils/createFetcherStore'
+import {type Project} from '../project/project'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {defineFetcher} from '../store/fetcherStore'
+import {buildQuery} from '../utils/buildQuery'
 
 const API_VERSION = 'v2025-02-19'
 
-const projects = createFetcherStore({
-  name: 'Projects',
-  getKey: (_instance, options?: {organizationId?: string; includeMembers?: boolean}) => {
-    const orgKey = options?.organizationId ? `:org:${options.organizationId}` : ''
-    const membersKey = options?.includeMembers === false ? ':no-members' : ''
-    return `projects${orgKey}${membersKey}`
-  },
-  fetcher: (instance) => (options?: {organizationId?: string; includeMembers?: boolean}) =>
-    getClientState(instance, {
-      apiVersion: API_VERSION,
-      scope: 'global',
-      requestTagPrefix: 'sanity.sdk.projects',
-    }).observable.pipe(
-      switchMap((client) => {
-        const organizationId = options?.organizationId
-        return client.observable.projects.list({
-          // client method has a type that expects false | undefined
-          includeMembers: !options?.includeMembers ? false : undefined,
-          organizationId,
-        })
-      }),
+/** @public */
+export interface ProjectsOptions<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = true,
+> {
+  organizationId?: string
+  includeMembers?: IncludeMembers
+  includeFeatures?: IncludeFeatures
+  onlyExplicitMembership?: boolean
+}
+
+function normalizeProjectsOptions(options?: ProjectsOptions<boolean, boolean>) {
+  return {
+    organizationId: options?.organizationId,
+    includeMembers: options?.includeMembers ?? false,
+    includeFeatures: options?.includeFeatures ?? true,
+    onlyExplicitMembership: options?.onlyExplicitMembership ?? false,
+  }
+}
+
+/** @internal */
+export function getProjectsCacheKey(
+  _instance: SanityInstance,
+  options?: ProjectsOptions<boolean, boolean>,
+): string {
+  const {organizationId, includeMembers, includeFeatures, onlyExplicitMembership} =
+    normalizeProjectsOptions(options)
+  const orgKey = organizationId ? `:org:${organizationId}` : ''
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  const explicitKey = onlyExplicitMembership ? ':explicit' : ''
+  return `projects${orgKey}${membersKey}${featuresKey}${explicitKey}`
+}
+
+/**
+ * Fetcher for the current user's projects (`GET /projects`), on the shared
+ * fetcher cache.
+ *
+ * @internal
+ */
+export const projects = defineFetcher<
+  [options?: ProjectsOptions<boolean, boolean>],
+  Project<boolean, boolean>[]
+>({
+  name: 'projects',
+  getKey: getProjectsCacheKey,
+  fetch: (instance) => (options) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable.request<Project<boolean, boolean>[]>({
+          uri: '/projects',
+          query: buildQuery(normalizeProjectsOptions(options)),
+          tag: 'projects.list',
+        }),
+      ),
     ),
+  tags: (data) => [
+    {type: 'project', id: 'LIST'},
+    ...data.map((project) => ({type: 'project', id: project.id})),
+  ],
 })
-
-/** @public */
-export const getProjectsState = projects.getState
-/** @public */
-export const resolveProjects = projects.resolveState