@sanity/sdk 0.0.0-alpha.1

package/src/documentList/documentListStore.ts

@@ -0,0 +1,269 @@
+import type {SyncTag} from '@sanity/client'
+import {isEqual} from 'lodash-es'
+import {
+  distinctUntilChanged,
+  map,
+  Observable,
+  pairwise,
+  startWith,
+  type Subscribable,
+  switchMap,
+  tap,
+} from 'rxjs'
+import {devtools} from 'zustand/middleware'
+import {createStore} from 'zustand/vanilla'
+
+import {getClientStore} from '../client/store/clientStore'
+import type {SanityInstance} from '../instance/types'
+
+const PAGE_SIZE = 50
+
+const API_VERSION = 'vX'
+
+/**
+ * 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
+ */
+export interface DocumentHandle {
+  _id: string
+  _type: string
+}
+
+/**
+ * Represents the current state of a document list, including the query options
+ * and loading status.
+ * @public
+ */
+export interface DocumentListState extends DocumentListOptions {
+  /** Array of document handles in the current result set, or null if not yet loaded */
+  result: DocumentHandle[] | null
+  /** Indicates whether the document list is currently loading */
+  isPending: boolean
+}
+
+/**
+ * Represents a sort ordering configuration.
+ * @public
+ */
+export interface SortOrderingItem {
+  field: string
+  direction: 'asc' | 'desc'
+}
+
+/**
+ * Configuration options for filtering and sorting documents in a document list.
+ * @public
+ */
+export interface DocumentListOptions {
+  /** GROQ filter expression to query specific documents */
+  filter?: string
+  /** Array of sort ordering specifications to determine the order of results */
+  sort?: SortOrderingItem[]
+}
+
+/**
+ * Manages the state and operations for a list of Sanity documents.
+ * Provides methods to update options, load more documents, and subscribe to
+ * state changes.
+ *
+ * Implements a subscription model where you can register callback functions
+ * to be notified when the document list state changes.
+ * @public
+ */
+export interface DocumentListStore extends Subscribable<DocumentListState> {
+  /** Updates the filtering and sorting options for the document list */
+  setOptions: (options: DocumentListOptions) => void
+  /** Retrieves the current state of the document list synchronously */
+  getCurrent: () => DocumentListState
+  /** Loads the next page of documents */
+  loadMore: () => void
+  /** Cleans up resources and subscriptions when the store is no longer needed */
+  dispose: () => void
+}
+
+interface DocumentListInternalState extends DocumentListOptions {
+  isPending: boolean
+  lastLiveEventId?: string
+  syncTags: Set<SyncTag>
+  limit: number
+  result: DocumentHandle[] | null
+}
+
+/**
+ * Creates a `DocumentListStore` from a `SanityInstance`.
+ *
+ * @public
+ *
+ * See {@link SanityInstance} and {@link DocumentListStore}
+ */
+export function createDocumentListStore(instance: SanityInstance): DocumentListStore {
+  const clientStore = getClientStore(instance)
+  const clientStream$ = new Observable(
+    clientStore.getClientEvents({apiVersion: API_VERSION}).subscribe,
+  )
+
+  const initialState: DocumentListInternalState = {
+    syncTags: new Set<SyncTag>(),
+    isPending: false,
+    result: null,
+    limit: PAGE_SIZE,
+  }
+
+  const store = createStore<DocumentListInternalState>()(
+    devtools((..._unusedArgs) => initialState, {
+      name: 'SanityDocumentListStore',
+      enabled: true, // Should be process.env.NODE_ENV === 'development'
+    }),
+  )
+
+  const liveSubscription = clientStream$
+    .pipe(
+      switchMap((client) => client.live.events({includeDrafts: true, tag: 'sdk.live-listener'})),
+    )
+    .subscribe({
+      next: (event) => {
+        const {syncTags} = store.getState()
+        if (event.type === 'message' && event.tags.some((tag) => syncTags.has(tag))) {
+          store.setState(
+            {lastLiveEventId: event.id},
+            false,
+            'UPDATE_EVENT_ID_FROM_LIVE_CONTENT_API',
+          )
+        }
+      },
+    })
+
+  const resultSubscription = new Observable<DocumentListInternalState>((observer) =>
+    store.subscribe((state) => observer.next(state)),
+  )
+    .pipe(
+      distinctUntilChanged((prev, current) => {
+        if (prev.filter !== current.filter) return false
+        if (prev.lastLiveEventId !== current.lastLiveEventId) return false
+        if (!isEqual(prev.sort, current.sort)) return false
+        if (prev.limit !== current.limit) return false
+        return true
+      }),
+      tap(() => store.setState({isPending: true}, false, {type: 'START_FETCH'})),
+      switchMap((state) => {
+        const filter = state.filter ? `[${state.filter}]` : ''
+        const order = state.sort
+          ? `| order(${state.sort
+              .map((ordering) =>
+                [ordering.field, ordering.direction.toLowerCase()]
+                  .map((str) => str.trim())
+                  .filter(Boolean)
+                  .join(' '),
+              )
+              .join(',')})`
+          : ''
+
+        return clientStream$.pipe(
+          switchMap((client) =>
+            client.observable.fetch(
+              `*${filter}${order}[0..$__limit]{_id, _type}`,
+              {__limit: state.limit},
+              {
+                filterResponse: false,
+                returnQuery: false,
+                lastLiveEventId: state.lastLiveEventId,
+                tag: 'sdk.document-list',
+                // // TODO: this should use the `previewDrafts` perspective for
+                // // removing duplicates in the result set but the live content API
+                // // does not currently return the correct sync tags. CLDX has
+                // // planned to add perspective support to the live content API
+                // // in december of 2024
+                // perspective: 'previewDrafts'
+              },
+            ),
+          ),
+        )
+      }),
+    )
+    .subscribe({
+      next: ({syncTags, result}) => {
+        store.setState(
+          {
+            syncTags: new Set(syncTags),
+            result,
+            isPending: false,
+          },
+          false,
+          {type: 'UPDATE_FROM_FETCH'},
+        )
+      },
+    })
+
+  function setOptions({filter, sort}: DocumentListOptions) {
+    store.setState(
+      {
+        // spreads properties only if they exist, preserving other state
+        // properties set in the zustand store already
+        ...(filter && {filter}),
+        ...(sort && {sort}),
+      },
+      false,
+      {type: 'SET_OPTIONS'},
+    )
+  }
+
+  function loadMore() {
+    store.setState((prev) => ({limit: prev.limit + PAGE_SIZE}), undefined, {type: 'LOAD_MORE'})
+  }
+
+  function getCurrent() {
+    const {isPending, result, filter, sort} = store.getState()
+    return {isPending, result, filter, sort}
+  }
+
+  const state$ = new Observable<DocumentListState>((observer) => {
+    function emitCurrent() {
+      const {isPending, result, filter, sort} = store.getState()
+      observer.next({
+        isPending,
+        result,
+        filter,
+        sort,
+      })
+    }
+
+    emitCurrent()
+    return store.subscribe(emitCurrent)
+  }).pipe(
+    distinctUntilChanged((prev, curr) => {
+      if (!isEqual(prev.sort, curr.sort)) return false
+      if (prev.result !== curr.result) return false
+      if (prev.filter !== curr.filter) return false
+      if (prev.isPending !== curr.isPending) return false
+      return true
+    }),
+    startWith(null),
+    pairwise(),
+    map((arg): DocumentListState => {
+      // casting this since `curr` will never be null
+      const [prev, curr] = arg as [DocumentListState | null, DocumentListState]
+      if (!prev?.result) return curr
+      if (!curr?.result) return curr
+
+      const prevMap = prev.result.reduce<Map<string, DocumentHandle>>((acc, handle) => {
+        acc.set(handle._id, handle)
+        return acc
+      }, new Map())
+
+      return {
+        ...curr,
+        result: curr.result.map((i) => prevMap.get(i._id) ?? i),
+      }
+    }),
+  )
+
+  const subscribe = state$.subscribe.bind(state$)
+
+  function dispose() {
+    liveSubscription.unsubscribe()
+    resultSubscription.unsubscribe()
+  }
+
+  return {setOptions, getCurrent, loadMore, subscribe, dispose}
+}

