dry-initializer 3.0.2 → 3.1.1

data/docsite/source/skip-undefined.html.md

@@ -1,59 +0,0 @@
----
-title: Skip Undefined
-layout: gem-single
-name: dry-initializer
----
-
-The initializer uses special constant `Dry::Initializer::UNDEFINED` to distinguish variables that are set to `nil` from those that are not set at all.
-
-When no value was provided, the constant is assigned to a variable, but hidden in a reader.
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-  option :email, optional: true
-end
-
-user = User.new
-
-user.email
-# => nil
-
-user.instance_variable_get :@email
-# => Dry::Initializer::UNDEFINED
-```
-
-This gives you full control of the real state of the attributes. However, all that checks cost about >30% of instantiation time, and make attribute readers 2 times slower.
-
-To avoid the overhead in cases you don't care about the differences between `nil` and undefined, you can use a light version of the module. Add `[undefined: false]` config to either `extend` or `include` line of code:
-
-```ruby
-extend Dry::Initializer[undefined: false]
-```
-
-```ruby
-include Dry::Initializer[undefined: false] -> do
-  # ...
-end
-```
-
-This time you should expect `nil` every time no value was given to an optional attribute:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer[undefined: false]
-  option :email, optional: true
-end
-
-user = User.new
-
-user.email
-# => nil
-
-user.instance_variable_get :@email
-# => nil
-```

data/docsite/source/type-constraints.html.md

@@ -1,160 +0,0 @@
----
-title: Type Constraints
-layout: gem-single
-name: dry-initializer
----
-
-## Base Syntax
-
-Use `:type` key in a `param` or `option` declarations to add type coercer.
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-  param :name, type: proc(&:to_s)
-end
-
-user = User.new :Andrew
-user.name # => "Andrew"
-```
-
-Any object that responds to `#call` with 1 argument can be used as a type. Common examples are `proc(&:to_s)` for strings, `method(:Array)` (for arrays) or `Array.method(:wrap)` in Rails, `->(v) { !!v }` (for booleans), etc.
-
-## Dry Types as coercers
-
-Another important example is the usage of `dry-types` as type constraints:
-
-```ruby
-require 'dry-initializer'
-require 'dry-types'
-
-class User
-  extend Dry::Initializer
-  param :name, type: Dry::Types['strict.string']
-end
-
-user = User.new :Andrew # => #<TypeError ...>
-```
-
-## Positional Argument
-
-Instead of `:type` option you can send a constraint/coercer as the second argument:
-
-```ruby
-require 'dry-initializer'
-require 'dry-types'
-
-class User
-  extend Dry::Initializer
-  param :name,  Dry::Types['coercible.string']
-  param :email, proc(&:to_s)
-end
-```
-
-## Array Types
-
-As mentioned above, the `:type` option takes a callable object... with one important exception.
-
-You can use arrays for values that should be wrapped to array:
-
-```ruby
-class User
-  extend Dry::Initializer
-
-  option :name,   proc(&:to_s)
-  option :emails, [proc(&:to_s)]
-end
-
-user = User.new name: "joe", emails: :"joe@example.com"
-user.emails # => ["joe@example.com"]
-
-user = User.new name: "jane", emails: [:"jane@example.com", :"jane@example.org"]
-user.emails # => ["jane@example.com", "jane@example.org"]
-```
-
-You can wrap the coercer into several arrays as well:
-
-```ruby
-class User
-  extend Dry::Initializer
-
-  option :emails, [[proc(&:to_s)]]
-end
-
-user = User.new name: "joe", emails: "joe@example.com"
-user.emails # => [["joe@example.com"]]
-```
-
-Eventually, you can use an empty array as a coercer. In that case we just wrap the source value(s) into array, not modifying the items:
-
-```ruby
-class Article
-  extend Dry::Initializer
-
-  option :tags, []
-end
-
-article = Article.new(tags: 1)
-article.tags # => [1]
-```
-
-## Nested Options
-
-Sometimes you need to describe a structure with nested options. In this case you can use a block with `options` inside.
-
-```ruby
-class User
-  extend Dry::Initializer
-
-  option :name, proc(&:to_s)
-
-  option :emails, [] do
-    option :address,     proc(&:to_s)
-    option :description, proc(&:to_s)
-  end
-end
-
-user = User.new name: "joe",
-                emails: { address: "joe@example.com", description: "Job email" }
-
-user.emails.class         # => Array
-user.emails.first.class   # => User::Emails
-user.emails.first.address # => "joe@example.com"
-
-user.emails.to_h # => [{ address: "joe@example.com", description: "Job email" }]
-```
-
-Notice how we mixed array wrapper with a nested type.
-
-The only syntax restriction here is that you cannot use a positional `param` _inside_ the block.
-
-## Back References
-
-Sometimes you need to refer back to the initialized instance. In this case use a second argument to explicitly give the instance to a coercer:
-
-```ruby
-class Location < String
-  attr_reader :parameter # refers back to its parameter
-
-  def initialize(name, parameter)
-    super(name)
-    @parameter = parameter
-  end
-end
-
-class Parameter
-  extend Dry::Initializer
-  param :name
-  param :location, ->(value, param) { Location.new(value, param) }
-end
-
-offset = Parameter.new "offset", location: "query"
-offset.name     # => "offset"
-offset.location # => "query"
-offset.location.parameter == offset # true
-```
-
-[dry-types]: https://github.com/dry-rb/dry-types
-[dry-types-docs]: http://dry-rb.org/gems/dry-types/

