@sanity/sdk 3.0.0-rc.1 → 3.0.0

package/src/presence/types.ts

@@ -1,27 +1,199 @@
 import {type SanityClient} from '@sanity/client'
+import {type Path} from '@sanity/types'
 import {type Observable} from 'rxjs'
 
+import {type PerspectiveHandle} from '../config/sanityConfig'
 import {type SanityUser} from '../users/types'
 
-/** @public */
+/**
+ * One end of a text selection: a Portable Text path plus a character offset
+ * within the span it addresses.
+ * @public
+ */
+export interface PresenceSelectionPoint {
+  path: Path
+  offset: number
+}
+
+/**
+ * A Portable Text caret or selected range, as exchanged with the Studio.
+ *
+ * Structurally identical to `EditorSelection` from `@portabletext/editor`, and
+ * declared separately so that `@sanity/sdk` stays free of React dependencies. A
+ * value from the editor can be passed straight through, and vice versa.
+ *
+ * `offset` is a character offset within the span that `path` addresses.
+ * @public
+ */
+export type PresenceSelection = {
+  anchor: PresenceSelectionPoint
+  focus: PresenceSelectionPoint
+  backward?: boolean
+} | null
+
+/**
+ * Somewhere a participant is, as it arrives over the wire.
+ *
+ * Prefer {@link DocumentPresence} from `getDocumentPresence`, which is scoped to one
+ * document, flattened for rendering, and types `path` accurately.
+ * @public
+ */
 export interface PresenceLocation {
   type: 'document'
+  /**
+   * The specific document the participant is in, so a draft, published, or version
+   * id rather than a bare document id.
+   */
   documentId: string
+  /**
+   * The focused field path, empty when they are in the document but not a field.
+   *
+   * Declared as `string[]`, but segments can also be numbers or `{_key: string}`
+   * objects when the focus is inside an array or a Portable Text field, because
+   * that is what other clients send. Guard for those rather than assuming strings.
+   * Widening the declared type is a breaking change, so it waits for the next major;
+   * {@link DocumentPresence.path} is typed correctly today.
+   */
   path: string[]
+  /**
+   * When the participant said they were last active, on *their* clock.
+   *
+   * Fine for display, unreliable for deciding whether someone is still here: it is
+   * subject to clock skew between machines. Presence already drops participants that
+   * stop announcing, so a session appearing here is one the SDK still considers
+   * live.
+   */
   lastActiveAt: string
+  /** A Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection
 }
 
-/** @public */
+/**
+ * A location as it travels over the wire. Identical in shape to
+ * {@link PresenceLocation}, except `path` is a full `Path`, which is what is
+ * really exchanged. See the note on {@link PresenceLocation.path}.
+ *
+ * Internal: nothing in the public API accepts or returns this. Apps describe
+ * where they are with {@link ReportPresenceOptions} and read presence as
+ * {@link PresenceLocation}.
+ * @internal
+ */
+export interface WirePresenceLocation extends Omit<PresenceLocation, 'path'> {
+  path: Path
+}
+
+/**
+ * Which specific document a presence id resolves to.
+ *
+ * Presence compares exact document ids, so a client in a draft and a client in the
+ * published document are in different places even for the same `documentId`. Pass
+ * the perspective you are editing under and the SDK resolves it; the React hooks
+ * take it from `ResourceProvider` when you do not pass one.
+ * @public
+ */
+export interface PresencePerspectiveOptions extends PerspectiveHandle {
+  /** Live-edit documents have no draft, so presence resolves to the published id. */
+  liveEdit?: boolean
+}
+
+/**
+ * What an app reports about where the current user is.
+ *
+ * Omit `path` for document-level presence, or pass one for field-level presence.
+ * @public
+ */
+export interface ReportPresenceOptions extends PresencePerspectiveOptions {
+  /**
+   * The document the user is in.
+   *
+   * Pass the plain document id; the perspective decides which specific document that
+   * resolves to. An already-specific id is accepted and re-resolved, so passing
+   * `drafts.abc` while the perspective is `published` reports the published document.
+   */
+  documentId: string
+  /**
+   * The focused field path. Supports keyed and numeric segments, so array items
+   * and Portable Text spans can be addressed.
+   */
+  path?: Path
+  /** A Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection
+}
+
+/**
+ * One participant's session and everywhere it currently is.
+ *
+ * Keyed by session, not by user: the same person in two tabs is two entries with
+ * the same `user`.
+ * @public
+ */
 export interface UserPresence {
   user: SanityUser
   locations: PresenceLocation[]
+  /** Identifies one tab. Stable while that tab is open, and not reused. */
+  sessionId: string
+}
+
+/**
+ * One participant at one location within a single document, flattened so it can
+ * be rendered directly against a field.
+ *
+ * Unlike {@link PresenceLocation.path}, `path` here is typed as a full `Path`, so
+ * keyed and numeric segments are described rather than cast away.
+ * @beta
+ */
+export interface DocumentPresence {
+  user: SanityUser
+  /** Identifies one tab, so the same person in two tabs appears twice. */
   sessionId: string
+  /**
+   * The specific document id this participant is in: a draft, published, or
+   * version id, depending on which perspective they are editing.
+   */
+  documentId: string
+  /** The focused field path. Empty when they are in the document but no field. */
+  path: Path
+  /**
+   * When they said they were last active, on *their* clock. Fine for display,
+   * unreliable for liveness. See {@link PresenceLocation.lastActiveAt}.
+   */
+  lastActiveAt: string
+  /** The Portable Text caret, when they are focused in a Portable Text field. */
+  selection?: PresenceSelection
+}
+
+/** @beta */
+export interface DocumentPresenceOptions extends PresencePerspectiveOptions {
+  /**
+   * The document to look at. Resolved through the perspective exactly as
+   * {@link ReportPresenceOptions.documentId} is, so reads match writes.
+   */
+  documentId: string
+  /**
+   * Narrows to participants at or below this field path. Omit it for everyone in
+   * the document.
+   */
+  path?: Path
+  /**
+   * By default a draft, its published version, and any release versions are
+   * treated as the same document, which is what document lists want. Set this to
+   * compare ids exactly, which is what field-level indicators want so that a
+   * draft and a release version do not bleed into each other.
+   */
+  excludeVersions?: boolean
 }
 
 /** @public */
 export type PresenceTransport = [
   incomingEvents$: Observable<TransportEvent>,
   dispatchMessage: (message: TransportMessage) => Observable<void>,
+  /**
+   * Emits an incrementing generation number each time the connection becomes
+   * live. Reconnects with backoff, and subscribing keeps the connection alive.
+   */
+  connections$: Observable<number>,
+  /** Emits when the page is going away, so a disconnect can be announced. */
+  unload$: Observable<void>,
 ]
 
 /** @public */
@@ -54,7 +226,7 @@ export interface DisconnectEvent {
 /** @public */
 export type TransportMessage =
   | {type: 'rollCall'}
-  | {type: 'state'; locations: PresenceLocation[]}
+  | {type: 'state'; locations: WirePresenceLocation[]}
   | {type: 'disconnect'}
 
 /** @public */

package/src/preview/types.ts

@@ -59,28 +59,3 @@ export interface PreviewValue {
     lastEditedDraftAt?: string
   }
 }
-
-/**
- * Represents the current state of a preview value along with a flag indicating whether
- * the preview data is still being fetched or is fully resolved.
- *
- * The tuple contains a preview value or null, and a boolean indicating if the data is
- * pending. A `true` value means a fetch is ongoing; `false` indicates that the
- * currently provided preview value is up-to-date.
- *
- * @public
- */
-export type ValuePending<T> = {
-  data: T | null
-  isPending: boolean
-}
-
-/**
- * @public
- * @deprecated This interface is kept for backwards compatibility but is no longer used internally.
- * Preview state is now stored in the projection store.
- */
-export interface PreviewStoreState {
-  values: {[TDocumentId in string]?: ValuePending<PreviewValue>}
-  subscriptions: {[TDocumentId in string]?: {[TSubscriptionId in string]?: true}}
-}

package/src/projection/projectionStore.test.ts

@@ -6,14 +6,6 @@ import {createStoreInstance} from '../store/createStoreInstance'
 import {projectionStore} from './projectionStore'
 import {subscribeToStateAndFetchBatches} from './subscribeToStateAndFetchBatches'
 
-// Mock the module with a factory function
-vi.mock('../common/createLiveEventSubscriber', () => {
-  const mockLiveSubscriber = vi.fn()
-  return {
-    createLiveEventSubscriber: vi.fn(() => mockLiveSubscriber),
-  }
-})
-
 vi.mock('./subscribeToStateAndFetchBatches')
 
 describe('projectionStore', () => {

package/src/projection/types.ts

@@ -11,14 +11,6 @@ export interface DocumentProjectionValues<TValue extends object = object> {
   [projectionHash: string]: ProjectionValuePending<TValue>
 }
 
-/**
- * @public
- * @deprecated
- * Template literals are a bit too limited, so this type is deprecated.
- * Use `string` instead. Projection strings are validated at runtime.
- */
-export type ValidProjection = string
-
 export interface DocumentProjections {
   [projectionHash: string]: string
 }

package/src/query/queryStore.ts

@@ -80,9 +80,10 @@ export interface ResolveQueryOptions<
 
 const EMPTY_ARRAY: never[] = []
 
-/** @beta */
-export const getQueryKey = (options: QueryOptions): string => JSON.stringify(options)
-/** @beta */
+/** @internal */
+export const getQueryKey = (instance: SanityInstance, options: QueryOptions): string =>
+  JSON.stringify(normalizeOptionsWithPerspective(instance, options))
+/** @internal */
 export const parseQueryKey = (key: string): QueryOptions => JSON.parse(key)
 
 /**
@@ -302,14 +303,14 @@ const _getQueryState = bindActionByResource(
   createStateSourceAction({
     selector: ({state, instance}: SelectorContext<QueryStoreState>, options: QueryOptions) => {
       if (state.error) throw state.error
-      const key = getQueryKey(normalizeOptionsWithPerspective(instance, options))
+      const key = getQueryKey(instance, options)
       const queryState = state.queries[key]
       if (queryState?.error) throw queryState.error
       return queryState?.result
     },
     onSubscribe: ({state, instance}, options: QueryOptions) => {
       const subscriptionId = insecureRandomId()
-      const key = getQueryKey(normalizeOptionsWithPerspective(instance, options))
+      const key = getQueryKey(instance, options)
 
       state.set('addSubscriber', addSubscriber(key, subscriptionId))
 
@@ -362,7 +363,7 @@ const _resolveQuery = bindActionByResource(
   ({state, instance}, {signal, ...options}: ResolveQueryOptions) => {
     const normalized = normalizeOptionsWithPerspective(instance, options)
     const {getCurrent} = getQueryState(instance, normalized)
-    const key = getQueryKey(normalized)
+    const key = getQueryKey(instance, normalized)
 
     // Hold a temporary subscription for the lifetime of this resolution so the
     // key participates in normal cleanup. Without one, a fetch that errors

package/src/store/createActionBinder.test.ts

@@ -2,7 +2,6 @@ import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {type DocumentResource} from '../config/sanityConfig'
 import {
-  bindActionByDataset,
   bindActionByResource,
   bindActionByResourceAndPerspective,
   bindActionGlobally,
@@ -96,34 +95,6 @@ describe('createActionBinder', () => {
   })
 })
 
-describe('bindActionByDataset', () => {
-  it('should work correctly when projectId and dataset are provided', () => {
-    const storeDefinition = {
-      name: 'DSStore',
-      getInitialState: () => ({counter: 0}),
-    }
-    const action = vi.fn((_context, {value}: {value: string}) => value)
-    const boundAction = bindActionByDataset(storeDefinition, action)
-    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
-    const result = boundAction(instance, {value: 'hello'})
-    expect(result).toBe('hello')
-  })
-
-  it('should throw an error if projectId or dataset is missing', () => {
-    const storeDefinition = {
-      name: 'DSStore',
-      getInitialState: () => ({counter: 0}),
-    }
-    const action = vi.fn((_context, _?) => 'fail')
-    const boundAction = bindActionByDataset(storeDefinition, action)
-    // Instance with missing dataset
-    const instance = createSanityInstance({projectId: 'proj1', dataset: ''})
-    expect(() => boundAction(instance)).toThrow(
-      'This API requires a project ID and dataset configured.',
-    )
-  })
-})
-
 describe('bindActionGlobally', () => {
   it('should work correctly ignoring config in key generation', () => {
     const storeDefinition = {
@@ -206,6 +177,57 @@ describe('bindActionByResource', () => {
   })
 })
 
+describe('instance default resource', () => {
+  const storeDefinition = {
+    name: 'DefaultResourceStore',
+    getInitialState: () => ({counter: 0}),
+  }
+  const whichResource = bindActionByResource(storeDefinition, ({key}) => key)
+
+  it('uses config.resource when no resource is passed', () => {
+    const instance = createSanityInstance({resource: {projectId: 'p', dataset: 'd'}})
+    expect(whichResource(instance, {})).toMatchObject({
+      name: 'p.d',
+      resource: {projectId: 'p', dataset: 'd'},
+    })
+    instance.dispose()
+  })
+
+  it('supports a media library as the instance default', () => {
+    const instance = createSanityInstance({resource: {mediaLibraryId: 'ml-123'}})
+    expect(whichResource(instance, {})).toMatchObject({
+      name: 'media-library:ml-123',
+      resource: {mediaLibraryId: 'ml-123'},
+    })
+    instance.dispose()
+  })
+
+  it('supports a canvas as the instance default', () => {
+    const instance = createSanityInstance({resource: {canvasId: 'c-1'}})
+    expect(whichResource(instance, {})).toMatchObject({
+      name: 'canvas:c-1',
+      resource: {canvasId: 'c-1'},
+    })
+    instance.dispose()
+  })
+
+  it('lets a per-call resource override the instance default', () => {
+    const instance = createSanityInstance({resource: {mediaLibraryId: 'ml-123'}})
+    expect(whichResource(instance, {resource: {projectId: 'x', dataset: 'y'}})).toMatchObject({
+      resource: {projectId: 'x', dataset: 'y'},
+    })
+    instance.dispose()
+  })
+
+  it('still accepts the projectId/dataset shorthand', () => {
+    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    expect(whichResource(instance, {})).toMatchObject({
+      resource: {projectId: 'p', dataset: 'd'},
+    })
+    instance.dispose()
+  })
+})
+
 describe('bindActionByResourceAndPerspective', () => {
   it('should throw an error when provided an invalid resource', () => {
     const storeDefinition = {

package/src/store/createActionBinder.ts

@@ -21,12 +21,6 @@ export interface BoundResourceKey {
 export interface BoundPerspectiveKey extends BoundResourceKey {
   perspective: ClientPerspective | ReleasePerspective
 }
-interface BoundDatasetKey {
-  name: string
-  projectId: string
-  dataset: string
-}
-
 /**
  * Defines a store action that operates on a specific state type
  */
@@ -123,70 +117,29 @@ export function createActionBinder<
   }
 }
 
-/**
- * Binds an action to a store that's scoped to a specific project and dataset
- *
- * @remarks
- * This creates actions that operate on state isolated to a specific projectId and dataset.
- * Different project/dataset combinations will have separate states.
- *
- * @throws Error if projectId or dataset is missing from the Sanity instance config
- *
- * @example
- * ```ts
- * // Define a store
- * const documentStore = defineStore<DocumentState>({
- *   name: 'Document',
- *   getInitialState: () => ({ documents: {} }),
- *   // ...
- * })
- *
- * // Create dataset-specific actions
- * export const fetchDocument = bindActionByDataset(
- *   documentStore,
- *   ({instance, state}, documentId) => {
- *     // This state is isolated to the specific project/dataset
- *     // ...fetch logic...
- *   }
- * )
- *
- * // Usage
- * fetchDocument(sanityInstance, 'doc123')
- * ```
- */
-export const bindActionByDataset = createActionBinder<
-  BoundDatasetKey,
-  [(object & {projectId?: string; dataset?: string})?, ...unknown[]]
->((instance, options) => {
-  const projectId = options?.projectId ?? instance.config.projectId
-  const dataset = options?.dataset ?? instance.config.dataset
-  if (!projectId || !dataset) {
-    throw new Error('This API requires a project ID and dataset configured.')
-  }
-  return {name: `${projectId}.${dataset}`, projectId, dataset}
-})
-
 const createResourceKey = (
   instance: SanityInstance,
   resource?: DocumentResource,
 ): BoundResourceKey => {
   let name: string | undefined
   let resourceForKey: DocumentResource | undefined
-  if (resource) {
-    resourceForKey = resource
-    if (isDatasetResource(resource)) {
-      name = `${resource.projectId}.${resource.dataset}`
-    } else if (isMediaLibraryResource(resource)) {
-      name = `media-library:${resource.mediaLibraryId}`
-    } else if (isCanvasResource(resource)) {
-      name = `canvas:${resource.canvasId}`
+  // A per-call resource wins; otherwise use the instance's default resource.
+  const effectiveResource = resource ?? instance.config.resource
+  if (effectiveResource) {
+    resourceForKey = effectiveResource
+    if (isDatasetResource(effectiveResource)) {
+      name = `${effectiveResource.projectId}.${effectiveResource.dataset}`
+    } else if (isMediaLibraryResource(effectiveResource)) {
+      name = `media-library:${effectiveResource.mediaLibraryId}`
+    } else if (isCanvasResource(effectiveResource)) {
+      name = `canvas:${effectiveResource.canvasId}`
     } else {
-      throw new Error(`Received invalid resource: ${JSON.stringify(resource)}`)
+      throw new Error(`Received invalid resource: ${JSON.stringify(effectiveResource)}`)
     }
     return {name, resource: resourceForKey}
   }
 
-  // TODO: remove reference to instance.config when we get to v3
+  // `projectId`/`dataset` on the config are shorthand for a dataset resource.
   const {projectId, dataset} = instance.config
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
@@ -199,8 +152,8 @@ const createResourceKey = (
  **/
 export const bindActionByResource = createActionBinder<
   BoundResourceKey,
-  // this implies resources is optional to keep backwards compatibility
-  // but in reality, we'll always pass a resource (since we'll defer to the instance until v3)
+  // `resource` is optional because it falls back to the instance config in
+  // `createResourceKey` — see the note there on why that fallback still exists.
   [{resource?: DocumentResource}, ...unknown[]]
 >((instance, {resource}) => {
   return createResourceKey(instance, resource)
@@ -245,7 +198,8 @@ export const bindActionByResourceAndPerspective = createActionBinder<
   [DatasetHandle, ...unknown[]]
 >((instance, options): BoundPerspectiveKey => {
   const {resource, perspective} = options
-  // TODO: remove reference to instance.config.perspective when we get to v3
+  // Same trade-off as the resource fallback in `createResourceKey`: configured once on the
+  // instance rather than passed to every call. Kept for the same reason.
   const utilizedPerspective = perspective ?? instance.config.perspective ?? 'drafts'
   let perspectiveKey: string
   if (isReleasePerspective(utilizedPerspective)) {

package/src/store/createSanityInstance.test.ts

@@ -29,60 +29,6 @@ describe('createSanityInstance', () => {
     expect(callback).toHaveBeenCalledTimes(1)
   })
 
-  it('should create a child instance with merged config and correct parent', () => {
-    const parent = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
-    const child = parent.createChild({dataset: 'ds2'})
-    expect(child.config).toEqual({projectId: 'proj1', dataset: 'ds2'})
-    expect(child.getParent()).toBe(parent)
-  })
-
-  it('should match an instance in the hierarchy using match', () => {
-    // three-level hierarchy
-    const grandparent = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
-    const parent = grandparent.createChild({projectId: 'proj2'})
-    const child = parent.createChild({dataset: 'ds2'})
-
-    expect(child.config).toEqual({projectId: 'proj2', dataset: 'ds2'})
-    expect(parent.config).toEqual({projectId: 'proj2', dataset: 'ds1'})
-
-    expect(child.match({dataset: 'ds2'})).toBe(child)
-    expect(child.match({projectId: 'proj2'})).toBe(child)
-    expect(child.match({projectId: 'proj1'})).toBe(grandparent)
-    expect(parent.match({projectId: 'proj1'})).toBe(grandparent)
-    expect(grandparent.match({projectId: 'proj1'})).toBe(grandparent)
-  })
-
-  it('should match `undefined` when the desired resource ID should not be set on an instance', () => {
-    const noProjectOrDataset = createSanityInstance()
-    const noDataset = noProjectOrDataset.createChild({projectId: 'proj1'})
-    const leaf = noDataset.createChild({dataset: 'ds1'})
-
-    // no keys means anything (in this case, self) will match
-    expect(leaf.match({})).toBe(leaf)
-
-    // `[resourceId]: undefined` means match an instance with no dataset set
-    expect(leaf.match({dataset: undefined})).toBe(noDataset)
-    expect(noDataset.match({dataset: undefined})).toBe(noDataset)
-    expect(leaf.match({projectId: undefined})).toBe(noProjectOrDataset)
-    expect(noDataset.match({projectId: undefined})).toBe(noProjectOrDataset)
-    expect(noProjectOrDataset.match({projectId: undefined})).toBe(noProjectOrDataset)
-  })
-
-  it('should return undefined when no match is found', () => {
-    const instance = createSanityInstance({projectId: 'proj1', dataset: 'ds1'})
-    expect(instance.match({dataset: 'non-existent'})).toBeUndefined()
-  })
-
-  it('should inherit and merge auth config', () => {
-    const parent = createSanityInstance({
-      projectId: 'proj1',
-      dataset: 'ds1',
-      auth: {apiHost: 'api.sanity.work'},
-    })
-    const child = parent.createChild({auth: {token: 'my-token'}})
-    expect(child.config.auth).toEqual({apiHost: 'api.sanity.work', token: 'my-token'})
-  })
-
   describe('logging', () => {
     const mockHandler: LogHandler = {
       error: vi.fn(),
@@ -141,20 +87,6 @@ describe('createSanityInstance', () => {
       )
     })
 
-    it('should log child instance creation at debug level', () => {
-      const parent = createSanityInstance({projectId: 'parent-proj'})
-      vi.clearAllMocks() // Clear parent creation logs
-
-      parent.createChild({dataset: 'child-ds'})
-
-      expect(mockHandler.debug).toHaveBeenCalledWith(
-        expect.stringContaining('Creating child instance'),
-        expect.objectContaining({
-          overridingDataset: true,
-        }),
-      )
-    })
-
     it('should include instance context in logs', () => {
       createSanityInstance({projectId: 'my-project', dataset: 'my-dataset'})