stannum 0.2.0 → 0.4.0

data/lib/stannum/entities/attributes.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Methods for defining and accessing entity attributes.
+  module Attributes # rubocop:disable Metrics/ModuleLength
+    # Class methods to extend the class when including Attributes.
+    module ClassMethods
+      # Defines an attribute on the entity.
+      #
+      # When an attribute is defined, each of the following steps is executed:
+      #
+      # - Adds the attribute to ::Attributes and the .attributes class method.
+      # - Adds the attribute to #attributes and the associated methods, such as
+      #   #assign_attributes, #[] and #[]=.
+      # - Defines reader and writer methods.
+      #
+      # @param attr_name [String, Symbol] The name of the attribute. Must be a
+      #   non-empty String or Symbol.
+      # @param attr_type [Class, String] The type of the attribute. Must be a
+      #   Class or Module, or the name of a class or module.
+      # @param options [Hash] Additional options for the attribute.
+      #
+      # @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.
+      def attribute(attr_name, attr_type, **options)
+        attributes.define(
+          name:    attr_name,
+          type:    attr_type,
+          options:
+        )
+
+        attr_name.intern
+      end
+      alias define_attribute attribute
+
+      # @return [Stannum::Schema] The attributes Schema object for the Entity.
+      def attributes
+        self::Attributes
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::Attributes)
+
+        Stannum::Entities::Attributes.apply(other) if other.is_a?(Class)
+      end
+
+      def inherited(other)
+        super
+
+        Stannum::Entities::Attributes.apply(other)
+      end
+    end
+
+    class << self
+      # Generates Attributes schema for the class.
+      #
+      # Creates a new Stannum::Schema and sets it as the class's :Attributes
+      # constant. If the superclass is an entity class (and already defines its
+      # own Attributes, includes the superclass Attributes in the class
+      # Attributes). Finally, includes the class Attributes 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(:Attributes, build_schema)
+
+        if entity_class?(other.superclass)
+          other::Attributes.include(other.superclass::Attributes)
+        end
+
+        other.include(other::Attributes)
+      end
+
+      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
+
+      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)
+      @attributes = {}
+
+      self.class.attributes.each_key { |key| @attributes[key] = nil }
+
+      super
+    end
+
+    # Updates the struct's attributes with the given values.
+    #
+    # This method is used to update some (but not all) of the attributes of the
+    # struct. For each key in the hash, it calls the corresponding writer method
+    # with the value for that attribute. If the value is nil, this will set the
+    # attribute value to the default for that attribute.
+    #
+    # Any attributes that are not in the given hash are unchanged, as are any
+    # properties that are not attributes.
+    #
+    # If the attributes hash includes any keys that do not correspond to an
+    # attribute, the struct will raise an error.
+    #
+    # @param attributes [Hash] The attributes for the struct.
+    #
+    # @raise ArgumentError if any key is not a valid attribute.
+    #
+    # @see #attributes=
+    def assign_attributes(attributes)
+      unless attributes.is_a?(Hash)
+        raise ArgumentError, 'attributes must be a Hash'
+      end
+
+      set_attributes(attributes, force: false)
+    end
+
+    # Collects the entity attributes.
+    #
+    # @return [Hash<String, Object>] the entity attributes.
+    def attributes
+      @attributes.dup
+    end
+
+    # Replaces the entity's attributes with the given values.
+    #
+    # This method is used to update all of the attributes of the entity. For
+    # each attribute, the writer method is called with the value from the hash,
+    # or nil if the corresponding key is not present in the hash. Any nil or
+    # missing values set the attribute value to that attribute's default value,
+    # if any. Non-attribute properties are unchanged.
+    #
+    # If the attributes hash includes any keys that do not correspond to a valid
+    # attribute, the entity will raise an error.
+    #
+    # @param attributes [Hash] the attributes to assign to the entity.
+    #
+    # @raise ArgumentError if any key is not a valid attribute.
+    #
+    # @see #assign_attributes
+    def attributes=(attributes)
+      unless attributes.is_a?(Hash)
+        raise ArgumentError, 'attributes must be a Hash'
+      end
+
+      set_attributes(attributes, force: true)
+    end
+
+    # (see Stannum::Entities::Properties#properties)
+    def properties
+      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 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:)
+      attributes, non_matching =
+        bisect_properties(attributes, self.class.attributes)
+
+      unless non_matching.empty?
+        handle_invalid_properties(non_matching, as: 'attribute')
+      end
+
+      write_attributes(attributes, force:)
+    end
+
+    def set_properties(properties, force:)
+      attributes, non_matching =
+        bisect_properties(properties, self.class.attributes)
+
+      super(non_matching, force:)
+
+      write_attributes(attributes, force:)
+    end
+
+    def set_property(key, value)
+      return super unless attributes.key?(key.to_s)
+
+      send(self.class.attributes[key.to_s].writer_name, value)
+    end
+
+    def write_attributes(attributes, force:)
+      self.class.attributes.each do |attr_name, attribute|
+        next unless attributes.key?(attr_name) || force
+
+        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

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Methods for defining and accessing entity constraints.
+  module Constraints
+    # Class methods to extend the class when including Attributes.
+    module AttributesMethods
+      # Defines an attribute on the entity.
+      #
+      # Delegates to the superclass method, and then adds a type constraint to
+      # ::Contract.
+      #
+      # @see Stannum::Entities::Attributes::ClassMethods#attribute.
+      def attribute(attr_name, attr_type, **options) # rubocop:disable Metrics/MethodLength
+        returned = super
+
+        attribute  = attributes[attr_name.to_s]
+        constraint = Stannum::Constraints::Type.new(
+          attribute.type,
+          required: attribute.required?
+        )
+
+        self::Contract.add_constraint(
+          constraint,
+          property: attribute.reader_name
+        )
+
+        returned
+      end
+      alias define_attribute attribute
+    end
+
+    # Class methods to extend the class when including Constraints.
+    module ClassMethods
+      # Defines a constraint on the entity or one of its properties.
+      #
+      # @overload constraint()
+      #   Defines a constraint on the entity.
+      #
+      #   A new Stannum::Constraint instance will be generated, passing the
+      #   block from .constraint to the new constraint. This constraint will be
+      #   added to the contract.
+      #
+      #   @yieldparam entity [Stannum::Entities::Constraints] The entity at the
+      #     time the constraint is evaluated.
+      #
+      # @overload constraint(constraint)
+      #   Defines a constraint on the entity.
+      #
+      #   The given constraint is added to the contract. When the contract is
+      #   evaluated, this constraint will be matched against the entity.
+      #
+      #   @param constraint [Stannum::Constraints::Base] The constraint to add.
+      #
+      # @overload constraint(attr_name)
+      #   Defines a constraint on the given attribute or property.
+      #
+      #   A new Stannum::Constraint instance will be generated, passing the
+      #   block from .constraint to the new constraint. This constraint will be
+      #   added to the contract.
+      #
+      #   @param attr_name [String, Symbol] The name of the attribute or
+      #     property to constrain.
+      #
+      #   @yieldparam value [Object] The value of the attribute or property of
+      #     the entity at the time the constraint is evaluated.
+      #
+      # @overload constraint(attr_name, constraint)
+      #   Defines a constraint on the given attribute or property.
+      #
+      #   The given constraint is added to the contract. When the contract is
+      #   evaluated, this constraint will be matched against the value of the
+      #   attribute or property.
+      #
+      #   @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, &)
+        attr_name, constraint = resolve_constraint(attr_name, constraint)
+
+        if block_given?
+          constraint = Stannum::Constraint.new(&)
+        else
+          validate_constraint(constraint)
+        end
+
+        contract.add_constraint(constraint, property: attr_name)
+      end
+
+      # @return [Stannum::Contract] The Contract object for the entity.
+      def contract
+        self::Contract
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::Constraints)
+
+        Stannum::Entities::Constraints.apply(other) if other.is_a?(Class)
+      end
+
+      def inherited(other)
+        super
+
+        Stannum::Entities::Constraints.apply(other)
+      end
+
+      def resolve_constraint(attr_name, constraint)
+        return [nil, attr_name] if attr_name.is_a?(Stannum::Constraints::Base)
+
+        unless attr_name.nil?
+          tools.assertions.validate_name(attr_name, as: 'attribute')
+        end
+
+        [attr_name.nil? ? attr_name : attr_name.intern, constraint]
+      end
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+
+      def validate_constraint(constraint)
+        raise ArgumentError, "constraint can't be blank" if constraint.nil?
+
+        return if constraint.is_a?(Stannum::Constraints::Base)
+
+        raise ArgumentError, 'constraint must be a Stannum::Constraints::Base'
+      end
+    end
+
+    class << self
+      # Generates a Contract for the class.
+      #
+      # Creates a new Stannum::Contract and sets it as the class's :Contract
+      # constant. If the superclass is an entity class (and already defines its
+      # own Contract, concatenates the superclass Contract into the class
+      # Contract).
+      #
+      # @param other [Class] the class to which attributes are added.
+      def apply(other)
+        return unless other.is_a?(Class)
+
+        return if entity_class?(other)
+
+        contract = Stannum::Contract.new
+
+        other.const_set(:Contract, contract)
+
+        return unless entity_class?(other.superclass)
+
+        contract.concat(other.superclass::Contract)
+      end
+
+      private
+
+      def entity_class?(other)
+        other.const_defined?(:Contract, false)
+      end
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+
+        if other < Stannum::Entities::Attributes
+          other.extend(self::AttributesMethods)
+        end
+
+        apply(other) if other.is_a?(Class)
+      end
+    end
+  end
+end

