typed_operation 1.0.0.pre2 → 1.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1337560f2bffbfd45574c1df5f007c951dba43293324c309c3409aab18e57f0c
-  data.tar.gz: 63deedbca3cde1fadb88668af46ec21652e17f9600d23c0e13c8b22429c05e0c
+  metadata.gz: c16e335815316d0cc264b143755c63556fa1a016403198e83aeeeeb067307d4a
+  data.tar.gz: ddd2475fd3bb2898245b9430136dd881b3ef52fe92abbd7ffe4230e243398aad
 SHA512:
-  metadata.gz: 0a8fdc89c772282de6c654365e18d7397532b84aebd738285499998c04c32906dc1e63961f5b47d139dfff532a458461dbe07a29bdfcda9f29d8132d645599df
-  data.tar.gz: cee03eb2c1e2d9100e657d98a1b70f6889b0e276251dd839f343586ff89f17287853224a487357343fc421ff6723686a2bf672c7ad53a058246668bb1d80a926
+  metadata.gz: 1134e7f162febf03703dc2b36a60f799779a9170f6bf75888df7ffe58245b73b3f66b3b434509d0444537ed818c7eb5d3946df61cbe0cf485e4cd02b4bdbc2de
+  data.tar.gz: 1ceee6f8f37b538cf25b9011e188c79d49be4618f23b12b314fbb4295affffbf25173d61dcbfebf20589c2aad2a85a8531636adf3e4870286ab8b790351322d7

data/README.md

@@ -49,16 +49,28 @@ class ShelveBookOperation < ::TypedOperation::Base
 
   named_param :category, String, default: "unknown".freeze
 
-  # to setup (optional)
+  # optional hook called when the operation is initialized, and after the parameters have been set
   def prepare
     raise ArgumentError, "ISBN is invalid" unless valid_isbn?
   end
 
-  # The 'work' of the operation
-  def call
+  # optionally hook in before execution ... and call super to allow subclasses to hook in too
+  def before_execute_operation
+    # ...
+    super
+  end
+
+  # The 'work' of the operation, this is the main body of the operation and must be implemented
+  def perform
     "Put away '#{title}' by author ID #{author_id}#{shelf_code ? " on shelf #{shelf_code}" : "" }"
   end
 
+  # optionally hook in after execution ... and call super to allow subclasses to hook in too
+  def after_execute_operation(result)
+    # ...
+    super
+  end
+  
   private
 
   def valid_isbn?
@@ -100,7 +112,7 @@ class TestOperation < ::TypedOperation::Base
   param :bar, String
   param :baz, String, &:to_s
 
-  def call = "It worked! (#{foo}, #{bar}, #{baz})"
+  def perform = "It worked! (#{foo}, #{bar}, #{baz})"
 end
 
 # Invoking the operation directly
@@ -162,12 +174,32 @@ Create an operation by subclassing `TypedOperation::Base` or `TypedOperation::Im
 - `TypedOperation::ImmutableBase` (uses `Literal::Data`) is the parent class for an operation where the arguments are immutable (frozen on initialization),
   thus giving a somewhat stronger immutability guarantee (ie that the operation does not mutate its arguments).
 
-The subclass must implement the `#call` method which is where the operations main work is done.
+The subclass must implement the `#perform` method which is where the operations main work is done.
 
 The operation can also implement:
 
 - `#prepare` - called when the operation is initialized, and after the parameters have been set
+- `#before_execute_operation` - optionally hook in before execution ... and call super to allow subclasses to hook in too
+- `#after_execute_operation` - optionally hook in after execution ... and call super to allow subclasses to hook in too
+  
+```ruby
+# optionally hook in before execution...
+def before_execute_operation
+  # Remember to call super
+  super
+end
+
+def perform
+  # ... implement me!
+end
 
+# optionally hook in after execution...
+def after_execute_operation(result)
+  # Remember to call super, note the result is passed in and the return value of this method is the result of the operation
+  # thus allowing you to modify the result if you wish
+  super
+end
+```
 
 ### Specifying parameters (using `.param`)
 
@@ -260,7 +292,7 @@ class MyOperation < ::TypedOperation::Base
   # Or alternatively => `param :name, String, positional: true` 
   positional_param :age, Integer, default: -> { 0 }
   
-  def call
+  def perform
     puts "Hello #{name} (#{age})"
   end
 end
@@ -291,7 +323,7 @@ class MyOperation < ::TypedOperation::Base
   # Or alternatively => `param :name, String` 
   named_param :age, Integer, default: -> { 0 }
   
-  def call
+  def perform
     puts "Hello #{name} (#{age})"
   end
 end
@@ -312,7 +344,7 @@ class MyOperation < ::TypedOperation::Base
   positional_param :name, String
   named_param :age, Integer, default: -> { 0 }
   
-  def call
+  def perform
     puts "Hello #{name} (#{age})"
   end
 end
@@ -403,9 +435,10 @@ An operation can be invoked by:
 
 - instantiating it with at least required params and then calling the `#call` method on the instance
 - once a partially applied operation has been prepared (all required parameters have been set), the call
-  method on TypedOperation::Prepared can be used to instantiate and call the operation.
+  method on `TypedOperation::Prepared` can be used to instantiate and call the operation.
 - once an operation is curried, the `#call` method on last TypedOperation::Curried in the chain will invoke the operation
 - calling `#call` on a partially applied operation and passing in any remaining required parameters
