philiprehberger-json_path 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd62ae147160109624e6b6d186c60479cfca265cbe8c66f40755863a532abc1e
-  data.tar.gz: 2cac68f58e4ea420d84429d660730a07de443d71d8560b025c82a5166239ccb2
+  metadata.gz: 9d1f6e3df479eeb12b69af816742069bd38c31953c3b1611add83bc3aac4434a
+  data.tar.gz: 69b8a9a12b7a95fcf12ac173c6559d9e002a9d8d085c05b28716eb9948262fe5
 SHA512:
-  metadata.gz: b8f52edcf91f65be006493f1e9c60b03cbf6fbe83e935602622d96f07f729a560d02d49532976f72e5ba6c292a4c5f063298373cba732e158e2003ef5b2ad0a0
-  data.tar.gz: 027f7f078a753000cf26c1783b045e58dbf65100c8de3ca8496196d7f48c61ddf5e14e5904dc5aa5ea1981510780742301cb985ed9e73f698bcfd8e9147c2fa0
+  metadata.gz: c603bf6cd3c2a58f248b1ca535ebcd63d28f3d1cdc269ff73f7e2889f161316c0a1c3a710c7e250c5529d090458fc42ffeac1cb2a43020fb81d037b500548a04
+  data.tar.gz: 12a21c296a86fe78d87ffd71ad9bba9b81200d60c8ffb1f3959e77f56f7312d31fda4d04fc00e3baa37103dee548237d0827810d8abe672b148b696d86f9c9e4

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- `JsonPath.paths(data, expression)` returns the canonical JSONPath strings of every match (complement to `.values`)
+
 ## [0.2.0] - 2026-04-03
 
 ### 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
 
@@ -55,6 +59,21 @@ Philiprehberger::JsonPath.exists?(data, '$.store.books')
 # => true
 ```
 
+### Matched paths
+
+Use `paths` to get canonical JSONPath strings for every match, rather than the values themselves. Each returned path re-evaluates back to the single element it identifies, making it handy for diffing, patching, or reporting.
+
+```ruby
+Philiprehberger::JsonPath.paths(data, '$.store.books[*].title')
+# => ["$.store.books[0].title", "$.store.books[1].title", "$.store.books[2].title"]
+
+Philiprehberger::JsonPath.paths(data, '$.store.books[?(@.price>22)]')
+# => ["$.store.books[0]", "$.store.books[1]"]
+
+Philiprehberger::JsonPath.paths(data, '$.missing')
+# => []
+```
+
 ### Recursive Descent
 
 ```ruby
@@ -134,8 +153,10 @@ 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 |
 
 ## Development
 

data/lib/philiprehberger/json_path/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JsonPath
-    VERSION = '0.2.0'
+    VERSION = '0.4.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
@@ -52,6 +61,20 @@ module Philiprehberger
       !query(data, path).empty?
     end
 
+    # Return the canonical JSONPath strings for every match of an expression
+    #
+    # Each returned path is an unambiguous JSONPath that, when re-evaluated,
+    # resolves to the single element it identifies. Paths are returned in
+    # document order. Returns an empty array when no matches exist.
+    #
+    # @param data [Hash, Array] the data structure to query
+    # @param path [String] JSONPath expression
+    # @return [Array<String>] canonical JSONPath strings for each match
+    def self.paths(data, path)
+      tokens = tokenize(path)
+      evaluate_with_paths(data, tokens).map { |_node, p| p }
+    end
+
     class << self
       private
 
@@ -281,6 +304,163 @@ module Philiprehberger
         end
       end
 
