slayer 0.4.0.beta4 → 0.5.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5fdd7e7da2630dcab6357d4aa3391c24d203cd5b
-  data.tar.gz: 61d1b9ba39d0751fc579dadaf106c31d77358e24
+SHA256:
+  metadata.gz: bc095dc4fad61e836560eb30851324c846f8a5a1b3fd51bdc48d692ab576d8a3
+  data.tar.gz: 9a77c6b602b544462311a897bb53685434a51dde783602274fce9d83096f3644
 SHA512:
-  metadata.gz: fc1f3e004f7403938b3b8505a527211e3ed04b72e0674e2d8f36a00300815f158057e79354eb743f68e0295d6c59c07715dd7dc7ac7d8ed6cc86daf86be5c1ac
-  data.tar.gz: 10cc9fe7a69d05478255729b97575d31f1b1daa6360e6de049d4789b1f0f0a45ebec16ece1895a310ce9d9cd9b3bdda12ee119e3665b1007b1abbcbdf41bbd0d
+  metadata.gz: 3a95c4d4b95bffc5d4f129e07fae690fcccd3543c6f7f745471aeaa8093bbfd9e5b377ffc931d52c0bb0f4f3048330f7b9421233246f633dde19de52526a6851
+  data.tar.gz: 2de8ba806e4210a197ec87323f8a48777f6e024e9546170cee4ce15a651cfad2dc62134f3e4021003fde1ef378e57771778d98eec49a9747110955c675956926

data/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+# .github/workflows/release.yml
+
+name: Release
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0.0
+      - run: bundle install
+      - name: publish gem
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+

data/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test & Lint
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: ['3.1', '3.0', '2.7']
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Rubocop
+        run: rubocop
+      - name: Run tests
+        run: bundle exec rake

data/.gitignore

@@ -1,6 +1,7 @@
 /.bundle/
 /.yardoc
 /_yardoc/
+/vendor/
 /coverage/
 /doc/
 /pkg/

data/.rubocop.yml

@@ -1,7 +1,7 @@
-inherit_from: .rubocop_todo.yml
-
 AllCops:
-  TargetRubyVersion: 2.1
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.1
   Include:
     - 'lib/**/*.rb'
     - 'test/**/*.rb'
@@ -12,6 +12,14 @@ AllCops:
     - 'bin/**/*'
     - 'test/fixtures/**/*.rb'
 
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+
+Style/Documentation:
+  Enabled: false
+
+Naming/BlockForwarding:
+  Enabled: false
 
 Style/RedundantSelf:
   Enabled: false
@@ -34,13 +42,7 @@ Style/FrozenStringLiteralComment:
 Layout/CommentIndentation:
   Enabled: false
 
-Style/BracesAroundHashParameters:
-  Enabled: false
-
-Layout/IndentationConsistency:
-  EnforcedStyle: rails
-
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
 
 Metrics/ClassLength:
@@ -49,17 +51,10 @@ Metrics/ClassLength:
 Layout/EmptyLineBetweenDefs:
   AllowAdjacentOneLineDefs: true
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   AllowedNames:
     - _
 
-# Temporarily disabled until this can be resolved in the todo file
-# Style/Documentation:
-#   Exclude:
-#     - 'spec/**/*'
-#     - 'test/**/*'
-#     - 'lib/ext/**/*'
-
 Style/ClassVars:
   Exclude:
     - 'lib/slayer/service.rb'

data/Dockerfile

@@ -1,5 +1,4 @@
-FROM ruby:2.5.1-alpine
-MAINTAINER wyatt@apsis.io
+FROM ruby:3.1.2-alpine
 
 RUN apk add --no-cache --update \
     bash \

data/README.md

@@ -8,7 +8,7 @@ Slayer is intended to operate as a minimal service layer for your ruby applicati
 
 ## Application Structure
 
-Slayer provides 3 base classes for organizing your business logic: `Forms`, `Commands`, and `Services`. Each of these has a distinct role in your application's structure.
+Slayer provides 2 base classes for organizing your business logic: `Forms` and `Commands`. These each have a distinct role in your application's structure.
 
 ### Forms
 
