trailblazer-activity 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 642864a6553c58d2a746291414cc523eadb23fa3e661f100a6f556859fce88f5
-  data.tar.gz: 04b9cae767f24c32680b4a30cc0e6d1e23449f3ff9a3b665e4a6dbb000b3f35d
+  metadata.gz: b2666e0f5190759b775c83c2cd4d04c87d64b230e71e4921a01c6656fd27d5c8
+  data.tar.gz: b16fe2deab89048538e6351aabd5b274a55f378e0dc081ea3e3519586a2146be
 SHA512:
-  metadata.gz: cee010776ef741794a746dde08b8a691ed60494ad7664a9aa1c7aa136f0e3344031063c45275f81de5f53b61a10d17d050b8985ffdefa7a7522b8bf348e9ea91
-  data.tar.gz: 3716026cd5f591346757a3b22b40318e227e63a1b206f5cd93f2c7666e9231c7ba6a6913f6a5a8baaf5a2013f2a192033dff13b140e1fae67a9dfbc9e4285ed1
+  metadata.gz: 3c100c03b31cd3abf3d8c60b16d6e710202c9503e74aadd2f70d8c41ae33a48fcc92b86e862e58c0609fdcb9169ab1dcd3e4a08aa933a78412b397dccbd49591
+  data.tar.gz: 73a7aa9fec238f54c07b888038e252948fa3c4db76183b37f6848421c53e3c2a31aab4bb235889517edc8ec4d3b055d1855c475811a4bf692d9653776d9979f1

data/CHANGES.md

@@ -1,3 +1,8 @@
+# 0.4.1
+
+* Remove `decompose` and replace it with a better `to_h`.
+* `End` doesn't have a redundant `@name` anymore but only a semantic.
+
 # 0.4.0
 
 * We now use the "Module Subclass" pattern, and activities aren't classes anymore but modules.

data/README.md

@@ -1,109 +1,79 @@
 # Activity
 
-An _activity_ is a collection of connected _tasks_ with one _start event_ and one (or many) _end_ events.
+The `activity` gem brings a light-weight DSL to define business processes, and the runtime logic to run those activities.
 
-## Installation
+A process is a set of arbitrary pieces of logic you define, chained together and put into a meaningful context by an activity. Activity lets you focus on the implementation of steps while Trailblazer takes care of the control flow.
 
