@sanity/sdk 0.0.0-alpha.21 → 0.0.0-alpha.23

package/src/resources/README.md

@@ -1,370 +0,0 @@
-# SDK Resource Management
-
-## Resources
-
-In the SDK, we group together state and functions that concern that state into a unit called a **Resource**.
-
-To create a resource, call `createResource` with a `name` for the resource (this will be used as the key in the resource cache), a `getInitialState` function which takes in a `SanityInstance` and return the initial state, and an optional initialize function that can set up any subscriptions.
-
-```ts
-// documentList.ts
-import {SyncTag} from '@sanity/client'
-import {createResource} from '../resources/createResource'
-import {subscribeToLiveContentAndSetLastLiveEventId} from './subscribeToLiveContentAndSetLastLiveEventId'
-
-// declare the state shape for this resource
-interface DocumentListState {
-  results: DocumentHandle[]
-  syncTags: SyncTag[]
-  lastLiveEventId: string | null
-}
-
-export const documentList = createResource<DocumentListState>({
-  name: 'documentList',
-  getInitialState(instance) {
-    // utilize the instance to set a different initial state
-    // instance.config.someConfigOption
-
-    return {results: [], syncTags: [], lastLiveEventId: null}
-  },
-  initialize() {
-    // set up subscriptions
-    const liveContentSubscription = subscribeToLiveContentAndSetLastLiveEventId(this)
-
-    return () => {
-      // teardown / cleanup
-      // this function will be ran when `instance.dispose()` is called
-      liveContentSubscription.unsubscribe()
-    }
-  },
-})
-```
-
-## Actions
-
-**Actions** are functions that are auto-magically bound to a resource by using `createAction`.
-
-```ts
-// subscribeToLiveContentAndSetLastLiveEventId.ts
-import {createAction} from '../resources/createAction'
-import {getClientSource} from '../client/getClientSource'
-import {documentList} from './documentList'
-
-// use `createAction` to create a function that binds the resource's state
-export const subscribeToLiveContentAndSetLastLiveEventId = createAction(
-  // provide the resource you'd like to bind this action to
-  () => documentList,
-  // provide the implementation of the function using the provided `state` or `instance`
-  ({state, instance}) => {
-    // return a function, the parameters here will be the parameters of the resulting action
-    return function () {
-      const client$ = getClientSource(instance).observable
-      const liveMessage$ = client$.pipe(switchMap((client) => client.live.events()))
-
-      return liveMessage$.subscribe((e) => {
-        const {syncTags} = state.get()
-        if (e.type === 'message' && e.tags.some((tag) => syncTags.includes(tag))) {
-          state.set('setLastLiveEventId', {lastLiveEventId: e.id})
-        }
-      })
-    }
-  },
-)
-```
-
-`createAction` returns a function that takes in either just an `instance` or an object with a instance and the initialized resource state `{instance, state}`.
-
-If the initialized state is not passed into the action, it will call `getOrCreateResource` to grab the existing resource state or to initialize the resource state if not already created. Take a look at the [implementation](./createAction.ts) to see this in action.
-
----
-
-When using a resource action from the same resource, the convention is to pass `this` which is bound to an object that contains the initialized state and the current instance.
-
-```ts
-import {createAction} from '../resources/createAction'
-import {fooResource} from './fooResource'
-
-const privateFooAction = createAction(
-  () => fooResource,
-  ({state, instance}) => {
-    return function (value: string) {
-      // do something with state
-    }
-  },
-)
-
-export const publicFooAction = createAction(
-  () => fooResource,
-  ({state, instance}) => {
-    return function () {
-      const result = privateFooAction(this, 'some value')
-      return result
-    }
-  },
-)
-```
-
-When using a resource action from a different resource, the convention is to just pass in an instance and rely on `getOrCreateResource` to pull or create the state for the resource.
-
-```ts
-import {createAction} from '../resources/createAction'
-import {barResource} from './barResource'
-import {publicFooAction} from '../foo/publicFooAction'
-
-export const barActionThatUsesFooAction = createAction(
-  () => barResource,
-  ({state, instance}) => {
-    return function () {
-      const result = publicFooAction(instance)
-      return `from foo: ${result}`
-    }
-  },
-)
-```
-
-`this` is also available to be used in the `initialize` function provided to `createResource`
-
-```ts
-import {createResource} from '../resources/createResource'
-import {barActionThatUsesFooAction} from './barActionThatUsesFooAction'
-
-const barResource = createResource({
-  name: 'bar',
-  getInitialState: () => ({}),
-  initialize() {
-    const result = barActionThatUsesFooAction(this)
-    // ...
-
-    return () => {
-      // ...
-    }
-  },
-})
-```
-
-## Stores
-
-By default, actions are global meaning that calling them with a sanity instance will result in global resource state available to all actions that use the same resource.
-
-There are certain cases like the document list where we do not want global state. This is where `createStore` comes in.
-
-```ts
-interface TestState {
-  value: number
-}
-
-const testResource = createResource<TestState>({
-  name: 'test',
-  getInitialState: () => ({value: 0}),
-  initialize() {
-    // set up subscriptions etc
-    return () => {}
-  },
-})
-
-const inc = createAction(
-  () => testResource,
-  ({state}) => {
-    return function () {
-      state.set('increment', (prevState) => ({value: prevState.value + 1}))
-    }
-  },
-)
-
-const set = createAction(
-  () => testResource,
-  ({state}) => {
-    return function (value: number) {
-      state.set('setValue', {value})
-    }
-  },
-)
-
-const get = createAction(
-  () => testResource,
-  ({state}) => {
-    return function () {
-      return state.get().value
-    }
-  },
-)
-
-export const createTestStore = createStore(testResource, {inc, set, get})
-```
-
-Now `createTestStore` will return an object with the actions bound to it as methods.
-
-```ts
-import {createTestStore} from './createTestStore'
-
-const testStore = createTestStore(instance)
-
-console.log(testStore.get()) // 0
-testStore.inc()
-
-console.log(testStore.get()) // 1
-
-// calls the clean up function returned in initialize
-testStore.dispose()
-```
-
-## Resource State
-
-All resource actions are provided with a `state` param of type `ResourceState` that contains a `get`, `set`, and `observable` properties.
-
-```ts
-export type ResourceState<TState> = {
-  get: () => TState
-  set: (name: string, state: Partial<TState> | ((s: TState) => Partial<TState>)) => void
-  observable: Observable<TState>
-}
-```
-
-```ts
-import {map, distinctUntilChanged} from 'rxjs'
-import {createAction} from '../resources/createAction'
-import {myResource} from './myResource'
-
-export const myAction = createAction(
-  () => myResource,
-  ({state, instance}) => {
-    return function (value: string) {
-      // call `state.get` to get the current resource state
-      const currentState = state.get()
-
-      // call `state.set` with an update label (for redux dev tools)
-      // with either a new state value or a function that returns new state.
-      // Note: state.set is powered by zustand which always shallowly
-      // with the previous state in the store
-      // https://zustand.docs.pmnd.rs/guides/updating-state
-      state.set('stateUpdateLabel', (prev) => ({foo: value}))
-
-      // you can also subscribe to internal state changes via `state.observable`
-      const subscription = state.observable
-        .pipe(
-          map((s) => s.foo),
-          distinctUntilChanged(),
-        )
-        .subscribe(console.log)
-
-      return subscription
-    }
-  },
-)
-```
-
-## State Sources
-
-A `StateSource` represents a stream of changing values derived from the state of a resource.
-
-```ts
-export interface StateSource<T> {
-  // `getCurrent` allows the current state to be pulled without creating a subscription
-  getCurrent: () => T
-  // `subscribe` allows us to notify consumers when a new value is available.
-  // note that this callback does not accept any parameters and the expectation
-  // is for consumers to pull from `getCurrent`.
-  subscribe: (onStoreChanged: () => void) => () => void
-  // `observable` is provides combination of the above. on subscribe, this will
-  // emit the current value from `getCurrent` and will update when the above
-  // `subscribe` fires
-  observable: Observable<T>
-}
-```
-
-By convention, actions that return state sources should end with the `-State` suffix.
-
-```ts
-// example usage in a hook
-import {getSchemaState} from '@sanity/sdk'
-import {useSanityInstance} from '@sanity/sdk-react'
-
-export function useSchema(): Schema {
-  const instance = useSanityInstance()
-  const {subscribe, getCurrent} = useMemo(() => getSchemaState(instance), [instance])
-
-  return useSyncExternalStore(subscribe, getCurrent)
-}
-```
-
-```ts
-// example usage in an action
-import {getSchemaState} from '../schema/getSchemaState'
-import {createAction} from '../resources/createAction'
-import {myResource} from './myResource'
-
-export const myAction = createAction(
-  () => myResource,
-  ({state, instance}) => {
-    return function () {
-      const schema$ = getSchemaState(instance).observable
-
-      // ...
-    }
-  },
-)
-```
-
-Creating a state source involves creating a **selector** to pull the desired value from state and then using `createStateSourceAction`.
-
-```ts
-import {schemaStore} from './schemaStore'
-import {createStateSourceAction} from '../resources/createStateSourceAction'
-
-export const getSchemaState = createStateSourceAction(
-  () => schemaStore, // pick the resource
-  (state) => state.schema, // write a selector
-)
-```
-
-## Selectors
-
-Selectors are functions that extract and compute derived data from the resource state. When used with `createStateSourceAction`, they help create efficient state sources that only update when their selected data changes.
-
-```ts
-import {createSelector} from 'reselect'
-import {createStateSourceAction} from '../resources/createStateSourceAction'
-
-interface DocumentListState {
-  options: DocumentListOptions
-  lastLiveEventId?: string
-  syncTags: SyncTag[]
-  limit: number
-  results: DocumentHandle[]
-  isPending: boolean
-}
-
-const documentList = createResource<DocumentListState>({
-  name: 'documentList',
-  // ... resource implementation
-})
-
-const getDocumentListState = createStateSourceAction(
-  () => documentList,
-  // Basic selector that returns multiple state properties
-  createSelector(
-    [(state: DocumentListState) => state.results, (state: DocumentListState) => state.isPending],
-    (results, isPending) => ({results, isPending}),
-  ),
-)
-```
-
-**When to Use Reselect**
-
-If your selector simply returns an existing object from state without creating a new derived value, you **don't need reselect**:
-
-```ts
-// Simple selector that just returns an existing object - reselect not needed
-const getResults = createStateSourceAction(
-  () => documentList,
-  (state: DocumentListState) => state.results,
-)
-```
-
-However, when computing derived data that creates new objects, arrays, or values, `reselect` provides several key benefits:
-
-1. **Memoization**: The `createSelector` utility from reselect caches results and only recomputes when input selectors return new values, reducing unnecessary calculations.
-2. **Reference Stability**: By memoizing results, reselect helps maintain stable references which is crucial for preventing infinite loops in state source subscriptions.
-3. **Composition**: Input selectors can be either plain functions or other selectors, allowing you to build complex derivations while maintaining performance.
-
-Read more at [reselect.js.org](https://reselect.js.org/)

package/src/resources/createAction.test.ts

@@ -1,101 +0,0 @@
-import {describe, expect, it} from 'vitest'
-
-import {createSanityInstance} from '../instance/sanityInstance'
-import {type ActionContext, createAction, createInternalAction} from './createAction'
-import {createResource, createResourceState} from './createResource'
-
-const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
-
-interface TestState {
-  value: number
-}
-
-const testResource = createResource<TestState>({
-  name: 'test',
-  getInitialState: () => ({value: 0}),
-  initialize() {
-    return () => {}
-  },
-})
-
-describe('createAction', () => {
-  it('should create an action that can access state and instance', () => {
-    // Define an action that accesses state and instance
-    const testAction = createAction(testResource, ({state, instance: {identity}}) => {
-      return function () {
-        state.set('increment', (prev) => ({value: prev.value + 1}))
-        return identity.projectId
-      }
-    })
-
-    // Call the action with instance
-    const result = testAction(instance)
-
-    // Verify that the state and instance are correctly passed into the action
-    expect(result).toBe('test')
-    expect(createResourceState({value: 0}).get()).toEqual({value: 0})
-  })
-
-  it('should correctly update the state using set', () => {
-    const testAction = createAction(testResource, ({state, instance: {identity}}) => {
-      return function () {
-        state.set('increment', (prev) => ({value: prev.value + 1}))
-        return identity.projectId
-      }
-    })
-
-    const state = createResourceState({value: 1})
-    const actionContext: ActionContext<TestState> = {instance, state}
-
-    // call the action with state
-    const projectId = testAction(actionContext)
-    expect(projectId).toBe(instance.identity.projectId)
-
-    // Verify that the state has been changed
-    expect(state.get()).toEqual({value: 2})
-  })
-
-  it('should bind the action to a provided context and work without instance', () => {
-    const testAction = createAction(testResource, ({state}) => {
-      return function (value: number) {
-        state.set('updateValue', {value: value})
-        return state.get().value
-      }
-    })
-
-    const mockState = createResourceState({value: 10})
-    const result = testAction(
-      {state: mockState, instance: instance} as ActionContext<TestState>,
-      20,
-    )
-
-    expect(result).toBe(20)
-    expect(mockState.get()).toEqual({value: 20})
-
-    const mockState2 = createResourceState({value: 10})
-    const result2 = testAction({state: mockState2} as ActionContext<TestState>, 30)
-    expect(result2).toBe(30)
-    expect(mockState2.get()).toEqual({value: 30})
-  })
-})
-
-describe('createInternalAction', () => {
-  it('creates an action that requires state and instance', () => {
-    // Define an action that accesses state and instance
-    const testAction = createInternalAction<TestState, [], string>(
-      ({state, instance: {identity}}) => {
-        return function () {
-          state.set('increment', (prev) => ({value: prev.value + 1}))
-          return identity.projectId
-        }
-      },
-    )
-
-    const result = testAction({
-      state: createResourceState({value: 10}),
-      instance: instance,
-    } as ActionContext<TestState>)
-
-    expect(result).toBe('test')
-  })
-})

package/src/resources/createAction.ts

@@ -1,44 +0,0 @@
-import {type SanityInstance} from '../instance/types'
-import {getOrCreateResource, type Resource, type ResourceState} from './createResource'
-
-/** @public */
-export interface ActionContext<TState> {
-  instance: SanityInstance
-  state: ResourceState<TState>
-}
-
-type ResourceActionDefinition<TState, TParams extends unknown[], TReturn> = (
-  options: ActionContext<TState>,
-) => (this: ActionContext<TState>, ...args: TParams) => TReturn
-
-/**
- * @public
- */
-export type ResourceAction<TState, TParams extends unknown[], TReturn> = (
-  dependencies: SanityInstance | ActionContext<TState>,
-  ...params: TParams
-) => TReturn
-
-export function createAction<TState, TParams extends unknown[], TReturn>(
-  resource: Resource<TState>,
-  actionDefinition: ResourceActionDefinition<TState, TParams, TReturn>,
-): ResourceAction<TState, TParams, TReturn> {
-  return (dependencies: SanityInstance | ActionContext<TState>, ...args: TParams): TReturn => {
-    const instance = 'state' in dependencies ? dependencies.instance : dependencies
-    const {state} =
-      'state' in dependencies ? dependencies : getOrCreateResource(dependencies, resource)
-    const actionContext = {instance, state}
-    return actionDefinition(actionContext).bind(actionContext)(...args)
-  }
-}
-
-/**
- * @internal
- */
-export function createInternalAction<TState, TParams extends unknown[], TReturn>(
-  actionDefinition: ResourceActionDefinition<TState, TParams, TReturn>,
-) {
-  return (actionContext: ActionContext<TState>, ...args: TParams): TReturn => {
-    return actionDefinition(actionContext).bind(actionContext)(...args)
-  }
-}

package/src/resources/createResource.test.ts

@@ -1,112 +0,0 @@
-import {describe, expect, it, vi} from 'vitest'
-
-import {createSanityInstance} from '../instance/sanityInstance'
-import {
-  createResource,
-  disposeResources,
-  getOrCreateResource,
-  initializeResource,
-  type Resource,
-} from './createResource'
-
-describe('createResource', () => {
-  const instance = createSanityInstance({projectId: 'test', dataset: 'test'})
-
-  interface TestState {
-    value: number
-  }
-
-  const testResource: Resource<TestState> = createResource<TestState>({
-    name: 'test',
-    getInitialState: () => ({value: 0}),
-    initialize: vi.fn(),
-  })
-
-  it('should return the same state from getOrCreateResource', () => {
-    const resource1 = getOrCreateResource(instance, testResource)
-    const resource2 = getOrCreateResource(instance, testResource)
-    expect(resource1).toBe(resource2)
-  })
-
-  it('should initialize a resource with initial state', () => {
-    const initialState = {value: 1}
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => initialState,
-    })
-
-    const {state} = initializeResource(instance, resource)
-    expect(state.get()).toEqual(initialState)
-  })
-
-  it('should invoke the init function on initialization', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-      initialize: vi.fn(),
-    })
-
-    initializeResource(instance, resource)
-    expect(resource.initialize).toHaveBeenCalledTimes(1)
-  })
-
-  it('should update the state using set method', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-    })
-
-    const {state} = initializeResource(instance, resource)
-    state.set('increment', (prevState) => ({value: prevState.value + 1}))
-    expect(state.get()).toEqual({value: 1})
-  })
-
-  it('should create an observable from the state', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-    })
-    const {state} = initializeResource(instance, resource)
-    const next = vi.fn()
-    state.observable.subscribe(next)
-    state.set('increment', (prevState) => ({value: prevState.value + 1}))
-    expect(next).toHaveBeenCalledTimes(2) // inital and updated
-    expect(next).toHaveBeenLastCalledWith({value: 1})
-  })
-
-  it('should return a disposable object with a dispose function', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-      initialize: vi.fn(() => vi.fn()),
-    })
-
-    const {dispose} = initializeResource(instance, resource)
-    dispose()
-    expect(resource.initialize).toHaveReturnedWith(expect.any(Function))
-    expect(resource.initialize).toHaveBeenCalledTimes(1)
-  })
-
-  it('should not throw when no dispose function is supplied', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-    })
-    const {dispose} = initializeResource(instance, resource)
-    expect(() => dispose()).not.toThrowError()
-  })
-
-  it('should clear resource caqche on disposeResources', () => {
-    const resource = createResource<TestState>({
-      name: 'test',
-      getInitialState: () => ({value: 0}),
-    })
-
-    getOrCreateResource(instance, resource)
-    disposeResources(instance.identity)
-
-    const {state} = initializeResource(instance, resource)
-
-    expect(state.get()).toEqual({value: 0})
-  })
-})