@@ -16,16 +16,12 @@ Slayer provides 3 base classes for organizing your business logic: `Forms`, `Com
 
 ### Commands
 
-`Slayer::Commands` are the bread and butter of your application's business logic, and a specific implementation of the `Slayer::Service` object. `Commands` are where you compose services, and perform one-off business logic tasks. In our applications, we usually create a single `Command` per `Controller` endpoint.
+`Slayer::Commands` are the bread and butter of your application's business logic. `Commands` wrap logic into easily tested, isolated, composable classes. In our applications, we usually create a single `Command` per `Controller` endpoint.
 
 `Slayer::Commands` must implement a `call` method, which always return a structured `Slayer::Result` object making operating on results straightforward. The `call` method can also take a block, which provides `Slayer::ResultMatcher` object, and enforces handling of both `pass` and `fail` conditions for that result.
 
 This helps provide confidence that your core business logic is behaving in expected ways, and helps coerce you to develop in a clean and testable way.
 
-### Services
-
-`Slayer::Service`s are the base class of `Slayer::Command`s, and encapsulate re-usable chunks of application logic. `Services` also return structured `Slayer::Result` objects.
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -50,7 +46,7 @@ $ gem install slayer
 
 ### Commands
 
-Slayer Commands should implement `call`, which will `pass` or `fail` the service based on input. Commands return a `Slayer::Result` which has a predictable interface for determining `success?` or `failure?`, a 'value' payload object, a 'status' value, and a user presentable `message`.
+Slayer Commands should implement `call`, which will `pass` or `fail` the service based on input. Commands return a `Slayer::Result` which has a predictable interface for determining `passed?` or `failed?`, a 'value' payload object, a 'status' value, and a user presentable `message`.
 
 ```ruby
 # A Command that passes when given the string "foo"
@@ -58,10 +54,10 @@ Slayer Commands should implement `call`, which will `pass` or `fail` the service
 class FooCommand < Slayer::Command
   def call(foo:)
     unless foo == "foo"
-      flunk! value: foo, message: "Argument must be foo!"
+      return err value: foo, message: "Argument must be foo!"
     end
 
-    pass! value: foo
+    ok value: foo
   end
 end
 ```
@@ -70,11 +66,11 @@ Handling the results of a command can be done in two ways. The primary way is th
 
 ```ruby
 FooCommand.call(foo: "foo") do |m|
-  m.pass do |result|
+  m.ok do |value|
     puts "This code runs on success"
   end
 
-  m.fail do |result|
+  m.err do |_value, result|
     puts "This code runs on failure. Message: #{result.message}"
   end
 
@@ -92,10 +88,10 @@ The second is less comprehensive, but can be useful for very simple commands. Th
 
 ```ruby
 result = FooCommand.call(foo: "foo")
-puts result.success? # => true
+puts result.ok? # => true
 
 result = FooCommand.call(foo: "bar")
-puts result.success? # => false
+puts result.ok? # => false
 ```
 
 Here's a more complex example demonstrating how the command pattern can be used to encapuslate the logic for validating and creating a new user. This example is shown using a `rails` controller, but the same approach can be used regardless of the framework.
@@ -105,7 +101,7 @@ Here's a more complex example demonstrating how the command pattern can be used
 class CreateUserCommand < Slayer::Command
   def call(create_user_form:)
     unless arguments_valid?(create_user_form)
-      flunk! value: create_user_form, status: :arguments_invalid
+      return err value: create_user_form, status: :arguments_invalid
     end
 
     user = nil
@@ -114,10 +110,10 @@ class CreateUserCommand < Slayer::Command
     end
 
     unless user.persisted?
-      flunk! message: I18n.t('user.create.error'), status: :unprocessible_entity
+      return err message: I18n.t('user.create.error'), status: :unprocessible_entity
     end
 
-    pass! value: user
+    ok value: user
   end
 
   def arguments_valid?(create_user_form)
@@ -133,17 +129,17 @@ class UsersController < ApplicationController
     @create_user_form = CreateUserForm.from_params(create_user_params)
 
     CreateUserCommand.call(create_user_form: @create_user_form) do |m|
-      m.pass do |user|
+      m.ok do |user|
         auto_login(user)
         redirect_to root_path, notice: t('user.create.success')
       end
 
-      m.fail(:arguments_invalid) do |result|
+      m.err(:arguments_invalid) do |_user, result|
         flash[:error] = result.errors.full_messages.to_sentence
         render :new, status: :unprocessible_entity
       end
 
-      m.fail do |result|
+      m.err do |_user, result|
         flash[:error] = t('user.create.error')
         render :new, status: :bad_request
       end
