upgrow 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ade9c609af4d3b6a3dbcf14e3391c279b0043ca68a7b3abca290c0558d31d7d5
-  data.tar.gz: d7f3ad187cc54e12c7000bbb1bc6e489f160b0d24c9e815c4d338c0654ff2980
+  metadata.gz: 3238cf0308b8e81b0349792dc104880479702dc5c802a8985d2f37461fb1029f
+  data.tar.gz: 3c06e81104d588ae28d500d4db9946e16afeee449eb7b58a70700a8e3f6b7bb1
 SHA512:
-  metadata.gz: a94d9ab2c7d815c912670e58e234f7052c6c062c54cb2ab6c65a729280db7fb1867ee5314aa6599893a6aabbbebdb8763b2cddf9e5e01056e8a532fa7eef7f7b
-  data.tar.gz: 9ad9d668636f257c12c1a9dec5bd6cfcc4c209feb2f18adaf63717d8c0725535b347025305a391ace8d67e6fffef87827015d93784887cf79ea8e7b37aa70915
+  metadata.gz: b7f23d2e55b0b06d99c168353c99e1b13e3ee4c0d9a12371e5f6771c7bc9dfae347512c583d716188454b634d54d57149e24b98cf203738d5aee718148405f29
+  data.tar.gz: 646705859b0fb813b215081f1f52058b2b36b2e15b2a0b81cdeb0dfd537ebe30e84c2846a5b37e99d9646e9706015ded057f365100798bdec360918c8936ae5a

data/Rakefile

@@ -18,4 +18,4 @@ end
 
 RuboCop::RakeTask.new
 
-task default: ['rubocop', 'test', 'db:setup', 'test:system']
+task default: ['rubocop', 'test', 'test:system']

data/lib/upgrow.rb

@@ -1,16 +1,10 @@
 # frozen_string_literal: true
 
-require 'active_model'
-
 require_relative 'upgrow/action'
-require_relative 'upgrow/active_record_adapter'
-require_relative 'upgrow/immutable_object'
-require_relative 'upgrow/basic_repository'
-require_relative 'upgrow/immutable_struct'
-require_relative 'upgrow/repository'
+require_relative 'upgrow/actions'
 require_relative 'upgrow/input'
 require_relative 'upgrow/model'
-require_relative 'upgrow/result'
+require_relative 'upgrow/repository'
 
 # The gem's main namespace.
 module Upgrow

data/lib/upgrow/action.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'result'
+
 module Upgrow
   # Actions represent the entry points to the app’s core logic. These objects
   # coordinate workflows in order to get operations and activities done.
@@ -23,32 +25,80 @@ module Upgrow
   # own set of required arguments for perform, as well what can be expected as
   # the result of that method.
   class Action
+    # Module to be prepended to subclasses of Action. This allows Action to
+    # decorate methods implemented by subclasses so they can have additional
+    # behaviour.
+    module Decorator
+      def perform(...)
+        catch(:failure) do
+          super
+          result
+        end
+      end
+    end
+
     class << self
-      attr_writer :result_class
+      attr_writer :exposures
 
-      # Each Action class has its own Result class with the expected members to
-      # be returned when the Action is called successfully.
+      # Each Action class has its own list of exposed instance variables to be
+      # included in the returned Result when the Action is called.
       #
-      # @return [Result] the Result class for this Action, as previously
-      #   defined, or a Result class with no members by default.
-      def result_class
-        @result_class ||= Result.new
+      # @return [Array] the list of exposed instance variables.
+      def exposures
+        @exposures ||= []
       end
 
-      # Sets the Action Result class with the given members.
+      # Sets the given instance variable names as exposed in the Result.
       #
-      # @param args [Array<Symbol>] the list of members for the Result class.
-      def result(*args)
-        @result_class = Result.new(*args)
+      # @param names [Array<Symbol>] the list of instance variable names to be
+      #   exposed as part of the Result.
+      def expose(*names)
+        @exposures += names
+      end
+
+      private
+
+      def inherited(subclass)
+        super
+        subclass.exposures = exposures.dup
+        subclass.prepend(Decorator)
       end
     end
 
-    # Instance method to return the Action's Result class. This method delegates
-    # to the Action class's method (see #result_class).
+    # Throws a Result populated with the given errors.
     #
-    # @return [Result] the Result class for this Action.
-    def result
-      self.class.result_class
+    # @param errors [Array<Error>, ActiveModel::Errors] the errors object to
+    #   be set as the Result errors. If an ActiveModel::Errors object is
+    #   provided, it will be converted to an Array of Errors.
+    #
+    # @return [:failure, Result] the Result instance populated with the given
+    #   errors.
+    def failure(*errors)
+      errors = errors.first if errors.first.respond_to?(:each)
+
+      if errors.respond_to?(:full_message)
+        errors = errors.map do |error|
+          Error.new(
+            attribute: error.attribute,
+            code: error.type,
+            message: error.full_message
+          )
+        end
+      end
+
+      throw(:failure, result(errors: errors))
+    end
+
+    private
+
+    def result(members = {})
+      result_class = Result.new(*self.class.exposures)
+
+      values = self.class.exposures.to_h do |name|
+        [name, instance_variable_get("@#{name}")]
+      end
+
+      result_class.new(**values.merge(members))
     end
   end
 end

