trailblazer 2.0.7 → 2.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf6240c4f189a477366736fe061c493f08c6949b
-  data.tar.gz: 68b716f9d99c124fc6d86f1e471c21478d25c0ae
+  metadata.gz: c82134611daa3efe9309eebb4a283585b4095428
+  data.tar.gz: cc121cdb03c9ea4da12b9b2713150e50d18ebac9
 SHA512:
-  metadata.gz: 3ea12ffe486f4f9c50ac9a839cd3b6429a36c7e6be2c6dd889244f025d7dbe4b21b50b45f56378b77fdddba1c819cdaf81b204d32aed90ce606b846ba561aac8
-  data.tar.gz: 0cbc2fc6e6f3e3e38019cf3181373803fc0828a12799bd6239705f77786eafacc9d339e1c48f3939876aa93473a5a49ce1a5f50b2651d50f5a5489f9b59d0b8b
+  metadata.gz: 992b2af33d7b5de098b59c2eb9a75b6dd4854d0a580613b6938c6ae44f5ec2d048f4686cfecb23c4daf5673c78b24aa90286b50e5df24bc856134155f7e9d7f4
+  data.tar.gz: 96912060658256a931dec0a8951c61fb3bc1eb62521a4730a2458258f2e1e7c145adad129820c19149d578213c45c81673587f1f1afe16bec9c1a189ad32c914

data/CHANGES.md

