parametric 0.2.10 → 0.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f629915e6b2fee5ae5fcb9c63e340cd19880a72a3b53e06e33d3daff39ffa6a
-  data.tar.gz: c3fd0ec0a51e954fccd021c62098192b52913d44e1f0c35299cc77c56e428f57
+  metadata.gz: c773dd859f56f8d526384567daf66c1c259a7e5d859c9fe40ecc620c0ee73253
+  data.tar.gz: 9b056fd197e9fe84a2b14b16134d860ae3a7c49313f370fd9de82fb918c7bc3b
 SHA512:
-  metadata.gz: 9b46933db3b2bddd50ea66ec5e03faeb637248382e9a6fab81b2c539e201f148dc88ddc49e77f467974813a0c30a9c5196d48c3eef69f324ac47b15f39cd3d9e
-  data.tar.gz: 14ce2da62e976fa4c234d25087cfa9abeff2b4d4a077dbeab2a85654cbcc641f33fadcd9f42c76f02cf21321468d971e754e9ed4ff76ee0c314c1382d0201770
+  metadata.gz: 9d068ab0c811e30db11d3b6eea2e38937557d2abb36df07623f419b669e7186a86af8de645575cacdb5efe7a51c0dbbe40048aa3fe5417296ee3c5810fd477bf
+  data.tar.gz: da9c1a990c6a0c2b85cf27d3f8ea7dd78e9b2e031548e240a79a43b85de9538e496ed491f3a5ef023ae6939d0f706b74274dd0519a7ae48d6452db65eed0d3ce

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

@@ -849,6 +849,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,3 +1,5 @@
+# frozen_string_literal: true
+
 require "parametric/field_dsl"
 
 module Parametric

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

data/lib/parametric/registry.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'parametric/block_validator'
 
 module Parametric

data/lib/parametric/results.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
   class Results
     attr_reader :output, :errors

data/lib/parametric/schema.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "parametric/context"
 require "parametric/results"
 require "parametric/field"
@@ -12,6 +14,8 @@ module Parametric
       @default_field_policies = []
       @ignored_field_keys = []
       @expansions = {}
+      @before_hooks = []
+      @after_hooks = []
     end
 
     def schema
@@ -90,6 +94,20 @@ module Parametric
       end
     end
 
+    def before_resolve(klass = nil, &block)
+      raise ArgumentError, '#before_resolve expects a callable object, or a block' if !klass && !block_given?
+      callable = klass || block
+      before_hooks << callable
+      self
+    end
+
+    def after_resolve(klass = nil, &block)
+      raise ArgumentError, '#after_resolve expects a callable object, or a block' if !klass && !block_given?
+      callable = klass || block
+      after_hooks << callable
+      self
+    end
+
     def expand(exp, &block)
       expansions[exp] = block
       self
@@ -139,19 +157,35 @@ module Parametric
 
     protected
 
-    attr_reader :definitions, :options
+    attr_reader :definitions, :options, :before_hooks, :after_hooks
 
     private
 
     attr_reader :default_field_policies, :ignored_field_keys, :expansions
 
     def coerce_one(val, context, flds: fields)
-      flds.each_with_object({}) do |(_, field), m|
+      val = run_before_hooks(val, context)
+
+      out = flds.each_with_object({}) do |(_, field), m|
         r = field.resolve(val, context.sub(field.key))
         if r.eligible?
           m[field.key] = r.value
         end
       end
+
+      run_after_hooks(out, context)
+    end
+
+    def run_before_hooks(val, context)
+      before_hooks.reduce(val) do |value, callable|
+        callable.call(value, context)
+      end
+    end
+
+    def run_after_hooks(val, context)
+      after_hooks.reduce(val) do |value, callable|
+        callable.call(value, context)
+      end
     end
 
     class MatchContext

data/lib/parametric/struct.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'parametric/dsl'
 
 module Parametric
@@ -56,10 +58,24 @@ module Parametric
 
       # this hook is called after schema definition in DSL module
       def parametric_after_define_schema(schema)
