parametric 0.2.17 → 0.2.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71e71a5ddf414bb333a499f425d68e891f60a2e0610a8a57d8362f6481da16e6
-  data.tar.gz: 5c13b835147015f11f66591d311612139b16c4001891451d299c39358045725c
+  metadata.gz: 98676c8edebba19bd1adff020f5eadf9dce07e44f89125be4f0451d6bdee50cf
+  data.tar.gz: 5a5d0ecded864e5185d2b1d1cafe5eeb2307d92cf52c4111e7dd85ebe65c0321
 SHA512:
-  metadata.gz: 8cd1bb404bb5bcf24fc7b4826dcf360d367efb23cbe0e1d300a25f3e0a709ee5fb4e9d17db5820803a9e8f2f0b65e68ddae5c27325573f7fc213c7814a8f4e04
-  data.tar.gz: 0fd11bca14c7c75decb6dcc9781ef1b26a3ecc7bed3b4348b30f5c8c06ad57237b10beb7d3acd6a5b1f0e8989823da29e2f3bc3956f51856b1e57b852a7bdd5d
+  metadata.gz: 1a3b81c816a02516450bdeb70ddb5b804741481ec0084167f31cdddcef4c3734f25b0d69da022048d9889c7b47a462cd821bf3a4cef07d719aff9b57293e10ef
+  data.tar.gz: 5a2cd8dd4d68cd896901d744f656fca3385f6d3763bc05d62dbd1b6c53362a32092781e7bd57e439b27c6e0071d1179a0355372778d33b9c96f893e6fd4e07d3

data/README.md

@@ -127,6 +127,60 @@ person_schema = Parametric::Schema.new do |sc, options|
   sc.field(:friends).type(:array).schema(friends_schema)
 end
 ```
+
+## Tagged One Of (multiple nested schemas, discriminated by payload key).
+
+You can use `Field#tagged_one_of` to resolve a nested schema based on the value of a top-level field.
+
+```ruby
+user_schema = Parametric::Schema.new do |sc, _|
+  field(:name).type(:string).present
+  field(:age).type(:integer).present
+end
+
+company_schema = Parametric::Schema.new do
+  field(:name).type(:string).present
+  field(:company_code).type(:string).present
+end
+
+schema = Parametric::Schema.new do |sc, _|
+  # Use :type field to locate the sub-schema to use for :sub
+  sc.field(:type).type(:string)
+
+  # Use the :one_of policy to select the sub-schema based on the :type field above
+  sc.field(:sub).type(:object).tagged_one_of do |sub|
+    sub.index_by(:type)
+    sub.on('user', user_schema)
+    sub.on('company', company_schema)
+  end
+end
+
+# The schema will now select the correct sub-schema based on the value of :type
+result = schema.resolve(type: 'user', sub: { name: 'Joe', age: 30 })
+
+# Instances can also be created separately and used as a policy:
+
+UserOrCompany = Parametric::TaggedOneOf.new do |sc, _|
+  sc.on('user', user_schema)
+  sc.on('company', company_schema)
+end
+
+schema = Parametric::Schema.new do |sc, _|
+  sc.field(:type).type(:string)
+  sc.field(:sub).type(:object).policy(UserOrCompany.index_by(:type))
+end
+```
+
+`#index_by` can take a block to decide what value to resolve schemas by:
+
+```ruby
+sc.field(:sub).type(:object).tagged_one_of do |sub|
+  sub.index_by { |payload| payload[:entity_type] }
+  sub.on('user', user_schema)
+  sub.on('company', company_schema)
+end
+```
+
 ## Built-in policies
 
 Type coercions (the `type` method) and validations (the `validate` method) are all _policies_.
@@ -285,60 +339,96 @@ field(:currency).policy(:value, 'gbp') # this field always resolves to 'gbp'
 
 ## Custom policies
 