package/src/instance/identity.test.ts

@@ -0,0 +1,46 @@
+import {describe, expect, it} from 'vitest'
+
+import {getSdkIdentity} from './identity'
+
+describe('identity', () => {
+  describe('getSdkIdentity', () => {
+    it('creates a frozen object with expected properties', () => {
+      const identity = getSdkIdentity({
+        projectId: 'test-project',
+        dataset: 'test-dataset',
+      })
+
+      // Check if object is frozen
+      expect(Object.isFrozen(identity)).toBe(true)
+
+      // Check if all expected properties exist
+      expect(identity).toHaveProperty('id')
+      expect(identity).toHaveProperty('projectId', 'test-project')
+      expect(identity).toHaveProperty('dataset', 'test-dataset')
+    })
+
+    it('generates unique ids for different instances', () => {
+      const identity1 = getSdkIdentity({
+        projectId: 'test-project',
+        dataset: 'test-dataset',
+      })
+
+      const identity2 = getSdkIdentity({
+        projectId: 'test-project',
+        dataset: 'test-dataset',
+      })
+
+      expect(identity1.id).not.toBe(identity2.id)
+    })
+
+    it('generates id with correct format', () => {
+      const identity = getSdkIdentity({
+        projectId: 'test-project',
+        dataset: 'test-dataset',
+      })
+
+      // ID should be 16 characters long (8 pairs of hex digits)
+      expect(identity.id).toMatch(/^[0-9a-f]{16}$/)
+    })
+  })
+})