-        schema.fields.keys.each do |key|
-          define_method key do
-            _graph[key]
+        schema.fields.values.each do |field|
+          if field.meta_data[:schema]
+            if field.meta_data[:schema].is_a?(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])
+            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}]
+            end
+          RUBY
         end
       end
 
@@ -69,27 +85,11 @@ module Parametric
         end
       end
 
-      def parametric_build_class_for_child(key, child_schema)
-        klass = Class.new do
-          include Struct
-        end
-        klass.schema = child_schema
-        klass
-      end
-
       def wrap(key, value)
-        field = schema.fields[key]
-        return value unless field
-
         case value
         when Hash
           # find constructor for field
-          cons = field.meta_data[:schema]
-          if cons.kind_of?(Parametric::Schema)
-            klass = parametric_build_class_for_child(key, cons)
-            klass.parametric_after_define_schema(cons)
-            cons = klass
-          end
+          cons = self.const_get(__class_name(key))
           cons ? cons.new(value) : value.freeze
         when Array
           value.map{|v| wrap(key, v) }.freeze
@@ -97,6 +97,12 @@ module Parametric
           value.freeze
         end
       end
+
+      PLURAL_END = /s$/.freeze
+
+      def __class_name(key)
+        key.to_s.split('_').map(&:capitalize).join.sub(PLURAL_END, '')
+      end
     end
   end
 end

data/lib/parametric/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Parametric
-  VERSION = "0.2.10"
+  VERSION = "0.2.12"
 end

data/lib/parametric.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "parametric/version"
 require "parametric/registry"
 require "parametric/field"

data/parametric.gemspec

@@ -17,7 +17,6 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", '3.4.0'
   spec.add_development_dependency "byebug"

data/spec/policies_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe 'default coercions' do
   def test_coercion(key, value, expected)
-    coercion = Parametric.registry.coercions[key]
+    coercion = Parametric.registry.policies[key]
     expect(coercion.new.coerce(value, nil, nil)).to eq expected
   end
 

data/spec/schema_lifecycle_hooks_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper'
+
+describe Parametric::Schema do
+  describe '#before_resolve' do
+    it 'passes payload through before_resolve block, if defined' do
+      schema = described_class.new do
+        before_resolve do |payload, _context|
+          payload[:slug] = payload[:name].to_s.downcase.gsub(/\s+/, '-') unless payload[:slug]
+          payload
+        end
+
+        field(:name).policy(:string).present
+        field(:slug).policy(:string).present
+        field(:variants).policy(:array).schema do
+          before_resolve do |payload, _context|
+            payload[:slug] = "v: #{payload[:name].to_s.downcase}"
+            payload
+          end
+          field(:name).policy(:string).present
+          field(:slug).type(:string).present
+        end
+      end
+
+      result = schema.resolve({ name: 'A name', variants: [{ name: 'A variant' }] })
+      expect(result.valid?).to be true
+      expect(result.output[:slug]).to eq 'a-name'
+      expect(result.output[:variants].first[:slug]).to eq 'v: a variant'
+    end
+
+    it 'collects errors added in before_resolve blocks' do
+      schema = described_class.new do
+        field(:variants).type(:array).schema do
+          before_resolve do |payload, context|
+            context.add_error 'nope!' if payload[:name] == 'with errors'
+            payload
+          end
+          field(:name).type(:string)
+        end
+      end
+
+      results = schema.resolve({ variants: [ {name: 'no errors'}, {name: 'with errors'}]})
+      expect(results.valid?).to be false
+      expect(results.errors['$.variants[1]']).to eq ['nope!']
+    end
+
+    it 'copies before_resolve hooks to merged schemas' do
+      schema1 = described_class.new do
+        before_resolve do |payload, _context|
+          payload[:slug] = payload[:name].to_s.downcase.gsub(/\s+/, '-') unless payload[:slug]
+          payload
+        end
+        field(:name).present.type(:string)
+        field(:slug).present.type(:string)
+      end
+
+      schema2 = described_class.new do
+        before_resolve do |payload, _context|
+          payload[:slug] = "slug-#{payload[:slug]}" if payload[:slug]
+          payload
+        end
+
+        field(:age).type(:integer)
+      end
+
+      schema3 = schema1.merge(schema2)
+
+      results = schema3.resolve({ name: 'Ismael Celis', age: 41 })
+      expect(results.output[:slug]).to eq 'slug-ismael-celis'
+    end
+
+    it 'works with any callable' do
+      slug_maker = Class.new do
+        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 = described_class.new do |sc, _opts|
+        sc.before_resolve slug_maker.new(:slug, from: :name)
+
+        sc.field(:name).type(:string)
+        sc.field(:slug).type(:string)
+      end
+
+      results = schema.resolve(name: 'Ismael Celis')
+      expect(results.output[:slug]).to eq 'ismael-celis'
+    end
+  end
+
+  describe '#after_resolve' do
+    let!(:schema) do
+      described_class.new do
+        after_resolve do |payload, ctx|
+          ctx.add_base_error('deposit', 'cannot be greater than house price') if payload[:deposit] > payload[:house_price]
+          payload.merge(desc: 'hello')
+        end
+
+        field(:deposit).policy(:integer).present
+        field(:house_price).policy(:integer).present
+        field(:desc).policy(:string)
+      end
+    end
+
+    it 'passes payload through after_resolve block, if defined' do
+      result = schema.resolve({ deposit: 1100, house_price: 1000 })
+      expect(result.valid?).to be false
+      expect(result.output[:deposit]).to eq 1100
+      expect(result.output[:house_price]).to eq 1000
+      expect(result.output[:desc]).to eq 'hello'
+    end
+
+    it 'copies after hooks when merging schemas' do
+      child_schema = described_class.new do
+        field(:name).type(:string)
+      end
+
+      union = schema.merge(child_schema)
+
+      result = union.resolve({ name: 'Joe', deposit: 1100, house_price: 1000 })
+      expect(result.valid?).to be false
+      expect(result.output[:deposit]).to eq 1100
+      expect(result.output[:house_price]).to eq 1000
+      expect(result.output[:desc]).to eq 'hello'
+      expect(result.output[:name]).to eq 'Joe'
+    end
+  end
+end