-You can also register your own custom policy objects. A policy must implement the following methods:
+You can also register your own custom policy objects.
+A policy consist of the following:
+
+* A `PolicyFactory` interface:
 
 ```ruby
 class MyPolicy
-  # Validation error message, if invalid
-  def message
-    'is invalid'
+  # Initializer signature is up to you.
+  # These are the arguments passed to the policy when using in a Field,
+  # ex. field(:name).policy(:my_policy, 'arg1', 'arg2')
+  def initialize(arg1, arg2)
+    @arg1, @arg2 = arg1, arg2
   end
 
-  # Whether or not to validate and coerce this value
-  # if false, no other policies will be run on the field
-  def eligible?(value, key, payload)
-    true
+  # @return [Hash]
+  def meta_data
+   { type: :string }
   end
 
-  # Transform the value
-  def coerce(value, key, context)
-    value
+  # Buld a Policy Runner, which is instantiated
+  # for each field when resolving a schema
+  # @param key [Symbol]
+  # @param value [Any]
+  # @option payload [Hash]
+  # @option context [Parametric::Context]
+  # @return [PolicyRunner]
+  def build(key, value, payload:, context:)
+    MyPolicyRunner.new(key, value, payload, context)
+  end
+end
+```
+
+* A `PolicyRunner` interface.
+
+```ruby
+class MyPolicyRunner
+  # Initializer is up to you. See `MyPolicy#build`
+  def initialize(key, value, payload, context)
+
   end
 
-  # Is the value valid?
-  def valid?(value, key, payload)
+  # Should this policy run at all?
+  # returning [false] halts the field policy chain.
+  # @return [Boolean]
+  def eligible?
     true
   end
 
-  # merge this object into the field's meta data
-  def meta_data
-    {type: :string}
+  # If [false], add [#message] to result errors and halt processing field.
+  # @return [Boolean]
+  def valid?
+    true
+  end
+
+  # Coerce the value, or return as-is.
+  # @return [Any]
+  def value
+    @value
+  end
+
+  # Error message for this policy
+  # @return [String]
+  def message
+    "#{@value} is invalid"
   end
 end
 ```
 
-You can register your policy with:
+Then register your custom policy factory:
 
 ```ruby
-Parametric.policy :my_policy, MyPolicy
+Parametric.policy :my_polict, MyPolicy
 ```
 
 And then refer to it by name when declaring your schema fields
 
 ```ruby
-field(:title).policy(:my_policy)
+field(:title).policy(:my_policy, 'arg1', 'arg2')
 ```
 
 You can chain custom policies with other policies.
 
 ```ruby
-field(:title).required.policy(:my_policy)
+field(:title).required.policy(:my_policy, 'arg1', 'arg2')
 ```
 
 Note that you can also register instances.
 
 ```ruby
