dry-initializer 2.4.0 → 3.0.3

data/benchmarks/with_coercion.rb

@@ -1,6 +1,6 @@
 Bundler.require(:benchmarks)
 
-require "dry-initializer"
+require 'dry-initializer'
 class DryTest
   extend Dry::Initializer[undefined: false]
 
@@ -24,7 +24,7 @@ class PlainRubyTest
   end
 end
 
-require "virtus"
+require 'virtus'
 class VirtusTest
   include Virtus.model
 
@@ -32,7 +32,7 @@ class VirtusTest
   attribute :bar, String
 end
 
-require "fast_attributes"
+require 'fast_attributes'
 class FastAttributesTest
   extend FastAttributes
 
@@ -42,29 +42,29 @@ class FastAttributesTest
   end
 end
 
-puts "Benchmark for instantiation with coercion"
+puts 'Benchmark for instantiation with coercion'
 
 Benchmark.ips do |x|
   x.config time: 15, warmup: 10
 
-  x.report("plain Ruby") do
-    PlainRubyTest.new foo: "FOO", bar: "BAR"
+  x.report('plain Ruby') do
+    PlainRubyTest.new foo: 'FOO', bar: 'BAR'
   end
 
-  x.report("dry-initializer") do
-    DryTest.new foo: "FOO", bar: "BAR"
+  x.report('dry-initializer') do
+    DryTest.new foo: 'FOO', bar: 'BAR'
   end
 
-  x.report("dry-initializer (with UNDEFINED)") do
-    DryTestUndefined.new foo: "FOO", bar: "BAR"
+  x.report('dry-initializer (with UNDEFINED)') do
+    DryTestUndefined.new foo: 'FOO', bar: 'BAR'
   end
 
-  x.report("virtus") do
-    VirtusTest.new foo: "FOO", bar: "BAR"
+  x.report('virtus') do
+    VirtusTest.new foo: 'FOO', bar: 'BAR'
   end
 
-  x.report("fast_attributes") do
-    FastAttributesTest.new foo: "FOO", bar: "BAR"
+  x.report('fast_attributes') do
+    FastAttributesTest.new foo: 'FOO', bar: 'BAR'
   end
 
   x.compare!

data/benchmarks/with_defaults.rb

@@ -1,64 +1,64 @@
 Bundler.require(:benchmarks)
 
-require "dry-initializer"
+require 'dry-initializer'
 class DryTest
   extend Dry::Initializer[undefined: false]
 
-  option :foo, default: -> { "FOO" }
-  option :bar, default: -> { "BAR" }
+  option :foo, default: -> { 'FOO' }
+  option :bar, default: -> { 'BAR' }
 end
 
 class DryTestUndefined
   extend Dry::Initializer
 
-  option :foo, default: -> { "FOO" }
-  option :bar, default: -> { "BAR" }
+  option :foo, default: -> { 'FOO' }
+  option :bar, default: -> { 'BAR' }
 end
 
 class PlainRubyTest
   attr_reader :foo, :bar
 
-  def initialize(foo: "FOO", bar: "BAR")
+  def initialize(foo: 'FOO', bar: 'BAR')
     @foo = foo
     @bar = bar
   end
 end
 
-require "kwattr"
+require 'kwattr'
 class KwattrTest
-  kwattr foo: "FOO", bar: "BAR"
+  kwattr foo: 'FOO', bar: 'BAR'
 end
 
-require "active_attr"
+require 'active_attr'
 class ActiveAttrTest
   include ActiveAttr::AttributeDefaults
 
-  attribute :foo, default: "FOO"
-  attribute :bar, default: "BAR"
+  attribute :foo, default: 'FOO'
+  attribute :bar, default: 'BAR'
 end
 
-puts "Benchmark for instantiation with default values"
+puts 'Benchmark for instantiation with default values'
 
 Benchmark.ips do |x|
   x.config time: 15, warmup: 10
 
-  x.report("plain Ruby") do
+  x.report('plain Ruby') do
     PlainRubyTest.new
   end
 
-  x.report("dry-initializer") do
+  x.report('dry-initializer') do
     DryTest.new
   end
 