data/spec/struct_spec.rb

@@ -99,32 +99,6 @@ describe Parametric::Struct do
     expect(instance.friends.first.age).to eq 10
   end
 
-  it 'wraps nested schemas in custom class' do
-    klass = Class.new do
-      include Parametric::Struct
-
-      def self.parametric_build_class_for_child(key, child_schema)
-        Class.new do
-          include Parametric::Struct
-          schema child_schema
-          def salutation
-            "my age is #{age}"
-          end
-        end
-      end
-
-      schema do
-        field(:name).type(:string).present
-        field(:friends).type(:array).schema do
-          field(:age).type(:integer)
-        end
-      end
-    end
-
-    user = klass.new(name: 'Ismael', friends: [{age: 43}])
-    expect(user.friends.first.salutation).to eq 'my age is 43'
-  end
-
   it "wraps regular schemas in structs" do
     friend_schema = Parametric::Schema.new do
       field(:name)

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: parametric
 version: !ruby/object:Gem::Version
-  version: 0.2.10
+  version: 0.2.12
 platform: ruby
 authors:
 - Ismael Celis
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-09-26 00:00:00.000000000 Z
+date: 2020-08-24 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -81,6 +67,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bench/struct_bench.rb
 - bin/console
 - lib/parametric.rb
 - lib/parametric/block_validator.rb
@@ -101,6 +88,7 @@ files:
 - spec/expand_spec.rb
 - spec/field_spec.rb
 - spec/policies_spec.rb
+- spec/schema_lifecycle_hooks_spec.rb
 - spec/schema_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb
@@ -110,7 +98,7 @@ homepage: ''
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -125,9 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
-signing_key: 
+rubygems_version: 3.0.3
+signing_key:
 specification_version: 4
 summary: DSL for declaring allowed parameters with options, regexp patern and default
   values.
@@ -137,6 +124,7 @@ test_files:
 - spec/expand_spec.rb
 - spec/field_spec.rb
 - spec/policies_spec.rb
+- spec/schema_lifecycle_hooks_spec.rb
 - spec/schema_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb