domainic-attributer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a25981d1a30af4ee16bd8339c975c935eee76c0bcda186af868e28c4ae4874f8
+  data.tar.gz: c9dd81c87a0cc108010e4463beba162f30830182c485624ba0782de971ebb93f
+SHA512:
+  metadata.gz: 97e1331498dc427a98bcaf3dfa38828d1aafe02466bcbd2ae84101542b476a92543f611eed55f842537da5224fa568c8f812f475f21fec6c4831e1704c2b456e
+  data.tar.gz: f2a5d8b6540cc7aba2eed108a5181ea3db350dc8f3a52f30a386e94f78b0ebd9df984697ad7f92071f1bd338fa3c25619be0ff4a5e3054d52703570ba2884ea9

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Break Versioning].
+
+## [Unreleased]
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Break Versioning]: https://www.taoensso.com/break-versioning
+
+<!-- versions -->
+
+[Unreleased]: https://github.com/domainic/domainic/tree/main/domainic-attributer

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Aaron Allen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,396 @@
+# Domainic::Attributer
+
+[![Domainic::Attributer Version](https://badge.fury.io/rb/domainic-attributer.svg)](https://rubygems.org/gems/domainic-attributer)
+
+Domainic::Attributer is a powerful toolkit for Ruby that brings clarity and safety to your class attributes. It's
+designed to solve common Domain-Driven Design (DDD) challenges by making your class attributes self-documenting,
+type-safe, and well-behaved. Ever wished your class attributes could:
+
+* Validate themselves to ensure they only accept correct values?
+* Transform input data automatically into the right format?
+* Have clear, enforced visibility rules?
+* Handle their own default values intelligently?
+* Tell you when they change?
+* Distinguish between required arguments and optional settings?
+
+That's exactly what Domainic::Attributer does! It's particularly useful when building domain models, value objects, or
+any Ruby classes where data integrity and clear interfaces matter. Instead of writing repetitive validation code, manual
+type checking, and custom attribute methods, let Domainic::Attributer handle the heavy lifting while you focus on your
+domain logic.
+
+Think of it as giving your attributes a brain - they know what they want, how they should behave, and they're not afraid
+to speak up when something's not right!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'domainic-attributer'
+```
+
+Or install it yourself as:
+
+```bash
+gem install domainic-attributer
+```
+
+## Usage
+
+### Basic Attributes
+
+Getting started with Domainic::Attributer is as easy as including the module and declaring your attributes:
+
+```ruby
+class Person
+  include Domainic::Attributer
+
+  argument :name
+  option :age, default: nil
+end
+
+person = Person.new("Alice", age: 30)
+person.name  # => "Alice"
+person.age   # => 30
+```
+
+### Arguments vs Options
+
+Domainic::Attributer gives you two ways to define attributes:
+
+* `argument`: Required positional parameters that must be provided in order
+* `option`: Named parameters that can be provided in any order (and are optional by default)
+
+```ruby
+class Hero
+  include Domainic::Attributer
+
+  argument :name        # Required, must be first
+  argument :power      # Required, must be second
+  option :catchphrase  # Optional, can be provided by name
+  option :sidekick     # Optional, can be provided by name
+end
+
+# All valid ways to create a hero:
+Hero.new("Spider-Man", "Web-slinging", catchphrase: "With great power...")
+Hero.new("Batman", "Being rich", sidekick: "Robin")
+Hero.new("Wonder Woman", "Super strength")
+```
+
+#### Argument Ordering and Default Values
+
+Arguments in Domainic::Attributer follow special ordering rules based on whether they have defaults:
+
+* Arguments without defaults are required and are automatically moved to the front of the argument list
+* Arguments with defaults are optional and are moved to the end of the argument list
+* Within each group (with/without defaults), arguments maintain their order of declaration
+
+This means the actual position when providing arguments to the constructor will be different from their declaration
+order:
+
+```ruby
+class EmailMessage
+  include Domainic::Attributer
+
+  # This will be the first argument (no default)
+  argument :to
+
+  # This will be the third argument (has default)
+  argument :priority, default: :normal
+
+  # This will be the second argument (no default)
+  argument :subject
+end
+
+# Arguments must be provided in their sorted order,
+# with required arguments first:
+EmailMessage.new("user@example.com", "Welcome!", :high)
+# => #<EmailMessage:0x00007f9b1b8b3b10 @to="user@example.com", @priority=:high, @subject="Welcome!">
+
+# If you try to provide the arguments in their declaration order, you'll get undesired results:
+EmailMessage.new("user@example.com", :high, "Welcome!")
+# => #<EmailMessage:0x00007f9b1b8b3b10 @to="user@example.com", @priority="Welcome!", @subject=:high>
+```
+
+This behavior ensures that required arguments are provided first and optional arguments (those with defaults) come
+after, making argument handling more predictable. You can rely on this ordering regardless of how you declare the
+arguments in your class. Best practice is to declare arguments without defaults first, followed by those with defaults.
+
+### Nilability And Option Requirements
+
+Be explicit about nil values:
+
+```ruby
+class User
+  include Domainic::Attributer
+
+  argument :email do
+    non_nilable  # or not_null, non_null, etc.
+  end
+
+  option :nickname do
+    default nil  # Explicitly allow nil
+  end
+end
+```
+
+Ensure certain options are always provided:
+
+```ruby
+class Order
+  include Domainic::Attributer
+
+  option :items, required: true
+  option :status, Symbol
+end
+
+Order.new(option: ['item1', 'item2']) # OK
+Order.new(status: :pending) # Raises ArgumentError
+```
+
+#### Required vs NonNilable
+
+`required` and `non_nilable` are similar but not identical. `required` means the option must be provided when the object
+is created, while `non_nilable` means the option must not be nil. A `required` option can still be nil if it's provided.
+
+```ruby
+class User
+  include Domainic::Attributer
+
+  option :email, String do
+    required
+    non_nilable
+  end
+
+  option :nickname, String do
+    required
+  end
+end
+
+User.new(email: 'example@example.com', nickname: nil) # OK
+User.new(email: nil, nickname: 'example') # Raises ArgumentError because email is non_nilable
+User.new(email: 'example@example.com') # Raises ArgumentError because nickname is required
+
+user = User.new(email: 'example@example.com', nickname: 'example')
+user.nickname = nil # OK
+user.email = nil # Raises ArgumentError because email is non_nilable
+```
+
+### Type Validation
+
+Keep your data clean with built-in type validation:
+
+```ruby
+class BankAccount
+  include Domainic::Attributer
+
+  argument :account_name, String                                # Direct class validation
+  argument :opened_at, Time                                     # Another direct class example  
+  option :balance, Integer, default: 0                          # Combining class validation with defaults
+  option :status, ->(val) { [:active, :closed].include?(val) }  # Custom validation
+end
+
+# Will raise ArgumentError:
+BankAccount.new(:my_account_name, Time.now)
+BankAccount.new("my_account_name", "not a time")
+BankAccount.new("my_account_name", Time.now, balance: "not an integer")
+BankAccount.new("my_account_name", Time.now, balance: 100, status: :not_included_in_the_allow_list)
+```
+
+### Documentation
+
+Make your attributes self-documenting:
+
+```ruby
+class Car
+  include Domainic::Attributer
+
+  argument :make, String do
+    desc "The make of the car"
+  end
+
+  argument :model, String do
+    description "The model of the car"
+  end
+
+  argument :year, ->(value) { value.is_a?(Integer) && value >= 1900 && value <= Time.now.year } do
+    description "The year the car was made"
+  end
+end
+```
+
+### Value Coercion
+
+Transform input values automatically:
+
+```ruby
+class Temperature
+  include Domainic::Attributer
+
+  argument :celsius do |value|
+    coerce_with ->(val) { val.to_f }
+    validate_with ->(val) { val.is_a?(Float) }
+  end
+
+  option :unit, default: "C" do |value|
+    validate_with ->(val) { ["C", "F"].include?(val) }
+  end
+end
+
+temp = Temperature.new("24.5")  # Automatically converted to Float
+temp.celsius  # => 24.5
+```
+
+### Custom Validation
+
+Domainic::Attributer provides flexible validation options that can be combined to create sophisticated validation rules.
+You can:
+
+* Use Ruby classes directly to validate types
+* Use Procs/lambdas for custom validation logic
+* Chain multiple validations
+* Combine validations with coercions
+
+```ruby
+class BankTransfer
+  include Domainic::Attributer
+
+  # Combine coercion and multiple validations
+  argument :amount do
+    coerce_with ->(val) { val.to_f }             # First coerce to float
+    validate_with Float                          # Then validate it's a float
+    validate_with ->(val) { val.positive? }      # And validate it's positive
+  end
+
+  # Different validation styles
+  argument :status do
+    validate_with Symbol                         # Must be a Symbol
+    validate_with ->(val) { [:pending, :completed, :failed].include?(val) }  # Must be one of these values
+  end
+
+  # Validation with custom error handling
+  argument :reference_number do
+    validate_with ->(val) {
+      raise ArgumentError, "Reference must be 8 characters" unless val.length == 8
+      true
+    }
+  end
+end
+
+# These will work:
+BankTransfer.new("50.0", :pending, "12345678")    # amount coerced to 50.0
+BankTransfer.new(75.25, :completed, "ABCD1234")   # amount already a float
+
+# These will raise ArgumentError:
+BankTransfer.new(-10, :pending, "12345678")       # amount must be positive
+BankTransfer.new(100, :invalid, "12345678")       # invalid status
+BankTransfer.new(100, :pending, "123")            # invalid reference number
+```
+
+Validations are run in the order they're defined, after any coercions. This lets you build up complex validation rules
+while keeping them readable and maintainable.
+
+### Visibility Control
+
+Control access to your attributes:
+
+```ruby
+class SecretAgent
+  include Domainic::Attributer
+
+  argument :code_name
+  option :real_name do
+    private_read   # Can't read real_name from outside
+    private_write  # Can't write real_name from outside
+  end
+  option :mission do
+    protected  # Both read and write are protected
+  end
+end
+```
+
+### Change Callbacks
+
+React to attribute changes:
+
+```ruby
+class Thermostat
+  include Domainic::Attributer
+
+  option :temperature do
+    default 20
+    on_change ->(old_val, new_val) {
+      puts "Temperature changing from #{old_val}°C to #{new_val}°C"
+    }
+  end
+end
+```
+
+### Default Values
+
+Provide static defaults or generate them dynamically:
+
+```ruby
+class Order
+  include Domainic::Attributer
+
+  argument :items
+  option :created_at do
+    default { Time.now }  # Dynamic default
+  end
+  option :status do
+    default "pending"     # Static default
+  end
+end
+```
+
+### Custom Method Names
+
+Don't like `argument` and `option`? Create your own interface:
+
+```ruby
+class Configuration
+  include Domainic.Attributer(argument: :param, option: :setting)
+
+  param :environment
+  setting :debug_mode, default: false
+end
+```
+
+or turn off one of the methods entirely:
+
+```ruby
+class Configuration
+  include Domainic.Attributer(argument: nil)
+
+  option :environment
+end
+```
+
+### Serialization
+
+Convert your objects to hashes easily:
+
+```ruby
+class Product
+  include Domainic::Attributer
+
+  argument :name
+  argument :price
+  option :description, default: ""
+  option :internal_id do
+    private  # Won't be included in to_h output
+  end
+end
+
+product = Product.new("Widget", 9.99, description: "A fantastic widget")
+product.to_h  # => { name: "Widget", price: 9.99, description: "A fantastic widget" }
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/domainic/attributer/attribute/callback.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
+
+module Domainic
+  module Attributer
+    class Attribute
+      # A class responsible for managing change callbacks for an attribute.
+      #
+      # This class handles the execution of callbacks that are triggered when an
+      # attribute's value changes. Each callback must be a Proc that accepts two
+      # arguments: the old value and the new value.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Callback
+        # @rbs!
+        #   type handler = ^(untyped old_value, untyped new_value) -> void | Proc
+
+        # @rbs @handlers: Array[handler]
+
+        include BelongsToAttribute
+
+        # Initialize a new Callback instance.
+        #
+        # @param attribute [Attribute] the attribute this Callback belongs to
+        # @param handlers [Array<Proc>] the handlers to use for processing
+        #
+        # @return [Callback] the new instance of Callback
+        # @rbs (Attribute attribute, Array[handler] | handler handlers) -> void
+        def initialize(attribute, handlers = [])
+          super
+          @handlers = [*handlers].map do |handler|
+            validate_handler!(handler)
+            handler
+          end.uniq
+        end
+
+        # Execute all callbacks for a value change.
+        #
+        # @param instance [Object] the instance on which to execute callbacks
+        # @param old_value [Object] the previous value
+        # @param new_value [Object] the new value
+        #
+        # @return [void]
+        # @rbs (untyped instance, untyped old_value, untyped new_value) -> void
+        def call(instance, old_value, new_value)
+          @handlers.each { |handler| instance.instance_exec(old_value, new_value, &handler) }
+        end
+
+        private
+
+        # Validate that a callback handler is a valid Proc.
+        #
+        # @param handler [Object] the handler to validate
+        #
+        # @raise [TypeError] if the handler is not a valid Proc
+        # @return [void]
+        # @rbs (handler handler) -> void
+        def validate_handler!(handler)
+          return if handler.is_a?(Proc)
+
+          raise TypeError, "`#{attribute_method_name}`: invalid handler: #{handler.inspect}. Must be a Proc."
+        end
+      end
+    end
+  end
+end

data/lib/domainic/attributer/attribute/coercer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
+
+module Domainic
+  module Attributer
+    class Attribute
+      # A class responsible for coercing attribute values.
+      #
+      # This class manages the coercion of values assigned to an attribute. Coercion can be
+      # handled by either a Proc that accepts a single value argument, or by referencing an
+      # instance method via Symbol.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Coercer
+        # @rbs!
+        #   type handler = proc | Proc | Symbol
+        #
+        #   type proc = ^(untyped value) -> untyped
+
+        include BelongsToAttribute
+
+        # @rbs @handlers: Array[handler]
+
+        # Initialize a new Coercer instance.
+        #
+        # @param attribute [Attribute] the attribute this Coercer belongs to
+        # @param handlers [Array<Proc, Symbol>] the handlers to use for processing
+        #
+        # @return [Coercer] the new instance of Coercer
+        # @rbs (Attribute attribute, Array[handler] | handler handlers) -> void
+        def initialize(attribute, handlers = [])
+          super
+          @handlers = [*handlers].map do |handler|
+            validate_handler!(handler)
+            handler
+          end.uniq
+        end
+
+        # Process a value through all coercion handlers.
+        #
+        # @param instance [Object] the instance on which to perform coercion
+        # @param value [Object] the value to coerce
+        #
+        # @return [Object] the coerced value
+        # @rbs (untyped instance, untyped value) -> untyped
+        def call(instance, value)
+          @handlers.reduce(value) { |accumulator, handler| coerce_value(instance, handler, accumulator) }
+        end
+
+        private
+
+        # Process a value through a single coercion handler.
+        #
+        # @param instance [Object] the instance on which to perform coercion
+        # @param handler [Proc, Symbol] the coercion handler
+        # @param value [Object] the value to coerce
+        #
+        # @raise [TypeError] if the handler is invalid
+        # @return [Object] the coerced value
+        # @rbs (untyped instance, handler, untyped value) -> untyped
+        def coerce_value(instance, handler, value)
+          case handler
+          when Proc
+            instance.instance_exec(value, &handler)
+          when Symbol
+            instance.send(handler, value)
+          else
+            # We should never get here because we validate the handlers in the initializer.
+            raise TypeError, "`#{attribute_method_name}`: invalid coercer: #{handler}. "
+          end
+        end
+
+        # Validate that a coercion handler is valid.
+        #
+        # @param handler [Object] the handler to validate
+        #
+        # @raise [TypeError] if the handler is not valid
+        # @return [void]
+        # @rbs (handler handler) -> void
+        def validate_handler!(handler)
+          return if handler.is_a?(Proc)
+          return if handler.is_a?(Symbol) &&
+                    (@attribute.base.method_defined?(handler) || @attribute.base.private_method_defined?(handler))
+
+          raise TypeError, "`#{attribute_method_name}`: invalid coercer: #{handler.inspect}. Must be a Proc " \
+                           'or a Symbol referencing a method.'
+        end
+      end
+    end
+  end
+end

data/lib/domainic/attributer/attribute/mixin/belongs_to_attribute.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Attributer
+    class Attribute
+      # A mixin providing common functionality for classes that belong to an Attribute.
+      #
+      # This module provides initialization and duplication behavior for classes that are owned
+      # by and work in conjunction with an Attribute instance. These classes typically handle
+      # specific aspects of attribute processing such as coercion, validation, or callbacks.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module BelongsToAttribute
+        # @rbs @attribute: Attribute
+
+        # Initialize a new instance that belongs to an attribute.
+        #
+        # @param attribute [Attribute] the attribute this instance belongs to
+        #
+        # @return [void]
+        # @rbs (Attribute attribute, *untyped, **untyped) -> void
+        def initialize(attribute, ...)
+          validate_attribute!(attribute)
+          @attribute = attribute
+        end
+
+        # Create a duplicate instance associated with a new attribute.
+        #
+        # @param new_attribute [Attribute] the new attribute to associate with
+        #
+        # @return [BelongsToAttribute] a duplicate instance
+        # @rbs (Attribute attribute) -> BelongsToAttribute
+        def dup_with_attribute(new_attribute)
+          validate_attribute!(new_attribute)
+
+          dup.tap { |duped| duped.instance_variable_set(:@attribute, new_attribute) }
+        end
+
+        private
+
+        # Generate a method name for error messages.
+        #
+        # @return [String] the formatted method name
+        # @rbs () -> String
+        def attribute_method_name
+          "#{@attribute.base}##{@attribute.name}"
+        end
+
+        # Ensure that an attribute is a valid {Attribute} instance.
+        #
+        # @param attribute [Attribute] the attribute to validate
+        #
+        # @raise [TypeError] if the attribute is not a valid {Attribute} instance
+        # @return [void]
+        # @rbs (Attribute attribute) -> void
+        def validate_attribute!(attribute)
+          return if attribute.is_a?(Attribute)
+          return if defined?(RSpec::Mocks::TestDouble) && attribute.is_a?(RSpec::Mocks::TestDouble)
+
+          raise TypeError,
+                "invalid attribute: #{attribute.inspect}. Must be an Domainic::Attributer::Attribute instance"
+        end
+      end
+      private_constant :BelongsToAttribute
+    end
+  end
+end