@sanity/sdk 2.9.0 → 2.11.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,12 +1,10 @@
-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
- * @remarks Instances form a hierarchy through parent/child relationships
  *
  * @public
  */
@@ -19,7 +17,6 @@ export interface SanityInstance {
 
   /**
    * Resolved configuration for this instance
-   * @remarks Merges values from parent instances where appropriate
    */
   readonly config: SanityConfig
 
@@ -45,13 +42,14 @@ export interface SanityInstance {
   /**
    * Gets the parent instance in the hierarchy
    * @returns Parent instance or undefined if this is the root
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
    */
   getParent(): SanityInstance | undefined
 
   /**
    * Creates a child instance with merged configuration
    * @param config - Configuration to merge with parent values
-   * @remarks Child instances inherit parent configuration but can override values
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
    */
   createChild(config: SanityConfig): SanityInstance
 
@@ -60,6 +58,7 @@ export interface SanityInstance {
    * matches the given target config using a shallow comparison.
    * @param targetConfig - A partial configuration object containing key-value pairs to match.
    * @returns The first matching instance or undefined if no match is found.
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
    */
   match(targetConfig: Partial<SanityConfig>): SanityInstance | undefined
 }
@@ -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/telemetry/devMode.test.ts

@@ -30,6 +30,14 @@ describe('isDevMode', () => {
     expect(isDevMode()).toBe(true)
   })
 
+  it('returns true on localhost even when NODE_ENV is production', () => {
+    vi.stubEnv('NODE_ENV', 'production')
+    vi.stubGlobal('window', {
+      location: {href: 'http://localhost:3000/'},
+    })
+    expect(isDevMode()).toBe(true)
+  })
+
   it('returns false for a non-local URL', () => {
     vi.stubEnv('NODE_ENV', 'test')
     vi.stubGlobal('window', {

package/src/telemetry/devMode.ts

@@ -17,21 +17,22 @@ function isLocalUrl(win: Window): boolean {
 }
 
 /**
- * Determines whether the SDK should enable dev-mode telemetry.
+ * Determines whether the SDK should enable dev-mode telemetry for the
+ * SDK consumer (i.e. a developer building an app with `@sanity/sdk`).
  *
- * 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.
+ * Browser: returns true only when the URL is `localhost` or `127.0.0.1`.
+ * The URL check is the primary signal because consumer bundlers may or
+ * may not forward `NODE_ENV` to the browser reliably.
+ *
+ * Node (scripts / non-browser): falls back to `NODE_ENV === 'development'`.
+ *
+ * Bracket-notation `process.env['NODE_ENV']` is used to avoid bundler
+ * dead-code replacement.
  *
  * @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)
   }

package/src/telemetry/initTelemetry.test.ts

@@ -205,21 +205,4 @@ describe('initTelemetry', () => {
 
     instance.dispose()
   })
-
-  it('finds manager through parent-child instance chain', async () => {
-    vi.mocked(isDevMode).mockReturnValue(true)
-
-    const root = createSanityInstance()
-    const child = root.createChild({})
-
-    initTelemetry(root, 'abc123')
-    await flushPromises()
-
-    trackHookMounted(child, 'useUsers')
-
-    const manager = vi.mocked(createTelemetryManager).mock.results[0].value
-    expect(manager.logHookFirstUsed).toHaveBeenCalledWith('useUsers')
-
-    root.dispose()
-  })
 })

package/src/telemetry/initTelemetry.ts

@@ -187,19 +187,9 @@ export function trackHookMounted(instance: SanityInstance, hookName: string): vo
 }
 
 function findManager(instance: SanityInstance): TelemetryManager | undefined {
-  let current: SanityInstance | undefined = instance
-  while (current) {
-    const manager = telemetryManagers.get(current)
-    if (manager) return manager
-    current = typeof current.getParent === 'function' ? current.getParent() : undefined
-  }
-  return undefined
+  return telemetryManagers.get(instance)
 }
 
 function getRootInstance(instance: SanityInstance): SanityInstance {
-  let current = instance
-  while (typeof current.getParent === 'function' && current.getParent()) {
-    current = current.getParent()!
-  }
-  return current
+  return instance
 }

package/src/users/reducers.ts

@@ -1,6 +1,5 @@
-import {omit} from 'lodash-es'
-
 import {type SanityInstance} from '../store/createSanityInstance'
+import {omitProperty} from '../utils/object'
 import {type GetUsersOptions, type SanityUserResponse, type UsersStoreState} from './types'
 import {DEFAULT_USERS_BATCH_SIZE} from './usersConstants'
 
@@ -48,7 +47,7 @@ export const removeSubscription =
     const group = prev.users[key]
     if (!group) return prev
     const subscriptions = group.subscriptions.filter((id) => id !== subscriptionId)
-    if (!subscriptions.length) return {...prev, users: omit(prev.users, key)}
+    if (!subscriptions.length) return {...prev, users: omitProperty(prev.users, key)}
     return {...prev, users: {...prev.users, [key]: {...group, subscriptions}}}
   }
 
@@ -83,7 +82,7 @@ export const cancelRequest =
     const group = prev.users[key]
     if (!group) return prev
     if (group.subscriptions.length) return prev
-    return {...prev, users: omit(prev.users, key)}
+    return {...prev, users: omitProperty(prev.users, key)}
   }
 
 export const initializeRequest =

package/src/utils/createFetcherStore.ts

@@ -1,4 +1,3 @@
-import {omit} from 'lodash-es'
 import {asapScheduler, EMPTY, firstValueFrom, from, Observable} from 'rxjs'
 import {
   catchError,
@@ -23,6 +22,7 @@ import {
 } from '../store/createStateSourceAction'
 import {defineStore, type StoreContext} from '../store/defineStore'
 import {insecureRandomId} from '../utils/ids'
+import {omitProperty} from '../utils/object'
 import {setCleanupTimeout} from './setCleanupTimeout'
 
 interface CreateFetcherStoreOptions<TParams extends unknown[], TData> {
@@ -183,8 +183,10 @@ export function createFetcherStore<TParams extends unknown[], TData>({
                     stateByParams: {
                       ...prev.stateByParams,
                       [entry.key]: {
-                        ...omit(entry, 'error'),
-                        ...omit(prev.stateByParams[entry.key], 'error'),
+                        ...omitProperty(entry, 'error'),
+                        ...(prev.stateByParams[entry.key]
+                          ? omitProperty(prev.stateByParams[entry.key], 'error')
+                          : {}),
                         data,
                       },
                     },
@@ -255,7 +257,7 @@ export function createFetcherStore<TParams extends unknown[], TData>({
 
               const newSubs = (entry.subscriptions || []).filter((id) => id !== subscriptionId)
               if (newSubs.length === 0) {
-                return {stateByParams: omit(prev.stateByParams, key)}
+                return {stateByParams: omitProperty(prev.stateByParams, key)}
               }
 
               return {

package/src/utils/isImportError.test.ts

@@ -0,0 +1,72 @@
+import {describe, expect, test} from 'vitest'
+
+import {isImportError} from './isImportError'
+
+describe('isImportError', () => {
+  test('returns false for non-Error values', () => {
+    expect(isImportError(null)).toBe(false)
+    expect(isImportError(undefined)).toBe(false)
+    expect(isImportError('Loading chunk 5 failed.')).toBe(false)
+    expect(isImportError({message: 'Loading chunk 5 failed.'})).toBe(false)
+    expect(isImportError(42)).toBe(false)
+  })
+
+  test('returns false for unrelated Error instances', () => {
+    expect(isImportError(new Error('Something else went wrong'))).toBe(false)
+    expect(isImportError(new TypeError('Cannot read properties of undefined'))).toBe(false)
+  })
+
+  test('detects webpack ChunkLoadError by name', () => {
+    const err = new Error('arbitrary message')
+    err.name = 'ChunkLoadError'
+    expect(isImportError(err)).toBe(true)
+  })
+
+  test('detects webpack numeric chunk failure messages', () => {
+    expect(isImportError(new Error('Loading chunk 5 failed.'))).toBe(true)
+    expect(
+      isImportError(new Error('Loading chunk 42 failed. (missing: https://x.com/42.abc.js)')),
+    ).toBe(true)
+  })
+
+  test('detects webpack named chunk failure messages', () => {
+    expect(isImportError(new Error('Loading chunk vendors-foo failed.'))).toBe(true)
+    expect(isImportError(new Error('Loading chunk react_vendors failed.'))).toBe(true)
+  })
+
+  test('detects Vite "Failed to fetch dynamically imported module"', () => {
+    expect(
+      isImportError(
+        new TypeError(
+          'Failed to fetch dynamically imported module: https://example.com/assets/Home-abc123.js',
+        ),
+      ),
+    ).toBe(true)
+  })
+
+  test('detects Firefox "error loading dynamically imported module"', () => {
+    expect(
+      isImportError(
+        new TypeError(
+          'error loading dynamically imported module: http://localhost:8080/src/views/Dashboard/index.vue',
+        ),
+      ),
+    ).toBe(true)
+  })
+
+  test('detects Safari module-script failures with and without the "ing" suffix', () => {
+    expect(isImportError(new TypeError('Importing a module script failed.'))).toBe(true)
+    expect(isImportError(new TypeError('Import a module script failed.'))).toBe(true)
+  })
+
+  test('detects Vite CSS preload failures', () => {
+    expect(isImportError(new Error('Unable to preload CSS for /assets/App-BBLnt7oG.css'))).toBe(
+      true,
+    )
+  })
+
+  test('matches case-insensitively', () => {
+    expect(isImportError(new Error('loading chunk 1 FAILED'))).toBe(true)
+    expect(isImportError(new Error('FAILED TO FETCH DYNAMICALLY IMPORTED MODULE'))).toBe(true)
+  })
+})

package/src/utils/isImportError.ts

@@ -0,0 +1,34 @@
+/**
+ * Returns true when the given error looks like a dynamic-import or
+ * code-split chunk-loading failure.
+ *
+ * These errors typically surface when a user has a tab open against a
+ * previously-deployed version of an app and the JavaScript or CSS chunk
+ * filenames have since changed: a fresh deployment removes the hashed assets
+ * the open tab still references. Detecting them lets the SDK trigger an
+ * automatic reload so the user gets the new build without manual intervention.
+ *
+ * Recognized shapes (webpack ChunkLoadError, Vite "Failed to fetch
+ * dynamically imported module", Firefox "error loading dynamically imported
+ * module", Safari "Importing a module script failed", and Vite "Unable to
+ * preload CSS").
+ *
+ * @param error - The value to inspect. Anything that is not an Error
+ *   instance returns false.
+ * @returns True if the error matches a known import/chunk-load failure.
+ *
+ * @public
+ */
+export function isImportError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  if (error.name === 'ChunkLoadError') return true
+
+  const message = error.message || ''
+  return (
+    /Loading chunk [\w-]+ failed/i.test(message) ||
+    /Failed to fetch dynamically imported module/i.test(message) ||
+    /error loading dynamically imported module/i.test(message) ||
+    /Import(?:ing)? a module script failed/i.test(message) ||
+    /Unable to preload CSS/i.test(message)
+  )
+}

package/src/utils/object.test.ts

@@ -0,0 +1,95 @@
+import {describe, expect, it} from 'vitest'
+
+import {isDeepEqual, isObject, omitProperty, pickProperties} from './object'
+
+describe('object utils', () => {
+  describe('isObject', () => {
+    it('returns true for objects and false for primitives', () => {
+      expect(isObject({foo: 'bar'})).toBe(true)
+      expect(isObject(null)).toBe(false)
+      expect(isObject('hello')).toBe(false)
+    })
+  })
+
+  describe('omitProperty', () => {
+    it('removes a property from an object copy', () => {
+      expect(omitProperty({foo: 'bar', baz: 1}, 'foo')).toEqual({baz: 1})
+    })
+
+    it('returns an empty object for undefined input', () => {
+      expect(omitProperty<{foo: string}, 'foo'>(undefined, 'foo')).toEqual({})
+    })
+  })
+
+  describe('pickProperties', () => {
+    it('copies only the requested own properties', () => {
+      expect(pickProperties({foo: 'bar', baz: 1}, ['foo'])).toEqual({foo: 'bar'})
+    })
+  })
+
+  describe('isDeepEqual', () => {
+    it('matches nested plain objects and arrays', () => {
+      expect(
+        isDeepEqual({foo: [{bar: 'baz'}], qux: {count: 2}}, {foo: [{bar: 'baz'}], qux: {count: 2}}),
+      ).toBe(true)
+    })
+
+    it('returns false for unequal nested plain objects and arrays', () => {
+      expect(
+        isDeepEqual(
+          {foo: [{bar: 'baz'}], qux: {count: 2}},
+          {foo: [{bar: 'nope'}], qux: {count: 2}},
+        ),
+      ).toBe(false)
+      expect(isDeepEqual([1, {foo: 'bar'}], [1, {foo: 'baz'}])).toBe(false)
+    })
+
+    it('matches sets and maps with equal contents', () => {
+      expect(isDeepEqual(new Set([{foo: 'bar'}, 'baz']), new Set(['baz', {foo: 'bar'}]))).toBe(true)
+
+      expect(
+        isDeepEqual(
+          new Map<string, unknown>([
+            ['foo', {bar: 'baz'}],
+            ['count', 2],
+          ]),
+          new Map<string, unknown>([
+            ['foo', {bar: 'baz'}],
+            ['count', 2],
+          ]),
+        ),
+      ).toBe(true)
+    })
+
+    it('compares dates by timestamp', () => {
+      expect(isDeepEqual(new Date('2024-01-01'), new Date('2024-01-01'))).toBe(true)
+      expect(isDeepEqual(new Date('2024-01-01'), new Date('2024-01-02'))).toBe(false)
+    })
+
+    it('compares regular expressions by source and flags', () => {
+      expect(isDeepEqual(/foo/gi, /foo/gi)).toBe(true)
+      expect(isDeepEqual(/foo/g, /foo/i)).toBe(false)
+      expect(isDeepEqual(/foo/g, /bar/g)).toBe(false)
+    })
+
+    it('returns false for cross-shape mismatches', () => {
+      expect(isDeepEqual({foo: 'bar'}, ['foo', 'bar'] as unknown as {foo: string})).toBe(false)
+      expect(
+        isDeepEqual(
+          new Map<string, unknown>([['foo', 'bar']]) as unknown as object,
+          new Set(['foo', 'bar']) as unknown as object,
+        ),
+      ).toBe(false)
+    })
+
+    it('treats non-plain objects as unequal unless they are the same reference', () => {
+      class Example {
+        constructor(public value: string) {}
+      }
+
+      expect(isDeepEqual(new Example('a'), new Example('a'))).toBe(false)
+      const instance = new Example('a')
+      expect(isDeepEqual(instance, instance)).toBe(true)
+    })
+  })
+})