stannum 0.3.0 → 0.4.0

data/lib/stannum/attribute.rb

@@ -4,16 +4,71 @@ require 'stannum'
 require 'stannum/support/optional'
 
 module Stannum
-  # Data object representing an attribute on a struct.
+  # Data object representing an attribute on an entity.
   class Attribute
     include Stannum::Support::Optional
 
+    # Builder class for defining attribute methods on an entity.
+    class Builder
+      # @param schema [Stannum::Schema] the attributes schema on which to define
+      #   methods.
+      def initialize(schema)
+        @schema = schema
+      end
+
+      # @return [Stannum::Schema] the attributes schema on which to define
+      #   methods.
+      attr_reader :schema
+
+      # Defines the reader and writer methods for the attribute.
+      #
+      # @param attribute [Stannum::Attribute]
+      def call(attribute)
+        define_reader(attribute)
+        define_writer(attribute)
+      end
+
+      private
+
+      def define_reader(attribute)
+        schema.define_method(attribute.reader_name) do
+          read_attribute(attribute.name, safe: false)
+        end
+      end
+
+      def define_writer(attribute) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        assoc_name = attribute.association_name
+
+        schema.define_method(attribute.writer_name) do |value|
+          previous_value = read_attribute(attribute.name, safe: false)
+
+          return if previous_value == value
+
+          if attribute.foreign_key? && !previous_value.nil?
+            self
+              .class
+              .associations[assoc_name]
+              .remove_value(self, previous_value)
+          end
+
+          value = attribute.default_value_for(self) if value.nil?
+
+          write_attribute(attribute.name, value, safe: false)
+        end
+      end
+    end
+
     # @param name [String, Symbol] The name of the attribute. Converted to a
     #   String.
     # @param options [Hash, nil] Options for the attribute. Converted to a Hash
     #   with Symbol keys. Defaults to an empty Hash.
     # @param type [Class, Module, String] The type of the attribute. Can be a
     #   Class, a Module, or the name of a class or module.
+    #
+    # @option options [Object] :default The default value for the attribute.
+    #   Defaults to nil.
+    # @option options [Boolean] :primary_key true if the attribute represents
+    #   the primary key for the entity; otherwise false. Defaults to false.
     def initialize(name:, options:, type:)
       validate_name(name)
       validate_options(options)
@@ -35,6 +90,12 @@ module Stannum
     # @return [String] the name of the attribute type Class or Module.
     attr_reader :type
 
+    # @return [String] the name of the association if the attribute is a foreign
+    #   key; otherwise false.
+    def association_name
+      @options[:association_name]
+    end
+
     # @return [Object] the default value for the attribute, if any.
     def default
       @options[:default]
@@ -46,6 +107,29 @@ module Stannum
       !@options[:default].nil?
     end
 
+    # @param context [Object] the context object used to determinet the default
+    #   value.
+    #
+    # @return [Object] the value of the default attribute for the given context
+    #   object, if any.
+    def default_value_for(context)
+      return default unless default.is_a?(Proc)
+
+      default.arity.zero? ? default.call : default.call(context)
+    end
+
+    # @return [Boolean] true if the attribute represents the foreign key for an
+    #   association; otherwise false.
+    def foreign_key?
+      !!@options[:foreign_key]
+    end
+
+    # @return [Boolean] true if the attribute represents the primary key for the
+    #   entity; otherwise false.
+    def primary_key?
+      !!@options[:primary_key]
+    end
+
     # @return [Symbol] the name of the reader method for the attribute.
     def reader_name
       @reader_name ||= name.intern
@@ -82,13 +166,7 @@ module Stannum
     end
 
     def validate_name(name)
-      raise ArgumentError, "name can't be blank" if name.nil?
-
-      unless name.is_a?(String) || name.is_a?(Symbol)
-        raise ArgumentError, 'name must be a String or Symbol'
-      end
-
-      raise ArgumentError, "name can't be blank" if name.empty?
+      tools.assertions.validate_name(name, as: 'name')
     end
 
     def validate_options(options)

data/lib/stannum/constraints/base.rb