data/spec/attributes_spec.rb

@@ -1,38 +0,0 @@
-describe Dry::Initializer, "dry_initializer.attributes" do
-  subject { instance.class.dry_initializer.attributes(instance) }
-
-  context "when class has params" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer
-        param :foo, proc(&:to_s)
-        param :bar, default: proc { 1 }
-        param :baz, optional: true
-      end
-    end
-
-    let(:instance) { Test::Foo.new(:FOO) }
-
-    it "collects coerced params with default values" do
-      expect(subject).to eq({ foo: "FOO", bar: 1 })
-    end
-  end
-
-  context "when class has options" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer
-        option :foo
-        option :bar, default: proc { 1 }
-        option :baz, optional: true
-        option :qux, proc(&:to_s), as: :quxx
-      end
-    end
-
-    let(:instance) { Test::Foo.new(foo: :FOO, qux: :QUX) }
-
-    it "collects coerced and renamed options with default values" do
-      expect(subject).to eq({ foo: :FOO, bar: 1, quxx: "QUX" })
-    end
-  end
-end

data/spec/coercion_of_nil_spec.rb

@@ -1,25 +0,0 @@
-describe "coercion of nil" do
-  before do
-    class Test::Foo
-      extend Dry::Initializer
-      param :bar, proc(&:to_i)
-    end
-
-    class Test::Baz
-      include Dry::Initializer.define -> do
-        param :qux, proc(&:to_i)
-      end
-    end
-  end
-
-  let(:foo) { Test::Foo.new(nil) }
-  let(:baz) { Test::Baz.new(nil) }
-
-  it "works with extend syntax" do
-    expect(foo.bar).to eq 0
-  end
-
-  it "works with include syntax" do
-    expect(baz.qux).to eq 0
-  end
-end

data/spec/custom_dispatchers_spec.rb

@@ -1,35 +0,0 @@
-describe "custom dispatchers" do
-  subject { Test::Foo.new "123" }
-
-  before do
-    dispatcher = ->(op) { op[:integer] ? op.merge(type: proc(&:to_i)) : op }
-    Dry::Initializer::Dispatchers << dispatcher
-  end
-
-  context "with extend syntax" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer
-        param :id, integer: true
-      end
-    end
-
-    it "adds syntax sugar" do
-      expect(subject.id).to eq 123
-    end
-  end
-
-  context "with include syntax" do
-    before do
-      class Test::Foo
-        include Dry::Initializer.define -> do
-          param :id, integer: true
-        end
-      end
-    end
-
-    it "adds syntax sugar" do
-      expect(subject.id).to eq 123
-    end
-  end
-end

data/spec/custom_initializer_spec.rb

