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

package/src/store/createSanityInstance.ts

@@ -1,9 +1,10 @@
 import {type SanityConfig} from '../config/sanityConfig'
 import {insecureRandomId} from '../utils/ids'
 import {createLogger, type InstanceContext} from '../utils/logger'
+import {pickProperties} from '../utils/object'
 
 /**
- * Represents a Sanity.io resource instance with its own configuration and lifecycle.
+ * Represents a Sanity.io resource instance with its own configuration and lifecycle
  *
  * @public
  */
@@ -14,7 +15,9 @@ export interface SanityInstance {
    */
   readonly instanceId: string
 
-  /** Resolved configuration for this instance */
+  /**
+   * Resolved configuration for this instance
+   */
   readonly config: SanityConfig
 
   /**
@@ -35,12 +38,36 @@ export interface SanityInstance {
    * @returns Function to unsubscribe the callback
    */
   onDispose(cb: () => void): () => void
+
+  /**
+   * Gets the parent instance in the hierarchy
+   * @returns Parent instance or undefined if this is the root
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  getParent(): SanityInstance | undefined
+
+  /**
+   * Creates a child instance with merged configuration
+   * @param config - Configuration to merge with parent values
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  createChild(config: SanityConfig): SanityInstance
+
+  /**
+   * Traverses the instance hierarchy to find the first instance whose configuration
+   * matches the given target config using a shallow comparison.
+   * @param targetConfig - A partial configuration object containing key-value pairs to match.
+   * @returns The first matching instance or undefined if no match is found.
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  match(targetConfig: Partial<SanityConfig>): SanityInstance | undefined
 }
 
 /**
  * Creates a new Sanity resource instance
  * @param config - Configuration for the instance (optional)
  * @returns A configured SanityInstance
+ * @remarks When creating child instances, configurations are merged with parent values
  *
  * @public
  */
@@ -49,21 +76,32 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
   const disposeListeners = new Map<string, () => void>()
   const disposed = {current: false}
 
+  // Create instance context for logging
   const instanceContext: InstanceContext = {
     instanceId,
+    projectId: config.projectId,
+    dataset: config.dataset,
   }
 
+  // Create logger with instance context
   const logger = createLogger('sdk', {instanceContext})
 
+  // Log instance creation
   logger.info('Sanity instance created', {
+    hasProjectId: !!config.projectId,
+    hasDataset: !!config.dataset,
     hasAuth: !!config.auth,
     hasPerspective: !!config.perspective,
   })
 
+  // Log configuration details at debug level
   logger.debug('Instance configuration', {
+    projectId: config.projectId,
+    dataset: config.dataset,
     perspective: config.perspective,
     hasStudioConfig: !!config.studio,
     hasStudioTokenSource: !!config.studio?.auth?.token,
+    legacyStudioMode: config.studioMode?.enabled,
     hasAuthProviders: !!config.auth?.providers,
     hasAuthToken: !!config.auth?.token,
   })
@@ -93,6 +131,43 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
         disposeListeners.delete(listenerId)
       }
     },
+    getParent: () => undefined,
+    createChild: (next) => {
+      logger.debug('Creating child instance', {
+        parentInstanceId: instanceId.slice(0, 8),
+        overridingProjectId: !!next.projectId,
+        overridingDataset: !!next.dataset,
+        overridingAuth: !!next.auth,
+      })
+      const child = Object.assign(
+        createSanityInstance({
+          ...config,
+          ...next,
+          ...(config.auth === next.auth
+            ? config.auth
+            : config.auth && next.auth && {auth: {...config.auth, ...next.auth}}),
+        }),
+        {getParent: () => instance},
+      )
+      logger.trace('Child instance created', {
+        internal: true,
+        childInstanceId: child.instanceId.slice(0, 8),
+      })
+      return child
+    },
+    match: (targetConfig) => {
+      if (
+        Object.entries(pickProperties(targetConfig, ['auth', 'projectId', 'dataset'])).every(
+          ([key, value]) => config[key as keyof SanityConfig] === value,
+        )
+      ) {
+        return instance
+      }
+
+      const parent = instance.getParent()
+      if (parent) return parent.match(targetConfig)
+      return undefined
+    },
   }
 
   return instance

package/src/store/createStateSourceAction.test.ts

