@sanity/sdk 2.5.0 → 2.7.0

package/src/store/createSanityInstance.test.ts

@@ -1,5 +1,6 @@
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
+import {configureLogging, type LogHandler, resetLogging} from '../utils/logger'
 import {createSanityInstance} from './createSanityInstance'
 
 describe('createSanityInstance', () => {
@@ -81,4 +82,87 @@ describe('createSanityInstance', () => {
     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(),
+      warn: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+      trace: vi.fn(),
+    }
+
+    beforeEach(() => {
+      vi.clearAllMocks()
+      configureLogging({
+        level: 'debug',
+        namespaces: ['sdk'],
+        handler: mockHandler,
+      })
+    })
+
+    afterEach(() => {
+      resetLogging()
+    })
+
+    it('should log instance creation at info level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('[INFO] [sdk]'),
+        expect.objectContaining({
+          hasProjectId: true,
+          hasDataset: true,
+        }),
+      )
+    })
+
+    it('should log configuration details at debug level', () => {
+      createSanityInstance({projectId: 'test-proj', dataset: 'test-ds'})
+
+      expect(mockHandler.debug).toHaveBeenCalledWith(
+        expect.stringContaining('[DEBUG] [sdk]'),
+        expect.objectContaining({
+          projectId: 'test-proj',
+          dataset: 'test-ds',
+        }),
+      )
+    })
+
+    it('should log instance disposal', () => {
+      const instance = createSanityInstance({projectId: 'test-proj'})
+      vi.clearAllMocks() // Clear creation logs
+
+      instance.dispose()
+
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringContaining('Instance disposed'),
+        expect.anything(),
+      )
+    })
+
+    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'})
+
+      // Check that logs include the instance context (project and dataset)
+      expect(mockHandler.info).toHaveBeenCalledWith(
+        expect.stringMatching(/\[project:my-project\].*\[dataset:my-dataset\]/),
+        expect.anything(),
+      )
+    })
+  })
 })

package/src/store/createSanityInstance.ts

@@ -2,6 +2,7 @@ import {pick} from 'lodash-es'
 
 import {type SanityConfig} from '../config/sanityConfig'
 import {insecureRandomId} from '../utils/ids'
