mirror of
https://github.com/Comfy-Org/ComfyUI_frontend.git
synced 2026-02-27 02:04:09 +00:00
97547434b0
- Replace metadata-based approach with import-based version selection - Add dual endpoint fetching strategy (object_info + v3/object_info) - Implement proxy-based bidirectional data synchronization - Create version-specific type definitions (v1, v1.2, v3) - Add data transformation pipeline between API versions - Update extension service for version-aware invocation This provides type-safe API versioning where extensions choose their API version through imports, ensuring compile-time safety and zero breaking changes for existing extensions.
134 lines
4.2 KiB
Markdown
134 lines
4.2 KiB
Markdown
# ComfyUI Frontend V3 Compatibility - Implementation Summary
|
|
|
|
## Core Concept
|
|
**Import-based API versioning** with proxy-synchronized data layers. Extensions choose their API version through imports, getting typed interfaces and guaranteed backward compatibility.
|
|
|
|
## Architecture Overview
|
|
|
|
### 1. Version-Specific Imports
|
|
```typescript
|
|
// Legacy (unchanged)
|
|
import { app } from '@/scripts/app'
|
|
|
|
// Version-specific
|
|
import { app } from '@/scripts/app/v1' // v1.x API
|
|
import { app } from '@/scripts/app/v1_2' // v1.2 API
|
|
import { app } from '@/scripts/app/v3' // v3.x API
|
|
import { app } from '@/scripts/app/latest' // Latest
|
|
|
|
// Typed interfaces per version
|
|
app.registerExtension({
|
|
beforeRegisterNodeDef(nodeType, nodeData: ComfyNodeDefV1_2, app: ComfyAppV1_2) {
|
|
// nodeData guaranteed to be v1.2 format
|
|
}
|
|
})
|
|
```
|
|
|
|
### 2. Dual Endpoint Data Fetching
|
|
```typescript
|
|
// Simultaneous fetching from multiple endpoints
|
|
const [currentData, v3Data] = await Promise.allSettled([
|
|
api.get('/object_info'), // Current format
|
|
api.get('/v3/object_info') // V3 format
|
|
])
|
|
|
|
// All versions stored and transformed
|
|
nodeDefinitions.value = {
|
|
canonical: mergeToCanonical(currentData, v3Data),
|
|
v1: transformToV1(currentData),
|
|
v1_2: transformToV1_2(currentData),
|
|
v3: v3Data || transformToV3(currentData)
|
|
}
|
|
```
|
|
|
|
### 3. Proxy-Based Synchronization
|
|
```typescript
|
|
// Bidirectional data sync through proxies
|
|
const createV1_2Proxy = (canonical: ComfyNodeDefLatest) => {
|
|
return new Proxy({}, {
|
|
get(target, prop) {
|
|
return transformCanonicalToV1_2(canonical, prop)
|
|
},
|
|
set(target, prop, value) {
|
|
transformV1_2ToCanonical(canonical, prop, value)
|
|
notifyChange(canonical.name, prop, value)
|
|
return true
|
|
}
|
|
})
|
|
}
|
|
```
|
|
|
|
## Implementation Structure
|
|
|
|
### Phase 1: API Infrastructure (3-4 days)
|
|
- **Entry Points**: `src/scripts/app/v1.ts`, `src/scripts/app/v1_2.ts`, etc.
|
|
- **Type Definitions**: `src/types/versions/` with version-specific interfaces
|
|
- **Adapters**: `src/scripts/app/adapters/` for API compatibility layers
|
|
|
|
### Phase 2: Data Layer (2-3 days)
|
|
- **Multi-Version Store**: Single store with all format versions
|
|
- **Transform Pipeline**: `src/utils/versionTransforms.ts` for format conversion
|
|
- **Reactive Getters**: Version-specific computed properties
|
|
|
|
### Phase 3: Proxy System (2-3 days)
|
|
- **Bidirectional Proxies**: `src/utils/versionProxies.ts`
|
|
- **Change Notification**: Event system for data sync
|
|
- **Type Safety**: Proper typing for proxy objects
|
|
|
|
### Phase 4: Extension Integration (2-3 days)
|
|
- **Version-Aware Service**: Extensions grouped by API version
|
|
- **Hook Invocation**: Transform args per version before calling
|
|
- **App Adapters**: Version-specific app instances
|
|
|
|
## Key Benefits
|
|
|
|
- **Type Safety**: Compile-time checking for each API version
|
|
- **Zero Breaking Changes**: Existing extensions work unchanged
|
|
- **Bidirectional Sync**: Changes through any API stay synchronized
|
|
- **Performance**: No runtime version detection overhead
|
|
- **Future Proof**: Easy to add new API versions
|
|
- **Developer Experience**: Clear, typed interfaces
|
|
|
|
## Migration Path
|
|
|
|
```typescript
|
|
// Step 1: No changes (works with latest)
|
|
import { app } from '@/scripts/app'
|
|
|
|
// Step 2: Explicit version (better compatibility)
|
|
import { app } from '@/scripts/app/v1_2'
|
|
|
|
// Step 3: Use newer APIs when ready
|
|
import { app } from '@/scripts/app/latest'
|
|
```
|
|
|
|
## Example Usage
|
|
|
|
```typescript
|
|
// v1.2 Extension
|
|
import { app } from '@/scripts/app/v1_2'
|
|
|
|
app.registerExtension({
|
|
name: 'MyExtension',
|
|
beforeRegisterNodeDef(nodeType, nodeData: ComfyNodeDefV1_2, app) {
|
|
// nodeData.input.required - v1 format
|
|
// nodeData.inputs - v1.2 format
|
|
if (nodeData.inputs) {
|
|
// Use v1.2 features
|
|
} else {
|
|
// Fallback to v1 format
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
## Implementation Timeline
|
|
- **Phase 1**: API Version Infrastructure (3-4 days)
|
|
- **Phase 2**: Multi-Version Data Layer (2-3 days)
|
|
- **Phase 3**: Proxy-Based Synchronization (2-3 days)
|
|
- **Phase 4**: Extension System Integration (2-3 days)
|
|
- **Phase 5**: Migration Tools & Documentation (1-2 days)
|
|
|
|
**Total**: 10-15 days
|
|
|
|
This approach provides type-safe API versioning that scales with ComfyUI's growth while maintaining complete backward compatibility and smooth migration paths for extension developers. |