parametric 0.2.10 → 0.2.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f629915e6b2fee5ae5fcb9c63e340cd19880a72a3b53e06e33d3daff39ffa6a
-  data.tar.gz: c3fd0ec0a51e954fccd021c62098192b52913d44e1f0c35299cc77c56e428f57
+  metadata.gz: 98676c8edebba19bd1adff020f5eadf9dce07e44f89125be4f0451d6bdee50cf
+  data.tar.gz: 5a5d0ecded864e5185d2b1d1cafe5eeb2307d92cf52c4111e7dd85ebe65c0321
 SHA512:
-  metadata.gz: 9b46933db3b2bddd50ea66ec5e03faeb637248382e9a6fab81b2c539e201f148dc88ddc49e77f467974813a0c30a9c5196d48c3eef69f324ac47b15f39cd3d9e
-  data.tar.gz: 14ce2da62e976fa4c234d25087cfa9abeff2b4d4a077dbeab2a85654cbcc641f33fadcd9f42c76f02cf21321468d971e754e9ed4ff76ee0c314c1382d0201770
+  metadata.gz: 1a3b81c816a02516450bdeb70ddb5b804741481ec0084167f31cdddcef4c3734f25b0d69da022048d9889c7b47a462cd821bf3a4cef07d719aff9b57293e10ef
+  data.tar.gz: 5a2cd8dd4d68cd896901d744f656fca3385f6d3763bc05d62dbd1b6c53362a32092781e7bd57e439b27c6e0071d1179a0355372778d33b9c96f893e6fd4e07d3

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in parametric.gemspec
 gemspec
+
+group :development do
+  gem 'benchmark-ips'
+end

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_.
@@ -275,62 +329,106 @@ Useful for parsing comma-separated query-string parameters.
 field(:status).policy(:split) # turns "pending,confirmed" into ["pending", "confirmed"]
 ```
 
+### :value
+
+A policy to return a static value
+
+```ruby
+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
+
+  # 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
 
-  # Transform the value
-  def coerce(value, key, context)
-    value
+  # Should this policy run at all?
+  # returning [false] halts the field policy chain.
+  # @return [Boolean]
+  def eligible?
+    true
   end
 
-  # Is the value valid?
-  def valid?(value, key, payload)
+  # If [false], add [#message] to result errors and halt processing field.
+  # @return [Boolean]
+  def valid?
     true
   end
 
-  # merge this object into the field's meta data
-  def meta_data
-    {type: :string}
+  # 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:
@@ -341,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
 
@@ -849,6 +954,130 @@ results.errors["$.Weight"] # => ["is required and value must be present"]
 
 NOTES: dynamically expanded field names are not included in `Schema#structure` metadata, and they are only processes if fields with the given expressions are present in the payload. This means that validations applied to those fields only run if keys are present in the first place.
 
