json-mask 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b68741ab4daac730737fe2b7a0f0550409d981fe7535619d2c2655a1c1a9beba
-  data.tar.gz: f65a88df55f70fcb6c2af28f97a805a0dd2a0fbd34c4d2d0975b685946ef1d53
+  metadata.gz: bf429554b940fea4a030589830ad3eb3ad509983d365f19c0c371c5ff026b530
+  data.tar.gz: 8ff525f2b92a3c4f8634c4c28b96f2dc54d2652a0b5a760f267cf3b7f9885627
 SHA512:
-  metadata.gz: 46daa73f26f18e75dc6f1cc83232e33a047326801f38807c5fa2df8f16c94fdebef63778a2acce086aeb75446cb613d700d5f11dc4c9b09f7aa3e2c088b83189
-  data.tar.gz: 1ef0a561a43eb13ca3e877a7f1dde1590125fb38ff51d609e35f0bc8ee119278144cb3575cbaea19af14e08bcb742c6d183886dfe9f21edf270c9edc7981bb43
+  metadata.gz: fb6a7be61059829fb6219b874fcfa41369070aecbd4792889e70a63a6d3c9aeb0b45b727a2cd80c6a2ee4297d695790d72b8c61fc668a1b2c73db64388805537
+  data.tar.gz: 52f4c5e63190f7fe5cc238eb13b65b86e93696470d5a0b34704b14e7c46f814b76cf37fb5eea90c02d2d5befa600beaa209f7405f44d4c1289f2f04be8f39d41

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## 0.1.0 - Unreleased
+## 0.2.0 - 2026-09-04
+
+- Expose compiled selectors for inspection. `CompiledMask#selection_tree` returns the root
+  `JsonMask::SelectionTree`; its `named`, `wildcard`, and `selection_for` readers and
+  `JsonMask::Selection`'s `leaf?` and `children` are public API. Applications that have a
+  response schema can use the tree to reject selectors that name undeclared fields.
+
+## 0.1.0 - 2026-08-04
 
 - Implement Google partial-response and JSON Mask field selectors.
 - Support comma-separated fields, slash paths, sub-selections, wildcards, and escaping.

data/README.md

@@ -116,7 +116,68 @@ Exceeding a limit raises `JsonMask::LimitError`, a subclass of `JsonMask::ParseE
 
 Validation is syntactic. Because the library has no response schema, a well-formed selector that
 names a field absent from the input simply omits that field; it cannot produce Google's
-schema-aware "Invalid field selection" error on its own.
+schema-aware "Invalid field selection" error on its own. An application that has a schema can
+produce one by inspecting the compiled selector.
+
+## Inspecting a compiled selector
+
+`JsonMask::CompiledMask#selection_tree` exposes the parsed selector as an immutable tree, for
+callers that need to examine a selector rather than apply it:
+
+```ruby
+tree = JsonMask.compile("id,permissions(role),*/kind").selection_tree
+
+tree.named.keys                                        # => ["id", "permissions"]
+tree.named["id"].leaf?                                 # => true
+tree.named["permissions"].children.named.keys          # => ["role"]
+tree.wildcard.children.named.keys                      # => ["kind"]
+tree.selection_for("permissions").children.named.keys  # => ["role", "kind"]
+tree.selection_for("other").children.named.keys        # => ["kind"]
+```
+
+- A `JsonMask::SelectionTree` holds `named`, a frozen `Hash` from each explicitly written field
+  name (unescaped) to a `JsonMask::Selection`, and `wildcard`, the `*` selection at that level or
+  `nil`.
+- A `JsonMask::Selection` is either a leaf (`leaf?` is true and the whole value is selected) or
+  has `children`, a nested `JsonMask::SelectionTree`.
+- `selection_for(key)` returns what the projector applies to a key (`String` or `Symbol`): the
+  named selection merged with the wildcard, the wildcard alone for a key that is not named, or
+  `nil` when the key is not selected.
+
+Blank selectors compile to a mask that passes values through, and its `selection_tree` is `nil`.
+
+This is enough to add schema-aware validation. For example, to list the selected paths that a
+JSON-Schema-style hash does not declare:
+
+```ruby
+def undeclared_paths(tree, schema, path = [])
+  schema = schema["items"] if schema["type"] == "array"
+  properties = schema.fetch("properties", {})
+
+  tree.named.flat_map do |name, selection|
+    property = properties[name]
+    next [(path + [name]).join("/")] unless property
+    next [] if selection.leaf?
+
+    undeclared_paths(selection.children, property, path + [name])
+  end
+end
+
+schema = {
+  "type" => "object",
+  "properties" => {
+    "id" => {"type" => "string"},
+    "permissions" => {
+      "type" => "array",
+      "items" => {"type" => "object", "properties" => {"role" => {"type" => "string"}}}
+    }
+  }
+}
+
+tree = JsonMask.compile("id,permissions(role,email),owner/name").selection_tree
+undeclared_paths(tree, schema)
+# => ["permissions/email", "owner"]
+```
 
 ## Compatibility
 

