action_operation 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9472dfbb606def8319b09f68a32eb640f9fc2e1ecee0ef5ce32b19b3468cc7f1
-  data.tar.gz: fc055466ce4f942268fc94866237ce480576ab8ce040ef776b9812e84bb8e192
+  metadata.gz: f97e8fc036a03a7ff4b0fdab9e4316d2312ad17ae5cf1a1844dc1ceb7cf84ad1
+  data.tar.gz: e2e2b98a9c87a50b42acbe2b2d1cfa507a4972d2871f6e26ad5a938d5a28c464
 SHA512:
-  metadata.gz: 2437722d056461d7b88808c3f11dbf17551189e41f0dd8b03465aa0d95d4d27ba06c3aded9c1ca933916d8644ca01e3f086c1a47d9461ebbc02578d70f547143
-  data.tar.gz: 7ddfe5268976e50691c39929f4f8588eeb6262b19eddb9c1cd50cfa52612d464720cf1c987f7be6dba43cd761edf236f8b83ab724f73ad460e4315116cf46da6
+  metadata.gz: b0d55912ff981d7298d3c9ca0c24babeea983427af130714e808d8767913cfde985b9a5fd5cb611d2f87c9c0986f133daa6357dd5645d460d740ea4f29e44e42
+  data.tar.gz: 90dca03f785f51506abb76bdcda2a2448e1236de32957ab5e9592e2252c3f63f125eb83c7e4e17477619d534a06fcbeb07788e266182b1e2abadf32bd89a1eb1

data/README.md

