@sanity/sdk 2.8.0 → 2.10.0

package/src/store/createActionBinder.ts

@@ -2,10 +2,10 @@ import {type ClientPerspective} from '@sanity/client'
 
 import {
   type DatasetHandle,
-  type DocumentSource,
-  isCanvasSource,
-  isDatasetSource,
-  isMediaLibrarySource,
+  type DocumentResource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
   type ReleasePerspective,
 } from '../config/sanityConfig'
 import {isReleasePerspective} from '../releases/utils/isReleasePerspective'
@@ -14,14 +14,14 @@ import {createStoreInstance, type StoreInstance} from './createStoreInstance'
 import {type StoreState} from './createStoreState'
 import {type StoreContext, type StoreDefinition} from './defineStore'
 
-export interface BoundSourceKey {
+export interface BoundResourceKey {
   name: string
-  source: DocumentSource
+  resource: DocumentResource
 }
-export interface BoundPerspectiveKey extends BoundSourceKey {
+export interface BoundPerspectiveKey extends BoundResourceKey {
   perspective: ClientPerspective | ReleasePerspective
 }
-export interface BoundDatasetKey {
+interface BoundDatasetKey {
   name: string
   projectId: string
   dataset: string
@@ -166,21 +166,24 @@ export const bindActionByDataset = createActionBinder<
   return {name: `${projectId}.${dataset}`, projectId, dataset}
 })
 
-const createSourceKey = (instance: SanityInstance, source?: DocumentSource): BoundSourceKey => {
+const createResourceKey = (
+  instance: SanityInstance,
+  resource?: DocumentResource,
+): BoundResourceKey => {
   let name: string | undefined
-  let sourceForKey: DocumentSource | undefined
-  if (source) {
-    sourceForKey = source
-    if (isDatasetSource(source)) {
-      name = `${source.projectId}.${source.dataset}`
-    } else if (isMediaLibrarySource(source)) {
-      name = `media-library:${source.mediaLibraryId}`
-    } else if (isCanvasSource(source)) {
-      name = `canvas:${source.canvasId}`
+  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}`
     } else {
-      throw new Error(`Received invalid source: ${JSON.stringify(source)}`)
+      throw new Error(`Received invalid resource: ${JSON.stringify(resource)}`)
     }
-    return {name, source: sourceForKey}
+    return {name, resource: resourceForKey}
   }
 
   // TODO: remove reference to instance.config when we get to v3
@@ -188,30 +191,32 @@ const createSourceKey = (instance: SanityInstance, source?: DocumentSource): Bou
   if (!projectId || !dataset) {
     throw new Error('This API requires a project ID and dataset configured.')
   }
-  return {name: `${projectId}.${dataset}`, source: {projectId, dataset}}
+  return {name: `${projectId}.${dataset}`, resource: {projectId, dataset}}
 }
 
 /**
- * Binds an action to a store that's scoped to a specific document source.
+ * Binds an action to a store that's scoped to a specific document resource.
  **/
-export const bindActionBySource = createActionBinder<
-  BoundSourceKey,
-  [{source?: DocumentSource}, ...unknown[]]
->((instance, {source}) => {
-  return createSourceKey(instance, source)
+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?: DocumentResource}, ...unknown[]]
+>((instance, {resource}) => {
+  return createResourceKey(instance, resource)
 })
 
 /**
- * Binds an action to a store that's scoped to a specific document source and perspective.
+ * Binds an action to a store that's scoped to a specific document resource and perspective.
  *
  * @remarks
- * This creates actions that operate on state isolated to a specific document source and perspective.
- * Different document sources and perspectives will have separate states.
+ * This creates actions that operate on state isolated to a specific document resource and perspective.
+ * Different document resources and perspectives will have separate states.
  *
  * This is mostly useful for stores that do batch fetching operations, since the query store
  * can isolate single queries by perspective.
  *
- * @throws Error if source or perspective is missing from the Sanity instance config
+ * @throws Error if resource or perspective is missing from the Sanity instance config
  *
  * @example
  * ```ts
@@ -222,11 +227,11 @@ export const bindActionBySource = createActionBinder<
  *   // ...
  * })
  *
- * // Create source-and-perspective-specific actions
- * export const fetchDocuments = bindActionBySourceAndPerspective(
+ * // Create resource-and-perspective-specific actions
+ * export const fetchDocuments = bindActionByResourceAndPerspective(
  *   documentStore,
  *   ({instance, state}, documentId) => {
- *     // This state is isolated to the specific document source and perspective
+ *     // This state is isolated to the specific document resource and perspective
  *     // ...fetch logic...
  *   }
  * )
@@ -235,11 +240,11 @@ export const bindActionBySource = createActionBinder<
  * fetchDocument(sanityInstance, 'doc123')
  * ```
  */
-export const bindActionBySourceAndPerspective = createActionBinder<
+export const bindActionByResourceAndPerspective = createActionBinder<
   BoundPerspectiveKey,
   [DatasetHandle, ...unknown[]]
 >((instance, options): BoundPerspectiveKey => {
-  const {source, perspective} = options
+  const {resource, perspective} = options
   // TODO: remove reference to instance.config.perspective when we get to v3
   const utilizedPerspective = perspective ?? instance.config.perspective ?? 'drafts'
   let perspectiveKey: string
@@ -251,11 +256,11 @@ export const bindActionBySourceAndPerspective = createActionBinder<
     // "StackablePerspective", shouldn't be a common case, but just in case
     perspectiveKey = JSON.stringify(utilizedPerspective)
   }
-  const sourceKey = createSourceKey(instance, source)
+  const sourceKey = createResourceKey(instance, resource)
 
   return {
     name: `${sourceKey.name}:${perspectiveKey}`,
-    source: sourceKey.source,
+    resource: sourceKey.resource,
     perspective: utilizedPerspective,
   }
 })

package/src/store/createSanityInstance.ts

@@ -1,8 +1,7 @@
-import {pick} from 'lodash-es'
-
 import {type SanityConfig} from '../config/sanityConfig'
 import {insecureRandomId} from '../utils/ids'
 import {createLogger, type InstanceContext} from '../utils/logger'
+import {pickProperties} from '../utils/object'
 
 /**
  * Represents a Sanity.io resource instance with its own configuration and lifecycle
@@ -158,7 +157,7 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
     },
     match: (targetConfig) => {
       if (
-        Object.entries(pick(targetConfig, 'auth', 'projectId', 'dataset')).every(
+        Object.entries(pickProperties(targetConfig, ['auth', 'projectId', 'dataset'])).every(
           ([key, value]) => config[key as keyof SanityConfig] === value,
         )
       ) {

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'
@@ -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'
@@ -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/telemetry/__telemetry__/sdk.telemetry.ts

@@ -0,0 +1,42 @@
+import {defineEvent} from '@sanity/telemetry'
+
+/** @internal */
+export const SDKDevSessionStarted = defineEvent<{
+  version: string
+  projectId: string
+  perspective: string
+  authMethod: string
+}>({
+  name: 'SDK Dev Session Started',
+  version: 1,
+  description: 'SDK instance created in development mode',
+})
+
+/** @internal */
+export const SDKHookMounted = defineEvent<{
+  hookName: string
+}>({
+  name: 'SDK Hook Mounted',
+  version: 1,
+  description: 'An SDK hook was mounted for the first time in this session',
+})
+
+/** @internal */
+export const SDKDevSessionEnded = defineEvent<{
+  durationSeconds: number
+  hooksUsed: string[]
+}>({
+  name: 'SDK Dev Session Ended',
+  version: 1,
+  description: 'SDK instance disposed in development mode',
+})
+
+/** @internal */
+export const SDKDevError = defineEvent<{
+  errorType: string
+  hookName: string
+}>({
+  name: 'SDK Dev Error',
+  version: 1,
+  description: 'Runtime error caught during SDK development',
+})

package/src/telemetry/devMode.test.ts

@@ -0,0 +1,52 @@
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+import {isDevMode} from './devMode'
+
+describe('isDevMode', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  it('returns false when NODE_ENV is production', () => {
+    vi.stubEnv('NODE_ENV', 'production')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(false)
+  })
+
+  it('returns true when running on localhost', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', {
+      location: {href: 'http://localhost:3000/'},
+    })
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns true when running on 127.0.0.1', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', {
+      location: {href: 'http://127.0.0.1:3000/'},
+    })
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns false for a non-local URL', () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    vi.stubGlobal('window', {
+      location: {href: 'https://myapp.sanity.studio/'},
+    })
+    expect(isDevMode()).toBe(false)
+  })
+
+  it('returns true when NODE_ENV is development and no window', () => {
+    vi.stubEnv('NODE_ENV', 'development')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(true)
+  })
+
+  it('returns false when NODE_ENV is test and no window', () => {
+    vi.stubEnv('NODE_ENV', 'test')
+    vi.stubGlobal('window', undefined)
+    expect(isDevMode()).toBe(false)
+  })
+})

package/src/telemetry/devMode.ts

@@ -0,0 +1,40 @@
+/**
+ * Checks whether the current URL points to a local development server.
+ *
+ * @param win - The window object to check
+ * @returns True if running on localhost or 127.0.0.1
+ * @internal
+ */
+function isLocalUrl(win: Window): boolean {
+  const url = win.location?.href
+  if (!url) return false
+  return (
+    url.startsWith('http://localhost') ||
+    url.startsWith('https://localhost') ||
+    url.startsWith('http://127.0.0.1') ||
+    url.startsWith('https://127.0.0.1')
+  )
+}
+
+/**
+ * Determines whether the SDK should enable dev-mode telemetry.
+ *
+ * Combines a browser URL check (localhost/127.0.0.1) with a Node.js
+ * environment variable check (`NODE_ENV === 'development'`). Returns
+ * false in production environments so bundlers can tree-shake the
+ * telemetry code path entirely.
+ *
+ * @returns True if the SDK is running in a development environment
+ * @internal
+ */
+export function isDevMode(): boolean {
+  if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production') {
+    return false
+  }
+
+  if (typeof window !== 'undefined') {
+    return isLocalUrl(window)
+  }
+
+  return typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development'
+}