data/lib/json-mask.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-# Entry file matching the gem name, so Bundler's default require
-# (`gem "json-mask"`) resolves without an explicit `require:` option.
+# Bundler's default require for `gem "json-mask"` looks for this file name.
 require_relative 'json_mask'

data/lib/json_mask/compiled_mask.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
 module JsonMask
-  # An immutable, reusable field selector.
   class CompiledMask
     attr_reader :fields
 
+    # nil for a blank selector, which passes values through unchanged.
+    attr_reader :selection_tree
+
     def initialize(fields, selection_tree)
       @fields = fields&.dup&.freeze
       @selection_tree = selection_tree
       freeze
     end
 
-    # Filters a JSON-compatible value using this selector.
-    #
-    # @param value [Hash, Array] response data to filter
-    # @return [Hash, Array, nil] a structural subset of value
     def call(value)
       return value unless @selection_tree
 

data/lib/json_mask/error.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module JsonMask
-  # Raised when a field selector does not conform to the supported grammar.
   class ParseError < ArgumentError
     attr_reader :expression, :offset, :reason
 
@@ -14,7 +13,7 @@ module JsonMask
     end
   end
 
-  # Raised when a field selector exceeds a configured parser limit.
+  # A ParseError subclass so one rescue covers malformed and oversized selectors.
   class LimitError < ParseError
   end
 end

data/lib/json_mask/parser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module JsonMask
-  # Compiles a field selector string into an immutable selection tree.
   class Parser
     DEFAULT_MAX_LENGTH = 16_384
     DEFAULT_MAX_DEPTH = 64

data/lib/json_mask/projector.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module JsonMask
-  # Applies a compiled selection tree to Hash and Array values.
   module Projector
     MISSING = Object.new.freeze
 
@@ -19,9 +18,8 @@ module JsonMask
       when Array
         project_array(value, selection_tree)
       when nil
-        # JSON null is a value, not a shape mismatch: a nested selection into
-        # null keeps the null (matching the reference implementation), so a
-        # nullable field stays distinguishable from an unselected one.
+        # Keep nulls, as the reference implementation does, so a nullable
+        # field stays distinguishable from an unselected one.
         nil
       else
         MISSING

data/lib/json_mask/selection_tree.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module JsonMask
-  # Represents either a complete field or a field with nested selections.
   class Selection
     attr_reader :children
 
@@ -18,6 +17,7 @@ module JsonMask
       children.nil?
     end
 
+    # A leaf already selects the whole value, so it absorbs any nested selection.
     def merge(other)
       return self.class.leaf if leaf? || other.leaf?
 
@@ -25,7 +25,6 @@ module JsonMask
     end
   end
 
-  # Stores named and wildcard selections, merging repeated selections by union.
   class SelectionTree
     attr_reader :named, :wildcard
 
@@ -57,6 +56,8 @@ module JsonMask
       )
     end
 
+    # Unlike `named`, folds the wildcard's nested selections into each named
+    # selection; unnamed fields get the wildcard itself.
     def selection_for(key)
       @effective_named.fetch(key.to_s, wildcard)
     end

data/lib/json_mask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonMask
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/json_mask.rb

@@ -7,25 +7,14 @@ require_relative 'json_mask/parser'
 require_relative 'json_mask/projector'
 require_relative 'json_mask/compiled_mask'
 
-# Filters JSON-compatible Ruby values using Google partial-response selectors.
 module JsonMask
   class << self
-    # Filters a JSON-compatible value with a field selector.
-    #
-    # @param value [Hash, Array] response data to filter
-    # @param fields [String, nil] fields selector; blank values pass through unchanged
-    # @return [Hash, Array, nil] a structural subset of value
     def call(value, fields, **options)
       compile(fields, **options).call(value)
     end
 
     alias mask call
 
-    # Compiles a selector for reuse across multiple values.
-    #
-    # @return [CompiledMask] an immutable selector
-    # @raise [ParseError] if the selector is malformed
-    # @raise [LimitError] if the selector exceeds a configured limit
     def compile(
       fields,
       max_length: Parser::DEFAULT_MAX_LENGTH,
@@ -43,5 +32,5 @@ module JsonMask
     end
   end
 
-  private_constant :Parser, :Projector, :Selection, :SelectionTree
+  private_constant :Parser, :Projector
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json-mask
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Robert Sheldon