@@ -167,24 +163,24 @@ end
 
 The result matcher is an object that is used to handle `Slayer::Result` objects based on their status.
 
-#### Handlers: `pass`, `fail`, `all`, `ensure`
+#### Handlers: `ok`, `err`, `all`, `ensure`
 
-The result matcher block can take 4 types of handler blocks: `pass`, `fail`, `all`, and `ensure`. They operate as you would expect based on their names.
+The result matcher block can take 4 types of handler blocks: `ok`, `err`, `all`, and `ensure`. They operate as you would expect based on their names.
 
-* The `pass` block runs if the command was successful.
-* The `fail` block runs if the command was `flunked`.
-* The `all` block runs on any type of result --- `pass` or `fail` --- unless the result has already been handled.
+* The `ok` block runs if the command was successful.
+* The `err` block runs if the command was `koed`.
+* The `all` block runs on any type of result --- `ok` or `err` --- unless the result has already been handled.
 * The `ensure` block always runs after the result has been handled.
 
 #### Handler Params
 
-Every handler in the result matcher block is given three arguments: `value`, `result`, and `command`. These encapsulate the `value` provided in the `pass!` or `flunk!` call from the `Command`, the returned `Slayer::Result` object, and the `Slayer::Command` instance that was just run:
+Every handler in the result matcher block is given three arguments: `value`, `result`, and `command`. These encapsulate the `value` provided in the `ok` or `return err` call from the `Command`, the returned `Slayer::Result` object, and the `Slayer::Command` instance that was just run:
 
 ```ruby
 class NoArgCommand < Slayer::Command
   def call
     @instance_var = 'instance'
-    pass value: 'pass'
+    ok value: 'pass'
   end
 end
 
@@ -192,42 +188,39 @@ end
 NoArgCommand.call do |m|
   m.all do |value, result, command|
     puts value # => 'pass'
-    puts result.success? # => true
+    puts result.ok? # => true
     puts command.instance_var # => 'instance'
   end
-endpoint
+end
 ```
 
 #### Statuses
 
-You can pass a `status` flag to both the `pass!` and `flunk!` methods that allows the result matcher to process different kinds of successes and failures differently:
+You can pass a `status` flag to both the `ok` and `return err` methods that allows the result matcher to process different kinds of successes and failures differently:
 
 ```ruby
 class StatusCommand < Slayer::Command
   def call
-    flunk! message: "Generic flunk"
-    flunk! message: "Specific flunk", status: :specific_flunk
-    flunk! message: "Extra specific flunk", status: :extra_specific_flunk
+    return err message: "Extra specific ko", status: :extra_specific_err if extra_specific_err?
+    return err message: "Specific ko", status: :specific_err if specific_err?
+    return err message: "Generic ko" if generic_err?
+
+    return ok message: "Specific pass", status: :specific_pass if specific_pass?
 
-    pass! message: "Generic pass"
-    pass! message: "Specific pass", status: :specific_pass
+    ok message: "Generic pass"
   end
 end
 
 StatusCommand.call do |m|
-  m.fail                        { puts "generic fail" }
-  m.fail(:specific_flunk)       { puts "specific flunk" }
-  m.fail(:extra_specific_flunk) { puts "extra specific flunk" }
+  m.err                         { puts "generic err" }
+  m.err(:specific_err)          { puts "specific err" }
+  m.err(:extra_specific_err)    { puts "extra specific err" }
 
-  m.pass                        { puts "generic pass" }
-  m.pass(:specific_pass)        { puts "specific pass" }
+  m.ok                          { puts "generic pass" }
+  m.ok(:specific_pass)          { puts "specific pass" }
 end
 ```
 
-### Forms
-
-### Services
-
 ## RSpec & Minitest Integrations
 
 `Slayer` provides assertions and matchers that make testing your `Commands` simpler.
@@ -283,12 +276,12 @@ class MinitestCommandTest < Minitest::Test
     @failed_result = MinitestCommand.call(should_pass: false)
   end
 
-  def test_is_success
+  def test_is_ok
     assert_success @success_result, status: :no_status, message: 'message', value: 'value'
     refute_failed @success_result, status: :no_status, message: 'message', value: 'value'
   end
 
-  def test_is_failed
+  def test_is_err
     assert_failed @failed_result, status: :no_status, message: 'message', value: 'value'
     refute_success @failed_result, status: :no_status, message: 'message', value: 'value'
   end
