@sanity/sdk-react 2.9.0 → 2.11.0

package/src/hooks/documents/useDocuments.ts

@@ -1,14 +1,15 @@
 import {
   createGroqSearchFilter,
-  type DatasetHandle,
   type DocumentHandle,
+  isDatasetResource,
   type QueryOptions,
 } from '@sanity/sdk'
+import {pickProperties} from '@sanity/sdk/_internal'
 import {type SortOrderingItem} from '@sanity/types'
-import {pick} from 'lodash-es'
-import {useCallback, useEffect, useMemo, useState} from 'react'
+import {useCallback, useMemo, useState} from 'react'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {type ResourceHandle} from '../../config/handles'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
 import {useTrackHookUsage} from '../helpers/useTrackHookUsage'
 import {useQuery} from '../query/useQuery'
 
@@ -25,7 +26,7 @@ export interface DocumentsOptions<
   TDataset extends string = string,
   TProjectId extends string = string,
 >
-  extends DatasetHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
+  extends ResourceHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
   /**
    * Filter documents by their `_type`. Can be a single type or an array of types.
    */
@@ -202,14 +203,14 @@ export function useDocuments<
   filter,
   orderings,
   documentType,
-  ...options
+  ...rawOptions
 }: DocumentsOptions<TDocumentType, TDataset, TProjectId>): DocumentsResponse<
   TDocumentType,
   TDataset,
   TProjectId
 > {
   useTrackHookUsage('useDocuments')
-  const instance = useSanityInstance(options)
+  const options = useNormalizedResourceOptions(rawOptions)
   const [limit, setLimit] = useState(batchSize)
   const documentTypes = useMemo(
     () =>
@@ -230,9 +231,11 @@ export function useDocuments<
     types: documentTypes,
     ...options,
   })
