runger_actions 0.19.0

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'runger_actions'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/guard

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', 'guard')

data/bin/release

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'release' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('release_assistant', 'release')

data/bin/rspec

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort(<<~ERROR)
+      Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+      Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.
+    ERROR
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/rubocop

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort(<<~ERROR)
+      Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+      Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.
+    ERROR
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/runger_actions/action/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generates an action with the given name.
+
+Example:
+    bin/rails generate runger_actions:action Users::Create
+
+    This will create:
+        app/actions/users/create.rb

data/lib/generators/runger_actions/action/action_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RungerActions::Generators ; end
+
+class RungerActions::Generators::ActionGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('templates', __dir__)
+
+  def create_policy
+    template('action.rb', File.join('app/actions', class_path, "#{file_name}.rb"))
+  end
+end

data/lib/generators/runger_actions/action/templates/action.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < ApplicationAction
+  # requires :email, String
+
+  # returns :user, User
+
+  def execute
+    # result.user = User.create!(email: email)
+    # NewUserMailer.user_created(result.user.id).deliver_later
+  end
+end

data/lib/runger_actions/base.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+class RungerActions::Base
+  extend Memoist
+
+  class << self
+    extend Memoist
+
+    def run!(params)
+      new!(params).run!
+    end
+
+    def new!(params)
+      action = new(params)
+      if action.valid?
+        action
+      else
+        raise(RungerActions::InvalidParam, action.errors.full_messages.join(', '))
+      end
+    end
+
+    def requires(param_name, *shape_descriptions, &blk)
+      required_params[param_name] = Shaped::Shape(*shape_descriptions)
+
+      shape_description = shape_descriptions.first if shape_descriptions.size == 1
+      if (
+        shape_description.is_a?(Class) && (shape_description < ActiveRecord::Base) && blk.present?
+      )
+        register_validator_klass(param_name, shape_description, blk)
+      end
+
+      define_reader_method(param_name)
+    end
+
+    def define_reader_method(param_name)
+      define_method(param_name) do
+        @params[param_name]
+      end
+    end
+
+    def register_validator_klass(param_name, param_klass, blk)
+      validator_klass = const_set("#{param_name.to_s.camelize}Validator", Class.new)
+      validator_klass.include(ActiveModel::Model)
+      validator_klass.attr_accessor(*param_klass.column_names)
+      validator_klass.class_eval(&blk)
+      validators[param_name] = validator_klass
+    end
+
+    def returns(param_name, *shape_descriptions)
+      shape = Shaped::Shape(*shape_descriptions)
+      promised_values[param_name] = shape
+      result_klass.class_eval do
+        define_method(param_name) do
+          @return_values[param_name]
+        end
+
+        define_method("#{param_name}=") do |value|
+          if locked?
+            raise(RungerActions::MutatingLockedResult, <<~ERROR.squish)
+              You are attempting to assign a value to an instance of #{self.class} outside of the
+              #{self.class.module_parent}#execute method. This is not allowed; you may only assign
+              values to the `result` within the #execute method.
+            ERROR
+          end
+
+          if !shape.matched_by?(value)
+            raise(RungerActions::TypeMismatch, <<~ERROR.squish)
+              Attemted to assign an invalid value for `result.#{param_name}` ; expected an object
+              shaped like #{shape} but got #{value.inspect}
+            ERROR
+          end
+
+          @return_values[param_name] = value
+        end
+      end
+    end
+
+    def fails_with(error_type)
+      result_klass.class_eval do
+        define_method("#{error_type}!") do |error_message = nil|
+          @failure = error_type
+          @error_message = error_message
+          if @action.raise_on_failure?
+            raise(
+              RungerActions::RuntimeFailure,
+              "#{@action.class.name} action failed with `#{error_type}`",
+            )
+          end
+        end
+
+        define_method("#{error_type}?") do
+          @failure == error_type
+        end
+      end
+    end
+
+    memoize \
+    def result_klass
+      const_set(:Result, Class.new(RungerActions::Result))
+    end
+
+    memoize \
+    def required_params
+      {}
+    end
+
+    memoize \
+    def promised_values
+      {}
+    end
+
+    memoize \
+    def validators
+      {}
+    end
+  end
+
+  attr_reader :errors
+
+  # We can't specify keyword arguments for this method because we don't know which keywords/params
+  # the method will need to accept; that's defined by the user.
+  #
+  # rubocop:disable Style/OptionHash
+  def initialize(params = {})
+    @params = params
+    @errors = ActiveModel::Errors.new(self)
+    validate_required_params!
+  end
+  # rubocop:enable Style/OptionHash
+
+  def run(raise_on_failure: false)
+    @raise_on_failure = raise_on_failure
+    if !respond_to?(:execute)
+      raise(RungerActions::ExecuteNotImplemented, <<~ERROR.squish)
+        All RungerActions classes must implement an #execute instance method, but #{self.class}
+        fails to do so.
+      ERROR
+    end
+
+    execute
+    result.lock!
+    verify_promised_return_values! if result.success?
+    result
+  end
+
+  def run!
+    if valid?
+      run(raise_on_failure: true)
+    else
+      raise(RungerActions::InvalidParam, @errors.full_messages.join(', '))
+    end
+  end
+
+  def valid?
+    run_custom_validations
+    @errors.blank?
+  end
+
+  def raise_on_failure?
+    !!@raise_on_failure
+  end
+
+  memoize \
+  def result
+    self.class.result_klass.new(action: self)
+  end
+
+  private
+
+  def verify_promised_return_values!
+    missing_return_values = self.class.promised_values.keys - result.return_values.keys
+    if missing_return_values.any?
+      violation_messages =
+        missing_return_values.map do |missing_return_value|
+          expected_shape = self.class.promised_values[missing_return_value]
+          "`#{missing_return_value}` (should be shaped like #{expected_shape})"
+        end
+
+      raise(RungerActions::MissingResultValue, <<~ERROR.squish)
+        #{self.class.name} failed to set all promised return values on its `result`. The
+        following were missing on the `result`: #{violation_messages.join(', ')}.
+      ERROR
+    end
+  end
+
+  def run_custom_validations
+    self.class.required_params.each_key do |param_name|
+      validator_klass = self.class.validators[param_name]
+      next if validator_klass.nil?
+
+      model_instance = @params[param_name]
+      validator_instance = validator_klass.new(model_instance.attributes)
+      if !validator_instance.valid?
+        @errors = validator_instance.errors
+      end
+    end
+  end
+
+  def validate_required_params!
+    missing_params = self.class.required_params.keys - @params.keys
+    if missing_params.any?
+      raise(RungerActions::MissingParam, <<~ERROR.squish)
+        Required param(s) #{missing_params.map { "`#{_1}`" }.join(', ')} were not provided to
+        the #{self.class} action.
+      ERROR
+    end
+
+    type_mismatches = []
+    self.class.required_params.each do |param_name, shape|
+      value = @params[param_name]
+      if !shape.matched_by?(value)
+        type_mismatches << [param_name, shape, value]
+      end
+    end
+
+    if type_mismatches.any?
+      messages =
+        type_mismatches.map do |param_name, shape, value|
+          <<~MESSAGE.squish
+            `#{param_name}` is expected to be shaped like #{shape}, but was
+            `#{value.is_a?(String) ? value.inspect : value}`
+          MESSAGE
+        end
+      raise(RungerActions::TypeMismatch, <<~ERROR.squish)
+        One or more required params are of the wrong type: #{messages.join(' ; ')}.
+      ERROR
+    end
+  end
+end

