Skip to content

Latest commit

 

History

History
198 lines (158 loc) · 4.42 KB

technical_design.md

File metadata and controls

198 lines (158 loc) · 4.42 KB

Technical Design Document: JSON Management Custom Nodes

1. System Architecture

1.1 Overview

The JSON Management system will be implemented as a collection of custom nodes for ComfyUI, built in Python. Each node will inherit from a common base class that provides shared functionality for JSON handling and error management.

1.2 Base Components

BaseJSONNode

Common base class providing:

  • JSON validation utilities
  • Error handling mechanisms
  • Type checking functions
  • Performance optimization helpers

2. Node Specifications

2.1 RandomJSONValueNode

Purpose: Extract random values from JSON structures Processing Logic:

  • For arrays: Use random.choice() for direct selection
  • For objects: First select random key, then return corresponding value
  • For nested structures: Support depth parameter for multi-level random selection

Edge Cases:

  • Empty JSON structures
  • Mixed data types
  • Nested structures exceeding maximum depth

2.2 JSONObjectIteratorNode

Purpose: Iterate through JSON object key-value pairs Processing Logic:

  • Implement iterator protocol
  • Maintain iteration state
  • Support pause/resume operations

State Management:

  • Current iteration index
  • Iteration history
  • Reset capability

2.3 JSONArrayIteratorNode

Purpose: Sequential array element access Processing Logic:

  • Linear array traversal
  • Index tracking
  • Element type handling

Features:

  • Bidirectional iteration
  • Index access
  • Batch processing capability

2.4 JSONMergeNode

Purpose: Combine multiple JSON structures Processing Logic:

  • Deep merge for objects
  • Concatenation for arrays
  • Conflict resolution strategies

Merge Strategies:

  • Override existing keys
  • Preserve existing keys
  • Custom conflict resolution

2.5 JSONModifierNode

Purpose: Update JSON object values Processing Logic:

  • Path-based value location
  • Type-safe value replacement
  • Structure preservation

Validation:

  • Key existence checking
  • Type compatibility verification
  • Structure integrity maintenance

2.6 JSONParserNode

Purpose: Convert string to JSON structure Processing Logic:

  • JSON syntax validation
  • Schema validation (optional)
  • Error recovery options

Error Handling:

  • Syntax error detection
  • Schema violation reporting
  • Malformed input recovery

2.7 JSONGeneratorNode

Purpose: Create new JSON objects Processing Logic:

  • Dynamic object construction
  • Type inference
  • Schema compliance

Validation:

  • Key uniqueness
  • Value type validation
  • Structure consistency

2.8 JSONLengthNode

Purpose: Calculate JSON structure size Processing Logic:

  • Object key counting
  • Array length calculation
  • Nested structure handling

Features:

  • Depth-aware counting
  • Type-specific calculations
  • Performance optimization for large structures

2.9 JSONKeyCheckerNode

Purpose: Verify key existence Processing Logic:

  • Key path resolution
  • Nested key checking
  • Case sensitivity options

Features:

  • Deep key checking
  • Multiple key verification
  • Partial path matching

2.10 JSONStringifierNode

Purpose: Convert JSON to string Processing Logic:

  • Pretty printing
  • Compact formatting
  • Custom formatting options

Features:

  • Indentation control
  • Encoding options
  • Format customization

3. Error Handling Strategy

3.1 Error Categories

  • Syntax Errors
  • Type Errors
  • Value Errors
  • Structure Errors

3.2 Error Response

  • Detailed error messages
  • Error recovery options
  • User-friendly notifications

4. Performance Considerations

4.1 Optimization Strategies

  • Lazy evaluation for large structures
  • Caching for frequently accessed values
  • Stream processing for large arrays

4.2 Memory Management

  • Efficient data structure usage
  • Memory-conscious operations
  • Resource cleanup

5. Integration Requirements

5.1 ComfyUI Integration

  • Node registration
  • UI component integration
  • Event handling

5.2 Data Flow

  • Input validation
  • Output formatting
  • Inter-node communication

6. Testing Strategy

6.1 Test Categories

  • Unit tests for individual nodes
  • Integration tests for node combinations
  • Performance tests for large datasets

6.2 Test Coverage

  • Edge cases
  • Error conditions
  • Performance benchmarks

7. Documentation Requirements

7.1 Code Documentation

  • Function documentation
  • Class documentation
  • Usage examples

7.2 User Documentation

  • Node usage guides
  • Example workflows
  • Troubleshooting guides