parametric 0.2.21 → 0.2.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61eb99562317fd43b8ea59c1ed4e48c13320ff04334d372c07b5c78efe7ebd22
-  data.tar.gz: ee09741be15edf7ff3082b285ae16549029e995eb5841518e7f4394f5c131049
+  metadata.gz: e4c6ddb5aba085ae7a2c3d0adf46164ecaf9bf3d3e7d6a0ec6891d48a0af0b77
+  data.tar.gz: 3612f9a678802ed4353d964734932951fb5a09fdceaf52eca76090907210a225
 SHA512:
-  metadata.gz: 9c994b498b30870bb501890ecb44fe007d8ea49ae0ab2737033b70388ba36036b12a6795cf392a712e8b2d5121aa86e875280c080cf9a4ac4af953db2784c1fd
-  data.tar.gz: 55e8c26767574c8090d144465c23be6fe0a170470f736173cbde5beb059a8adcd1ca4aa52ad9a56038bc487b00e4595e7257d31ad84227df5720fe276c964012
+  metadata.gz: 7181f7d9cd318fb362ab77a6bc9da5b9bf6bc41373b6de6d8e3e41ddb92d23b9a2a46c073d88570692edf644ab748c9f7fdb70e565372e710ece850978ed3cf0
+  data.tar.gz: 7998b13d22814989ebcd0cda3fab50b05a522dc853157dde131a0e0bb4b53f06aabb25c84c120136f2204ba289cc274a05793beb039edc466c172835bf3ceca5

data/README.md

@@ -181,6 +181,68 @@ sc.field(:sub).type(:object).tagged_one_of do |sub|
 end
 ```
 
+## One Of (multiple nested schemas, pick first valid match)
+
+You can use `Field#one_of` to validate a field against multiple possible schemas and accept the first one that validates successfully.
+
+Unlike `tagged_one_of`, this doesn't require a discriminator field - it tries each schema in order until it finds one that validates the input data.
+
+```ruby
+user_schema = Parametric::Schema.new do |sc, _|
+  sc.field(:name).type(:string).present
+  sc.field(:age).type(:integer).present
+end
+
+company_schema = Parametric::Schema.new do |sc, _|
+  sc.field(:company_name).type(:string).present
+  sc.field(:company_code).type(:string).present
+end
+
+schema = Parametric::Schema.new do |sc, _|
+  # This field can be either a user or company object
+  # The schema will try user_schema first, then company_schema
+  sc.field(:entity).type(:object).one_of(user_schema, company_schema)
+end
+
+# This will validate against user_schema (first match)
+result = schema.resolve(entity: { name: 'Joe', age: 30 })
+result.output # => { entity: { name: 'Joe', age: 30 } }
+
+# This will validate against company_schema (user_schema fails, so it tries company_schema)
+result = schema.resolve(entity: { company_name: 'Acme Corp', company_code: 'ACME' })
+result.output # => { entity: { company_name: 'Acme Corp', company_code: 'ACME' } }
+```
+
+The validation fails if:
+- No schemas match the input data
+- Multiple schemas match the input data (ambiguous)
+
+```ruby
+# This fails because it doesn't match either schema
+result = schema.resolve(entity: { invalid_field: 'value' })
+result.valid? # => false
+result.errors # => { "$.entity" => ["No valid sub-schema found"] }
+```
+
+### Usage with Structs
+
+When used with `Parametric::Struct`, `one_of` automatically creates multiple nested struct classes:
+
+```ruby
+class MyStruct
+  include Parametric::Struct
+
+  schema do |sc, _|
+    sc.field(:data).type(:object).one_of(user_schema, company_schema)
+  end
+end
+
+# The appropriate struct class will be instantiated based on which schema validates
+instance = MyStruct.new!(data: { name: 'Joe', age: 30 })
+instance.data # => #<MyStruct::Data2:...> (User struct)
+instance.data.name # => 'Joe'
+```
+
 ## Built-in policies
 
 Type coercions (the `type` method) and validations (the `validate` method) are all _policies_.

data/lib/parametric/field.rb