@@ -366,12 +359,11 @@ end
 
 ### Generators
 
-Use generators to make sure your `Slayer` objects are always in the right place. `slayer_rails` includes generators for `Slayer::Form`, `Slayer::Command`, and `Slayer::Service` objects.
+Use generators to make sure your `Slayer` objects are always in the right place. `slayer_rails` includes generators for `Slayer::Form` and `Slayer::Command`.
 
 ```sh
 $ bin/rails g slayer:form foo_form
 $ bin/rails g slayer:command foo_command
-$ bin/rails g slayer:service foo_service
 ```
 
 ## Development

data/Rakefile

@@ -3,15 +3,4 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-if defined? Chandler
-  # Set Chandler options
-  Chandler::Tasks.configure do |config|
-    config.changelog_path = 'CHANGELOG.md'
-    config.github_repository = 'apsislabs/slayer'
-  end
-
-  # Add chandler as a prerequisite for `rake release`
-  task 'release:rubygem_push' => 'chandler:push'
-end
-
 task default: :spec

data/lib/slayer/command.rb

@@ -1,21 +1,78 @@
 module Slayer
-  class Command < Service
-    singleton_skip_hook :call
-
+  class Command
     class << self
       def call(*args, &block)
-        self.new.call(*args, &block)
+        instance = self.new
+
+        begin
+          res = instance.call(*args, &block)
+        rescue ResultFailureError => e
+          res = e.result
+        end
+
+        raise CommandNotImplementedError unless res.is_a? Result
+
+        handle_match(res, instance, block) if block_given?
+        return res
+      end
+      ruby2_keywords :call if respond_to?(:ruby2_keywords, true)
+
+      def ok(value: nil, status: :default, message: nil)
+        Result.new(value, status, message)
+      end
+
+      def err(value: nil, status: :default, message: nil)
+        ok(value: value, status: status, message: message).fail
+      end
+
+      def err!(value: nil, status: :default, message: nil)
+        warn '[DEPRECATION] `err!` is deprecated.  Please use `return err` instead.'
+        raise ResultFailureError, err(value: value, status: status, message: message)
       end
 
       private
 
-      def inherited(klass)
-        super(klass)
-        klass.wrap_service_methods!
-        klass.only_hook :call
+      def handle_match(res, instance, block)
+        matcher = Slayer::ResultMatcher.new(res, instance)
+
+        block.call(matcher)
+
+        # raise error if not all defaults were handled
+        unless matcher.handled_defaults?
+          raise(ResultNotHandledError, 'The pass or fail condition of a result was not handled')
+        end
+
+        begin
+          matcher.execute_matching_block
+        ensure
+          matcher.execute_ensure_block
+        end
       end
     end
 
+    def ok(*args)
+      self.class.ok(*args)
+    end
+    ruby2_keywords :ok if respond_to?(:ruby2_keywords, true)
+
+    def err(*args)
+      self.class.err(*args)
+    end
+    ruby2_keywords :err if respond_to?(:ruby2_keywords, true)
+
+    def err!(*args)
+      self.class.err!(*args)
+    end
+    ruby2_keywords :err! if respond_to?(:ruby2_keywords, true)
+
+    def try!(value: nil, status: nil, message: nil)
+      r = yield
+      err!(value: value, status: status || :default, message: message) unless r.is_a?(Result)
+      return r.value if r.ok?
+
+      err!(value: value || r.value, status: status || r.status, message: message || r.message)
+    end
+
     def call
       raise NotImplementedError, 'Commands must define method `#call`.'
     end

data/lib/slayer/compat/compat_040.rb