+      SAFE_KEY = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      def evaluate_with_paths(data, tokens)
+        results = [[data, '$']]
+
+        tokens.each do |token|
+          results = results.flat_map { |node, path| apply_token_with_paths(node, path, token) }
+        end
+
+        results
+      end
+
+      def apply_token_with_paths(node, path, token)
+        case token[:type]
+        when :key
+          apply_key_with_paths(node, path, token[:value])
+        when :index
+          apply_index_with_paths(node, path, token[:value])
+        when :wildcard
+          apply_wildcard_with_paths(node, path)
+        when :slice
+          apply_slice_with_paths(node, path, token[:start], token[:end])
+        when :filter
+          apply_filter_with_paths(node, path, token[:key], token[:op], token[:value])
+        when :filter_exists
+          apply_filter_exists_with_paths(node, path, token[:key])
+        when :filter_not_exists
+          apply_filter_not_exists_with_paths(node, path, token[:key])
+        when :filter_length
+          apply_filter_length_with_paths(node, path, token[:key_path], token[:op], token[:value])
+        when :recursive
+          apply_recursive_with_paths(node, path, token[:value])
+        else
+          []
+        end
+      end
+
+      def key_segment(key)
+        str = key.to_s
+        SAFE_KEY.match?(str) ? ".#{str}" : "['#{str.gsub("'", "\\\\'")}']"
+      end
+
+      def apply_key_with_paths(node, path, key)
+        return [] unless node.is_a?(Hash)
+
+        sym_key = key.to_sym
+        if node.key?(key)
+          [[node[key], path + key_segment(key)]]
+        elsif node.key?(sym_key)
+          [[node[sym_key], path + key_segment(key)]]
+        else
+          []
+        end
+      end
+
+      def apply_index_with_paths(node, path, index)
+        return [] unless node.is_a?(Array)
+        return [] if index >= node.length || index < -node.length
+
+        normalized = index.negative? ? node.length + index : index
+        [[node[index], "#{path}[#{normalized}]"]]
+      end
+
+      def apply_wildcard_with_paths(node, path)
+        case node
+        when Array
+          node.each_with_index.map { |v, i| [v, "#{path}[#{i}]"] }
+        when Hash
+          node.map { |k, v| [v, path + key_segment(k)] }
+        else
+          []
+        end
+      end
+
+      def apply_slice_with_paths(node, path, start_idx, end_idx)
+        return [] unless node.is_a?(Array)
+
+        end_idx = node.length if end_idx.nil?
+        range = (start_idx...end_idx)
+        indices = range.to_a.select { |i| i >= 0 && i < node.length }
+        indices.map { |i| [node[i], "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_with_paths(node, path, key, op, value)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          actual = item[key] || item[key.to_sym]
+          next false if actual.nil? && !item.key?(key) && !item.key?(key.to_sym)
+
+          compare(actual, op, value)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_exists_with_paths(node, path, key)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          item.key?(key) || item.key?(key.to_sym)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_not_exists_with_paths(node, path, key)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.reject do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          item.key?(key) || item.key?(key.to_sym)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_filter_length_with_paths(node, path, key_path, op, value)
+        return [] unless node.is_a?(Array)
+
+        matches = node.each_with_index.select do |item, _i|
+          next false unless item.is_a?(Hash)
+
+          resolved = resolve_key_path(item, key_path)
+          next false if resolved.nil?
+
+          length = resolved.respond_to?(:length) ? resolved.length : nil
+          next false if length.nil?
+
+          compare(length, op, value)
+        end
+        matches.map { |item, i| [item, "#{path}[#{i}]"] }
+      end
+
+      def apply_recursive_with_paths(node, path, key)
+        results = []
+        collect_recursive_with_paths(node, path, key, results)
+        results
+      end
+
+      def collect_recursive_with_paths(node, path, key, results)
+        case node
+        when Hash
+          node.each do |k, v|
+            child_path = path + key_segment(k)
+            results << [v, child_path] if k.to_s == key
+            collect_recursive_with_paths(v, child_path, key, results)
+          end
+        when Array
+          node.each_with_index do |item, i|
+            collect_recursive_with_paths(item, "#{path}[#{i}]", key, results)
+          end
+        end
+      end
+
       def compare(actual, op, value)
         case op
         when '==' then actual == value

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-json_path
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - philiprehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-20 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,