trailblazer-macro-contract 2.1.0.beta2

data/Gemfile

@@ -0,0 +1,21 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in trailblazer.gemspec
+gemspec
+
+gem "reform-rails"
+gem "activesupport"
+
+gem "reform"
+gem "multi_json"
+
+gem "dry-auto_inject"
+gem "dry-matcher"
+gem "dry-validation"
+
+# gem "trailblazer-operation", github: "trailblazer/trailblazer-operation"
+# gem "trailblazer-macro", github: "trailblazer/trailblazer-macro"
+
+gem "minitest-line"
+
+gem "rubocop", require: false

data/LICENSE.txt

@@ -0,0 +1,9 @@
+Copyright (c) Nick Sutterer
+
+Trailblazer is an Open Source project licensed under the terms of
+the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
+for license text.
+
+Trailblazer Enterprise has a commercial-friendly license allowing private forks
+and modifications of Trailblazer.  Please see http://trailblazer.to/enterprise/ for
+more detail.  You can find the commercial license terms in COMM-LICENSE.

data/README.md

@@ -0,0 +1,195 @@
+# Trailblazer Macro Contract
+The Contract Macros helps you defining contracts and assists with instantiating and validating data with those contracts at runtime.
+
+## Table of Contents
+* [Installation](#installation)
+* [Contract](#contract)
+  + [Build](#build)
+  + [Validation](#validation)
+    - [Key](#key)
+  + [Persist](#persist)
+    - [Name](#name)
+  + [Result Object](#result-object)
+
+## Installation
+The obvious needs to be in your `Gemfile`.
+```ruby
+gem "trailblazer-operation"
+gem "reform"
+gem "trailblazer-macro-contract"
+```
+Note: you don't need to install anything if you're using the trailblazer gem itself.
+
+## Contract
+The Contract Macro, covers the contracts for Trailblazer, they are basically Reform objects that you can define and validate inside an operation. Reform is a fantastic tool for deserializing and validating deeply nested hashes, and then, when valid, writing those to the database using your persistence layer such as ActiveRecord.
+
+```ruby
+# app/concepts/song/contract/create.rb
+module Song::Contract
+  class Create < Reform::Form
+    property :title
+    property :length
+
+    validates :title,  length: 2..33
+    validates :length, numericality: true
+  end
+end
+```
+
+The Contract then gets hooked into the operation. using this Macro.
+```ruby
+# app/concepts/song/operation/create.rb
+class Song::Create < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build( constant: Song::Contract::Create )
+  step Contract::Validate()
+  step Contract::Persist()
+end
+```
+As you can see, using contracts consists of five steps.
+
+Define the contract class (or multiple of them) for the operation.
+Plug the contract creation into the operation’s pipe using Contract::Build.
+Run the contract’s validation for the params using Contract::Validate.
+If successful, write the sane data to the model(s). This will usually happen in the Contract::Persist macro.
+After the operation has been run, interpret the result. For instance, a controller calling an operation will render a erroring form for invalid input.
+
+Here’s what the result would look like after running the Create operation with invalid data.
+```ruby
+result = Song::Create.( title: "A" )
+result.success? #=> false
+result["contract.default"].errors.messages
+  #=> {:title=>["is too short (minimum is 2 characters)"], :length=>["is not a number"]}
+```
+
+### Build
+The Contract::Build macro helps you to instantiate the contract. It is both helpful for a complete workflow, or to create the contract, only, without validating it, e.g. when presenting the form.
+```ruby
+class Song::New < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build( constant: Song::Contract::Create )
+end
+```
+
+This macro will grab the model from options["model"] and pass it into the contract’s constructor. The contract is then saved in options["contract.default"].
+```ruby
+result = Song::New.()
+result["model"] #=> #<struct Song title=nil, length=nil>
+result["contract.default"]
+  #=> #<Song::Contract::Create model=#<struct Song title=nil, length=nil>>
+```
+The Build macro accepts the :name option to change the name from default.
+
+### Validation
+The Contract::Validate macro is responsible for validating the incoming params against its contract. That means you have to use Contract::Build beforehand, or create the contract yourself. The macro will then grab the params and throw then into the contract’s validate (or call) method.
+
+```ruby
+class Song::ValidateOnly < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build( constant: Song::Contract::Create )
+  step Contract::Validate()
+end
+```
+Depending on the outcome of the validation, it either stays on the right track, or deviates to left, skipping the remaining steps.
+```ruby
+result = Song::ValidateOnly.({}) # empty params
+result.success? #=> false
+```
+
+Note that Validate really only validates the contract, nothing is written to the model, yet. You need to push data to the model manually, e.g. with Contract::Persist.
+```ruby
+result = Song::ValidateOnly.({ title: "Rising Force", length: 13 })
+
+result.success? #=> true
+result["model"] #=> #<struct Song title=nil, length=nil>
+result["contract.default"].title #=> "Rising Force"
+```
+
+Validate will use options["params"] as the input. You can change the nesting with the :key option.
+
+Internally, this macro will simply call Form#validate on the Reform object.
+
+Note: Reform comes with sophisticated deserialization semantics for nested forms, it might be worth reading a bit about Reform to fully understand what you can do in the Validate step.
+
+#### Key
+Per default, Contract::Validate will use options["params"] as the data to be validated. Use the key: option if you want to validate a nested hash from the original params structure.
+```ruby
+class Song::Create < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build( constant: Song::Contract::Create )
+  step Contract::Validate( key: "song" )
+  step Contract::Persist( )
+end
+```
+
+This automatically extracts the nested "song" hash.
+```ruby
+result = Song::Create.({ "song" => { title: "Rising Force", length: 13 } })
+result.success? #=> true
+```
+
+If that key isn’t present in the params hash, the operation fails before the actual validation.
+```ruby
+result = Song::Create.({ title: "Rising Force", length: 13 })
+result.success? #=> false
+```
+
+Note: String vs. symbol do matter here since the operation will simply do a hash lookup using the key you provided.
+
+### Persist
+To push validated data from the contract to the model(s), use Persist. Like Validate, this requires a contract to be set up beforehand.
+```ruby
+class Song::Create < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build( constant: Song::Contract::Create )
+  step Contract::Validate()
+  step Contract::Persist()
+end
+```
+
+After the step, the contract’s attribute values are written to the model, and the contract will call save on the model.
+```ruby
+result = Song::Create.( title: "Rising Force", length: 13 )
+result.success? #=> true
+result["model"] #=> #<Song title="Rising Force", length=13>
+```
+
+You can also configure the Persist step to call sync instead of Reform’s save.
+```ruby
+step Persist( method: :sync )
+```
+This will only write the contract’s data to the model without calling save on it.
+
+#### Name
+Explicit naming for the contract is possible, too.
+```ruby
+
+class Song::Create < Trailblazer::Operation
+  step Model( Song, :new )
+  step Contract::Build(    name: "form", constant: Song::Contract::Create )
+  step Contract::Validate( name: "form" )
+  step Contract::Persist(  name: "form" )
+end
+```
+
+You have to use the name: option to tell each step what contract to use. The contract and its result will now use your name instead of default.
+```ruby
+result = Song::Create.({ title: "A" })
+result["contract.form"].errors.messages #=> {:title=>["is too short (minimum is 2 ch...
+```
+
+Use this if your operation has multiple contracts.
+
+### Result Object
+The operation will store the validation result for every contract in its own result object.
+
+The path is result.contract.#{name}.
+```ruby
+result = Create.({ length: "A" })
+
+result["result.contract.default"].success?        #=> false
+result["result.contract.default"].errors          #=> Errors object
+result["result.contract.default"].errors.messages #=> {:length=>["is not a number"]}
+```
+
+Each result object responds to success?, failure?, and errors, which is an Errors object. TODO: design/document Errors. WE ARE CURRENTLY WORKING ON A UNIFIED API FOR ERRORS (FOR DRY AND REFORM).

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+task :default => %i[test rubocop]
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/**/*_test.rb']
+  test.verbose = true
+end
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.patterns = ['lib/**/*.rb', 'test/**/*.rb']
+  task.options << "--display-cop-names"
+  task.fail_on_error = false
+end

data/lib/trailblazer/macro/contract.rb

@@ -0,0 +1,5 @@
+require "reform"
+require "trailblazer/macro/contract/version"
+require "trailblazer/operation/contract"
+require "trailblazer/operation/validate"
+require "trailblazer/operation/persist"

data/lib/trailblazer/macro/contract/version.rb

@@ -0,0 +1,7 @@
+module Trailblazer
+  module Macro
+    module Contract
+    VERSION = "2.1.0.beta2".freeze
+    end
+  end
+end

data/lib/trailblazer/operation/contract.rb

@@ -0,0 +1,61 @@
+module Trailblazer
+  class Operation
+    module Contract
+      def self.Build(name: "default", constant: nil, builder: nil)
+        task = lambda do |(options, flow_options), **circuit_options|
+          result = Build.(options, circuit_options, name: name, constant: constant, builder: builder)
+
+          return Activity::TaskBuilder::Binary.binary_direction_for( result, Activity::Right, Activity::Left ),
+              [options, flow_options]
+        end
+
+        { task: task, id: "contract.build" }
+      end
+
+      module Build
+        # 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"] # DISCUSS: Injection possible here?
+          model          = options[:model]
+          name           = "contract.#{name}"
+
+          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)
+          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
+        #   Op.contract CommentForm # copies (and subclasses) external contract.
+        #   Op.contract CommentForm do .. end # copies and extends contract.
+        def contract(name=:default, constant=nil, base: Reform::Form, &block)
+          heritage.record(:contract, name, constant, &block)
+
+          path, form_class = Trailblazer::DSL::Build.new.({ prefix: :contract, class: base, container: self }, name, constant, block)
+
+          self[path] = form_class
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/persist.rb

@@ -0,0 +1,14 @@
+module Trailblazer
+  class Operation
+    module Contract
+      def self.Persist(method: :save, name: "default")
+        path = "contract.#{name}"
+        step = ->(options, **) { options[path].send(method) }
+
+        task = Activity::TaskBuilder::Binary.( step )
+
+        { task: task, id: "persist.save" }
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/validate.rb

@@ -0,0 +1,74 @@
+module Trailblazer
+  class Operation
+    module Contract
+      # result.contract = {..}
+      # result.contract.errors = {..}
+      # Deviate to left track if optional key is not found in params.
+      # Deviate to left if validation result falsey.
+      def self.Validate(skip_extract: false, name: "default", representer: false, key: nil) # DISCUSS: should we introduce something like Validate::Deserializer?
+        params_path = "contract.#{name}.params" # extract_params! save extracted params here.
+
+        extract  = Validate::Extract.new( key: key, params_path: params_path ).freeze
+        validate = Validate.new( name: name, representer: representer, params_path: params_path ).freeze
+
+        # Build a simple Railway {Activity} for the internal flow.
+        activity = Module.new do
+          extend Activity::Railway(name: "Contract::Validate")
+
+          step extract,  id: "#{params_path}_extract" unless skip_extract || representer
+          step validate, id: "contract.#{name}.call"
+        end
+
+        # activity, _ = activity.decompose
+
+        # DISCUSS: use Nested here?
+        { task: activity, id: "contract.#{name}.validate", outputs: activity.outputs }
+      end
+
+      class Validate
+        # Task: extract the contract's input from params by reading `:key`.
+        class Extract
+          def initialize(key:nil, params_path:nil)
+            @key, @params_path = key, params_path
+          end
+
+          def call( ctx, params:, ** )
+            ctx[@params_path] = @key ? params[@key] : params
+          end
+        end
+
+        def initialize(name:"default", representer:false, params_path:nil)
+          @name, @representer, @params_path = name, representer, params_path
+        end
+
+        # Task: Validates contract `:name`.
+        def call( ctx, ** )
+          validate!(
+            ctx,
+            representer: ctx["representer.#{@name}.class"] ||= @representer, # FIXME: maybe @representer should use DI.
+            params_path: @params_path
+          )
+        end
+
+        def validate!(options, representer:false, from: :document, params_path:nil)
+          path     = "contract.#{@name}"
+          contract = options[path]
+
+          # this is for 1.1-style compatibility and should be removed once we have Deserializer in place:
+          options["result.#{path}"] = result =
+            if representer
+              # use :document as the body and let the representer deserialize to the contract.
+              # this will be simplified once we have Deserializer.
+              # translates to contract.("{document: bla}") { MyRepresenter.new(contract).from_json .. }
+              contract.(options[from]) { |document| representer.new(contract).parse(document) }
+            else
+              # let Reform handle the deserialization.
+              contract.(options[params_path])
+            end
+
+          result.success?
+        end
+      end
+    end
+  end # Operation
+end

data/test/docs/contract_test.rb

@@ -0,0 +1,439 @@
+require "test_helper"
+
+class DocsContractOverviewTest < Minitest::Spec
+  Song = Struct.new(:length, :title)
+
+  #:overv-reform
+  # app/concepts/song/create.rb
+  class Create < Trailblazer::Operation
+    #~contractonly
+    class MyContract < Reform::Form
+      property :title
+      property :length
+
+      validates :title,  presence: true
+      validates :length, numericality: true
+    end
+    #~contractonly end
+
+    step Model( Song, :new )
+    step Contract::Build(constant: MyContract)
+    step Contract::Validate()
+    step Contract::Persist( method: :sync )
+    #~contractonly end
+  end
+  #:overv-reform end
+
+  puts Trailblazer::Operation::Inspect.(Create, style: :rows)
+
+=begin
+  #:overv-reform-pipe
+   0 ==========================&model.build
+   1 =======================>contract.build
+   2 ==============&validate.params.extract
+   3 ====================&contract.validate
+   4 =========================&persist.save
+  #:overv-reform-pipe end
+=end
+
+  it do
+    assert Create.(params: {})["contract.default"].must_be_instance_of DocsContractOverviewTest::Create::MyContract
+  end
+
+  #- result
+  it do
+    #:result
+    result = Create.(params: { length: "A" })
+
+    result["result.contract.default"].success?        #=> false
+    result["result.contract.default"].errors          #=> Errors object
+    result["result.contract.default"].errors.messages #=> {:length=>["is not a number"]}
+
+    #:result end
+    result["result.contract.default"].success?.must_equal false
+    result["result.contract.default"].errors.messages.must_equal ({:title=>["can't be blank"], :length=>["is not a number"]})
+  end
+
+  it "shows 2-level tracing" do
+    result = Create.trace( params: { length: "A" } )
+    result.wtf.gsub(/0x\w+/, "").must_equal %{|-- #<Trailblazer::Activity::Start semantic=:default>
+|-- model.build
+|-- contract.build
+|-- contract.default.validate
+|   |-- #<Trailblazer::Activity::Start semantic=:default>
+|   |-- contract.default.params_extract
+|   |-- contract.default.call
+|   `-- #<Trailblazer::Activity::End semantic=:failure>
+`-- #<Trailblazer::Operation::Railway::End::Failure semantic=:failure>}
+  end
+end
+#---
+# contract MyContract
+class DocsContractExplicitTest < Minitest::Spec
+  Song = Struct.new(:length, :title)
+
+  #:reform-inline
+  class MyContract < Reform::Form
+    property :title
+    property :length
+
+    validates :title,  presence: true
+    validates :length, numericality: true
+  end
+  #:reform-inline end
+
+  #:reform-inline-op
+  # app/concepts/comment/create.rb
+  class Create < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build(constant: MyContract)
+    step Contract::Validate()
+    step Contract::Persist( method: :sync )
+  end
+  #:reform-inline-op end
+end
+
+#- Validate with manual key extraction
+class DocsContractSeparateKeyTest < Minitest::Spec
+  Song = Struct.new(:id, :title)
+  #:key-extr
+  class Create < Trailblazer::Operation
+    class MyContract < Reform::Form
+      property :title
+    end
+
+    def type
+      "evergreen" # this is how you could do polymorphic lookups.
+    end
+
+    step Model( Song, :new )
+    step Contract::Build(constant: MyContract)
+    step :extract_params!
+    step Contract::Validate( skip_extract: true )
+    step Contract::Persist( method: :sync )
+
+    def extract_params!(options, **)
+      options["contract.default.params"] = options[:params][type]
+    end
+  end
+  #:key-extr end
+
+  it { Create.(params: { }).inspect(:model).must_equal %{<Result:false [#<struct DocsContractSeparateKeyTest::Song id=nil, title=nil>] >} }
+  it { Create.(params: {"evergreen" => { title: "SVG" }}).inspect(:model).must_equal %{<Result:true [#<struct DocsContractSeparateKeyTest::Song id=nil, title="SVG">] >} }
+end
+
+#---
+#- Contract::Build( constant: XXX )
+class ContractConstantTest < Minitest::Spec
+  Song = Struct.new(:title, :length) do
+    def save
+      true
+    end
+  end
+
+  #:constant-contract
+  # app/concepts/song/contract/create.rb
+  module Song::Contract
+    class Create < Reform::Form
+      property :title
+      property :length
+
+      validates :title,  length: 2..33
+      validates :length, numericality: true
+    end
+  end
+  #:constant-contract end
+
+  #:constant
+  class Song::Create < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build( constant: Song::Contract::Create )
+    step Contract::Validate()
+    step Contract::Persist()
+  end
+  #:constant end
+
+  it { Song::Create.(params: { title: "A" }).inspect(:model).must_equal %{<Result:false [#<struct ContractConstantTest::Song title=nil, length=nil>] >} }
+  it { Song::Create.(params: { title: "Anthony's Song", length: 12 }).inspect(:model).must_equal %{<Result:true [#<struct ContractConstantTest::Song title="Anthony's Song", length=12>] >} }
+  it do
+    #:constant-result
+    result = Song::Create.(params: { title: "A" })
+    result.success? #=> false
+    result["contract.default"].errors.messages
+    #=> {:title=>["is too short (minimum is 2 characters)"], :length=>["is not a number"]}
+    #:constant-result end
+
+    #:constant-result-true
+    result = Song::Create.(params: { title: "Rising Force", length: 13 })
+    result.success? #=> true
+    result["model"] #=> #<Song title="Rising Force", length=13>
+    #:constant-result-true end
+  end
+
+  #---
+  # Song::New
+  #:constant-new
+  class Song::New < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build( constant: Song::Contract::Create )
+  end
+  #:constant-new end
+
+  it { Song::New.(params: {}).inspect(:model).must_equal %{<Result:true [#<struct ContractConstantTest::Song title=nil, length=nil>] >} }
+  it { Song::New.(params: {})["contract.default"].model.inspect.must_equal %{#<struct ContractConstantTest::Song title=nil, length=nil>} }
+  it do
+    #:constant-new-result
+    result = Song::New.(params: {})
+    result["model"] #=> #<struct Song title=nil, length=nil>
+    result["contract.default"]
+    #=> #<Song::Contract::Create model=#<struct Song title=nil, length=nil>>
+    #:constant-new-result end
+  end
+
+  #---
+  #:validate-only
+  class Song::ValidateOnly < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build( constant: Song::Contract::Create )
+    step Contract::Validate()
+  end
+  #:validate-only end
+
+  it { Song::ValidateOnly.(params: {}).inspect(:model).must_equal %{<Result:false [#<struct ContractConstantTest::Song title=nil, length=nil>] >} }
+  it do
+    result = Song::ValidateOnly.(params: { title: "Rising Forse", length: 13 })
+    result.inspect(:model).must_equal %{<Result:true [#<struct ContractConstantTest::Song title=nil, length=nil>] >}
+  end
+
+  it do
+    #:validate-only-result-false
+    result = Song::ValidateOnly.(params: {}) # empty params
+    result.success? #=> false
+    #:validate-only-result-false end
+  end
+
+  it do
+    #:validate-only-result
+    result = Song::ValidateOnly.(params: { title: "Rising Force", length: 13 })
+
+    result.success? #=> true
+    result["model"] #=> #<struct Song title=nil, length=nil>
+    result["contract.default"].title #=> "Rising Force"
+    #:validate-only-result end
+  end
+end
+
+#---
+#- Validate( key: :song )
+class DocsContractKeyTest < Minitest::Spec
+  Song = Class.new(ContractConstantTest::Song)
+
+  module Song::Contract
+    Create = ContractConstantTest::Song::Contract::Create
+  end
+
+  #:key
+  class Song::Create < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build( constant: Song::Contract::Create )
+    step Contract::Validate( key: "song" )
+    step Contract::Persist( )
+  end
+  #:key end
+
+  it { Song::Create.(params: {}).inspect(:model, "result.contract.default.extract").must_equal %{<Result:false [#<struct DocsContractKeyTest::Song title=nil, length=nil>, nil] >} }
+  it { Song::Create.(params: {"song" => { title: "SVG", length: 13 }}).inspect(:model).must_equal %{<Result:true [#<struct DocsContractKeyTest::Song title=\"SVG\", length=13>] >} }
+  it do
+    #:key-res
+    result = Song::Create.(params: { "song" => { title: "Rising Force", length: 13 } })
+    result.success? #=> true
+    #:key-res end
+
+    #:key-res-false
+    result = Song::Create.(params: { title: "Rising Force", length: 13 })
+    result.success? #=> false
+    #:key-res-false end
+  end
+end
+
+#- Contract::Build[ constant: XXX, name: AAA ]
+class ContractNamedConstantTest < Minitest::Spec
+  Song = Class.new(ContractConstantTest::Song)
+
+  module Song::Contract
+    Create = ContractConstantTest::Song::Contract::Create
+  end
+
+  #:constant-name
+  class Song::Create < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build(    name: "form", constant: Song::Contract::Create )
+    step Contract::Validate( name: "form" )
+    step Contract::Persist(  name: "form" )
+  end
+  #:constant-name end
+
+  it { Song::Create.(params: { title: "A" }).inspect(:model).must_equal %{<Result:false [#<struct ContractNamedConstantTest::Song title=nil, length=nil>] >} }
+  it { Song::Create.(params: { title: "Anthony's Song", length: 13 }).inspect(:model).must_equal %{<Result:true [#<struct ContractNamedConstantTest::Song title="Anthony's Song", length=13>] >} }
+
+  it do
+    #:name-res
+    result = Song::Create.(params: { title: "A" })
+    result["contract.form"].errors.messages #=> {:title=>["is too short (minimum is 2 ch...
+    #:name-res end
+  end
+end
+
+#---
+#- dependency injection
+#- contract class
+class ContractInjectConstantTest < Minitest::Spec
+  Song = Struct.new(:id, :title)
+  #:di-constant-contract
+  class MyContract < Reform::Form
+    property :title
+    validates :title, length: 2..33
+  end
+  #:di-constant-contract end
+  #:di-constant
+  class Create < Trailblazer::Operation
+    step Model( Song, :new )
+    step Contract::Build()
+    step Contract::Validate()
+    step Contract::Persist( method: :sync )
+  end
+  #:di-constant end
+
+  it do
+    #:di-contract-call
+    Create.(
+      params: { title: "Anthony's Song" },
+      "contract.default.class" => MyContract
+    )
+    #:di-contract-call end
+  end
+  it { Create.(params: { title: "A" }, "contract.default.class" => MyContract).inspect(:model).must_equal %{<Result:false [#<struct ContractInjectConstantTest::Song id=nil, title=nil>] >} }
+  it { Create.(params: { title: "Anthony's Song" }, "contract.default.class" => MyContract).inspect(:model).must_equal %{<Result:true [#<struct ContractInjectConstantTest::Song id=nil, title="Anthony's Song">] >} }
+end
+
+class DryValidationContractTest < Minitest::Spec
+  Song = Struct.new(:id, :title)
+  #---
+  # DRY-validation with multiple validation sets,
+  #- result.path
+  #:dry-schema
+  require "reform/form/dry"
+  class Create < Trailblazer::Operation
+    # contract to verify params formally.
+    class MyContract < Reform::Form
+      feature Reform::Form::Dry
+      property :id
+      property :title
+
+      validation name: :default do
+        required(:id).filled
+      end
+
+      validation name: :extra, if: :default do
+        required(:title).filled(min_size?: 2)
+      end
+    end
+    #~form end
+
+    step Model( Song, :new )                      # create the op's main model.
+    step Contract::Build( constant: MyContract )  # create the Reform contract.
+    step Contract::Validate()                     # validate the Reform contract.
+    step Contract::Persist( method: :sync)        # persist the contract's data via the model.
+    #~form end
+  end
+  #:dry-schema end
+
+  puts "@@@@@ #{Trailblazer::Operation::Inspect.(Create, style: :rows)}"
+
+  it { Create.(params: {}).inspect("result.contract.default").must_include "Result:false"}
+  it { Create.(params: {}).inspect("result.contract.default").must_include "@errors={:id=>[\"must be filled\""}
+
+  it { Create.(params: { id: 1 }).inspect(:model, "result.contract.default").must_include "Result:false"}
+  it { Create.(params: { id: 1 }).inspect(:model, "result.contract.default").must_include "@errors={:title=>[\"must be filled\", \"size cannot be less than 2\"]}"}
+  it { Create.(params: { id: 1 }).inspect(:model, "result.contract.default").wont_include ":id=>[\"must be filled\""}
+
+  it { Create.(params: { id: 1, title: "" }).inspect(:model).must_equal %{<Result:false [#<struct DryValidationContractTest::Song id=nil, title=nil>] >} }
+  it { Create.(params: { id: 1, title: "Y" }).inspect(:model).must_equal %{<Result:false [#<struct DryValidationContractTest::Song id=nil, title=nil>] >} }
+  it { Create.(params: { id: 1, title: "Yo" }).inspect(:model).must_equal %{<Result:true [#<struct DryValidationContractTest::Song id=1, title="Yo">] >} }
+end
+
+class DocContractBuilderTest < Minitest::Spec
+  Song = Struct.new(:id, :title)
+  #---
+  #- builder:
+  #:builder-option
+  class Create < Trailblazer::Operation
+
+    class MyContract < Reform::Form
+      property :title
+      property :current_user, virtual: true
+
+      validate :current_user?
+      validates :title, presence: true
+
+      def current_user?
+        return true if defined?(current_user)
+        false
+      end
+    end
+
+    step Model( Song, :new )
+    step Contract::Build( constant: MyContract, builder: :default_contract! )
+    step Contract::Validate()
+    step Contract::Persist( method: :sync )
+
+    def default_contract!(options, constant:, model:, **)
+      constant.new(model, current_user: options [:current_user])
+    end
+  end
+  #:builder-option end
+
+  it { Create.(params: {}).inspect(:model).must_equal %{<Result:false [#<struct DocContractBuilderTest::Song id=nil, title=nil>] >} }
+  it { Create.(params: { title: "title"}, current_user: Module).inspect(:model).must_equal %{<Result:true [#<struct DocContractBuilderTest::Song id=nil, title="title">] >} }
+end
+
+class DocContractTest < Minitest::Spec
+  Song = Struct.new(:id, :title)
+  #---
+  # with contract block, and inheritance, the old way.
+  class Block < Trailblazer::Operation
+    class MyContract < Reform::Form
+      property :title
+    end
+
+    step Model( Song, :new )
+    step Contract::Build(constant: MyContract)            # resolves to "contract.class.default" and is resolved at runtime.
+    step Contract::Validate()
+    step Contract::Persist( method: :sync )
+  end
+
+  it { Block.(params: {}).inspect(:model).must_equal %{<Result:true [#<struct DocContractTest::Song id=nil, title=nil>] >} }
+  it { Block.(params: { id:1, title: "Fame" }).inspect(:model).must_equal %{<Result:true [#<struct DocContractTest::Song id=nil, title="Fame">] >} }
+
+  class Breach < Block
+    class MyContract < MyContract
+      property :id
+    end
+
+    step Contract::Build(constant: MyContract), replace: "contract.build"
+  end
+
+  it { Breach.(params: { id:1, title: "Fame" }).inspect(:model).must_equal %{<Result:true [#<struct DocContractTest::Song id=1, title="Fame">] >} }
+
+  #-
+  # with constant.
+  class Break < Block
+    class MyContract < Reform::Form
+      property :id
+    end
+    # override the original block as if it's never been there.
+    step Contract::Build(constant: MyContract), replace: "contract.build"
+  end
+
+  it { Break.(params: { id:1, title: "Fame" }).inspect(:model).must_equal %{<Result:true [#<struct DocContractTest::Song id=1, title=nil>] >} }
+end