@sanity/sdk 2.18.0 → 3.0.0-rc.1

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()
+  })
+})