stannum 0.2.0 → 0.4.0

data/config/locales/en.rb

@@ -7,6 +7,7 @@
         absent: 'is nil or empty',
         anything: 'is a value',
         does_not_have_methods: 'does not respond to the methods',
+        does_not_match_format: 'does not match the expected format',
         has_methods: 'responds to the methods',
         hashes: {
           extra_keys: 'has extra keys',
@@ -15,10 +16,12 @@
           no_extra_keys: 'does not have extra keys'
         },
         invalid: 'is invalid',
+        is_a_uuid: 'is a valid UUID',
         is_boolean: 'is true or false',
         is_in_list: 'is in the list',
         is_in_union: 'matches one of the constraints',
         is_equal_to: 'is equal to',
+        is_not_a_uuid: 'is not a valid UUID',
         is_not_boolean: 'is not true or false',
         is_not_equal_to: 'is not equal to',
         is_not_in_list: 'is not in the list',
@@ -39,6 +42,7 @@
           end
         end,
         is_value: 'is the expected value',
+        matches_format: 'matches the expected format',
         parameters: {
           extra_arguments: 'has extra arguments',
           extra_keywords: 'has extra keywords',

data/lib/stannum/association.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'stannum'
+
+module Stannum
+  # Data object representing an association on an entity.
+  class Association # rubocop:disable Metrics/ClassLength
+    # Exception raised when calling an abstract method.
+    class AbstractAssociationError < StandardError; end
+
+    # Exception raised when referencing an invalid inverse association..
+    class InverseAssociationError < StandardError; end
+
+    # Builder class for defining association methods on an entity.
+    class Builder
+      # @param schema [Stannum::Schema] the associations schema on which to
+      #   define methods.
+      def initialize(schema)
+        @schema = schema
+      end
+
+      # @return [Stannum::Schema] the associations schema on which to define
+      #   methods.
+      attr_reader :schema
+
+      # Defines the reader and writer methods for the association.
+      #
+      # @param association [Stannum::Association]
+      def call(association)
+        define_reader(association)
+        define_writer(association)
+      end
+
+      private
+
+      def define_reader(association)
+        schema.define_method(association.reader_name) do
+          association.get_value(self)
+        end
+      end
+
+      def define_writer(association)
+        schema.define_method(association.writer_name) do |value|
+          association.clear_value(self)
+
+          association.set_value(self, value)
+        end
+      end
+    end
+
+    # @param name [String, Symbol] The name of the association. Converted to a
+    #   String.
+    # @param options [Hash, nil] Options for the association. Converted to a
+    #   Hash with Symbol keys. Defaults to an empty Hash.
+    # @param type [Class, Module, String] The type of the association. Can be a
+    #   Class, a Module, or the name of a class or module.
+    def initialize(name:, options:, type:)
+      validate_name(name)
+      validate_options(options)
+      validate_type(type)
+
+      @name    = name.to_s
+      @options = tools.hash_tools.convert_keys_to_symbols(options || {})
+
+      @type, @resolved_type = resolve_type(type)
+    end
+
+    # @return [String] the name of the association.
+    attr_reader :name
+
+    # @return [Hash] the association options.
+    attr_reader :options
+
+    # @return [String] the name of the association type Class or Module.
+    attr_reader :type
+
+    # @api private
+    #
+    # Adds the given value to the association for the entity.
+    #
+    # @param entity [Stannum::Entity] the entity to update.
+    # @param value [Object] the new value for the association.
+    # @param update_inverse [Boolean] if true, updates the inverse association
+    #   (if any). Defaults to false.
+    #
+    # @return [void]
+    def add_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
+      raise AbstractAssociationError,
+        "#{self.class} is an abstract class - use an association subclass"
+    end
+
+    # @api private
+    #
+    # Removes the value of the association for the entity.
+    #
+    # @param entity [Stannum::Entity] the entity to update.
+    #
+    # @return [void]
+    def clear_value(entity, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
+      raise AbstractAssociationError,
+        "#{self.class} is an abstract class - use an association subclass"
+    end
+
+    # @return [String, nil] the name of the original entity class.
+    def entity_class_name
+      @options[:entity_class_name]
+    end
+
+    # @return [true, false] true if the association has defines a foreign key;
+    #   otherwise false.
+    def foreign_key?
+      false
+    end
+
+    # @return [String?] the name of the foreign key, if any.
+    def foreign_key_name
+      nil
+    end
+
+    # @return [Class, Stannum::Constraint, nil] the type of the foreign key, if
+    #   any.
+    def foreign_key_type
+      nil
+    end
+
+    # @api private
+    #
+    # Retrieves the value of the association for the entity.
+    #
+    # @param entity [Stannum::Entity] the entity to update.
+    #
+    # @return [Object] the value of the association.
+    def get_value(entity) # rubocop:disable Lint/UnusedMethodArgument
+      raise AbstractAssociationError,
+        "#{self.class} is an abstract class - use an association subclass"
+    end
+
+    # @return [Boolean] true if the association has an inverse association;
+    #   otherwise false.
+    def inverse?
+      !!@options[:inverse]
+    end
+
+    # @return [String] the name of the inverse association, if any.
+    def inverse_name
+      @inverse_name ||= resolve_inverse_name
+    end
+
+    # @return [false] true if the association is a plural association;
+    #   otherwise false.
+    def many?
+      false
+    end
+
+    # @return [false] true if the association is a singular association;
+    #   otherwise false.
+    def one?
+      false
+    end
+
+    # @return [Symbol] the name of the reader method for the association.
+    def reader_name
+      @reader_name ||= name.intern
+    end
+
+    # @api private
+    #
+    # Removes the given value from the association for the entity.
+    #
+    # @param entity [Stannum::Entity] the entity to update.
+    # @param value [Stannum::Entity] the association value to remove.
+    # @param update_inverse [Boolean] if true, updates the inverse association
+    #   (if any). Defaults to false.
+    #
+    # @return [void]
+    def remove_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
+      raise AbstractAssociationError,
+        "#{self.class} is an abstract class - use an association subclass"
+    end
+
+    # @return [Stannum::Association] the inverse association, if any.
+    def resolved_inverse
+      return @resolved_inverse if @resolved_inverse
+
+      return unless inverse?
+
+      @resolved_inverse = resolved_type.associations[inverse_name]
+    rescue KeyError => exception
+      raise InverseAssociationError,
+        "unable to resolve inverse association #{exception.key.inspect}"
+    end
+
+    # @return [Module] the type of the association.
+    def resolved_type
+      return @resolved_type if @resolved_type
+
+      @resolved_type = Object.const_get(type)
+
+      unless @resolved_type.is_a?(Module)
+        raise NameError, "constant #{type} is not a Class or Module"
+      end
+
+      @resolved_type
+    end
+
+    # @api private
+    #
+    # Replaces the association for the entity with the given value.
+    #
+    # @param entity [Stannum::Entity] the entity to update.
+    # @param value [Object] the new value for the association.
+    # @param update_inverse [Boolean] if true, updates the inverse association
+    #   (if any). Defaults to false.
+    #
+    # @return [void]
+    def set_value(entity, value, update_inverse: true) # rubocop:disable Lint/UnusedMethodArgument
+      raise AbstractAssociationError,
+        "#{self.class} is an abstract class - use an association subclass"
+    end
+
+    # @return [Symbol] the name of the writer method for the association.
+    def writer_name
+      @writer_name ||= :"#{name}="
+    end
+
+    private
+
+    def plural_class_name
+      @plural_class_name ||= tools.string_tools.pluralize(singular_class_name)
+    end
+
+    def resolve_inverse_name # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return unless inverse?
+
+      return options[:inverse_name].to_s if options[:inverse_name]
+
+      if resolved_type.associations.key?(singular_class_name)
+        return singular_class_name
+      end
+
+      if resolved_type.associations.key?(plural_class_name)
+        return plural_class_name
+      end
+
+      raise InverseAssociationError,
+        'unable to resolve inverse association ' \
+        "#{singular_class_name.inspect} or #{plural_class_name.inspect}"
+    end
+
+    def resolve_type(type)
+      return [type, nil] if type.is_a?(String)
+
+      [type.to_s, type]
+    end
+
+    def singular_class_name
+      @singular_class_name ||=
+        entity_class_name
+        .split('::')
+        .last
+        .then { |str| tools.string_tools.underscore(str) }
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_name(name)
+      tools.assertions.validate_name(name, as: 'name')
+    end
+
+    def validate_options(options)
+      return if options.nil? || options.is_a?(Hash)
+
+      raise ArgumentError, 'options must be a Hash or nil'
+    end
+
+    def validate_type(type)
+      raise ArgumentError, "type can't be blank" if type.nil?
+
+      return if type.is_a?(Module)
+
+      if type.is_a?(String)
+        return unless type.empty?
+
+        raise ArgumentError, "type can't be blank"
+      end
+
+      raise ArgumentError,
+        'type must be a Class, a Module, or the name of a class or module'
+    end
+  end
+end

data/lib/stannum/associations/many.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'stannum/associations'
+
+module Stannum::Associations
+  # Data object representing a plural association.
+  class Many < Stannum::Association
+    # Wrapper object for an entity's plural association.
+    class Proxy
+      include Enumerable
+      extend  Forwardable
+
+      # @param association [Stannum::Associations::Many] the association being
+      #   wrapped.
+      # @param entity [Stannum::Entity] the entity instance whose association is
+      #   being wrapped.
+      def initialize(association:, entity:)
+        @association = association
+        @entity      = entity
+      end
+
+      # @!method [](index)
+      #   Retrieves the value of the association at the specified index.
+      #
+      #   @param index [Integer] the index of the value to retrieve.
+      #
+      #   @return [Stannum::Entity] the association value at the index.
+      def_delegator :data, :[]
+
+      # @!method each(&block)
+      #   @overload each
+      #     @return [Enumerator] an enumerator over each item in the entity's
+      #       association data.
+      #
+      #   @overload each(&block)
+      #     @yield Yields each item in the entity's association data.
+      #     @yieldparam item [Stannum::Entity] the associated entity.
+      def_delegator :data, :each
+
+      # @!method empty?
+      #   @return [true, false] true if the association has no items; otherwise
+      #     false.
+      def_delegator :data, :empty?
+
+      # @!method size
+      #   @return [Integer] the number of items in the association.
+      def_delegator :data, :size
+      alias size count
+
+      # @param other [Object] the object to compare.
+      #
+      # @return [true, false] true if the object has matching data; otherwise
+      #   false.
+      def ==(other)
+        return false if other.nil?
+
+        return false unless other.respond_to?(:to_a)
+
+        to_a == other.to_a
+      end
+
+      # Appends the entity to the association.
+      #
+      # If the entity is already in the association data, this method does
+      # nothing.
+      #
+      # @param value [Stannum::Entity] the entity to add.
+      #
+      # @return [self] the association proxy.
+      def add(value)
+        unless value.is_a?(association.resolved_type)
+          message =
+            'invalid association item - must be an instance of ' \
+            "#{association.resolved_type.name}"
+
+          raise ArgumentError, message
+        end
+
+        association.add_value(entity, value)
+
+        self
+      end
+      alias << add
+      alias push add
+
+      # @return [String] a human-readable string representation of the object.
+      def inspect
+        "#{super[...55]} data=[#{each.map(&:inspect).join(', ')}]>"
+      end
+
+      # Removes the entity from the association.
+      #
+      # If the entity is not in the association data, this method does nothing.
+      #
+      # @param value [Stannum::Entity] the entity to remove.
+      #
+      # @return [self] the association proxy.
+      def remove(value)
+        unless value.is_a?(association.resolved_type)
+          message =
+            'invalid association item - must be an instance of ' \
+            "#{association.resolved_type.name}"
+
+          raise ArgumentError, message
+        end
+
+        association.remove_value(entity, value)
+
+        self
+      end
+      alias delete remove
+
+      private
+
+      attr_reader :association
+
+      attr_reader :entity
+
+      def data
+        entity.read_association(association.name, safe: false) || []
+      end
+    end
+
+    # (see Stannum::Association#add_value)
+    def add_value(entity, value, update_inverse: true)
+      return unless value
+
+      data = entity.read_association(name, safe: false) || []
+
+      data, changed = add_item(data:, value:)
+
+      entity.write_association(name, data, safe: false) if changed
+
+      update_item_inverse(entity:, value:) if inverse? && update_inverse
+
+      nil
+    end
+
+    # (see Stannum::Association#clear_value)
+    def clear_value(entity, update_inverse: true)
+      data = entity.read_association(name, safe: false) || []
+
+      entity.write_association(name, [], safe: false)
+
+      if inverse? && update_inverse
+        data.each { |item| remove_item_inverse(value: item) }
+      end
+
+      nil
+    end
+
+    # (see Stannum::Association#get_value)
+    def get_value(entity)
+      entity.association_proxy_for(self)
+    end
+
+    # @return [true] true if the association is a plural association; otherwise
+    #   false.
+    def many?
+      true
+    end
+
+    # (see Stannum::Association#remove_value)
+    def remove_value(entity, value, update_inverse: true)
+      return unless value
+
+      data = entity.read_association(name, safe: false) || []
+
+      data, changed = remove_item(data:, value:)
+
+      return unless changed
+
+      entity.write_association(name, data, safe: false)
+
+      remove_item_inverse(value:) if inverse? && update_inverse
+
+      nil
+    end
+
+    # (see Stannum::Association#resolved_inverse)
+    def resolved_inverse
+      return @resolved_inverse if @resolved_inverse
+
+      inverse = super
+
+      return inverse unless inverse&.many?
+
+      raise InverseAssociationError,
+        "invalid inverse association #{inverse_name.inspect} - :many to " \
+        ':many associations are not currently supported'
+    end
+
+    # (see Stannum::Association#set_value)
+    def set_value(entity, value, update_inverse: true)
+      data = entity.read_association(name, safe: false) || []
+
+      value&.each do |item|
+        next unless item
+
+        data, _ = add_item(data:, value: item)
+
+        update_item_inverse(entity:, value: item) if inverse? && update_inverse
+      end
+
+      entity.write_association(name, data, safe: false)
+
+      nil
+    end
+
+    private
+
+    def add_item(data:, value:)
+      return data, false if data.include?(value)
+
+      data = [*data, value]
+
+      [data, true]
+    end
+
+    def remove_item(data:, value:)
+      return data, false unless data.include?(value)
+
+      data = data.reject { |item| item == value }
+
+      [data, true]
+    end
+
+    def remove_item_inverse(value:, inverse_value: nil, update_inverse: false)
+      inverse_value ||= resolved_inverse.get_value(value)
+
+      return unless inverse_value
+
+      resolved_inverse.remove_value(value, inverse_value, update_inverse:)
+    end
+
+    def update_item_inverse(entity:, value:)
+      inverse_value = resolved_inverse.get_value(value)
+
+      return if entity == inverse_value
+
+      if inverse_value
+        remove_item_inverse(inverse_value:, value:, update_inverse: true)
+      end
+
+      resolved_inverse.add_value(value, entity, update_inverse: false)
+    end
+  end
+end

data/lib/stannum/associations/one.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'stannum/associations'
+
+module Stannum::Associations
+  # Data object representing a singular association.
+  class One < Stannum::Association
+    # (see Stannum::Association#add_value)
+    def add_value(entity, value, update_inverse: true)
+      set_value(entity, value, update_inverse:)
+    end
+
+    # (see Stannum::Association#clear_value)
+    def clear_value(entity, update_inverse: true)
+      previous_value = entity.read_association(name, safe: false)
+
+      if update_inverse && previous_value && inverse?
+        resolved_inverse.remove_value(
+          previous_value,
+          entity,
+          update_inverse: false
+        )
+      end
+
+      entity.write_attribute(foreign_key_name, nil, safe: false) if foreign_key?
+
+      entity.write_association(name, nil, safe: false)
+    end
+
+    # @return [Boolean] true if the association has a foreign key; otherwise
+    #   false.
+    def foreign_key?
+      return @has_foreign_key unless @has_foreign_key.nil?
+
+      value = options[:foreign_key_name]
+
+      return @has_foreign_key = false if value.nil? || value == false
+
+      @has_foreign_key = true
+    end
+
+    # @return [String?] the name of the foreign key, if any.
+    def foreign_key_name
+      return nil unless foreign_key?
+
+      @foreign_key_name ||= options[:foreign_key_name].to_s
+    end
+
+    # @return [Class, Stannum::Constraint, nil] the type of the foreign key, if
+    #   any.
+    def foreign_key_type
+      return nil unless foreign_key?
+
+      @foreign_key_type ||= options[:foreign_key_type]
+    end
+
+    # (see Stannum::Association#get_value)
+    def get_value(entity)
+      entity.read_association(name, safe: false)
+    end
+
+    # @return [true] true if the association is a singular association;
+    #   otherwise false.
+    def one?
+      true
+    end
+
+    # (see Stannum::Association#remove_value)
+    def remove_value(entity, value, update_inverse: true)
+      previous_value = entity.read_association(name, safe: false)
+
+      return unless matching_value?(value, previous_value)
+
+      clear_value(entity, update_inverse:)
+    end
+
+    # (see Stannum::Association#set_value)
+    def set_value(entity, value, update_inverse: true) # rubocop:disable Metrics/MethodLength
+      if foreign_key?
+        entity.write_attribute(
+          foreign_key_name,
+          value&.primary_key,
+          safe: false
+        )
+      end
+
+      entity.write_association(name, value, safe: false)
+
+      return unless update_inverse && value && inverse?
+
+      previous_inverse = resolved_inverse.get_value(value)
+
+      resolved_inverse.remove_value(value, previous_inverse) if previous_inverse
+
+      resolved_inverse.add_value(value, entity, update_inverse: false)
+    end
+
+    private
+
+    def matching_value?(value, previous_value)
+      return true if value == previous_value
+
+      foreign_key? && (value == previous_value&.primary_key)
+    end
+  end
+end

data/lib/stannum/associations.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'stannum'
+
+module Stannum
+  # Namespace for modules implementing Association functionality.
+  module Associations
+    autoload :Many, 'stannum/associations/many'
+    autoload :One,  'stannum/associations/one'
+  end
+end