+- calling `#execute_operation` on an operation instance (this is the method that is called by `#call`)
 
 See the many examples in this document.
 
@@ -524,6 +557,26 @@ class ApplicationOperation < ::TypedOperation::Base
 end
 ```
 
+### Using with Action Policy (`action_policy` gem)
+
+Base you `ApplicationOperation` on the following:
+
+```ruby
+class ApplicationOperation < ::TypedOperation::Base
+  # ...
+  include ActionPolicy::Behaviour
+
+  # ...
+  
+  param :initiator, ::User
+  authorize :initiator
+  # Or
+  # param :initiator, optional(::User)
+  # authorize :initiator, through: {optional: true}
+  
+  # ...
+end
+```
 ### Using with `literal` monads
 
 You can use the `literal` gem to provide a `Result` type for your operations.
@@ -533,7 +586,7 @@ class MyOperation < ::TypedOperation::Base
   param :account_name, String
   param :owner, String
 
-  def call
+  def perform
     create_account.bind do |account|
       associate_owner(account).map { account }
     end
@@ -570,7 +623,7 @@ class MyOperation < ::TypedOperation::Base
   param :account_name, String
   param :owner, ::Owner
   
-  def call
+  def perform
     account = yield create_account(account_name)
     yield associate_owner(account, owner)
 

data/lib/generators/templates/operation.rb

@@ -14,7 +14,7 @@ module <%= namespace_name %>
       # Prepare...
     end
 
-    def call
+    def perform
       # Perform...
       "Hello World!"
     end
@@ -33,7 +33,7 @@ class <%= name %> < ::ApplicationOperation
     # Prepare...
   end
 
-  def call
+  def perform
     # Perform...
     "Hello World!"
   end

data/lib/typed_operation/base.rb

@@ -6,9 +6,10 @@ module TypedOperation
     extend Operations::Parameters
     extend Operations::PartialApplication
 
-    include Operations::Callable
     include Operations::Lifecycle
+    include Operations::Callable
     include Operations::Deconstruct
+    include Operations::Executable
 
     class << self
       def attribute(name, type, special = nil, reader: :public, writer: :public, positional: false, default: nil)

data/lib/typed_operation/immutable_base.rb

@@ -6,8 +6,9 @@ module TypedOperation
     extend Operations::Parameters
     extend Operations::PartialApplication
 
-    include Operations::Callable
     include Operations::Lifecycle
+    include Operations::Callable
     include Operations::Deconstruct
+    include Operations::Executable
   end
 end

data/lib/typed_operation/operations/attribute_builder.rb

@@ -17,13 +17,19 @@ module TypedOperation
       end
 
       def define(&converter)
+        # If nilable, then converter should not attempt to call the type converter block if the value is nil
+        coerce_by = if type_nilable? && converter
+          ->(v) { (v == Literal::Null || v.nil?) ? v : converter.call(v) }
+        else
+          converter
+        end
         @typed_operation.attribute(
           @name,
           @signature,
           default: default_value_for_literal,
           positional: @positional,
           reader: @reader,
-          &converter
+          &coerce_by
         )
       end
 

data/lib/typed_operation/operations/callable.rb

@@ -18,10 +18,6 @@ module TypedOperation
       end
 
       include CallableMethods
-
-      def call
-        raise InvalidOperationError, "You must implement #call"
-      end
     end
   end
 end

data/lib/typed_operation/operations/executable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TypedOperation
+  module Operations
+    module Executable
+      def call
+        execute_operation
+      end
+
+      def execute_operation
+        before_execute_operation
+        retval = perform
+        after_execute_operation(retval)
+      end
+
+      def before_execute_operation
+        # noop
+      end
+
+      def after_execute_operation(retval)
+        retval
+      end
+
+      def perform
+        raise InvalidOperationError, "Operation #{self.class} does not implement #perform"
+      end
+    end
+  end
+end

data/lib/typed_operation/operations/lifecycle.rb

@@ -3,6 +3,7 @@
 module TypedOperation
   module Operations
     module Lifecycle
+      # This is called by Literal on initialization of underlying Struct/Data
       def after_initialization
         prepare if respond_to?(:prepare)
       end

data/lib/typed_operation/version.rb

@@ -1,3 +1,3 @@
 module TypedOperation
-  VERSION = "1.0.0.pre2"
+  VERSION = "1.0.0.pre3"
 end

data/lib/typed_operation.rb

@@ -13,6 +13,7 @@ require "typed_operation/operations/callable"
 require "typed_operation/operations/lifecycle"
 require "typed_operation/operations/deconstruct"
 require "typed_operation/operations/attribute_builder"
+require "typed_operation/operations/executable"
 require "typed_operation/curried"
 require "typed_operation/immutable_base"
 require "typed_operation/base"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typed_operation
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre2
+  version: 1.0.0.pre3
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-22 00:00:00.000000000 Z
+date: 2023-08-25 00:00:00.000000000 Z
 dependencies: []
 description: TypedOperation is a command pattern implementation where inputs can be
   defined with runtime type checks. Operations can be partially applied.
@@ -36,6 +36,7 @@ files:
 - lib/typed_operation/operations/attribute_builder.rb
 - lib/typed_operation/operations/callable.rb
 - lib/typed_operation/operations/deconstruct.rb
+- lib/typed_operation/operations/executable.rb
 - lib/typed_operation/operations/introspection.rb
 - lib/typed_operation/operations/lifecycle.rb
 - lib/typed_operation/operations/parameters.rb