@@ -1,3 +1,38 @@
+# 2.1
+
+* Macros now always have to provide an `:id`. This was a bit fuzzy in 2.0.
+
+* Nested
+  if Nested( Edit ), outputs will automatically be connected, see editor.
+* Wrap
+  dropped the `pipe` option. This is now `options, flow_options, *`
+  `false` is now automatically connected to End.failure.
+
+* `operation.new` step removed.
+* Undocumented step behavior removed. You can't write to `self` anymore.
+
+        ```ruby
+        step :process
+        def process(*)
+          self["x"] = true
+        end
+        ```
+
+    Always write to `options`.
+
+* self[] removed
+* Fixed `Guard` where procs could receive one argument, only. Guards follow the step interface: `Policy::Guard( ->(options, **) { .. } )
+* Removed `Operation::Callback` which was a poor idea and luckily no one was using it.
+
+TODO:
+document Task API and define step API
+deprecate step->(options) ?
+injectable, per-operation step arguments strategy?
+
+# 2.1.0.beta1
+
+* Add `deprecation/call` and `deprecation/context` that help with the new `call` API and symbols for `options` keys.
+
 # 2.0.7
 
 * Allow to use any method with the Model macro, e.g.
@@ -8,7 +43,6 @@
 
   will now invoke `Comment[ params[:id] ]`, which makes using Sequel a breeze.
 
-
 # 2.0.6
 
 * Fix what we broke in 2.0.5, where `Wrap` would always use the current operation subclass and not the empty `Trailblazer::Operation`. Thanks to @mensfeld.

data/Gemfile

@@ -3,29 +3,23 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in trailblazer.gemspec
 gemspec
 
-# gem "representable", path: "../representable"
-# gem "disposable", path: "../disposable"
-# gem "reform", github: "apotonick/reform"
 gem "reform-rails"
-gem "activesupport", "~> 4.2.0"
+gem "activesupport"#, "~> 4.2.0"
 
-gem "roar", github: "apotonick/roar"
 # gem "reform", "~> 2.0.0"
 gem "reform"#, path: "../reform"
-# gem "roar", path: "../roar"
 gem "multi_json"
 
 gem "dry-auto_inject"
 gem "dry-matcher"
 gem "dry-validation"
 
-
-# gem "trailblazer-operation", path: "../operation"
-# gem "pipetree", path: "../pipetree"
+gem "trailblazer-operation", path: "../operation"
 # gem "trailblazer-operation", github: "trailblazer/trailblazer-operation"
-# gem "pipetree", github: "apotonick/pipetree"
-
 
 gem "minitest-line"
 
-# gem "uber", path: "../uber"
+gem "trailblazer-activity", path: "../trailblazer-circuit"
+# gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"
+
+# gem "trailblazer-context", path: "../trailblazer-context"

data/README.md

@@ -6,7 +6,9 @@ _Trailblazer provides new high-level abstractions for Ruby frameworks. It gently
 [![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
 [![Gem Version](https://badge.fury.io/rb/trailblazer.svg)](http://badge.fury.io/rb/trailblazer)
 
-**This document discusses Trailblazer 2.0. The [1.x documentation is here](http://trailblazer.to/gems/operation/1.1/).**
+**This document discusses Trailblazer 2.1.** An overview about the additions are [on our website](http://trailblazer.to/blog/2017-12-trailblazer-2-1-what-you-need-to-know.html).
+
+The [1.x documentation is here](http://trailblazer.to/gems/operation/1.1/).
 
 ## Trailblazer In A Nutshell
 

data/Rakefile

@@ -5,23 +5,12 @@ task :default => [:test]
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  # test.test_files = FileList['test/**/*_test.rb']
-  test_files = FileList[%w{
-    test/operation/pundit_test.rb
-    test/operation/model_test.rb
-    test/operation/contract_test.rb
-    test/operation/persist_test.rb
-    test/operation/callback_test.rb
-    test/operation/resolver_test.rb
-    test/operation/dsl/contract_test.rb
-
-    test/docs/*_test.rb
-    }]
-
-  if RUBY_VERSION == "1.9.3"
-    test_files = test_files - %w{test/docs/dry_test.rb test/docs/auto_inject_test.rb}
-  end
+  test.test_files = FileList['test/**/*_test.rb'] - FileList["test/deprecation/*_test.rb"]
+  test.verbose = true
+end
 
-  test.test_files = test_files #- ["test/docs/rescue_test.rb"]
+Rake::TestTask.new(:testdep) do |test|
+  test.libs << 'test'
+  test.test_files = FileList["test/deprecation/*_test.rb"]
   test.verbose = true
 end

data/lib/trailblazer.rb

@@ -1,8 +1,11 @@
-require "trailblazer/operation"
-require "trailblazer/operation/pipetree"
+require "trailblazer/version"
 
+require "trailblazer/operation"
 require "trailblazer/dsl"
-require "trailblazer/version"
+
+require "trailblazer/task"
+
+require "trailblazer/operation/deprecations"
 
 require "trailblazer/operation/model"
 require "trailblazer/operation/contract"
@@ -12,7 +15,7 @@ require "trailblazer/operation/policy"
 require "trailblazer/operation/pundit"
 require "trailblazer/operation/guard"
 require "trailblazer/operation/persist"
-# require "trailblazer/operation/callback"
 require "trailblazer/operation/nested"
 require "trailblazer/operation/wrap"
 require "trailblazer/operation/rescue"
+require "trailblazer/operation/inject"

data/lib/trailblazer/deprecation/call.rb

@@ -0,0 +1,46 @@
+module Trailblazer
+  module Deprecation
+    module Operation
+      # This is super hacky. Fix you call calls everywhere (shouldn't take too long) and never load this file, again.
+      module Call
+        def self.options_for_call(params, *containers)
+          if containers == []
+            if params.is_a?(Hash) # this means we assume everything is cool. Create.( {...} )
+
+            else # this means someone did Create.( #<WeirdParamsObject> )
+              deprecate_positional_params(params, *containers)
+              return { params: params }, *containers
+            end
+          else # Create.( params, "current_user" => ... )
+            options, containers = containers[0], (containers[1..-1] || [])
+            if options.is_a?(Hash) # old API
+              warn "[Trailblazer] Please don't pass the `params` object as a positional argument into `Operation.()`, use the `:params` key and one hash for all: `Operation.( params: my_params, current_user: ... )` ."
+              return options.merge( params: params ), *containers
+            end
+          end
+
+          return params, *containers
+        end
+
+        def self.deprecate_positional_params(params, *containers)
+          warn "[Trailblazer] Please don't pass the `params` object as a positional argument into `Operation.()`, use the `:params` key: `Operation.( params: my_params )` ."
+        end
+      end
+    end
+  end
+end
+
+Trailblazer::Operation.module_eval do
+  # this sucks:
+  def self.call(options={}, *containers)
+    options, *containers = Trailblazer::Deprecation::Operation::Call.options_for_call(options, *containers)
+
+    ctx = Trailblazer::Operation::PublicCall.options_for_public_call(options, *containers)
+
+    # call the activity.
+    last_signal, (options, flow_options) = __call__( [ctx, {}] ) # Railway::call # DISCUSS: this could be ::call_with_context.
+
+    # Result is successful if the activity ended with an End event derived from Railway::End::Success.
+    Trailblazer::Operation::Railway::Result(last_signal, options, flow_options)
+  end
+end

data/lib/trailblazer/deprecation/context.rb

@@ -0,0 +1,43 @@
+module Trailblazer
+  module Deprecation
+    class ContextWithIndifferentAccess < Trailblazer::Context
+      def [](key)
+        return super unless Trailblazer::Operation::PublicCall.deprecatable?(key)
+        key, _ = Trailblazer::Operation::PublicCall.deprecate_string(key, nil)
+        super(key)
+      end
+
+      def []=(key, value)
+        return super unless Trailblazer::Operation::PublicCall.deprecatable?(key)
+        key, _ = Trailblazer::Operation::PublicCall.deprecate_string(key, nil)
+        super(key, value)
+      end
+    end
+  end
+end
+
+Trailblazer::Operation::PublicCall.module_eval do
+  def self.options_for_public_call(options={}, *containers)
+    hash_transformer = ->(containers) { containers[0].to_hash } # FIXME: don't transform any containers into kw args.
+
+    options = deprecate_strings(options)
+
+    immutable_options = Trailblazer::Context::ContainerChain.new( [options, *containers], to_hash: hash_transformer ) # Runtime options, immutable.
+
+    Trailblazer::Deprecation::ContextWithIndifferentAccess.new(immutable_options, {})
+  end
+
+  def self.deprecatable?(key)
+    key.is_a?(String) && key.split(".").size == 1
+  end
+
+  def self.deprecate_strings(options)
+    ary = options.collect { |k,v| deprecatable?(k) ? deprecate_string(k, v) : [k,v]  }
+    Hash[ary]
+  end
+
+  def self.deprecate_string(key, value)
+    warn "[Trailblazer] Using a string key for non-namespaced keys is deprecated. Please use `:#{key}` instead of `#{key.inspect}`."
+    [ key.to_sym, value ]
+  end
+end

