Add modify nodes interface

[ashphy]

Summary

• Document comprehensive interface design for modify nodes functionality
• Add update(), parents(), and pathSegments() methods to README
• Provide detailed TypeScript interfaces and usage examples
• Include advanced modification patterns for JSON manipulation

Detailed API Interface

1. update(json, callback) Method

Purpose: Modify matched nodes using a callback function with rich context access.

Signature:

update<T = Json>(json: Json, callback: UpdateCallback<T>): Json

Types:

type UpdateCallback<T = Json> = (
  value: T,
  context: {
    key: string | number;        // Property key or array index
    parent: ModifiableNode;      // Parent node with modification capabilities
    path: string;                // Full JSONPath to current node
    root: Json;                  // Reference to root document
  }
) => T | undefined;  // Return undefined to delete the node

Features:

• In-place modification with callback pattern
• Rich context including parent, key, path, and root access
• Support for node deletion by returning undefined
• Type-safe callback with generic support

---

2. parents(json) Method

Purpose: Access nodes with their parent context for complex modification scenarios.

Signature:

parents(json: Json): ParentNode[]

Types:

type ParentNode = {
  value: Json;                    // Current node value
  path: string;                   // JSONPath to this node
  key: string | number;           // Property key or array index
  parent: ModifiableNode;         // Parent with modification methods
  root: Json;                     // Reference to root document
  
  // Modification methods
  update(callback: UpdateCallback): void;
  delete(): void;
  replace(newValue: Json): void;
};

Features:

• Direct parent-child relationship access
• Contextual modification based on parent data
• Individual node modification methods
• Maintains reference to root document

---

3. pathSegments(json) Method

Purpose: Provide detailed path information for precise navigation and modification.

Signature:

pathSegments(json: Json): PathSegment[]

Types:

type PathSegment = {
  value: Json;                      // Node value
  path: string;                     // Full JSONPath string
  segments: string[];               // Array of path segments
  depth: number;                    // Depth level (0 = root)
  isLeaf: boolean;                  // True if node has no children
  ancestors: AncestorNode[];        // Array of ancestor nodes
  
  // Modification methods
  update(callback: UpdateCallback): void;
  delete(): void;
  replace(newValue: Json): void;
  
  // Navigation methods
  getAncestor(depth: number): AncestorNode | undefined;
  getSegment(index: number): string | undefined;
};

type AncestorNode = {
  value: Json;
  path: string;
  segment: string;
  depth: number;
};

Features:

• Granular path analysis with segment breakdown
• Ancestor navigation capabilities
• Depth-based modification logic
• Leaf node identification

---

4. Core ModifiableNode Interface

All modification methods return nodes implementing this unified interface:

interface ModifiableNode {
  value: Json;
  path: string;
  
  // Core modification methods
  update(callback: UpdateCallback): void;
  replace(newValue: Json): void;
  delete(): void;
  
  // Type checking utilities
  isArray(): boolean;
  isObject(): boolean;
  isPrimitive(): boolean;
  
  // Array-specific methods (when isArray() returns true)
  push(value: Json): void;
  splice(start: number, deleteCount?: number, ...items: Json[]): void;
  
  // Object-specific methods (when isObject() returns true)
  set(key: string, value: Json): void;
  unset(key: string): void;
  keys(): string[];
}

Features:

• Unified modification interface across all methods
• Type-specific operations for arrays and objects
• Runtime type checking capabilities
• Consistent API surface

---

Usage Examples

Basic Modification

const data = { users: [{ name: "John", temp: true }] };
const query = new JSONPathJS("$.users[*]");

// Remove temporary properties
query.update(data, (user) => {
  const { temp, ...cleanUser } = user;
  return cleanUser;
});

Parent Context Access

const data = {
  sections: [
    { title: "Intro", metadata: { priority: "low" } }
  ]
};

const query = new JSONPathJS("$.sections[*].metadata");
query.parents(data).forEach(node => {
  if (node.parent.value.title === "Intro") {
    node.update(meta => ({ ...meta, priority: "high" }));
  }
});

Path-Based Logic

const query = new JSONPathJS("$..connections.*");
query.pathSegments(data).forEach(segment => {
  if (segment.segments.includes("primary")) {
    segment.update(conn => ({ ...conn, ssl: true }));
  }
});

---

Design Principles

1. Immutability by Default: Original data preserved unless explicitly modified
2. Rich Context Access: Full parent, path, and root context available
3. Type Safety: Strong TypeScript interfaces throughout
4. Flexible Patterns: Multiple modification approaches for different use cases
5. JSONPath Compliance: All operations maintain RFC 9535 compatibility

Test Plan

• Review interface design for completeness
• Validate TypeScript type definitions match implementation needs
• Ensure examples cover common use cases
• Confirm alignment with RFC 9535 JSONPath specification
• Verify modification patterns work with existing codebase architecture
• Ready for implementation phase

Addresses #13

🤖 Generated with Claude Code