+## Before and after resolve hooks
+
+`Schema#before_resolve` can be used to register blocks to modify the entire input payload _before_ individual fields are validated and coerced.
+This can be useful when you need to pre-populate fields relative to other fields' values, or fetch extra data from other sources.
+
+```ruby
+# This example computes the value of the :slug field based on :name
+schema = Parametric::Schema.new do
+  # Note1: These blocks run before field validations, so :name might be blank or invalid at this point.
+  # Note2: Before hooks _must_ return a payload hash.
+  before_resolve do |payload, context|
+    payload.merge(
+      slug: payload[:name].to_s.downcase.gsub(/\s+/, '-')
+    )
+  end
+
+  # You still need to define the fields you want
+  field(:name).type(:string).present
+  field(:slug).type(:string).present
+end
+
+result = schema.resolve( name: 'Joe Bloggs' )
+result.output # => { name: 'Joe Bloggs', slug: 'joe-bloggs' }
+```
+
+Before hooks can be added to nested schemas, too:
+
+```ruby
+schema = Parametric::Schema.new do
+  field(:friends).type(:array).schema do
+    before_resolve do |friend_payload, context|
+      friend_payload.merge(title: "Mr/Ms #{friend_payload[:name]}")
+    end
+
+    field(:name).type(:string)
+    field(:title).type(:string)
+  end
+end
+```
+
+You can use inline blocks, but anything that responds to `#call(payload, context)` will work, too:
+
+```ruby
+class SlugMaker
+  def initialize(slug_field, from:)
+    @slug_field, @from = slug_field, from
+  end
+
+  def call(payload, context)
+    payload.merge(
+      @slug_field => payload[@from].to_s.downcase.gsub(/\s+/, '-')
+    )
+  end
+end
+
+schema = Parametric::Schema.new do
+  before_resolve SlugMaker.new(:slug, from: :name)
+
+  field(:name).type(:string)
+  field(:slug).type(:slug)
+end
+```
+
+The `context` argument can be used to add custom validation errors in a before hook block.
+
+```ruby
+schema = Parametric::Schema.new do
+  before_resolve do |payload, context|
+    # validate that there's no duplicate friend names
+    friends = payload[:friends] || []
+    if friends.any? && friends.map{ |fr| fr[:name] }.uniq.size < friends.size
+      context.add_error 'friend names must be unique'
+    end
+
+    # don't forget to return the payload
+    payload
+  end
+
+  field(:friends).type(:array).schema do
+    field(:name).type(:string)
+  end
+end
+
+result = schema.resolve(
+  friends: [
+    {name: 'Joe Bloggs'},
+    {name: 'Joan Bloggs'},
+    {name: 'Joe Bloggs'}
+  ]
+)
+
+result.valid? # => false
+result.errors # => {'$' => ['friend names must be unique']}
+```
+
+In most cases you should be validating individual fields using field policies. Only validate in before hooks in cases you have dependencies between fields.
+
+`Schema#after_resolve` takes the sanitized input hash, and can be used to further validate fields that depend on eachother.
+
+```ruby
+schema = Parametric::Schema.new do
+  after_resolve do |payload, ctx|
+    # Add a top level error using an arbitrary key name
+    ctx.add_base_error('deposit', 'cannot be greater than house price') if payload[:deposit] > payload[:house_price]
+    # Or add an error keyed after the current position in the schema
+    # ctx.add_error('some error') if some_condition
+    # after_resolve hooks must also return the payload, or a modified copy of it
+    # note that any changes added here won't be validated.
+    payload.merge(desc: 'hello')
+  end
+
+  field(:deposit).policy(:integer).present
+  field(:house_price).policy(:integer).present
+  field(:desc).policy(:string)
+end
+
+result = schema.resolve({ deposit: 1100, house_price: 1000 })
+result.valid? # false
+result.errors[:deposit] # ['cannot be greater than house price']
+result.output[:deposit] # 1100
+result.output[:house_price] # 1000
+result.output[:desc] # 'hello'
+```
+
 ## Structs
 
 Structs turn schema definitions into objects graphs with attribute readers.

data/bench/struct_bench.rb

@@ -0,0 +1,53 @@
+require 'benchmark/ips'
+require 'parametric/struct'
+
+StructAccount = Struct.new(:id, :email, keyword_init: true)
+StructFriend = Struct.new(:name, keyword_init: true)
+StructUser = Struct.new(:name, :age, :friends, :account, keyword_init: true)
+
+class ParametricAccount
+  include Parametric::Struct
+  schema do
+    field(:id).type(:integer).present
+    field(:email).type(:string)
+  end
+end
+
+class ParametricUser
+  include Parametric::Struct
+  schema do
+    field(:name).type(:string).present
+    field(:age).type(:integer).default(42)
+    field(:friends).type(:array).schema do
+      field(:name).type(:string).present
+    end
+    field(:account).type(:object).schema ParametricAccount
+  end
+end
+
+Benchmark.ips do |x|
+  x.report("Struct") {
+    StructUser.new(
+      name: 'Ismael',
+      age: 42,
+      friends: [
+        StructFriend.new(name: 'Joe'),
+        StructFriend.new(name: 'Joan'),
+      ],
+      account: StructAccount.new(id: 123, email: 'my@account.com')
+    )
+  }
+  x.report("Parametric::Struct")  {
+    ParametricUser.new!(
+      name: 'Ismael',
+      age: 42,
+      friends: [
+        { name: 'Joe' },
+        { name: 'Joan' }
+      ],
+      account: { id: 123, email: 'my@account.com' }
+    )
+  }
+  x.compare!
+end
+