@@ -5,7 +5,7 @@
   - [![Version](http://img.shields.io/gem/v/action_operation.svg?style=flat-square)](https://rubygems.org/gems/action_operation)
 
 
-A simple set of right-to-left operations, similar to many other gems out there.
+A simple set of right-to-left operations, similar to many other gems out there like [trailblazer operations](http://trailblazer.to/gems/operation/2.0/index.html).
 
 
 ## Using
@@ -25,50 +25,55 @@ class AddToCartOperation
   task :lock
   task :persist
   task :publish
-  error :notify, catch: ProductMissingFromCartItemError
-  error :reraise
+  catch :notify, exception: ProductMissingFromCartItemError
+  catch :reraise
 
-  state :check_for_missing_product do
+  schema :check_for_missing_product do
     field :cart_item, type: Types.Instance(CartItem)
   end
-  step :check_for_missing_product do |state|
+  def check_for_missing_product(state:)
     raise ProductMissingFromCartItemError if state.cart_item.product.nil?
   end
 
-  state :carbon_copy_cart_item do
+  schema :carbon_copy_cart_item do
     field :cart_item, type: Types.Instance(CartItem)
   end
-  step :carbon_copy_cart_item do |state|
+  def carbon_copy_cart_item(state:)
     state.cart_item.carbon_copy
   end
 
-  state :lock do
+  schema :lock do
     field :cart_item, type: Types.Instance(CartItem)
   end
-  step :lock do |state|
-    GlobalLock.(state.cart_item.owner, state.cart_item, expires_in: 15.minutes)
+  def lock(state:)
+    GlobalLock.(resource: state.cart_item, expires_in: 15.minutes)
   end
 
-  state :persist do
+  schema :persist do
     field :cart_item, type: Types.Instance(CartItem)
   end
-  step :persist do |state|
+  def persist(state:)
     CartItem.transaction do
       state.cart_item.save!
     end
 
-    fresh(current_account: state.cart_item.owner, cart_item: state.cart_item)
+    fresh(state: {current_account: state.cart_item.owner, cart_item: state.cart_item})
   end
 
-  state :publish do
+  schema :publish do
     field :cart_item, type: Types.Instance(CartItem)
     field :current_account, type: Types.Instance(Account)
   end
-  step :publish do |state|
-    CartItemPickedMessage.(subject: state.cart_item, to: state.current_account).via_pubsub.deliver_later!
+  def publish(state:)
+    CartItemPickedMessage.(
+      to: state.current_account,
+      subject: state.cart_item,
+      via: :pubsub,
+      deliver: :later
+    )
   end
 
-  step :notify do |exception|
+  def notify(exception:, **)
     Bugsnag.notify(exception)
   end
 end
@@ -85,16 +90,16 @@ class AddToCartOperation
   task :lock
   task :persist
   task :publish
-  error :notify, catch: ProductMissingFromCartItemError
-  error :reraise
+  catch :notify, exception: ProductMissingFromCartItemError
+  catch :reraise
 
   # ...
 end
 ```
 
-These are the steps our process will take. Each `task` call is *in the order it is listed*, which means that `check_for_missing_product` will happen before `carbon_copy_cart_item`. Each `error` is also *in the order it is listed*, but they only trigger when one of the `task` raises an exception. In this case, we only want to `notify` when there's something seriously wrong!
+These are the steps our process will take. Each `task` call is *in the order it is listed*, which means that `check_for_missing_product` will happen before `carbon_copy_cart_item`. Each `catch` is also *in the order it is listed*, but they only trigger when one of the `task` raises an exception. In this case, we only want to `notify` when there's something seriously wrong!
 
-Finally, before we leave, notice the `reraise` error step. This is built in to the operation layer so that you can easily pass the buck to whomever owns the action currently.
+Finally, before we leave notice the `reraise` error step. This is built in to the operation layer so that you can easily pass the buck to whomever owns the action currently.
 
 Okay, so on to our first step:
 
@@ -102,10 +107,10 @@ Okay, so on to our first step:
 class AddToCartOperation
   # ...
 
-  state :check_for_missing_product do
+  schema :check_for_missing_product do
     field :cart_item, type: Types.Instance(CartItem)
   end
-  step :check_for_missing_product do |state|
+  def check_for_missing_product(state:)
     raise ProductMissingFromCartItemError if state.cart_item.product.nil?
   end
 
@@ -113,66 +118,40 @@ class AddToCartOperation
 end
 ```
 
-There's two things we want to talk about there and the first is `state`. It defines the shape of the *immutable* state that the step will receive. We use [smart_params](https://github.com/krainboltgreene/smart_params.rb) which means each field is typed with [dry-types](https://github.com/dry-rb/dry-types). Read up on both of those libraries for more fine grained control over your data.
-
-Second is the `step` definition itself which provides a `state` object that is based on the schema defined above. You have four choices on what you can do in a `step`. You can:
+There's two things we want to talk about there and the first is `schema`. It defines the shape of the *immutable* state that the step will receive. We use [smart_params](https://github.com/krainboltgreene/smart_params.rb) which means each field is typed with [dry-types](https://github.com/dry-rb/dry-types). Read up on both of those libraries for more fine grained control over your data. Second is the step definition itself which provides a `state` object that is based on the schema by the same name. You have four choices on what you can do in a step. You can:
 
   - Return any value, which will simply proceed to the next step.
-  - Raise an exception, which will move you into the left track (that uses `error` steps)
+  - Raise an exception, which will move you into the left track (that uses `catch` steps)
   - Return a fresh state, which will be described below
   - Return a drift instruction, which will be described below
 
 ### Fresh State
 
-Sometimes you want to change the data that is passed around after a step is completed. To achieve this functionality we provide the `fresh()` function:
+Sometimes you want to pass different state to all steps after. We provide the `fresh()` function for this very purpose:
 
 ``` ruby
 class AddToCartOperation
   # ...
 
-  step :persist do |state|
+  schema :persist do
+    field :cart_item, type: Types.Instance(CartItem)
+  end
+  def persist(state:)
     CartItem.transaction do
       state.cart_item.save!
     end
 
-    fresh(current_account: state.cart_item.owner, cart_item: state.cart_item)
+    fresh(state: {current_account: state.cart_item.owner, cart_item: state.cart_item})
   end
 
   # ...
 end
 ```
 
-This is the only way to "change" the shape of the state.
-
-
-### Receivers
-
-Sometimes you need to share functionality across multiple operations. You can do this via modules and inheritance like normal or you can use our specialized interface:
-
-``` ruby
-class DocumentUploadOperation
-  include ActionOperation
-
-  task :upload_to_s3, receiver: S3UploadOperation
-end
-```
-
-This will give the `DocumentUploadOperation` a task that is on another operation! Sometimes that other task has a different name, so we also provide aliasing:
-
-``` ruby
-class DocumentUploadOperation
-  include ActionOperation
-
-  task :upload_to_s3, receiver: S3UploadOperation, :upload
-end
-```
-
-So when `DocumentUploadOperation` finally gets to the `upload_to_s3` task it's actually calling the `S3UploadOperation` task called `upload`. More on why this is useful in the next section.
-
 
 ### Drifting
 
-Alright, so lets say you have a business requirement to upload important documents to the cloud. You have multiple providers (S3, Azure, and DigitalOcean Spaces) and you want to make sure it gets pushed to at least one. Here's how you would write this:
+Alright, so lets say you have a business requirement to upload important documents to the cloud. You have multiple providers (S3, Azure, and DigitalOcean Spaces) and you want to make sure it gets pushed to at least one. First we define how to talk to S3:
 
 ``` ruby
 class S3UploadOperation
@@ -180,67 +159,86 @@ class S3UploadOperation
 
   task :upload
 
-  state :upload do
+  schema :upload do
     field :document, type: Types.Instance(Document)
   end
-  step :upload do |state|
-    fresh(document: state.document, location: S3.push(state.document))
+  def upload(state:)
+    fresh(state: {document: state.document, location: S3.push(state.document)})
   rescue StandardError => exception
     raise FailedUploadError
   end
 end
-
 ```
 
-``` ruby
-class DocumentUploadOperation
-  include ActionOperation
+Now we define the controlling operation:
 
-  task :upload_to_s3, receiver: S3UploadOperation, as: :upload
-  task :upload_to_azure, receiver: AzureUploadOperation, as: :upload, required: false
-  task :upload_to_spaces, receiver: SpacesUploadOperation, as: :upload, required: false
+``` ruby
+class DocumentUploadOperation < ApplicationOperation
+  task :upload_to_s3
+  task :upload_to_azure, required: false
+  task :upload_to_spaces, required: false
   task :publish
-  error :retry, catch: FailedUploadError
-  error :reraise
+  catch :retry, exception: FailedUploadError
+  catch :reraise
 
-  step :retry do |exception, _, step|
-    case step
-    when :upload_to_s3 then drift(to: :upload_to_azure)
-    when :upload_to_azure then drift(to: :upload_to_spaces)
-    end
+  schema :upload_to_s3 do
+    field :document, type: Types.Instance(Document)
+  end
+  def upload_to_s3(state:)
+    fresh(state: S3UploadOperation.(document: state.document))
   end
 
-  state :publish do
+  schema :upload_to_azure do
+    field :document, type: Types.Instance(Document)
+  end
+  def upload_to_azure(state:)
+    fresh(state: AzureUploadOperation.(document: state.document))
+  end
+
+  schema :upload_to_spaces do
+    field :document, type: Types.Instance(Document)
+  end
+  def upload_to_spaces(state:)
+    fresh(state: SpacesUploadOperation.(document: state.document))
+  end
+
+  schema :publish do
     field :document, type: Types.Instance(Document)
     field :location, type: Types::Strict::String
   end
-  step :publish do |state|
-    DocumentSuccessfullyUploadedMessage.(owner: state.document.owner, location: state.location).via_pubsub.deliver_later!
+  def publish(state:)
+    DocumentSuccessfullyUploadedMessage.(
+      to: state.document.owner,
+      subject: state.location,
+      via: :pubsub,
+      deliver: :later
+    )
+  end
+
+  def retry(exception:, step:, **)
+    case step.name
+    when :upload_to_s3 then drift(to: :upload_to_azure)
+    when :upload_to_azure then drift(to: :upload_to_spaces)
+    end
   end
 end
 ```
 
 So here's how this works:
 
-  1. First we call `upload_to_s3`, which actually talks to `S3UploadOperation/upload`, but for some reason this fails and gets caught by `failed_upload`, which bubbles up a specific exception that we catch with `DocumentUploadOperation/retry`
+  1. First we call `upload_to_s3` which talks to `S3UploadOperation`, but for some reason this fails which bubbles up a specific exception that we catch with `DocumentUploadOperation#retry`
   2. `retry` looks at the last known step and then drifts to `upload_to_azure`, which functions just like above.
   3. Then somehow we fail to upload to Azure, so we repeat and retry with DigitalOcean Spaces.
-  4. We fail to even upload that, which means the next error step gets called (`reraise`) giving control back to the owner of the operation
-
-
-However, if it finishes successfully we get to push a notification to the document owner in `finish`.
-
-
-### Understanding the design
+  4. We fail to even upload that, which means the next catch step gets called (`reraise()`) giving control back to the owner of the operation
 
-Each task is a map function wrapped in a HOC for handling the return data. The annotation of each task is `state -> mixed | state` and the HOC is `state -> (state -> mixed | state) -> state`. `error` is like a task, but instead: `exception -> mixed` wrapped in a HOC that matches `exception -> (exception -> mixed) -> exception`.
+However, if it finishes successfully we get to push a notification to the document owner in `publish()`.
 
 
 ## Installing
 
 Add this line to your application's Gemfile:
 
-    gem "action_operation", "1.1.0"
+    gem "action_operation", "2.0.0"
 
 And then execute:
 

data/lib/action_operation/error/missing_error.rb

@@ -1,13 +1,12 @@
 module ActionOperation
   class Error
     class MissingError < Error
-      def initialize(function)
-        @function = function
+      def initialize(step)
+        @step = step
       end
 
       def message
-        binding.pry
-        "expected to see #{@function.name} but the receiver (#{@function.receiver.name}) didn't support it"
+        "expected to see #{@step.name} but the receiver (#{@step.receiver.name}) didn't support it"
       end
     end
   end

data/lib/action_operation/error/missing_schema.rb

@@ -0,0 +1,13 @@
+module ActionOperation
+  class Error
+    class MissingSchema < Error
+      def initialize(step)
+        @step = step
+      end
+
+      def message
+        "expected to see #{@step.name} have a schema but the receiver (#{@step.receiver.name}) didn't support it"
+      end
+    end
+  end
+end

data/lib/action_operation/error/missing_task.rb

@@ -1,12 +1,12 @@
 module ActionOperation
   class Error
     class MissingTask < Error
-      def initialize(function)
-        @function = function
+      def initialize(step)
+        @step = step
       end
 
       def message
-        "expected to see #{function.name} but the receiver (#{function.receiver.name}) didn't support it"
+        "expected to see #{@step.name} but the receiver (#{@step.receiver.name}) didn't support it"
       end
     end
   end

data/lib/action_operation/error.rb

@@ -1,7 +1,7 @@
 module ActionOperation
   class Error < StandardError
     require_relative "error/missing_error"
-    require_relative "error/missing_schema_for_task"
+    require_relative "error/missing_schema"
     require_relative "error/missing_task"
   end
 end

data/lib/action_operation/version.rb

@@ -1,3 +1,3 @@
 module ActionOperation
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

data/lib/action_operation.rb

@@ -6,62 +6,63 @@ module ActionOperation
   extend ActiveSupport::Concern
 
   require_relative "action_operation/version"
-  require_relative "action_operation/types"
   require_relative "action_operation/error"
+  require_relative "action_operation/types"
 
   State = Struct.new(:raw)
   Drift = Struct.new(:to)
-
-  attr_reader :raw
-  attr_reader :state
-  attr_reader :step
+  Task = Struct.new(:name, :required)
+  Catch = Struct.new(:name, :exception)
 
   def initialize(raw:)
+    raise ArgumentError, "needs to be a Hash" unless raw.kind_of?(Hash)
+
     @raw = raw
   end
 
-  def call(forced: nil)
-    right.from(forced || 0).reduce(state || raw) do |state, function|
-      next state unless function.required || (forced && right.at(forced) == function)
-
-      # NOTE: We store this so we can go drift back if an error tells us to
-      @state = state
+  def call(start: nil, raw: @raw)
+    right.from(start || 0).reduce(raw) do |state, step|
+      next state unless step.required || (start && right.at(start) == step)
 
-      # NOTE: We store this so an error step can ask for the last ran step
-      @step = function.name
+      raise Error::MissingTask, step unless respond_to?(step.name)
+      raise Error::MissingSchema, step unless self.class.schemas.key?(step.name)
 
-      raise Error::MissingTask, function unless function.receiver.steps.key?(function.as)
-      raise Error::MissingSchemaForTask, function unless function.receiver.schemas.key?(function.as)
+      # NOTE: We only care about this so we can refernece it in the rescue
+      @latest_step = step
 
-      value = instance_exec(function.receiver.schemas.fetch(function.as).new(state), &function.receiver.steps.fetch(function.as))
+      value = public_send(step.name, state: self.class.schemas.fetch(step.name).new(state))
 
       case value
       when State then value.raw
-      when Drift then break call(forced: right.find_index { |step| step.name == value.to })
+      when Drift then break call(start: right.find_index { |step| step.name == value.to }, raw: raw)
       else state
       end
     end
-  rescue *left.select(&:catch).map(&:catch).uniq => handled_exception
+  rescue *left.select(&:exception).map(&:exception).uniq => handled_exception
     left.select do |failure|
-      failure.catch === handled_exception
-    end.reduce(handled_exception) do |exception, function|
-      raise Error::MissingError, function unless function.receiver.steps.key?(function.as)
+      failure.exception === handled_exception
+    end.reduce(handled_exception) do |exception, step|
+      raise Error::MissingError, step unless respond_to?(step.name)
 
-      value = instance_exec(exception, @state, @step, &function.receiver.steps.fetch(function.as))
+      value = public_send(step.name, exception: exception, state: self.class.schemas.fetch(@latest_step.name).new(raw), step: @latest_step)
 
       if value.kind_of?(Drift)
-        break call(forced: right.find_index { |step| step.name == value.to })
+        break call(start: right.find_index { |step| step.name == value.to }, raw: raw)
       else
         exception
       end
     end
   end
 
-  def fresh(raw)
-    State.new(raw)
+  def fresh(state:)
+    raise ArgumentError, "needs to be a Hash" unless state.kind_of?(Hash)
+
+    State.new(state)
   end
 
   def drift(to:)
+    raise ArgumentError, "needs to be a Symbol or String" unless to.kind_of?(Symbol) || to.kind_of?(String)
+
     Drift.new(to)
   end
 
@@ -73,22 +74,16 @@ module ActionOperation
     self.class.right
   end
 
-  included do
-    step :reraise do |exception|
-      raise exception
-    end
+  def reraise(exception:, **)
+    raise exception
   end
 
   class_methods do
-    def inherited(klass)
-      klass.class_eval do
-        step :reraise do |exception|
-          raise exception
-        end
-      end
+    def call(raw = {})
+      new(raw: raw).call
     end
 
-    def state(name, &structure)
+    def schema(name, &structure)
       schemas[name] = Class.new do
         include(SmartParams)
 
@@ -96,20 +91,12 @@ module ActionOperation
       end
     end
 
-    def task(name, receiver: self, as: name, required: true)
-      right.<<(OpenStruct.new({name: name, as: as, receiver: receiver || self, required: required}))
-    end
-
-    def error(name, receiver: self, catch: StandardError, as: name)
-      left.<<(OpenStruct.new({name: name, as: as, receiver: receiver || self, catch: catch || StandardError}))
+    def task(name, required: true)
+      right << Task.new(name, required)
     end
 
-    def step(name, &process)
-      steps[name] = process
-    end
-
-    def call(raw = {})
-      new(raw: raw).call
+    def catch(name, exception: StandardError)
+      left << Catch.new(name, exception)
     end
 
     def right
@@ -123,9 +110,5 @@ module ActionOperation
     def schemas
       @schemas ||= Hash.new
     end
-
-    def steps
-      @steps ||= Hash.new
-    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_operation
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Kurtis Rainbolt-Greene
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-01 00:00:00.000000000 Z
+date: 2018-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -138,7 +138,7 @@ files:
 - lib/action_operation.rb
 - lib/action_operation/error.rb
 - lib/action_operation/error/missing_error.rb
-- lib/action_operation/error/missing_schema_for_task.rb
+- lib/action_operation/error/missing_schema.rb
 - lib/action_operation/error/missing_task.rb
 - lib/action_operation/types.rb
 - lib/action_operation/version.rb

data/lib/action_operation/error/missing_schema_for_task.rb

@@ -1,13 +0,0 @@
-module ActionOperation
-  class Error
-    class MissingSchemaForTask < Error
-      def initialize(function)
-        @function = function
-      end
-
-      def message
-        "expected to see #{function.name} have a schema but the receiver (#{function.receiver.name}) didn't support it"
-      end
-    end
-  end
-end