+import {createLogger, type InstanceContext} from '../utils/logger'
 
 /**
  * Represents a Sanity.io resource instance with its own configuration and lifecycle
@@ -76,15 +77,53 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
   const disposeListeners = new Map<string, () => void>()
   const disposed = {current: false}
 
+  // Create instance context for logging
+  const instanceContext: InstanceContext = {
+    instanceId,
+    projectId: config.projectId,
+    dataset: config.dataset,
+  }
+
+  // Create logger with instance context
+  const logger = createLogger('sdk', {instanceContext})
+
+  // Log instance creation
+  logger.info('Sanity instance created', {
+    hasProjectId: !!config.projectId,
+    hasDataset: !!config.dataset,
+    hasAuth: !!config.auth,
+    hasPerspective: !!config.perspective,
+  })
+
+  // Log configuration details at debug level
+  logger.debug('Instance configuration', {
+    projectId: config.projectId,
+    dataset: config.dataset,
+    perspective: config.perspective,
+    hasStudioConfig: !!config.studio,
+    hasStudioTokenSource: !!config.studio?.auth?.token,
+    legacyStudioMode: config.studioMode?.enabled,
+    hasAuthProviders: !!config.auth?.providers,
+    hasAuthToken: !!config.auth?.token,
+  })
+
   const instance: SanityInstance = {
     instanceId,
     config,
     isDisposed: () => disposed.current,
     dispose: () => {
-      if (disposed.current) return
+      if (disposed.current) {
+        logger.trace('Dispose called on already disposed instance', {internal: true})
+        return
+      }
+      logger.trace('Disposing instance', {
+        internal: true,
+        listenerCount: disposeListeners.size,
+      })
       disposed.current = true
       disposeListeners.forEach((listener) => listener())
       disposeListeners.clear()
+      logger.info('Instance disposed')
     },
     onDispose: (cb) => {
       const listenerId = insecureRandomId()
@@ -94,8 +133,14 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
       }
     },
     getParent: () => undefined,
-    createChild: (next) =>
-      Object.assign(
+    createChild: (next) => {
+      logger.debug('Creating child instance', {
+        parentInstanceId: instanceId.slice(0, 8),
+        overridingProjectId: !!next.projectId,
+        overridingDataset: !!next.dataset,
+        overridingAuth: !!next.auth,
+      })
+      const child = Object.assign(
         createSanityInstance({
           ...config,
           ...next,
@@ -104,7 +149,13 @@ export function createSanityInstance(config: SanityConfig = {}): SanityInstance
             : config.auth && next.auth && {auth: {...config.auth, ...next.auth}}),
         }),
         {getParent: () => instance},
-      ),
+      )
+      logger.trace('Child instance created', {
+        internal: true,
+        childInstanceId: child.instanceId.slice(0, 8),
+      })
+      return child
+    },
     match: (targetConfig) => {
       if (
         Object.entries(pick(targetConfig, 'auth', 'projectId', 'dataset')).every(

package/src/utils/logger-usage-example.md

@@ -0,0 +1,141 @@
+# Logger Usage Examples
+
+This document shows how to use the logging infrastructure in different scenarios.
+
+## For SDK Users
+
+### Basic Setup
+
+```typescript
+import {configureLogging, createSanityInstance} from '@sanity/sdk'
+
+// Enable logging in development
+if (process.env.NODE_ENV === 'development') {
+  configureLogging({
+    level: 'info',
+    namespaces: ['auth', 'document', 'query'],
+  })
+}
+
+const instance = createSanityInstance({
+  projectId: 'my-project',
+  dataset: 'production',
+})
+```
+
+### Expected Output
+
+```
+[2024-12-01T22:15:29.000Z] [INFO] [sdk] Logging configured
+  level: "info"
+  namespaces: ["auth", "document", "query"]
+[2024-12-01T22:15:30.123Z] [INFO] [auth] Checking URL for auth code
+[2024-12-01T22:15:30.456Z] [INFO] [auth] [project:my-project] [dataset:production] User logged in
+  userId: "user-123"
+[2024-12-01T22:15:31.789Z] [INFO] [document] [project:my-project] [dataset:production] Document synced
+  documentId: "draft.post-1"
+```
+
+## For SDK Maintainers
+
+### Using Logger in Stores
+
+```typescript
+// In authStore.ts
+import {createLogger, getInstanceContext} from '../utils/logger'
+import {defineStore} from '../store/defineStore'
+
+export const authStore = defineStore<AuthStoreState>({
+  name: 'Auth',
+
+  initialize(context) {
+    const {instance} = context
+
+    // Create logger with instance context
+    const logger = createLogger('auth', {
+      instanceContext: getInstanceContext(instance),
+    })
+
+    // Logs will automatically include [project:x] [dataset:y]
+    logger.info('Auth store initialized')
+
+    // With additional context
+    logger.debug('Fetching current user', {
+      method: 'cookie',
+      projectId: instance.config.projectId,
+    })
+  },
+})
+```
+
+### Using Logger in Static Utils
+
+```typescript
+// In utils/ids.ts (no instance context)
+import {createLogger} from './logger'
+
+const logger = createLogger('sdk')
+
+export function getDraftId(id: string): string {
+  logger.trace('Converting to draft ID', {inputId: id})
+  return `drafts.${id}`
+}
+```
+
+### Performance Timing
+
+```typescript
+import {createTimer} from '../utils/logger'
+
+async function fetchDocument(id: string) {
+  const timer = createTimer('document', 'fetchDocument')
+
+  try {
+    const doc = await client.fetch(query, {id})
+    timer.end('Document fetched successfully', {documentId: id})
+    return doc
+  } catch (error) {
+    timer.end('Document fetch failed', {documentId: id, error})
+    throw error
+  }
+}
+```
+
+## Multi-Instance Debugging
+
+When working with multiple instances, logs automatically show which instance they came from:
+
+```typescript
+const prodInstance = createSanityInstance({
+  projectId: 'my-project',
+  dataset: 'production',
+})
+
+const stagingInstance = createSanityInstance({
+  projectId: 'my-project',
+  dataset: 'staging',
+})
+
+// Logs will clearly show which instance:
+// [INFO] [query] [project:my-project] [dataset:production] Query executed
+// [INFO] [query] [project:my-project] [dataset:staging] Query executed
+```
+
+## Environment-Based Configuration
+
+```typescript
+// Configure based on environment
+const logLevel = process.env.SANITY_LOG_LEVEL || 'warn'
+const logNamespaces = process.env.SANITY_LOG_NAMESPACES?.split(',') || []
+
+configureLogging({
+  level: logLevel as LogLevel,
+  namespaces: logNamespaces,
+})
+```
+
+Then run your app with:
+
+```bash
+SANITY_LOG_LEVEL=debug SANITY_LOG_NAMESPACES=auth,document npm start
+```