philiprehberger-json_path 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5f622166e4beba5e485f24b63a4286e28b6745c120a1271cd3e663cfe87150f
-  data.tar.gz: 71dd674e321a36c295037a9672ab8c92f0eb87e6709a9ec7bbc98299abc14343
+  metadata.gz: f593dd25616efcfc78e8efbda2f1909d8ba63d19e1b144c9d9708c7a9e736fde
+  data.tar.gz: 83c8f2bc4b1dfdc7da601cb21739ae2b2ff5c22964d0cefeae04cb6bcae4d09a
 SHA512:
-  metadata.gz: ff4e5a102c7c9ab0d59add298fbd4b9b2d4f9feb2d88274cdebdbb7358cdcb97aeccd99c62e6d5e38990902a1840224e4c042cb3e03c5751cb21a27f14a95410
-  data.tar.gz: 1bb735639d90eb6827d01b6b5a37ad5b9c63d9dcece71dfd45ef124bae7cca27de0dab19335184e0351e3f86c1905603f2f39aa8b48325183542dfa60adac16e
+  metadata.gz: 63eaa887ffe7f5a8e440b06e78217c9f19391dafd3705ac0fb29a68fbd6362599532626f2c47f9848d76e83370bc3a38503942a8e48d3fbf4cd332adef9813e4
+  data.tar.gz: 86c79db3e059ae57cd8192fa63168aa58b34a6a187041a3ce7905a58276a30fd0c10b7289da3724ec122d49283011c555f9b557b3e916bee3f91a168f05217fe

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-01
+
+### Added
+- `JsonPath.update(data, path, &block)` — apply a block to every JSONPath match, replacing each with the block's return value. Mutates `data` in place; returns it for chaining. Raises when the path resolves to the root document.
+
+## [0.4.0] - 2026-04-19
+
+### Added
+- `JsonPath.last(data, path)` — last matching value; symmetric with existing `.first`; returns `nil` on no match
+
 ## [0.3.0] - 2026-04-17
 
 ### Added

data/README.md

@@ -48,6 +48,10 @@ Philiprehberger::JsonPath.values(data, '$.store.books[*].title')
 Philiprehberger::JsonPath.first(data, '$.store.books[0].title')
 # => "Ruby"
 
+items = { "items" => [{ "id" => 1 }, { "id" => 2 }, { "id" => 3 }] }
+Philiprehberger::JsonPath.first(items, "$.items[*].id") # => 1
+Philiprehberger::JsonPath.last(items, "$.items[*].id")  # => 3
+
 Philiprehberger::JsonPath.count(data, '$.store.books[*]')
 # => 3
 
@@ -126,6 +130,20 @@ Philiprehberger::JsonPath.query(data, '$.groups[?(@.members.length > 0)].name')
 # => ["team1"]
 ```
 
+### In-place Updates
+
+Apply a transformation to every match. Mutates the data and returns it for chaining.
+
+```ruby
+data = { 'users' => [{ 'name' => 'alice' }, { 'name' => 'bob' }] }
+
+Philiprehberger::JsonPath.update(data, '$.users[*].name', &:upcase)
+# data["users"].map { |u| u["name"] } => ["ALICE", "BOB"]
+
+# Increment every numeric price in a nested store
+Philiprehberger::JsonPath.update(catalog, '$..price') { |p| p * 1.10 }
+```
+
 ### Supported Syntax
 
 | Syntax | Description |
@@ -149,9 +167,11 @@ Philiprehberger::JsonPath.query(data, '$.groups[?(@.members.length > 0)].name')
 | `JsonPath.query(data, path)` | Return all matches as an array |
 | `JsonPath.values(data, path)` | Alias for `query` |
 | `JsonPath.first(data, path)` | Return the first match or nil |
+| `JsonPath.last(data, path)` | Return the last match or nil |
 | `JsonPath.count(data, path)` | Return the number of matches |
 | `JsonPath.exists?(data, path)` | Check if any match exists |
 | `JsonPath.paths(data, path)` | Return canonical JSONPath strings for each match |
+| `JsonPath.update(data, path, &block)` | Replace every matched value with the block's return; mutates `data` in place |
 
 ## Development
 

data/lib/philiprehberger/json_path/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JsonPath
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/json_path.rb

@@ -34,6 +34,15 @@ module Philiprehberger
       query(data, path).first
     end
 
+    # Query data and return the last match
+    #
+    # @param data [Hash, Array] the data structure to query
+    # @param path [String] JSONPath expression
+    # @return [Object, nil] the last matching value or nil
+    def self.last(data, path)
+      query(data, path).last
+    end
+
     # Return the number of matches for a JSONPath expression
     #
     # @param data [Hash, Array] the data structure to query
@@ -66,6 +75,79 @@ module Philiprehberger
       evaluate_with_paths(data, tokens).map { |_node, p| p }
     end
 
+    # Apply a transformation to every JSONPath match in `data`.
+    #
+    # Mutates `data` in place and returns it for chaining. Each match is
+    # replaced with the block's return value. Skips matches that resolve
+    # to the document root (`"$"`). Use `Marshal.load(Marshal.dump(data))`
+    # first if you need to preserve the original.
+    #
+    # @param data [Hash, Array] the data to transform
+    # @param path [String] JSONPath expression
+    # @yield [value] each matched value
+    # @yieldreturn [Object] the replacement value
+    # @return [Hash, Array] the mutated data
+    # @raise [Error] when the path resolves to the root document
+    def self.update(data, path, &block)
+      raise Error, 'block required for update' unless block
+
+      paths(data, path).each do |canonical|
+        raise Error, 'Cannot update root document' if canonical == '$'
+
+        mutate_at(data, canonical, &block)
+      end
+      data
+    end
+
+    # @api private
+    def self.mutate_at(data, canonical, &block)
+      segments = canonical_segments(canonical)
+      *parent_path, last = segments
+      parent = parent_path.reduce(data) { |node, seg| descend(node, seg) }
+
+      if parent.is_a?(Hash)
+        key = parent.key?(last) ? last : last.to_sym
+        parent[key] = block.call(parent[key])
+      elsif parent.is_a?(Array)
+        idx = Integer(last)
+        parent[idx] = block.call(parent[idx])
+      end
+    end
+
+    # @api private
+    def self.canonical_segments(canonical)
+      remaining = canonical[1..]
+      segments = []
+
+      until remaining.empty?
+        case remaining
+        when /\A\.([A-Za-z_][A-Za-z0-9_]*)/
+          segments << ::Regexp.last_match(1)
+          remaining = remaining[::Regexp.last_match(0).length..]
+        when /\A\['((?:\\'|[^'])*)'\]/
+          segments << ::Regexp.last_match(1).gsub("\\'", "'")
+          remaining = remaining[::Regexp.last_match(0).length..]
+        when /\A\[(\d+)\]/
+          segments << ::Regexp.last_match(1)
+          remaining = remaining[::Regexp.last_match(0).length..]
+        else
+          raise Error, "Unparseable canonical path segment: #{remaining}"
+        end
+      end
+
+      segments
+    end
+
+    # @api private
+    def self.descend(node, segment)
+      if node.is_a?(Hash)
+        node.key?(segment) ? node[segment] : node[segment.to_sym]
+      elsif node.is_a?(Array)
+        node[Integer(segment)]
+      end
+    end
+    private_class_method :mutate_at, :canonical_segments, :descend
+
     class << self
       private
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-json_path
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - philiprehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies: []
 description: Evaluate JSONPath expressions against Ruby hashes and arrays. Supports
   dot notation, array indexing, wildcards, slices, filter expressions, recursive descent,