dto_schema 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04216668970682a3eaa4bc062784a6d977dbd1e6e795bf30904e28aa48715b8
-  data.tar.gz: 94151a67d6deecf1b3cc0b799b4b0b23efb945c61e4d79d5d84bfe16144dc6c4
+  metadata.gz: a767f94c364d3093e4c335a8a50e66cf93c774d840c6300eed506c4e8bbc2566
+  data.tar.gz: 5bbbfd55ba7887b3130f7bbbfa42768be731b3bad9f8030f9b1b16a9c54713c0
 SHA512:
-  metadata.gz: c201e08d594b7b2d6b9caa0fa596101d41e5a40a52bc700e0673fae1f20e8461565ba457ddb4b2b80cd9915127c3cbafbfd828205d94e1bc5db51777dda8dea0
-  data.tar.gz: c7da82328e46a70b91d6ee466c0efd0ae02f52ce8724663fe2ef92010354feb9783f79be68eee3745acfd483d4de3020faed11f24a6bfbf89926263464ec4c49
+  metadata.gz: 5427d6ea29d2096a6fbf06cec0cfa82aeea1dc3951d51d42055e6bdbda6436eee2f0d6300adf4431e774f565e6838ec0babca4a701af8c979090b2be678cb14b
+  data.tar.gz: 95b5de458d50891e2360c6c21c3a1b3bb2f4501dc080b3762abb1b423244c25eba7f461bc5a7e4f46f1e8f7734f57960ebf26cc6d996e7f98a67b7252481ce05

data/README.md

@@ -11,15 +11,16 @@ DTO-Schema is a small Ruby library to validate simple data.
 gem install dto_schema
 ```
 
-## What is validated?
+## What is being validated?
 
-A notion of `Simple Data` could be defined as follows: 
-* `nil` is a simple data
-* `String` is a simple data
-* `Numeric` is a simple data
-* Boolean is a simple data
-* `Array` of simple data is a simple data
-* `Hash` with symbolic keys and simple-data values is a simple data
+DTO-Schema validates a _"simple data"_. 
+A notion of _"simple data"_ could be defined as follows: 
+* `nil` is a _simple data_
+* `String` is a _simple data_
+* `Numeric` is a _simple data_
+* Boolean is a _simple data_
+* `Array` of _simple data_ is a _simple data_ itself
+* `Hash` with symbolic keys and _simple-data_ values is a _simple data_ itself
 
 ## Example 
 
@@ -35,7 +36,6 @@ schema = DTOSchema::define do
   
     object :post do
         required :title, String, check: [:not_empty]
-        required :body, String, check: [:not_empty]
         optional :tags, list[:tag]
     end
   
@@ -49,12 +49,320 @@ And then use it to validate data:
 ```ruby
 require 'json'
 
-data = JSON.parse('{"title": 42, "tags":[42, {"name":"", "value":"foo"}]}', symbolize_names: true)
+data = JSON.parse('{"tags":[42, {"name":"", "value":"foo"}]}', symbolize_names: true)
 p schema.post.validate data
 ```
 
 And result will be:
 ```
