interaktor 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be48f704b8d52c81c07e9708d1e90230ead270e4da3ddf74e8e4e6251e677978
-  data.tar.gz: '09e99c6f8129b44ff287aa9e8a742327cac3a232f13d7596ece9b428a575bc28'
+  metadata.gz: d187b41c956972596b434b05aa5e4b3f8558457953327e305c5d76165f7c195b
+  data.tar.gz: e123fbeb3e8c1db843cb41b54023ca71d077a6947f0a3a50e0ec5bd78dfd4ddb
 SHA512:
-  metadata.gz: ea1fe86854da930c537f9fb69864accdf8cb1948d8dacae4b64685ff88508964e99eb968826a12e5653791f492c1e8af6426b734838c5ac152c581dfee6399ba
-  data.tar.gz: 0d8c4406b6d3ee81f39c6adc56118ce4e204465743eed6dc5f342f3b3b5a9a03722f9b04ed48dab265ef9bfbcb54e047476245fdf000295b150e2a835f8087e6
+  metadata.gz: 5549218310ebd0e3d0505eac4d43302f83c9508a0bee463f3a8c0f2042de5bfd25954aec67beae050a140606b14e75ce1e7ff8f0866726e5a24a09dd8071b4e6
+  data.tar.gz: a7eabf0b930c9efd51ec3407e119234d6a1d29aa3d88494bacde287cc0e3d67ae9882707d8636ddba7289c6889f536bcdbad22eebc47a8344b659828a0718f4b

data/.github/workflows/publish.yml

@@ -1,8 +1,9 @@
 name: Publish
 
 on:
+  # Manually publish
+  workflow_dispatch:
   push:
-    branches: [master]
     tags:
       - v*
 
@@ -12,11 +13,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Ruby
-        uses: actions/setup-ruby@v1
+        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.5.x
+          ruby-version: 3.2
 
       - name: Publish to RubyGems
         run: |

data/.github/workflows/tests.yml

@@ -7,10 +7,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu, macos]
-        ruby: [2.5, 2.6, 2.7, head, debug]
-    runs-on: ${{ matrix.os }}-latest
+        os: [ubuntu-latest, macos-latest]
+        ruby: [2.5, 2.6, 2.7, 3.0, head, debug]
+    runs-on: ${{ matrix.os }}
     continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    env:
+      BUNDLE_GEMFILE: "Gemfile.ci"
     steps:
       - uses: actions/checkout@v2
       - name: Set up Ruby
@@ -18,7 +20,5 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Install dependencies
-        run: bundle install
       - name: Run tests
         run: bundle exec rspec

data/.gitignore

@@ -4,6 +4,7 @@
 .config
 .yardoc
 Gemfile.lock
+Gemfile.ci.lock
 InstalledFiles
 _yardoc
 coverage
@@ -15,3 +16,5 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+spec/examples.txt
+/vendor

data/.ruby-version

@@ -1 +1 @@
-2.5.8
+3.1.3

data/Gemfile

@@ -2,12 +2,12 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "guard-rspec", require: false
 gem "rubocop"
 gem "rubocop-performance"
 gem "rubocop-rspec"
 gem "rufo", "~> 0.12.0"
 gem "solargraph"
-gem "guard-rspec", require: false
 
 group :test do
   gem "pry-byebug", platforms: [:mri]

data/Gemfile.ci

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rspec", "~> 3.9.0"
+gem "simplecov"

data/README.md

@@ -5,11 +5,11 @@
 
 **DISCLAIMER: Interaktor is under active development. Feel free to use it, but until 1.0 is released, any update could break compatibility with an older version.**
 
