versponse 0.1.0 → 0.2.0

data/lib/versponse/steps/nested.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # Renders a nested object, or each item of a collection, with a child plan
+    #
+    # @api private
+    class Nested
+      # @return [String] output key
+      attr_reader :key
+
+      # @param key [String] output key
+      # @param extractor [#call] value reader
+      # @param condition [Versponse::Condition, nil] if:/unless:
+      # @param plan [#call] child plan
+      # @param collection [Boolean] render each item
+      # @param collapsed_plan [#call, nil] plan used when the association is expandable and not expanded
+      # @param collapse_if [#call, nil] the referenced identifier's condition; when it is false for the value
+      #   (for a collection: for any item) the full plan is used instead of collapsed_plan
+      # @param nil_fails [Boolean] in a validating plan, a nil value fails its schema (see InlineValidation)
+      # @param context_override [#call, nil] computes the subtree's context from (object, context)
+      def initialize(key:, extractor:, condition:, plan:, collection:, collapsed_plan: nil, collapse_if: nil, nil_fails: false, context_override: nil)
+        @key = key
+        @extractor = extractor
+        @condition = condition
+        @plan = plan
+        @collection = collection
+        @collapsed_plan = collapsed_plan
+        @collapse_if = collapse_if
+        @nil_fails = nil_fails
+        @context_override = context_override
+        freeze
+      end
+
+      # @return [Boolean] true with if:/unless:
+      def conditional?
+        !@condition.nil?
+      end
+
+      # @return [Boolean] true when each item of a collection is rendered
+      def collection?
+        @collection
+      end
+
+      # @return [Array<#call>] the child plan, and the collapsed plan when there is one
+      def plans
+        [@plan, @collapsed_plan].compact
+      end
+
+      # @param plan [#call] child plan
+      # @param collapsed_plan [#call, nil] plan used when collapsed
+      # @param nil_fails [Boolean] a nil value fails validation (validating plans only)
+      # @return [Nested] the same step rendering with these plans
+      def with_plans(plan:, collapsed_plan:, nil_fails: false)
+        self.class.new(key: @key, extractor: @extractor, condition: @condition, plan:, collection: @collection,
+          collapsed_plan:, collapse_if: @collapse_if, nil_fails:, context_override: @context_override)
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param expansion [Versponse::Expansion] expand tree node of the parent
+      # @return [void]
+      # @raise [Versponse::ExtractionError] with the item index in its keys when a collection item fails
+      def call(object, hash, context, output, expansion)
+        return if @condition && !@condition.call(object, context)
+
+        value = @extractor.call(object, hash, context)
+        output[@key] = if value.nil?
+          InlineValidation.failed! if @nil_fails
+          nil
+        else
+          context = @context_override.call(object, context) if @context_override
+          # Errors from the child plans are marked, so only an explicit association policy recovers them
+          begin
+            collapse = @collapsed_plan && !expansion.expand?(@key) && (@collapse_if.nil? || collapse?(value, context))
+            plan = collapse ? @collapsed_plan : @plan
+            node = expansion.child(@key)
+            @collection ? Collections.map(Collections.items(value)) { |item| plan.call(item, context, node) } : plan.call(value, context, node)
+          rescue => e
+            ErrorPolicy.mark_nested!(e)
+            raise
+          end
+        end
+      end
+
+      private
+
+      # A collection collapses only when every item passes, so its items share one shape
+      def collapse?(value, context)
+        return @collapse_if.call(value, context) unless @collection
+
+        Collections.items(value).all? { |item| @collapse_if.call(item, context) }
+      end
+    end
+  end
+end

