changelog.yml

---
- version: 3.2.0
  date: '2025-01-01'
  changed:
  - Set minimal supported Ruby version to 3.1 (@flash-gordon)
  - |
    Exclude block forwarding from `Root#initialize`. This helps
    with tracking down calls that shouldn't pass a block in Ruby 3.4 (see #109) (@flash-gordon)
- version: 3.1.1
  date: '2022-01-19'
  changed:
  - Improved error messages were rolled back, they created
    an implicit dependency on dry-types (@flash-gordon)
- version: 3.1.0
  date: '2022-01-16'
  changed:
  - Improved error messages on type mismatch (@swerling)
  - '[BREAKING] Minimal supported Ruby version is 2.7 (@flash-gordon)'
- version: 3.0.4
  date: '2020-09-29'
  fixed:
  - 'Arity check for lambdas used for coercion (@flash-gordon)'
- version: 3.0.3
  date: '2020-01-08'
  fixed:
  - 'Constrained member arrays work correctly now (see #33) (@bjeanes + @solnic)'
- version: 3.0.2
  date: '2019-11-07'
  fixed:
  - Warnings about keyword arguments (flash-gordon)
- version: 3.0.1
  date: '2019-04-15'
  fixed:
  - |-
    Usage of underscored names of `option`-s and `param`-s (nepalez)

      You can use any sequence of underscores except for in nested types.
      In nested types single underscores can be used to split alphanumeric
      parts only.

      ```ruby
      class Test
        extend Dry::Initializer

        # Proper usage
        option :foo_bar do
          option :__foo__, proc(&:to_s)
        end
      end

        # Improper usage
        option :__foo__ do
          # ...
        end

        option :foo__bar do
          # ...
        end
      end
      ```

      This restriction is necessary because we constantize option/param names
      when defining nested structs.
- version: 3.0.0
  date: '2019-04-14'
  added:
  - |-
    Support of wrapped types/coercers (nepalez)

      ```ruby
      class Test
        # Wrap type to the array
        param :foo, [proc(&:to_s)]
      end

      # And the value will be wrapped as well
      test = Test.new(42)
      test.foo # => ["42"]
      ```
  - |-
    It works with several layers of nesting (nepalez)

      ```ruby
      class Test
        # Wrap type to the array
        param :foo, [[proc(&:to_s)]]
      end

      # And the value will be wrapped as well
      test = Test.new(42)
      test.foo # => [["42"]]
      ```
  - |-
    Support of nested types/coercers (nepalez)

      ```ruby
      class Test
        param :foo do
          option :bar do
            option :baz, proc(&:to_s)
          end
        end
      end

      test = Test.new(bar: { "baz" => 42 })
      test.foo.bar.baz # => "42"
      ```
  - |-
    Wrapped/nested combinations are supported as well (nepalez)

      ```ruby
      class Test
        param :foo, [] do
          option :bar, proc(&:to_s)
        end
      end

      test = Test.new(bar: 42)
      test.foo.first.bar # => "42"
      ```
  - "## [2.7.0] Unreleazed"
  fixed:
  - |-
    Roll back master to the state of [2.5.0].

      Somehow distinction between `@default_null` and `@null` variables
      in the `Dry::Initializer::Builders` broken the `rom` library.

      The version [2.6.0] has been yanked on rubygems, so the master
      was rolled back to the previous state until the reason for
      the incompatibility become clear (bjeanes, nepalez)
  - "## [2.6.0] [2018-09-09] (YANKED)"
- version: 2.5.0
  date: '2018-08-17'
  fixed:
  - |-
    `nil` coercion (belousovAV)

      When default value is `nil` instead of `Dry::Initializer::UNDEFINED`,
      the coercion should be applied to any value, including `nil`, because
      we cannot distinct "undefined" `nil` from the "assigned" `nil` value.
