Skip to content

Refactor Core Architecture and Transition to v2.0.0.#22

Merged
brunoga merged 2 commits intomainfrom
jsonpatch-predicates
Feb 11, 2026
Merged

Refactor Core Architecture and Transition to v2.0.0.#22
brunoga merged 2 commits intomainfrom
jsonpatch-predicates

Conversation

@brunoga
Copy link
Owner

@brunoga brunoga commented Feb 11, 2026

Overview
This PR represents a major evolution of the deep library. It focuses on modularizing the internal implementation, significantly improving performance and memory efficiency, and unifying the public API into a more ergonomic and consistent model. Due to breaking changes in the Condition interface and function signatures, this PR transitions the project to v2.0.0.

Key Changes

  1. Modular Architecture
  • Deconstructed the monolithic patch.go and condition.go into specialized logical units (_ops, _parser, _serialization, _utils).
  • Improved maintainability and isolated testing for core components.
  1. Unified & Ergonomic API
  • Polymorphic Options: Introduced an interface-based options pattern. A single deep.IgnorePath("path") now works seamlessly for both Copy and Diff.
  • Blind Updates: Added Node.Put(value) to the Builder, allowing for "blind" sets that bypass strict consistency checks—ideal for API-driven updates.
  • Navigation: Exported Node.Navigate(path) supporting both Go-style notation and JSON Pointers.
  • Deprecation: CopySkipUnsupported is now deprecated in favor of the deep.SkipUnsupported() option.
  1. High-Performance Optimizations
  • Copy Fast-Path: Achieved up to 7x faster cloning for basic types by bypassing the recursive engine when no options are present.
  • Reduced Allocations:
    • Implemented sync.Pool for internal pointer tracking maps.
    • Lazy path construction: Structural paths are now only computed if IgnorePath options are active.
  • Reflection Reduction: Refactored condition evaluation to use a "sealed" internal interface instead of MethodByName reflection, significantly speeding up ApplyChecked calls.
  • Slice Diffing: Added $O(N)$ fast-paths for simple appends and removals.
  1. Robustness & Bug Fixes
  • Fixed a critical bug in Copy where self-referencing value-type structs were not correctly detected as cycles.
  • Added guards against panics when handling nil interfaces or nil pointers implementing the Copier interface.
  1. Documentation & Standards
  • Completely restructured README.md to follow a logical progression (Quick Start → Core Concepts → Advanced Logic).
  • Added 100% Go doc coverage for the public interface.
  • Updated module path to github.com/brunoga/deep/v2 per Go SemVer requirements.

- Modularized patch.go and condition.go into specialized sub-files
  (ops, parser, serialization, utils) to improve maintainability.
- Unified Copy and Diff APIs using a polymorphic functional options
  pattern, introducing shared IgnorePath and SkipUnsupported options.
- Optimized Copy performance (up to 7x faster for basic types) via:
    - sync.Pool for pointersMap to reduce garbage collection pressure.
    - Fast-path for basic types bypassing expensive recursion.
    - Lazy path string construction.
- Optimized Condition evaluation by replacing reflection-based calls
  with a direct internal interface.
- Enhanced Diff with fast-paths for simple slice appends/removals.
- Refined unsafe.DisableRO usage to be surgical, targeting only
  unexported fields.
- Fixed critical bugs in Copy regarding cyclic self-referencing value
  types and nil interface handling.
- Completely restructured README.md for better clarity and added
  comprehensive Go doc comments across the public interface.
- Reorganized and expanded test suite to match new modular structure.
@brunoga brunoga merged commit 6899f7f into main Feb 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant