stannum 0.3.0 → 0.4.0

data/lib/stannum/entities/associations.rb

@@ -0,0 +1,451 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+require 'stannum/schema'
+
+module Stannum::Entities
+  # Methods for defining and accessing entity associations.
+  module Associations # rubocop:disable Metrics/ModuleLength
+    # Class methods to extend the class when including Associations.
+    module ClassMethods # rubocop:disable Metrics/ModuleLength
+      START_WITH_CAPITAL_LETTER = /\A[A-Z]/
+      private_constant :START_WITH_CAPITAL_LETTER
+
+      # Defines an association on the entity.
+      #
+      # When an association is defined, each of the following steps is executed:
+      #
+      # - Adds the association to ::Associations and the .associations class
+      #   method.
+      # - Adds the association to #association and the associated methods, such
+      #   as #assign_associations, #[] and #[]=.
+      # - Defines reader and writer methods.
+      #
+      # @overload association(arity, assoc_name, **options)
+      #   Defines an association with the given name. The class of the
+      #   associated object is determined automatically based on the association
+      #   name, or can be specified with the :class_name keyword.
+      #
+      #   @param arity [:one, :many] :one if the association has one item, or
+      #     :many if the association can have multiple items.
+      #   @param assoc_name [String, Symbol] the name of the association.
+      #   @param options [Hash] additional options for the association.
+      #
+      #   @option options [String] :class_name the name of the associated class.
+      #   @option options [true, Hash] :foreign_key the foreign key options for
+      #     the association. Can be true, or a Hash containing :name and/or
+      #     :type keys.
+      #
+      #   @return [Symbol] the association name as a symbol.
+      #
+      # @overload association(arity, assoc_type, **options)
+      #   Defines an association with the given class. The name of the
+      #   association is determined automatically based on the association
+      #   class.
+      #
+      #   @param arity [:one, :many] :one if the association has one item, or
+      #     :many if the association can have multiple items.
+      #   @param assoc_type [String, Symbol, Class] the type of the associated
+      #   @param options [Hash] additional options for the association.
+      #
+      #   @option options [true, Hash] :foreign_key the foreign key options for
+      #     the association. Can be true, or a Hash containing :name and/or
+      #     :type keys.
+      #
+      #   @return [Symbol] the association name as a symbol.
+      def association(arity, class_or_name, **options) # rubocop:disable Metrics/MethodLength
+        assoc_class                     =
+          resolve_association_class(arity)
+        assoc_name, assoc_type, options =
+          resolve_parameters(arity, class_or_name, options)
+
+        association = associations.define(
+          definition_class: assoc_class,
+          name:             assoc_name,
+          type:             assoc_type,
+          options:          parse_options(assoc_name, **options)
+        )
+        define_foreign_key(association) if association.foreign_key?
+
+        association.name.intern
+      end
+      alias define_association association
+
+      # @return [Stannum::Schema] The associations Schema object for the Entity.
+      def associations
+        self::Associations
+      end
+
+      # @return [Class] the default type for foreign key attributes.
+      def default_foreign_key_type
+        (defined?(primary_key_type) && primary_key_type) || Integer
+      end
+
+      private
+
+      def association_name_for(arity, class_or_name, configured) # rubocop:disable Metrics/MethodLength
+        if configured
+          raise ArgumentError,
+            %(ambiguous class name "#{class_or_name}" or "#{configured}" ) \
+            '- do not provide both a class and a :class_name keyword'
+        end
+
+        assoc_name = tools.string_tools.underscore(
+          class_or_name.to_s.split('::').last
+        )
+        assoc_name = tools.string_tools.singularize(assoc_name) if arity == :one
+        assoc_name = tools.string_tools.pluralize(assoc_name) if arity == :many
+
+        assoc_name
+      end
+
+      def class_name?(class_or_name)
+        START_WITH_CAPITAL_LETTER.match?(class_or_name)
+      end
+
+      def define_foreign_key(association)
+        define_attribute(
+          association.foreign_key_name,
+          association.foreign_key_type,
+          association_name: association.name,
+          foreign_key:      true,
+          required:         false
+        )
+      end
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::Associations)
+
+        Stannum::Entities::Associations.apply(other) if other.is_a?(Class)
+      end
+
+      def inherited(other)
+        super
+
+        Stannum::Entities::Associations.apply(other)
+      end
+
+      def parse_foreign_key_options(assoc_name, foreign_key) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+        return {} if foreign_key == false
+
+        foreign_key = {} if foreign_key == true
+
+        if foreign_key.is_a?(String) || foreign_key.is_a?(Symbol)
+          foreign_key = { name: foreign_key.to_s }
+        end
+
+        unless foreign_key.is_a?(Hash)
+          raise InvalidOptionError, "invalid foreign key #{foreign_key.inspect}"
+        end
+
+        name = foreign_key.fetch(:name) { "#{assoc_name}_id" }
+        type = foreign_key.fetch(:type) { default_foreign_key_type }
+
+        {
+          foreign_key_name: name,
+          foreign_key_type: type
+        }
+      end
+
+      def parse_inverse_options(inverse)
+        hsh = {
+          entity_class_name: name,
+          inverse:           true
+        }
+
+        if inverse.is_a?(String) || inverse.is_a?(Symbol)
+          hsh[:inverse_name] = inverse.to_s
+        end
+
+        hsh
+      end
+
+      def parse_options(assoc_name, **options) # rubocop:disable Metrics/MethodLength
+        if options.key?(:foreign_key)
+          options = options.merge(
+            parse_foreign_key_options(assoc_name, options.delete(:foreign_key))
+          )
+        end
+
+        if options[:inverse] != false
+          options = options.merge(
+            parse_inverse_options(options.delete(:inverse))
+          )
+        end
+
+        options
+      end
+
+      def resolve_association_class(arity)
+        return Stannum::Associations::One if arity == :one
+
+        return Stannum::Associations::Many if arity == :many
+
+        raise ArgumentError, 'association arity must be :one or :many'
+      end
+
+      def resolve_association_type(assoc_name)
+        tools.string_tools.chain(assoc_name, :singularize, :camelize)
+      end
+
+      def resolve_parameters(arity, class_or_name, options)
+        class_name = options.delete(:class_name)
+
+        if class_or_name.is_a?(Module) || class_name?(class_or_name)
+          assoc_name = association_name_for(arity, class_or_name, class_name)
+          assoc_type = class_or_name
+
+          return [assoc_name, assoc_type, options]
+        end
+
+        assoc_name = tools.string_tools.underscore(class_or_name.to_s)
+        assoc_type = class_name || resolve_association_type(assoc_name)
+
+        [assoc_name, assoc_type, options]
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+
+    # Exception class raised when an invalid option value is set.
+    class InvalidOptionError < StandardError; end
+
+    class << self
+      # Generates Associations schema for the class.
+      #
+      # Creates a new Stannum::Schema and sets it as the class's :Associations
+      # constant. If the superclass is an entity class (and already defines its
+      # own Associations, includes the superclass Associations in the class
+      # Associations). Finally, includes the class Associations in the class.
+      #
+      # @param other [Class] the class to which attributes are added.
+      def apply(other)
+        return unless other.is_a?(Class)
+
+        return if entity_class?(other)
+
+        other.const_set(:Associations, build_schema)
+
+        if entity_class?(other.superclass)
+          other::Associations.include(other.superclass::Associations)
+        end
+
+        other.include(other::Associations)
+      end
+
+      private
+
+      def build_schema
+        Stannum::Schema.new(
+          property_class: Stannum::Association,
+          property_name:  'associations'
+        )
+      end
+
+      def entity_class?(other)
+        other.const_defined?(:Associations, false)
+      end
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+
+        apply(other) if other.is_a?(Class)
+      end
+    end
+
+    # @param properties [Hash] the properties used to initialize the entity.
+    def initialize(**properties)
+      @associations        = {}
+      @association_proxies = {}
+
+      super
+    end
+
+    # Updates the struct's associations with the given values.
+    #
+    # This method is used to update some (but not all) of the associations of
+    # the struct. For each key in the hash, it calls the corresponding writer
+    # method with the value for that association.
+    #
+    # Any associations that are not in the given hash are unchanged, as are any
+    # properties that are not associations.
+    #
+    # If the associations hash includes any keys that do not correspond to an
+    # association, the struct will raise an error.
+    #
+    # @param associations [Hash] The associations for the struct.
+    #
+    # @raise ArgumentError if any key is not a valid association.
+    #
+    # @see #associations=
+    def assign_associations(associations)
+      unless associations.is_a?(Hash)
+        raise ArgumentError, 'associations must be a Hash'
+      end
+
+      set_associations(associations, force: false)
+    end
+
+    # @private
+    def association_proxy_for(association)
+      @association_proxies[association.name] ||=
+        Stannum::Associations::Many::Proxy.new(association:, entity: self)
+    end
+
+    # Collects the entity associations.
+    #
+    # @return [Hash<String, Object>] the entity associations.
+    def associations
+      @associations.dup
+    end
+
+    # Replaces the entity's associations with the given values.
+    #
+    # This method is used to update all of the associations of the entity. For
+    # each association, the writer method is called with the value from the
+    # hash. Non-association properties are unchanged.
+    #
+    # If the associations hash includes any keys that do not correspond to a
+    # valid association, the entity will raise an error.
+    #
+    # @param associations [Hash] the associations to assign to the entity.
+    #
+    # @raise ArgumentError if any key is not a valid association.
+    #
+    # @see #assign_attributes
+    def associations=(associations)
+      unless associations.is_a?(Hash)
+        raise ArgumentError, 'associations must be a Hash'
+      end
+
+      set_associations(associations, force: true)
+    end
+
+    # (see Stannum::Entities::Properties#properties)
+    def properties
+      super.merge(associations)
+    end
+
+    # Retrieves the association value for the requested key.
+    #
+    # If the :safe flag is set, will verify that the association name is valid
+    # (a non-empty String or Symbol) and that there is a defined association by
+    # that name. By default, :safe is set to true.
+    #
+    # @param key [String, Symbol] the key of the association to retrieve.
+    # @param safe [Boolean] if true, validates the association key.
+    #
+    # @return [Object] the value of the requested association.
+    #
+    # @api private
+    def read_association(key, safe: true)
+      if safe
+        tools.assertions.validate_name(key, as: 'association')
+
+        unless self.class.associations.key?(key.to_s)
+          raise ArgumentError, "unknown association #{key.inspect}"
+        end
+      end
+
+      @associations[key.to_s]
+    end
+
+    # Assigns the association value for the requested key.
+    #
+    # If the :safe flag is set, will verify that the association name is valid
+    # (a non-empty String or Symbol) and that there is a defined association by
+    # that name. By default, :safe is set to true.
+    #
+    # @param key [String, Symbol] the key of the association to assign.
+    # @param value [Object] the value to assign.
+    # @param safe [Boolean] if true, validates the association key.
+    #
+    # @return [Object] the assigned value.
+    #
+    # @api private
+    def write_association(key, value, safe: true)
+      if safe
+        tools.assertions.validate_name(key, as: 'association')
+
+        unless self.class.associations.key?(key.to_s)
+          raise ArgumentError, "unknown association #{key.inspect}"
+        end
+      end
+
+      @associations[key.to_s] = value
+    end
+
+    private
+
+    def get_property(key)
+      return @associations[key.to_s] if associations.key?(key.to_s)
+
+      super
+    end
+
+    def inspect_association(value, **options) # rubocop:disable Metrics/MethodLength
+      if value.nil?
+        'nil'
+      elsif value.is_a?(Array)
+        value
+          .map { |item| inspect_association(item, **options) }
+          .join(', ')
+          .then { |str| "[#{str}]" }
+      elsif value.respond_to?(:inspect_with_options)
+        value.inspect_with_options(**options)
+      else
+        value.inspect
+      end
+    end
+
+    def inspect_properties(**options)
+      return super unless options.fetch(:associations, true)
+
+      @associations.reduce(super) do |memo, (key, value)|
+        mapped = inspect_association(value, **options, associations: false)
+
+        "#{memo} #{key}: #{mapped}"
+      end
+    end
+
+    def set_associations(associations, force:)
+      associations, non_matching =
+        bisect_properties(associations, self.class.associations)
+
+      unless non_matching.empty?
+        handle_invalid_properties(non_matching, as: 'association')
+      end
+
+      write_associations(associations, force:)
+    end
+
+    def set_properties(properties, force:)
+      associations, non_matching =
+        bisect_properties(properties, self.class.associations)
+
+      super(non_matching, force:)
+
+      write_associations(associations, force:)
+    end
+
+    def set_property(key, value)
+      return super unless associations.key?(key.to_s)
+
+      send(self.class.associations[key.to_s].writer_name, value)
+    end
+
+    def write_associations(associations, force:)
+      self.class.associations.each do |assoc_name, association|
+        next unless associations.key?(assoc_name) || force
+
+        send(association.writer_name, associations[assoc_name])
+      end
+    end
+  end
+end

