json-mask 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b68741ab4daac730737fe2b7a0f0550409d981fe7535619d2c2655a1c1a9beba
+  data.tar.gz: f65a88df55f70fcb6c2af28f97a805a0dd2a0fbd34c4d2d0975b685946ef1d53
+SHA512:
+  metadata.gz: 46daa73f26f18e75dc6f1cc83232e33a047326801f38807c5fa2df8f16c94fdebef63778a2acce086aeb75446cb613d700d5f11dc4c9b09f7aa3e2c088b83189
+  data.tar.gz: 1ef0a561a43eb13ca3e877a7f1dde1590125fb38ff51d609e35f0bc8ee119278144cb3575cbaea19af14e08bcb742c6d183886dfe9f21edf270c9edc7981bb43

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Implement Google partial-response and JSON Mask field selectors.
+- Support comma-separated fields, slash paths, sub-selections, wildcards, and escaping.
+- Add reusable compiled masks and parser resource limits.
+- Add a `json-mask` entry file so Bundler's default require works without a `require:` option.
+- Preserve `nil` values under nested selections, matching the reference implementation.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Sheldon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# JSON Mask for Ruby
+
+[![CI](https://github.com/wistia/json-mask-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/wistia/json-mask-ruby/actions/workflows/ci.yml)
+
+`json-mask` selects fields from JSON-compatible Ruby objects while preserving the shape of the
+response. It implements the field selector language used by Google's partial responses and the
+[JSON Mask](https://github.com/nemtsov/json-mask) project.
+
+The library has no runtime dependencies.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "json-mask"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+```ruby
+require "json_mask"
+
+response = {
+  "id" => "abc123",
+  "name" => "Product demo",
+  "permissions" => [
+    {"id" => "owner", "role" => "owner", "email" => "owner@example.com"}
+  ]
+}
+
+JsonMask.call(response, "id,permissions(id,role)")
+# => {
+#      "id" => "abc123",
+#      "permissions" => [{"id" => "owner", "role" => "owner"}]
+#    }
+```
+
+`JsonMask.mask` is an alias for `JsonMask.call`.
+
+Compile selectors that will be reused:
+
+```ruby
+mask = JsonMask.compile("id,name,permissions(role)")
+
+mask.call(first_response)
+mask.call(second_response)
+```
+
+Compiled masks are immutable and safe to share between threads.
+
+Passing `nil`, an empty string, or a whitespace-only string returns the original value unchanged.
+This makes an optional HTTP `fields` parameter straightforward:
+
+```ruby
+render json: JsonMask.call(payload, params[:fields])
+```
+
+## Selector syntax
+
+The syntax is loosely based on XPath:
+
+| Selector | Meaning |
+| --- | --- |
+| `id,name` | Select multiple fields |
+| `permissions/role` | Select a nested field |
+| `permissions(id,role)` | Select multiple fields from an object or each object in an array |
+| `permissions/*` | Select every field below `permissions` |
+| `items/*/id` | Select `id` from every value below `items` |
+
+Slash paths and parenthesized sub-selections traverse arrays transparently. Empty hashes remain in
+arrays, preserving their positions. Missing fields are omitted.
+
+Backslash escapes structural characters in field names:
+
+```ruby
+JsonMask.call({"a/b" => 1, "other" => 2}, 'a\/b')
+# => {"a/b" => 1}
+
+JsonMask.call({"*" => 1, "other" => 2}, '\\*')
+# => {"*" => 1}
+```
+
+The structural characters are `,`, `/`, `(`, `)`, `*`, and `\\`. An asterisk is a wildcard only
+when it is the entire, unescaped field name. Unescaped whitespace around field names and operators
+is ignored; whitespace inside a field name is preserved.
+
+String and symbol hash keys are supported, and the result preserves the key objects from the input.
+The input is never mutated.
+
+## Invalid selectors and limits
+
+Malformed selectors raise `JsonMask::ParseError`, which includes the original expression and the
+zero-based character offset:
+
+```ruby
+JsonMask.compile("files(id,,name)")
+# raises JsonMask::ParseError: expected a field name at offset 9
+```
+
+The parser applies conservative defaults suitable for accepting selectors from HTTP or MCP clients:
+
+- Maximum selector length: 16,384 bytes
+- Maximum nesting depth: 64
+- Maximum field selectors: 1,000
+
+The limits can be tightened for a specific boundary:
+
+```ruby
+JsonMask.compile(fields, max_length: 1_024, max_depth: 16, max_selectors: 100)
+```
+
+Exceeding a limit raises `JsonMask::LimitError`, a subclass of `JsonMask::ParseError`.
+
+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.
+
+## Compatibility
+
+The supported grammar follows the [Google Drive `fields` parameter rules](https://developers.google.com/workspace/drive/api/guides/fields-parameter)
+and JSON Mask's documented grammar. This library intentionally validates malformed expressions
+instead of attempting to recover from them.
+
+The projector accepts JSON-compatible `Hash` and `Array` values. If a selected field contains a
+scalar where the selector asks for nested fields, that field is omitted — except `nil`, which
+passes through unchanged (matching the reference implementation), so a nullable field stays
+distinguishable from an unselected one. A non-container root value with a non-empty selector
+produces `nil`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+```
+
+The default Rake task runs the full test suite and RuboCop.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/json-mask.rb

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

data/lib/json_mask/compiled_mask.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JsonMask
+  # An immutable, reusable field selector.
+  class CompiledMask
+    attr_reader :fields
+
+    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
+
+      Projector.call(value, @selection_tree)
+    end
+
+    alias filter call
+  end
+end

data/lib/json_mask/error.rb

@@ -0,0 +1,20 @@
+# 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
+
+    def initialize(reason, expression:, offset:)
+      @reason = reason
+      @expression = expression
+      @offset = offset
+
+      super("#{reason} at offset #{offset}")
+    end
+  end
+
+  # Raised when a field selector exceeds a configured parser limit.
+  class LimitError < ParseError
+  end
+end

data/lib/json_mask/parser.rb

@@ -0,0 +1,189 @@
+# 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
+    DEFAULT_MAX_SELECTORS = 1_000
+
+    TERMINALS = [',', '/', '(', ')'].freeze
+    WHITESPACE = [' ', "\t", "\n", "\r"].freeze
+
+    def initialize(expression, max_length:, max_depth:, max_selectors:)
+      validate_expression!(expression)
+      validate_limit!(:max_length, max_length)
+      validate_limit!(:max_depth, max_depth)
+      validate_limit!(:max_selectors, max_selectors)
+
+      @expression = expression
+      @max_length = max_length
+      @max_depth = max_depth
+      @max_selectors = max_selectors
+    end
+
+    def parse
+      return if @expression.nil?
+
+      enforce_length!
+      return if @expression.strip.empty?
+
+      @characters = @expression.each_char.to_a
+      @index = 0
+      @selector_count = 0
+      parse_list(depth: 1)
+    end
+
+    private
+
+    def parse_list(depth:, terminator: nil)
+      tree = SelectionTree.empty
+      expect_selection!(terminator)
+
+      loop do
+        tree = tree.merge(parse_selection(depth))
+        skip_whitespace
+
+        break if finish_list?(terminator)
+
+        expect_character!(',')
+        advance
+        expect_selection!(terminator)
+      end
+
+      tree
+    end
+
+    def parse_selection(depth)
+      enforce_depth!(depth)
+      name, wildcard = parse_name
+      count_selector!
+      skip_whitespace
+
+      children = case current_character
+                 when '/'
+                   advance
+                   parse_selection(depth + 1)
+                 when '('
+                   advance
+                   parse_list(depth: depth + 1, terminator: ')')
+                 end
+
+      SelectionTree.single(name:, wildcard:, children:)
+    end
+
+    def parse_name
+      skip_whitespace
+      entries = []
+
+      while current_character && !TERMINALS.include?(current_character)
+        entries << next_name_character
+      end
+
+      entries.pop while trailing_whitespace?(entries.last)
+      parse_error!('expected a field name') if entries.empty?
+
+      name = entries.map(&:first).join
+      wildcard = entries == [['*', false]]
+      [name, wildcard]
+    end
+
+    def next_name_character
+      character = current_character
+      unless character == '\\'
+        advance
+        return [character, false]
+      end
+
+      advance
+      return ['\\', false] unless current_character
+
+      character = current_character
+      advance
+      [character, true]
+    end
+
+    def finish_list?(terminator)
+      if terminator && current_character == terminator
+        advance
+        return true
+      end
+
+      return true if current_character.nil? && terminator.nil?
+
+      parse_error!("expected #{terminator.inspect}") if current_character.nil?
+      false
+    end
+
+    def expect_selection!(terminator)
+      skip_whitespace
+      unless current_character.nil? || current_character == ',' || current_character == terminator
+        return
+      end
+
+      parse_error!('expected a field name')
+    end
+
+    def expect_character!(expected)
+      return if current_character == expected
+
+      parse_error!("expected #{expected.inspect}")
+    end
+
+    def skip_whitespace
+      advance while WHITESPACE.include?(current_character)
+    end
+
+    def trailing_whitespace?(entry)
+      entry && !entry.last && WHITESPACE.include?(entry.first)
+    end
+
+    def current_character
+      @characters[@index]
+    end
+
+    def advance
+      @index += 1
+    end
+
+    def count_selector!
+      @selector_count += 1
+      return if @selector_count <= @max_selectors
+
+      limit_error!("selector contains more than #{@max_selectors} fields")
+    end
+
+    def enforce_length!
+      return if @expression.bytesize <= @max_length
+
+      limit_error!("selector is longer than #{@max_length} bytes", offset: 0)
+    end
+
+    def enforce_depth!(depth)
+      return if depth <= @max_depth
+
+      limit_error!("selector nesting is deeper than #{@max_depth}")
+    end
+
+    def validate_expression!(expression)
+      return if expression.nil?
+
+      raise TypeError, 'fields must be a String or nil' unless expression.is_a?(String)
+      raise ArgumentError, 'fields must use valid UTF-8' unless expression.valid_encoding?
+    end
+
+    def validate_limit!(name, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive Integer"
+    end
+
+    def parse_error!(reason, offset: @index)
+      raise ParseError.new(reason, expression: @expression, offset:)
+    end
+
+    def limit_error!(reason, offset: @index || 0)
+      raise LimitError.new(reason, expression: @expression, offset:)
+    end
+  end
+end

data/lib/json_mask/projector.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module JsonMask
+  # Applies a compiled selection tree to Hash and Array values.
+  module Projector
+    MISSING = Object.new.freeze
+
+    module_function
+
+    def call(value, selection_tree)
+      projected = project(value, selection_tree)
+      projected.equal?(MISSING) ? nil : projected
+    end
+
+    def project(value, selection_tree)
+      case value
+      when Hash
+        project_hash(value, selection_tree)
+      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.
+        nil
+      else
+        MISSING
+      end
+    end
+
+    def project_hash(value, selection_tree)
+      value.each_with_object({}) do |(key, field_value), result|
+        selection = selection_tree.selection_for(key)
+        next unless selection
+
+        projected = selection.leaf? ? field_value : project(field_value, selection.children)
+        result[key] = projected unless projected.equal?(MISSING)
+      end
+    end
+
+    def project_array(value, selection_tree)
+      value.each_with_object([]) do |item, result|
+        projected = project(item, selection_tree)
+        result << projected unless projected.equal?(MISSING)
+      end
+    end
+  end
+end

data/lib/json_mask/selection_tree.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module JsonMask
+  # Represents either a complete field or a field with nested selections.
+  class Selection
+    attr_reader :children
+
+    def self.leaf
+      @leaf ||= new
+    end
+
+    def initialize(children = nil)
+      @children = children
+      freeze
+    end
+
+    def leaf?
+      children.nil?
+    end
+
+    def merge(other)
+      return self.class.leaf if leaf? || other.leaf?
+
+      self.class.new(children.merge(other.children))
+    end
+  end
+
+  # Stores named and wildcard selections, merging repeated selections by union.
+  class SelectionTree
+    attr_reader :named, :wildcard
+
+    def self.empty
+      @empty ||= new
+    end
+
+    def self.single(name:, wildcard:, children: nil)
+      selection = children ? Selection.new(children) : Selection.leaf
+
+      if wildcard
+        new(wildcard: selection)
+      else
+        new(named: { name => selection })
+      end
+    end
+
+    def initialize(named: {}, wildcard: nil)
+      @named = named.freeze
+      @wildcard = wildcard
+      @effective_named = effective_named.freeze
+      freeze
+    end
+
+    def merge(other)
+      self.class.new(
+        named: named.merge(other.named) { |_name, left, right| left.merge(right) },
+        wildcard: merge_wildcards(other)
+      )
+    end
+
+    def selection_for(key)
+      @effective_named.fetch(key.to_s, wildcard)
+    end
+
+    private
+
+    def effective_named
+      return named unless wildcard
+
+      named.transform_values { |selection| selection.merge(wildcard) }
+    end
+
+    def merge_wildcards(other)
+      return other.wildcard unless wildcard
+      return wildcard unless other.wildcard
+
+      wildcard.merge(other.wildcard)
+    end
+  end
+end

data/lib/json_mask/version.rb

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

data/lib/json_mask.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative 'json_mask/version'
+require_relative 'json_mask/error'
+require_relative 'json_mask/selection_tree'
+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,
+      max_depth: Parser::DEFAULT_MAX_DEPTH,
+      max_selectors: Parser::DEFAULT_MAX_SELECTORS
+    )
+      selection_tree = Parser.new(
+        fields,
+        max_length:,
+        max_depth:,
+        max_selectors:
+      ).parse
+
+      CompiledMask.new(fields, selection_tree)
+    end
+  end
+
+  private_constant :Parser, :Projector, :Selection, :SelectionTree
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: json-mask
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Sheldon
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A dependency-free implementation of the Google partial-response and JSON Mask fields
+  language for filtering Hash and Array response data.
+email:
+- rsheldon@wistia.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/json-mask.rb
+- lib/json_mask.rb
+- lib/json_mask/compiled_mask.rb
+- lib/json_mask/error.rb
+- lib/json_mask/parser.rb
+- lib/json_mask/projector.rb
+- lib/json_mask/selection_tree.rb
+- lib/json_mask/version.rb
+homepage: https://github.com/wistia/json-mask-ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/wistia/json-mask-ruby/issues
+  changelog_uri: https://github.com/wistia/json-mask-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/json-mask
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/wistia/json-mask-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Select fields from JSON-compatible Ruby objects without changing their shape
+test_files: []