-{:title=>["Must be a String"], :body=>["Cannot be null"], :tags=>{0=>["Must be object"], 1=>{:name=>["Cannot be empty"]}}}
+{:title=>["Cannot be null"], :tags=>{0=>["Must be object"], 1=>{:name=>["Cannot be empty"]}}}
 ```
 
+## Usage
+
+* [Creating a schema](#creating-a-schema)
+* [Defining a DTO type](#defining-a-dto-type)
+* [Validating data](#validating-data)
+* [Inline checks](#inline-checks)
+* [Reusing checks](#reusing-checks)
+* [Parametrized checks](#parametrized-checks)
+* [Referencing one DTO from another](#referencing-one-dto-from-another)
+* [List as attribute type](#list-as-attribute-type)
+* [List as DTO](#list-as-dto)
+* [Invariants](#invariants)
+* [Using Bool and Any](#using-bool-and-any)
+
+### Creating a schema
+
+DTO-Schema is defined with `DTOSchema::define` method
+```ruby
+require 'dto_schema'
+
+schema = DTOSchema::define do
+    # schema definition goes here ... 
+end
+```
+
+### Defining a DTO type
+
+Use the `object <name> do <definition> end` method to define a new DTO type:
+```ruby
+require 'dto_schema'
+
+schema = DTOSchema::define do
+  object :post do
+    required :title, String 
+    optional :body, String
+  end
+end
+```
+Each DTO definition provides `required` and `optional` method to declare DTO attributes.
+
+The schema above defines `post` DTO with optional attribute `body` and required attribute `title`.
+
+### Validating data
+
+For each defined DTO schema provides a number of dynamically-generated methods to access it. 
+For example if we define a `post` DTO as shown above, the schema will have the 
+following methods:
+* `post` - to get the *post*-validator
+* `post? (data)` - to check if the data has a valid structure 
+(equivalent of `schema.post.valid_structure? data`, more on this later)
+* `valid_post? (data)` - to check if data is a valid `post` DTO (a short-hand of `schema.post.valid? data`)
+* `validate_post (data)` - get the data validation errors (a short-hand of `schema.post.validate data`)
+
+For example:
+```ruby
+data = {
+  body: 42
+}
+p schema.validate_post data
+```
+```
+{:body=>["Must be a String"], :title=>["Cannot be null"]}
+```
+
+### Inline checks
+To apply a custom checks to a DTO attributes, `required` and `optional` methods accept
+an optional block which is called during validation with an attribute value as an argument. 
+
+A block must return either an Array of error-messages, a single error message or `nil`.
+
+Example:
+```ruby
+schema = DTOSchema::define do
+  object :post do
+    required :title, String do |value|
+      next "Cannot be empty" if value.empty?
+    end
+
+    optional :body, String do |value|
+      next "Cannot be empty" if value.empty?
+    end
+  end
+end
+```
+```ruby
+data = {
+    title: true,
+    body: ""
+}
+p schema.validate_post data
+```
+```
+{:title=>["Must be a String"], :body=>["Cannot be empty"]}
+```
+
+### Reusing checks
+
+You can define and reuse checks using a `check` method. 
+Each attribute may have any number of checks.
+```ruby
+schema = DTOSchema::define do
+  object :post do
+    required :title, String, check: :not_empty
+    optional :body, String, check: [:not_empty]
+  end
+
+  check :not_empty do |value|
+    next "Cannot be empty" if value.empty?
+  end
+end
+```
+This is an equivalent of the previous example. 
+
+### Parametrized checks
+
+Sometimes it is useful to define a parametrized checks. It could be done like this:
+```ruby
+schema = DTOSchema::define do
+  object :post do
+    required :title, String, check: check.length(min: 3)
+    optional :body, String, check: check.length(max: 2)
+  end
+
+  check :length do |value, min: 0, max: nil|
+    next "Must contain at least #{min} chars" if value.size < min
+    next "Must contain at max #{max} chars" if !max.nil? && value.size > max
+  end
+end
+```
+```ruby
+data = {
+    title: "hi",
+    body: "foo"
+}
+p schema.validate_post data
+```
+```
+{:title=>["Must contain at least 3 chars"], :body=>["Must contain at max 2 chars"]}
+```
+
+### Referencing one DTO from another
+
+You may define any number of DTOs and embed one into another. 
+To do that you simply use dto name as an attribute type.
+```ruby
+schema = DTOSchema::define do
+  object :book_details do
+    required :pages, Numeric
+    required :author, String
+    required :language, String
+  end
+
+  object :book do
+    required :title, String
+    required :text, String
+    required :details, :book_details
+  end
+end
+```
+```ruby
+data = {
+    title: "Moby-Dick",
+    text: "Call me Ishmael...",
+    details: {
+        author: "Herman Melville",
+        pages: 768,
+    }
+}
+p schema.validate_book data
+```
+```
+{:details=>{:language=>["Cannot be null"]}}
+```
+
+### List as attribute type
+
+DTO-Schema provides a `list` method to define list-attributes:
+```ruby
+schema = DTOSchema::define do
+  object :book do
+    required :title, String
+    required :pages, list[String]
+  end
+end
+```
+```ruby
+data = {
+    title: "Moby-Dick",
+    pages: ["Call me Ishmael...", 42]
+}
+p schema.validate_book data
+```
+```
+{:pages=>{1=>["Must be a String"]}}
+```
+
+You may reference any DTO as a list item type:
+```ruby
+schema = DTOSchema::define do
+  object :tree do
+    required :value, Numeric
+    optional :child, list[:tree]
+  end
+end
+```
+```ruby
+data = {
+    value: 42,
+    child: [
+        {
+            value: 12
+        },
+        {
+            value: "wrong!"
+        }
+    ]
+}
+p schema.validate_tree data
+```
+```
+{:child=>{1=>{:value=>["Must be a Numeric"]}}}
+```
+List item type may be any valid type including list itself: `list[list[Numeric]]`.
+
+### List as DTO
+
+DTO-Schema allows to declare list as independent DTO type
+```ruby
+schema = DTOSchema::define do
+  object :polygon do
+    required :name, String
+    optional :vertices, list[:point]
+  end
+
+  list :point, Float do |items|
+    next "Must contain exactly 2 items" unless items.size == 2
+  end
+end
+```
+```ruby
+data = {
+    name: "My Polygon",
+    vertices: [
+        [1.0, 2.0],
+        [5.0]
+    ],
+}
+p schema.validate_polygon data
+p schema.point? [1.0, 2.0]
+```
+```
+{:vertices=>{1=>["Must contain exactly 2 items"]}}
+true
+```
+
+### Invariants
+Sometimes it is useful to check some invariants across DTO attributes. 
+To declare such validation DTO-Schema provides an `invariant (fields, &block)` method. 
+```ruby
+schema = DTOSchema::define do
+  object :new_account do
+    required :password, String
+    required :confirm_password, String
+
+    invariant :confirm_password do |data|
+      next "Passwords must be equal" if data[:password] != data[:confirm_password]
+    end
+  end
+end
+```
+```ruby
+data = {
+    password: "foo",
+    confirm_password: "bar",
+}
+p schema.validate_new_account data
+```
+```
+{:confirm_password=>["Passwords must be equal"]}
+```
+
+### Using Bool and Any
+
+Ruby doesn't have a single class for boolean values (instead it has `TrueClass` and `FalseClass`). 
+DTO-Schema provides a `bool` method to expect boolean attribute type. 
+
+Sometimes we want to verify that some attribute is presented whatever value it has. For this purpose
+DTO-Schema provides an `any` method that could be used as attribute type. 
+```ruby
+schema = DTOSchema::define do
+  object :envelope do
+    required :custom_data, any
+    required :flags, list[bool]
+  end
+end
+```
+```ruby
+data = {
+    custom_data: {
+        anything: "whatever"
+    },
+    flags: [true, false, 42]
+}
+p schema.validate_envelope data
+```
+```
+{:flags=>{2=>["Must be boolean"]}}
+```

data/dto_schema.gemspec

@@ -13,4 +13,5 @@ Gem::Specification.new do |s|
   s.files       = %w(dto_schema.gemspec) + Dir["*.md", "lib/**/*.rb"]
   s.homepage    = 'https://github.com/stepan-anokhin/dto-schema'
   s.license     = 'MIT'
+  s.required_ruby_version = ">= 2.2.10"
 end

data/lib/dto_schema/checks.rb

@@ -1,11 +1,13 @@
 module DTOSchema
   module Checks
 
+    # A custom DTO-attribute validation
     class Check
       def initialize (check)
         @check = check
       end
 
+      # Validate attribute value
       def validate (data, args = nil)
         result = @check.call(data) if args.nil?
         result = @check.call(data, args) unless args.nil?
@@ -14,52 +16,76 @@ module DTOSchema
         []
       end
 
+      # Ensure check doesn't have dangling references
       def resolve
-        self
+        self # simple Check never has references
       end
     end
 
+    # A dynamic reference to a custom Check
     class CheckReference
       def initialize (schema, ref, args = nil)
         @schema, @ref = schema, ref
         @args = args
       end
 
+      # Validate attribute value
       def validate (data, args = nil)
         resolve.validate data, args
       end
 
+      # Get the referent check
       def resolve
         @schema.resolve_check @ref
       end
     end
 
+    # A validation check with bound key-word arguments.
+    #
     class BoundCheck
       def initialize (check, args)
         @check = check
         @args = args
       end
 
+      # Validate attribute value
       def validate (data, args = {})
         args = @args.merge(args)
-        @check.validate data, args
+        @check.validate data, args # pass predefined kw-args
       end
 
+      # Ensure the underlying check doesn't have dangling references
       def resolve
         @check.resolve
       end
     end
 
+    # It provides check-binding API:
+    #   check.length(min: 2, max: 3)
     class CheckBinder
       def initialize (schema)
         @schema = schema
       end
 
+      # Bind a check by its name passed as dynamic method name.
+      # It is this method that implements check-binding API in schema definition.
       def method_missing (name, args = {})
         check = CheckReference.new @schema, name
         BoundCheck.new check, args
       end
     end
 
+    def self.create_check (spec, schema)
+      return spec if spec.is_a? Checks::BoundCheck
+      return Checks::CheckReference.new schema, spec if spec.is_a? Symbol
+      raise ArgumentError, "Unexpected check type: #{spec.class}"
+    end
+
+    def self.parse_checks(checks, schema)
+      checks ||= []
+      checks = [checks] if checks.is_a?(Symbol) || checks.is_a?(BoundCheck)
+      checks.collect { |spec| Checks::create_check(spec, schema) }
+    end
+
   end
 end

data/lib/dto_schema/schema.rb

@@ -13,6 +13,7 @@ module DTOSchema
     end
   end
 
+
   class Schema
     def initialize(&block)
       @validators = {}
@@ -22,15 +23,44 @@ module DTOSchema
     end
 
     def define (&block)
-      self.instance_eval &block unless block.nil?
+      raise ArgumentError, "Block is expected" if block.nil?
+      builder = Builder.new self
+      builder.instance_eval &block
       resolve
     end
 
-    def object(name, &definition)
-      validator = Validators::ObjectValidator.new self
-      validator.instance_eval(&definition)
+    def define_validator(name, validator)
       @validators[name] = validator
+      generate_methods(name, validator)
+    end
+
+    def define_check(name, check)
+      @checks[name] = check
+    end
+
+    def bind_check
+      @check_binder
+    end
+
+    def resolve
+      @validators.each_value { |validator| validator.resolve }
+      @checks.each_value { |check| check.resolve }
+      self
+    end
+
+    def resolve_validator (name)
+      raise NameError, "Undefined validator `#{name}'" unless @validators.include? name
+      @validators[name]
+    end
+
+    def resolve_check (name)
+      raise NameError, "Undefined check `#{name}'" unless @checks.include? name
+      @checks[name]
+    end
+
+    private
 