- version: 2.4.0
  date: '2018-02-01'
  added:
  - |-
    Dispatchers for adding syntax sugar to `param` and `options` (nepalez)

      ```ruby
      # Converts `integer: true` to `type: proc(&:to_i)`
      dispatcher = ->(op) { op[:integer] ? op.merge(type: proc(&:to_i)) : op }
      # Register a dispatcher
      Dry::Initializer::Dispatchers << dispatcher
      # Use syntax sugar
      class User
        param :id, integer: true # same as param :id, proc(&:to_i)
      end
      ```
- version: 2.3.0
  date: '2017-09-19'
  added:
  - |-
    Type coercer can take second argument for the initialized instance (nepalez)
      This allows to wrap assigned value to the object that refers back
      to the initializer instance. More verbose example:

      ```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
      ```
- version: 2.2.0
  date: '2017-09-13'
  added:
  - Option `:desc` for option/param to add a description (nepalez)
  - |-
    Methods `Definition#inch` and `Config#inch` to inspect definitions (nepalez)

      ```ruby
      class User
        extend Dry::Initializer
        option :name,  proc(&:to_s), optional: true, desc: "User name"
        option :email, optional: true, desc: "user email"
      end

      User.dry_initializer.inch
      # @!method initialize(*, **options)
      # Initializes an instance of User
      # @option [Object] :name (optional) User name
      # @option [Object] :email (optional) User email
      # @return [User]
      ```
- version: 2.1.0
  date: '2017-09-11'
  added:
  - |-
    Method `#options` to param/option definition (nepalez)

      ```ruby
      class User
        extend Dry::Initializer
        option :name,  proc(&:to_s), optional: true
        option :email, optional: true
      end

      User.dry_initializer.options.map do |option|
        [option.source, option.options]
      end
      # => [
      #      [:name,  { type: proc(&:to_s), as: :name, optional: true }],
      #      [:email, { as: :email, optional: true }]
      #    ]
      ```

      This method can be helpful for replicating params/options
      in another class without inheritance.
