bronze 0.0.1.alpha → 0.1.0

data/lib/bronze.rb

@@ -1,14 +1,5 @@
-# lib/bronze.rb
-
-require 'sleeping_king_studios/tools/all'
+# frozen_string_literal: true
 
 # A component-based application toolkit designed around dependency injection,
 # composable objects, and modern design principles.
-module Bronze
-  # The file path to the root of the Bronze directory.
-  def self.gem_path
-    @gem_path ||= __dir__.sub %r{/lib\z}, ''
-  end # method
-end # module
-
-require 'bronze/version'
+module Bronze; end

data/lib/bronze/entities.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bronze'
+
+module Bronze
+  # Namespace for library classes and modules that implement or enhance data
+  # entities, which store information about business objects in a datastore-
+  # independent implementation.
+  module Entities; end
+end

data/lib/bronze/entities/attributes.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'bronze/entities'
+require 'bronze/entities/attributes/builder'
+
+module Bronze::Entities
+  # Module for defining attributes on an entity class.
+  module Attributes
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to define when including Attributes in a class.
+    module ClassMethods
+      # Defines an attribute with the specified name and type.
+      #
+      # @example Defining an Attribute
+      #   class Book
+      #     include Bronze::Entities::Attributes
+      #
+      #     attribute :title, String
+      #   end # class
+      #
+      #   book.title
+      #   #=> nil
+      #
+      #   book.title = 'Romance of the Three Kingdoms'
+      #   book.title
+      #   #=> 'Romance of the Three Kingdoms'
+      #
+      # @param (see Attributes::Builder#build)
+      #
+      # @option (see Attributes::Builder#build)
+      #
+      # @return (see Attributes::Builder#build)
+      #
+      # @raise (see Attributes::Builder#build)
+      def attribute(attribute_name, attribute_type, attribute_options = {})
+        metadata =
+          build_attribute(attribute_name, attribute_type, attribute_options)
+
+        (@attributes ||= {})[metadata.name] = metadata
+      end
+
+      # Returns the metadata for the attributes defined for the current class.
+      #
+      # @return [Hash{Symbol => Attributes::Metadata}] the metadata for each
+      #   attribute.
+      #
+      # @note This method allocates a new hash each time it is called and is not
+      #   cached. To loop through the attributes, use the ::each_attribute
+      #   method instead.
+      def attributes
+        each_attribute
+          .with_object({}) do |(name, metadata), hsh|
+            hsh[name] = metadata
+          end
+          .freeze
+      end
+
+      # @overload each_attribute
+      #   Returns an enumerator that iterates through the attributes defined on
+      #   the entity class and any parent classes.
+      #
+      #   @return [Enumerator] the enumerator.
+      #
+      # @overload each_attribute
+      #   Iterates through the attributes defined on the entity class and any
+      #   parent classes, and yields the name and metadata of each attribute to
+      #   the block.
+      #
+      #   @yieldparam name [Symbol] The name of the attribute.
+      #   @yieldparam name [Bronze::Entities::Attributes::Metadata] The metadata
+      #     for the attribute.
+      def each_attribute
+        return enum_for(:each_attribute) unless block_given?
+
+        if superclass.respond_to?(:each_attribute)
+          superclass.each_attribute { |name, metadata| yield(name, metadata) }
+        end
+
+        (@attributes ||= {}).each { |name, metadata| yield(name, metadata) }
+      end
+
+      private
+
+      def attribute_builder
+        Bronze::Entities::Attributes::Builder.new(self)
+      end
+
+      def build_attribute(attribute_name, attribute_type, attribute_options)
+        attribute_builder
+          .build(attribute_name, attribute_type, attribute_options)
+      end
+    end
+
+    # @param attributes [Hash] The default attributes with which to initialize
+    #   the entity. Defaults to an empty hash.
+    def initialize(attributes = {})
+      initialize_attributes(attributes)
+    end
+
+    # Compares with the other object.
+    #
+    # If the other object is a Hash, returns true if the entity attributes hash
+    # is equal to the given hash. Otherwise, returns true if the other object
+    # has the same class and attributes as the entity.
+    #
+    # @param other [Bronze::Entities::Attributes, Hash] The object to compare.
+    #
+    # @return [Boolean] true if the other object matches the entity, otherwise
+    #   false.
+    def ==(other)
+      return attributes == other if other.is_a?(Hash)
+
+      other.class == self.class && other.attributes == attributes
+    end
+
+    # Updates the attributes with the given hash. If an attribute is not in the
+    # hash, it is unchanged.
+    #
+    # @raise ArgumentError if one of the keys is not a valid attribute
+    def assign_attributes(hash)
+      validate_attributes(hash)
+
+      self.class.each_attribute do |name, metadata|
+        next if metadata.read_only?
+        next unless hash.key?(name) || hash.key?(name.to_s)
+
+        set_attribute(name, hash[name] || hash[name.to_s])
+      end
+    end
+    alias_method :assign, :assign_attributes
+
+    # @return true if the entity has an attribute with the given name, otherwise
+    #   false.
+    def attribute?(name)
+      attribute_name = name.intern
+
+      self.class.each_attribute.any? { |key, _metadata| key == attribute_name }
+    rescue NoMethodError
+      raise ArgumentError, "invalid attribute #{name.inspect}"
+    end
+
+    # Returns the current value of each attribute.
+    #
+    # @return [Hash{Symbol => Object}] the attribute values.
+    def attributes
+      each_attribute.with_object({}) do |attr_name, hsh|
+        hsh[attr_name] = get_attribute(attr_name)
+      end
+    end
+
+    # Replaces the attributes with the given hash. If a non-primary key
+    # attribute is not in the hash, it is set to nil.
+    #
+    # @raise ArgumentError if one of the keys is not a valid attribute
+    def attributes=(hash)
+      validate_attributes(hash)
+
+      self.class.each_attribute do |name, metadata|
+        next if metadata.primary_key?
+
+        @attributes[name] = hash[name] || hash[name.to_s]
+      end
+    end
+
+    # @param name [String] The name of the attribute.
+    #
+    # @return [Object] the value of the given attribute.
+    #
+    # @raise ArgumentError when the attribute name is not a valid attribute
+    def get_attribute(name)
+      unless attribute?(name)
+        raise ArgumentError, "invalid attribute #{name.inspect}"
+      end
+
+      @attributes[name.intern]
+    end
+
+    # @return [String] a human-readable representation of the entity, composed
+    #   of the class name and the attribute keys and values.
+    def inspect # rubocop:disable Metrics/AbcSize
+      buffer = +'#<'
+      buffer << self.class.name
+      each_attribute.with_index do |(name, _metadata), index|
+        buffer << ',' unless index.zero?
+        buffer << ' ' << name.to_s << ': ' << get_attribute(name).inspect
+      end
+      buffer << '>'
+    end
+
+    # @param name [String] The name of the attribute.
+    # @param value [Object] The new value of the attribute.
+    #
+    # @return [Object] the new value of the given attribute.
+    #
+    # @raise ArgumentError when the attribute name is not a valid attribute
+    def set_attribute(name, value)
+      unless attribute?(name)
+        raise ArgumentError, "invalid attribute #{name.inspect}"
+      end
+
+      @attributes[name.intern] = value
+    end
+
+    private
+
+    def each_attribute
+      return enum_for(:each_attribute) unless block_given?
+
+      self.class.each_attribute { |name, _metadata| yield(name) }
+    end
+
+    def initialize_attributes(data)
+      @attributes = {}
+
+      validate_attributes(data)
+
+      self.class.each_attribute do |name, metadata|
+        name = name.intern if name.is_a?(String)
+        value = data[name] || data[name.to_s] || metadata.default
+
+        @attributes[name] = value
+      end
+    end
+
+    def validate_attributes(obj)
+      unless obj.is_a?(Hash)
+        raise ArgumentError,
+          "expected attributes to be a Hash, but was #{obj.inspect}"
+      end
+
+      obj.each_key do |name|
+        unless attribute?(name)
+          raise ArgumentError, "invalid attribute #{name.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/bronze/entities/attributes/builder.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'bronze/entities'
+require 'bronze/entities/attributes/metadata'
+require 'bronze/transforms/attributes/big_decimal_transform'
+require 'bronze/transforms/attributes/date_time_transform'
+require 'bronze/transforms/attributes/date_transform'
+require 'bronze/transforms/attributes/symbol_transform'
+require 'bronze/transforms/attributes/time_transform'
+
+module Bronze::Entities::Attributes
+  # Service class to define attributes on an entity.
+  class Builder # rubocop:disable Metrics/ClassLength
+    # Provides a list of the valid options for the attribute_options parameter
+    # for Builder#build.
+    VALID_OPTIONS = %w[
+      allow_nil
+      default
+      default_transform
+      foreign_key
+      primary_key
+      read_only
+      transform
+    ].map(&:freeze).freeze
+
+    class << self
+      # Registers a transform as the default transform for attributes with the
+      # specified type or a subtype of the specified type.
+      #
+      # This default is not retroactive - any attributes already defined will
+      # use their existing default transform, if any. If more than one
+      # registered transform has a matching type, the most recently defined
+      # transform will be used.
+      #
+      # @param type [Class] The attribute type. When defining an attribute, if
+      #   the type of the attribute is this class or a subclass of this class
+      #   and no :transform option is given, the transform for the attribute
+      #   will be the transform passed to ::attribute_transform.
+      # @param transform [Class, Bronze::Transforms::Transform] The transform to
+      #   use as the default. If this value is a transform instance, the default
+      #   transform for matching attributes will be the given transform.
+      #   Otherwise, will set the default transform to the result of ::instance
+      #   (if defined) or ::new.
+      def attribute_transform(type, transform)
+        (@attribute_transforms ||= {})[type] = transform
+      end
+
+      private
+
+      def transform_for_attribute(attribute_type)
+        (@attribute_transforms ||= {}).reverse_each do |type, transform|
+          return transform if attribute_type <= type
+        end
+
+        return super if superclass.respond_to?(:transform_for_attribute)
+      end
+    end
+
+    attribute_transform BigDecimal,
+      Bronze::Transforms::Attributes::BigDecimalTransform
+
+    attribute_transform Date,
+      Bronze::Transforms::Attributes::DateTransform
+
+    attribute_transform DateTime,
+      Bronze::Transforms::Attributes::DateTimeTransform
+
+    attribute_transform Symbol,
+      Bronze::Transforms::Attributes::SymbolTransform
+
+    attribute_transform Time,
+      Bronze::Transforms::Attributes::TimeTransform
+
+    # @param entity_class [Class] The entity class on which attributes will be
+    #   defined.
+    def initialize(entity_class)
+      @entity_class = entity_class
+    end
+
+    # @return [Class] the entity class on which attributes will be defined.
+    attr_reader :entity_class
+
+    # Defines an attribute on the entity class.
+    #
+    # @example Defining an Attribute
+    #   class Book < Bronze::Entities::Entity; end
+    #
+    #   book = Book.new
+    #   book.title
+    #   #=> NoMethodError: undefined method `title'
+    #
+    #   builder = Bronze::Entities::Attributes::Builder.new(Book)
+    #   builder.define_attribute :title, String
+    #
+    #   book.title
+    #   #=> nil
+    #
+    #   book.title = 'Romance of the Three Kingdoms'
+    #   book.title
+    #   #=> 'Romance of the Three Kingdoms'
+    #
+    # @param attribute_name [Symbol, String] The name of the attribute to
+    #   define.
+    # @param attribute_type [Class] The type of the attribute to define.
+    # @param attribute_options [Hash] Additional options for building the
+    #   attribute.
+    #
+    # @option attribute_options [Object, Proc] :default The default value for
+    #   the attribute. If the attribute value is nil or has not been set, the
+    #   attribute will be set to the default. If the default is a Proc, the
+    #   Proc will be called each time and the attribute set to the return value.
+    #   Otherwise, the attribute will be set to the default value.
+    # @option attribute_options [Boolean] :default_transform If a transform is
+    #   set, marks the transform as a default transform, which can be overriden
+    #   when normalizing the attribute.
+    # @option attribute_options [Boolean] :foreign_key Marks the attribute as a
+    #   foreign key. Will be set to true by association builders, and generally
+    #   should not be set manually. Defaults to false.
+    # @option attribute_options [Boolean] :read_only If true, the writer method
+    #   for the attribute will be set as private. Defaults to false.
+    # @option attribute_options [Class, Bronze::Transform] :transform If set,
+    #   the attribute will be normalized using this transform. By default,
+    #   certain attribute types will be transformed - BigDecimal, Date,
+    #   DateTime, Symbol, and Time.
+    #
+    # @return [Attributes::Metadata] The generated metadata for the
+    #   attribute.
+    #
+    # @raise Builder::Error if the attribute name or attribute type is missing
+    #   or invalid.
+    def build(attribute_name, attribute_type, attribute_options = {})
+      validate_attribute_name(attribute_name)
+      validate_attribute_opts(attribute_options)
+
+      characterize(
+        attribute_name,
+        attribute_type,
+        attribute_options
+      )
+        .tap { |metadata| define_property_methods(metadata) }
+    end
+
+    private
+
+    def attributes_module
+      @attributes_module ||= define_attributes_module
+    end
+
+    def characterize(attribute_name, attribute_type, attribute_options)
+      Bronze::Entities::Attributes::Metadata.new(
+        attribute_name,
+        attribute_type,
+        normalize_options(attribute_options, type: attribute_type)
+      )
+    end
+
+    def define_attributes_module
+      mod =
+        if entity_class.const_defined?(:Attributes, false)
+          entity_class::Attributes
+        else
+          entity_class.const_set(:Attributes, Module.new)
+        end
+
+      entity_class.send(:include, mod) unless entity_class < mod
+
+      mod
+    end
+
+    def define_property_methods(metadata)
+      define_reader(metadata)
+      define_writer(metadata)
+    end
+
+    def define_reader(metadata)
+      attr_name = metadata.name
+
+      attributes_module.send :define_method,
+        metadata.reader_name,
+        -> { get_attribute(attr_name) }
+    end
+
+    def define_writer(metadata)
+      attr_name = metadata.name
+
+      attributes_module.send :define_method,
+        metadata.writer_name,
+        ->(value) { set_attribute(attr_name, value) }
+
+      return unless metadata.read_only?
+
+      attributes_module.send(:private, metadata.writer_name)
+    end
+
+    def normalize_options(options, type:)
+      options = options.each.with_object({}) do |(key, value), hsh|
+        hsh[key.intern] = value
+      end
+
+      unless options.key?(:default_transform)
+        options[:default_transform] = !options[:transform]
+      end
+
+      options[:transform] =
+        normalize_transform(options[:transform], type: type)
+
+      options
+    end
+
+    def normalize_transform(transform, type:)
+      transform ||= self.class.send(:transform_for_attribute, type)
+
+      return nil if transform.nil?
+
+      transform_instance(transform)
+    end
+
+    def transform_instance(transform)
+      return transform unless transform.is_a?(Class)
+
+      return transform.instance if transform.respond_to?(:instance)
+
+      transform.new
+    end
+
+    def validate_attribute_name(attribute_name)
+      unless attribute_name.is_a?(String) || attribute_name.is_a?(Symbol)
+        message = 'expected attribute name to be a String or Symbol, but was ' \
+                  "#{attribute_name.inspect}"
+
+        raise ArgumentError, message, caller[1..-1]
+      end
+
+      return unless attribute_name.to_s.empty?
+
+      raise ArgumentError, "attribute name can't be blank", caller[1..-1]
+    end
+
+    def validate_attribute_opts(attribute_options)
+      attribute_options.each do |key, _value|
+        next if VALID_OPTIONS.include?(key.to_s)
+
+        raise ArgumentError,
+          "invalid attribute option #{key.inspect}",
+          caller[1..-1]
+      end
+    end
+  end
+end