+    def generate_methods (name, validator)
       self.define_singleton_method(name) do
         validator
       end
@@ -46,37 +76,37 @@ module DTOSchema
       self.define_singleton_method("valid_#{name}?".to_sym) do |data|
         validator.valid? data
       end
-
-      validator
-    end
-
-    def list
-      Validators::ListValidator.new self, Validators::AnyValidator.new
     end
 
-    def check(name = nil, &body)
-      return @check_binder if name.nil? && body.nil?
-      raise ArgumentError, "Check definition name is not provided" if name.nil?
-      raise ArgumentError, "Check definition is not provided for `#{name}`" if body.nil?
-      result = Checks::Check.new(body)
-      @checks[name] = result
-      result
-    end
+    class Builder
+      def initialize(schema)
+        @schema = schema
+      end
 
-    def resolve
-      @validators.each_value { |validator| validator.resolve }
-      @checks.each_value { |check| check.resolve }
-      self
-    end
+      def object(name, &definition)
+        validator = Validators::ObjectValidator.new @schema
+        builder = Validators::ObjectValidator::Builder.new @schema, validator
+        builder.instance_eval(&definition)
+        @schema.define_validator(name, validator)
+        validator
+      end
 
-    def resolve_validator (name)
-      raise NameError, "Undefined validator `#{name}'" unless @validators.include? name
-      @validators[name]
-    end
+      def list(name, item_type, check: nil, &predicate)
+        check = Checks::parse_checks check, @schema
+        check << Checks::Check.new(predicate) unless predicate.nil?
+        item_validator = Validators::Parse::parse_validator item_type, @schema
+        validator = Validators::ListValidator.new @schema, item_validator, check
+        @schema.define_validator(name, validator)
+        validator
+      end
 