data/lib/stannum/entities/primary_key.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Methods for defining and accessing an entity's primary key attribute.
+  module PrimaryKey
+    # Raised when adding a primary key to an entity that already has one.
+    class PrimaryKeyAlreadyExists < StandardError; end
+
+    # Raised when accessing a primary key for an entity that does not have one.
+    class PrimaryKeyMissing < StandardError; end
+
+    # Class methods to extend the class when including PrimaryKey.
+    module ClassMethods
+      # Defines a primary key attribute on the entity.
+      #
+      # @param attr_name [String, Symbol] The name of the attribute. Must be a
+      #   non-empty String or Symbol.
+      # @param attr_type [Class, String] The type of the attribute. Must be a
+      #   Class or Module, or the name of a class or module.
+      # @param options [Hash] Additional options for the attribute.
+      #
+      # @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.
+      #
+      # @see Stannum::Entities::Attributes::ClassMethods#define_attribute.
+      def define_primary_key(attr_name, attr_type, **options)
+        if primary_key?
+          raise PrimaryKeyAlreadyExists,
+            "#{name} already defines primary key #{primary_key_name.inspect}"
+        end
+
+        attribute(attr_name, attr_type, **options, primary_key: true)
+      end
+
+      # @return [Stannum::Attribute] the primary key attribute.
+      #
+      # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+      #   does not define a primary key.
+      def primary_key
+        primary_key =
+          attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+
+        return primary_key if primary_key
+
+        raise PrimaryKeyMissing, "#{name} does not define a primary key"
+      end
+
+      # @return [Boolean] true if the entity class defines a primary key;
+      #   otherwise false.
+      def primary_key?
+        attributes.any? { |_, attribute| attribute.primary_key? }
+      end
+
+      # @return [String, nil] the name of the primary key attribute, or nil if
+      #   the entity does not define a primary key.
+      def primary_key_name
+        attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+          &.name
+      end
+
+      # @return [Class, nil] the type of the primary key attribute, or nil if
+      #   the entity does not define a primary key.
+      def primary_key_type
+        attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+          &.resolved_type
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::PrimaryKey)
+      end
+    end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+      end
+    end
+
+    # @return [Boolean] true if the entity class defines a primary key and if
+    #   the entity has a non-empty value for that attribute; otherwise false.
+    def primary_key?
+      return false unless self.class.primary_key?
+
+      value = attributes[self.class.primary_key_name]
+
+      return false if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      true
+    end
+
+    # @return [String] the name of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_name
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      self.class.primary_key_name
+    end
+
+    # @return [Class] the type of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_type
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      self.class.primary_key_type
+    end
+
+    # @return [Object] the current value of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_value
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      attributes[self.class.primary_key_name]
+    end
+    alias primary_key primary_key_value
+  end
+end