data/lib/trailblazer/operation/contract.rb

@@ -8,27 +8,58 @@
 # Needs #[], #[]= skill dependency.
 class Trailblazer::Operation
   module Contract
-    def self.Build(name:"default", constant:nil, builder: nil)
-      step = ->(input, options) { Build.for(input, options, name: name, constant: constant, builder: builder) }
+    def self.Build(name: "default", constant: nil, builder: nil)
+      step = ->((options, flow_options), **circuit_options) { Build.(options, circuit_options, name: name, constant: constant, builder: builder) }
 
-      [ step, name: "contract.build" ]
+      task = Trailblazer::Activity::Task::Binary( step )
+
+      { task: task, id: "contract.build" }
     end
 
     module Build
-      # bla build contract at runtime.
-      def self.for(operation, options, name:"default", constant:nil, builder: nil)
+      # Build contract at runtime.
+      def self.call(options, circuit_options, name: "default", constant: nil, builder: nil)
         # TODO: we could probably clean this up a bit at some point.
-        contract_class = constant || options["contract.#{name}.class"]
-        model          = options["model"] # FIXME: model.default
+        contract_class = constant || options["contract.#{name}.class"] # DISCUSS: Injection possible here?
+        model          = options[:model]
         name           = "contract.#{name}"
 
-        return options[name] = Option::KW.(builder).(operation, options, constant: contract_class, name: name) if builder
+        options[name] =
+          if builder
+            call_builder( options, circuit_options, builder: builder, constant: contract_class, name: name )
+          else
+            contract_class.new(model)
+          end
+      end
+
+      def self.call_builder(options, circuit_options, builder:raise, constant:raise, name:raise)
+        # builder_options = Trailblazer::Context( options, constant: constant, name: name ) # options.merge( .. )
+
+        # Trailblazer::Option::KW(builder).(builder_options, circuit_options)
+
+
+
 
-        options[name] = contract_class.new(model)
+
+
+
+
+        # FIXME: almost identical with Option::KW.
+        # FIXME: see Nested::Options::Dynamic, the same shit
+        tmp_options =  options.to_hash.merge(
+          constant: constant,
+          name:     name
+        )
+
+        Trailblazer::Option(builder).( options, tmp_options, circuit_options )
       end
     end
 
     module DSL
+      def self.extended(extender)
+        extender.extend(ClassDependencies)
+        warn "[Trailblazer] Using `contract do...end` is deprecated. Please use a form class and the Builder( constant: <Form> ) option."
+      end
       # This is the class level DSL method.
       #   Op.contract #=> returns contract class
       #   Op.contract do .. end # defines contract

data/lib/trailblazer/operation/deprecations.rb