@@ -3,6 +3,7 @@
 require 'delegate'
 require 'parametric/field_dsl'
 require 'parametric/policy_adapter'
+require 'parametric/one_of'
 require 'parametric/tagged_one_of'
 
 module Parametric
@@ -50,6 +51,44 @@ module Parametric
       policy(instance || Parametric::TaggedOneOf.new(&block))
     end
 
+    # Validate field value against multiple schemas, accepting the first valid match.
+    # 
+    # This method allows a field to accept one of several possible object structures.
+    # It validates the input against each provided schema in order and uses the output
+    # from the first schema that successfully validates the input.
+    # 
+    # The validation fails if:
+    # - No schemas match the input (invalid data)
+    # - Multiple schemas match the input (ambiguous structure)
+    # 
+    # @param schemas [Array<Schema>] Variable number of Schema objects to validate against
+    # @return [Field] Returns self for method chaining
+    # 
+    # @example Define a field that can be either a user or admin object
+    #   user_schema = Schema.new { field(:name).type(:string).present }
+    #   admin_schema = Schema.new { field(:role).type(:string).options(['admin']) }
+    #   
+    #   schema = Schema.new do |sc, _|
+    #     sc.field(:person).type(:object).one_of(user_schema, admin_schema)
+    #   end
+    # 
+    # @example With different data structures
+    #   payment_schema = Schema.new do
+    #     field(:amount).type(:number).present
+    #     field(:currency).type(:string).present
+    #   end
+    #   
+    #   credit_schema = Schema.new do
+    #     field(:credits).type(:integer).present
+    #   end
+    #   
+    #   schema = Schema.new do |sc, _|
+    #     sc.field(:transaction).type(:object).one_of(payment_schema, credit_schema)
+    #   end
+    def one_of(*schemas)
+      policy OneOf.new(schemas)
+    end
+
     def schema(sc = nil, &block)
       sc = (sc ? sc : Schema.new(&block))
       meta schema: sc
@@ -71,8 +110,12 @@ module Parametric
 
     def visit(meta_key = nil, &visitor)
       if sc = meta_data[:schema]
-        r = sc.schema.visit(meta_key, &visitor)
-        (meta_data[:type] == :array) ? [r] : r
+        if sc.is_a?(Array)
+          sc.map { |s| s.schema.visit(meta_key, &visitor) }
+        else
+          r = sc.schema.visit(meta_key, &visitor)
+          (meta_data[:type] == :array) ? [r] : r
+        end
       else
         meta_key ? meta_data[meta_key] : yield(self)
       end