data/lib/versponse/steps/one_of.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # Renders a value with the plan of the variant its dispatcher picks
+    #
+    # @api private
+    class OneOf
+      # @return [String] output key
+      attr_reader :key
+
+      # @param key [String] output key
+      # @param extractor [#call] value reader
+      # @param condition [Versponse::Condition, nil] if:/unless:
+      # @param dispatcher [Versponse::VariantDispatcher] variant matching
+      # @param collapsed_dispatcher [Versponse::VariantDispatcher, nil] matching to collapsed variants (expandable one_of)
+      # @param context_override [#call, nil] computes the variants' context from (object, context)
+      def initialize(key:, extractor:, condition:, dispatcher:, collapsed_dispatcher: nil, context_override: nil)
+        @key = key
+        @extractor = extractor
+        @condition = condition
+        @dispatcher = dispatcher
+        @collapsed_dispatcher = collapsed_dispatcher
+        @context_override = context_override
+        freeze
+      end
+
+      # @return [Boolean] true with if:/unless:
+      def conditional?
+        !@condition.nil?
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param expansion [Versponse::Expansion] expand tree node of the parent
+      # @return [void]
+      # @raise [KeyError] when no variant matches (the plan wraps it in an ExtractionError)
+      def call(object, hash, context, output, expansion)
+        return if @condition && !@condition.call(object, context)
+
+        value = @extractor.call(object, hash, context)
+        return output[@key] = nil if value.nil?
+
+        context = @context_override.call(object, context) if @context_override
+        dispatcher = (@collapsed_dispatcher && !expansion.expand?(@key)) ? @collapsed_dispatcher : @dispatcher
+        output[@key] = dispatch(dispatcher, value, context, expansion.child(@key))
+      end
+
+      private
+
+      # Errors from the variant plans (and a value matching no variant) are marked like a nested step's
+      def dispatch(dispatcher, value, context, node)
+        dispatcher.call(value, context, node)
+      rescue => e
+        ErrorPolicy.mark_nested!(e)
+        raise
+      end
+    end
+  end
+end

data/lib/versponse/steps/read.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # A plain field: reads a method or Hash key and formats it, with no condition, block or path.
+    # The common case, without Value's extractor and condition layers.
+    #
+    # @api private
+    class Read
+      # @return [String] output key
+      attr_reader :key
+
+      # @param key [String] output key
+      # @param name [String, Symbol] method or Hash key to read
+      # @param formatter [#call, nil] applied to non-nil values
+      def initialize(key:, name:, formatter: nil)
+        @key = key
+        @symbol = name.to_sym
+        @string = name.to_s.freeze
+        @formatter = formatter
+        freeze
+      end
+
+      # @param check [#valid?] checker of the property's schema
+      # @param recheck [Boolean] check an unfrozen value again after the render
+      # @return [CheckedRead] the same read, checking what it writes
+      def checked(check, recheck:)
+        CheckedRead.new(key: @key, name: @string, formatter: @formatter, check:, recheck:)
+      end
+
+      # @return [Boolean] false: a read has no if:/unless:
+      def conditional?
+        false
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param _context [Hash] unused
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      # @raise [KeyError] when a Hash has neither key; NoMethodError when an object has no such method
+      def call(object, hash, _context, output, _expansion)
+        output[@key] = hash ? object.fetch(@symbol) { object.fetch(@string) } : object.public_send(@symbol)
+      end
+    end
+  end
+end

data/lib/versponse/steps/read_formatted.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Steps
+    # A plain field with a formatter, applied to non-nil values
+    #
+    # @api private
+    class ReadFormatted < Read
+      # @param check [#valid?] checker of the property's schema
+      # @param recheck [Boolean] check an unfrozen value again after the render
+      # @return [CheckedReadFormatted] the same read, checking the formatted value it writes
+      def checked(check, recheck:)
+        CheckedReadFormatted.new(key: @key, name: @string, formatter: @formatter, check:, recheck:)
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param _context [Hash] unused
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, hash, _context, output, _expansion)
+        value = hash ? object.fetch(@symbol) { object.fetch(@string) } : object.public_send(@symbol)
+        output[@key] = value.nil? ? nil : @formatter.call(value)
+      end
+    end
+  end
+end