-    def resolve_check (name)
-      raise NameError, "Undefined check `#{name}'" unless @checks.include? name
-      @checks[name]
+      def check(name = nil, &body)
+        raise ArgumentError, "Check definition name is not provided" if name.nil?
+        raise ArgumentError, "Check definition is not provided for `#{name}`" if body.nil?
+        result = Checks::Check.new(body)
+        @schema.define_check(name, result)
+        result
+      end
     end
   end
 end

data/lib/dto_schema/validators.rb

@@ -7,30 +7,6 @@ module DTOSchema
       def resolve
         self
       end
-
-      protected
-
-      def resolve_validator (spec)
-        return PrimitiveValidator.new(spec) if primitive? spec
-        return spec if validator? spec
-        resolve_reference spec if reference? spec
-      end
-
-      def primitive? (spec)
-        spec.is_a?(Class) && (spec <= Numeric || spec <= String)
-      end
-
-      def validator? (spec)
-        spec.is_a? BaseValidator
-      end
-
-      def reference? (spec)
-        spec.is_a? Symbol
-      end
-
-      def resolve_reference (ref)
-        ValidatorReference.new @schema, ref
-      end
     end
 
     class BoolValidator < BaseValidator
@@ -44,6 +20,8 @@ module DTOSchema
       end
 
       alias :valid_structure? :valid?
