bronze 0.0.1.alpha → 0.1.0

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'bronze/entities'
+
+module Bronze::Entities::Attributes
+  # Data class that characterizes an entity attribute and allows for reflection
+  # on its properties and options.
+  class Metadata
+    # @param name [String, Symbol] The name of the attribute.
+    # @param type [Class] The type of the attribute.
+    # @param options [Hash] Additional options for the attribute.
+    def initialize(name, type, options)
+      @name        = name.intern
+      @type        = type
+      @options     = options
+      @reader_name = name.intern
+      @writer_name = "#{name}=".intern
+    end
+
+    # @return [String, Symbol] the name of the attribute.
+    attr_reader :name
+
+    # @return [Hash] additional options for the attribute.
+    attr_reader :options
+
+    # @return [String, Symbol] the name of the attribute's reader method.
+    attr_reader :reader_name
+
+    # @return [Class] the type of the attribute.
+    attr_reader :type
+
+    # @return [String, Symbol] the name of the attribute's writer method.
+    attr_reader :writer_name
+
+    # @return [Boolean] true if the attribute allows nil values, otherwise
+    #   false.
+    def allow_nil?
+      !!@options[:allow_nil]
+    end
+
+    # @return [Object] the default value for the attribute.
+    def default
+      val = @options[:default]
+
+      val.is_a?(Proc) ? val.call : val
+    end
+    alias_method :default_value, :default
+
+    # @return [Boolean] true if the default value is set, otherwise false.
+    def default?
+      !@options[:default].nil?
+    end
+
+    # @return [Boolean] true if the attribute does not have a custom transform,
+    #   or if the transform is flagged as a default transform; otherwise false.
+    def default_transform?
+      !!@options[:default_transform] || !transform?
+    end
+
+    # @return [Boolean] true if the attribute is a foreign key, otherwise false.
+    def foreign_key?
+      !!@options[:foreign_key]
+    end
+
+    # @return [Boolean] true if the attribute is a primary key, otherwise false.
+    def primary_key?
+      !!@options[:primary_key]
+    end
+
+    # @return [Boolean] true if the attribute is read-only, otherwise false.
+    def read_only?
+      !!@options[:read_only]
+    end
+
+    # @return [Bronze::Transform] the transform used to normalize and
+    #   denormalize the attribute.
+    def transform
+      @options[:transform]
+    end
+
+    # @return [Boolean] true if the attribute has a custom transform, otherwise
+    #   false.
+    def transform?
+      !!@options[:transform]
+    end
+  end
+end

data/lib/bronze/entities/normalization.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'bronze/entities'
+
+module Bronze::Entities
+  # Module for transforming entities to and from a normal form.
+  module Normalization
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to define when including Normalization in a class.
+    module ClassMethods
+      # Returns an entity instance from the given normalized representation.
+      #
+      # @param attributes [Hash] A hash with String keys and normal values.
+      #
+      # @return [Bronze::Entity] The entity.
+      def denormalize(attributes)
+        entity = new
+
+        entity.send(:validate_attributes, attributes)
+
+        each_attribute do |name, metadata|
+          value = attributes[name] || attributes[name.to_s]
+          value = metadata.transform.denormalize(value) if metadata.transform?
+
+          next if value.nil? && metadata.primary_key?
+
+          entity.set_attribute(name, value)
+        end
+
+        entity
+      end
+    end
+
+    # Returns a normalized representation of the entity. The normal
+    # representation of an entity is a hash with String keys. Each value must be
+    # nil, a literal value (true, false, a String, an Integer, a Float, etc), an
+    # Array of normal values, or a Hash with String keys and normal values.
+    #
+    # @param [Array<Class>] permit An optional array of types to normalize
+    #   as-is, rather than applying a transform. Only default transforms can be
+    #   permitted, i.e. the built-in default transforms for BigDecimal, Date,
+    #   DateTime, Symbol, and Time, or for an attribute with the
+    #   :default_transform flag set to true.
+    #
+    # @return [Hash] The normal representation.
+    def normalize(permit: [])
+      self.class.each_attribute.with_object({}) do |(name, metadata), hsh|
+        value = get_attribute(name)
+        value = normalize_attribute(value, metadata: metadata, permit: permit)
+
+        hsh[name.to_s] = value
+      end
+    end
+
+    private
+
+    def normalize_attribute(value, metadata:, permit:)
+      return value unless metadata.transform?
+
+      return value if metadata.default_transform? &&
+                      Array(permit).any? { |type| metadata.type <= type }
+
+      metadata.transform.normalize(value)
+    end
+  end
+end