package/src/instance/identity.ts

@@ -0,0 +1,28 @@
+import type {SdkIdentity} from './types'
+
+/**
+ * thoughtLevel 2 - Primarily what we want is to have an object that we can bind stores/memoizations to, but let the things that depend on it (eg projectId, dataset) be internals that can't be overwritten by accident/intentionally
+ * @public
+ */
+export function getSdkIdentity({
+  projectId,
+  dataset,
+}: {
+  projectId: string
+  dataset: string
+}): SdkIdentity {
+  const id = generateId()
+  return Object.freeze({
+    id,
+    projectId,
+    dataset,
+  })
+}
+
+function generateId() {
+  return Array.from({length: 8}, () =>
+    Math.floor(Math.random() * 16)
+      .toString(16)
+      .padStart(2, '0'),
+  ).join('')
+}

package/src/instance/sanityInstance.test.ts

@@ -0,0 +1,66 @@
+import {beforeEach, describe, expect, test} from 'vitest'
+
+import {createSanityInstance, getOrCreateResource, type SanityConfig} from './sanityInstance'
+
+describe('sanityInstance', () => {
+  let config: SanityConfig
+
+  beforeEach(() => {
+    config = {
+      projectId: 'test-project',
+      dataset: 'test-dataset',
+    }
+  })
+
+  describe('createSanityInstance', () => {
+    test('creates instance with correct configuration', () => {
+      const instance = createSanityInstance(config)
+
+      expect(instance.identity).toEqual(
+        expect.objectContaining({
+          projectId: 'test-project',
+          dataset: 'test-dataset',
+        }),
+      )
+    })
+  })
+
+  describe('getOrCreateResource', () => {
+    test('creates and caches resource', () => {
+      const instance = createSanityInstance(config)
+      let createCount = 0
+
+      const creator = () => {
+        createCount++
+        return {value: 'test-resource'}
+      }
+
+      // First call should create new resource
+      const resource1 = getOrCreateResource(instance, 'test-key', creator)
+      expect(resource1).toEqual({value: 'test-resource'})
+      expect(createCount).toBe(1)
+
+      // Second call should return cached resource
+      const resource2 = getOrCreateResource(instance, 'test-key', creator)
+      expect(resource2).toBe(resource1)
+      expect(createCount).toBe(1)
+    })
+
+    test('different instances have separate resource caches', () => {
+      const instance1 = createSanityInstance({...config, projectId: 'project1'})
+      const instance2 = createSanityInstance({...config, projectId: 'project2'})
+      let createCount = 0
+
+      const creator = () => {
+        createCount++
+        return {value: 'test-resource'}
+      }
+
+      const resource1 = getOrCreateResource(instance1, 'test-key', creator)
+      const resource2 = getOrCreateResource(instance2, 'test-key', creator)
+
+      expect(resource1).not.toBe(resource2)
+      expect(createCount).toBe(2)
+    })
+  })
+})