data/lib/parametric/one_of.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Parametric
+  # Policy that validates a value against multiple schemas and chooses the first valid match.
+  # 
+  # OneOf is useful for polymorphic validation where a field can be one of several
+  # different object structures. It tries each schema in order and returns the output
+  # of the first schema that successfully validates the input.
+  # 
+  # @example Basic usage
+  #   user_schema = Schema.new { field(:name).type(:string).present }
+  #   admin_schema = Schema.new { field(:role).type(:string).options(['admin']) }
+  #   
+  #   schema = Schema.new do |sc, _|
+  #     sc.field(:person).type(:object).one_of(user_schema, admin_schema)
+  #   end
+  # 
+  # @example With Struct
+  #   class MyStruct
+  #     include Parametric::Struct
+  #
+  #     schema do
+  #       field(:data).type(:object).one_of(schema1, schema2, schema3)
+  #     end
+  #   end
+  class OneOf
+    # Initialize with an array of schemas to validate against
+    # 
+    # @param schemas [Array<Schema>] Array of Parametric::Schema objects
+    def initialize(schemas = [])
+      @schemas = schemas
+    end
+
+    # Build a Runner instance for this policy (PolicyFactory interface)
+    # 
+    # @param key [Symbol] The field key being validated
+    # @param value [Object] The value to validate
+    # @param payload [Hash] The full input payload
+    # @param context [Object] Validation context
+    # @return [Runner] A new Runner instance
+    def build(key, value, payload:, context:)
+      Runner.new(@schemas, key, value, payload, context)
+    end
+
+    # Return metadata about this policy
+    # 
+    # @return [Hash] Metadata hash with type and schema information
+    def meta_data
+      { type: :object, schema: @schemas }
+    end
+
+    # Runner handles the actual validation logic for OneOf policy.
+    # 
+    # It validates the input value against each schema in order and determines
+    # which one(s) are valid. The policy succeeds if exactly one schema validates
+    # the input, and fails if zero or multiple schemas are valid.
+    class Runner
+      # Initialize the runner with validation parameters
+      # 
+      # @param schemas [Array<Schema>] Schemas to validate against
+      # @param key [Symbol] Field key being validated
+      # @param value [Object] Value to validate
+      # @param payload [Hash] Full input payload
+      # @param context [Object] Validation context
+      def initialize(schemas, key, value, payload, context)
+        @schemas = schemas
+        @key = key
+        @raw_value = value
+        @payload = payload
+        @context = context
+        @results = []
+        @message = nil
+      end
+
+      # Should this policy run at all?
+      # returning [false] halts the field policy chain.
+      # @return [Boolean]
+      def eligible?
+        true
+      end
+
+      # Validates that exactly one schema matches the input value.
+      # 
+      # The validation fails if:
+      # - No schemas validate the input (invalid data)
+      # - Multiple schemas validate the input (ambiguous match)
+      # 
+      # @return [Boolean] true if exactly one schema validates the input
+      def valid?
+        value
+        valids = @results.select(&:valid?)
+        if valids.size > 1
+          @message = "#{@raw_value} is invalid. Multiple valid sub-schemas found"
+        elsif valids.empty?
+          @message = "#{@raw_value} is invalid. No valid sub-schema found"
+        end
+        @message.nil?
+      end
+
+      # Returns the validated and coerced value from the first matching schema.
+      # 
+      # This method triggers the validation process by resolving the input value
+      # against each schema. If a valid schema is found, its coerced output is
+      # returned. Otherwise, the raw value is returned unchanged.
+      # 
+      # @return [Object] The coerced value from the first valid schema, or raw value if none match
+      def value
+        @value ||= begin
+          @results = @schemas.map do |schema|
+            schema.resolve(@raw_value)
+          end
+          first_valid = @results.find(&:valid?)
+          first_valid ? first_valid.output : @raw_value
+        end
+      end
+
+      # Error message when validation fails
+      # 
+      # @return [String, nil] Error message if validation failed, nil if valid
+      def message
+        @message
+      end
+    end
+  end
+end

data/lib/parametric/struct.rb

@@ -64,17 +64,33 @@ module Parametric
       def parametric_after_define_schema(schema)
         schema.fields.values.each do |field|
           if field.meta_data[:schema]
-            if field.meta_data[:schema].is_a?(Parametric::Schema)
+            case field.meta_data[:schema]
+            when Parametric::Schema
               klass = Class.new do
                 include Struct
               end
               klass.schema = field.meta_data[:schema]
               self.const_set(__class_name(field.key), klass)
               klass.parametric_after_define_schema(field.meta_data[:schema])
+            when Array
+              # Handle one_of fields: create multiple struct classes, one for each possible schema
+              # This allows the field to instantiate the appropriate nested struct based on which schema validates
+              classes = field.meta_data[:schema].map.with_index(1) do |sc, idx|
+                klass = Class.new do
+                  include Struct
+                end
+                klass.schema = sc
+                class_name = "#{__class_name(field.key)}#{idx}"
+                self.const_set(__class_name(class_name), klass)
+                klass.parametric_after_define_schema(sc)
+                klass
+              end
+              self.const_set(__class_name(field.key), classes)
             else
               self.const_set(__class_name(field.key), field.meta_data[:schema])
             end
           end