data/lib/bronze/entities/primary_key.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'bronze/entities'
+
+module Bronze::Entities
+  # Module for defining a primary key attribute on an entity class.
+  module PrimaryKey
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+
+    # Class methods to define when including PrimaryKey in a class.
+    module ClassMethods
+      # Defines the primary key with the specified name and type.
+      #
+      # @example Defining a Primary Key
+      #   class Book
+      #     include Bronze::Entities::Attributes
+      #     include Bronze::Entities::PrimaryKey
+      #
+      #     next_id = -1
+      #     define_primary_key :id, Integer, default: -> { next_id += 1 }
+      #   end # class
+      #
+      #   book = Book.new
+      #   book.id
+      #   #=> 0
+      #
+      #   Book.new.id
+      #   #=> 1
+      #
+      # @param attribute_name [Symbol, String] The name of the primary key.
+      # @param attribute_type [Class] The type of the primary key.
+      # @param default [Proc] The proc to call when generating a new primary
+      #   key.
+      #
+      # @return [Attributes::Metadata] the metadata for the primary key
+      #   attribute.
+      def define_primary_key(attribute_name, attribute_type, default:)
+        @primary_key =
+          attribute(
+            attribute_name,
+            attribute_type,
+            default:     default,
+            primary_key: true,
+            read_only:   true
+          )
+      end
+
+      # @return [Attributes::Metadata] the metadata for the primary key
+      #   attribute, or nil if the primary key is not defined.
+      def primary_key
+        return @primary_key if @primary_key
+
+        return superclass.primary_key if superclass.respond_to?(:primary_key)
+
+        nil
+      end
+    end
+
+    # @return [Object] the primary key for the current entity.
+    def primary_key
+      attribute_name = self.class.primary_key&.name
+
+      return nil unless attribute_name
+
+      get_attribute(attribute_name)
+    end
+  end
+end

data/lib/bronze/entities/primary_keys.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bronze/entities'
+
+module Bronze::Entities
+  # Namespace for primary key implementations.
+  module PrimaryKeys; end
+end

data/lib/bronze/entities/primary_keys/uuid.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'sleeping_king_studios/tools/toolbox/mixin'
+
+require 'bronze/entities/primary_key'
+require 'bronze/entities/primary_keys'
+
+module Bronze::Entities::PrimaryKeys
+  # Module for defining a UUID primary key attribute on an entity class.
+  module Uuid
+    extend SleepingKingStudios::Tools::Toolbox::Mixin
+    include Bronze::Entities::PrimaryKey
+
+    # Class methods to define when including PrimaryKeys::Uuid in a class.
+    module ClassMethods
+      # Defines a UUID primary key with the specified name.
+      #
+      # @example Defining a Primary Key
+      #   class Book
+      #     include Bronze::Entities::Attributes
+      #     include Bronze::Entities::PrimaryKey::Uuid
+      #
+      #     define_primary_key :id
+      #   end # class
+      #
+      #   book = Book.new
+      #   book.id
+      #   #=> '19eeac71-2b8b-439a-8f5d-cb63f26e4ddf'
+      #
+      #   Book.new.id
+      #   #=> '4c08d721-8aa2-4ff9-942f-852b5c33bcc9'
+      #
+      # @param attribute_name [Symbol, String] The name of the primary key.
+      #
+      # @return [Attributes::Metadata] the metadata for the primary key
+      #   attribute.
+      def define_primary_key(attribute_name)
+        super(attribute_name, String, default: -> { SecureRandom.uuid })
+      end
+    end
+  end
+end

data/lib/bronze/entity.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bronze/entities/attributes'
+require 'bronze/entities/normalization'
+require 'bronze/entities/primary_key'
+
+module Bronze
+  # Base class for implementing data entities.
+  class Entity
+    include Bronze::Entities::Attributes
+    include Bronze::Entities::Normalization
+    include Bronze::Entities::PrimaryKey
+  end
+end