- version: 2.0.0
  date: '2017-08-28'
  summary: and to @gzigzigzeo for persuading me to do this refactoring.
  added:
  - |-
    Class method `.dry_initializer` -- a container for `.params` and `.options`
      `.definitions` along with the `.null` setting (either `nil` or `UNDEFINED`)
      used for unassigned values (nepalez)
  - |-
    `.dry_initializer.attributes` method takes an instance of the same class
      and returns the hash of assigned options. This provide the same
      functionality as previously used instance variable `@__options__` (nepalez)

      ```ruby
      object.class.dry_initializer.attributes(object)
      ```

      When you use "Dry::Initializer.define -> { ... }" syntax,
      the class method `.dry_initializer` is not defined. To access attributes
      you should use private instance method `#__dry_initializer_config__` instead:

      ```ruby
      object.send(:__dry_initializer_config__).attributes(object)
      ```

      Both methods `.dry_initializer` and `#__dry_initializer_config__` refer
      to the same object.
  - |-
    `.dry_initializer.public_attributes`. This method works differently:
      it looks through (possibly reloaded) readers instead of variables
      (gzigzigzeo, nepalez)

      ```ruby
      object.class.dry_initializer.public_attributes(object)
      ```

      You can use the same trick as above mutatis mutandis.
  fixed:
  - |-
    Definition order dependency bug (nepalez)

      I've found out that if you provided a subclass and then changed params
      or options of its superclass, these changes woudn't be reflected in
      subclasses until you change any of it params/options as well.

      Now this bug is fixed: every time you call `param` or `option` at
      any class, the gem scans through all its descendants to the very bottom
      of the tree, and reloads their defintitions.

      Being done in load time, the rebuilt makes no effect on runtime performance.
  - |-
    Possible misbehavior when you define param and option with the same name (nepalez)

      Doing this will provide `option :name` only, not both:

      ```ruby
      param  :name
      option :name
      ```
  - |-
    Attempt to redefine param/option of superclass with option/param in
      its subclass will cause an exception because it would break
      Liskov substitute principle with unexpected behaviour (nepalez)

      No, you can do neither these definitions, nor vice versa:

      ```ruby
      class Foo
        extend Dry::Intitializer
        param :name
      end

      class Bar < Foo
        option :name
      end
      ```
  - |-
    When you reloading previously defined param of superclass, the gem
      will check all its descendands for whether all required positional params
      goes before optional ones (nepalez)

      ```ruby
      class Foo
        param :name
        # Foo: def initializer(name)
      end

      class Bar
        param :email
        # Bar: def initializer(name, email)
      end

      class Foo
        # This raises SyntaxError because in Bar this would cause wrong definition
        # Foo: def initializer(name = nil)
        # Bar: def initializer(name = nil, email)
        param :name, optional: true
      end
      ```
  changed:
  - |-
    Under the hood I've separated param/option settings declaration (a container
      with param/option settings) from code builders for initializer and readers
      (nepalez)

      You can check both the code for the `__initializer__`:

      ```ruby
      class Foo
        extend Dry::Initializer
        # ...
      end

      Foo.dry_initializer.code
      ```

      and readers:

      ```ruby
      Foo.dry_initializer.params.map(&:code)
      Foo.dry_initializer.options.map(&:code)

      # or

      Foo.dry_initializer.definitions.values.map(&:code)
      ```

      You can also check settings for every param and option using methods
      `dry_initializer.params`, `dry_initializer.options` (lists), or
      `dry_initializer.definitions` (hash).

      You can check null value via `.dry_initializer.null` which is different
      for `Dry::Initializer` and `Dry::Initializer[undefined: false]` modules.
  - |-
    Optimized the code for `__initializer__`-s (the method where all magics occurs)
      (nepalez)

      Benchmarks remained about the same:

      ```shell
      rake benchmark
      ```

      ```
      Benchmark for instantiation with plain params
              value_struct:  4317196.9 i/s
                plain Ruby:  4129803.9 i/s - 1.05x  slower
           dry-initializer:  1710702.1 i/s - 2.52x  slower
                   concord:  1372630.4 i/s - 3.15x  slower
                    values:   601651.8 i/s - 7.18x  slower
               attr_extras:   535599.5 i/s - 8.06x  slower
      ```

      ```
      Benchmark for instantiation with plain options
                plain Ruby: 1769174.1 i/s
           dry-initializer:  636634.1 i/s - 2.78x  slower
                    kwattr:  423296.5 i/s - 4.18x  slower
                     anima:  399415.0 i/s - 4.43x  slower
      ```

      ```
      Benchmark for instantiation with coercion
                plain Ruby:  1565501.0 i/s
           fast_attributes:   569952.9 i/s -  2.75x  slower
           dry-initializer:   461122.1 i/s -  3.39x  slower
                    virtus:   138074.8 i/s - 11.34x  slower
      ```

      ```
      Benchmark for instantiation with default values
                plain Ruby:  3402455.4 i/s
                    kwattr:   586206.5 i/s -  5.80x  slower
           dry-initializer:   528482.2 i/s -  6.44x  slower
               active_attr:   298697.7 i/s - 11.39x  slower
      ```

      ```
      Benchmark for instantiation with type constraints and default values
                plain Ruby: 2881696.1 i/s
           dry-initializer:  470815.1 i/s -  6.12x  slower
                    virtus:  180272.6 i/s - 15.99x  slower
      ```
- version: 1.4.1
  date: '2017-04-05'
  fixed:
  - |-
    Warning about redefined `#initialize` in case the method reloaded in a klass
      that extends the module (nepalez, sergey-chechaev)
  changed:
  - Rename `Dry::Initializer::DSL` -> `Dry::Initializer::ClassDSL` (nepalez)
  - Add `Dry::Initializer::InstanceDSL` (nepalez)
- version: 1.4.0
  date: '2017-03-08'
  changed:
  - |-
    The `@__options__` hash now collects all assigned attributes,
      collected via `#option` (as before), and `#param` (nepalez)