data/lib/runger_actions/error.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class RungerActions::Error < StandardError ; end

data/lib/runger_actions/result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class RungerActions::Result
+  attr_reader :error_message, :return_values
+
+  def initialize(action:)
+    @action = action
+    @return_values = {}
+    @failure = nil
+  end
+
+  def lock!
+    @locked = true
+  end
+
+  def locked?
+    @locked == true
+  end
+
+  def success?
+    @failure.nil?
+  end
+end

data/lib/runger_actions/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RungerActions
+  VERSION = '0.19.0'
+end

data/lib/runger_actions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RungerActions ; end
+
+require 'active_model'
+require 'active_record'
+require 'active_support/all'
+require 'memoist'
+require 'shaped'
+Dir["#{File.dirname(__FILE__)}/runger_actions/**/*.rb"].each { |file| require file }
+
+class RungerActions::ExecuteNotImplemented < RungerActions::Error ; end
+class RungerActions::InvalidParam < RungerActions::Error ; end
+class RungerActions::MissingParam < RungerActions::Error ; end
+class RungerActions::MissingResultValue < RungerActions::Error ; end
+class RungerActions::MutatingLockedResult < RungerActions::Error ; end
+class RungerActions::RuntimeFailure < RungerActions::Error ; end
+class RungerActions::TypeMismatch < RungerActions::Error ; end

data/runger_actions.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/runger_actions/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'runger_actions'
+  spec.version       = RungerActions::VERSION
+  spec.authors       = ['David Runger']
+  spec.email         = ['davidjrunger@gmail.com']
+
+  spec.summary       = 'Organize (and validate) the business logic of your Rails application.'
+  spec.description   = 'Organize (and validate) the business logic of your Rails application.'
+  spec.homepage      = 'https://github.com/davidrunger/runger_actions'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.2.0')
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/davidrunger/runger_actions'
+  spec.metadata['changelog_uri'] =
+    'https://github.com/davidrunger/runger_actions/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files =
+    Dir.chdir(File.expand_path(__dir__)) do
+      `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    end
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency('memoist', '~> 0.16')
+  spec.add_runtime_dependency('rails', '>= 6', '< 8')
+  spec.add_runtime_dependency('shaped', '>= 0.9', '< 0.11')
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: runger_actions
+version: !ruby/object:Gem::Version
+  version: 0.19.0
+platform: ruby
+authors:
+- David Runger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-05-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: memoist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: shaped
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Organize (and validate) the business logic of your Rails application.
+email:
+- davidjrunger@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/dependabot.yml"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".release_assistant.yml"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- RELEASING.md
+- Rakefile
+- bin/_guard-core
+- bin/console
+- bin/guard
+- bin/release
+- bin/rspec
+- bin/rubocop
+- bin/setup
+- lib/generators/runger_actions/action/USAGE
+- lib/generators/runger_actions/action/action_generator.rb
+- lib/generators/runger_actions/action/templates/action.rb
+- lib/runger_actions.rb
+- lib/runger_actions/base.rb
+- lib/runger_actions/error.rb
+- lib/runger_actions/result.rb
+- lib/runger_actions/version.rb
+- runger_actions.gemspec
+homepage: https://github.com/davidrunger/runger_actions
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/davidrunger/runger_actions
+  source_code_uri: https://github.com/davidrunger/runger_actions
+  changelog_uri: https://github.com/davidrunger/runger_actions/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.4
+signing_key:
+specification_version: 4
+summary: Organize (and validate) the business logic of your Rails application.
+test_files: []