-  x.report("dry-initializer (with UNDEFINED)") do
+  x.report('dry-initializer (with UNDEFINED)') do
     DryTestUndefined.new
   end
 
-  x.report("kwattr") do
+  x.report('kwattr') do
     KwattrTest.new
   end
 
-  x.report("active_attr") do
+  x.report('active_attr') do
     ActiveAttrTest.new
   end
 

data/benchmarks/with_defaults_and_coercion.rb

@@ -1,24 +1,24 @@
 Bundler.require(:benchmarks)
 
-require "dry-initializer"
+require 'dry-initializer'
 class DryTest
   extend Dry::Initializer[undefined: false]
 
-  option :foo, proc(&:to_s), default: -> { "FOO" }
-  option :bar, proc(&:to_s), default: -> { "BAR" }
+  option :foo, proc(&:to_s), default: -> { 'FOO' }
+  option :bar, proc(&:to_s), default: -> { 'BAR' }
 end
 
 class DryTestUndefined
   extend Dry::Initializer
 
-  option :foo, proc(&:to_s), default: -> { "FOO" }
-  option :bar, proc(&:to_s), default: -> { "BAR" }
+  option :foo, proc(&:to_s), default: -> { 'FOO' }
+  option :bar, proc(&:to_s), default: -> { 'BAR' }
 end
 
 class PlainRubyTest
   attr_reader :foo, :bar
 
-  def initialize(foo: "FOO", bar: "BAR")
+  def initialize(foo: 'FOO', bar: 'BAR')
     @foo = foo
     @bar = bar
     raise TypeError unless String === @foo
@@ -26,32 +26,32 @@ class PlainRubyTest
   end
 end
 
-require "virtus"
+require 'virtus'
 class VirtusTest
   include Virtus.model
 
-  attribute :foo, String, default: "FOO"
-  attribute :bar, String, default: "BAR"
+  attribute :foo, String, default: 'FOO'
+  attribute :bar, String, default: 'BAR'
 end
 
-puts "Benchmark for instantiation with type constraints and default values"
+puts 'Benchmark for instantiation with type constraints and default values'
 
 Benchmark.ips do |x|
   x.config time: 15, warmup: 10
 
-  x.report("plain Ruby") do
+  x.report('plain Ruby') do
     PlainRubyTest.new
   end
 
-  x.report("dry-initializer") do
+  x.report('dry-initializer') do
     DryTest.new
   end
 
-  x.report("dry-initializer (with UNDEFINED)") do
+  x.report('dry-initializer (with UNDEFINED)') do
     DryTest.new
   end
 
-  x.report("virtus") do
+  x.report('virtus') do
     VirtusTest.new
   end
 

data/docsite/source/attributes.html.md

