@sanity/sdk 2.3.1 → 2.4.0

package/src/document/actions.test.ts

@@ -42,6 +42,40 @@ describe('document actions', () => {
         documentType: typeHandle.documentType,
       })
     })
+
+    it('creates a document action with initial values', () => {
+      const initialValue = {
+        title: 'Test Title',
+        author: 'John Doe',
+        count: 42,
+      }
+      const action = createDocument(dummyDocHandle, initialValue)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue,
+      })
+    })
+
+    it('creates a document action without initialValue when not provided', () => {
+      const action = createDocument(dummyDocHandle, undefined)
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+      })
+    })
+
+    it('creates a document action with empty initialValue object', () => {
+      const action = createDocument(dummyDocHandle, {})
+      expect(action).toEqual({
+        type: 'document.create',
+        documentId: 'abc123',
+        documentType: dummyDocHandle.documentType,
+        initialValue: {},
+      })
+    })
   })
 
   describe('deleteDocument', () => {

package/src/document/actions.ts

@@ -1,6 +1,7 @@
 import {SanityEncoder} from '@sanity/mutate'
 import {type PatchMutation as SanityMutatePatchMutation} from '@sanity/mutate/_unstable_store'
 import {type PatchMutation, type PatchOperations} from '@sanity/types'
+import {type SanityDocument} from 'groq'
 
 import {type DocumentHandle, type DocumentTypeHandle} from '../config/sanityConfig'
 import {getPublishedId} from '../utils/ids'
@@ -24,6 +25,17 @@ export interface CreateDocumentAction<
   TProjectId extends string = string,
 > extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.create'
+  /**
+   * Optional initial field values for the document.
+   * These values will be set when the document is created.
+   * System fields (_id, _type, _rev, _createdAt, _updatedAt) are omitted as they are set automatically.
+   */
+  initialValue?: Partial<
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
+  >
 }
 
 /**
@@ -111,6 +123,7 @@ export type DocumentAction<
 /**
  * Creates a `CreateDocumentAction` object.
  * @param doc - A handle identifying the document type, dataset, and project. An optional `documentId` can be provided.
+ * @param initialValue - Optional initial field values for the document. (System fields are omitted as they are set automatically.)
  * @returns A `CreateDocumentAction` object ready for dispatch.
  * @beta
  */
@@ -120,11 +133,18 @@ export function createDocument<
   TProjectId extends string = string,
 >(
   doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>,
+  initialValue?: Partial<
+    Omit<
+      SanityDocument<TDocumentType, `${TProjectId}.${TDataset}`>,
+      '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'
+    >
+  >,
 ): CreateDocumentAction<TDocumentType, TDataset, TProjectId> {
   return {
     type: 'document.create',
     ...doc,
     ...(doc.documentId && {documentId: getPublishedId(doc.documentId)}),
+    ...(initialValue && {initialValue}),
   }
 }
 

package/src/document/documentStore.test.ts

@@ -110,6 +110,34 @@ it('creates, edits, and publishes a document', async () => {
   unsubscribe()
 })
 
+it('creates a document with initial values', async () => {
+  const doc = createDocumentHandle({documentId: 'doc-with-initial', documentType: 'article'})
+  const documentState = getDocumentState(instance, doc)
+
+  expect(documentState.getCurrent()).toBeUndefined()
+
+  const unsubscribe = documentState.subscribe()
+
+  // Create a new document with initial field values
+  const {appeared} = await applyDocumentActions(
+    instance,
+    createDocument(doc, {
+      title: 'Article with Initial Values',
+      author: 'Jane Doe',
+      count: 42,
+    }),
+  )
+  expect(appeared).toContain(getDraftId(doc.documentId))
+
+  const currentDoc = documentState.getCurrent()
+  expect(currentDoc?._id).toEqual(getDraftId(doc.documentId))
+  expect(currentDoc?.title).toEqual('Article with Initial Values')
+  expect(currentDoc?.['author']).toEqual('Jane Doe')
+  expect(currentDoc?.['count']).toEqual(42)
+
+  unsubscribe()
+})
+
 it('edits existing documents', async () => {
   const doc = createDocumentHandle({documentId: 'existing-doc', documentType: 'article'})
   const state = getDocumentState(instance, doc)

package/src/document/processActions.test.ts

@@ -138,6 +138,103 @@ describe('processActions', () => {
         processActions({actions, transactionId, base, working, timestamp, grants}),
       ).toThrow(/You do not have permission to create a draft for document "doc1"/)
     })
+
+    it('should create a draft document with initial values', () => {
+      const base: DocumentSet = {}
+      const working: DocumentSet = {}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {
+            title: 'New Article',
+            author: 'John Doe',
+            count: 42,
+          },
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      expect(draftDoc?._id).toBe(draftId)
+      expect(draftDoc?._type).toBe('article')
+      expect(draftDoc?._rev).toBe(transactionId)
+      // Should have the initial values:
+      expect(draftDoc?.['title']).toBe('New Article')
+      expect(draftDoc?.['author']).toBe('John Doe')
+      expect(draftDoc?.['count']).toBe(42)
+    })
+
+    it('should create a draft with initial values that override published document values', () => {
+      const published = createDoc('doc1', 'Original Title')
+      const base: DocumentSet = {doc1: published}
+      const working: DocumentSet = {doc1: published}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {
+            title: 'Overridden Title',
+            newField: 'New Value',
+          },
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      // Should have the overridden title from initialValue:
+      expect(draftDoc?.['title']).toBe('Overridden Title')
+      // Should have the new field:
+      expect(draftDoc?.['newField']).toBe('New Value')
+    })
+
+    it('should create a draft with empty initial values object', () => {
+      const base: DocumentSet = {}
+      const working: DocumentSet = {}
+      const actions: DocumentAction[] = [
+        {
+          documentId: 'doc1',
+          type: 'document.create',
+          documentType: 'article',
+          initialValue: {},
+        },
+      ]
+      const result = processActions({
+        actions,
+        transactionId,
+        base,
+        working,
+        timestamp,
+        grants: defaultGrants,
+      })
+
+      const draftId = 'drafts.doc1'
+      const draftDoc = result.working[draftId]
+      expect(draftDoc).toBeDefined()
+      expect(draftDoc?._id).toBe(draftId)
+      expect(draftDoc?._type).toBe('article')
+      expect(draftDoc?._rev).toBe(transactionId)
+    })
   })
 
   describe('document.delete', () => {

package/src/document/processActions.ts

@@ -152,8 +152,18 @@ export function processActions({
         }
 
         // Spread the (possibly undefined) published version directly.
-        const newDocBase = {...base[publishedId], _type: action.documentType, _id: draftId}
-        const newDocWorking = {...working[publishedId], _type: action.documentType, _id: draftId}
+        const newDocBase = {
+          ...base[publishedId],
+          _type: action.documentType,
+          _id: draftId,
+          ...action.initialValue,
+        }
+        const newDocWorking = {
+          ...working[publishedId],
+          _type: action.documentType,
+          _id: draftId,
+          ...action.initialValue,
+        }
         const mutations: Mutation[] = [{create: newDocWorking}]
 
         base = processMutations({

package/src/query/queryStore.ts

@@ -23,9 +23,9 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type DatasetHandle} from '../config/sanityConfig'
+import {type DatasetHandle, type DocumentSource} from '../config/sanityConfig'
 import {getPerspectiveState} from '../releases/getPerspectiveState'
-import {bindActionByDataset} from '../store/createActionBinder'
+import {bindActionBySource} from '../store/createActionBinder'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {
   createStateSourceAction,
@@ -62,6 +62,7 @@ export interface QueryOptions<
     DatasetHandle<TDataset, TProjectId> {
   query: TQuery
   params?: Record<string, unknown>
+  source?: DocumentSource
 }
 
 /**
@@ -160,6 +161,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               projectId,
               dataset,
               tag,
+              source,
               perspective: perspectiveFromOptions,
               ...restOptions
             } = parseQueryKey(group$.key)
@@ -172,6 +174,7 @@ const listenForNewSubscribersAndFetch = ({state, instance}: StoreContext<QuerySt
               apiVersion: QUERY_STORE_API_VERSION,
               projectId,
               dataset,
+              source,
             }).observable
 
             return combineLatest([lastLiveEventId$, client$, perspective$]).pipe(
@@ -290,7 +293,7 @@ export function getQueryState(
 ): ReturnType<typeof _getQueryState> {
   return _getQueryState(...args)
 }
-const _getQueryState = bindActionByDataset(
+const _getQueryState = bindActionBySource(
   queryStore,
   createStateSourceAction({
     selector: ({state, instance}: SelectorContext<QueryStoreState>, options: QueryOptions) => {
@@ -349,7 +352,7 @@ export function resolveQuery<TData>(
 export function resolveQuery(...args: Parameters<typeof _resolveQuery>): Promise<unknown> {
   return _resolveQuery(...args)
 }
-const _resolveQuery = bindActionByDataset(
+const _resolveQuery = bindActionBySource(
   queryStore,
   ({state, instance}, {signal, ...options}: ResolveQueryOptions) => {
     const normalized = normalizeOptionsWithPerspective(instance, options)

package/src/store/createActionBinder.ts

@@ -1,4 +1,4 @@
-import {type SanityConfig} from '../config/sanityConfig'
+import {type DocumentSource, type SanityConfig, SOURCE_ID} from '../config/sanityConfig'
 import {type SanityInstance} from './createSanityInstance'
 import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
@@ -43,7 +43,9 @@ export type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (
  * )
  * ```
  */
-export function createActionBinder(keyFn: (config: SanityConfig) => string) {
+export function createActionBinder<TKeyParams extends unknown[]>(
+  keyFn: (config: SanityConfig, ...params: TKeyParams) => string,
+) {
   const instanceRegistry = new Map<string, Set<string>>()
   const storeRegistry = new Map<string, StoreInstance<unknown>>()
 
@@ -54,12 +56,12 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
    * @param action - The action to bind
    * @returns A function that executes the action with a Sanity instance
    */
-  return function bindAction<TState, TParams extends unknown[], TReturn>(
+  return function bindAction<TState, TParams extends TKeyParams, TReturn>(
     storeDefinition: StoreDefinition<TState>,
     action: StoreAction<TState, TParams, TReturn>,
   ): BoundStoreAction<TState, TParams, TReturn> {
     return function boundAction(instance: SanityInstance, ...params: TParams) {
-      const keySuffix = keyFn(instance.config)
+      const keySuffix = keyFn(instance.config, ...params)
       const compositeKey = storeDefinition.name + (keySuffix ? `:${keySuffix}` : '')
 
       // Get or create instance set for this composite key
@@ -128,13 +130,32 @@ export function createActionBinder(keyFn: (config: SanityConfig) => string) {
  * fetchDocument(sanityInstance, 'doc123')
  * ```
  */
-export const bindActionByDataset = createActionBinder(({projectId, dataset}) => {
+export const bindActionByDataset = createActionBinder<unknown[]>(({projectId, dataset}) => {
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
   }
   return `${projectId}.${dataset}`
 })
 
+/**
+ * Binds an action to a store that's scoped to a specific document source.
+ **/
+export const bindActionBySource = createActionBinder<[{source?: DocumentSource}, ...unknown[]]>(
+  ({projectId, dataset}, {source}) => {
+    if (source) {
+      const id = source[SOURCE_ID]
+      if (!id) throw new Error('Invalid source (missing ID information)')
+      if (Array.isArray(id)) return id.join(':')
+      return `${id.projectId}.${id.dataset}`
+    }
+
+    if (!projectId || !dataset) {
+      throw new Error('This API requires a project ID and dataset configured.')
+    }
+    return `${projectId}.${dataset}`
+  },
+)
+
 /**
  * Binds an action to a global store that's shared across all Sanity instances
  *
@@ -173,4 +194,4 @@ export const bindActionByDataset = createActionBinder(({projectId, dataset}) =>
  * getCurrentUser(sanityInstance)
  * ```
  */
-export const bindActionGlobally = createActionBinder(() => 'global')
+export const bindActionGlobally = createActionBinder<unknown[]>(() => 'global')