data/lib/versponse/steps/value.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Compiled operations a plan runs for each property
+  module Steps
+    # Writes one extracted value, formatted when a formatter is bound
+    #
+    # @api private
+    class Value
+      # @return [String] output key
+      attr_reader :key
+
+      # @param key [String] output key
+      # @param extractor [#call] value reader
+      # @param condition [Versponse::Condition, nil] if:/unless:
+      # @param formatter [#call, nil] applied to non-nil values
+      def initialize(key:, extractor:, condition:, formatter:)
+        @key = key
+        @extractor = extractor
+        @condition = condition
+        @formatter = formatter
+        freeze
+      end
+
+      # @param check [#valid?] checker of the property's schema
+      # @param recheck [Boolean] check an unfrozen value again after the render
+      # @return [CheckedValue] the same step, checking what it writes
+      def checked(check, recheck:)
+        CheckedValue.new(key: @key, extractor: @extractor, condition: @condition, formatter: @formatter, check:, recheck:)
+      end
+
+      # @return [Boolean] true with if:/unless:
+      def conditional?
+        !@condition.nil?
+      end
+
+      # @param object [Object] source
+      # @param hash [Boolean] whether the source is a Hash
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @param _expansion [Versponse::Expansion] unused
+      # @return [void]
+      def call(object, hash, context, output, _expansion)
+        return if @condition && !@condition.call(object, context)
+
+        value = @extractor.call(object, hash, context)
+        value = @formatter.call(value) if @formatter && !value.nil?
+        output[@key] = value
+      end
+    end
+  end
+end

data/lib/versponse/supported_versions.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Inclusive range of versions a response class serves, declared with supported_versions.
+  # Versions are compared with config.version_resolver, so the range uses the same order as
+  # resolution (string order by default, where "preview" sorts after dated versions).
+  #
+  # @api private
+  class SupportedVersions
+    # @return [String, nil] first supported version, nil to start at the first declared version
+    attr_reader :min
+    # @return [String, nil] last supported version, nil for no upper bound
+    attr_reader :max
+
+    # The resolver picks earlier for a request of later only when earlier sorts at or before it
+    #
+    # @param earlier [String] version expected first
+    # @param later [String] version expected second
+    # @return [Boolean] true when earlier sorts at or before later
+    def self.at_or_before?(earlier, later)
+      Versponse.configuration.version_resolver.call(later, [earlier]) == earlier
+    end
+
+    # @param min [String, nil] first supported version (inclusive)
+    # @param max [String, nil] last supported version (inclusive)
+    # @raise [Versponse::DefinitionError] when min sorts after max
+    def initialize(min:, max:)
+      @min = min&.to_s
+      @max = max&.to_s
+      raise DefinitionError, "supported_versions min: #{@min} is after max: #{@max}" if @min && @max && !self.class.at_or_before?(@min, @max)
+
+      freeze
+    end
+
+    # Without min, earlier versions are left to the resolver, which finds nothing before the first declared one
+    #
+    # @param version [String] version name
+    # @return [Boolean] true when the range includes the version
+    def covers?(version)
+      (min.nil? || self.class.at_or_before?(min, version)) && (max.nil? || self.class.at_or_before?(version, max))
+    end
+
+    # Only max is checked: declared blocks don't have to be inside the range, so min: "preview"
+    # with a single version "2025-09" block serves "preview" from 2025-09
+    #
+    # @param declared [Array<String>] declared version names, oldest first
+    # @param owner [String] class name, for the message
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when max sorts before every declared version, so no request could resolve
+    def check!(declared, owner)
+      return if max.nil? || declared.empty? || declared.any? { |version| self.class.at_or_before?(version, max) }
+
+      raise DefinitionError, "#{owner}: supported_versions max: #{max} is before every declared version (#{declared.join(", ")})"
+    end
+
+    # @return [String] the range for messages, like "min: 2025-09, max: none"
+    def to_s
+      "min: #{min || "first declared"}, max: #{max || "none"}"
+    end
+  end
+end

