upgrow 0.0.1 → 0.0.2

data/lib/upgrow/model.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # Models are objects that represent core entities of the app’s business logic.
+  # These are usually persisted and can be fetched and created as needed. They
+  # have unique keys for identification (usually a numeric value), and, most
+  # importantly perhaps, they are immutable. This is the key difference between
+  # this new Model layer of objects and the Active Record instances regularly
+  # referred to as models in typical Rails default apps.
+  #
+  # Another difference between Models and Records is that, once instantiated,
+  # Models simply hold its attributes immutably, and they don’t have any
+  # capabilities to create or update any information in the persistence layer.
+  #
+  # The collaboration between Repositories and Models is what allows Active
+  # Record to be completely hidden away from any other areas of the app. There
+  # are no references to Records in controllers, views, and anywhere else.
+  # Repositories are invoked instead, which in turn return read-only Models.
+  class Model < ImmutableObject
+    attribute :id
+    attribute :created_at
+    attribute :updated_at
+
+    # Initializes a new Model with the given member values.
+    #
+    # @param args [Hash<Symbol, Object>] the list of values for each attribute.
+    #
+    # @raise [KeyError] if an attribute is missing in the list of arguments.
+    def initialize(**args)
+      self.class.attribute_names.each { |key| args.fetch(key) }
+
+      super
+    end
+  end
+end

data/lib/upgrow/repository.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Upgrow
+  # Repositories are responsible for the persistence layer of the app. They
+  # encapsulate Rails’ Active Record in a subset of simple methods for querying
+  # and persistence of data, and return simple read-only objects as a result.
+  # This allows the app to isolate Active Record only to this subset, exposing
+  # only the desired queries and methods to other layers through Repositories.
+  class Repository < BasicRepository
+    include ActiveRecordAdapter
+  end
+end

data/lib/upgrow/result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+module Upgrow
+  # Results are special Structs that are generated dynamically to accommodate a
+  # set of pre-defined members. Since different Actions might want to return
+  # zero to multiple values, they are always returned as members of a Result
+  # instance.
+  #
+  # Regardless of the values the Action might want to return, a Result has one
+  # default member called errors, which holds any errors that might occur when
+  # the Action is performed. If Result errors are empty, the Result is a
+  # success; if there are errors present, however, the Result is a failure. This
+  # empowers Actions with a predictable public interface, so callers can expect
+  # how to evaluate if an operation was successful or not by simply checking the
+  # success or failure of a Result.
+  #
+  # Additionally, Result instances behave like monadic values by offering
+  # bindings to be called only in case of success or failure, which further
+  # simplifies the caller’s code by not having to use conditional to check for
+  # errors.
+  class Result < ImmutableStruct
+    class << self
+      # Creates a new Result class that can handle the given members.
+      #
+      # @param members [Array<Symbol>] the list of members the new Result should
+      #   be able to hold.
+      #
+      # @return [Result] the new Result class with the given members.
+      def new(*members)
+        super(*members, :errors)
+      end
+
+      # Returns a new Result instance populated with the given values.
+      #
+      # @param values [Hash<Symbol, Object>] the list of values for each member
+      #   provided as keyword arguments.
+      #
+      # @return [Result] the Result instance populated with the given values.
+      def success(*values)
+        new(*values)
+      end
+
+      # Returns a new Result instance populated with the given errors.
+      #
+      # @param errors [ActiveModel::Errors] the errors object to be set as the
+      #   Result errors.
+      #
+      # @return [Result] the Result instance populated with the given errors.
+      def failure(errors)
+        values = members.to_h { |member| [member, nil] }
+        new(**values.merge(errors: errors))
+      end
+    end
+
+    # Calls the given block only when the Result is successful.
+    #
+    # This method receives a block that is called with the Result values passed
+    # to the block only when the Result itself is a success, meaning its list of
+    # errors is empty. Otherwise the block is not called.
+    #
+    # It returns self for convenience so other methods can be chained together.
+    #
+    # @yield [values] gives the Result values to the block on a successful
+    #   Result.
+    #
+    # @return [Result] self for chaining.
+    def and_then
+      yield(**to_h.except(:errors)) if errors.none?
+      self
+    end
+
+    # Calls the given block only when the Result is a failure.
+    #
+    # This method receives a block that is called with the Result errors passed
+    # to the block only when the Result itself is a failure, meaning its list of
+    # errors is not empty. Otherwise the block is not called.
+    #
+    # It returns self for convenience so other methods can be chained together.
+    #
+    # @yield [errors] gives the Result errors to the block on a failed Result.
+    #
+    # @return [Result] self for chaining.
+    def or_else
+      yield(errors) if errors.any?
+      self
+    end
+
+    private
+
+    def initialize(*args)
+      values = { errors: [] }.merge(args.first || {})
+      super(**values)
+    end
+  end
+end

data/test/application_system_test_case.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+require 'webdrivers/chromedriver'
+require 'action_dispatch/system_testing/server'
+
+ActionDispatch::SystemTesting::Server.silence_puma = true
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :selenium, using: :headless_chrome do |options|
+    options.add_argument('--disable-dev-shm-usage')
+  end
+end

data/test/dummy/app/actions/create_article_action.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+class CreateArticleAction < Upgrow::Action
+  result :article
+
+  def perform(input)
+    if input.valid?
+      article = ArticleRepository.new.create(input)
+      result.success(article: article)
+    else
+      result.failure(input.errors)
+    end
+  end
+end

data/test/dummy/app/actions/delete_article_action.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+class DeleteArticleAction < Upgrow::Action
+  def perform(id)
+    ArticleRepository.new.delete(id)
+    result.success
+  end
+end

data/test/dummy/app/actions/edit_article_action.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+class EditArticleAction < Upgrow::Action
+  result :article
+
+  def perform(id)
+    article = ArticleRepository.new.find(id)
+
+    result.success(article: article)
+  end
+end

data/test/dummy/app/actions/list_articles_action.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+class ListArticlesAction < Upgrow::Action
+  result :articles
+
+  def perform
+    result.success(articles: ArticleRepository.new.all)
+  end
+end

data/test/dummy/app/actions/show_article_action.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+class ShowArticleAction < Upgrow::Action
+  result :article
+
+  def perform(id)
+    article = ArticleRepository.new.find(id)
+
+    result.success(article: article)
+  end
+end

data/test/dummy/app/actions/update_article_action.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+class UpdateArticleAction < Upgrow::Action
+  result :article
+
+  def perform(id, input)
+    if input.valid?
+      article = ArticleRepository.new.update(id, input)
+      result.success(article: article)
+    else
+      result.failure(input.errors)
+    end
+  end
+end

data/test/dummy/app/channels/application_cable/channel.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/test/dummy/app/channels/application_cable/connection.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+  end
+end

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+class ApplicationController < ActionController::Base
+end