@@ -55,9 +55,7 @@ module Stannum::Constraints
     #
     # @return [Stannum::Constraints::Base] the cloned constraint.
     def clone(freeze: nil)
-      freeze = true if freeze.nil? && RUBY_VERSION <= '3.0.0'
-
-      super(freeze: freeze).copy_properties(self)
+      super.copy_properties(self)
     end
 
     # Checks that the given object does not match the constraint.
@@ -80,7 +78,7 @@ module Stannum::Constraints
     #   or behavior, otherwise true.
     #
     # @see #matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches?(actual)
     end
 
@@ -118,7 +116,7 @@ module Stannum::Constraints
     # @see #matches?
     # @see #negated_errors_for
     def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
-      (errors || Stannum::Errors.new).add(type, message: message)
+      (errors || Stannum::Errors.new).add(type, message:)
     end
 
     # Checks the given object against the constraint and returns errors, if any.

data/lib/stannum/constraints/enum.rb

@@ -26,7 +26,7 @@ module Stannum::Constraints
     def initialize(first, *rest, **options)
       expected_values = rest.unshift(first)
 
-      super(expected_values: expected_values, **options)
+      super(expected_values:, **options)
 
       @matching_values = Set.new(expected_values)
     end

data/lib/stannum/constraints/equality.rb

@@ -27,7 +27,7 @@ module Stannum::Constraints
     def initialize(expected_value, **options)
       @expected_value = expected_value
 
-      super(expected_value: expected_value, **options)
+      super(expected_value:, **options)
     end
 
     # @return [Object] the expected object.

data/lib/stannum/constraints/format.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A Format constraint asserts the value is a string matching the given format.
+  #
+  # @example Using a Format constraint with a String format.
+  #   format = 'Greetings'
+  #   constraint = Stannum::Constraints::Format.new(format)
+  #
+  #   constraint.matches?(nil)                    #=> false
+  #   constraint.matches?('Hello, world')         #=> false
+  #   constraint.matches?('Greetings, programs!') #=> true
+  #
+  # @example Using a Format constraint with a Regex format.
+  #   format = /\AGreetings/
+  #   constraint = Stannum::Constraints::Format.new(format)
+  #
+  #   constraint.matches?(nil)                    #=> false
+  #   constraint.matches?('Hello, world')         #=> false
+  #   constraint.matches?('Greetings, programs!') #=> true
+  class Format < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.matches_format'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.does_not_match_format'
+
+    # @param expected_format [Regex, String] The expected object.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_format, **options)
+      @expected_format = expected_format
+
+      super(expected_format:, **options)
+    end
+
+    # @return [Regex, String] the expected format.
+    attr_reader :expected_format
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      return super if type_constraint.matches?(actual)
+
+      type_constraint.errors_for(actual, errors:)
+    end
+
+    # Checks that the object is a string with the expected format.
+    #
+    # @return [true, false] true if the object is a string with the expected
+    #   format, otherwise false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      return false unless type_constraint.matches?(actual)
+
+      if expected_format.is_a?(String)
+        actual.include?(expected_format)
+      else
+        actual.match?(expected_format)
+      end
+    end
+    alias match? matches?
+
+    private
+
+    def type_constraint
+      @type_constraint ||= Stannum::Constraints::Type.new(String)
+    end
+  end
+end

data/lib/stannum/constraints/hashes/extra_keys.rb

@@ -38,19 +38,14 @@ module Stannum::Constraints::Hashes
     def initialize(expected_keys, **options)
       validate_expected_keys(expected_keys)
 
-      expected_keys =
-        if expected_keys.is_a?(Array)
-          Set.new(expected_keys)
-        else
-          expected_keys
-        end
-
-      super(expected_keys: expected_keys, **options)
+      expected_keys = Set.new(expected_keys) if expected_keys.is_a?(Array)
+
+      super(expected_keys:, **options)
     end
 
     # @return [true, false] true if the object responds to #[] and #keys and the
     #   object has at least one key that is not in expected_keys.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless hash?(actual)
 
       !(Set.new(actual.keys) <= expected_keys) # rubocop:disable Style/InverseMethods