data/lib/parametric/block_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
   class BlockValidator
     def self.build(meth, &block)

data/lib/parametric/context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
   class Top
     attr_reader :errors
@@ -26,6 +28,10 @@ module Parametric
       top.add_error(string_path, msg)
     end
 
+    def add_base_error(key, msg)
+      top.add_error(key, msg)
+    end
+
     def sub(key)
       self.class.new(path + [key], top)
     end
@@ -40,5 +46,4 @@ module Parametric
       end.join
     end
   end
-
 end

data/lib/parametric/default_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "date"
 
 module Parametric

data/lib/parametric/dsl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "parametric"
 
 module Parametric

data/lib/parametric/field.rb

@@ -1,4 +1,9 @@
-require "parametric/field_dsl"
+# frozen_string_literal: true
+
+require 'delegate'
+require 'parametric/field_dsl'
+require 'parametric/policy_adapter'
+require 'parametric/tagged_one_of'
 
 module Parametric
   class ConfigurationError < StandardError; end
@@ -37,15 +42,32 @@ 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
       policy sc.schema
     end
 
+    def from(another_field)
+      meta another_field.meta_data
+      another_field.policies.each do |plc|
+        policies << plc
+      end
+
+      self
+    end
+
+    def has_policy?(key)
+      policies.any? { |pol| pol.key == key }
+    end
+
     def visit(meta_key = nil, &visitor)
       if sc = meta_data[:schema]
-        r = sc.visit(meta_key, &visitor)
+        r = sc.schema.visit(meta_key, &visitor)
         (meta_data[:type] == :array) ? [r] : r
       else
         meta_key ? meta_data[meta_key] : yield(self)
@@ -63,37 +85,39 @@ 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
 
       Result.new(eligible, value)
     end
 
+    protected
+
+    attr_reader :policies
+
     private
-    attr_reader :policies, :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
+
+    attr_reader :registry, :default_block
 
     def has_default?
       !!default_block && !meta_data[:skip_default]
@@ -104,7 +128,20 @@ module Parametric
 
       raise ConfigurationError, "No policies defined for #{key.inspect}" unless obj
 
-      obj.respond_to?(:new) ? obj.new(*args) : obj
+      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
+
+    class PolicyWithKey < SimpleDelegator
+      attr_reader :key
+
+      def initialize(policy, key)
+        super policy
+        @key = key
+      end
     end
   end
 end

data/lib/parametric/field_dsl.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
   # Field DSL
   # host instance must implement:

data/lib/parametric/policies.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
   module Policies
     class Format
@@ -24,6 +26,31 @@ module Parametric
         {}
       end
     end
+
+    class Value
+      attr_reader :message
+
+      def initialize(val, msg = 'invalid value')
+        @message = msg
+        @val = val
+      end
+
+      def eligible?(value, key, payload)
+        payload.key?(key)
+      end
+
+      def coerce(_value, _key, _context)
+        @val
+      end
+
+      def valid?(value, key, payload)
+        !payload.key?(key) || !!(value == @val)
+      end
+
+      def meta_data
+        { value: @val }
+      end
+    end
   end
 
   # Default validators
@@ -31,6 +58,7 @@ module Parametric
 
   Parametric.policy :format, Policies::Format
   Parametric.policy :email, Policies::Format.new(EMAIL_REGEXP, 'invalid email')
+  Parametric.policy :value, Policies::Value
 
   Parametric.policy :noop do
     eligible do |value, key, payload|