parametric 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 723fbc2c52d12ad990405295ef4a0a857d0d6638
-  data.tar.gz: 685e8e6b97ffebbf51e413e1780fcfd69bb626a4
+SHA256:
+  metadata.gz: f5dfee33e2a3f175505899e0238390e2795e0a862469b851a3a550aef152e8be
+  data.tar.gz: c1225c196aeb662384da471dd31b62ea8e072a90049eecb609976dfa21eec1d6
 SHA512:
-  metadata.gz: a5f63c830feb5c708b64be0d2de108949cd2b07a3157686f64b6535c77ca79fa157a24293a1983a17a69ce0c30cd24df6b482aad9a4d295e254ac2400771de00
-  data.tar.gz: 3eb0a6f083e87303716931e6e55247e044b7d969af09322638758029adef56c6c1ecf66c79f148ae7b14b3879a590835af1f5af83e6e8475517b9b76205ca7eb
+  metadata.gz: 2645e19eda4c75f82f8620fa16cce48fad7b60a14d1749e78a3de05411b55f1daf2ae9e41149467ccd1ccecd613178972d8283ead6a8becdf0c35bae1d4a7123
+  data.tar.gz: 84ecd165ff1355b17f5596f7f7c47a1b2965a2a7c50e6211801400f019aa8d318847ebf68ecbbf2c6c75da6cd8f3bb257707f9e69a4d9b5500ddf82c52733ff2

data/README.md

@@ -474,10 +474,10 @@ create_user_schema.structure[:friends].structure[:name].label # => "Friend full
 Note that many field policies add field meta data.
 
 ```ruby
-create_user_schema.schema[:name][:type] # => :string
-create_user_schema.schema[:name][:required] # => true
-create_user_schema.schema[:status][:options] # => ["published", "unpublished"]
-create_user_schema.schema[:status][:default] # => "published"
+create_user_schema.structure[:name][:type] # => :string
+create_user_schema.structure[:name][:required] # => true
+create_user_schema.structure[:status][:options] # => ["published", "unpublished"]
+create_user_schema.structure[:status][:default] # => "published"
 ```
 
 ## #walk
@@ -487,7 +487,7 @@ The `#walk` method can recursively walk a schema definition and extract meta dat
 ```ruby
 schema_documentation = create_user_schema.walk do |field|
   {type: field.meta_data[:type], label: field.meta_data[:label]}
-end
+end.output
 
 # Returns
 
@@ -507,7 +507,7 @@ end
 When passed a _symbol_, it will collect that key from field meta data.
 
 ```ruby
-schema_labels = create_user_schema.walk(:label)
+schema_labels = create_user_schema.walk(:label).output
 
 # returns
 
@@ -690,8 +690,7 @@ class CreateUserForm
   attr_reader :errors, :params
 
   def initialize(payload: {})
-    @payload = payload
-    results = self.class.schema.resolve(params)
+    results = self.class.schema.resolve(payload)
     @errors = results.errors
     @params = results.output
   end
