upgrow 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b332e16457e8d2d1e8d1392f217f9f8755b998cd5888dedba58a7ebce9f213b
-  data.tar.gz: fb61e9ee12281e326a9468847a9b3eb6753c5df7e39acf8978d00f4a783f6838
+  metadata.gz: ade9c609af4d3b6a3dbcf14e3391c279b0043ca68a7b3abca290c0558d31d7d5
+  data.tar.gz: d7f3ad187cc54e12c7000bbb1bc6e489f160b0d24c9e815c4d338c0654ff2980
 SHA512:
-  metadata.gz: 8fe7ac0a75bc514a24ed3656f68b926b40007dfd5aa596c7fa7b58fcd64fb5081b5f17435ee508cb174b9c1da98526bb189ece5d88acec56b2b28d4b710b5abe
-  data.tar.gz: 2e12cb7c99f5ce534e9f4c55c338b31d0772838765b69832669503f3d81a373340ebb5bfa916028d8ccdb58340ec79015afb520cb66fea5e945eed97617aecf0
+  metadata.gz: a94d9ab2c7d815c912670e58e234f7052c6c062c54cb2ab6c65a729280db7fb1867ee5314aa6599893a6aabbbebdb8763b2cddf9e5e01056e8a532fa7eef7f7b
+  data.tar.gz: 9ad9d668636f257c12c1a9dec5bd6cfcc4c209feb2f18adaf63717d8c0725535b347025305a391ace8d67e6fffef87827015d93784887cf79ea8e7b37aa70915

data/README.md

@@ -1,23 +1,56 @@
+<!--
+  # @title Upgrow
+-->
+
 # Upgrow
 
-TODO: Delete this and the text above, and describe your gem
+**Heads Up!**
 
-## Installation
+**This project is a work in progress. We are working on documenting our
+best practices to help sustainable development for the long term with
+Ruby on Rails. The Upgrow gem is not yet available and the contents of
+the guide are still being amended, matured, and reviewed. That being
+said, feel free to follow the GitHub repo and stay tuned for the
+latest updates!**
 
-Add this line to your application's Gemfile:
+## A sustainable architecture for Ruby on Rails
 
-```ruby
-gem 'upgrow'
-```
+Ruby on Rails is the framework of choice for web apps at Shopify. It is an
+opinionated stack for quick and easy development of apps that need standard
+persistence with relational databases, an HTTP server, and HTML views.
+
+By design, Rails does not define conventions for structuring business logic and
+domain-specific code, leaving developers to define their own architecture and
+best practices for a sustainable codebase.
+
+In fast product development teams, budgets and deadlines interfere with this
+architectural work, leading to poorly written business logic and complicated
+code that is very hard to maintain long term. Even when developer teams take
+the time to think about what a good architecture in Rails look like, this work
+is likely required to be done all over again when a new Rails app needs to be
+created.
 
-And then execute:
+This project aims to make it easier for both new and existing Rails apps to
+adopt patterns that are proven to make code more sustainable long term, and
+codebases easier to maintain and extend. We will recommend a set of abstractions
+and practices that are simple, yet powerful in organizing code in Rails apps in
+a way that allows fast-growing apps to remain easy to change.
 
-    $ bundle install
+## The Upgrow Guide
 