+
           self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{field.key}
               _graph[:#{field.key}]
@@ -94,7 +110,17 @@ module Parametric
         when Hash
           # find constructor for field
           cons = self.const_get(__class_name(key))
-          cons ? cons.new(value) : value.freeze
+          case cons
+          when Class # Single nested struct
+            cons.new(value)
+          when Array # Array of possible nested structs (one_of)
+            # For one_of fields: instantiate all possible struct classes and return the first valid one
+            # This allows the struct to automatically choose the correct nested structure based on the data
+            structs = cons.map{|c| c.new(value) }
+            structs.find(&:valid?) || structs.first
+          else
+            value.freeze
+          end
         when Array
           value.map{|v| wrap(key, v) }.freeze
         else

data/lib/parametric/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parametric
-  VERSION = '0.2.21'
+  VERSION = '0.2.23'
 end

data/spec/schema_spec.rb

@@ -274,6 +274,60 @@ describe Parametric::Schema do
     end
   end
 
+  describe '#one_of' do
+    let(:kwh_schema) do
+      described_class.new do
+        field(:unit).type(:string).present.default('kwh').options(['kwh'])
+        field(:value).type(:integer).present
+      end
+    end
+
+    let(:euro_schema) do
+      described_class.new do
+        field(:unit).type(:string).present.default('euro').options(['euro'])
+        field(:value).type(:integer).present
+        field(:period).type(:string).options(['month', 'year'])
+      end
+    end
+
+    let(:schema) do
+      described_class.new do |sc, _|
+        sc.field(:consumption).type(:object).one_of(kwh_schema, euro_schema)
+      end
+    end
+
+    it 'picks the valid sub-schema' do
+      result = schema.resolve(consumption: { unit: 'kwh', value: 100 })
+      expect(result.valid?).to be true
+      expect(result.output).to eq({ consumption: { unit: 'kwh', value: 100 } })
+
+      result = schema.resolve(consumption: { unit: 'euro', value: 100, period: 'month' })
+      expect(result.valid?).to be true
+      expect(result.output).to eq({ consumption: { unit: 'euro', value: 100, period: 'month' } })
+
+      result = schema.resolve(consumption: { unit: 'euro', value: 100, period: 'nope' })
+      expect(result.valid?).to be false
+    end
+
+    it 'is invalid is more than one valid sub-schema' do
+      sub1 = described_class.new do
+        field(:name).type(:string).present
+      end
+      sub2 = described_class.new do
+        field(:name).type(:string).present
+      end
+      schema = described_class.new do |sc, _|
+        sc.field(:obj).type(:object).one_of(sub1, sub2)
+      end
+      result = schema.resolve(obj: { name: 'Joe' })
+      expect(result.valid?).to be false
+    end
+
+    it 'does not break #walk' do
+      expect(schema.walk(:default).output).to be_a(Hash)
+    end
+  end
+
   describe '#tagged_one_of for multiple sub-schemas' do
     let(:user_schema) do
       described_class.new do

data/spec/struct_spec.rb

@@ -318,4 +318,30 @@ describe Parametric::Struct do
       expect(valid.title).to eq 'foo'
     end
   end
+
+  it 'works with Field#one_of(*schemas)' do
+    sub1 = Parametric::Schema.new do
+      field(:name).type(:string).present
+    end
+
+    sub2 = Parametric::Schema.new do
+      field(:age).type(:integer).present
+    end
+
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:user).type(:object).one_of(sub1, sub2)
+      end
+    end
+
+    valid = klass.new!(user: { age: '20' })
+    expect(valid.user.age).to eq 20
+    expect(valid.user).to be_a(klass.const_get('User2'))
+
+    invalid = klass.new(user: { nope: '20' })
+    expect(invalid.valid?).to be false
+    expect(invalid.errors['$.user']).not_to be_nil
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parametric
 version: !ruby/object:Gem::Version
-  version: 0.2.21
+  version: 0.2.23
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-30 00:00:00.000000000 Z
+date: 2025-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -77,6 +77,7 @@ files:
 - lib/parametric/field.rb
 - lib/parametric/field_dsl.rb
 - lib/parametric/nullable_policy.rb
+- lib/parametric/one_of.rb
 - lib/parametric/policies.rb
 - lib/parametric/policy_adapter.rb
 - lib/parametric/registry.rb
@@ -117,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: DSL for declaring allowed parameters with options, regexp patern and default