@@ -1,30 +0,0 @@
-describe "custom initializer" do
-  before do
-    class Test::Foo
-      extend Dry::Initializer
-
-      param :bar
-
-      def initialize(*args)
-        super
-        @bar *= 3
-      end
-    end
-
-    class Test::Baz < Test::Foo
-      param :qux
-
-      def initialize(*args)
-        super
-        @qux += 1
-      end
-    end
-  end
-
-  it "reloads the initializer" do
-    baz = Test::Baz.new(5, 5)
-
-    expect(baz.bar).to eq 15 # 5 * 3
-    expect(baz.qux).to eq 6  # 5 + 1
-  end
-end

data/spec/default_values_spec.rb

@@ -1,83 +0,0 @@
-describe "default values" do
-  before do
-    class Test::Foo
-      extend Dry::Initializer
-
-      param  :foo, default: proc { :FOO }
-      param  :bar, default: proc { :BAR }
-      option :baz, default: -> { :BAZ }
-      option :qux, default: proc { foo }
-      option :mox, default: -> { default_mox }
-
-      private
-
-      def default_mox
-        :MOX
-      end
-    end
-  end
-
-  it "instantiate arguments" do
-    subject = Test::Foo.new(1, 2, baz: 3, qux: 4)
-
-    expect(subject.foo).to eql 1
-    expect(subject.bar).to eql 2
-    expect(subject.baz).to eql 3
-    expect(subject.qux).to eql 4
-  end
-
-  it "applies default values" do
-    subject = Test::Foo.new
-
-    expect(subject.foo).to eql :FOO
-    expect(subject.bar).to eql :BAR
-    expect(subject.baz).to eql :BAZ
-    expect(subject.qux).to eql :FOO
-  end
-
-  it "applies default values partially" do
-    subject = Test::Foo.new 1, baz: 3
-
-    expect(subject.foo).to eql 1
-    expect(subject.bar).to eql :BAR
-    expect(subject.baz).to eql 3
-    expect(subject.qux).to eql 1
-  end
-
-  it "applies default values from private methods" do
-    subject = Test::Foo.new
-    expect(subject.mox).to eql :MOX
-  end
-
-  describe "when the last param has a default and there are no options" do
-    before do
-      class Test::Bar
-        extend Dry::Initializer
-
-        param :foo
-        param :bar, default: proc { {} }
-      end
-    end
-
-    it "instantiates arguments" do
-      subject = Test::Bar.new(1, 2)
-
-      expect(subject.foo).to eql 1
-      expect(subject.bar).to eql 2
-    end
-
-    it "applies default values" do
-      subject = Test::Bar.new(1)
-
-      expect(subject.foo).to eql 1
-      expect(subject.bar).to eql({})
-    end
-
-    it "instantiates arguments also if the last is an hash" do
-      subject = Test::Bar.new(1, { baz: 2, qux: 3 })
-
-      expect(subject.foo).to eql 1
-      expect(subject.bar).to eql({ baz: 2, qux: 3 })
-    end
-  end
-end

data/spec/definition_spec.rb

@@ -1,111 +0,0 @@
-describe "definition" do
-  shared_examples :initializer do |in_context|
-    subject { Test::Foo.new(1, bar: 2) }
-
-    it "sets variables when defined via `#{in_context}`" do
-      expect(subject.instance_variable_get(:@foo)).to eql 1
-      expect(subject.instance_variable_get(:@bar)).to eql 2
-    end
-  end
-
-  it_behaves_like :initializer, "extend Dry::Initializer" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer
-        param  :foo
-        option :bar
-      end
-    end
-
-    it "preservers definition params" do
-      params = Test::Foo.dry_initializer.params.map do |definition|
-        [definition.source, definition.options]
-      end
-
-      expect(params).to eq [
-        [:foo, { as: :foo, reader: :public, optional: false }]
-      ]
-    end
-
-    it "preservers definition options" do
-      options = Test::Foo.dry_initializer.options.map do |definition|
-        [definition.source, definition.options]
-      end
-
-      expect(options).to eq [
-        [:bar, { as: :bar, reader: :public, optional: false }]
-      ]
-    end
-  end
-
-  it_behaves_like :initializer, "extend Dry::Initializer" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer
-        param  :foo
-        option :bar
-      end
-    end
-  end
-
-  it_behaves_like :initializer, "extend Dry::Initializer[undefined: false]" do
-    before do
-      class Test::Foo
-        extend Dry::Initializer[undefined: false]
-        param  :foo
-        option :bar
-      end
-    end
-  end
-
-  it_behaves_like :initializer, "include Dry::Initializer with block" do
-    before do
-      class Test::Foo
-        include(
-          Dry::Initializer.define do
-            param  :foo
-            option :bar
-          end
-        )
-      end
-    end
-  end
-
-  it_behaves_like :initializer, "include Dry::Initializer with lambda" do
-    before do
-      class Test::Foo
-        include Dry::Initializer.define -> do
-          param  :foo
-          option :bar
-        end
-      end
-    end
-  end
-
-  it_behaves_like :initializer, "include Dry::Initializer[undefined: false]" do
-    before do
-      class Test::Foo
-        include(
-          Dry::Initializer[undefined: false].define do
-            param  :foo
-            option :bar
-          end
-        )
-      end
-    end
-  end
-
-  # @deprecated
-  it_behaves_like :initializer, "include Dry::Initializer::Mixin" do
-    before do
-      class Test::Foo
-        include(
-          Dry::Initializer::Mixin.define do
-            param  :foo
-            option :bar
-          end
-        )
-      end
-    end
-  end
-end