-  useEffect(() => {
+  const [prevKey, setPrevKey] = useState(key)
+  if (prevKey !== key) {
+    setPrevKey(key)
     setLimit(batchSize)
-  }, [key, batchSize])
+  }
 
   const filterClause = useMemo(() => {
     const conditions: string[] = []
@@ -281,9 +284,14 @@ export function useDocuments<
     query: `{"count":${countQuery},"data":${dataQuery}}`,
     params: {
       ...params,
+      // these are passed back to the user as part of each document handle
       __handle: {
-        ...pick(instance.config, 'projectId', 'dataset', 'perspective'),
-        ...pick(options, 'projectId', 'dataset', 'perspective'),
+        // keep projectId/dataset for backward compat until v4; resource is added
+        // intentionally so that hook consumers can resolve the correct resource
+        ...(options.resource && isDatasetResource(options.resource)
+          ? pickProperties(options.resource, ['projectId', 'dataset'])
+          : {}),
+        ...pickProperties(options, ['perspective', 'resource']),
       },
       __types: documentTypes,
     },

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -19,11 +19,10 @@ export function createStateSourceHook<TParams extends unknown[], TState>(
   options: StateSourceFactory<TParams, TState> | CreateStateSourceHookOptions<TParams, TState>,
 ): (...params: TParams) => TState {
   const getState = typeof options === 'function' ? options : options.getState
-  const getConfig = 'getConfig' in options ? options.getConfig : undefined
   const suspense = 'shouldSuspend' in options && 'suspender' in options ? options : undefined
 
   function useHook(...params: TParams) {
-    const instance = useSanityInstance(getConfig?.(...params))
+    const instance = useSanityInstance()
 
     if (suspense?.suspender && suspense?.shouldSuspend?.(instance, ...params)) {
       throw suspense.suspender(instance, ...params)

package/src/hooks/helpers/useNormalizedResourceOptions.test.tsx

@@ -0,0 +1,253 @@
+import {createSanityInstance, type DocumentHandle} from '@sanity/sdk'
+import {type ReactNode} from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {renderHook, resources} from '../../../test/test-utils'
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+import {useNormalizedResourceOptions} from './useNormalizedResourceOptions'
+
+// Wrapper that sets ResourceContext via the `resource` prop (tier 3).
+// Includes ResourcesContext so resourceName resolution also works in these tests.
+function ResourceContextWrapper({
+  children,
+  resource,
+}: {
+  children: ReactNode
+  resource: {projectId: string; dataset: string}
+}) {
+  return (
+    <ResourceProvider resource={resource} fallback={null}>
+      <ResourcesContext.Provider value={resources}>{children}</ResourcesContext.Provider>
+    </ResourceProvider>
+  )
+}
+
+// Wrapper that provides an instance with no projectId/dataset and no ResourceContext (tier 5).
+const bareInstance = createSanityInstance({})
+function NoResourceWrapper({children}: {children: ReactNode}) {
+  return (
+    <SanityInstanceContext.Provider value={bareInstance}>{children}</SanityInstanceContext.Provider>
+  )
+}
+
+describe('useNormalizedResourceOptions', () => {
+  describe('tier 1 — explicit options', () => {
+    it('uses an explicit dataset resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {projectId: 'explicit', dataset: 'explicit-ds'}}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'explicit', dataset: 'explicit-ds'})
+    })
+
+    it('uses an explicit media-library resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {mediaLibraryId: 'ml-123'}}),
+      )
+      expect(result.current.resource).toEqual({mediaLibraryId: 'ml-123'})
+    })
+
+    it('uses an explicit canvas resource object', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resource: {canvasId: 'canvas-123'}}),
+      )
+      expect(result.current.resource).toEqual({canvasId: 'canvas-123'})
+    })
+
+    it('resolves resourceName to a named dataset resource', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'dataset'}))
+      expect(result.current.resource).toEqual({
+        projectId: 'resource-project-id',
+        dataset: 'resource-dataset',
+      })
+    })
+
+    it('resolves resourceName to a named media-library resource', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({resourceName: 'media-library'}),
+      )
+      expect(result.current.resource).toEqual({mediaLibraryId: 'media-library-id'})
+    })
+
+    it('resolves resourceName to a named canvas resource', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'canvas'}))
+      expect(result.current.resource).toEqual({canvasId: 'canvas-id'})
+    })
+
+    it('throws when resourceName is not registered', () => {
+      expect(() =>
+        renderHook(() => useNormalizedResourceOptions({resourceName: 'unknown'})),
+      ).toThrow(/no resource named/i)
+    })
+
+    it('throws when both resource and resourceName are provided', () => {
+      expect(() =>
+        renderHook(() =>
+          useNormalizedResourceOptions({
+            resource: {projectId: 'p', dataset: 'd'},
+            resourceName: 'dataset',
+          }),
+        ),
+      ).toThrow()
+    })
+
+    it('resolves deprecated `source` as `resource`', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({source: {projectId: 'src', dataset: 'src-ds'}}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'src', dataset: 'src-ds'})
+    })
+
+    it('resolves deprecated `sourceName` as `resourceName`', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({sourceName: 'dataset'}))
+      expect(result.current.resource).toEqual({
+        projectId: 'resource-project-id',
+        dataset: 'resource-dataset',
+      })
+    })
+  })
+
+  describe('tier 2 — bare projectId/dataset in options', () => {
+    it('synthesizes a resource from projectId + dataset', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({projectId: 'opt', dataset: 'opt-ds'}),
+      )
+      expect(result.current.resource).toEqual({projectId: 'opt', dataset: 'opt-ds'})
+    })
+
+    it('falls through to context when only projectId is provided (no dataset)', () => {
+      // Only projectId is not enough to synthesize — should fall back to context resource
+      const {result} = renderHook(() => useNormalizedResourceOptions({projectId: 'opt'}))
+      // Default test-utils: ResourceProvider projectId="test" dataset="test" → tier-3 via config synthesis
+      expect(result.current.resource).toEqual({projectId: 'test', dataset: 'test'})
+    })
+  })
+
+  describe('tier 3 — ResourceContext', () => {
+    it('uses ResourceContext set via ResourceProvider `resource` prop', () => {
+      const contextResource = {projectId: 'ctx-project', dataset: 'ctx-dataset'}
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <ResourceContextWrapper resource={contextResource}>{children}</ResourceContextWrapper>
+        ),
+      })
+      expect(result.current.resource).toEqual(contextResource)
+    })
+
+    it('uses ResourceContext synthesized from ResourceProvider projectId/dataset', () => {
+      // ResourceProvider with projectId/dataset (no explicit resource prop) synthesizes ResourceContext
+      const {result} = renderHook(() => useNormalizedResourceOptions({}))
+      // Default test-utils: ResourceProvider projectId="test" dataset="test"
+      expect(result.current.resource).toEqual({projectId: 'test', dataset: 'test'})
+    })
+
+    it('explicit resource in options takes precedence over ResourceContext', () => {
+      const {result} = renderHook(
+        () =>
+          useNormalizedResourceOptions({resource: {projectId: 'explicit', dataset: 'explicit-ds'}}),
+        {
+          wrapper: ({children}) => (
+            <ResourceContextWrapper resource={{projectId: 'ctx-project', dataset: 'ctx-dataset'}}>
+              {children}
+            </ResourceContextWrapper>
+          ),
+        },
+      )
+      expect(result.current.resource).toEqual({projectId: 'explicit', dataset: 'explicit-ds'})
+    })
+  })
+
+  describe('tier 4 — SanityInstance config fallback', () => {
+    it('falls back to instance projectId/dataset when ResourceContext is not set', () => {
+      // Bare SanityInstanceContext with config — no ResourceProvider, so no ResourceContext
+      const instanceWithConfig = createSanityInstance({projectId: 'inst', dataset: 'inst-ds'})
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <SanityInstanceContext.Provider value={instanceWithConfig}>
+            {children}
+          </SanityInstanceContext.Provider>
+        ),
+      })
+      expect(result.current.resource).toEqual({projectId: 'inst', dataset: 'inst-ds'})
+    })
+  })
+
+  describe('tier 5 — no resource available', () => {
+    it('returns no resource when neither options, context, nor instance config provide one', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: NoResourceWrapper,
+      })
+      expect(result.current).not.toHaveProperty('resource')
+    })
+  })
+
+  describe('perspective resolution', () => {
+    it('uses explicit perspective from options', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({perspective: 'published'}))
+      expect(result.current.perspective).toBe('published')
+    })
+
+    it('falls back to PerspectiveContext when no perspective in options', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: ({children}) => (
+          <ResourceProvider perspective="previewDrafts" fallback={null}>
+            {children}
+          </ResourceProvider>
+        ),
+      })
+      expect(result.current.perspective).toBe('previewDrafts')
+    })
+
+    it('explicit perspective overrides PerspectiveContext', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({perspective: 'published'}), {
+        wrapper: ({children}) => (
+          <ResourceProvider perspective="previewDrafts" fallback={null}>
+            {children}
+          </ResourceProvider>
+        ),
+      })
+      expect(result.current.perspective).toBe('published')
+    })
+
+    it('omits perspective from result when not set', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({}), {
+        wrapper: NoResourceWrapper,
+      })
+      expect(result.current).not.toHaveProperty('perspective')
+    })
+  })
+
+  describe('field stripping', () => {
+    it('strips resourceName from the result', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({resourceName: 'dataset'}))
+      expect(result.current).not.toHaveProperty('resourceName')
+    })
+
+    it('strips projectId and dataset from the result when synthesized into resource', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({projectId: 'p', dataset: 'd'}),
+      )
+      expect(result.current).not.toHaveProperty('projectId')
+      expect(result.current).not.toHaveProperty('dataset')
+    })
+
+    it('strips deprecated source from the result', () => {
+      const {result} = renderHook(() =>
+        useNormalizedResourceOptions({source: {projectId: 'src', dataset: 'src-ds'}}),
+      )
+      expect(result.current).not.toHaveProperty('source')
+    })
+
+    it('strips deprecated sourceName from the result', () => {
+      const {result} = renderHook(() => useNormalizedResourceOptions({sourceName: 'dataset'}))
+      expect(result.current).not.toHaveProperty('sourceName')
+    })
+
+    it('preserves unrelated fields', () => {
+      const opts: DocumentHandle = {documentId: 'doc-1', documentType: 'article'}
+      const {result} = renderHook(() => useNormalizedResourceOptions(opts))
+      expect(result.current).toMatchObject({documentId: 'doc-1', documentType: 'article'})
+    })
+  })
+})

package/src/hooks/helpers/useNormalizedResourceOptions.ts

@@ -0,0 +1,169 @@
+import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
+import {useContext, useMemo} from 'react'
+
+import {ResourceContext} from '../../context/DefaultResourceContext'
+import {PerspectiveContext} from '../../context/PerspectiveContext'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
+
+type NormalizedResourceFields = 'resourceName' | 'source' | 'sourceName' | 'projectId' | 'dataset'
+
+/**
+ * Adds React hook support (resourceName resolution) to core types.
+ * Prefer using the React-layer handle types (ResourceHandle, DocumentHandle)
+ * from `@sanity/sdk-react` — this wrapper is kept for cases where overloads
+ * don't fit (e.g. non-handle options objects).
+ *
+ * @typeParam T - The core type to extend (must have optional `resource` field)
+ * @beta
+ */
+export type WithResourceNameSupport<T extends {resource?: DocumentResource}> = T & {
+  /**
+   * Optional name of a resource to resolve from context.
+   * If provided, will be resolved to a `DocumentResource` via `ResourcesContext`.
+   * @beta
+   */
+  resourceName?: string
+  /**
+   * @deprecated Use `resourceName` instead.
+   * @beta
+   */
+  sourceName?: string
+}
+
+/**
+ * Pure function that normalizes options by resolving `resourceName` to a `DocumentResource`
+ * using the provided resources map. Use this when options are only available at call time
+ * (e.g. inside a callback) and you cannot call the {@link useNormalizedResourceOptions} hook.
+ *
+ * @typeParam T - The options type (must include optional resource field)
+ * @param options - Options that may include `resourceName` and/or `resource`
+ * @param resources - Map of resource names to DocumentResource (e.g. from ResourcesContext)
+ * @param contextResource - Resource from context (from ResourceContext)
+ * @param contextPerspective - Perspective from context (from PerspectiveContext)
+ * @returns Normalized options with `resourceName` removed and `resource` resolved
+ * @internal
+ */
+export function normalizeResourceOptions<
+  T extends {
+    resource?: DocumentResource
+    resourceName?: string
+    source?: DocumentResource
+    sourceName?: string
+    projectId?: string
+    dataset?: string
+    perspective?: unknown
+  },
+>(
+  options: T,
+  resources: Record<string, DocumentResource>,
+  contextResource?: DocumentResource,
+  contextPerspective?: PerspectiveHandle['perspective'],
+): Omit<T, NormalizedResourceFields> {
+  const {resourceName, sourceName, source, projectId, dataset, ...rest} = options
+
+  // Coalesce deprecated aliases to their canonical equivalents
+  const effectiveResourceName = resourceName ?? sourceName
+  const effectiveResource = options.resource ?? source
+
+  if (effectiveResourceName && effectiveResource) {
+    throw new Error(
+      `Resource name ${JSON.stringify(effectiveResourceName)} and resource ${JSON.stringify(effectiveResource)} cannot be used together.`,
+    )
+  }
+
+  let resolvedResource: DocumentResource | undefined
+
+  // Tier (a): explicit resource object or resourceName lookup
+  if (effectiveResource) {
+    resolvedResource = effectiveResource
+  } else if (effectiveResourceName) {
+    if (!Object.hasOwn(resources, effectiveResourceName)) {
+      throw new Error(
+        `There's no resource named ${JSON.stringify(effectiveResourceName)} in context. Please use <ResourceProvider>.`,
+      )
+    }
+    resolvedResource = resources[effectiveResourceName]
+  }
+
+  // Tier (b): projectId or dataset in options → synthesize a resource
+  if (!resolvedResource && projectId && dataset) {
+    resolvedResource = {
+      projectId,
+      dataset,
+    }
+  }
+
+  // Tier (c): fall back to whatever ResourceContext provides
+  if (!resolvedResource) {
+    resolvedResource = contextResource
+  }
+
+  // Inject perspective from context when not explicitly provided in options
+  const resolvedPerspective = Object.hasOwn(options, 'perspective')
+    ? options.perspective
+    : contextPerspective
+
+  return {
+    ...rest,
+    ...(resolvedResource !== undefined && {resource: resolvedResource}),
+    ...(resolvedPerspective !== undefined && {perspective: resolvedPerspective}),
+  }
+}
+
+/**
+ * Returns the effective context resource: the `ResourceContext` value if set,
+ * otherwise a resource synthesized from the current `SanityInstance` config
+ * (tier-d fallback — returns `undefined` for studio-style configs with no project).
+ *
+ * @internal
+ */
+export function useEffectiveContextResource(): DocumentResource | undefined {
+  const contextResource = useContext(ResourceContext)
+  const instance = useContext(SanityInstanceContext)
+  const {projectId, dataset} = instance?.config ?? {}
+
+  return useMemo(() => {
+    if (contextResource) return contextResource
+    if (projectId && dataset) return {projectId, dataset}
+    return undefined
+  }, [contextResource, projectId, dataset])
+}
+
+/**
+ * Normalizes hook options by resolving `resourceName` to a `DocumentResource`.
+ *
+ * Resolution priority for resource:
+ * 1. Explicit `resource` or `resourceName` in options
+ * 2. Bare `projectId`/`dataset` pair in options → synthesized into a resource
+ * 3. `ResourceContext` value (set by `ResourceProvider` / `SDKProvider`)
+ * 4. Current `SanityInstance` config — falls back to `undefined` for studio configs
+ *
+ * Resolution priority for perspective:
+ * 1. Explicit `perspective` in options
+ * 2. `PerspectiveContext` value (set by `ResourceProvider`)
+ *
+ * @internal
+ */
+export function useNormalizedResourceOptions<
+  T extends {
+    resource?: DocumentResource
+    resourceName?: string
+    source?: DocumentResource
+    sourceName?: string
+    projectId?: string
+    dataset?: string
+    perspective?: PerspectiveHandle['perspective']
+  },
+>(
+  options: T,
+): Omit<T, NormalizedResourceFields> & {
+  resource?: DocumentResource
+  perspective?: PerspectiveHandle['perspective']
+} {
+  const resources = useContext(ResourcesContext)
+  const effectiveContextResource = useEffectiveContextResource()
+  const contextPerspective = useContext(PerspectiveContext)
+
+  return normalizeResourceOptions(options, resources, effectiveContextResource, contextPerspective)
+}

package/src/hooks/helpers/useTrackHookUsage.ts

@@ -18,8 +18,8 @@ import {useSanityInstance} from '../context/useSanityInstance'
  */
 export function useTrackHookUsage(hookName: string): void {
   const instance = useSanityInstance()
-  const tracked = useRef(false)
-  if (!tracked.current) {
+  const tracked = useRef<true | null>(null)
+  if (tracked.current === null) {
     tracked.current = true
     trackHookMounted(instance, hookName)
   }

package/src/hooks/organizations/useOrganization.test-d.ts

@@ -0,0 +1,53 @@
+import {type Organization, type OrganizationMember} from '@sanity/sdk'
+import {expectTypeOf, test} from 'vitest'
+
+import {useOrganization} from './useOrganization'
+
+test('useOrganization — no flags: members and features both omitted', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1'})).toEqualTypeOf<
+    Organization<false, false>
+  >()
+})
+
+test('useOrganization — includeMembers: true adds members to the type', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers: true})).toEqualTypeOf<
+    Organization<true, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<true, false>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('useOrganization — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeFeatures: true})).toEqualTypeOf<
+    Organization<false, true>
+  >()
+})
+
+test('useOrganization — both flags true → both arrays present', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: true, includeFeatures: true}),
+  ).toEqualTypeOf<Organization<true, true>>()
+})
+
+test('useOrganization — both flags false → bare base shape', () => {
+  expectTypeOf(
+    useOrganization({organizationId: 'org_1', includeMembers: false, includeFeatures: false}),
+  ).toEqualTypeOf<Organization<false, false>>()
+  type Result = ReturnType<typeof useOrganization<false, false>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('useOrganization — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void useOrganization({organizationId: 'org_1', includeMembers: 'yes'})
+})
+
+test('useOrganization — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(useOrganization({organizationId: 'org_1', includeMembers})).toEqualTypeOf<
+    Organization<boolean, false>
+  >()
+  type Result = ReturnType<typeof useOrganization<boolean, false>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[] | undefined>()
+  expectTypeOf<Pick<Result, 'members'>>().toEqualTypeOf<{members?: OrganizationMember[]}>()
+})

package/src/hooks/organizations/useOrganization.test.ts

@@ -0,0 +1,65 @@
+import {getOrganizationState, type OrganizationOptions, type SanityInstance} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+vi.mock('@sanity/sdk', () => ({
+  getOrganizationState: vi.fn(() => ({
+    getCurrent: vi.fn(() => undefined),
+  })),
+  resolveOrganization: vi.fn(),
+}))
+vi.mock('../helpers/createStateSourceHook', () => ({
+  createStateSourceHook: vi.fn(),
+}))
+
+describe('useOrganization', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.mock('@sanity/sdk', () => ({
+      getOrganizationState: vi.fn(() => ({
+        getCurrent: vi.fn(() => undefined),
+      })),
+      resolveOrganization: vi.fn(),
+    }))
+    vi.mock('../helpers/createStateSourceHook', () => ({
+      createStateSourceHook: vi.fn(),
+    }))
+  })
+
+  it('should call createStateSourceHook with correct arguments on import', async () => {
+    await import('./useOrganization')
+
+    expect(createStateSourceHook).toHaveBeenCalled()
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: expect.any(Function),
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function),
+      }),
+    )
+  })
+
+  it('shouldSuspend should call getOrganizationState and getCurrent', async () => {
+    await import('./useOrganization')
+
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook.mock.calls.length).toBeGreaterThan(0)
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    const mockInstance = {} as SanityInstance
+    const mockOptions: OrganizationOptions = {organizationId: 'org_1'}
+
+    const result = shouldSuspend(mockInstance, mockOptions)
+
+    const mockGetOrganizationState = getOrganizationState as ReturnType<typeof vi.fn>
+    expect(mockGetOrganizationState).toHaveBeenCalledWith(mockInstance, mockOptions)
+
+    expect(mockGetOrganizationState.mock.results.length).toBeGreaterThan(0)
+    const getOrganizationStateMockResult = mockGetOrganizationState.mock.results[0].value
+    expect(getOrganizationStateMockResult.getCurrent).toHaveBeenCalled()
+
+    expect(result).toBe(true)
+  })
+})

package/src/hooks/organizations/useOrganization.ts

@@ -0,0 +1,40 @@
+import {
+  getOrganizationState,
+  type Organization,
+  type OrganizationOptions,
+  resolveOrganization,
+} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * Returns metadata for a given organisation.
+ *
+ * @category Organizations
+ * @param options - Configuration options
+ * @returns The metadata for the organisation. `members` is included only when
+ *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @example
+ * ```tsx
+ * function OrganizationName({organizationId}: {organizationId: string}) {
+ *   const organization = useOrganization({organizationId})
+ *
+ *   return <h1>{organization.name}</h1>
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * const organizationWithMembers = useOrganization({organizationId, includeMembers: true})
+ * const organizationWithFeatures = useOrganization({organizationId, includeFeatures: true})
+ * ```
+ * @public
+ * @function
+ */
+export const useOrganization = createStateSourceHook({
+  getState: getOrganizationState,
+  shouldSuspend: (instance, ...params) =>
+    getOrganizationState(instance, ...params).getCurrent() === undefined,
+  suspender: resolveOrganization,
+}) as <IncludeMembers extends boolean = false, IncludeFeatures extends boolean = false>(
+  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
+) => Organization<IncludeMembers, IncludeFeatures>