@@ -61,13 +56,13 @@ module Stannum::Constraints::Hashes
       errors ||= Stannum::Errors.new
 
       unless actual.respond_to?(:keys)
-        return add_invalid_hash_error(actual: actual, errors: errors)
+        return add_invalid_hash_error(actual:, errors:)
       end
 
       each_extra_key(actual) do |key, value|
         key = Stannum::Support::Coercion.error_key(key)
 
-        errors[key].add(type, value: value)
+        errors[key].add(type, value:)
       end
 
       errors
@@ -96,7 +91,7 @@ module Stannum::Constraints::Hashes
     def add_invalid_hash_error(actual:, errors:)
       Stannum::Constraints::Signature
         .new(:keys)
-        .errors_for(actual, errors: errors)
+        .errors_for(actual, errors:)
     end
 
     def each_extra_key(actual)

data/lib/stannum/constraints/identity.rb

@@ -26,7 +26,7 @@ module Stannum::Constraints
     def initialize(expected_value, **options)
       @expected_value = expected_value
 
-      super(expected_value: expected_value, **options)
+      super(expected_value:, **options)
     end
 
     # @return [Object] the expected object.

data/lib/stannum/constraints/properties/base.rb

@@ -37,7 +37,7 @@ module Stannum::Constraints::Properties
       super(
         allow_empty:    !!options[:allow_empty],
         allow_nil:      !!options[:allow_nil],
-        property_names: property_names,
+        property_names:,
         **options
       )
     end

data/lib/stannum/constraints/properties/do_not_match_property.rb

@@ -41,7 +41,7 @@ module Stannum::Constraints::Properties
 
     # @return [true, false] true if the property values match the reference
     #   property value; otherwise false.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless can_match_properties?(actual)
 
       expected = expected_value(actual)
@@ -49,8 +49,8 @@ module Stannum::Constraints::Properties
       return false if skip_property?(expected)
 
       each_non_matching_property(
-        actual:      actual,
-        expected:    expected,
+        actual:,
+        expected:,
         include_all: true
       )
         .none?
@@ -63,12 +63,12 @@ module Stannum::Constraints::Properties
       return invalid_object_errors(errors) unless can_match_properties?(actual)
 
       expected = expected_value(actual)
-      matching = each_matching_property(actual: actual, expected: expected)
+      matching = each_matching_property(actual:, expected:)
 
-      return generic_errors(errors) if matching.count.zero?
+      return generic_errors(errors) if matching.none?
 
-      matching.each do |property_name, _|
-        errors[property_name].add(type, message: message)
+      matching.each do |property_name, _| # rubocop:disable Style/HashEachMethods
+        errors[property_name].add(type, message:)
       end
 
       errors
@@ -83,7 +83,7 @@ module Stannum::Constraints::Properties
 
       return true if skip_property?(expected)
 
-      each_matching_property(actual: actual, expected: expected).none?
+      each_matching_property(actual:, expected:).none?
     end
     alias match? matches?
 
@@ -95,12 +95,12 @@ module Stannum::Constraints::Properties
 
       expected = expected_value(actual)
       matching = each_non_matching_property(
-        actual:      actual,
-        expected:    expected,
+        actual:,
+        expected:,
         include_all: true
       )
 