@@ -0,0 +1,64 @@
+# :nocov:
+require 'minitest/assertions'
+require 'rspec/expectations'
+
+module Slayer
+  class Command
+    class << self
+      def pass(value: nil, status: :default, message: nil)
+        warn '[DEPRECATION] `pass` is deprecated.  Please use `ok` instead.'
+        ok(value: value, status: status, message: message)
+      end
+
+      def flunk(value: nil, status: :default, message: nil)
+        warn '[DEPRECATION] `flunk` is deprecated.  Please use `err` instead.'
+        err(value: value, status: status, message: message)
+      end
+
+      def flunk!(value: nil, status: :default, message: nil)
+        warn '[DEPRECATION] `flunk!` is deprecated.  Please use `return err` instead.'
+        err!(value: value, status: status, message: message)
+      end
+    end
+
+    alias pass ok
+    alias flunk err
+    alias flunk! err!
+  end
+
+  class Result
+    def success?
+      warn '[DEPRECATION] `success?` is deprecated.  Please use `ok?` instead.'
+      ok?
+    end
+
+    def failure?
+      warn '[DEPRECATION] `failure?` is deprecated.  Please use `err?` instead.'
+      err?
+    end
+  end
+
+  class ResultMatcher
+    def pass(...)
+      warn '[DEPRECATION] `pass` is deprecated.  Please use `ok` instead.'
+      ok(...)
+    end
+
+    def fail(...)
+      warn '[DEPRECATION] `fail` is deprecated.  Please use `err` instead.'
+      err(...)
+    end
+  end
+end
+
+module Minitest::Assertions
+  alias assert_success assert_ok
+  alias refute_failed assert_ok
+  alias assert_failed refute_ok
+  alias refute_success refute_ok
+end
+
+RSpec::Matchers.alias_matcher :be_failed_result, :be_err_result
+RSpec::Matchers.alias_matcher :be_success_result, :be_ok_result
+
+# :nocov:

data/lib/slayer/cops/return_matcher.rb

@@ -0,0 +1,45 @@
+require 'rubocop'
+
+module Slayer
+  class CommandReturn < RuboCop::Cop::Base
+    def_node_search :explicit_returns, 'return'
+    def_node_matcher :slayer_command?, '(class (const (const nil :Slayer) :Command) _)'
+    def_node_matcher :is_call_to_pass?, '(send nil :pass ?)'
+    def_node_matcher :is_call_to_flunk?, '(send nil :flunk! ?)'
+
+    def on_def(node)
+      return unless node.method?(:call)
+      return unless in_slayer_command?(node)
+
+      explicit_returns(node) do |n|
+        validate_return! n.child_nodes.first, n
+      end
+
+      # Temporarily does not look at implicit returns
+      #
+      # implicit_returns(node) do |node|
+      #   validate_return! node
+      # end
+    end
+
+    private
+
+    # Continue traversing `node` until you get to the last expression.
+    # If that expression is a call to `.can_see?`, then add an offense.
+    def implicit_returns(_node)
+      raise 'Not Implemented Yet'
+    end
+
+    def in_slayer_command?(node)
+      node.ancestors.any?(&:slayer_command?)
+    end
+
+    def validate_return!(node, return_node = nil)
+      return if is_call_to_pass? node
+      return if is_call_to_flunk? node
+
+      add_offense(return_node || node,
+                  message: 'call in Slayer::Command must return the result of `pass` or call `flunk!`')
+    end
+  end
+end

data/lib/slayer/minitest.rb

@@ -1,10 +1,9 @@
 # :nocov:
 require 'minitest/assertions'
-# rubocop:disable Style/Documentation
 # rubocop:disable Metrics/MethodLength
 module Minitest::Assertions
-  def assert_success(result, status: nil, message: nil, value: nil)
-    assert result.success?, 'Expected command to succeed.'
+  def assert_ok(result, status: nil, message: nil, value: nil)
+    assert result.ok?, 'Expected command to succeed.'
 
     unless status.nil?
       assert_equal(
@@ -30,10 +29,10 @@ module Minitest::Assertions
       )
     end
   end
-  alias refute_failed assert_success
+  alias refute_err assert_ok
 
-  def refute_success(result, status: nil, message: nil, value: nil)
-    refute result.success?, 'Expected command to fail.'
+  def refute_ok(result, status: nil, message: nil, value: nil)
+    refute result.ok?, 'Expected command to fail.'
 
     unless status.nil?
       refute_equal(
@@ -59,7 +58,7 @@ module Minitest::Assertions
       )
     end
   end
-  alias assert_failed refute_success
+  alias assert_err refute_ok
 end
 # rubocop:enable Style/Documentation
 # rubocop:enable Metrics/MethodLength

data/lib/slayer/result.rb

@@ -8,16 +8,16 @@ module Slayer
       @message = message
     end
 
-    def success?
-      !failure?
+    def ok?
+      !err?
     end
 
-    def failure?
-      @failure ||= false
+    def err?
+      @err ||= false
     end
 
     def fail
-      @failure ||= true
+      @err ||= true
       self
     end
   end