package/src/instance/sanityInstance.ts

@@ -0,0 +1,64 @@
+import type {AuthConfig} from '../auth/internalAuthStore'
+import {getSdkIdentity} from './identity'
+import type {SanityInstance, SdkIdentity} from './types'
+
+/**
+ * @public
+ */
+export interface SanityConfig {
+  projectId: string
+  dataset: string
+  auth?: AuthConfig
+}
+
+/**
+ * Returns a new instance of dependencies required for SanitySDK.
+ *
+ * @public
+ *
+ * @param config - The configuration for this instance
+ *
+ * @returns A new "instance" of a Sanity SDK, used to bind resources/configuration to it
+ */
+export function createSanityInstance({
+  projectId = '',
+  dataset = '',
+  ...config
+}: SanityConfig): SanityInstance {
+  return {
+    identity: getSdkIdentity({projectId, dataset}),
+    config,
+  }
+}
+
+const resourceStorage = new WeakMap<SdkIdentity, Map<string, unknown>>()
+
+function getResource(instance: SanityInstance, key: string) {
+  const instanceMap = resourceStorage.get(instance.identity)
+  return instanceMap?.get(key)
+}
+
+function setResource(instance: SanityInstance, key: string, value: unknown) {
+  let instanceMap = resourceStorage.get(instance.identity)
+  if (!instanceMap) {
+    instanceMap = new Map()
+    resourceStorage.set(instance.identity, instanceMap)
+  }
+  instanceMap.set(key, value)
+}
+
+/**
+ * This is an internal function that retrieves or creates a Zustand store resource.
+ * @internal
+ */
+export function getOrCreateResource<T>(instance: SanityInstance, key: string, creator: () => T): T {
+  const cached = getResource(instance, key)
+
+  if (cached) {
+    return cached as T
+  }
+
+  const resource = creator()
+  setResource(instance, key, resource)
+  return resource
+}

package/src/instance/types.d.ts

@@ -0,0 +1,29 @@
+import type {ClientStore} from '../client/store/clientStore'
+import type {SchemaStore} from '../schema/schemaStore'
+import type {SanityConfig} from './sanityInstance'
+
+/** @internal */
+export interface InternalStores {
+  clientStore?: ClientStore
+  schemaStore?: SchemaStore
+}
+
+/** @public */
+export interface SanityInstance {
+  /**
+   * The following is used to look up resources associated with this instance,
+   * and can be used to retrieve an "id" for the instance - useful in debugging.
+   *
+   * @public
+   */
+  readonly identity: SdkIdentity
+
+  config: Omit<SanityConfig, 'projectId' | 'dataset'>
+}
+
+/** @public */
+export interface SdkIdentity {
+  readonly id: string
+  readonly projectId: string
+  readonly dataset: string
+}

package/src/schema/schemaStore.test.ts

@@ -0,0 +1,30 @@
+import {describe, expect, it} from 'vitest'
+
+import {createSchemaStore} from './schemaStore'
+
+describe('schemaStore', () => {
+  it('should create a store with initial schema types', () => {
+    const mockTypes = [{name: 'post', type: 'document'}]
+    const store = createSchemaStore(mockTypes)
+
+    expect(store.getState().schema).toEqual({types: mockTypes})
+  })
+
+  it('should update schema when setSchema is called', () => {
+    const store = createSchemaStore([])
+    const newSchema = {types: [{name: 'author', type: 'document'}]}
+
+    store.getState().setSchema(newSchema)
+
+    expect(store.getState().schema).toEqual(newSchema)
+  })
+
+  it('should maintain store reference when updating schema', () => {
+    const store = createSchemaStore([])
+    const initialStoreRef = store
+
+    store.getState().setSchema({types: []})
+
+    expect(store).toBe(initialStoreRef)
+  })
+})

