Q-Bug4-Comfyui-Simple-Json-Node/technical_design.md

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