definition 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b16eba88381d8ea5594b51e4855b3ca4f0684196bf552f5498a5eb43f67458bd
-  data.tar.gz: 238611bb117e46b6701fae5d6236b66ab9754424dd88a6363dd091601ee2b249
+  metadata.gz: 9e79beba1853328e9b03847f3b8f9b3a088d381965cba2fd1ccedd283b57bd0c
+  data.tar.gz: b0835b29633b6887e39bbb6b6d34146c6870a13ab82415492e70050a9727831c
 SHA512:
-  metadata.gz: e4a1d3d64e85ba1a43356adf08413a6469d8f0f59acf35f395c43adc44320557e562a90b54c49f51236664ce94201f65b18a8e9c288edb709cf3ab85102dc12c
-  data.tar.gz: 3e753b50686933ddb0c83afbcd394ce0a98b5f16fe9cee7799df94f3b968489f6e0828332b01f4c444ccc86ca575f3af27e6b35a34f391306c5328f721ee2906
+  metadata.gz: ca5aae1db840f6ee3b45fd59cf8698a66a83a5d40d7f5f06be1413c0ce40ee979932382e4e3c866423faffda6a113f6f926053b84a76bd5986ba68eb37cda2f8
+  data.tar.gz: 86c2aad58a186b58f71f43f4e5a137ced0e2f472d1ee5bcd970045b76e252fa6ef2b258e005d9ffa169b0cbe7dea028d6e4ec3cda21dd38d4e23dc337e3ad330

data/.gitignore

@@ -10,3 +10,4 @@
 *.swp
 .approvals
 spec/examples.txt
+tags

data/Changelog.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [0.8.0] - 2022-10-05
+### Added
+- A Definition::Initializer mixin that can be used to validate keyword arguments of a class constructor
+
+### Changes
+- Include more information in the internal non-translated error messages. E.g. the max size of a LessThenEqual definition
+- Renamed GreaterThen, GreaterThenEqual, LessThen and LessThenEqual to fix typo (Then VS Than) Backwards compatibility is ensured
+
+### Breaking changes
+- The Definition::ValueObject was removed and replaced by Definition:Model which has a nicer DSL and only works with hash data structures. See [upgrade notes](./UpgradeNotes.md)
+
 ## [0.7.1] - 2022-03-04
 ### Fixed
 - Float coercion: check for nil before coercion

data/Gemfile.lock

@@ -1,26 +1,27 @@
 PATH
   remote: .
   specs:
-    definition (0.7.1)
+    definition (0.8.0)
       activesupport
       i18n
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.2.2)
+    activesupport (7.0.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
-    approvals (0.0.25)
+    approvals (0.0.26)
+      json (~> 2.0)
       nokogiri (~> 1.8)
       thor (~> 1.0)
     ast (2.4.2)
     awesome_print (1.9.2)
     benchmark-ips (2.10.0)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     diff-lcs (1.5.0)
     ffi (1.15.5)
     formatador (1.1.0)
@@ -41,37 +42,38 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.10.0)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
+    json (2.6.2)
     listen (3.7.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     lumberjack (1.2.8)
     method_source (1.0.0)
     mini_portile2 (2.8.0)
-    minitest (5.15.0)
+    minitest (5.16.3)
     nenv (0.3.0)
-    nokogiri (1.13.3)
+    nokogiri (1.13.8)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
-    nokogiri (1.13.3-x86_64-linux)
+    nokogiri (1.13.8-x86_64-linux)
       racc (~> 1.4)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    parallel (1.21.0)
-    parser (3.1.0.0)
+    parallel (1.22.1)
+    parser (3.1.2.1)
       ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    psych (4.0.3)
+    psych (4.0.6)
       stringio
     racc (1.6.0)
     rainbow (3.1.1)
     rake (13.0.6)
-    rb-fsevent (0.11.1)
+    rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     rspec (3.11.0)
@@ -80,17 +82,17 @@ GEM
       rspec-mocks (~> 3.11.0)
     rspec-core (3.11.0)
       rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec-expectations (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
     rspec-its (1.3.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
-    rspec-mocks (3.11.0)
+    rspec-mocks (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rspec_junit_formatter (0.5.1)
+    rspec-support (3.11.1)
+    rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
     rubocop (0.66.0)
       jaro_winkler (~> 1.5.1)
@@ -105,10 +107,10 @@ GEM
     rubocop_runner (2.2.0)
     ruby-progressbar (1.11.0)
     shellany (0.0.1)
-    stringio (3.0.1)
+    stringio (3.0.2)
     thor (1.2.1)
-    timecop (0.9.4)
-    tzinfo (2.0.4)
+    timecop (0.9.5)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.5.0)
 

data/README.md

@@ -42,7 +42,7 @@ conform_result.error_hash # =>
 # {
 #     :birthday => [
 #         [0] <Definition::ConformError
-#               desciption: "hash fails validation for key birthday: { Is of type String instead of Date }",
+#               description: "hash fails validation for key birthday: { Is of type String instead of Date }",
 #               json_pointer: "/birthday">
 #     ]
 # }
@@ -71,66 +71,60 @@ conform_result.value # => {title: "My first blog post", body: "Shortest one ever
 Because definitions do not only validate input but also transform input, we use
 the term `conform` which stands for validation and coercion.
 
-### Value Objects
+### Handling errors
 
-```ruby
-class User < Definition::ValueObject
-  definition(Definition.Keys do
-    required :username, Definition.Type(String)
-    required :password, Definition.Type(String)
-  end)
-end
-
-user = User.new(username: "johndoe", password: "zg(2ds8x2/")
-user.username # => "johndoe"
-user[:username] # => "johndoe"
-user.username = "Alice" # => NoMethodError (ValueObjects are immutable)
-user[:username] = "Alice" # => FrozenError (ValueObjects are immutable)
-
-User.new(username: "johndoe") # => Definition::InvalidValueObjectError: hash does not include :password
-```
-
-Value objects delegate all calls to the output value of the defined definition,
-so in this example you can use all methods that are defined on `Hash` also on the
-user object. If you use a `Keys` definition, the value object additionally defines
-convenient accessor methods for all attributes.
-
-Value Objects can also be used for all other data structures that can be validated
-by a definition, for example arrays:
+#### I18n translated errors
+For end users you best use the translated errors that you get from definition:
 
 ```ruby
-class IntegerArray < Definition::ValueObject
-  definition(Definition.Each(Definition.Type(Integer)))
+schema = Definition.Keys do
+  required :title, Definition.NonEmptyString
+  required :body, Definition::And(
+                    Definition.Type(String),
+                    Definition.MinSize(100)
+                  )
 end
 
-array = IntegerArray.new([1,2,3])
-array.first # => 1
-
-IntegerArray.new([1,2,"3"]) # => Definition::InvalidValueObjectError: Not all items conform with each: { Item "3" did not conform to each: { Is of type String instead of Integer } }
+conform_result = schema.conform({title: "", body: "this is not long enough"})
+conform_result.errors # => returns an array of Definition::ConformError
+conform_result.errors.each do |error|
+  puts "----"
+  puts error.json_pointer # provides a path to the invalid value, also works with nested objects and arrays
+  puts error.translated_error
+end
+# =>
+# ----
+# /title
+# Value is shorter than 1
+# ----
+# /body
+# Value is shorter than 100
 ```
 
-You can access the conform result object via `InvalidValueObjectError#conform_result`
+The error messages are only translated into English for now, but you can add or change translations by adding a yaml file like [this](./config/locales/en.yml) to your I18n load path.
 
-#### Nesting value Objects
+#### Other ways of accessing errors
 
-Value objects can be nested by either using the value object itself as type definition,
-or by using the `CoercibleValueObject` Definition. The latter would convert input
-hashes that conform with the value objects schema to an instance of the value object.
+To get a quick error summary during debugging, you can also use `conform_result.error_message`
 
-```ruby
-class IntegerArray < Definition::ValueObject
-  definition(Definition.Each(Definition.Type(Integer)))
-end
+Instead of getting a flat array of all errors via `conform_result.errors`, you can also get a hierarchical representation:
 
-class User < Definition::ValueObject
-  definition(Definition.Keys do
-    required :username, Definition.Type(String)
-    required :scores, Definition.CoercibleValueObject(IntegerArray)
-  end)
-end
+```ruby
+conform_result.error_hash
+# =>
+# {
+#     :title => [
+#         [0] <Definition::ConformError 
+# 	 message: "hash fails validation for key title: { Not all definitions are valid for 'non_empty_string': { Did not pass test for min_size (1) } }", 
+# 	 json_pointer: "/title">
+#     ],
+#      :body => [
+#         [0] <Definition::ConformError 
+# 	 message: "hash fails validation for key body: { Not all definitions are valid for 'and': { Did not pass test for min_size (100) } }", 
+# 	 json_pointer: "/body">
+#     ]
+# }
 
-object = User.new(username: "John", scores: [1,2,3])
-object.scores.class.name # => IntegerArray
 ```
 
 ### Conforming Hashes
@@ -353,10 +347,10 @@ Definition.Regex(/^\d*$/).conform("123") # => pass
 #### Numerics
 
 ```ruby
-Definition.GreaterThen(5).conform(5.1) # => pass
-Definition.GreaterThenEqual(5).conform(5) # => pass
-Definition.LessThen(5).conform(4) # => pass
-Definition.LessThenEqual(5).conform(5) # => pass
+Definition.GreaterThan(5).conform(5.1) # => pass
+Definition.GreaterThanEqual(5).conform(5) # => pass
+Definition.LessThan(5).conform(4) # => pass
+Definition.LessThanEqual(5).conform(5) # => pass
 ```
 
 #### Strings, Array, Hashes
@@ -382,7 +376,7 @@ Definition.Nil.conform(nil) # => pass
 #### Boolean
 
 ```ruby
-Definition.Boolean.conform(tru) # => pass
+Definition.Boolean.conform(true) # => pass
 ```
 
 #### All types
@@ -431,6 +425,92 @@ end
 schema.conform(input_hash).errors.first.translated_error # => Value is of wrong type, needs to be a String"
 ```
 
+# Helpers / useful tools
+
+### Value Objects / Models
+
+Provides simple immutable objects that can validate and hold your data so that it can be safely passed around in your application.
+
+```ruby
+class User < Definition::Model
+  required :username, Definition.Type(String)
+  required :password, Definition.Type(String)
+  optional :age, Definition.Type(Integer)
+end
+
+user = User.new(username: "johndoe", password: "zg(2ds8x2/")
+user.username # => "johndoe"
+user.age # => nil
+user.to_h # => { username: "johndoe", password: "zg(2ds8x2/" }
+user.new(age: 21) # => new model instance with username and password from before plus the age set to 21
+
+user.username = "Alice" # => raises NoMethodError (Models are immutable)
+
+User.new(username: "johndoe") # => raises a Definition::InvalidModelError: hash is missing :password
+
+```
+
+You can access the conform result of InvalidModel errors via their `conform_result` method.
+
+#### Nesting Models
+
+Models can be nested by either using the model object itself as type definition,
+or by using the `CoercibleModel` Definition. The latter is less strict and will 
+convert input hashes that conform with the model schema to an instance of the model.
+
+```ruby
+class Address < Definition::Model
+  required :street, Definition.Type(String)
+  required :postal_code, Definition.Type(String)
+end
+
+class User < Definition::Model
+  required :username, Definition.Type(String)
+  required :address, Definition.CoercibleModel(Address)
+end
+
+# Address is converted into an Address model automatically:
+user = User.new(username: "John", address: { street: "123 Fakestreet", postal_code: "2dfx4" })
+user.address.street # => "123 Fakestreet"
+
+class UserNotCoercibleAddress < Definition::Model
+  required :username, Definition.Type(String)
+  required :address, Address
+end
+
+# Address is not converted automatically, instead it needs to be of type Address already:
+UserNotCoercibleAddress.new(username: "John", address: { street: "123 Fakestreet", postal_code: "2dfx4" }) # => raises a Definition::InvalidModelError
+UserNotCoercibleAddress.new(username: "John", address: Address.new(street: "123 Fakestreet", postal_code: "2dfx4")).address.street # => "123 Fakestreet"
+```
+
+### Intialization argument validation
+
+Definition provides a mixin that allows you to validate keyword arguments of class initialization methods. This is meant to be used with classes that provide business logic whereas the models are meant to be used to pass data around.
+
+The major differences to a Definition::Model are:
+* The values are not frozen and can be changed by the classes internal business logic
+* None of the getters for the attributes are public
+
+```ruby
+class User
+  include Definition::Initializer
+
+  required :id, Definition.Type(Integer)
+  required :name, Definition.Type(String)
+  optional :phone, Definition.Type(String), default: nil
+
+  def hello
+    puts "Hello, I'm #{name}"
+  end
+end
+
+user = User.new(id: 1, name: "Joe")
+user.hello # => "Hello, I'm Joe"
+user.name # => raises NoMethodError
+
+User.new(id: "1", name: "Joe") # => raises a Definition::Initializer::InvalidArgumentError
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/UpgradeNotes.md

@@ -0,0 +1,27 @@
+# Upgrade Notes
+
+## From version 0.7.1 and prior to version 0.8
+##### The Definition::ValueObject was removed and replaced by Definition:Model
+If you used ValueObjects then you need to migrate them to Models. This will be very easy if you used the ValueObject with a `Definition.Keys` definition, which is most likely the case.
+
+Before:
+```ruby
+class User < Definition::ValueObject
+  definition(Definition.Keys do
+    required :username, Definition.Type(String)
+    required :password, Definition.Type(String)
+  end)
+end
+```
+
+After:
+```ruby
+class User < Definition::Model
+  required :username, Definition.Type(String)
+  required :password, Definition.Type(String)
+end
+```
+
+If you use the `Definition.CoercibleValueObject` definition in your models, you just need to replace those with a `Definition.CoercibleModel` definition.
+
+If you use ValueObjects that do not use a `Keys` definition then there is currently no built in replacement available.

data/benchmark/initializer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "dry-initializer", "~> 3.1"
+  gem "dry-types", "~> 1.5"
+  gem "awesome_print"
+  gem "benchmark-ips"
+  gem "pry"
+  gem "ruby-prof"
+  gem "sorbet"
+  gem "sorbet-runtime"
+  gem "definition", path: File.expand_path("../.", __dir__)
+end
+
+class SorbetUseCase
+  extend T::Sig
+
+  sig { params(phone: String, admin: T::Boolean).void }
+  def initialize(phone:, admin: false)
+    self.phone = phone
+    self.admin = admin
+  end
+
+  private
+
+  attr_accessor :phone, :admin
+end
+
+class DryUseCase
+  extend Dry::Initializer
+
+  option :phone, Dry::Types["strict.string"]
+  option :admin, Dry::Types["strict.bool"], default: false, optional: true
+end
+
+class DefinitionUseCase
+  include Definition::Initializer
+
+  required :phone, Definition.Type(String)
+  optional :admin, Definition.Boolean, default: false
+end
+
+puts "Benchmark with valid input data:"
+valid_data = { phone: "+49 3424 234234" }
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("sorbet") do
+    SorbetUseCase.new(**valid_data)
+  end
+
+  x.report("definition") do
+    DefinitionUseCase.new(**valid_data)
+  end
+
+  x.report("dry-struct") do
+    DryUseCase.new(**valid_data)
+  end
+
+  x.compare!
+end
+
+puts "Benchmark with invalid input data:"
+invalid_data = { phone: "+49 3424 234234", admin: "yes" }
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("sorbet") do
+    SorbetUseCase.new(**invalid_data)
+  rescue TypeError
+    nil
+  end
+
+  x.report("definition") do
+    DefinitionUseCase.new(**invalid_data)
+  rescue Definition::Initializer::InvalidArgumentError
+    nil
+  end
+
+  x.report("dry-struct") do
+    DryUseCase.new(**invalid_data)
+  rescue Dry::Types::ConstraintError
+    nil
+  end
+
+  x.compare!
+end

data/benchmark/model.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "dry-struct", "~> 1.4"
+  gem "awesome_print"
+  gem "benchmark-ips"
+  gem "pry"
+  gem "ruby-prof"
+  gem "definition", path: File.expand_path("../.", __dir__)
+end
+
+class DryStructModel < Dry::Struct
+  schema schema.strict
+
+  attribute :id, Dry::Types["strict.integer"]
+  attribute :app_key, Dry::Types["strict.string"]
+  attribute :app_version, Dry::Types["strict.string"]
+  attribute :app_name, Dry::Types["strict.string"].optional.default(nil)
+  attribute :app_branch, Dry::Types["strict.string"].optional.default(nil)
+  attribute :platform, Dry::Types["strict.string"].optional.default(nil)
+end
+
+class DefinitionModel < Definition::Model
+  required :id, Definition.Type(Integer)
+  required :app_key, Definition.Type(String)
+  required :app_version, Definition.Type(String)
+  optional :app_name, Definition.Type(String)
+  optional :app_branch, Definition.Type(String)
+  optional :platform, Definition.Type(String)
+end
+
+puts "Benchmark with valid input data:"
+valid_data = { id: 1, app_key: "com.test", app_version: "1.0.0", app_name: "testapp" }
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("definition") do
+    DefinitionModel.new(**valid_data)
+  end
+
+  x.report("dry-struct") do
+    DryStructModel.new(**valid_data)
+  end
+
+  x.compare!
+end
+
+puts "Benchmark with invalid input data:"
+invalid_data = { id: "abc", app_key: "com.test", app_name: "testapp" }
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("definition") do
+    DefinitionModel.new(**invalid_data)
+  rescue Definition::InvalidModelError
+    nil
+  end
+
+  x.report("dry-struct") do
+    DryStructModel.new(**invalid_data)
+  rescue Dry::Struct::Error
+    nil
+  end
+
+  x.compare!
+end

data/benchmark/validation_only.rb

@@ -4,22 +4,20 @@ require "bundler/inline"
 
 gemfile do
   source "https://rubygems.org"
-  # FIXME: benchmark needs to be updated to work with dry-validation 1.0.0"
-  gem "dry-validation", "< 1.0.0"
-  gem "dry-types", "< 0.15"
+  gem "dry-validation", "~> 1.8"
+  gem "dry-types", "~> 1.5"
   gem "awesome_print"
   gem "benchmark-ips"
   gem "definition", path: File.expand_path("../.", __dir__)
 end
 
-DrySchema = Dry::Validation.Params do
-  configure do
-    config.type_specs = true
+class DryContract < Dry::Validation::Contract
+  params do
+    required(:name).filled(:string)
+    required(:time).filled(:time)
   end
-
-  required(:name, :string).value(type?: String)
-  required(:time, :time).value(type?: String)
 end
+DryContractInstance = DryContract.new
 
 DefinitionSchema = Definition.Keys do
   required(:name, Definition.Type(String))
@@ -29,7 +27,7 @@ end
 puts "Benchmark with valid input data:"
 valid_data = { name: "test", time: Time.now }
 ap DefinitionSchema.conform(valid_data).value
-ap DrySchema.call(valid_data)
+ap DryContractInstance.call(valid_data)
 Benchmark.ips do |x|
   x.config(time: 5, warmup: 2)
 
@@ -38,7 +36,7 @@ Benchmark.ips do |x|
   end
 
   x.report("dry-validation") do
-    DrySchema.call(valid_data)
+    DryContractInstance.call(valid_data)
   end
 
   x.compare!
@@ -47,7 +45,7 @@ end
 puts "Benchmark with invalid input data:"
 invalid_data = { name: 1, time: Time.now.to_s }
 ap DefinitionSchema.conform(invalid_data).error_message
-ap DrySchema.call(invalid_data).errors
+ap DryContractInstance.call(invalid_data).errors
 Benchmark.ips do |x|
   x.config(time: 5, warmup: 2)
 
@@ -56,7 +54,7 @@ Benchmark.ips do |x|
   end
 
   x.report("dry-validation") do
-    DrySchema.call(invalid_data)
+    DryContractInstance.call(invalid_data)
   end
 
   x.compare!

data/config/locales/en.yml

@@ -1,7 +1,7 @@
 en:
   definition:
-    max_size: "Value is bigger than %{max_size}"
-    min_size: "Value is smaller than %{min_size}"
+    max_size: "Value is longer than %{max_size}"
+    min_size: "Value is shorter than %{min_size}"
     greater_then: "Value must be greater than %{min_value}"
     greater_then_equal: "Value must be greater or equal to %{min_value}"
     less_then: "Value must be less than %{max_value}"