+
+      INSTANCE = BoolValidator.new
     end
 
     class AnyValidator < BaseValidator
@@ -51,11 +29,13 @@ module DTOSchema
         true
       end
 
-      def validate
+      def validate (data)
         []
       end
 
       alias :valid_structure? :valid?
+
+      INSTANCE = AnyValidator.new
     end
 
     class PrimitiveValidator < BaseValidator
@@ -98,8 +78,9 @@ module DTOSchema
     end
 
     class ListValidator < BaseValidator
-      def initialize(schema, item_validator)
+      def initialize(schema, item_validator, checks = nil)
         @schema, @item_validator = schema, item_validator
+        @checks = checks || []
       end
 
       def valid? (data)
@@ -113,35 +94,46 @@ module DTOSchema
           errors = @item_validator.validate value
           result[i] = errors unless errors.empty?
         end
-        result
+        return result unless result.empty?
+        @checks.each do |check|
+          errors = check.validate data
+          return errors unless errors.empty?
+        end
+        {}
       end
 
       def valid_structure? (data)
         data.is_a?(Array) && data.all? { |item| @item_validator.valid_structure? item }
       end
 
-      def [] (spec)
-        validator = resolve_validator spec
-        ListValidator.new @schema, validator
-      end
-
       def resolve
         @item_validator.resolve
         self
       end
+
+      class Builder
+        def initialize(schema)
+          @schema = schema
+        end
+
+        def [] (spec)
+          validator = Parse::parse_validator spec, @schema
+          ListValidator.new @schema, validator
+        end
+      end
     end
 
     class FieldValidator < BaseValidator
       def initialize(schema, name, required, type, check)
-        raise ArgumentError, "'#{name}' cannot have checks as it is not a primitive" unless check.empty? || primitive?(type)
+        raise ArgumentError, "'#{name}' cannot have checks as it is not a primitive" unless check.empty? || Parse::primitive?(type)
         @schema, @name, @required, @type, @check = schema, name, required, type, check