data/test/dummy/app/controllers/articles_controller.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class ArticlesController < ApplicationController
+  def index
+    @articles = ListArticlesAction.new.perform.articles
+  end
+
+  def show
+    @article = ShowArticleAction.new.perform(params[:id]).article
+  end
+
+  def new
+    @input = ArticleInput.new
+  end
+
+  def edit
+    article = EditArticleAction.new.perform(params[:id]).article
+    @input = ArticleInput.new(
+      title: article.title, body: article.body
+    )
+  end
+
+  def create
+    @input = ArticleInput.new(article_params)
+
+    CreateArticleAction.new.perform(@input)
+      .and_then do |article:|
+        redirect_to(
+          article_path(article.id), notice: 'Article was successfully created.'
+        )
+      end
+      .or_else do |errors|
+        @errors = errors
+        render(:new)
+      end
+  end
+
+  def update
+    @input = ArticleInput.new(article_params)
+
+    UpdateArticleAction.new.perform(params[:id], @input)
+      .and_then do |article:|
+        redirect_to(
+          article_path(article.id),
+          notice: 'Article was successfully updated.'
+        )
+      end
+      .or_else do |errors|
+        @errors = errors
+        render(:edit)
+      end
+  end
+
+  def destroy
+    DeleteArticleAction.new.perform(params[:id])
+    redirect_to(articles_url, notice: 'Article was successfully destroyed.')
+  end
+
+  private
+
+  def article_params
+    params.require(:article_input).permit(:title, :body)
+  end
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+module ApplicationHelper
+  class BulmaFormBuilder < ActionView::Helpers::FormBuilder
+    # Generic field wrapper for form inputs.
+    #
+    # It wraps the given block in a field div. In case a method is specified it
+    # also prepends a label tag for the input and renders any errors for the
+    # given method after the input.
+    #
+    # @param method [Symbol] the optional method to be called from the object
+    #   this form builder is attached to.
+    # @param label [Boolean] if the field needs a label or not.
+    # @param addons [Boolean] if the field will have addons.
+    #
+    # @return [String] an HTML safe markup content.
+    def field(method: nil, label: true, addons: false)
+      field_class = ['field']
+      field_class << 'has-addons' if addons
+      @template.content_tag(:div, class: field_class) do
+        result = ''.html_safe
+
+        result += label(method, class: 'label') if method && label
+        result += yield
+
+        if method
+          errors_for(method).each do |error|
+            result += @template.content_tag(:p, error, class: 'help is-danger')
+          end
+        end
+
+        result
+      end
+    end
+
+    # Render a text-type input.
+    #
+    # @param method [Symbol] the method to be called from the object this form
+    #   builder is attached to.
+    # @param label [Boolean] if the input requires a label.
+    # @param expanded [Boolean] if the control element will be expanded.
+    # @param field [Boolean] if the text will be wrapped within a field.
+    # @param args [Hash] optional arguments for the overloaded text_field
+    #   method.
+    #
+    # @return [String] an HTML safe markup content.
+    def text_field(method, label: true, expanded: false, field: true, **args)
+      input_class = ['input']
+      input_class << 'is-danger' if errors_for(method).any?
+      output = control(expanded: expanded) do
+        super(method, class: input_class, **args)
+      end
+
+      if field
+        field(method: method, label: label) { output }
+      else
+        output
+      end
+    end
+
+    def text_area(method, **args)
+      input_class = ['textarea']
+      input_class << 'is-danger' if errors_for(method).any?
+
+      output = control(expanded: false) do
+        super(method, class: input_class, **args)
+      end
+
+      field(method: method, label: true) { output }
+    end
+
+    # Render a form submit button.
+    #
+    # @param text [Symbol] the text for the button.
+    # @param field [Boolean] if the button is within a field.
+    # @param data [Hash] the HTML data attribute.
+    #
+    # @return [String] an HTML safe markup content.
+    def submit(text, field: true, data: {})
+      output = control { super(text, class: 'button is-primary', data: data) }
+      if field
+        field { output }
+      else
+        output
+      end
+    end
+
+    private
+
+    def control(expanded: false)
+      control_class = ['control']
+      control_class << ['is-expanded'] if expanded
+      @template.content_tag(:p, class: control_class) do
+        yield
+      end
+    end
+
+    def errors_for(method)
+      (options[:errors] || ActiveModel::Errors.new(self))
+        .full_messages_for(method)
+    end
+  end
+end

data/test/dummy/app/inputs/article_input.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+class ArticleInput < Upgrow::Input
+  attribute :title
+  attribute :body
+
+  validates :title, presence: true
+  validates :body, presence: true, length: { minimum: 10 }
+end

data/test/dummy/app/jobs/application_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer
+  # available
+  # discard_on ActiveJob::DeserializationError
+end

data/test/dummy/app/mailers/application_mailer.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+class ApplicationMailer < ActionMailer::Base
+  default from: 'from@example.com'
+  layout 'mailer'
+end