package/src/schema/schemaStore.ts

@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type {StoreApi} from 'zustand'
+import {devtools} from 'zustand/middleware'
+import {createStore} from 'zustand/vanilla'
+
+/** @public */
+export interface SchemaState {
+  schema: any
+  setSchema: (newSchema: any) => void
+}
+
+/** @public */
+export type SchemaStore = StoreApi<SchemaState>
+
+/**
+ * This is an internal function that creates a Zustand store for the schema.
+ * @internal
+ */
+export const createSchemaStore = (schemaTypes: any[]): SchemaStore => {
+  return createStore<SchemaState>()(
+    devtools(
+      (set) => ({
+        schema: {types: schemaTypes},
+        setSchema: (newSchema) => set({schema: newSchema}, false, 'setSchema'),
+      }),
+      {
+        name: 'SanitySchemaStore',
+        enabled: true, // Should be process.env.NODE_ENV === 'development'
+      },
+    ),
+  )
+}

package/src/store/createStore.test.ts

@@ -0,0 +1,108 @@
+import {describe, expect, it, vi} from 'vitest'
+
+import type {SanityInstance} from '../instance/types'
+import {createStore, type StoreActionContext} from './createStore'
+
+// Mock the devtools middleware
+vi.mock('zustand/middleware', () => ({
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  devtools: (storeFunction: any) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (...args: any[]) => storeFunction(...args)
+  },
+}))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('createStore', () => {
+  // Setup mock instance
+  const mockInstance = {
+    identity: {
+      id: 'test-id',
+    },
+  } as SanityInstance
+
+  // Setup types for our test store
+  interface TestState {
+    count: number
+    text: string
+  }
+
+  const initialState: TestState = {
+    count: 0,
+    text: '',
+  }
+
+  // Setup test actions
+  const createTestActions = () => ({
+    increment: ({store}: StoreActionContext<TestState>) => {
+      const state = store.getState()
+      store.setState({...state, count: state.count + 1})
+    },
+    setText: ({store}: StoreActionContext<TestState>, newText: string) => {
+      const state = store.getState()
+      store.setState({...state, text: newText})
+      return newText
+    },
+    getCount: ({store}: StoreActionContext<TestState>) => {
+      return store.getState().count
+    },
+    getText: ({store}: StoreActionContext<TestState>) => {
+      return store.getState().text
+    },
+  })
+
+  it('creates a store with initial state with all properties', () => {
+    const actions = createTestActions()
+    const store = createStore(initialState, actions, {
+      name: 'test-store',
+      instance: mockInstance,
+    })
+
+    // Verify store has all action methods
+    expect(store).toHaveProperty('increment')
+    expect(store).toHaveProperty('setText')
+    expect(store).toHaveProperty('getCount')
+  })
+
+  it('maintains separate state for different stores', () => {
+    const actions = createTestActions()
+    const store1 = createStore(initialState, actions, {
+      name: 'store-1',
+      instance: mockInstance,
+    })
+    const store2 = createStore(initialState, actions, {
+      name: 'store-2',
+      instance: mockInstance,
+    })
+
+    store1.increment()
+    store2.setText('hello')
+
+    // Verify stores are unaffected
+    expect(store1.getCount()).toBe(1)
+    expect(store2.getCount()).toBe(0)
+
+    expect(store1.getText()).toBe('')
+    expect(store2.getText()).toBe('hello')
+  })
+
+  it('correctly updates state through actions', () => {
+    const actions = createTestActions()
+    const store = createStore(initialState, actions, {
+      name: 'test-store',
+      instance: mockInstance,
+    })
+
+    store.increment()
+    expect(store.getCount()).toBe(1)
+
+    store.increment()
+    expect(store.getCount()).toBe(2)
+
+    store.setText('hello world')
+    expect(store.getText()).toBe('hello world')
+  })
+})