data/lib/upgrow/actions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # This module offers helpers to work with the collection of Actions loaded in
+  # the application.
+  #
+  # Actions are created with a concrete, predefined interface. This allows them
+  # to be uniformly instantiated in the context of an application, which is
+  # helpful to prevent duplications.
+  module Actions
+    extend self
+
+    # Convenience method to retrieve an Action based on a key name optionally
+    # namespaced.
+    #
+    # @example Retrieve Action based on a global key name
+    #   Actions['show'] #=> ShowAction
+    #
+    # @example Retrieve a namespaced Action
+    #   Actions['articles', 'show'] #=> Articles::ShowAction
+    #
+    # @param names [Array<String>] one or more names, the last one being the
+    #   name of the Action without the "Action" suffix, optionally lowercased.
+    #
+    # @return [Action] the Action specified by the names.
+    def [](*names)
+      action_class_name = names.map(&:capitalize).join('::') + 'Action'
+      Object.const_get(action_class_name)
+    end
+  end
+end

data/lib/upgrow/active_record_adapter.rb

@@ -5,6 +5,30 @@ module Upgrow
   # included in a Repository class, it sets the default base to be a class
   # ending with `Record`.
   module ActiveRecordAdapter
+    # Class methods for classes that include this module.
+    module ClassMethods
+      # Callback method used by Basic Repository to set a default Repository
+      # base when one is not explicitly provided at the Repository
+      # initialization.
+      #
+      # It attempts to find a constant based on the Repository name, with the
+      # `Record` suffix as a convention. For example, a `UserRepository` would
+      # have the `UserRecord` as its base. That is the naming convention for
+      # Active Record classes under this architecture.
+      #
+      # @return [Class] the Active Record Base class to be used as the
+      #   Repository base according to the architecture's naming convention.
+      def default_base
+        base_name = name[/\A(.+)Repository\z/, 1] + 'Record'
+        Object.const_get(base_name)
+      end
+    end
+
+    # @private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
     # Fetches all Records and returns them as an Array of Models.
     #
     # @return [Array<Model>] a collection of Models representing all persisted
@@ -54,20 +78,5 @@ module Upgrow
     def delete(id)
       base.destroy(id)
     end
-
-    # Callback method used by Basic Repository to set a default Repository base
-    # when one is not explicitly provided at the Repository initialization.
-    #
-    # It attempts to find a constant based on the Repository name, with the
-    # `Record` suffix as a convention. For example, a `UserRepository` would
-    # have the `UserRecord` as its base. That is the naming convention for
-    # Active Record classes under this architecture.
-    #
-    # @return [Class] the Active Record Base class to be used as the Repository
-    #   base according to the architecture's naming convention.
-    def default_base
-      base_name = self.class.name[/\A(.+)Repository\z/, 1] + 'Record'
-      Object.const_get(base_name)
-    end
   end
 end

data/lib/upgrow/active_record_schema.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # A Schema that dynamically infers attribute names from an Active Record Base,
+  # plus the attributes from an original Schema.
+  #
+  # This object is used to power Models so they can include Active Record
+  # attributes from a matching class based on the Model's name.
+  class ActiveRecordSchema
+    # Set the Schema's initial state.
+    #
+    # @param base_name [String] the name of the Active Record Base class that
+    #   should be used to fetch attribute names.
+    # @param default_schema [ModelSchema] the original Model Schema to be used
+    #   to fetch and define custom attributes.
+    def initialize(base_name, default_schema)
+      @base_name = base_name
+      @default_schema = default_schema
+    end
+
+    # Define a custom attribute in the default Schema.
+    #
+    # @param name [Symbol] the name of the new attribute.
+    def attribute(name)
+      @default_schema.attribute(name)
+    end
+
+    # Define a custom association in the default Schema.
+    #
+    # @param name [Symbol] the name of the association.
+    def association(name)
+      @default_schema.association(name)
+    end
+
+    # The list of attribute names. This is an aggregate of both the attributes
+    # from the Active Record Base as well as any custom attributes from the
+    # default Schema.
+    #
+    # @return [Array<Symbol>] the list of attribute names.
+    def attribute_names
+      base.attribute_names.map(&:to_sym) | @default_schema.attribute_names
+    end
+
+    # The list of association names. This is an aggregate of both the
+    # associations from the Active Record Base as well as any custom
+    # associations from the default Schema.
+    #
+    # @return [Array<Symbol>] the list of attribute names.
+    def association_names
+      association_names = base.reflections.keys.map do |key|
+        key.sub('_record', '').to_sym
+      end
+
+      association_names | @default_schema.association_names
+    end
+
+    private
+
+    def base
+      Object.const_get(@base_name)
+    end
+  end
+end