- version: 1.3.0
  date: '2017-03-05'
  added:
  - |-
    No-undefined configuration of the initializer (nepalez, flash-gordon)

      You can either extend or include module `Dry::Initializer` with additional option
      `[undefined: false]`. This time `nil` will be assigned instead of
      `Dry::Initializer::UNDEFINED`. Readers becomes faster because there is no need
      to chech whether a variable was defined or not. At the same time the initializer
      doesn't distinct cases when a variable was set to `nil` explicitly, and when it wasn's set at all:

        class Foo # old behavior
          extend Dry::Initializer
          param :qux, optional: true
        end

        class Bar # new behavior
          extend Dry::Initializer[undefined: false]
          param :qux, optional: true
        end

        Foo.new.instance_variable_get(:@qux) # => Dry::Initializer::UNDEFINED
        Bar.new.instance_variable_get(:@qux) # => nil
  changed:
  - Fixed method definitions for performance at the load time (nepalez, flash-gordon)
- version: 1.2.0
  date: '2017-03-05'
  fixed:
  - The `@__options__` variable collects renamed options after default values and
    coercions were applied (nepalez)
- version: 1.1.3
  date: '2017-03-01'
  added:
  - Support for lambdas as default values (nepalez, gzigzigzeo)
- version: 1.1.2
  date: '2017-02-06'
  changed:
  - Remove previously defined methods before redefining them (flash-gordon)
- version: 1.1.1
  date: '2017-02-04'
  fixed:
  - "`@__options__` collects defined options only (nepalez)"
- version: 1.1.0
  date: '2017-01-28'
  added:
  - |-
    enhancement via `Dry::Initializer::Attribute.dispatchers` registry (nepalez)

      ```ruby
      # Register dispatcher for `:string` option
      Dry::Initializer::Attribute.dispatchers << ->(string: nil, **op) do
        string ? op.merge(type: proc(&:to_s)) : op
      end

      # Now you can use the `:string` key for `param` and `option`
      class User
        extend Dry::Initializer
        param :name, string: true
      end

      User.new(:Andy).name # => "Andy"
      ```
  changed:
  - optimize assignments for performance (nepalez)
- version: 1.0.0
  date: '2017-01-22'
  summary: In this version the code has been rewritten for simplicity
  changed:
  - "[BREAKING] when `param` or `option` was not defined, the corresponding **variable**
    is set to `Dry::Initializer::UNDEFINED`, but the **reader** (when defined) will
    return `nil` (nepalez)"
  - "`Dry::Initializer` and `Dry::Initializer::Mixin` became aliases (nepalez)"
  added:
  - |-
    support for reloading `param` and `option` definitions (nepalez)

        class User
          extend Dry::Initializer
          param :name
          param :phone, optional: true
        end

        User.new # => Boom!

        class Admin < User
          param :name, default: proc { 'Merlin' }
        end

        # order of the param not changed
        Admin.new.name # => "Merlin"
  - |-
    support for assignment of attributes via several options (nepalez)

        class User
          extend Dry::Initializer
          option :phone
          option :number, as: :phone
        end

        # Both ways provide the same result
        User.new(phone: '1234567890').phone   # => '1234567890'
        User.new(number: '1234567890').phone # => '1234567890'
- version: 0.11.0
  date: '2017-01-02'
  added:
  - Support of reloading `#initializer` with `super` (nepalez)
- version: 0.10.2
  date: '2016-12-31'
  added:
  - Support of Ruby 2.4 (flas-gordon)
- version: 0.10.1
  date: '2016-12-27'
  fixed:
  - Wrong arity when there were no options and the last param had a default (nolith)
- version: 0.10.0
  date: '2016-11-20'
- version: 0.9.3
  date: '2016-11-20'
  fixed:
  - |-
    Support of weird option names (nepalez)

      ```ruby
      option :"First name", as: :first_name
      ```
- version: 0.9.2
  date: '2016-11-10'
  fixed:
  - Validation of attributes (params and options) (nepalez)
- version: 0.9.1
  date: '2016-11-06'
  added:
  - |-
    Support for renaming an option during initialization (nepalez)

      option :name, as: :username # to take :name option and create :username attribute