-To use activities you need one gem, only.
+Please find the [full documentation on the Trailblazer website](http://trailblazer.to/2.1/activity). [Note that the docs are WIP.]
 
-```ruby
-gem "trailblazer-activity"
-```
-
-## Overview
-
-> Since TRB 2.1, we use [BPMN](http://www.bpmn.org/) lingo and concepts for describing workflows and processes.
-
-An activity is a workflow that contains one or several tasks. It is the main concept to organize control flow in Trailblazer.
-
-The following diagram illustrates an exemplary workflow where a user writes and publishes a blog post.
-
-<img src="http://trb.to/images/diagrams/blog-bpmn1.png">
-
-After writing and spell-checking, the author has the chance to publish the post or, in case of typos, go back, correct, and go through the same flow, again. Note that there's only a handful of defined transistions, or connections. An author, for example, is not allowed to jump from "correct" into "publish" without going through the check.
-
-The `activity` gem allows you to define this *activity* and takes care of implementing the control flow, running the activity and making sure no invalid paths are taken.
-
-Your job is solely to implement the tasks and deciders put into this activity - Trailblazer makes sure it is executed it in the right order, and so on.
-
-To eventually run this activity, three things have to be done.
-
-1. The activity needs be defined. Easiest is to use the [Activity.from_hash builder](#activity-fromhash).
-2. It's the programmer's job (that's you!) to implement the actual tasks (the "boxes"). Use [tasks for that](#task).
-3. After defining and implementing, you can run the activity with any data [by `call`ing it](#activity-call).
-
-## Operation vs. Activity
+## Example
 
-An `Activity` allows to define and maintain a graph, that at runtime will be used as a "circuit". Or, in other words, it defines the boxes, circles, arrows and signals between them, and makes sure when running the activity, the circuit with your rules will be executed.
-
-Please note that an `Operation` simply provides a neat DSL for creating an `Activity` with a railway-oriented wiring (left and right track). An operation _always_ maintains an activity internally.
+The `activity` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example what a railway activity could look like, along with some more complex connections.
 
 ```ruby
-class Create < Trailblazer::Operation
-  step :exists?, pass_fast: true
-  step :policy
-  step :validate
-  fail :log_err
-  step :persist
-  fail :log_db_err
-  step :notify
+module Memo::Update
+  extend Trailblazer::Activity::Railway()
+  module_function
+
+  # here goes your business logic
+  #
+  def find_model(ctx, id:, **)
+    ctx[:model] = Memo.find_by(id: id)
+  end
+
+  def validate(ctx, params:, **)
+    return true if params[:body].is_a?(String) && params[:body].size > 10
+    ctx[:errors] = "body not long enough"
+    false
+  end
+
+  def save(ctx, model:, params:, **)
+    model.update_attributes(params)
+  end
+
+  def log_error(ctx, params:, **)
+    ctx[:log] = "Some idiot wrote #{params.inspect}"
+  end
+
+  # here comes the DSL describing the layout of the activity
+  #
+  step method(:find_model)
+  step method(:validate), Output(:failure) => End(:validation_error)
+  step method(:save)
+  fail method(:log_error)
 end
 ```
 
-Check the operation above. The DSL to create the activity with its graph is very different to `Activity`, but the outcome is a simple activity instance.
-
-<img src="http://trb.to/images/graph/op-vs-activity.png">
-
-When `call`ing an operation, several transformations on the arguments are applied, and those are passed to the `Activity#call` invocation. After the activity finished, its output is transformed into a `Result` object.
-
-## Activity
+Visually, this would translate to the following circuit.
 
-To understand how an activity works and what it performs in your application logic, it's easiest to see how activities are defined, and used.
+<img src="http://trailblazer.to/images/2.1/activity-readme-example.png">
 
-## Activity: From_Hash
-
-Instead of using an operation, you can manually define activities by using the `Activity.from_hash` builder.
+You can run the activity by invoking its `call` method.
 
 ```ruby
-activity = Activity.from_hash do |start, _end|
-  {
-    start            => { Trailblazer::Activity::Right => Blog::Write },
-    Blog::Write      => { Trailblazer::Activity::Right => Blog::SpellCheck },
-    Blog::SpellCheck => { Trailblazer::Activity::Right => Blog::Publish,
-                          Trailblazer::Activity::Left => Blog::Correct },
-    Blog::Correct    => { Trailblazer::Activity::Right => Blog::SpellCheck },
-    Blog::Publish    => { Trailblazer::Activity::Right => _end }
-  }
-end
-```
+ctx = { id: 1, params: { body: "Awesome!" } }
 
+signal, (ctx, *) = Update.( [ctx, {}] )
 
-The block yields a generic start and end event instance. You then connect every _task_ in that hash (hash keys) to another task or event via the emitted _signal_.
+pp ctx #=>
+{:id=>1,
+ :params=>{:body=>"Awesome!"},
+ :model=>#<Memo body=nil>,
+ :errors=>"body not long enough"}
 
-## Activity: Call
-
-To run the activity, you want to `call` it.
-
-```ruby
-my_options = {}
-last_signal, options, flow_options, _ = activity.( nil, my_options, {} )
+pp signal #=> #<struct Trailblazer::Activity::End semantic=:validation_error>
 ```
 
-1. The `start` event is `call`ed and per default returns the generic _signal_`Trailblazer::Activity::Right`.
-2. This emitted (or returned) signal is connected to the next task `Blog::Write`, which is now `call`ed.
-3. `Blog::Write` emits another `Right` signal that leads to `Blog::SpellCheck` being `call`ed.
-4. `Blog::SpellCheck` defines two outgoing signals and hence can decide what next task to call by emitting either `Right` if the spell check was ok, or `Left` if the post contains typos.
-5. ...and so on.
-
-<img src="http://trb.to/images/graph/blogpost-activity.png">
-
-Visualizing an activity as a graph makes it very straight-forward to understanding the mechanics of the flow.
-
+With Activity, modeling business processes turns out to be ridiculously simple: You define what should happen and when, and Trailblazer makes sure _that_ it happens.
 
-Note how signals translate to edges (or connections) in the graph, and tasks become vertices (or nodes).
+## Features
 
-The return values are the `last_signal`, which is usually the end event (they return themselves as a signal), the last `options` that usually contains all kinds of data from running the activity, and additional args.
+* Activities can model any process with arbitrary flow and connections.
+* Nesting and compositions are allowed and encouraged.
+* Different step interfaces, manual processing of DSL options, etc is all possible.
+* Steps can be any kind of callable objects.
+* Tracing!
 
-## More
+## Operation
 
-The [full documentation](http://trb.to/gems/activity/0.2/api.html) for this gem and many more interesting things can be found on the Trailblazer website.
+Trailblazer's [`Operation`](http://trailblazer.to/2.1/operation) internally uses an activity to model the processes.

data/Rakefile

@@ -5,7 +5,7 @@ require "rubocop/rake_task"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList['test/dsl/*_test.rb', 'test/wrap/*_test.rb', "test/*_test.rb"]
+  t.test_files = FileList["**/*_test.rb"]
 end
 
 RuboCop::RakeTask.new

data/lib/trailblazer/activity/dsl/helper.rb

@@ -24,11 +24,11 @@ module Trailblazer
         Activity.Output(signal, semantic)
       end
 
-      def End(name, semantic)
-        Activity.End(name, semantic)
+      def End(semantic)
+        Activity.End(semantic)
       end
 
-      def Path(normalizer, track_color: "track_#{rand}", end_semantic: :success, **options)
+      def Path(normalizer, track_color: "track_#{rand}", end_semantic: track_color, **options)
         options    = options.merge(track_color: track_color, end_semantic: end_semantic)
 
         # Build an anonymous class which will be where the block is evaluated in.

data/lib/trailblazer/activity/implementation/interface.rb

@@ -1,16 +1,16 @@
 class Trailblazer::Activity < Module
   module Interface
     # @return [Process, Hash, Adds] Adds is private and should not be used in your application as it might get removed.
-    def decompose # TODO: test me
+    def to_h # TODO: test me
       @state.to_h
     end
 
     def debug # TODO: TEST ME
-      decompose[:debug]
+      to_h[:debug]
     end
 
     def outputs
-      decompose[:outputs]
+      to_h[:outputs]
     end
   end
 end

data/lib/trailblazer/activity/introspect.rb

@@ -16,15 +16,15 @@ module Trailblazer
 
       # @api private
       def self.find(activity, &block)
-        circuit = activity.decompose[:circuit]
+        circuit = activity.to_h[:circuit]
 
         circuit.instance_variable_get(:@map).find(&block)
       end
 
 
       def self.collect(activity, options={}, &block)
-        circuit         = activity.decompose[:circuit]
-        circuit_hash, _ = circuit.decompose
+        circuit      = activity.to_h[:circuit]
+        circuit_hash = circuit.to_h[:map]
 
         locals = circuit_hash.collect do |task, connections|
           [
@@ -39,7 +39,7 @@ module Trailblazer
 
 # render
       def self.Cct(circuit, **options)
-        circuit_hash( circuit.decompose[0], **options )
+        circuit_hash( circuit.to_h[:map], **options )
       end
 
       def self.circuit_hash(circuit_hash, show_ids:false)
@@ -59,7 +59,7 @@ module Trailblazer
       end
 
       def self.Ends(activity)
-        end_events = activity.decompose[1]
+        end_events = activity.to_h[:end_events]
         ends = end_events.collect { |evt| Task(evt) }.join(",")
         "[#{ends}]".gsub(/\d\d+/, "")
       end
@@ -74,9 +74,9 @@ module Trailblazer
         return task.inspect unless task.kind_of?(Trailblazer::Activity::End)
 
         class_name = strip(task.class)
-        name     = task.instance_variable_get(:@name)
-        semantic = task.instance_variable_get(:@options)[:semantic]
-        "#<#{class_name}:#{name}/#{semantic.inspect}>"
+        options    = task.to_h
+
+        "#<#{class_name}/#{options[:semantic].inspect}>"
       end
 
       def self.strip(string)

data/lib/trailblazer/activity/magnetic/builder/fast_track.rb

@@ -81,7 +81,7 @@ module Trailblazer
         end
 
         # Adds the End.fail_fast and End.pass_fast end to the Railway sequence.
-        def self.InitialAdds(pass_fast_end: Activity.End("pass_fast", :pass_fast), fail_fast_end: Activity.End("fail_fast", :fail_fast), **builder_options)
+        def self.InitialAdds(pass_fast_end: Activity.End(:pass_fast), fail_fast_end: Activity.End(:fail_fast), **builder_options)
           path_adds = Railway.InitialAdds(**builder_options)
 
           ends =

data/lib/trailblazer/activity/magnetic/builder/path.rb

@@ -28,7 +28,7 @@ module Trailblazer
         end
 
         # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
-        def self.InitialAdds(track_color:raise, end_semantic:raise, default_plus_poles: self.default_plus_poles, track_end: Activity.End(track_color, end_semantic), **)
+        def self.InitialAdds(track_color:raise, end_semantic:raise, default_plus_poles: self.default_plus_poles, track_end: Activity.End(end_semantic), **)
 
           builder_options={ track_color: track_color, end_semantic: end_semantic }
 

data/lib/trailblazer/activity/magnetic/builder/railway.rb

@@ -31,7 +31,7 @@ module Trailblazer
 
         # Adds the End.failure end to the Path sequence.
         # @return [Adds] list of Adds instances that can be chained or added to an existing sequence.
-        def self.InitialAdds(failure_color:raise, failure_end: Activity.End(failure_color, :failure), **builder_options)
+        def self.InitialAdds(failure_color:raise, failure_end: Activity.End(failure_color), **builder_options)
           path_adds = Path.InitialAdds(**builder_options)
 
           end_adds = adds(

data/lib/trailblazer/activity/magnetic/dsl.rb

@@ -61,7 +61,7 @@ module Trailblazer
           elsif task.is_a?(Proc)
             start_color, activity = task.(block)
 
-            adds = activity.decompose[:adds]
+            adds = activity.to_h[:adds]
 
             [
               Polarization.new( output: output, color: start_color ),

data/lib/trailblazer/activity/state.rb

@@ -45,7 +45,7 @@ module Trailblazer
         def self.recompile_outputs(end_events)
           ary = end_events.collect do |evt|
             [
-              semantic = evt.instance_variable_get(:@options)[:semantic], # DISCUSS: better API here?
+              semantic = evt.to_h[:semantic],
               Activity::Output(evt, semantic)
             ]
           end

data/lib/trailblazer/activity/structures.rb

@@ -1,14 +1,15 @@
   module Trailblazer
     class Activity < Module     # End event is just another callable task.
+
       # Any instance of subclass of End will halt the circuit's execution when hit.
-      class End
-        def initialize(name, options={})
-          @name    = name
-          @options = options
-        end
 
+      # An End event is a simple structure typically found as the last task invoked
+      # in an activity. The special behavior is that it
+      # a) maintains a semantic that is used to further connect that very event
+      # b) its `End#call` method returns the end instance itself as the signal.
+      End = Struct.new(:semantic) do
         def call(*args)
-          [ self, *args ]
+          return self, *args
         end
       end
 
@@ -18,9 +19,9 @@
         end
       end
 
-      # Builder for Activity::End.
-      def self.End(name, semantic=name)
-        Activity::End.new(name, semantic: semantic)
+      # Builds an Activity::End instance.
+      def self.End(semantic)
+        Activity::End.new(semantic)
       end
 
       class Signal;         end

data/lib/trailblazer/activity/subprocess.rb

@@ -21,8 +21,8 @@ module Trailblazer
       end
 
       # @private
-      def decompose
-        @activity.decompose # TODO: test explicitly
+      def to_h
+        @activity.to_h # TODO: test explicitly
       end
 
       def debug

data/lib/trailblazer/activity/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Activity < Module
-    VERSION = "0.4.0"
+    VERSION = "0.4.1"
   end
 end

data/lib/trailblazer/circuit.rb

@@ -53,8 +53,8 @@ module Trailblazer
     end
 
     # Returns the circuit's components.
-    def decompose
-      return @map, @stop_events
+    def to_h
+      { map: @map, end_events: @stop_events }
     end
 
   private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-activity
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-23 00:00:00.000000000 Z
+date: 2018-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hirb