-Or install it yourself as:
+Visit [https://upgrow.shopify.io](https://upgrow.shopify.io) to learn more about
+creating a sustainable architecture for your Rails apps.
 
-    $ gem install upgrow
+## The Upgrow Gem
+
+This project offers a Ruby gem to make it easier for Rails apps to adopt the
+sustainable architecture proposed in the Upgrow Guide. To install, add this line
+to your application's Gemfile and run `bundle install`:
+
+```ruby
+gem 'upgrow'
+```
 
-## Usage
+## License
 
-TODO: Write usage instructions here
+For copyright and licensing please refer to `LICENSE.txt`.

data/Rakefile

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
+require 'bundler/setup'
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rubocop/rake_task'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+load('rails/tasks/engine.rake')
+task 'test:system' => 'app:test:system' # Hack to use the test environment.
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
+  t.pattern = 'test/upgrow/**/*_test.rb'
   t.warning = true
   t.verbose = true
-  t.test_files = FileList['test/**/*.rb']
 end
 
-require 'rubocop/rake_task'
-
 RuboCop::RakeTask.new
 
-task default: [:test, :rubocop]
+task default: ['rubocop', 'test', 'db:setup', 'test:system']

data/lib/upgrow.rb

@@ -1,6 +1,17 @@
 # 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/input'
+require_relative 'upgrow/model'
+require_relative 'upgrow/result'
+
+# The gem's main namespace.
 module Upgrow
-  class Error < StandardError; end
-  # Your code goes here...
 end

data/lib/upgrow/action.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+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.
+  # Ultimately, Actions are the public interface of the app’s business layers.
+  #
+  # Rails controllers talk to the app’s internals by sending messages to
+  # specific Actions, optionally with the required inputs. Actions have a
+  # one-to-one relationship with incoming requests: they are paired
+  # symmetrically with end-user intents and demands. This is quite a special
+  # requirement from this layer: any given HTTP request handled by the app
+  # should be handled by a single Action.
+  #
+  # The fact that each Action represents a meaningful and complete
+  # request-response cycle forces modularization for the app’s business logic,
+  # exposing immediately complex relationships between objects at the same time
+  # that frees up the app from scenarios such as interdependent requests. In
+  # other words, Actions do not have knowledge or coupling between other Actions
+  # whatsoever.
+  #
+  # Actions respond to a single public method perform. Each Action defines its
+  # own set of required arguments for perform, as well what can be expected as
+  # the result of that method.
+  class Action
+    class << self
+      attr_writer :result_class
+
+      # Each Action class has its own Result class with the expected members to
+      # be returned when the Action is called successfully.
+      #
+      # @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
+      end
+
+      # Sets the Action Result class with the given members.
+      #
+      # @param args [Array<Symbol>] the list of members for the Result class.
+      def result(*args)
+        @result_class = Result.new(*args)
+      end
+    end
+
+    # Instance method to return the Action's Result class. This method delegates
+    # to the Action class's method (see #result_class).
+    #
+    # @return [Result] the Result class for this Action.
+    def result
+      self.class.result_class
+    end
+  end
+end

data/lib/upgrow/active_record_adapter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # Mixin that implements Repository methods with an Active Record Base. When
+  # included in a Repository class, it sets the default base to be a class
+  # ending with `Record`.
+  module ActiveRecordAdapter
+    # Fetches all Records and returns them as an Array of Models.
+    #
+    # @return [Array<Model>] a collection of Models representing all persisted
+    #   Records.
+    def all
+      base.all.map { |record| to_model(record.attributes) }
+    end
+
+    # Persists a new Record with the given input, and materializes the newly
+    # created Record as the returned Model instance.
+    #
+    # @param input [Input] the Input with the attributes for the new Record.
+    #
+    # @return [Model] the Model with the attributes of the newly created
+    #   Record.
+    def create(input)
+      record = base.create!(input.attributes)
+      to_model(record.attributes)
+    end
+
+    # Retrieves the Record with the given ID, representing its data as a Model.
+    #
+    # @param id [Integer] the ID of the Record to be fetched.
+    #
+    # @return [Model] the Model with the attributes of the Record with the given
+    #   ID.
+    def find(id)
+      record = base.find(id)
+      to_model(record.attributes)
+    end
+
+    # Updates the Record with the given ID with the given Input attributes.
+    #
+    # @param id [Integer] the ID of the Record to be updated.
+    # @param input [Input] the Input with the attributes to be set in the
+    #   Record.
+    #
+    # @return [Model] the Model instance with the updated data of the Record.
+    def update(id, input)
+      record = base.update(id, input.attributes)
+      to_model(record.attributes)
+    end
+
+    # Deletes the Record that has the given ID.
+    #
+    # @param id [Integer] the ID of the Record to be deleted.
+    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/basic_repository.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # Base class for Repositories. It offers a basic API for the state all
+  # Repositories should have, as well as the logic on how to materialize data
+  # into Models.
+  class BasicRepository
+    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
+    end
+
+    # Represents the raw Hash of data attributes as a Model instance from the
+    # Repositorie's Model class.
+    #
+    # @param attributes [Hash<Symbol, Object>] the list of attributes the Model
+    #   will have.
+    #
+    # @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 default_base; end
+
+    def default_model_class
+      model_class_name = self.class.name[/\A(.+)Repository\z/, 1]
+      Object.const_get(model_class_name)
+    end
+  end
+end

data/lib/upgrow/immutable_object.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+module Upgrow
+  # A read-only Object. An Immutable Object is initialized with its attributes
+  # and subsequent state changes are not permitted.
+  class ImmutableObject
+    @attribute_names = []
+
+    class << self
+      attr_reader :attribute_names
+
+      # Specify an attribute for the Immutable Object. This enables the object
+      # to be instantiated with the attribute, as well as creates an attribute
+      # reader for it.
+      #
+      # @param name [Symbol] the name of the attribute.
+      def attribute(name)
+        @attribute_names << name
+        attr_reader(name)
+      end
+
+      private
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@attribute_names, @attribute_names.dup)
+      end
+    end
+
+    # Initializes a new Immutable Object with the given member values.
+    #
+    # @param args [Hash<Symbol, Object>] the list of values for each attribute
+    #   of the Immutable Object.
+    #
+    # @raise [ArgumentError] if the given argument is not an attribute.
+    def initialize(**args)
+      absent_attributes = args.keys - self.class.attribute_names
+
+      if absent_attributes.any?
+        raise ArgumentError, "Unknown attribute #{absent_attributes}"
+      end
+
+      args.each do |name, value|
+        instance_variable_set("@#{name}", value)
+      end
+
+      freeze
+    end
+
+    # The collection of attributes and their values.
+    #
+    # @return [Hash<Symbol, Object>] the collection of attributes and their
+    #   values.
+    def attributes
+      self.class.attribute_names.to_h { |name| [name, public_send(name)] }
+    end
+  end
+end