-**Interaktor** is a fork of [Interaktor by collectiveidea](https://github.com/collectiveidea/interaktor). While Interactor is still used by collectiveidea internally, communication and progress has been slow in adapting to pull requests and issues. This inactivity combined with my desire to dial back on the Interactor's inherent permissivity led me to fork it and create Interaktor.
+**Interaktor** is a fork of [Interactor by collectiveidea](https://github.com/collectiveidea/interactor). While Interactor is still used by collectiveidea internally, communication and progress has been slow in adapting to pull requests and issues. This inactivity combined with my desire to dial back on the Interactor's inherent permissivity led me to fork it and create Interaktor.
 
 Fundamentally, Interaktor is the same as Interactor, but with the following changes:
 
-- Required explicit definition of interaktor "attributes" which replaces the concept of the interaktor context. Attributes can be required or optional, and support options like default values.
+- Required explicit definition of interaktor "attributes" which replaces the concept of the interaktor context. Attributes are defined using a schema DSL provided by [dry-schema](https://github.com/dry-rb/dry-schema), which allows for complex validation, if desired.
 - The interaktor "context" is no longer a public-facing concept, all data/attribute accessors/setters are defined as attributes
 - Attributes passed to `#fail!` must be defined in advance
 - Interaktors support early-exit functionality through the use of `#success!`, which functions the same as `#fail!` in that you must define the required success attributes on the interaktor
@@ -34,15 +34,18 @@ Interaktors are used to encapsulate your application's [business logic](http://e
 
 Depending on its definition, an interaktor may require attributes to be passed in when it is invoked. These attributes contain everything the interaktor needs to do its work.
 
-You may define `required` or `optional` attributes.
+Attributes are defined using a schema DSL provided by the [dry-schema](https://github.com/dry-rb/dry-schema) gem. It allows the construction of schemas for validating attributes. The schema is typically provided as a block argument to the `input` class method as seen below.
+
+This example is an extremely simple case, and dry-schema supports highly complex schema validation, like type checking, nested hash data validation, and more. For more information on defining an attribute schema, please see the [dry-schema documentation website](https://dry-rb.org/gems/dry-schema). This link should take you to the latest version of dry-schema, but be sure to check that the version of dry-schema in your application bundle matches the documentation you are viewing.
 
 ```ruby
 class CreateUser
   include Interaktor
 
-  required :name
-
-  optional :email
+  input do
+    required(:name)
+    optional(:email)
+  end
 
   def call
     User.create!(
@@ -53,9 +56,12 @@ class CreateUser
 end
 
 CreateUser.call(name: "Foo Bar")
-
 ```
 
+`input` will also accept a `Dry::Schema::Params` object directly, if for some reason the schema needs to be constructed elsewhere.
+
+**A note about type checking**: Type checking is cool, but Ruby is a dynamic language, and Ruby developers tend to utilize the idea of [duck typing](https://en.wikipedia.org/wiki/Duck_typing). Forcing the attributes of an interaktor to be of a certain type in order to validate might sound like a good idea, but it can often cause problems in situations where you might like to use duck typing, for example, when using stubs in tests.
+
 #### Output attributes
 
 Based on the outcome of the interaktor's work, we can require certain attributes. In the example below, we must succeed with a `user_id` attribute, and if we fail, we must provide an `error_messages` attribute.
@@ -66,11 +72,17 @@ The use of `#success!` allows you to early-return from an interaktor's work. If
 class CreateUser
   include Interaktor
 
-  required :name
+  input do
+    required(:name).filled(:string)
+  end
 
-  success :user_id
+  success do
+    required(:user_id).value(:integer)
+  end
 
-  failure :error_messages
+  failure do
+    required(:error_messages).value(array[:string])
+  end
 
   def call
     user = User.new(name: name)
@@ -98,7 +110,7 @@ end
 
 Normally, however, these exceptions are not seen. In the recommended usage, the caller invokes the interaktor using the class method `.call`, then checks the `#success?` method of the returned object. This works because the `call` class method swallows exceptions. When unit testing an interaktor, if calling custom business logic methods directly and bypassing `call`, be aware that `fail!` will generate such exceptions.
 
-See _Interaktors in the controller_, below, for the recommended usage of `call` and `success?`.
+See _Interaktors in the controller_, below, for the recommended usage of `.call` and `#success?`.
 
 ### Hooks
 
@@ -235,13 +247,19 @@ A basic interaktor is a class that includes `Interaktor` and defines `call`.
 class AuthenticateUser
   include Interaktor
 
-  required :email
-  required :password
+  input do
+    required(:email).filled(:string)
+    required(:password).filled(:string)
+  end
 
-  success :user
-  success :token
+  success do
+    required(:user)
+    required(:token).filled(:string)
+  end
 
-  failure :message
+  failure do
+    required(:message).filled(:string)
+  end
 
   def call
     if user = User.authenticate(email, password)
@@ -263,7 +281,9 @@ An organizer is an important variation on the basic interaktor. Its single purpo
 class PlaceOrder
   include Interaktor::Organizer
 
-  required :order_params
+  input do
+    required(:order_params).filled(:hash)
+  end
 
   organize CreateOrder, ChargeCard, SendThankYou
 end
@@ -304,9 +324,13 @@ In addition, any interaktors that had already run are given the chance to undo t
 class CreateOrder
   include Interaktor
 
-  required :order_params
+  input do
+    required(:order_params).filled(:hash)
+  end
 
-  success :order
+  success do
+    required(:order)
+  end
 
   def call
     order = Order.create(order_params)
@@ -334,13 +358,19 @@ When written correctly, an interaktor is easy to test because it only _does_ one
 class AuthenticateUser
   include Interaktor
 
-  required :email
-  required :password
+  input do
+    required(:email).filled(:string)
+    required(:password).filled(:string)
+  end
 
-  success :user
-  success :token
+  success do
+    required(:user)
+    required(:token).filled(:string)
+  end
 
-  failure :message
+  failure do
+    required(:message).filled(:string)
+  end
 
   def call
     if user = User.authenticate(email, password)
@@ -406,12 +436,18 @@ It's a good idea to define your own interfaces to your models. Doing so makes it
 class AuthenticateUser
   include Interaktor
 
-  required :email
-  required :password
+  input do
+    required(:email).filled(:string)
+    required(:password).filled(:string)
+  end
 
-  success :user
+  success do
+    required(:user)
+  end
 
-  failure :message
+  failure do
+    required(:message).filled(:string)
+  end
 
   def call
     user = User.find_by(email: email)
@@ -515,4 +551,4 @@ This controller test will have to change very little during the life of the appl
 
 ### Rails
 
-Interactor provided [interactor-rails](https://github.com/collectiveidea/interactor-rails), which ensures `app/interactors` is included in your autoload paths, and provides generators for new interactors. I have no intention of maintaining generators but if someone feels strongly enough to submit a pull request to include the functionality in _this_ gem (not a separate Rails one) then I will be happy to take a look. Making sure `app/interactors` is included in your autoload paths is something I would like to do soon.
+Interactor provided [interactor-rails](https://github.com/collectiveidea/interactor-rails), which ensures `app/interactors` is included in your autoload paths, and provides generators for new interactors. I have no intention of maintaining generators but if someone feels strongly enough to submit a pull request to include the functionality in _this_ gem (not a separate Rails one) then I will be happy to take a look. Making sure `app/interaktors` is included in your autoload paths is something I would like to do soon.

data/interaktor.gemspec

@@ -1,9 +1,9 @@
 Gem::Specification.new do |spec|
   spec.name = "interaktor"
-  spec.version = "0.2.0"
+  spec.version = "0.4.0"
 
   spec.author = "Taylor Thurlow"
-  spec.email = "taylorthurlow@me.com"
+  spec.email = "thurlow@hey.com"
   spec.description = "A common interface for building service objects."
   spec.summary = "Simple service object implementation"
   spec.homepage = "https://github.com/taylorthurlow/interaktor"
@@ -13,6 +13,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.5"
   spec.require_path = "lib"
 
+  spec.add_runtime_dependency "dry-schema", "~> 1.0"
   spec.add_runtime_dependency "zeitwerk", "~> 2.0"
 
   spec.add_development_dependency "rake", "~> 13.0"