- version: 0.9.0
  date: '2016-11-06'
  added:
  - |-
    The method `#initialize` is defined when a class extended the module (nepalez)

      In previous versions the method was defined only by `param` and `option` calls.
- version: 0.8.1
  date: '2016-11-05'
  added:
  - |-
    Support for `dry-struct`ish syntax for constraints (type as a second parameter) (nepalez)

        option :name, Dry::Types['strict.string']
- version: 0.8.0
  date: '2016-11-05'
  summary: are deprecated and will be removed in the next version of the gem.
  added:
  - support for special options like `option :end`, `option :begin` etc. (nepalez)
  changed:
  - switched from key arguments to serialized hash argument in the initializer (nepalez)
- version: 0.7.0
  date: '2016-10-11'
  added:
  - Shared settings with `#using` method (nepalez)
- version: 0.6.0
  date: '2016-10-09'
  added:
  - Support for private and protected readers in the `reader:` option (jmgarnier)
- version: 0.5.0
  date: '2016-08-21'
  added:
  - Allow `optional` attribute to be left undefined (nepalez)
- version: 0.4.0
  date: '2016-05-28'
- version: 0.3.3
  date: '2016-05-28'
- version: 0.3.2
  date: '2016-05-25'
  fixed:
  - Add explicit requirement for ruby 'set' (rickenharp)
- version: 0.3.1
  date: '2016-05-22'
  added:
  - Support for tolerance to unknown options (nepalez)
- version: 0.3.0
  date: '2016-05-19'
  summary: 'its method #register doesn''t mutate the builder instance.'
  changed:
  - Made Mixin##initializer_builder method private (nepalez)
  - Add Mixin#register_initializer_plugin(plugin) method (nepalez)
  - Make all instances (Builder and Signature) immutable (nepalez)
  - Decouple mixin from a builder to prevent pollution (nepalez)
  - Ensure default value block can use private variables (jeremyf)
  fixed:
  - Prevent plugin's registry from polluting superclass (nepalez)
- version: 0.2.1
  date: '2016-05-19'
  fixed:
  - Fix polluting superclass with declarations from subclass (nepalez)
  changed:
  - Make all instances (Builder and Signature) immutable (nepalez)
  - Decouple mixin from a builder to prevent pollution (nepalez)
  - Ensure default value block can use private variables (jeremyf)
- version: 0.2.0
  date: '2016-05-16'
  summary: Default assignments became slower (while plain type constraint are not)!
  changed:
  - |-
    Make dry-types constraint to coerce variables (nepalez)

      ```ruby
      # This will coerce `name: :foo` to `"foo"`
      option :name, type: Dry::Types::Coercible::String
      ```
  - |-
    Stop supporing proc type constraint (nepalez)

      ```ruby
      option :name, type: ->(v) { String === v } # this does NOT work any more
      ```

      later it will be implemented via coercion plugin (not added by default):

      ```ruby
      require 'dry/initializer/coercion'

      class MyClass
        extend Dry::Initializer::Mixin
        extend Dry::Initializer::Coercion

        option :name, coercer: ->(v) { (String === v) ? v.to_sym : fail }
      end
      ```
  added:
  - |-
    Support type constraint via every object's case equality (nepalez)

      ```ruby
      option :name, type: /foo/
      option :name, type: (1...14)
      ```
  - Support defaults and type constraints for the "container" syntax (nepalez)
  - Support adding extensions via plugin system (nepalez)
- version: 0.1.1
  date: '2016-04-28'
  added:
  - "`include Dry::Initializer.define -> do ... end` syntax (flash-gordon)"
- version: 0.1.0
  date: '2016-04-26'
  summary: Backward compatibility is broken.
  changed:
  - Use `extend Dry::Initializer::Mixin` instead of `extend Dry::Initializer` (nepalez)
  added:
  - Use `include Dry::Initializer.define(&block)` as an alternative to extending the
    class (nepalez)
- version: 0.0.1
  date: '2016-04-09'
  summary: First public release