data/lib/bronze/not_implemented_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bronze'
+
+module Bronze
+  # Exception subclass to indicate an intended method has not been implemented
+  # on the receiver.
+  class NotImplementedError < StandardError
+    # @param receiver [Object] The object receiving the message.
+    # @param method_name [String] The name of the expected method.
+    def initialize(receiver, method_name)
+      receiver_message =
+        receiver.is_a?(Module) ? "#{receiver}." : "#{receiver.class}#"
+
+      super("#{receiver_message}#{method_name} is not implemented")
+    end
+  end
+end

data/lib/bronze/transform.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'bronze/not_implemented_error'
+require 'bronze/transforms'
+
+module Bronze
+  # Abstract class for converting an object to and from a normalized form. This
+  # can be a hash for database serialization, an active model object, another
+  # object, or any other transformation.
+  class Transform
+    # Converts an object from its normalized form.
+    #
+    # @param _object [Object] The object to convert.
+    #
+    # @return [Object] The converted object.
+    def denormalize(_object)
+      raise Bronze::NotImplementedError.new(self, :denormalize)
+    end
+
+    # Converts an object to its normalized form.
+    #
+    # @param _object [Object] The entity to convert.
+    #
+    # @return [Object] The converted object.
+    def normalize(_object)
+      raise Bronze::NotImplementedError.new(self, :normalize)
+    end
+  end
+end

data/lib/bronze/transforms.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'bronze'
+
+module Bronze
+  # Namespace for defining transform objects, which that map a data object into
+  # another representation of that data.
+  module Transforms; end
+end

data/lib/bronze/transforms/attributes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'bronze/transforms'
+
+module Bronze::Transforms
+  # Namespace for defining attribute transforms, which convert data objects to
+  # normalized forms.
+  module Attributes; end
+end

data/lib/bronze/transforms/attributes/big_decimal_transform.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+require 'bronze/transform'
+require 'bronze/transforms/attributes'
+
+module Bronze::Transforms::Attributes
+  # Transform class that normalizes a BigDecimal to a string representation.
+  class BigDecimalTransform < Bronze::Transform
+    # @return [BigDecimalTransform] a memoized instance of BigDecimalTranform.
+    def self.instance
+      @instance ||= new
+    end
+
+    # Converts a normalized BigDecimal (a String) to a BigDecimal instance.
+    #
+    # @param value [String] The normalized string.
+    #
+    # @return [BigDecimal] the denormalized instance.
+    def denormalize(value)
+      return nil if value.nil?
+
+      BigDecimal(value)
+    rescue ArgumentError
+      BigDecimal('0.0')
+    end
+
+    # Converts a BigDecimal to a string representation.
+    #
+    # @param value [BigDecimal] The BigDecimal to normalize.
+    #
+    # @return [String] the string representation.
+    def normalize(value)
+      return nil if value.nil?
+
+      value.to_s
+    end
+  end
+end

data/lib/bronze/transforms/attributes/date_time_transform.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require 'bronze/transform'
+require 'bronze/transforms/attributes'
+
+module Bronze::Transforms::Attributes
+  # Transform class that normalizes a DateTime to a formatted string
+  # representation.
+  class DateTimeTransform < Bronze::Transform
+    # Format string for ISO 8601 date+time format. Equivalent to
+    # YYYY-MM-DDTHH:MM:SS+ZZZZ.
+    ISO_8601 = '%FT%T%z'
+
+    # @return [DateTimeTransform] a memoized instance of DateTimeTransform.
+    def self.instance
+      @instance ||= new
+    end
+
+    # @param format [String] The format string used to normalize and denormalize
+    #   date times. The default is ISO 8601 format.
+    def initialize(format = ISO_8601)
+      @format = format
+    end
+
+    # @return [String] the format string.
+    attr_reader :format
+
+    # Converts a formatted DateTime string to a Date instance.
+    #
+    # @param value [String] The normalized string.
+    #
+    # @return [DateTime] the parsed date+time.
+    def denormalize(value)
+      return value if value.is_a?(DateTime)
+
+      return nil if value.nil? || value.empty?
+
+      DateTime.strptime(value, read_format)
+    end
+
+    # Converts a DateTime to a formatted string.
+    #
+    # @param value [DateTime] The DateTime to format.
+    #
+    # @return [String] the formatted string.
+    def normalize(value)
+      return nil if value.nil?
+
+      value.strftime(format)
+    end
+
+    private
+
+    def read_format
+      @read_format ||= format.gsub('%-', '%')
+    end
+  end
+end