@@ -1,3 +1,4 @@
+import {filter, firstValueFrom, timeout} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {createSanityInstance, type SanityInstance} from './createSanityInstance'
@@ -14,7 +15,7 @@ describe('createStateSourceAction', () => {
   let instance: SanityInstance
 
   beforeEach(() => {
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
     state = createStoreState({count: 0, items: [] as string[]}, {name: 'test-store'})
   })
 
@@ -179,7 +180,7 @@ describe('createStateSourceAction', () => {
 
   // New test: distinct contexts for same state with different instance
   it('should create distinct contexts for same state with different instance', () => {
-    const secondInstance = createSanityInstance()
+    const secondInstance = createSanityInstance({projectId: 'test2', dataset: 'test2'})
     const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
 
     const source1 = createStateSourceAction(selector)({state, instance, key: null})
@@ -194,4 +195,65 @@ describe('createStateSourceAction', () => {
     expect(context1.instance).toBe(instance)
     expect(context2.instance).toBe(secondInstance)
   })
+
+  it('correctly observes values defined in the onSubscribe', async () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({
+      selector: selector,
+      onSubscribe() {
+        state.set('update', {count: 1})
+      },
+    })({state, instance, key: null})
+
+    const value = await firstValueFrom(
+      source.observable.pipe(
+        filter((i) => i === 1),
+        timeout(10),
+      ),
+    )
+    expect(value).toBe(1)
+  })
+
+  it('only invokes selector once on changes', () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({selector: selector})({state, instance, key: null})
+
+    expect(selector).toBeCalledTimes(0)
+
+    // Now it should be called once:
+    const sub = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    // The observable should be shared so this shouldn't invoke it first.
+    const sub2 = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    // Updating the value should only invoke it once:
+    state.set('update', {count: 1})
+    expect(selector).toBeCalledTimes(2)
+
+    sub2.unsubscribe()
+    sub.unsubscribe()
+
+    // Once everyone has unsubscribed it should be invoked again.
+    const sub3 = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(3)
+    sub3.unsubscribe()
+  })
+
+  it('only subscribes once when mixing subscribe/observable', () => {
+    const selector = vi.fn(({state: s}: SelectorContext<CountStoreState>) => s.count)
+    const source = createStateSourceAction({selector: selector})({state, instance, key: null})
+
+    expect(selector).toBeCalledTimes(0)
+
+    const sub = source.observable.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    const sub2 = source.subscribe()
+    expect(selector).toBeCalledTimes(1)
+
+    sub.unsubscribe()
+    sub2()
+  })
 })

package/src/store/createStateSourceAction.ts

@@ -1,4 +1,4 @@
-import {distinctUntilChanged, map, Observable, share, skip} from 'rxjs'
+import {defer, distinctUntilChanged, finalize, map, Observable, shareReplay, skip} from 'rxjs'
 
 import {type StoreAction} from './createActionBinder'
 import {type SanityInstance} from './createSanityInstance'
@@ -57,9 +57,9 @@ export interface StateSource<T> {
  * ```ts
  * // Using both state and instance in a selector (psuedo example)
  * const getUserByProjectId = createStateSourceAction(
- *   ({ state, instance }: SelectorContext<UsersState>, options?: ResourceHandle) => {
+ *   ({ state, instance }: SelectorContext<UsersState>, options?: ProjectHandle) => {
  *     const allUsers = state.users
- *     const projectId = options?.projectId ?? instance.config.defaultResource?.projectId
+ *     const projectId = options?.projectId ?? instance.config.projectId
  *     return allUsers.filter(user => user.projectId === projectId)
  *   }
  * )
@@ -155,13 +155,13 @@ interface StateSourceOptions<TState, TParams extends unknown[], TReturn, TKey> {
  *   // ...
  * })
  *
- * const getDocument = bindActionByResource(
+ * const getDocument = bindActionByDataset(
  *   documentStore,
- *   createStateSourceAction(({state}, _options, documentId: string) => state.documents[documentId])
+ *   createStateSourceAction(({state}, documentId: string) => state.documents[documentId])
  * )
  *
  * // Usage
- * const documentSource = getDocument(sanityInstance, {}, 'doc123')
+ * const documentSource = getDocument(sanityInstance, 'doc123')
  * const doc = documentSource.getCurrent()
  * const subscription = documentSource.observable.subscribe(updatedDoc => {
  *   console.log('Document changed:', updatedDoc)
@@ -187,8 +187,7 @@ export function createStateSourceAction<TState, TParams extends unknown[], TRetu
   function stateSourceAction(context: StoreContext<TState, TKey>, ...params: TParams) {
     const {state, instance} = context
 
-    const getCurrent = () => {
-      const currentState = state.get()
+    const getCurrent = (currentState: TState) => {
       if (typeof currentState !== 'object' || currentState === null) {
         throw new Error(
           `Expected store state to be an object but got "${typeof currentState}" instead`,
@@ -208,53 +207,49 @@ export function createStateSourceAction<TState, TParams extends unknown[], TRetu
       return selector(selectorContext, ...params)
     }
 
-    // Subscription manager handles both RxJS and direct subscriptions
-    const subscribe = (onStoreChanged?: () => void) => {
-      // Run setup handler if provided
-      const cleanup = subscribeHandler?.(context, ...params)
+    // `state.observable` will emit the current value immediately and
+    // hence we inherit the same behavior here.
+    let values = state.observable.pipe(map(getCurrent), distinctUntilChanged(isEqual))
 
-      // Set up state change subscription
-      const subscription = state.observable
-        .pipe(
-          // Derive value from current state
-          map(getCurrent),
-          // Filter unchanged values using custom equality check
-          distinctUntilChanged(isEqual),
-          // Skip initial emission since we only want changes
-          skip(1),
-        )
-        .subscribe({
-          next: () => onStoreChanged?.(),
-          // Propagate selector errors to both subscription types
-          error: () => onStoreChanged?.(),
-        })
+    if (subscribeHandler) {
+      values = withSubscribeHook(values, () => subscribeHandler(context, ...params))
+    }
+
+    // Share but replay the latest value so every subscriber gets an
+    // initial synchronous emission, matching `state.observable`. That keeps
+    // `skip(1)` in `subscribe()` aligned with "skip current snapshot" rather than
+    // silently eating the first real update after multicasting.
+    const sharedValues = values.pipe(shareReplay({bufferSize: 1, refCount: true}))
+
+    const subscribe = (onStoreChanged?: () => void) => {
+      const subscription = sharedValues.pipe(skip(1)).subscribe({
+        next: () => onStoreChanged?.(),
+        // Propagate selector errors to both subscription types
+        error: () => onStoreChanged?.(),
+      })
 
       return () => {
         subscription.unsubscribe()
-        cleanup?.()
       }
     }
 
-    // Create shared observable that handles multiple subscribers efficiently
-    const observable = new Observable<TReturn>((observer) => {
-      const emitCurrent = () => {
-        try {
-          observer.next(getCurrent())
-        } catch (error) {
-          observer.error(error)
-        }
-      }
-      // Emit immediately on subscription
-      emitCurrent()
-      return subscribe(emitCurrent)
-    }).pipe(share())
-
     return {
-      getCurrent,
+      getCurrent: () => getCurrent(state.get()),
       subscribe,
-      observable,
+      observable: sharedValues,
     }
   }
 
   return stateSourceAction
 }
+
+/**
+ * Creates a new Observable which wraps an existing Observable which will invoke
+ * the function when a new subscriber appears.
+ */
+function withSubscribeHook<T>(obs: Observable<T>, fn: () => void | (() => void)): Observable<T> {
+  return defer(() => {
+    const cleanup = fn()
+    return cleanup ? obs.pipe(finalize(() => cleanup())) : obs
+  })
+}

package/src/store/createStoreInstance.test.ts

@@ -13,12 +13,14 @@ describe('createStoreInstance', () => {
       randomUUID: () => 'test-uuid-1234',
     })
 
-    instance = createSanityInstance()
+    instance = createSanityInstance({projectId: 'test', dataset: 'test'})
   })
 
   const storeDef: StoreDefinition<{count: number}> = {
     name: 'TestStore',
-    getInitialState: () => ({count: 0}),
+    getInitialState: (inst) => ({
+      count: inst.config.projectId === 'test' ? 0 : -1,
+    }),
   }
 
   it('should create store instance with initial state', () => {

package/src/store/fetcherStore.test-d.ts

@@ -0,0 +1,121 @@
+import {of} from 'rxjs'
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from './createSanityInstance'
+import {
+  defineFetcher,
+  defineMutation,
+  type Fetcher,
+  type FetcherSnapshot,
+  type MutationResult,
+} from './fetcherStore'
+
+declare const instance: SanityInstance
+
+interface Widget {
+  id: string
+  label: string
+}
+
+// No explicit generics anywhere below: `TData` is inferred from `fetch`'s
+// `Observable<T>` and `TParams` from the annotated `getKey`/`fetch` params —
+// the whole handle is inferred from the definition, TanStack-style.
+
+// A list fetcher: no params, resolves to Widget[].
+const widgets = defineFetcher({
+  name: 'test-d-widgets',
+  getKey: () => 'all',
+  fetch: () => () => of<Widget[]>([]),
+})
+
+// A detail fetcher: one string param, resolves to Widget.
+const widget = defineFetcher({
+  name: 'test-d-widget',
+  getKey: (_i, id) => id,
+  fetch: () => (id: string) => of<Widget>({id, label: ''}),
+})
+
+test('the handle is inferred from the definition — no explicit generics', () => {
+  expectTypeOf(widgets).toEqualTypeOf<Fetcher<[], Widget[]>>()
+  expectTypeOf(widget).toEqualTypeOf<Fetcher<[id: string], Widget>>()
+})
+
+test('unannotated getKey params are inferred (not any) from the fetcher', () => {
+  defineFetcher({
+    name: 'test-d-getkey-infer',
+    // `id` is not annotated here — it must be inferred as `string` from `fetch`.
+    getKey: (_i, id) => {
+      expectTypeOf(id).toEqualTypeOf<string>()
+      return id
+    },
+    fetch: () => (id: string) => of<Widget>({id, label: ''}),
+  })
+})
+
+test('getState carries TData through the snapshot envelope (not unknown)', () => {
+  expectTypeOf(widgets.getState(instance).getCurrent()).toEqualTypeOf<FetcherSnapshot<Widget[]>>()
+})
+
+test('the snapshot discriminates data by status', () => {
+  const snap = widget.getState(instance, 'w1').getCurrent()
+  if (snap.status === 'success') {
+    expectTypeOf(snap.data).toEqualTypeOf<Widget>()
+    expectTypeOf(snap.dataUpdatedAt).toEqualTypeOf<number>()
+  }
+  if (snap.status === 'pending') {
+    expectTypeOf(snap.data).toEqualTypeOf<undefined>()
+  }
+})
+
+test('resolveState and refetch resolve to TData', () => {
+  expectTypeOf(widgets.resolveState(instance)).resolves.toEqualTypeOf<Widget[]>()
+  expectTypeOf(widget.refetch(instance, 'w1')).resolves.toEqualTypeOf<Widget>()
+})
+
+test('the params tuple is enforced per fetcher', () => {
+  // @ts-expect-error — detail fetcher requires an id
+  void widget.getState(instance)
+  // @ts-expect-error — id must be a string
+  void widget.getState(instance, 123)
+  // @ts-expect-error — list fetcher takes no params
+  void widgets.getState(instance, 'nope')
+})
+
+test('setData updater is typed to TData', () => {
+  widget.setData(instance, ['w1'], {id: 'w1', label: 'x'})
+  widget.setData(instance, ['w1'], (current) => {
+    expectTypeOf(current).toEqualTypeOf<Widget | undefined>()
+    return {id: 'w1', label: 'y'}
+  })
+  // @ts-expect-error — value must be a full Widget
+  widget.setData(instance, ['w1'], {id: 'w1'})
+  // @ts-expect-error — updater function must return TData
+  widget.setData(instance, ['w1'], () => 42)
+})
+
+test('defineMutation resolves to a MutationResult of TResult with a typed input', () => {
+  const createWidget = defineMutation<{label: string}, Widget>({
+    name: 'test-d-create-widget',
+    mutationFn: () => (input) => {
+      expectTypeOf(input).toEqualTypeOf<{label: string}>()
+      return of<Widget>({id: 'x', label: input.label})
+    },
+  })
+  expectTypeOf(createWidget(instance, {label: 'a'})).resolves.toEqualTypeOf<
+    MutationResult<Widget>
+  >()
+})
+
+test('CacheWriter enforces the target fetcher’s TData and TParams', () => {
+  defineMutation<void, void>({
+    name: 'test-d-write-through',
+    mutationFn: () => () => of(undefined),
+    onMutate: (write) => {
+      write(widget, ['w1'], {id: 'w1', label: 'ok'})
+      // @ts-expect-error — value must match the fetcher's TData (Widget)
+      write(widget, ['w1'], {nope: true})
+      // @ts-expect-error — params must match the fetcher's TParams ([string])
+      write(widget, [], {id: 'w1', label: 'ok'})
+    },
+  })
+})