[docs] update CLAUDE.md and selected README.md files (#5293)

* docs: add Claude documentation for settings and feature flags * docs: update services README.md * docs: update stores README.md
2026-02-08 00:50:05 +00:00 · 2025-09-01 15:31:44 -07:00
parent b592c9015e
commit 481e3b593a
5 changed files with 807 additions and 93 deletions
--- a/src/services/README.md
+++ b/src/services/README.md
@@ -12,7 +12,7 @@ This directory contains the service layer for the ComfyUI frontend application.

 ## Overview

-Services in ComfyUI provide organized modules that implement the application's functionality and logic. They handle operations such as API communication, workflow management, user settings, and other essential features. 
+Services in ComfyUI provide organized modules that implement the application's functionality and logic. They handle operations such as API communication, workflow management, user settings, and other essential features.

 The term "business logic" in this context refers to the code that implements the core functionality and behavior of the application - the rules, processes, and operations that make ComfyUI work as expected, separate from the UI display code.

@@ -57,21 +57,25 @@ While services can interact with both UI components and stores (centralized stat

 ## Core Services

-The following table lists ALL services in the system as of 2025-01-30:
+The following table lists ALL services in the system as of 2025-09-01:

 ### Main Services

 | Service | Description | Category |
 |---------|-------------|----------|
+| audioService.ts | Manages audio recording and WAV encoding functionality | Media |
 | autoQueueService.ts | Manages automatic queue execution | Execution |
 | colorPaletteService.ts | Handles color palette management and customization | UI |
 | comfyManagerService.ts | Manages ComfyUI application packages and updates | Manager |
 | comfyRegistryService.ts | Handles registration and discovery of ComfyUI extensions | Registry |
+| customerEventsService.ts | Handles customer event tracking and audit logs | Analytics |
 | dialogService.ts | Provides dialog and modal management | UI |
 | extensionService.ts | Manages extension registration and lifecycle | Extensions |
 | keybindingService.ts | Handles keyboard shortcuts and keybindings | Input |
 | litegraphService.ts | Provides utilities for working with the LiteGraph library | Graph |
 | load3dService.ts | Manages 3D model loading and visualization | 3D |
+| mediaCacheService.ts | Manages media file caching with blob storage and cleanup | Media |
+| newUserService.ts | Handles new user initialization and onboarding | System |
 | nodeHelpService.ts | Provides node documentation and help | Nodes |
 | nodeOrganizationService.ts | Handles node organization and categorization | Nodes |
 | nodeSearchService.ts | Implements node search functionality | Search |
@@ -105,47 +109,82 @@ For complex services with state management and multiple methods, class-based ser
 ```typescript
 export class NodeSearchService {
  // Service state
-  private readonly nodeFuseSearch: FuseSearch<ComfyNodeDefImpl>
-  private readonly filters: Record<string, FuseFilter<ComfyNodeDefImpl, string>>
+  public readonly nodeFuseSearch: FuseSearch<ComfyNodeDefImpl>
+  public readonly inputTypeFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly outputTypeFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly nodeCategoryFilter: FuseFilter<ComfyNodeDefImpl, string>
+  public readonly nodeSourceFilter: FuseFilter<ComfyNodeDefImpl, string>

  constructor(data: ComfyNodeDefImpl[]) {
-    // Initialize state
-    this.nodeFuseSearch = new FuseSearch(data, { /* options */ })
-    
-    // Setup filters
-    this.filters = {
-      inputType: new FuseFilter<ComfyNodeDefImpl, string>(/* options */),
-      category: new FuseFilter<ComfyNodeDefImpl, string>(/* options */)
-    }
+    // Initialize search index
+    this.nodeFuseSearch = new FuseSearch(data, {
+      fuseOptions: {
+        keys: ['name', 'display_name'],
+        includeScore: true,
+        threshold: 0.3,
+        shouldSort: false,
+        useExtendedSearch: true
+      },
+      createIndex: true,
+      advancedScoring: true
+    })
+
+    // Setup individual filters
+    const fuseOptions = { includeScore: true, threshold: 0.3, shouldSort: true }
+    this.inputTypeFilter = new FuseFilter<ComfyNodeDefImpl, string>(data, {
+      id: 'input',
+      name: 'Input Type',
+      invokeSequence: 'i',
+      getItemOptions: (node) => Object.values(node.inputs).map((input) => input.type),
+      fuseOptions
+    })
+    // Additional filters initialized similarly...
  }

-  public searchNode(query: string, filters: FuseFilterWithValue[] = []): ComfyNodeDefImpl[] {
-    // Implementation
-    return results
+  public searchNode(
+    query: string,
+    filters: FuseFilterWithValue<ComfyNodeDefImpl, string>[] = []
+  ): ComfyNodeDefImpl[] {
+    const matchedNodes = this.nodeFuseSearch.search(query)
+    return matchedNodes.filter((node) => {
+      return filters.every((filterAndValue) => {
+        const { filterDef, value } = filterAndValue
+        return filterDef.matches(node, value, { wildcard: '*' })
+      })
+    })
+  }
+
+  get nodeFilters(): FuseFilter<ComfyNodeDefImpl, string>[] {
+    return [
+      this.inputTypeFilter,
+      this.outputTypeFilter,
+      this.nodeCategoryFilter,
+      this.nodeSourceFilter
+    ]
  }
 }
 ```

 ### 2. Composable-style Services

-For simpler services or those that need to integrate with Vue's reactivity system, we prefer using composable-style services:
+For services that need to integrate with Vue's reactivity system or handle API interactions, we use composable-style services:

 ```typescript
 export function useNodeSearchService(initialData: ComfyNodeDefImpl[]) {
  // State (reactive if needed)
  const data = ref(initialData)
-  
+
  // Search functionality
  function searchNodes(query: string) {
    // Implementation
    return results
  }
-  
+
  // Additional methods
  function refreshData(newData: ComfyNodeDefImpl[]) {
    data.value = newData
  }
-  
+
  // Return public API
  return {
    searchNodes,
@@ -154,12 +193,35 @@ export function useNodeSearchService(initialData: ComfyNodeDefImpl[]) {
 }
 ```

-When deciding between these approaches, consider:
+### Service Pattern Comparison

-1. **Stateful vs. Stateless**: For stateful services, classes often provide clearer encapsulation
-2. **Reactivity needs**: If the service needs to be reactive, composable-style services integrate better with Vue's reactivity system
-3. **Complexity**: For complex services with many methods and internal state, classes can provide better organization
-4. **Testing**: Both approaches can be tested effectively, but composables may be simpler to test with Vue Test Utils
+| Aspect | Class-Based Services | Composable-Style Services | Bootstrap Services | Shared State Services |
+|--------|---------------------|---------------------------|-------------------|---------------------|
+| **Count** | 4 services | 18+ services | 1 service | 1 service |
+| **Export Pattern** | `export class ServiceName` | `export function useServiceName()` | `export function setupX()` | `export function serviceFactory()` |
+| **Instantiation** | `new ServiceName(data)` | `useServiceName()` | Direct function call | Direct function call |
+| **Best For** | Complex data structures, search algorithms, expensive initialization | Vue integration, API calls, reactive state | One-time app initialization | Singleton-like shared state |
+| **State Management** | Encapsulated private/public properties | External stores + reactive refs | Event listeners, side effects | Module-level state |
+| **Vue Integration** | Manual integration needed | Native reactivity support | N/A | Varies |
+| **Examples** | `NodeSearchService`, `Load3dService` | `workflowService`, `dialogService` | `autoQueueService` | `newUserService` |
+
+### Decision Criteria
+
+When choosing between these approaches, consider:
+
+1. **Data Structure Complexity**: Classes work well for services managing multiple related data structures (search indices, filters, complex state)
+2. **Initialization Cost**: Classes are ideal when expensive setup should happen once and be controlled by instantiation
+3. **Vue Integration**: Composables integrate seamlessly with Vue's reactivity system and stores
+4. **API Interactions**: Composables handle async operations and API calls more naturally
+5. **State Management**: Classes provide strong encapsulation; composables work better with external state management
+6. **Application Bootstrap**: Bootstrap services handle one-time app initialization, event listener setup, and side effects
+7. **Singleton Behavior**: Shared state services provide module-level state that persists across multiple function calls
+
+**Current Usage Patterns:**
+- **Class-based services (4)**: Complex data processing, search algorithms, expensive initialization
+- **Composable-style services (18+)**: UI interactions, API calls, store integration, reactive state management
+- **Bootstrap services (1)**: One-time application initialization and event handler setup
+- **Shared state services (1)**: Singleton-like behavior with module-level state management

 ### Service Template

@@ -172,7 +234,7 @@ Here's a template for creating a new composable-style service:
 export function useExampleService() {
  // Private state/functionality
  const cache = new Map()
-  
+
  /**
   * Description of what this method does
   * @param param1 Description of parameter
@@ -188,7 +250,7 @@ export function useExampleService() {
      throw error
    }
  }
-  
+
  // Return public API
  return {
    performOperation
@@ -206,16 +268,16 @@ Services in ComfyUI frequently use the following design patterns:
 export function useCachedService() {
  const cache = new Map()
  const pendingRequests = new Map()
-  
+
  async function fetchData(key: string) {
    // Check cache first
    if (cache.has(key)) return cache.get(key)
-    
+
    // Check if request is already in progress
    if (pendingRequests.has(key)) {
      return pendingRequests.get(key)
    }
-    
+
    // Perform new request
    const requestPromise = fetch(`/api/${key}`)
      .then(response => response.json())
@@ -224,11 +286,11 @@ export function useCachedService() {
        pendingRequests.delete(key)
        return data
      })
-    
+
    pendingRequests.set(key, requestPromise)
    return requestPromise
  }
-  
+
  return { fetchData }
 }
 ```
@@ -248,7 +310,7 @@ export function useNodeFactory() {
        throw new Error(`Unknown node type: ${type}`)
    }
  }
-  
+
  return { createNode }
 }
 ```
@@ -267,11 +329,243 @@ export function useWorkflowService(
    const storagePath = await storageService.getPath(name)
    return apiService.saveData(storagePath, graphData)
  }
-  
+
  return { saveWorkflow }
 }
 ```

+## Testing Services
+
+Services in ComfyUI can be tested effectively using different approaches depending on their implementation pattern.
+
+### Testing Class-Based Services
+
+**Setup Requirements:**
+```typescript
+// Manual instantiation required
+const mockData = [/* test data */]
+const service = new NodeSearchService(mockData)
+```
+
+**Characteristics:**
+- Requires constructor argument preparation
+- State is encapsulated within the class instance
+- Direct method calls on the instance
+- Good isolation - each test gets a fresh instance
+
+**Example:**
+```typescript
+describe('NodeSearchService', () => {
+  let service: NodeSearchService
+
+  beforeEach(() => {
+    const mockNodes = [/* mock node definitions */]
+    service = new NodeSearchService(mockNodes)
+  })
+
+  test('should search nodes by query', () => {
+    const results = service.searchNode('test query')
+    expect(results).toHaveLength(2)
+  })
+
+  test('should apply filters correctly', () => {
+    const filters = [{ filterDef: service.inputTypeFilter, value: 'IMAGE' }]
+    const results = service.searchNode('*', filters)
+    expect(results.every(node => /* has IMAGE input */)).toBe(true)
+  })
+})
+```
+
+### Testing Composable-Style Services
+
+**Setup Requirements:**
+```typescript
+// Direct function call, no instantiation
+const { saveWorkflow, loadWorkflow } = useWorkflowService()
+```
+
+**Characteristics:**
+- No instantiation needed
+- Integrates naturally with Vue Test Utils
+- Easy mocking of reactive dependencies
+- External store dependencies need mocking
+
+**Example:**
+```typescript
+describe('useWorkflowService', () => {
+  beforeEach(() => {
+    // Mock external dependencies
+    vi.mock('@/stores/settingStore', () => ({
+      useSettingStore: () => ({
+        get: vi.fn().mockReturnValue(true),
+        set: vi.fn()
+      })
+    }))
+
+    vi.mock('@/stores/toastStore', () => ({
+      useToastStore: () => ({
+        add: vi.fn()
+      })
+    }))
+  })
+
+  test('should save workflow with prompt', async () => {
+    const { saveWorkflow } = useWorkflowService()
+    await saveWorkflow('test-workflow')
+
+    // Verify interactions with mocked dependencies
+    expect(mockSettingStore.get).toHaveBeenCalledWith('Comfy.PromptFilename')
+  })
+})
+```
+
+### Testing Bootstrap Services
+
+**Focus on Setup Behavior:**
+```typescript
+describe('autoQueueService', () => {
+  beforeEach(() => {
+    // Mock global dependencies
+    vi.mock('@/scripts/api', () => ({
+      api: {
+        addEventListener: vi.fn()
+      }
+    }))
+
+    vi.mock('@/scripts/app', () => ({
+      app: {
+        queuePrompt: vi.fn()
+      }
+    }))
+  })
+
+  test('should setup event listeners', () => {
+    setupAutoQueueHandler()
+
+    expect(mockApi.addEventListener).toHaveBeenCalledWith('graphChanged', expect.any(Function))
+  })
+
+  test('should handle graph changes when auto-queue enabled', () => {
+    setupAutoQueueHandler()
+
+    // Simulate graph change event
+    const graphChangeHandler = mockApi.addEventListener.mock.calls[0][1]
+    graphChangeHandler()
+
+    expect(mockApp.queuePrompt).toHaveBeenCalled()
+  })
+})
+```
+
+### Testing Shared State Services
+
+**Focus on Shared State Behavior:**
+```typescript
+describe('newUserService', () => {
+  beforeEach(() => {
+    // Reset module state between tests
+    vi.resetModules()
+  })
+
+  test('should return consistent API across calls', () => {
+    const service1 = newUserService()
+    const service2 = newUserService()
+
+    // Same functions returned (shared behavior)
+    expect(service1.isNewUser).toBeDefined()
+    expect(service2.isNewUser).toBeDefined()
+  })
+
+  test('should share state between service instances', async () => {
+    const service1 = newUserService()
+    const service2 = newUserService()
+
+    // Initialize through one instance
+    const mockSettingStore = { set: vi.fn() }
+    await service1.initializeIfNewUser(mockSettingStore)
+
+    // State should be shared
+    expect(service2.isNewUser()).toBe(true) // or false, depending on mock
+  })
+})
+```
+
+### Common Testing Patterns
+
+**Mocking External Dependencies:**
+```typescript
+// Mock stores
+vi.mock('@/stores/settingStore', () => ({
+  useSettingStore: () => ({
+    get: vi.fn(),
+    set: vi.fn()
+  })
+}))
+
+// Mock API calls
+vi.mock('@/scripts/api', () => ({
+  api: {
+    get: vi.fn().mockResolvedValue({ data: 'mock' }),
+    post: vi.fn().mockResolvedValue({ success: true })
+  }
+}))
+
+// Mock Vue composables
+vi.mock('vue', () => ({
+  ref: vi.fn((val) => ({ value: val })),
+  reactive: vi.fn((obj) => obj)
+}))
+```
+
+**Async Testing:**
+```typescript
+test('should handle async operations', async () => {
+  const service = useMyService()
+  const result = await service.performAsyncOperation()
+  expect(result).toBeTruthy()
+})
+
+test('should handle concurrent requests', async () => {
+  const service = useMyService()
+  const promises = [
+    service.loadData('key1'),
+    service.loadData('key2')
+  ]
+
+  const results = await Promise.all(promises)
+  expect(results).toHaveLength(2)
+})
+```
+
+**Error Handling:**
+```typescript
+test('should handle service errors gracefully', async () => {
+  const service = useMyService()
+
+  // Mock API to throw error
+  mockApi.get.mockRejectedValue(new Error('Network error'))
+
+  await expect(service.fetchData()).rejects.toThrow('Network error')
+})
+
+test('should provide meaningful error messages', async () => {
+  const service = useMyService()
+  const consoleSpy = vi.spyOn(console, 'error').mockImplementation()
+
+  await service.handleError('test error')
+
+  expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('test error'))
+})
+```
+
+### Testing Best Practices
+
+1. **Isolate Dependencies**: Always mock external dependencies (stores, APIs, DOM)
+2. **Reset State**: Use `beforeEach` to ensure clean test state
+3. **Test Error Paths**: Don't just test happy paths - test error scenarios
+4. **Mock Timers**: Use `vi.useFakeTimers()` for time-dependent services
+5. **Test Async Properly**: Use `async/await` and proper promise handling
+
 For more detailed information about the service layer pattern and its applications, refer to:
 - [Service Layer Pattern](https://en.wikipedia.org/wiki/Service_layer_pattern)
 - [Service-Orientation](https://en.wikipedia.org/wiki/Service-orientation)