@@ -0,0 +1,21 @@
+module Trailblazer
+  class Operation
+    class DeprecatedOptions < Option
+      def self.call!(proc, direction, options, flow_options, *args)
+        if proc.is_a?(Proc) && proc.arity == 1
+          deprecate(proc)
+          proc.(options)
+        elsif proc.method(:call).arity == 1
+          deprecate(proc)
+          proc.(options)
+        else
+          super
+        end
+      end
+
+      def self.deprecate(proc)
+        warn "[Trailblazer] Please use the step API `def my_step!(options, **)` for your step: #{proc}"
+      end
+    end # DeprecatedOptions
+  end
+end

data/lib/trailblazer/operation/guard.rb

@@ -1,17 +1,17 @@
-require "trailblazer/operation/policy"
-
 class Trailblazer::Operation
   module Policy
     def self.Guard(proc, name: :default, &block)
-      Policy.step(Guard.build(proc), name: name)
+      Policy.step( Guard.build(proc), name: name )
     end
 
     module Guard
       def self.build(callable)
-        value = Option::KW.(callable) # Operation::Option
+        option = Trailblazer::Option::KW(callable)
 
         # this gets wrapped in a Operation::Result object.
-        ->(input, options) { Result.new( !!value.(input, options), {} ) }
+        ->( (options, *), circuit_args ) do
+          Result.new( !!option.(options, circuit_args), {} )
+        end
       end
     end # Guard
   end

data/lib/trailblazer/operation/model.rb

@@ -1,23 +1,28 @@
 class Trailblazer::Operation
   def self.Model(model_class, action=nil)
-    step = Model.for(model_class, action)
+    # step = Pipetree::Step.new(step, "model.class" => model_class, "model.action" => action)
 
-    step = Pipetree::Step.new(step, "model.class" => model_class, "model.action" => action)
+    task = Railway::TaskBuilder.( Model.new )
 
-    [ step, name: "model.build" ]
+    runner_options = {
+      merge: Wrap::Inject::Defaults(
+        "model.class"  => model_class,
+        "model.action" => action
+      )
+    }
+
+    { task: task, id: "model.build", runner_options: runner_options }
   end
 
-  module Model
-    def self.for(model_class, action)
+  class Model
+    def call(options, params:,  **)
       builder = Model::Builder.new
 
-      ->(input, options) do
-        options["model"] = model = builder.(options, options["params"])
+      options[:model] = model = builder.(options, params)
 
-        options["result.model"] = result = Result.new(!model.nil?, {})
+      options["result.model"] = result = Result.new(!model.nil?, {})
 
-        result.success?
-      end
+      result.success?
     end
 
     class Builder

data/lib/trailblazer/operation/nested.rb

@@ -1,113 +1,84 @@
-class Trailblazer::Operation
-  def self.Nested(callable, input:nil, output:nil)
-    step = Nested.for(callable, input, output)
-
-    [ step, { name: "Nested(#{callable})" } ]
-  end
-
-  # WARNING: this is experimental API, but it will end up with something like that.
-  module Element
-    # DISCUSS: add builders here.
-    def initialize(wrapped=nil)
-      @wrapped = wrapped
-    end
+# per default, everything we pass into a circuit is immutable. it's the ops/act's job to allow writing (via a Context)
+module Trailblazer
+  class Operation
+    def self.Nested(callable, input:nil, output:nil, id: "Nested(#{callable})")
+      task_wrap_wirings = []
+      task, operation = Nested.build(callable, input, output)
 
-    module Dynamic
-      def initialize(wrapped)
-        @wrapped = Option::KW.(wrapped)
-      end
-    end
-  end
+      # @needs operation#outputs
 
-  module Nested
-    # Please note that the instance_variable_get are here on purpose since the
-    # superinternal API is not entirely decided, yet.
-    # @api private
-    def self.for(step, input, output, is_nestable_object=method(:nestable_object?)) # DISCUSS: use builders here?
-      invoker            = Caller::Dynamic.new(step)
-      invoker            = Caller.new(step) if is_nestable_object.(step)
+      # TODO: move this to the generic step DSL
+      task_wrap_extensions = []
 
-      options_for_nested = Options.new
-      options_for_nested = Options::Dynamic.new(input) if input
+      if input || output
+        default_input_filter  = ->(options, *) { ctx = options }
+        default_output_filter = ->(options, *) { options }
 
-      options_for_composer = Options::Output.new
-      options_for_composer = Options::Output::Dynamic.new(output) if output
+        input  ||= default_input_filter
+        output ||= default_output_filter
 