data/lib/upgrow/immutable_struct.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+module Upgrow
+  # A read-only Struct. An Immutable Struct is initialized with its member
+  # values and subsequent state changes are not permitted.
+  class ImmutableStruct < Struct
+    class << self
+      # Creates a new Immutable Struct class with the given members.
+      #
+      # @param args [Array<Symbol>] the list of members for the new class.
+      #
+      # @return [ImmutableStruct] the new Immutable Struct class able to
+      #   accommodate the given members.
+      def new(*args, &block)
+        if args.any? { |member| !member.is_a?(Symbol) }
+          raise ArgumentError, 'all members must be symbols'
+        end
+
+        struct_class = super(*args, keyword_init: true, &block)
+
+        struct_class.members.each do |member|
+          struct_class.send(:undef_method, :"#{member}=")
+        end
+
+        struct_class
+      end
+    end
+
+    undef []=
+
+    # Initializes a new Immutable Struct with the given member values.
+    #
+    # @param args [Hash<Symbol, Object>] the list of values for each member of
+    #   the Immutable Struct.
+    def initialize(**args)
+      members.each { |key| args.fetch(key) }
+      super(**args)
+      freeze
+    end
+  end
+end

data/lib/upgrow/input.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # Inputs are objects that represent user-entered data. They are populated with
+  # information that is available for modification, such as in HTML forms or in
+  # API payloads, and they are passed on to Repositories as arguments for
+  # persistence operations, as provided by the app user. Inputs have knowledge
+  # about which attributes should be present in a payload, among other
+  # constraints, and are able to tell if its own state is valid or not.
+  #
+  #
+  # It is important to note that Inputs differ from Records for not representing
+  # domain entities, but simply data entered by the user. Inputs do not have
+  # numeric identifiers, for example, as these are generated by the system and
+  # not set by users. There are also no strong expectations in regards to data
+  # integrity for inputs, since user-entered data can contain any information of
+  # different types, or even not to be present at all.
+  #
+  # User input validation is a core part of any app’s business logic. It ensures
+  # that incoming data is sane, proper, and respects a predefined schema. A
+  # default Rails app overloads Record objects with yet another responsibility:
+  # being the place where validation rules are written and checked. While there
+  # is value in making sure that database constraints are respected, input
+  # validation should happen as part of the business logic layer, before
+  # persistence is invoked with invalid input. Input objects are a great fit for
+  # that task. By leveraging validation utilities from Active Model, Input
+  # objects can not only perform the same validations as Records but also
+  # seamlessly integrate with view helpers such as Rails form builders.
+  class Input < ImmutableObject
+    include ActiveModel::Validations
+
+    # Creates a new Input instance.
+    #
+    # @param attributes [Hash<String, Object>] the values for each attribute.
+    def initialize(attributes = {})
+      @errors = ActiveModel::Errors.new(self)
+      super(**attributes.to_hash.transform_keys(&:to_sym))
+    end
+
+    private
+
+    # Overwrites the validation context writer so the Input's state is not
+    # mutated.
+    def validation_context=(_)
+    end
+  end
+end