-        @type_validator = resolve_validator type
+        @type_validator = Parse::parse_validator type, @schema
       end
 
       def validate (data)
         return ["Cannot be null"] if @required && data.nil?
         return [] if !@required && data.nil?
-        return @type_validator.validate data unless primitive? @type
+        return @type_validator.validate data unless Parse::primitive? @type
         type_check = @type_validator.validate data
         return type_check unless type_check.empty?
         @check.collect { |check| check.validate data }.flatten(1)
@@ -186,22 +178,6 @@ module DTOSchema
         @invariants = []
       end
 
-      def field (name, required: false, type: AnyValidator.new, check: nil, &validations)
-        check ||= []
-        check = [check] if check.is_a?(Symbol) || check.is_a?(Checks::BoundCheck)
-        check = check.collect { |check_spec| resolve_check check_spec }
-        check.append(Check.new validations) unless validations.nil?
-        @fields[name] = FieldValidator.new @schema, name, required, type, check
-      end
-
-      def required(name, type, check: nil, &validations)
-        field(name, required: true, type: type, check: check, &validations)
-      end
-
-      def optional(name, type, check: nil, &validations)
-        field(name, required: false, type: type, check: check, &validations)
-      end
-
       def validate (data)
         return ["Cannot be null"] if data.nil?
         return ["Must be object"] unless data.is_a? Hash
@@ -227,18 +203,12 @@ module DTOSchema
         @fields.all? { |name, validator| validator.valid_structure? data[name] }
       end
 
-      def list
-        @schema.list
-      end
-
-      def check
-        @schema.check
+      def define_invariant(invariant)
+        @invariants << invariant
       end
 
-      def invariant (fields = nil, &block)
-        fields = [] if fields.nil?
-        fields = [fields] if fields.is_a? Symbol
-        @invariants << Invariant.new(fields, block)
+      def define_field(name, field)
+        @fields[name] = field
       end
 
       def resolve
@@ -246,15 +216,69 @@ module DTOSchema
         self
       end
 
-      private
+      class Builder
+        def initialize(schema, validator)
+          @schema = schema
+          @validator = validator
+        end
+
+        def field (name, required: false, type: AnyValidator::INSTANCE, check: nil, &validations)
+          check = Checks::parse_checks check, @schema
+          check << Checks::Check.new(validations) unless validations.nil?
+          field = FieldValidator.new(@schema, name, required, type, check)
+          @validator.define_field(name, field)
+        end
 
-      def resolve_check (check)
-        return check if check.is_a? Checks::BoundCheck
-        return Checks::CheckReference.new @schema, check if check.is_a? Symbol
-        raise ArgumentError, "Unexpected check type: #{check.class}"
+        def required(name, type, check: nil, &validations)
+          field(name, required: true, type: type, check: check, &validations)
+        end
+
+        def optional(name, type, check: nil, &validations)
+          field(name, required: false, type: type, check: check, &validations)
+        end
+
+        def list
+          ListValidator::Builder.new @schema
+        end
+
+        def bool
+          BoolValidator::INSTANCE
+        end
+
+        def any
+          AnyValidator::INSTANCE
+        end
+
+        def check
+          @schema.bind_check
+        end
+
+        def invariant (fields = nil, &block)
+          fields = [] if fields.nil?
+          fields = [fields] if fields.is_a? Symbol
+          @validator.define_invariant Invariant.new(fields, block)
+        end
       end
     end
 
+    module Parse
+      def self.parse_validator (spec, schema)
+        return PrimitiveValidator.new(spec) if primitive? spec
+        return spec if validator? spec
+        ValidatorReference.new(schema, spec) if reference? spec
+      end
+
+      def self.primitive? (spec)
+        spec.is_a?(Class) && (spec <= Numeric || spec <= String)
+      end
+
+      def self.validator? (spec)
+        spec.is_a? BaseValidator
+      end
 
+      def self.reference? (spec)
+        spec.is_a? Symbol
+      end
+    end
   end
 end

data/lib/dto_schema/version.rb

@@ -1,3 +1,3 @@
 module DTOSchema
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dto_schema
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Stepan Anokhin
@@ -36,7 +36,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.2.10
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="