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

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)
  *   }
  * )
@@ -157,11 +157,11 @@ interface StateSourceOptions<TState, TParams extends unknown[], TReturn, TKey> {
  *
  * const getDocument = bindActionByResource(
  *   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'})
+    },
+  })
+})

package/src/store/fetcherStore.test.ts

@@ -0,0 +1,299 @@
+import {NEVER, of, startWith, Subject, throwError} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createSanityInstance, type SanityInstance} from './createSanityInstance'
+import {defineFetcher, defineMutation, type Fetcher} from './fetcherStore'
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+describe('fetcherStore', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.useRealTimers()
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('fetches on subscribe and exposes a success snapshot', async () => {
+    const fetcher = defineFetcher<[number], string>({
+      name: 'basic',
+      getKey: (_i, id) => `${id}`,
+      fetch: () => (id) => of(`data-${id}`),
+    })
+
+    const data = await fetcher.resolveState(instance, 1)
+    expect(data).toBe('data-1')
+    expect(fetcher.getState(instance, 1).getCurrent()).toMatchObject({
+      status: 'success',
+      data: 'data-1',
+      isFetching: false,
+    })
+  })
+
+  it('serves fresh data without refetching, and revalidates once stale', async () => {
+    const fetchSpy = vi.fn((id: number) => of(`v-${id}`))
+    const fetcher = defineFetcher<[number], string>({
+      name: 'swr',
+      staleTime: 10_000,
+      getKey: (_i, id) => `${id}`,
+      fetch: () => fetchSpy,
+    })
+
+    const first = fetcher.getState(instance, 1)
+    const unsub1 = first.subscribe()
+    await vi.waitFor(() => expect(first.getCurrent().status).toBe('success'))
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    unsub1()
+
+    // Re-subscribe within staleTime — fresh, so no refetch.
+    const second = fetcher.getState(instance, 1)
+    const unsub2 = second.subscribe()
+    await flush()
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    unsub2()
+
+    // Invalidation forces staleness — an active subscriber revalidates.
+    const third = fetcher.getState(instance, 1)
+    const unsub3 = third.subscribe()
+    await flush()
+    fetcher.invalidate(instance, 1)
+    await vi.waitFor(() => expect(fetchSpy).toHaveBeenCalledTimes(2))
+    unsub3()
+  })
+
+  it('invalidate refetches an actively-subscribed entry', async () => {
+    let n = 0
+    const fetcher = defineFetcher<[], number>({
+      name: 'invalidate',
+      getKey: () => 'k',
+      fetch: () => () => of(++n),
+    })
+
+    const source = fetcher.getState(instance)
+    const unsub = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().data).toBe(1))
+
+    fetcher.invalidate(instance)
+    await vi.waitFor(() => expect(source.getCurrent().data).toBe(2))
+    unsub()
+  })
+
+  it('refetch bypasses staleness and resolves with fresh data', async () => {
+    let n = 0
+    const fetcher = defineFetcher<[], number>({
+      name: 'refetch',
+      staleTime: 60_000,
+      getKey: () => 'k',
+      fetch: () => () => of(++n),
+    })
+
+    expect(await fetcher.resolveState(instance)).toBe(1)
+    expect(await fetcher.refetch(instance)).toBe(2)
+  })
+
+  it('surfaces an initial failure as an error snapshot, background failure on the success arm', async () => {
+    let attempt = 0
+    const fetcher = defineFetcher<[], string>({
+      name: 'errors',
+      getKey: () => 'k',
+      fetch: () => () => (attempt++ === 0 ? throwError(() => new Error('boom')) : of('recovered')),
+    })
+
+    await expect(fetcher.resolveState(instance)).rejects.toThrow('boom')
+    expect(fetcher.getState(instance).getCurrent().status).toBe('error')
+
+    // Now succeed, then fail a background revalidation: data stays, error attaches.
+    await fetcher.refetch(instance)
+    expect(fetcher.getState(instance).getCurrent()).toMatchObject({
+      status: 'success',
+      data: 'recovered',
+    })
+  })
+
+  it('pre-seeds an entry via initialData without fetching when the seed is fresh', async () => {
+    const fetchSpy = vi.fn(() => of('fetched'))
+    const fetcher = defineFetcher<[], string>({
+      name: 'seeded',
+      staleTime: 10_000,
+      getKey: () => 'k',
+      fetch: () => fetchSpy,
+      initialData: () => ({data: 'seeded', dataUpdatedAt: Date.now()}),
+    })
+
+    const source = fetcher.getState(instance)
+    const unsub = source.subscribe()
+    await flush()
+
+    expect(source.getCurrent()).toMatchObject({status: 'success', data: 'seeded'})
+    expect(fetchSpy).not.toHaveBeenCalled()
+    unsub()
+  })
+
+  it('setData writes optimistically and can be undone', () => {
+    const fetcher = defineFetcher<[], string>({
+      name: 'setdata',
+      getKey: () => 'k',
+      fetch: () => () => NEVER,
+    })
+
+    const {undo} = fetcher.setData(instance, [], 'written')
+    expect(fetcher.getState(instance).getCurrent().data).toBe('written')
+
+    undo()
+    expect(fetcher.getState(instance).getCurrent().status).toBe('pending')
+  })
+
+  it('garbage-collects an entry written without a subscriber after gcTime', async () => {
+    const fetcher = defineFetcher<[], string>({
+      name: 'gc-orphan',
+      gcTime: 5,
+      getKey: () => 'k',
+      fetch: () => () => NEVER,
+    })
+
+    // No subscriber ever holds this entry (as an optimistic mutation write would),
+    // so only setData's own GC scheduling can clean it up.
+    fetcher.setData(instance, [], 'written')
+    expect(fetcher.getState(instance).getCurrent().data).toBe('written')
+
+    await vi.waitFor(() => expect(fetcher.getState(instance).getCurrent().status).toBe('pending'))
+  })
+
+  it('rolls back optimistic writes when a mutation fails', async () => {
+    const fetcher = defineFetcher<[], string>({
+      name: 'mutate-rollback',
+      getKey: () => 'k',
+      fetch: () => () => NEVER,
+    })
+    fetcher.setData(instance, [], 'server')
+
+    const failing = defineMutation<string, never>({
+      name: 'rename-fail',
+      mutationFn: () => () => throwError(() => new Error('rejected')),
+      onMutate: (write, value) => write(fetcher, [], value),
+    })
+
+    await expect(failing(instance, 'optimistic')).rejects.toThrow('rejected')
+    expect(fetcher.getState(instance).getCurrent().data).toBe('server')
+  })
+
+  it('reconciles tagged entries after a successful mutation', async () => {
+    let n = 0
+    const list = defineFetcher<[], number>({
+      name: 'list',
+      getKey: () => 'all',
+      tags: [{type: 'thing', id: 'LIST'}],
+      fetch: () => () => of(++n),
+    })
+
+    const source = list.getState(instance)
+    const unsub = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().data).toBe(1))
+
+    const create = defineMutation<void, {ok: true}>({
+      name: 'create-thing',
+      mutationFn: () => () => of({ok: true}),
+      invalidates: [{type: 'thing', id: 'LIST'}],
+    })
+
+    const {invalidated} = await create(instance, undefined)
+    await invalidated
+    expect(source.getCurrent().data).toBe(2)
+    unsub()
+  })
+
+  it('discards a revalidation result that lands after an optimistic write', async () => {
+    const server = new Subject<string>()
+    const fetcher: Fetcher<[], string> = defineFetcher<[], string>({
+      name: 'version-guard',
+      staleTime: 0,
+      getKey: () => 'k',
+      fetch: () => () => server.pipe(startWith('initial')),
+    })
+
+    const source = fetcher.getState(instance)
+    const unsub = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().data).toBe('initial'))
+
+    // Force a refetch (in flight, no value yet), then write optimistically.
+    const refetching = fetcher.refetch(instance)
+    fetcher.setData(instance, [], 'optimistic')
+    expect(source.getCurrent().data).toBe('optimistic')
+
+    // Late server value must NOT clobber the optimistic write.
+    server.next('late-server')
+    await refetching
+    expect(source.getCurrent().data).toBe('optimistic')
+    unsub()
+  })
+
+  it('settles a pre-empted in-flight fetch when a forced refetch replaces it', async () => {
+    const server = new Subject<string>()
+    const fetcher = defineFetcher<[], string>({
+      name: 'preempt',
+      getKey: () => 'k',
+      fetch: () => () => server,
+    })
+
+    // First refetch is in flight with no value yet; a second forced refetch
+    // pre-empts it. Both promises must settle rather than hang.
+    const first = fetcher.refetch(instance)
+    const second = fetcher.refetch(instance)
+
+    server.next('data')
+    server.complete()
+
+    await expect(first).resolves.toBe('data')
+    await expect(second).resolves.toBe('data')
+  })
+
+  it('clears isFetching when a discarded revalidation runs on a non-completing source', async () => {
+    const server = new Subject<string>()
+    const fetcher = defineFetcher<[], string>({
+      name: 'version-guard-fetching',
+      staleTime: 0,
+      getKey: () => 'k',
+      fetch: () => () => server,
+    })
+
+    const source = fetcher.getState(instance)
+    const unsub = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().isFetching).toBe(true))
+
+    // Optimistic write bumps the version while the fetch is still in flight.
+    fetcher.setData(instance, [], 'optimistic')
+
+    // The late server value is discarded (version guard) — and because the source
+    // never completes, isFetching must be cleared here, not left stuck true.
+    server.next('late')
+    await flush()
+    expect(source.getCurrent()).toMatchObject({data: 'optimistic', isFetching: false})
+    unsub()
+  })
+
+  it('polls on refetchInterval while an entry has subscribers', async () => {
+    let n = 0
+    const fetcher = defineFetcher<[], number>({
+      name: 'polling',
+      staleTime: 60_000,
+      refetchInterval: 10,
+      getKey: () => 'k',
+      fetch: () => () => of(++n),
+    })
+
+    const source = fetcher.getState(instance)
+    const unsub = source.subscribe()
+    await vi.waitFor(() => expect((source.getCurrent().data ?? 0) >= 1).toBe(true))
+
+    // Fresh per staleTime, so any further increase can only come from the interval.
+    const before = source.getCurrent().data ?? 0
+    await vi.waitFor(() => expect((source.getCurrent().data ?? 0) > before).toBe(true), {
+      timeout: 500,
+    })
+    unsub()
+  })
+})