data/lib/stannum/entities/attributes.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 require 'stannum/entities'
-require 'stannum/schema'
 
 module Stannum::Entities
   # Methods for defining and accessing entity attributes.
-  module Attributes
+  module Attributes # rubocop:disable Metrics/ModuleLength
     # Class methods to extend the class when including Attributes.
     module ClassMethods
       # Defines an attribute on the entity.
@@ -25,17 +24,20 @@ module Stannum::Entities
       #
       # @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.
       #
-      # @return [Symbol] The attribute name as a symbol.
+      # @return [Symbol] the attribute name as a symbol.
       def attribute(attr_name, attr_type, **options)
-        attributes.define_attribute(
+        attributes.define(
           name:    attr_name,
           type:    attr_type,
-          options: options
+          options:
         )
 
         attr_name.intern
       end
+      alias define_attribute attribute
 
       # @return [Stannum::Schema] The attributes Schema object for the Entity.
       def attributes
@@ -73,7 +75,7 @@ module Stannum::Entities
 
         return if entity_class?(other)
 
-        other.const_set(:Attributes, Stannum::Schema.new)
+        other.const_set(:Attributes, build_schema)
 
         if entity_class?(other.superclass)
           other::Attributes.include(other.superclass::Attributes)
@@ -84,6 +86,13 @@ module Stannum::Entities
 
       private
 
+      def build_schema
+        Stannum::Schema.new(
+          property_class: Stannum::Attribute,
+          property_name:  'attributes'
+        )
+      end
+
       def entity_class?(other)
         other.const_defined?(:Attributes, false)
       end
@@ -101,6 +110,8 @@ module Stannum::Entities
     def initialize(**properties)
       @attributes = {}
 
+      self.class.attributes.each_key { |key| @attributes[key] = nil }
+
       super
     end
 
@@ -117,9 +128,9 @@ module Stannum::Entities
     # If the attributes hash includes any keys that do not correspond to an
     # attribute, the struct will raise an error.
     #
-    # @param attributes [Hash] The initial attributes for the struct.
+    # @param attributes [Hash] The attributes for the struct.
     #
-    # @raise ArgumentError if the key is not a valid attribute.
+    # @raise ArgumentError if any key is not a valid attribute.
     #
     # @see #attributes=
     def assign_attributes(attributes)
@@ -132,7 +143,7 @@ module Stannum::Entities
 
     # Collects the entity attributes.
     #
-    # @param attributes [Hash<String, Object>] the entity attributes.
+    # @return [Hash<String, Object>] the entity attributes.
     def attributes
       @attributes.dup
     end
@@ -166,16 +177,100 @@ module Stannum::Entities
       super.merge(attributes)
     end
 
+    # Retrieves the attribute value for the requested key.
+    #
+    # If the :safe flag is set, will verify that the attribute name is valid (a
+    # non-empty String or Symbol) and that there is a defined attribute by that
+    # name. By default, :safe is set to true.
+    #
+    # @param key [String, Symbol] the key of the attribute to retrieve.
+    # @param safe [Boolean] if true, validates the attribute key.
+    #
+    # @return [Object] the value of the requested attribute.
+    #
+    # @api private
+    def read_attribute(key, safe: true)
+      if safe
+        tools.assertions.validate_name(key, as: 'attribute')
+
+        unless self.class.attributes.key?(key.to_s)
+          raise ArgumentError, "unknown attribute #{key.inspect}"
+        end
+      end
+
+      @attributes[key.to_s]
+    end
+
+    # Assigns the attribute value for the requested key.
+    #
+    # If the :safe flag is set, will verify that the attribute name is valid (a
+    # non-empty String or Symbol) and that there is a defined attribute by that
+    # name. By default, :safe is set to true.
+    #
+    # @param key [String, Symbol] the key of the attribute to assign.
+    # @param value [Object] the value to assign.
+    # @param safe [Boolean] if true, validates the attribute key.
+    #
+    # @return [Object] the assigned value.
+    #
+    # @api private
+    def write_attribute(key, value, safe: true)
+      if safe
+        tools.assertions.validate_name(key, as: 'attribute')
+
+        unless self.class.attributes.key?(key.to_s)
+          raise ArgumentError, "unknown attribute #{key.inspect}"
+        end
+      end
+
+      @attributes[key.to_s] = value
+    end
+
     private
 
+    def apply_defaults_for(attributes) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      with_value, with_proc = bisect_attributes_by_default_type
+
+      with_value.each do |attribute|
+        next unless @attributes[attribute.name].nil?
+        next unless attributes.key?(attribute.name)
+
+        send(attribute.writer_name, attribute.default)
+      end
+
+      with_proc.each do |attribute|
+        next unless @attributes[attribute.name].nil?
+        next unless attributes.key?(attribute.name)
+
+        send(attribute.writer_name, attribute.default_value_for(self))
+      end
+    end
+
+    def bisect_attributes_by_default_type
+      with_value = []
+      with_proc  = []
+
+      self.class.attributes.each_value do |attribute|
+        next unless attribute.default?
+
+        (attribute.default.is_a?(Proc) ? with_proc : with_value) << attribute
+      end
+
+      [with_value, with_proc]
+    end
+
     def get_property(key)
       return @attributes[key.to_s] if attributes.key?(key.to_s)
 
       super
     end
 
-    def inspectable_properties
-      super().merge(attributes)
+    def inspect_properties(**options)
+      return super unless options.fetch(:attributes, true)
+
+      @attributes.reduce(super) do |memo, (key, value)|
+        "#{memo} #{key}: #{value.inspect}"
+      end
     end
 
     def set_attributes(attributes, force:)
@@ -186,16 +281,16 @@ module Stannum::Entities
         handle_invalid_properties(non_matching, as: 'attribute')
       end
 
-      write_attributes(attributes, force: force)
+      write_attributes(attributes, force:)
     end
 
     def set_properties(properties, force:)
       attributes, non_matching =
         bisect_properties(properties, self.class.attributes)
 
-      super(non_matching, force: force)
+      super(non_matching, force:)
 
-      write_attributes(attributes, force: force)
+      write_attributes(attributes, force:)
     end
 
     def set_property(key, value)
@@ -208,11 +303,14 @@ module Stannum::Entities
       self.class.attributes.each do |attr_name, attribute|
         next unless attributes.key?(attr_name) || force
 
-        send(
-          attribute.writer_name,
-          attributes[attr_name].nil? ? attribute.default : attributes[attr_name]
-        )
+        if attributes[attr_name].nil? && attribute.default?
+          @attributes[attr_name] = nil
+        else
+          send(attribute.writer_name, attributes[attr_name])
+        end
       end
+
+      apply_defaults_for(force ? @attributes : attributes)
     end
   end
 end

data/lib/stannum/entities/constraints.rb

@@ -29,6 +29,7 @@ module Stannum::Entities
 
         returned
       end
+      alias define_attribute attribute
     end
 
     # Class methods to extend the class when including Constraints.
@@ -76,11 +77,11 @@ module Stannum::Entities
       #   @param attr_name [String, Symbol] The name of the attribute or
       #     property to constrain.
       #   @param constraint [Stannum::Constraints::Base] The constraint to add.
-      def constraint(attr_name = nil, constraint = nil, &block)
+      def constraint(attr_name = nil, constraint = nil, &)
         attr_name, constraint = resolve_constraint(attr_name, constraint)
 
         if block_given?
-          constraint = Stannum::Constraint.new(&block)
+          constraint = Stannum::Constraint.new(&)
         else
           validate_constraint(constraint)
         end