-      # This lambda is the strut added on the track, executed at runtime.
-      ->(operation, options) do
-        result = invoker.(operation, options, options_for_nested.(operation, options)) # TODO: what about containers?
+        input_filter  = Activity::Wrap::Input.new(input)
+        output_filter = Activity::Wrap::Output.new(output)
 
-        options_for_composer.(operation, options, result).each { |k,v| options[k] = v }
-
-        result.success? # DISCUSS: what if we could simply return the result object here?
+        task_wrap_extensions = Activity::Magnetic::Builder::Path.plan do
+          task input_filter,  id: ".input",  before: "task_wrap.call_task"
+          task output_filter, id: ".output", before: "End.success", group: :end # DISCUSS: position
+        end
       end
-    end
+        # Default {Output} copies the mutable data from the nested activity into the original.
 
-    def self.nestable_object?(object)
-      # interestingly, with < we get a weird nil exception. bug in Ruby?
-      object.is_a?(Class) && object <= Trailblazer::Operation
+      { task: task, id: id, runner_options: { merge: task_wrap_extensions }, plus_poles: Activity::Magnetic::DSL::PlusPoles.from_outputs(operation.outputs) }
     end
 
-    # Is executed at runtime and calls the nested operation.
-    class Caller
-      include Element
+    # @private
+    module Nested
+      def self.build(nested_operation, input, output) # DISCUSS: use builders here?
+        return dynamic = Dynamic.new(nested_operation), dynamic unless nestable_object?(nested_operation)
 
-      def call(input, options, options_for_nested)
-        call_nested(nested(input, options), options_for_nested)
+        # The returned {Nested} instance is a valid circuit element and will be `call`ed in the circuit.
+        # It simply returns the nested activity's `signal,options,flow_options` return set.
+        # The actual wiring - where to go with that - is done by the step DSL.
+        return Trailblazer::Activity::Subprocess(nested_operation, call: :__call__), nested_operation
       end
 
-    private
-      def call_nested(operation, options)
-        operation._call(options)
+      def self.nestable_object?(object)
+        object.is_a?( Trailblazer::Activity::Interface )
       end
 
-      def nested(*); @wrapped end
-
-      class Dynamic < Caller
-        include Element::Dynamic
-
-        def nested(input, options)
-          @wrapped.(input, options)
-        end
+      def self.operation_class
+        Operation
       end
-    end
-
-    class Options
-      include Element
 
-      # Per default, only runtime data for nested operation.
-      def call(input, options)
-        options.to_runtime_data[0]
-      end
+      private
 
+      # For dynamic `Nested`s that do not expose an {Activity} interface.
+      # Since we do not know its outputs, we have to map them to :success and :failure, only.
+      #
+      # This is what {Nested} in 2.0 used to do, where the outcome could only be true/false (or success/failure).
       class Dynamic
-        include Element::Dynamic
-
-        def call(operation, options)
-          @wrapped.(operation, options, runtime_data: options.to_runtime_data[0], mutable_data: options.to_mutable_data )
+        def initialize(wrapped)
+          @wrapped = Trailblazer::Option::KW(wrapped)
+          @outputs = {
+            :success => Activity::Output( Railway::End::Success.new(:success), :success ),
+            :failure => Activity::Output( Railway::End::Failure.new(:failure), :failure ),
+          }
         end
-      end
 
-      class Output
-        include Element
+        attr_reader :outputs
 
-        def call(input, options, result)
-          mutable_data_for(result).each { |k,v| options[k] = v }
-        end
-
-        def mutable_data_for(result)
-          result.instance_variable_get(:@data).to_mutable_data
-        end
+        def call( (options, flow_options), **circuit_options )
+          activity = @wrapped.(options, circuit_options) # evaluate the option to get the actual "object" to call.
 
-        class Dynamic < Output
-          include Element::Dynamic
+          signal, args = activity.__call__( [options, flow_options], **circuit_options )
 
-          def call(input, options, result)
-            @wrapped.(input, options, mutable_data: mutable_data_for(result))
-          end
+          # Translate the genuine nested signal to the generic Dynamic end (success/failure, only).
+          # Note that here we lose information about what specific event was emitted.
+          [
+            signal.kind_of?(Railway::End::Success) ? @outputs[:success].signal : @outputs[:failure].signal,
+            args
+          ]
         end
       end
     end
-  end
+  end # Operation
 end
-