@@ -743,6 +742,165 @@ class CreateUserForm
 end
 ```
 
+## Expanding fields dynamically
+
+Sometimes you don't know the exact field names but you want to allow arbitrary fields depending on a given pattern.
+
+```ruby
+# with this payload:
+# {
+#   title: "A title",
+#   :"custom_attr_Color" => "red",
+#   :"custom_attr_Material" => "leather"
+# }
+
+schema = Parametric::Schema.new do
+  field(:title).type(:string).present
+  # here we allow any field starting with /^custom_attr/
+  # this yields a MatchData object to the block
+  # where you can define a Field and validations on the fly
+  # https://ruby-doc.org/core-2.2.0/MatchData.html
+  expand(/^custom_attr_(.+)/) do |match|
+    field(match[1]).type(:string).present
+  end
+end
+
+results = schema.resolve({
+  title: "A title",
+  :"custom_attr_Color" => "red",
+  :"custom_attr_Material" => "leather",
+  :"custom_attr_Weight" => "",
+})
+
+results.ouput[:Color] # => "red"
+results.ouput[:Material] # => "leather"
+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.
+
+## Structs
+
+Structs turn schema definitions into objects graphs with attribute readers.
+
+Add optional `Parametrict::Struct` module to define struct-like objects with schema definitions.
+
+```ruby
+require 'parametric/struct'
+
+class User
+  include Parametric::Struct
+
+  schema do
+    field(:name).type(:string).present
+    field(:friends).type(:array).schema do
+      field(:name).type(:string).present
+      field(:age).type(:integer)
+    end
+  end
+end
+```
+
+`User` objects can be instantiated with hash data, which will be coerced and validated as per the schema definition.
+
+```ruby
+user = User.new(
+  name: 'Joe',
+  friends: [
+    {name: 'Jane', age: 40},
+    {name: 'John', age: 30},
+  ]
+)
+
+# properties
+user.name # => 'Joe'
+user.friends.first.name # => 'Jane'
+user.friends.last.age # => 30
+```
+
+### Errors
+
+Both the top-level and nested instances contain error information:
+
+```ruby
+user = User.new(
+  name: '', # invalid
+  friends: [
+    # friend name also invalid
+    {name: '', age: 40},
+  ]
+)
+
+user.valid? # false
+user.errors['$.name'] # => "is required and must be present"
+user.errors['$.friends[0].name'] # => "is required and must be present"
+
+# also access error in nested instances directly
+user.friends.first.valid? # false
+user.friends.first.errors['$.name'] # "is required and must be valid"
+```
+
+### Nested structs
+
+You can also pass separate struct classes in a nested schema definition.
+
+```ruby
+class Friend
+  include Parametric::Struct
+
+  schema do
+    field(:name).type(:string).present
+    field(:age).type(:integer)
+  end
+end
+
+class User
+  include Parametric::Struct
+
+  schema do
+    field(:name).type(:string).present
+    # here we use the Friend class
+    field(:friends).type(:array).schema Friend
+  end
+end
+```
+
+### Inheritance
+
+Struct subclasses can add to inherited schemas, or override fields defined in the parent.
+
+```ruby
+class AdminUser < User
+  # inherits User schema, and can add stuff to its own schema
+  schema do
+    field(:permissions).type(:array)
+  end
+end
+```
+
+### #to_h
+
+`Struct#to_h` returns the ouput hash, with values coerced and any defaults populated.
+
+```ruby
+class User
+  include Parametrict::Struct
+  schema do
+    field(:name).type(:string)
+    field(:age).type(:integer).default(30)
+  end
+end
+
+user = User.new(name: "Joe")
+user.to_h # {name: "Joe", age: 30}
+```
+
+### Struct equality
+
+`Parametric::Struct` implements `#==()` to compare two structs Hash representation (same as `struct1.to_h.eql?(struct2.to_h)`.
+
+Users can override `#==()` in their own classes to do whatever they need.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/parametric/dsl.rb

@@ -41,6 +41,11 @@ module Parametric
 
         new_schema = Parametric::Schema.new(options, &block)
         @schema = @schema.merge(new_schema)
+        after_define_schema(@schema)
+      end
+
+      def after_define_schema(sc)
+        # noop hook
       end
     end
   end

data/lib/parametric/field.rb

@@ -40,7 +40,7 @@ module Parametric
     def schema(sc = nil, &block)
       sc = (sc ? sc : Schema.new(&block))
       meta schema: sc
-      policy sc
+      policy sc.schema
     end
 
     def visit(meta_key = nil, &visitor)

data/lib/parametric/schema.rb

@@ -11,6 +11,11 @@ module Parametric
       @definitions << block if block_given?
       @default_field_policies = []
       @ignored_field_keys = []
+      @expansions = {}
+    end
+
+    def schema
+      self
     end
 
     def fields
@@ -80,6 +85,11 @@ module Parametric
       end
     end
 
+    def expand(exp, &block)
+      expansions[exp] = block
+      self
+    end
+
     def resolve(payload)
       context = Context.new
       output = coerce(payload, nil, context)
@@ -112,10 +122,13 @@ module Parametric
     def coerce(val, _, context)
       if val.is_a?(Array)
         val.map.with_index{|v, idx|
-          coerce_one(v, context.sub(idx))
+          subcontext = context.sub(idx)
+          out = coerce_one(v, subcontext)
+          resolve_expansions(v, out, subcontext)
         }
       else
-        coerce_one val, context
+        out = coerce_one(val, context)
+        resolve_expansions(val, out, context)
       end
     end
 
@@ -125,10 +138,10 @@ module Parametric
 
     private
 
-    attr_reader :default_field_policies, :ignored_field_keys
+    attr_reader :default_field_policies, :ignored_field_keys, :expansions
 
-    def coerce_one(val, context)
-      fields.each_with_object({}) do |(_, field), m|
+    def coerce_one(val, context, flds: fields)
+      flds.each_with_object({}) do |(_, field), m|
         r = field.resolve(val, context.sub(field.key))
         if r.eligible?
           m[field.key] = r.value
@@ -136,6 +149,27 @@ module Parametric
       end
     end
 
+    class MatchContext
+      def field(key)
+        Field.new(key.to_sym)
+      end
+    end
+
+    def resolve_expansions(payload, into, context)
+      expansions.each do |exp, block|
+        payload.each do |key, value|
+          if match = exp.match(key.to_s)
+            fld = MatchContext.new.instance_exec(match, &block)
+            if fld
+              into.update(coerce_one({fld.key => value}, context, flds: {fld.key => apply_default_field_policies_to(fld)}))
+            end
+          end
+        end
+      end
+
+      into
+    end
+
     def apply_default_field_policies_to(field)
       default_field_policies.reduce(field) {|f, policy_name| f.policy(policy_name) }
     end

data/lib/parametric/struct.rb

@@ -0,0 +1,80 @@
+require 'parametric/dsl'
+
+module Parametric
+  module Struct
+    def self.included(base)
+      base.send(:include, Parametric::DSL)
+      base.extend ClassMethods
+    end
+
+    def initialize(attrs = {})
+      @_results = self.class.schema.resolve(attrs)
+      @_graph = self.class.build(@_results.output)
+    end
+
+    def valid?
+      !_results.errors.any?
+    end
+
+    def errors
+      _results.errors
+    end
+
+    # returns a shallow copy.
+    def to_h
+      _results.output.clone
+    end
+
+    def ==(other)
+      other.respond_to?(:to_h) && other.to_h.eql?(to_h)
+    end
+
+    def merge(attrs = {})
+      self.class.new(to_h.merge(attrs))
+    end
+
+    private
+    attr_reader :_graph, :_results
+
+    module ClassMethods
+      # this hook is called after schema definition in DSL module
+      def after_define_schema(schema)
+        schema.fields.keys.each do |key|
+          define_method key do
+            _graph[key]
+          end
+        end
+      end
+
+      def build(attrs)
+        attrs.each_with_object({}) do |(k, v), obj|
+          obj[k] = wrap(k, v)
+        end
+      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 = Class.new do
+              include Struct
+            end
+            klass.schema = cons
+            klass.after_define_schema(cons)
+            cons = klass
+          end
+          cons ? cons.new(value) : value.freeze
+        when Array
+          value.map{|v| wrap(key, v) }.freeze
+        else
+          value.freeze
+        end
+      end
+    end
+  end
+end

data/lib/parametric/version.rb

@@ -1,3 +1,3 @@
 module Parametric
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/spec/expand_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Parametric::Schema do
+  it "expands fields dynamically" do
+    schema = described_class.new do
+      field(:title).type(:string).present
+      expand(/^attr_(.+)/) do |match|
+        field(match[1]).type(:string)
+      end
+      expand(/^validate_(.+)/) do |match|
+        field(match[1]).type(:string).present
+      end
+    end
+
+    out = schema.resolve({
+      title: "foo",
+      :"attr_Attribute 1" => "attr 1",
+      :"attr_Attribute 2" => "attr 2",
+      :"validate_valid_attr" => "valid",
+      :"validate_invalid_attr" => "",
+    })
+
+    expect(out.output[:title]).to eq 'foo'
+    expect(out.output[:"Attribute 1"]).to eq 'attr 1'
+    expect(out.output[:"Attribute 2"]).to eq 'attr 2'
+
+    expect(out.errors['$.invalid_attr']).to eq ['is required and value must be present']
+  end
+end

data/spec/struct_spec.rb

@@ -0,0 +1,277 @@
+require 'spec_helper'
+require 'parametric/struct'
+
+describe Parametric::Struct do
+  it "works" do
+    friend_class = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:name).type(:string).present
+        field(:age).type(:integer)
+      end
+    end
+
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).default([]).schema friend_class
+      end
+    end
+
+    new_instance = klass.new
+    expect(new_instance.title).to eq ''
+    expect(new_instance.friends).to eq []
+    expect(new_instance.valid?).to be false
+    expect(new_instance.errors['$.title']).not_to be_nil
+
+    instance = klass.new({
+      title: 'foo',
+      friends: [
+        {name: 'Ismael', age: 40},
+        {name: 'Joe', age: 39},
+      ]
+    })
+
+    expect(instance.title).to eq 'foo'
+    expect(instance.friends.size).to eq 2
+    expect(instance.friends.first.name).to eq 'Ismael'
+    expect(instance.friends.first).to be_a friend_class
+
+    invalid_instance = klass.new({
+      friends: [
+        {name: 'Ismael', age: 40},
+        {age: 39},
+      ]
+    })
+
+    expect(invalid_instance.valid?).to be false
+    expect(invalid_instance.errors['$.title']).not_to be_nil
+    expect(invalid_instance.errors['$.friends[1].name']).not_to be_nil
+    expect(invalid_instance.friends[1].errors['$.name']).not_to be_nil
+  end
+
+  it "is inmutable by default" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).default([])
+        field(:friend).type(:object)
+      end
+    end
+
+    instance = klass.new
+    expect {
+      instance.title = "foo"
+    }.to raise_error NoMethodError
+
+    expect {
+      instance.friends << 1
+    }.to raise_error RuntimeError
+  end
+
+  it "works with anonymous nested schemas" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).schema do
+          field(:age).type(:integer)
+        end
+      end
+    end
+
+    instance = klass.new({
+      title: 'foo',
+      friends: [
+        {age: 10},
+        {age: 39},
+      ]
+    })
+
+    expect(instance.title).to eq 'foo'
+    expect(instance.friends.size).to eq 2
+    expect(instance.friends.first.age).to eq 10
+  end
+
+  it "wraps regular schemas in structs" do
+    friend_schema = Parametric::Schema.new do
+      field(:name)
+    end
+
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).schema friend_schema
+      end
+    end
+
+    instance = klass.new({
+      title: 'foo',
+      friends: [{name: 'Ismael'}]
+    })
+
+    expect(instance.friends.first.name).to eq 'Ismael'
+  end
+
+  it "#to_h" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).schema do
+          field(:name).type(:string)
+          field(:age).type(:integer).default(20)
+        end
+      end
+    end
+
+    instance = klass.new({
+      title: 'foo',
+      friends: [
+        {name: 'Jane'},
+        {name: 'Joe', age: '39'},
+      ]
+    })
+
+    expect(instance.to_h).to eq({
+      title: 'foo',
+      friends: [
+        {name: 'Jane', age: 20},
+        {name: 'Joe', age: 39},
+      ]
+    })
+
+    new_instance = klass.new(instance.to_h)
+    expect(new_instance.title).to eq 'foo'
+
+    # it returns a copy so we can't break things!
+    data = new_instance.to_h
+    data[:title] = 'nope'
+    expect(new_instance.to_h[:title]).to eq 'foo'
+  end
+
+  it "works with inheritance" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).schema do
+          field(:name).type(:string)
+          field(:age).type(:integer).default(20)
+        end
+      end
+    end
+
+    subclass = Class.new(klass) do
+      schema do
+        field(:email)
+      end
+    end
+
+    instance = subclass.new(
+      title: 'foo',
+      email: 'email@me.com',
+      friends: [
+        {name: 'Jane', age: 20},
+        {name: 'Joe', age: 39},
+      ]
+    )
+
+    expect(instance.title).to eq 'foo'
+    expect(instance.email).to eq 'email@me.com'
+    expect(instance.friends.size).to eq 2
+  end
+
+  it "implements deep struct equality" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:friends).type(:array).schema do
+          field(:age).type(:integer)
+        end
+      end
+    end
+
+    s1 = klass.new({
+      title: 'foo',
+      friends: [
+        {age: 10},
+        {age: 39},
+      ]
+    })
+
+
+    s2 = klass.new({
+      title: 'foo',
+      friends: [
+        {age: 10},
+        {age: 39},
+      ]
+    })
+
+    s3 = klass.new({
+      title: 'foo',
+      friends: [
+        {age: 11},
+        {age: 39},
+      ]
+    })
+
+    s4 = klass.new({
+      title: 'bar',
+      friends: [
+        {age: 10},
+        {age: 39},
+      ]
+    })
+
+    expect(s1 == s2).to be true
+    expect(s1 == s3).to be false
+    expect(s1 == s4).to be false
+  end
+
+  it "#merge returns a new instance" do
+    klass = Class.new do
+      include Parametric::Struct
+
+      schema do
+        field(:title).type(:string).present
+        field(:desc)
+        field(:friends).type(:array).schema do
+          field(:name).type(:string)
+        end
+      end
+    end
+
+    original = klass.new(
+      title: 'foo',
+      desc: 'no change',
+      friends: [{name: 'joe'}]
+    )
+
+    copy = original.merge(
+      title: 'bar',
+      friends: [{name: 'jane'}]
+    )
+
+    expect(original.title).to eq 'foo'
+    expect(original.desc).to eq 'no change'
+    expect(original.friends.first.name).to eq 'joe'
+
+    expect(copy.title).to eq 'bar'
+    expect(copy.desc).to eq 'no change'
+    expect(copy.friends.first.name).to eq 'jane'
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parametric
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Ismael Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-29 00:00:00.000000000 Z
+date: 2018-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,14 +96,17 @@ files:
 - lib/parametric/registry.rb
 - lib/parametric/results.rb
 - lib/parametric/schema.rb
+- lib/parametric/struct.rb
 - lib/parametric/version.rb
 - parametric.gemspec
 - spec/dsl_spec.rb
+- spec/expand_spec.rb
 - spec/field_spec.rb
 - spec/policies_spec.rb
 - spec/schema_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb
+- spec/struct_spec.rb
 - spec/validators_spec.rb
 homepage: ''
 licenses:
@@ -125,16 +128,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: DSL for declaring allowed parameters with options, regexp patern and default
   values.
 test_files:
 - spec/dsl_spec.rb
+- spec/expand_spec.rb
 - spec/field_spec.rb
 - spec/policies_spec.rb
 - spec/schema_spec.rb
 - spec/schema_walk_spec.rb
 - spec/spec_helper.rb
+- spec/struct_spec.rb
 - spec/validators_spec.rb