data/lib/upgrow/basic_model.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'immutable_object'
+require_relative 'model_schema'
+
+module Upgrow
+  # Base class for Models. As an Immutable Object, it sets a default schema with
+  # the minimal attribute ID, as well as requires all attributes to be set upon
+  # initialization.
+  class BasicModel < ImmutableObject
+    class AssociationNotLoadedError < StandardError; end
+
+    class << self
+      # Defines an association in the Model Schema.
+      #
+      # @param name [Symbol] the name of the association.
+      def belongs_to(name)
+        schema.association(name)
+      end
+
+      # Defines an association in the Model Schema.
+      #
+      # @param name [Symbol] the name of the association.
+      def has_many(name)
+        schema.association(name)
+      end
+    end
+
+    self.schema = ModelSchema.new
+
+    attribute :id
+
+    attr_reader :associations
+
+    # Initializes a new Model with the given member values.
+    #
+    # @param args [Hash<Symbol, Object>] the list of values for each attribute
+    #   and association.
+    #
+    # @raise [KeyError] if an attribute is missing in the list of arguments.
+    def initialize(**args)
+      @associations = self.class.schema.association_names.to_h do |name|
+        [name, args[name]]
+      end.freeze
+
+      attributes = self.class.schema.attribute_names.to_h do |name|
+        [name, args.fetch(name)]
+      end
+
+      super(**attributes)
+    end
+
+    private
+
+    def method_missing(name, *args, &block)
+      return super unless associations.include?(name)
+      associations[name] || raise(AssociationNotLoadedError)
+    end
+
+    def respond_to_missing?(name, _include_private = false)
+      associations.include?(name) || super
+    end
+  end
+end

data/lib/upgrow/basic_repository.rb

@@ -5,41 +5,68 @@ module Upgrow
   # Repositories should have, as well as the logic on how to materialize data
   # into Models.
   class BasicRepository
+    class << self
+      attr_writer :base
+      attr_writer :model_class
+
+      # model_class [Class] the Model class to be used to map and return the
+      # materialized data as instances of the domain. Defaults to a constant
+      # derived from the Repository class' name. For example, a `UserRepository`
+      # will have its default Model class set to `User`.
+      #
+      # @return [Class] the Repository Model class.
+      def model_class
+        @model_class || default_model_class
+      end
+
+      # the base object to be used internally to retrieve the persisted data.
+      # For example, a base class in which queries can be performed for a
+      # relational database adapter. Defaults to `nil`.
+      #
+      # @return [Object] the Repository base.
+      def base
+        @base || default_base
+      end
+
+      private
+
+      def default_base; end
+
+      def default_model_class
+        model_class_name = name.delete_suffix('Repository')
+        Object.const_get(model_class_name)
+      end
+    end
+
     attr_reader :base, :model_class
 
     # Sets the Basic Repositorie's state.
-    #
-    # @param base [Object] the base object to be used internally to retrieve the
-    #   persisted data. For example, a base class in which queries can be
-    #   performed for a relational database adapter. Defaults to `nil`.
-    #
-    # @param model_class [Class] the Model class to be used to map and return
-    #   the materialized data as instances of the domain. Defaults to a constant
-    #   derived from the Repository class' name. For example, a `UserRepository`
-    #   will have its default Model class set to `User`.
-    def initialize(base: default_base, model_class: default_model_class)
-      @base = base
-      @model_class = model_class
+    def initialize
+      @base = self.class.base
+      @model_class = self.class.model_class
     end
 
     # Represents the raw Hash of data attributes as a Model instance from the
     # Repositorie's Model class.
     #
+    # @param model_class_or_attributes [Class, Hash<Symbol, Object>] the Model
+    #   class to be instantiated, in case it is a different class than the
+    #   Repositorie's Model class, or the list of attributes the model will
+    #   have, in case the Model class is the Repositorie's Model class.
     # @param attributes [Hash<Symbol, Object>] the list of attributes the Model
-    #   will have.
+    #   will have, in case the Model to be instantiated is passed as the first
+    #   argument.
     #
     # @return [Model] the Model instance populated with the given attributes.
-    def to_model(attributes = {})
-      model_class.new(**attributes.transform_keys(&:to_sym))
-    end
-
-    private
+    def to_model(model_class_or_attributes, attributes = {})
+      model_class = model_class_or_attributes
 
-    def default_base; end
+      if model_class_or_attributes.respond_to?(:transform_keys)
+        model_class = self.model_class
+        attributes = model_class_or_attributes
+      end
 
-    def default_model_class
-      model_class_name = self.class.name[/\A(.+)Repository\z/, 1]
-      Object.const_get(model_class_name)
+      model_class.new(**attributes.transform_keys(&:to_sym))
     end
   end
 end