-      return generic_errors(errors) if matching.count.zero?
+      return generic_errors(errors) if matching.none?
 
       matching.each do |property_name, value|
         errors[property_name].add(

data/lib/stannum/constraints/properties/match_property.rb

@@ -41,7 +41,7 @@ module Stannum::Constraints::Properties
 
     # @return [true, false] false if any of the property values match the
     #   reference property value; otherwise true.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless can_match_properties?(actual)
 
       expected = expected_value(actual)
@@ -49,8 +49,8 @@ module Stannum::Constraints::Properties
       return false if skip_property?(expected)
 
       each_matching_property(
-        actual:      actual,
-        expected:    expected,
+        actual:,
+        expected:,
         include_all: true
       )
         .none?
@@ -63,14 +63,14 @@ module Stannum::Constraints::Properties
       return invalid_object_errors(errors) unless can_match_properties?(actual)
 
       expected = expected_value(actual)
-      matching = each_non_matching_property(actual: actual, expected: expected)
+      matching = each_non_matching_property(actual:, expected:)
 
-      return generic_errors(errors) if matching.count.zero?
+      return generic_errors(errors) if matching.none?
 
       matching.each do |property_name, value|
         errors[property_name].add(
           type,
-          message:  message,
+          message:,
           expected: filter_parameters? ? '[FILTERED]' : expected_value(actual),
           actual:   filter_parameters? ? '[FILTERED]' : value
         )
@@ -88,7 +88,7 @@ module Stannum::Constraints::Properties
 
       return true if skip_property?(expected)
 
-      each_non_matching_property(actual: actual, expected: expected).none?
+      each_non_matching_property(actual:, expected:).none?
     end
     alias match? matches?
 
@@ -100,14 +100,14 @@ module Stannum::Constraints::Properties
 
       expected = expected_value(actual)
       matching = each_matching_property(
-        actual:      actual,
-        expected:    expected,
+        actual:,
+        expected:,
         include_all: true
       )
 
-      return generic_errors(errors) if matching.count.zero?
+      return generic_errors(errors) if matching.none?
 
-      matching.each do |property_name, _|
+      matching.each do |property_name, _| # rubocop:disable Style/HashEachMethods
         errors[property_name].add(negated_type, message: negated_message)
       end
 

data/lib/stannum/constraints/properties/matching.rb

@@ -22,7 +22,7 @@ module Stannum::Constraints::Properties
 
       validate_reference_name
 
-      super(*property_names, reference_name: reference_name, **options)
+      super(*property_names, reference_name:, **options)
     end
 
     # @return [String, Symbol] the name of the reference property to compare to.
@@ -39,9 +39,9 @@ module Stannum::Constraints::Properties
       unless block_given?
         return to_enum(
           __method__,
-          actual:      actual,
-          expected:    expected,
-          include_all: include_all
+          actual:,
+          expected:,
+          include_all:
         )
       end
 
@@ -65,9 +65,9 @@ module Stannum::Constraints::Properties
       unless block_given?
         return to_enum(
           __method__,
-          actual:      actual,
-          expected:    expected,
-          include_all: include_all
+          actual:,
+          expected:,
+          include_all:
         )
       end
 

data/lib/stannum/constraints/signature.rb

@@ -27,7 +27,7 @@ module Stannum::Constraints
 
       @expected_methods = expected_methods
 
-      super(expected_methods: expected_methods, **options)
+      super(expected_methods:, **options)
     end
 
     # @return [Array<String, Symbol>] the methods the object is expected to
@@ -36,7 +36,7 @@ module Stannum::Constraints
 
     # @return [true, false] true if the object does not respond to any of the
     #   expected methods; otherwise false.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       each_missing_method(actual).to_a == expected_methods
     end
 

data/lib/stannum/constraints/tuples/extra_items.rb

@@ -24,12 +24,12 @@ module Stannum::Constraints::Tuples
     # @param options [Hash<Symbol, Object>] Configuration options for the
     #   constraint. Defaults to an empty Hash.
     def initialize(expected_count, **options)
-      super(expected_count: expected_count, **options)
+      super(expected_count:, **options)
     end
 
     # @return [true, false] true if the object responds to #size and the object
     #   size is greater than the number of expected items; otherwise false.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless actual.respond_to?(:size)
 
       actual.size > expected_count
@@ -40,7 +40,7 @@ module Stannum::Constraints::Tuples
       errors ||= Stannum::Errors.new
 
       unless actual.respond_to?(:size)
-        return add_invalid_tuple_error(actual: actual, errors: errors)
+        return add_invalid_tuple_error(actual:, errors:)
       end
 
       each_extra_item(actual) do |item, index|
@@ -72,13 +72,13 @@ module Stannum::Constraints::Tuples
     def add_invalid_tuple_error(actual:, errors:)
       Stannum::Constraints::Signature
         .new(:size)
-        .errors_for(actual, errors: errors)
+        .errors_for(actual, errors:)
     end
 
-    def each_extra_item(actual, &block)
+    def each_extra_item(actual, &)
       return if matches?(actual)
 
-      actual[expected_count..].each.with_index(expected_count, &block)
+      actual[expected_count..].each.with_index(expected_count, &)
     end
   end
 end

data/lib/stannum/constraints/type.rb

@@ -47,10 +47,10 @@ module Stannum::Constraints
       expected_type = resolve_expected_type(expected_type)
 
       super(
-        expected_type: expected_type,
+        expected_type:,
         **resolve_required_option(
-          optional: optional,
-          required: required,
+          optional:,
+          required:,
           **options
         )
       )

data/lib/stannum/constraints/types/array_type.rb

@@ -60,7 +60,7 @@ module Stannum::Constraints::Types
     #   otherwise false.
     #
     # @see Stannum::Constraints::Types::ArrayType#matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches_type?(actual)
     end
 
@@ -126,7 +126,7 @@ module Stannum::Constraints::Types
     end
 
     def error_properties
-      super().merge(allow_empty: allow_empty?)
+      super.merge(allow_empty: allow_empty?)
     end
 
     def item_type_matches?(actual)

data/lib/stannum/constraints/types/hash_type.rb

@@ -73,7 +73,7 @@ module Stannum::Constraints::Types
     #   false.
     #
     # @see Stannum::Constraints::Types::HashType#matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches_type?(actual)
     end
 
@@ -85,9 +85,9 @@ module Stannum::Constraints::Types
 
       return add_presence_error(errors) unless presence_matches?(actual)
 
-      update_key_errors_for(actual: actual, errors: errors)
+      update_key_errors_for(actual:, errors:)
 
-      update_value_errors_for(actual: actual, errors: errors)
+      update_value_errors_for(actual:, errors:)
 
       errors
     end
@@ -155,7 +155,7 @@ module Stannum::Constraints::Types
     end
 
     def error_properties
-      super().merge(allow_empty: allow_empty?)
+      super.merge(allow_empty: allow_empty?)
     end
 
     def key_type_matches?(actual)

data/lib/stannum/constraints/union.rb

@@ -31,7 +31,7 @@ module Stannum::Constraints
     def initialize(first, *rest, **options)
       expected_constraints = rest.unshift(first)
 
-      super(expected_constraints: expected_constraints, **options)
+      super(expected_constraints:, **options)
 
       @expected_constraints = expected_constraints
     end

data/lib/stannum/constraints/uuid.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A UUID constraint asserts the value is a string in UUID format.
+  #
+  # @example Using a UUID constraint with a String format.
+  #   constraint = Stannum::Constraints::Uuid.new
+  #
+  #   constraint.matches?(nil)                                    #=> false
+  #   constraint.matches?('Hello, world')                         #=> false
+  #   constraint.matches?('01234567-89ab-cdef-0123-456789abcdef') #=> true
+  class Uuid < Stannum::Constraints::Format
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_a_uuid'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_a_uuid'
+
+    # Regular expression describing a valid upper- or lower-case UUID.
+    UUID_FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(UUID_FORMAT, **options)
+    end
+  end
+end

data/lib/stannum/constraints.rb

@@ -12,6 +12,7 @@ module Stannum
     autoload :Delegator,  'stannum/constraints/delegator'
     autoload :Enum,       'stannum/constraints/enum'
     autoload :Equality,   'stannum/constraints/equality'
+    autoload :Format,     'stannum/constraints/format'
     autoload :Hashes,     'stannum/constraints/hashes'
     autoload :Identity,   'stannum/constraints/identity'
     autoload :Nothing,    'stannum/constraints/nothing'
@@ -24,5 +25,6 @@ module Stannum
     autoload :Type,       'stannum/constraints/type'
     autoload :Types,      'stannum/constraints/types'
     autoload :Union,      'stannum/constraints/union'
+    autoload :Uuid,       'stannum/constraints/uuid'
   end
 end