-Parametric.policy :my_policy, MyPolicy.new
+Parametric.policy :my_policy, MyPolicy.new('arg1', 'arg2')
 ```
 
 For example, a policy that can be configured on a field-by-field basis:
@@ -349,27 +439,34 @@ class AddJobTitle
     @job_title = job_title
   end
 
-  def message
-    'is invalid'
+  def build(key, value, payload:, context:)
+    Runner.new(@job_title, key, value, payload, context)
   end
 
-  # Noop
-  def eligible?(value, key, payload)
-    true
+  def meta_data
+    {}
   end
 
-  # Add job title to value
-  def coerce(value, key, context)
-    "#{value}, #{@job_title}"
-  end
+  class Runner
+    attr_reader :message
 
-  # Noop
-  def valid?(value, key, payload)
-    true
-  end
+    def initialize(job_title, key, value, payload, _context)
+      @job_title = job_title
+      @key, @value, @payload = key, value, payload
+      @message = 'is invalid'
+    end
 
-  def meta_data
-    {}
+    def eligible?
+      true
+    end
+
+    def valid?
+      true
+    end
+
+    def value
+      "#{@value}, #{@job_title}"
+    end
   end
 end
 

data/lib/parametric/field.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require 'delegate'
-require "parametric/field_dsl"
+require 'parametric/field_dsl'
+require 'parametric/policy_adapter'
+require 'parametric/tagged_one_of'
 
 module Parametric
   class ConfigurationError < StandardError; end
@@ -40,6 +42,10 @@ module Parametric
     end
     alias_method :type, :policy
 
+    def tagged_one_of(instance = nil, &block)
+      policy(instance || Parametric::TaggedOneOf.new(&block))
+    end
+
     def schema(sc = nil, &block)
       sc = (sc ? sc : Schema.new(&block))
       meta schema: sc
@@ -79,20 +85,26 @@ module Parametric
       end
 
       policies.each do |policy|
-        if !policy.eligible?(value, key, payload)
-          eligible = false
-          if has_default?
-            eligible = true
-            value = default_block.call(key, payload, context)
+        begin
+          pol = policy.build(key, value, payload:, context:)
+          if !pol.eligible?
+            eligible = false
+            if has_default?
+              eligible = true
+              value = default_block.call(key, payload, context)
+            end
+            break
+          else
+            value = pol.value
+            if !pol.valid?
+              eligible = true # eligible, but has errors
+              context.add_error pol.message
+              break # only one error at a time
+            end
           end
+        rescue StandardError => e
+          context.add_error e.message
           break
-        else
-          value = resolve_one(policy, value, context)
-          if !policy.valid?(value, key, payload)
-            eligible = true # eligible, but has errors
-            context.add_error policy.message
-            break # only one error at a time
-          end
         end
       end
 
@@ -107,15 +119,6 @@ module Parametric
 
     attr_reader :registry, :default_block
 
-    def resolve_one(policy, value, context)
-      begin
-        policy.coerce(value, key, context)
-      rescue StandardError => e
-        context.add_error e.message
-        value
-      end
-    end
-
     def has_default?
       !!default_block && !meta_data[:skip_default]
     end
@@ -127,6 +130,7 @@ module Parametric
 
       obj = obj.new(*args) if obj.respond_to?(:new)
       obj = PolicyWithKey.new(obj, key)
+      obj = PolicyAdapter.new(obj) unless obj.respond_to?(:build)
 
       obj
     end

data/lib/parametric/policy_adapter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Parametric
+  # Adapt legacy policies to the new policy interface
+  class PolicyAdapter
+    class PolicyRunner
+      def initialize(policy, key, value, payload, context)
+        @policy, @key, @raw_value, @payload, @context = policy, key, value, payload, context
+      end
+
+      # The PolicyRunner interface
+      # @return [Boolean]
+      def eligible?
+        @policy.eligible?(@raw_value, @key, @payload)
+      end
+
+      # @return [Boolean]
+      def valid?
+        @policy.valid?(value, @key, @payload)
+      end
+
+      # @return [Any]
+      def value
+        @value ||= @policy.coerce(@raw_value, @key, @context)
+      end
+
+      # @return [String]
+      def message
+        @policy.message
+      end
+    end
+
+    def initialize(policy)
+      @policy = policy
+    end
+
+    # The PolicyFactory interface
+    # Buld a Policy Runner, which is instantiated
+    # for each field when resolving a schema
+    # @param key [Symbol]
+    # @param value [Any]
+    # @option payload [Hash]
+    # @option context [Parametric::Context]
+    # @return [PolicyRunner]
+    def build(key, value, payload:, context:)
+      PolicyRunner.new(@policy, key, value, payload, context)
+    end
+
+    def meta_data
+      @policy.meta_data
+    end
+
+    def key
+      @policy.key
+    end
+  end
+end

data/lib/parametric/schema.rb

@@ -76,6 +76,8 @@ module Parametric
         meta = field.meta_data.dup
         sc = meta.delete(:schema)
         meta[:structure] = sc.schema.structure if sc
+        one_of = meta.delete(:one_of)
+        meta[:one_of] = one_of.values.map(&:structure) if one_of
         obj[field.key] = meta
       end
     end

data/lib/parametric/tagged_one_of.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Parametric
+  # A policy that allows you to select a sub-schema based on a value in the payload.
+  # @example
+  #
+  #   user_schema = Parametric::Schema.new do |sc, _|
+  #     field(:name).type(:string).present
+  #     field(:age).type(:integer).present
+  #   end
+  #
+  #   company_schema = Parametric::Schema.new do
+  #     field(:name).type(:string).present
+  #     field(:company_code).type(:string).present
+  #   end
+  #
+  #   schema = Parametric::Schema.new do |sc, _|
+  #      # Use :type field to locate the sub-schema to use for :sub
+  #      sc.field(:type).type(:string)
+  #
+  #      # Use the :one_of policy to select the sub-schema based on the :type field above
+  #      sc.field(:sub).type(:object).tagged_one_of do |sub|
+  #        sub.index_by(:type)
+  #        sub.on('user', user_schema)
+  #        sub.on('company', company_schema)
+  #      end
+  #    end
+  #
+  #    # The schema will now select the correct sub-schema based on the value of :type
+  #    result = schema.resolve(type: 'user', sub: { name: 'Joe', age: 30 })
+  #
+  # Instances can also be created separately and used as a policy:
+  # @example
+  #
+  #   UserOrCompany = Parametric::TaggedOneOf.new do |sc, _|
+  #     sc.on('user', user_schema)
+  #     sc.on('company', company_schema)
+  #   end
+  #
+  #   schema = Parametric::Schema.new do |sc, _|
+  #     sc.field(:type).type(:string)
+  #     sc.field(:sub).type(:object).policy(UserOrCompany.index_by(:type))
+  #   end
+  class TaggedOneOf
+    NOOP_INDEX = ->(payload) { payload }.freeze
+    def initialize(index: NOOP_INDEX, matchers: {}, &block)
+      @index = index
+      @matchers = matchers
+      @configuring = false
+      if block_given?
+        @configuring = true
+        block.call(self)
+        @configuring = false
+      end
+      freeze
+    end
+
+    def index_by(callable = nil, &block)
+      if callable.is_a?(Symbol)
+        key = callable
+        callable = ->(payload) { payload[key] }
+      end
+      index = callable || block
+      if configuring?
+        @index = index
+      else
+        self.class.new(index:, matchers: @matchers)
+      end
+    end
+
+    def on(key, schema)
+      @matchers[key] = schema
+    end
+
+    # The [PolicyFactory] interface
+    def build(key, value, payload:, context:)
+      Runner.new(@index, @matchers, key, value, payload, context)
+    end
+
+    def meta_data
+      { type: :object, one_of: @matchers }
+    end
+
+    private def configuring?
+      @configuring
+    end
+
+    class Runner
+      def initialize(index, matchers, key, value, payload, context)
+        @matchers = matchers
+        @key = key
+        @raw_value = value
+        @payload = payload
+        @context = context
+        @index_value = index.call(payload)
+      end
+
+      # Should this policy run at all?
+      # returning [false] halts the field policy chain.
+      # @return [Boolean]
+      def eligible?
+        true
+      end
+
+      # If [false], add [#message] to result errors and halt processing field.
+      # @return [Boolean]
+      def valid?
+        has_sub_schema?
+      end
+
+      # Coerce the value, or return as-is.
+      # @return [Any]
+      def value
+        @value ||= has_sub_schema? ? sub_schema.coerce(@raw_value, @key, @context) : @raw_value
+      end
+
+      # Error message for this policy
+      # @return [String]
+      def message
+        "#{@value} is invalid. No sub-schema found for '#{@index_value}'"
+      end
+
+      private
+
+      def has_sub_schema?
+        @matchers.key?(@index_value)
+      end
+
+      def sub_schema
+        @sub_schema ||= @matchers[@index_value]
+      end
+    end
+  end
+end

data/lib/parametric/version.rb

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

data/parametric.gemspec

@@ -18,6 +18,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec", '3.4.0'
+  spec.add_development_dependency "rspec", '3.12.0'
   spec.add_development_dependency "byebug"
 end

data/spec/schema_spec.rb

@@ -251,6 +251,87 @@ describe Parametric::Schema do
     end
   end
 
+  describe '#tagged_one_of for multiple sub-schemas' do
+    let(:user_schema) do
+      described_class.new do
+        field(:name).type(:string).present
+        field(:age).type(:integer).present
+      end
+    end
+
+    let(:company_schema) do
+      described_class.new do
+        field(:name).type(:string).present
+        field(:company_code).type(:string).present
+      end
+    end
+
+    it 'picks the right sub-schema' do
+      schema = described_class.new do |sc, _|
+        sc.field(:type).type(:string)
+        sc.field(:sub).type(:object).tagged_one_of do |sub|
+          sub.index_by(:type)
+          sub.on('user', user_schema)
+          sub.on('company', company_schema)
+        end
+      end
+
+      result = schema.resolve(type: 'user', sub: { name: 'Joe', age: 30 })
+      expect(result.valid?).to be true
+      expect(result.output).to eq({ type: 'user', sub: { name: 'Joe', age: 30 } })
+
+      result = schema.resolve(type: 'company', sub: { name: 'ACME', company_code: 123 })
+      expect(result.valid?).to be true
+      expect(result.output).to eq({ type: 'company', sub: { name: 'ACME', company_code: '123' } })
+
+      result = schema.resolve(type: 'company', sub: { name: nil, company_code: 123 })
+      expect(result.valid?).to be false
+      expect(result.errors['$.sub.name']).not_to be_empty
+
+      result = schema.resolve(type: 'foo', sub: { name: 'ACME', company_code: 123 })
+      expect(result.valid?).to be false
+    end
+
+    it 'can be assigned to instance and reused' do
+      user_or_company = Parametric::TaggedOneOf.new do |sub|
+        sub.on('user', user_schema)
+        sub.on('company', company_schema)
+      end
+
+      schema = described_class.new do |sc, _|
+        sc.field(:type).type(:string)
+        sc.field(:sub).type(:object).tagged_one_of(user_or_company.index_by(:type))
+      end
+
+      result = schema.resolve(type: 'user', sub: { name: 'Joe', age: 30 })
+      expect(result.valid?).to be true
+      expect(result.output).to eq({ type: 'user', sub: { name: 'Joe', age: 30 } })
+    end
+
+    specify '#structure' do
+      user_or_company = Parametric::TaggedOneOf.new do |sub|
+        sub.on('user', user_schema)
+        sub.on('company', company_schema)
+      end
+
+      schema = described_class.new do |sc, _|
+        sc.field(:type).type(:string)
+        sc.field(:sub).type(:object).tagged_one_of(user_or_company.index_by(:type))
+      end
+
+      structure = schema.structure
+      structure.dig(:sub).tap do |sub|
+        expect(sub[:type]).to eq :object
+        expect(sub[:one_of][0][:name][:type]).to eq :string
+        expect(sub[:one_of][0][:name][:required]).to be true
+        expect(sub[:one_of][0][:name][:present]).to be true
+        expect(sub[:one_of][0][:age][:type]).to eq :integer
+
+        expect(sub[:one_of][1][:company_code][:type]).to eq :string
+      end
+    end
+  end
+
   describe "#ignore" do
     it "ignores fields" do
       s1 = described_class.new.ignore(:title, :status) do

data/spec/struct_spec.rb

@@ -301,6 +301,9 @@ describe Parametric::Struct do
 
         schema do
           field(:title).type(:string).present
+          field(:consumption).type(:object).present.schema do
+            field(:type).present.options(%w[aaa bbb])
+          end
         end
       end
 
@@ -308,9 +311,10 @@ describe Parametric::Struct do
         klass.new!(title: '')
       rescue Parametric::InvalidStructError => e
         expect(e.errors['$.title']).not_to be nil
+        expect(e.errors['$.consumption']).not_to be nil
       end
 
-      valid = klass.new!(title: 'foo')
+      valid = klass.new!(title: 'foo', consumption: { type: 'aaa' })
       expect(valid.title).to eq 'foo'
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parametric
 version: !ruby/object:Gem::Version
-  version: 0.2.17
+  version: 0.2.19
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-29 00:00:00.000000000 Z
+date: 2023-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.4.0
+        version: 3.12.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.4.0
+        version: 3.12.0
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -77,10 +77,12 @@ files:
 - lib/parametric/field.rb
 - lib/parametric/field_dsl.rb
 - lib/parametric/policies.rb
+- lib/parametric/policy_adapter.rb
 - lib/parametric/registry.rb
 - lib/parametric/results.rb
 - lib/parametric/schema.rb
 - lib/parametric/struct.rb
+- lib/parametric/tagged_one_of.rb
 - lib/parametric/version.rb
 - parametric.gemspec
 - spec/custom_block_validator_spec.rb
@@ -113,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.4.18
 signing_key:
 specification_version: 4
 summary: DSL for declaring allowed parameters with options, regexp patern and default