@@ -0,0 +1,106 @@
+---
+title: Attributes
+layout: gem-single
+name: dry-initializer
+---
+
+Sometimes you need to access all attributes assigned via params and options of the object constructor.
+
+We support 2 methods: `attributes` and `public_attributes` for this goal. Both methods are wrapped into container accessible via `.dry_types` container:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :email,   optional: true
+  option :telefon, optional: true, as: :phone
+end
+
+user = User.new "Andy", telefon: "71002003040"
+
+User.dry_initializer.attributes(user)
+# => { name: "Andy", phone: "71002003040" }
+```
+
+What the method does is extracts *variables assigned* to the object (and skips unassigned ones like the `email` above). It doesn't matter whether you send it via `params` or `option`; we look at the result of the instantiation, not at the interface.
+
+Method `public_attributes` works different. Let's look at the following example to see the difference:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :telefon,  optional: true, as: :phone
+  option :email,    optional: true
+  option :token,    optional: true, reader: :private
+  option :password, optional: true, reader: false
+end
+
+user = User.new "Andy", telefon: "71002003040", token: "foo", password: "bar"
+
+User.dry_initializer.attributes(user)
+# => { name: "Andy", phone: "71002003040", token: "foo", password: "bar" }
+
+User.dry_initializer.public_attributes(user)
+# => { name: "Andy", phone: "71002003040", email: nil }
+```
+
+Notice that `public_attribute` reads *public reader methods*, not variables. That's why it skips both the private `token`, and the `password` whose reader hasn't been defined.
+
+Another difference concerns unassigned values. Because the reader `user.email` returns `nil` (its `@email` variable contains `Dry::Initializer::UNDEFINED` constant), the `public_attributes` adds this value to the hash using the method.
+
+The third thing to mention is that you can override the reader, and it is the overriden method which will be used by `public_attributes`:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :password, optional: true
+
+  def password
+    super.hash.to_s
+  end
+end
+
+user = User.new "Joe", password: "foo"
+
+User.dry_initializer.attributes(user)
+# => { user: "Joe", password: "foo" }
+
+User.dry_initializer.public_attributes(user)
+# => { user: "Joe", password: "-1844874613000160009" }
+```
+
+This feature works for the "extend Dry::Initializer" syntax. But what about "include Dry::Initializer.define ..."? Now we don't pollute class namespace with new methods, that's why `.dry_initializer` is absent.
+
+To access config you can use a hack. Under the hood we define private instance method `#__dry_initializer_config__` which refers to the same container. So you can write:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+  param :name
+end
+
+user = User.new "Joe"
+
+user.send(:__dry_initializer_config__).attributes(user)
+# => { user: "Joe" }
+
+user.send(:__dry_initializer_config__).public_attributes(user)
+# => { user: "Joe" }
+```
+
+This is a hack because the `__dry_initializer_config__` is not a part of the gem's public interface; there's a possibility it can be changed or removed in the later releases.
+
+We'll try to be careful with it, and mark it as deprecated method in case of such a removal.

data/docsite/source/container-version.html.md

@@ -0,0 +1,39 @@
+---
+title: Container Version
+layout: gem-single
+name: dry-initializer
+---
+
+Instead of extending a class with the `Dry::Initializer`, you can include a container with the `initializer` method only. This method should be preferred when you don't need subclassing.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  # notice `-> do .. end` syntax
+  include Dry::Initializer.define -> do
+    param  :name,  proc(&:to_s)
+    param  :role,  default: proc { 'customer' }
+    option :admin, default: proc { false }
+  end
+end
+```
+
+If you still need the DSL (`param` and `option`) to be inherited, use the direct extension:
+
+```ruby
+require 'dry-initializer'
+
+class BaseService
+  extend Dry::Initializer
+  alias_method :dependency, :param
+end
+
+class ShowUser < BaseService
+  dependency :user
+
+  def call
+    puts user&.name
+  end
+end
+```

data/docsite/source/index.html.md

@@ -0,0 +1,43 @@
+---
+title: Introduction & Usage
+description: DSL for defining initializer params and options
+layout: gem-single
+order: 8
+type: gem
+name: dry-initializer
+sections:
+  - container-version
+  - params-and-options
+  - options-tolerance
+  - optionals-and-defaults
+  - type-constraints
+  - readers
+  - inheritance
+  - skip-undefined
+  - attributes
+  - rails-support
+---
+
+`dry-initializer` is a simple mixin of class methods `params` and `options` for instances.
+
+## Synopsis
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name,  proc(&:to_s)
+  param  :role,  default: proc { 'customer' }
+  option :admin, default: proc { false }
+  option :phone, optional: true
+end
+
+user = User.new 'Vladimir', 'admin', admin: true
+
+user.name  # => 'Vladimir'
+user.role  # => 'admin'
+user.admin # => true
+user.phone # => nil
+```

data/docsite/source/inheritance.html.md

@@ -0,0 +1,43 @@
+---
+title: Inheritance
+layout: gem-single
+name: dry-initializer
+---
+
+Subclassing preserves all definitions being made inside a superclass.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name
+end
+
+class Employee < User
+  param :position
+end
+
+employee = Employee.new('John', 'supercargo')
+employee.name     # => 'John'
+employee.position # => 'supercargo'
+
+employee = Employee.new # => fails because type
+```
+
+You can override params and options.
+Such overriding leaves initial order of params (positional arguments) unchanged:
+
+```ruby
+class Employee < User
+  param :position, optional: true
+  param :name,     default:  proc { 'Unknown' }
+end
+
+user = User.new         # => Boom! because User#name is required
+employee = Employee.new # passes because who cares on employee's name
+
+employee.name
+# => 'Unknown' because it is the name that positioned first like in User
+```