data/spec/invalid_default_spec.rb

@@ -1,13 +0,0 @@
-describe "invalid default value assignment" do
-  subject do
-    class Test::Foo
-      extend Dry::Initializer
-
-      param :foo, default: 1
-    end
-  end
-
-  it "raises TypeError" do
-    expect { subject }.to raise_error TypeError
-  end
-end

data/spec/list_type_spec.rb

@@ -1,32 +0,0 @@
-require "dry-types"
-
-describe "list type argument" do
-  before do
-    class Test::Foo
-      extend Dry::Initializer
-      param  :foo, [proc(&:to_s)]
-      option :bar, [Dry::Types["strict.string"]]
-      option :baz, []
-    end
-  end
-
-  context "with single items" do
-    subject { Test::Foo.new(1, bar: "2", baz: { qux: :QUX }) }
-
-    it "coerces and wraps them to arrays" do
-      expect(subject.foo).to eq %w[1]
-      expect(subject.bar).to eq %w[2]
-      expect(subject.baz).to eq [{ qux: :QUX }]
-    end
-  end
-
-  context "with arrays" do
-    subject { Test::Foo.new([1], bar: %w[2], baz: [{ qux: :QUX }]) }
-
-    it "coerces elements" do
-      expect(subject.foo).to eq %w[1]
-      expect(subject.bar).to eq %w[2]
-      expect(subject.baz).to eq [{ qux: :QUX }]
-    end
-  end
-end

data/spec/missed_default_spec.rb

@@ -1,14 +0,0 @@
-describe "missed default values" do
-  subject do
-    class Test::Foo
-      extend Dry::Initializer
-
-      param :foo, default:  proc { :FOO }
-      param :bar, required: true
-    end
-  end
-
-  it "raises SyntaxError" do
-    expect { subject }.to raise_error SyntaxError, /bar/
-  end
-end

data/spec/nested_type_spec.rb

@@ -1,48 +0,0 @@
-describe "nested type argument" do
-  subject { Test::Xyz.new("bar" => { "baz" => 42 }) }
-
-  context "with nested definition only" do
-    before do
-      class Test::Xyz
-        extend Dry::Initializer
-
-        param :foo, as: :x do
-          option :bar, as: :y do
-            option :baz, proc(&:to_s), as: :z
-            option :qux, as: :w, optional: true
-          end
-        end
-      end
-    end
-
-    it "builds the type" do
-      expect(subject.x.y.z).to eq "42"
-    end
-
-    it "converts the nested type to hash" do
-      expect(subject.x.to_h).to eq("y" => { "z" => "42" })
-    end
-  end
-
-  context "with nested and wrapped definitions" do
-    before do
-      class Test::Xyz
-        extend Dry::Initializer
-
-        param :foo, [], as: :x do
-          option :bar, as: :y do
-            option :baz, proc(&:to_s), as: :z
-            option :qux, as: :w, optional: true
-          end
-        end
-      end
-    end
-
-    it "builds the type" do
-      x = subject.x
-      expect(x).to be_instance_of Array
-
-      expect(x.first.y.z).to eq "42"
-    end
-  end
-end