parametric 0.2.11 → 0.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 763b926782a534a5421ff8252b8da1e372b12ef7de36c57f8439e58daea178ac
-  data.tar.gz: 7e07efa2345016bd28f947d9d527b0ab698796f11b6fa466059e4dcfd7ceaea3
+  metadata.gz: c773dd859f56f8d526384567daf66c1c259a7e5d859c9fe40ecc620c0ee73253
+  data.tar.gz: 9b056fd197e9fe84a2b14b16134d860ae3a7c49313f370fd9de82fb918c7bc3b
 SHA512:
-  metadata.gz: 8b7d4569723c047a599af8da6e6f83ed05ffb976b7557396881d5ee1188ae0db30715a002cafa1d116bdfc3368fde1a1006baa83a5288ecab3ec2e39c08ea040
-  data.tar.gz: 50f419b619fa561a0769b812864bd43c7233a637f81b033d51052eb7e85eebb92872bb9a7fc41cf28092be04a50be813644423f9b9a6f3784255a5c5e84b8a1d
+  metadata.gz: 9d068ab0c811e30db11d3b6eea2e38937557d2abb36df07623f419b669e7186a86af8de645575cacdb5efe7a51c0dbbe40048aa3fe5417296ee3c5810fd477bf
+  data.tar.gz: da9c1a990c6a0c2b85cf27d3f8ea7dd78e9b2e031548e240a79a43b85de9538e496ed491f3a5ef023ae6939d0f706b74274dd0519a7ae48d6452db65eed0d3ce

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/lib/parametric/context.rb

@@ -28,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
@@ -42,5 +46,4 @@ module Parametric
       end.join
     end
   end
-
 end

data/lib/parametric/schema.rb

@@ -14,6 +14,8 @@ module Parametric
       @default_field_policies = []
       @ignored_field_keys = []
       @expansions = {}
+      @before_hooks = []
+      @after_hooks = []
     end
 
     def schema
@@ -92,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
@@ -141,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parametric
-  VERSION = "0.2.11"
+  VERSION = "0.2.12"
 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parametric
 version: !ruby/object:Gem::Version
-  version: 0.2.11
+  version: 0.2.12
 platform: ruby
 authors:
 - Ismael Celis
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-13 00:00:00.000000000 Z
+date: 2020-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -88,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
@@ -97,7 +98,7 @@ homepage: ''
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -112,8 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-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.
@@ -123,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