@sanity/sdk 0.0.0-alpha.14 → 0.0.0-alpha.15

package/dist/index.d.ts

@@ -14,15 +14,14 @@ import {Observable} from 'rxjs'
 import {PatchMutation} from '@sanity/mutate/_unstable_store'
 import {PatchOperations} from '@sanity/types'
 import {PathSegment} from '@sanity/types'
+import {ResponseQueryOptions} from '@sanity/client'
 import {Role} from '@sanity/types'
 import {SanityClient} from '@sanity/client'
 import {SanityDocument} from '@sanity/types'
 import {SanityDocumentLike} from '@sanity/types'
 import {SanityProject as SanityProject_2} from '@sanity/client'
 import {SchemaTypeDefinition} from '@sanity/types'
-import {SortOrderingItem} from '@sanity/types'
 import {Subject} from 'rxjs'
-import {SyncTag} from '@sanity/client'
 
 declare interface AccessAttributeNode extends BaseNode {
   type: 'AccessAttribute'
@@ -357,6 +356,10 @@ export declare interface ClientOptions extends ClientConfig {
    * A required string indicating the API version for the client.
    */
   apiVersion: string
+  /**
+   * A resource identifier for a document, in the format of `projectId.dataset`
+   */
+  resourceId?: ResourceId
 }
 
 /**
@@ -403,6 +406,12 @@ declare interface ContextNode extends BaseNode {
   key: string
 }
 
+/**
+ * This version is provided by pkg-utils at build time
+ * @internal
+ */
+export declare const CORE_SDK_VERSION: {}
+
 /** @beta */
 export declare function createDocument<TDocument extends SanityDocumentLike>(
   doc: DocumentTypeHandle<TDocument> | DocumentHandle<TDocument>,
@@ -418,25 +427,6 @@ export declare interface CreateDocumentAction<
   documentType: TDocument['_type']
 }
 
-/**
- * @public
- */
-export declare const createDocumentListStore: (instance: SanityInstance | ActionContext<any>) => {
-  dispose: () => void
-} & {
-  getState: BoundResourceAction<
-    [],
-    StateSource<{
-      results: DocumentHandle_2[]
-      isPending: boolean
-      count: number
-      hasMore: boolean
-    }>
-  >
-  loadMore: BoundResourceAction<[], void>
-  setOptions: BoundResourceAction<[options: DocumentListOptions], void>
-}
-
 /**
  * Returns a new instance of dependencies required for SanitySDK.
  *
@@ -655,44 +645,6 @@ export declare interface DocumentHandle<TDocument extends SanityDocumentLike = S
   resourceId?: DocumentResourceId
 }
 
-/**
- * Represents an identifier to a Sanity document, containing its `_id` to pull
- * the document from content lake and its `_type` to look up its schema type.
- * @public
- */
-declare interface DocumentHandle_2 {
-  _id: string
-  _type: string
-}
-
-/**
- * Configuration options for filtering and sorting documents in a document list.
- * @public
- */
-export declare interface DocumentListOptions {
-  /** The resourceId of the Sanity instance to use for this list. */
-  resourceId?: string
-  /** GROQ filter expression to query specific documents */
-  filter?: string
-  /** Array of sort ordering specifications to determine the order of results */
-  sort?: SortOrderingItem[]
-  /** The Content Lake perspective to use for this list. Defaults to `drafts`. */
-  perspective?: string
-}
-
-/**
- * @public
- */
-export declare interface DocumentListState {
-  options: DocumentListOptions
-  lastLiveEventId?: string
-  syncTags: SyncTag[]
-  limit: number
-  count: number
-  results: DocumentHandle_2[]
-  isPending: boolean
-}
-
 /**
  * @beta
  * Event emitted when a document is published.
@@ -1071,7 +1023,7 @@ export declare const getPermissionsState: ResourceAction<
 >
 
 /**
- * @public
+ * @beta
  */
 export declare const getPreviewState: ResourceAction<
   PreviewStoreState,
@@ -1080,10 +1032,10 @@ export declare const getPreviewState: ResourceAction<
 >
 
 /**
- * @public
+ * @beta
  */
 export declare interface GetPreviewStateOptions {
-  document: DocumentHandle_2
+  document: DocumentHandle
 }
 
 /**
@@ -1103,7 +1055,7 @@ export declare function getProjectionState(
 ): StateSource<ProjectionValuePending<Record<string, unknown>>>
 
 declare interface GetProjectionStateOptions {
-  document: DocumentHandle_2
+  document: DocumentHandle
   projection: ValidProjection
 }
 
@@ -1121,6 +1073,38 @@ export declare const getProjectState: ResourceAction<
   StateSource<SanityProject_2 | undefined>
 >
 
+/** @beta */
+export declare const getQueryKey: (query: string, options?: QueryOptions) => string
+
+/**
+ * Returns the state source for a query.
+ *
+ * This function returns a state source that represents the current result of a GROQ query.
+ * Subscribing to the state source will instruct the SDK to fetch the query (if not already fetched)
+ * and will keep the query live using the Live content API (considering sync tags) to provide up-to-date results.
+ * When the last subscriber is removed, the query state is automatically cleaned up from the store.
+ *
+ * Note: This functionality is for advanced users who want to build their own framework integrations.
+ * Our SDK also provides a React integration (useQuery hook) for convenient usage.
+ *
+ * Note: Automatic cleanup can interfere with React Suspense because if a component suspends while being the only subscriber,
+ * cleanup might occur unexpectedly. In such cases, consider using `resolveQuery` instead.
+ *
+ * @beta
+ */
+export declare function getQueryState<T>(
+  instance: SanityInstance | ActionContext<QueryStoreState>,
+  query: string,
+  options?: QueryOptions,
+): StateSource<T | undefined>
+
+/** @beta */
+export declare function getQueryState(
+  instance: SanityInstance | ActionContext<QueryStoreState>,
+  query: string,
+  options?: QueryOptions,
+): StateSource<unknown>
+
 /**
  * @beta
  * Get the resource ID from a document resource ID
@@ -1448,6 +1432,12 @@ declare type ParseBracket<TInput extends string> = TInput extends `[${infer TPar
   ? [ToNumber<TPart>, ...ParseSegment<TRest>]
   : []
 
+/** @beta */
+export declare const parseQueryKey: (key: string) => {
+  query: string
+  options: QueryOptions
+}
+
 /**
  * Parse a single “segment” that may include bracket parts.
  *
@@ -1628,6 +1618,30 @@ export declare interface PublishDocumentAction<
   resourceId?: DocumentResourceId
 }
 
+/**
+ * @beta
+ */
+export declare interface QueryOptions
+  extends Pick<ResponseQueryOptions, 'perspective' | 'useCdn' | 'cache' | 'next' | 'cacheMode'>,
+    Pick<ClientOptions, 'scope' | 'resourceId'> {
+  params?: Record<string, unknown>
+}
+
+declare interface QueryState {
+  syncTags?: string[]
+  result?: unknown
+  error?: unknown
+  lastLiveEventId?: string
+  subscribers: string[]
+}
+
+declare interface QueryStoreState {
+  queries: {
+    [key: string]: QueryState | undefined
+  }
+  error?: unknown
+}
+
 /**
  * Represents a transaction that is queued to be applied but has not yet been
  * applied. A transaction will remain in a queued state until all required
@@ -1690,7 +1704,7 @@ export declare const resolvePermissions: ResourceAction<
 >
 
 /**
- * @public
+ * @beta
  */
 export declare const resolvePreview: ResourceAction<
   PreviewStoreState,
@@ -1699,10 +1713,10 @@ export declare const resolvePreview: ResourceAction<
 >
 
 /**
- * @public
+ * @beta
  */
 export declare interface ResolvePreviewOptions {
-  document: DocumentHandle_2
+  document: DocumentHandle
 }
 
 /** @public */
@@ -1722,7 +1736,7 @@ export declare const resolveProjection: ResourceAction<
 >
 
 declare interface ResolveProjectionOptions {
-  document: DocumentHandle_2
+  document: DocumentHandle
   projection: ValidProjection
 }
 
@@ -1733,6 +1747,40 @@ export declare const resolveProjects: ResourceAction<
   Promise<Omit<SanityProject_2, 'members'>[]>
 >
 
+/**
+ * Resolves the result of a query without registering a lasting subscriber.
+ *
+ * This function fetches the result of a GROQ query and returns a promise that resolves with the query result.
+ * Unlike `getQueryState`, which registers subscribers to keep the query live and performs automatic cleanup,
+ * `resolveQuery` does not track subscribers. This makes it ideal for use with React Suspense, where the returned
+ * promise is thrown to delay rendering until the query result becomes available.
+ * Once the promise resolves, it is expected that a real subscriber will be added via `getQueryState` to manage ongoing updates.
+ *
+ * Additionally, an optional AbortSignal can be provided to cancel the query and immediately clear the associated state
+ * if there are no active subscribers.
+ *
+ * @beta
+ */
+export declare function resolveQuery<T>(
+  instance: SanityInstance | ActionContext<QueryStoreState>,
+  query: string,
+  options?: ResolveQueryOptions,
+): Promise<T>
+
+/** @beta */
+export declare function resolveQuery(
+  instance: SanityInstance | ActionContext<QueryStoreState>,
+  query: string,
+  options?: ResolveQueryOptions,
+): Promise<unknown>
+
+/**
+ * @beta
+ */
+declare interface ResolveQueryOptions extends QueryOptions {
+  signal?: AbortSignal
+}
+
 /**
  * @public
  */