data/lib/versponse/validator/all.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # Combines the checkers of one schema; all must pass
+    #
+    # @api private
+    class All
+      # @param checkers [Array<#valid?>] checkers of one schema
+      # @return [#valid?] VALID for none, the checker itself for one, else an All
+      def self.for(checkers)
+        return Constant::VALID if checkers.empty?
+        return checkers.first if checkers.one?
+        return Both.new(*checkers) if checkers.size == 2
+
+        new(checkers)
+      end
+
+      # @param checkers [Array<#valid?>] two or more checkers
+      def initialize(checkers)
+        @checkers = checkers.freeze
+        freeze
+      end
+
+      # @param data [Object] value to check
+      # @return [Boolean] true when every checker passes
+      def valid?(data)
+        @checkers.all? { |checker| checker.valid?(data) }
+      end
+    end
+  end
+end

data/lib/versponse/validator/array_check.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # items, minItems and maxItems
+    #
+    # @api private
+    class ArrayCheck
+      # @return [Array<String>] keywords this check owns
+      def self.keywords = %w[items minItems maxItems]
+
+      # @return [Class] the class a type folded into this check requires
+      def self.shape = Array
+
+      # @param schema [Hash] schema
+      # @param compiler [Versponse::Validator::Compiler] compiles the items schema
+      # @return [ArrayCheck, nil] the check, nil without array keywords
+      def self.build(schema, compiler)
+        return unless keywords.any? { |keyword| schema.key?(keyword) }
+
+        new(compiler.compile(schema.fetch("items", true)), Range.new(schema["minItems"], schema["maxItems"]))
+      end
+
+      # @param items [#valid?] checker of every item
+      # @param sizes [Range] allowed number of items
+      # @param strict [Boolean] true when anything but an Array fails (type: "array" folded in)
+      def initialize(items, sizes, strict: false)
+        @items = items
+        @sizes = sizes
+        @strict = strict
+        freeze
+      end
+
+      # @return [ArrayCheck] the same check, failing anything but an Array
+      def strict
+        self.class.new(@items, @sizes, strict: true)
+      end
+
+      # @param data [Object] value to check; anything but an Array passes unless strict
+      # @return [Boolean] true when the Array matches
+      def valid?(data)
+        return !@strict unless data.is_a?(Array)
+
+        @sizes.cover?(data.size) && data.all? { |item| @items.valid?(item) }
+      end
+    end
+  end
+end

data/lib/versponse/validator/boolean_check.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # type: boolean, compared with == as json_schemer does
+    #
+    # @api private
+    class BooleanCheck
+      # @param data [Object] value to check
+      # @return [Boolean] true when data is true or false
+      def valid?(data)
+        data == true || data == false
+      end
+    end
+  end
+end

data/lib/versponse/validator/both.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # Two checkers, called without an Array loop (the common case: a type and one other check)
+    #
+    # @api private
+    class Both
+      # @param first [#valid?] first checker
+      # @param second [#valid?] second checker
+      def initialize(first, second)
+        @first = first
+        @second = second
+        freeze
+      end
+
+      # @param data [Object] value to check
+      # @return [Boolean] true when both checkers accept data
+      def valid?(data)
+        @first.valid?(data) && @second.valid?(data)
+      end
+    end
+  end
+end

data/lib/versponse/validator/class_check.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # A type check that is one class test (only number, string, array, object, or integer where only Integers count)
+    #
+    # @api private
+    class ClassCheck
+      # @return [Class] the class data must be
+      attr_reader :klass
+
+      # @param klass [Class] the class data must be
+      def initialize(klass)
+        @klass = klass
+        freeze
+      end
+
+      # @param data [Object] value to check
+      # @return [Boolean] true when data is of the class
+      def valid?(data)
+        data.is_a?(@klass)
+      end
+    end
+  end
+end

data/lib/versponse/validator/closed_object_check.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # An object with additionalProperties: false whose required keys are all declared properties: each declared key
+    # is fetched and checked, and a count of the present ones equal to the Hash size proves there are no others
+    #
+    # @api private
+    class ClosedObjectCheck
+      # Marks a declared key the Hash doesn't have
+      MISSING = Object.new.freeze
+      private_constant :MISSING
+
+      # @return [Class] the class a type folded into this check requires
+      def self.shape = Hash
+
+      # @param properties [Hash{String => #valid?}] checkers of the declared properties
+      # @param required [Array<String>] required keys, all of them declared properties
+      # @param sizes [Range] allowed number of properties
+      # @param strict [Boolean] true when anything but a Hash fails (type: "object" folded in)
+      def initialize(properties:, required:, sizes:, strict: false)
+        @properties = properties
+        @required_keys = required
+        @keys = properties.keys.freeze
+        @checks = properties.values.freeze
+        @required = @keys.map { |key| required.include?(key) }.freeze
+        @sizes = sizes
+        @strict = strict
+        freeze
+      end
+
+      # @return [ClosedObjectCheck] the same check, failing anything but a Hash
+      def strict
+        self.class.new(properties: @properties, required: @required_keys, sizes: @sizes, strict: true)
+      end
+
+      # @param data [Object] value to check; anything but a Hash passes unless strict
+      # @return [Boolean] true when the Hash matches
+      def valid?(data)
+        return !@strict unless data.is_a?(Hash)
+
+        found = 0
+        index = 0
+        while index < @keys.size
+          value = data.fetch(@keys[index], MISSING)
+          if MISSING.equal?(value)
+            return reject(data) if @required[index]
+          else
+            return reject(data) unless @checks[index].valid?(value)
+
+            found += 1
+          end
+          index += 1
+        end
+        (found == data.size && @sizes.cover?(found)) || reject(data)
+      end
+
+      private
+
+      # json_schemer reads Symbol keys as Strings, so a false is certain only for a Hash with String keys; one with
+      # Symbol keys is checked again with their Strings, and any other Hash throws {Root::DEFER}
+      #
+      # @param data [Hash] value being checked
+      # @return [Boolean] false, or the answer for the Hash with String keys
+      def reject(data)
+        data.each_key do |key|
+          next if key.is_a?(String)
+
+          strings = StringKeys.call(data)
+          throw Root::DEFER unless strings
+
+          return valid?(strings)
+        end
+        false
+      end
+    end
+  end
+end

data/lib/versponse/validator/combinator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # anyOf, oneOf and allOf
+    #
+    # @api private
+    class Combinator
+      # Keywords and the Enumerable predicate each applies to its branches
+      MODES = {"anyOf" => :any?, "oneOf" => :one?, "allOf" => :all?}.freeze
+
+      # @return [Array<String>] keywords this check owns
+      def self.keywords = MODES.keys
+
+      # @param schema [Hash] schema
+      # @param compiler [Versponse::Validator::Compiler] compiles the branches
+      # @return [#valid?, nil] the check, nil without combinators
+      def self.build(schema, compiler)
+        combinators = MODES.filter_map do |keyword, mode|
+          new(schema[keyword].map { |branch| compiler.compile(branch) }, mode) if schema.key?(keyword)
+        end
+        All.for(combinators) unless combinators.empty?
+      end
+
+      # @param branches [Array<#valid?>] checkers of the branches
+      # @param mode [Symbol] :any?, :one? or :all?
+      def initialize(branches, mode)
+        @branches = branches.freeze
+        @mode = mode
+        freeze
+      end
+
+      # @param data [Object] value to check
+      # @return [Boolean] true when the branches match as the mode requires
+      def valid?(data)
+        @branches.public_send(@mode) { |branch| branch.valid?(data) }
+      end
+    end
+  end
+end