trailblazer 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 06e8559ba04b20c80f460c00d2fe76e94a7dceae
-  data.tar.gz: d16ed4ac3f269404152c316e2abcad2053c9f29c
+  metadata.gz: 6fe908e23b8ef76962d2eba061d666567e204120
+  data.tar.gz: 3df42356be844b922d258de9f3e64ed72f5b5a9c
 SHA512:
-  metadata.gz: 2818fb4a0c7cfdc66b700df7feed6ac8a60dca747922ac901c311c92dffaf44dd0b3881ddfb46bf3eceebbc122d558bbd5c1acfc463a4ff2246824f519e475ee
-  data.tar.gz: 39daeb303ccadc8dd261cfa44576bf046d94174568abecceed193de66c902cd3fc1a5ce27d99814644f26585b800d7f7568b094f5c5ff044eb8fbbaf29ea1fa6
+  metadata.gz: 9190472c21be262f4a216f52180c9b91bbf9c073650148fe53aec8b83ba2493f0365d4d10ebd603daa4a9f6c295411a634f66b302e7d5895c6fe8fdca66783b4
+  data.tar.gz: 119fbafbce0d79e95c9f4131400ba6860e12fe40f8e9e0901c4457da3450c0940915d9bb51e3ac0f502fd00cd6022224e4d082041dec843bf878537cdb3b6e71

data/CHANGES.md

@@ -1,3 +1,8 @@
+# 0.3.2
+
+* Allow to use `#contract` before `#validate`. The contract will be instantiated once per `#run` using `#contract` and then memoized. This allows to add/modify the contract _before_ you validate it using `#validate`.
+* New signature for `Operation#contract_for(model, contract_class)`. It used to be contract, then model.
+
 # 0.3.1
 
 * Autoload `Dispatch`.

data/Gemfile

@@ -8,4 +8,4 @@ gemspec
 # gem "disposable", path: "../disposable"
 gem "virtus"
 # gem "reform", github: "apotonick/reform"
-gem "reform", ">= 2.0.0.rc1"
+gem "reform", "~> 2.0.0"

data/README.md

@@ -420,6 +420,76 @@ Comment::Create.run(params) do |op|
 end
 ```
 
+### Inheritance
+
+Operations fully support inheritance and will copy the contract, the callback groups and any methods from the original operation class.
+
+```ruby
+class Create < Trailblazer::Operation
+  contract do
+    property :title
+  end
+
+  callback(:before_save) do
+    on_change :notify!
+  end
+
+  def notify!(*)
+  end
+end
+```
+
+This happens with normal Ruby inheritance.
+
+```ruby
+class Update < Create
+  # inherited:
+  # contract
+  # callback(:before_save)
+  # def notify!(*)
+end
+```
+
+You can customize callback groups and contracts using the `:inherit` option, add and remove properties or add methods.
+
+[Learn more](http://trailblazerb.org/gems/operation/inheritance.html)
+
+### Modules
+
+In case inheritance is not enough for you, use modules to share common functionality.
+
+```ruby
+module ExtendedCreate
+  include Trailblazer::Operation::Module
+
+  contract do
+    property :id
+  end
+
+  callback do
+    on_update :update!
+  end
+
+  def update!(song)
+    # do something
+  end
+end
+```
+
+Modules can be included and will simply run the declarations in the including class.
+
+```ruby
+class Create::Admin < Create
+  include ExtendedCreate
+
+  # contract has :title and :id now.
+```
+
+Modules are often used to modify an existing operation for admin or signed-in roles.
+
+[Learn more](http://trailblazerb.org/gems/operation/inheritance.html)
+
+
 ## Form API
 
 Usually, an operation has a form object.

data/Rakefile

@@ -6,7 +6,7 @@ default_task = Rake::Task[:build]
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  test.test_files = FileList['test/*_test.rb']
+  test.test_files = FileList['test/*_test.rb', "test/operation/*_test.rb"]
   test.verbose = true
 end
 

data/lib/trailblazer/autoloading.rb

@@ -4,4 +4,5 @@ Trailblazer::Operation.class_eval do
   autoload :CRUD,       "trailblazer/operation/crud"
   autoload :Collection, "trailblazer/operation/collection"
   autoload :Dispatch,   "trailblazer/operation/dispatch"
+  autoload :Module,     "trailblazer/operation/module"
 end

data/lib/trailblazer/operation.rb

@@ -1,10 +1,6 @@
-require 'uber/builder'
-# TODO: extract all reform-contract stuff into optional module.
-require 'reform'
+require "uber/builder"
+require "reform"
 
-# TODO: OP[] without wrapper, OP.run with (eg for params)
-
-# to be documented: only implement #setup! when not using CRUD and when ::present needed (make example for simple Op without #setup!)
 
 module Trailblazer
   class Operation
@@ -70,12 +66,10 @@ module Trailblazer
 
     def present(*params)
       setup!(*params)
-
-      @contract = contract_for(nil, @model)
+      contract!
       self
     end
 
-    attr_reader :contract
     attr_reader :model
 
     def errors
@@ -86,6 +80,10 @@ module Trailblazer
       @valid
     end
 
+    def contract(*args)
+      contract!(*args)
+    end
+
   private
     def setup!(*params)
       setup_params!(*params)
@@ -105,8 +103,8 @@ module Trailblazer
     def setup_params!(*params)
     end
 
-    def validate(params, model, contract_class=nil)
-      @contract = contract_for(contract_class, model)
+    def validate(params, model=nil, contract_class=nil)
+      contract!(model, contract_class)
 
       if @valid = validate_contract(params)
         yield contract if block_given?
@@ -133,8 +131,15 @@ module Trailblazer
 
     # Instantiate the contract, either by using the user's contract passed into #validate
     # or infer the Operation contract.
-    def contract_for(contract_class, *model)
-      (contract_class || self.class.contract_class).new(*model)
+    def contract_for(model=nil, contract_class=nil)
+      model          ||= self.model
+      contract_class ||= self.class.contract_class
+
+      contract_class.new(model)
+    end
+
+    def contract!(*args)
+      @contract ||= contract_for(*args)
     end
 
     class InvalidContract < RuntimeError
@@ -143,9 +148,3 @@ module Trailblazer
 end
 
 require 'trailblazer/operation/crud'
-
-# run
-#   setup
-#   process
-#     contract
-#     validate

data/lib/trailblazer/operation/controller.rb

@@ -12,9 +12,7 @@ private
     yield @operation if block_given?
   end
 
-  # Doesn't run #validate.
-  # TODO: allow only_setup.
-  # TODO: dependency to CRUD (::model_name)
+  # Doesn't run #process.
   def present(operation_class, params=self.params)
     res, op = operation!(operation_class, params) { [true, operation_class.present(params)] }
 

data/lib/trailblazer/operation/module.rb

@@ -0,0 +1,29 @@
+module Trailblazer::Operation::Module
+  def self.included(base)
+    base.extend ClassMethods
+    base.extend Included
+  end
+
+  module Included # TODO: use representable's inheritance mechanism.
+    def included(base)
+      super
+      instructions.each { |cfg|
+        method  = cfg[0]
+        args    = cfg[1].dup
+        block   = cfg[2]
+        # options = args.extract_options!.dup # we need to duplicate options has as AM::Validations messes it up later.
+
+        base.send(method, *args, &block) } # property :name, {} do .. end
+    end
+  end
+
+  module ClassMethods
+    def method_missing(method, *args, &block)
+      instructions << [method, args, block]
+    end
+
+    def instructions
+      @instructions ||= []
+    end
+  end
+end

data/lib/trailblazer/version.rb

@@ -1,3 +1,3 @@
 module Trailblazer
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/test/module_test.rb

@@ -0,0 +1,93 @@
+require 'test_helper'
+require "trailblazer/operation/module"
+require "trailblazer/operation/dispatch"
+
+class OperationModuleTest < MiniTest::Spec
+  Song = Struct.new(:name, :artist)
+  Artist = Struct.new(:id, :full_name)
+
+  class Create < Trailblazer::Operation
+    include Trailblazer::Operation::Dispatch
+
+    contract do
+      property :name
+      property :artist, populate_if_empty: Artist do
+        property :id
+      end
+    end
+
+    callback do
+      on_change :notify_me!
+    end
+
+    def process(params)
+      @model = Song.new
+
+      validate(params, @model) do
+        contract.sync
+
+        dispatch!
+      end
+    end
+
+    def dispatched
+      @dispatched ||= []
+    end
+
+  private
+    def notify_me!(*)
+      dispatched << :notify_me!
+    end
+  end
+
+
+  module SignedIn
+    include Trailblazer::Operation::Module
+
+    contract do
+      property :artist, inherit: true do
+        property :full_name
+      end
+    end
+
+    callback do
+      on_change :notify_you!
+    end
+
+    def notify_you!(*)
+      dispatched << :notify_you!
+    end
+  end
+
+
+  class Update < Create
+    callback do
+      on_change :notify_them!
+    end
+
+    include SignedIn
+
+    def notify_them!(*)
+      dispatched << :notify_them!
+    end
+  end
+
+
+  it do
+    op = Create.({name: "Feelings", artist: {id: 1, full_name: "The Offspring"}})
+
+    op.dispatched.must_equal [:notify_me!]
+    op.model.name.must_equal "Feelings"
+    op.model.artist.id.must_equal 1
+    op.model.artist.full_name.must_equal nil # property not declared.
+  end
+
+  it do
+    op = Update.({name: "Feelings", artist: {id: 1, full_name: "The Offspring"}})
+
+    op.dispatched.must_equal [:notify_me!, :notify_them!, :notify_you!]
+    op.model.name.must_equal "Feelings"
+    op.model.artist.id.must_equal 1
+    op.model.artist.full_name.must_equal "The Offspring" # property declared via Module.
+  end
+end

data/test/operation/contract_test.rb

@@ -0,0 +1,30 @@
+require "test_helper"
+
+
+class OperationContractTest < MiniTest::Spec
+
+  class Operation < Trailblazer::Operation
+    contract do
+      property :id
+      property :title
+      property :length
+    end
+
+    def process(params)
+      @model = Struct.new(:id, :title, :length).new
+
+      contract.id = 1
+      validate(params) do
+        contract.length = 3
+      end
+    end
+  end
+
+  # allow using #contract before #validate.
+  it do
+    op = Operation.(title: "Beethoven")
+    op.contract.id.must_equal 1
+    op.contract.title.must_equal "Beethoven"
+    op.contract.length.must_equal 3
+  end
+end

data/test/rails/fake_app/song/operations.rb

@@ -57,12 +57,9 @@ class Band < ActiveRecord::Base
       end
     end
 
+    require "representable/json"
     class JSON < self
       include Representer
-      require "reform/form/json"
-      contract do
-        include Reform::Form::JSON # this allows deserialising JSON.
-      end
 
       representer do
         collection :songs, inherit: true, render_empty: false # tested in ControllerPresentTest.
@@ -77,17 +74,9 @@ class Band < ActiveRecord::Base
       end
     end
 
-    # TODO: wait for uber 0.0.10 and @dutow.
-    # builds -> (params)
-    #   return JSON if params[:format] == "json"
-    #   return Admin if params[:admin]
-    # end
-    builds do |params|
-      if params[:format] == "json"
-        JSON
-      elsif params[:admin]
-        Admin
-      end
+    builds -> (params) do
+      return JSON if params[:format] == "json"
+      return Admin if params[:admin]
     end
   end
 

data/test/rails/test_helper.rb

@@ -1,4 +1,9 @@
 require 'trailblazer'
 require 'minitest/autorun'
 
-require 'fake_app/rails_app.rb'
+require "reform/form/active_model/validations"
+Reform::Form.class_eval do
+  include Reform::Form::ActiveModel::Validations
+end
+
+require 'fake_app/rails_app.rb'

data/test/test_helper.rb

@@ -55,3 +55,8 @@ class MiniTest::Spec
   end
 end
 
+
+require "reform/form/active_model/validations"
+Reform::Form.class_eval do
+  include Reform::Form::ActiveModel::Validations
+end

data/trailblazer.gemspec

@@ -1,4 +1,3 @@
-# coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'trailblazer/version'
@@ -26,7 +25,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest"
-  # spec.add_development_dependency "minitest-spec-rails" # TODO: can anyone make this work (test/rails).
   spec.add_development_dependency "sidekiq", "~> 3.1.0"
   spec.add_development_dependency "actionpack", '>= 3.0.0' # Rails is optional.
   spec.add_development_dependency "rails"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-03 00:00:00.000000000 Z
+date: 2015-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uber
@@ -208,6 +208,7 @@ files:
 - lib/trailblazer/operation/controller/active_record.rb
 - lib/trailblazer/operation/crud.rb
 - lib/trailblazer/operation/dispatch.rb
+- lib/trailblazer/operation/module.rb
 - lib/trailblazer/operation/representer.rb
 - lib/trailblazer/operation/responder.rb
 - lib/trailblazer/operation/uploaded_file.rb
@@ -219,6 +220,8 @@ files:
 - test/dispatch_test.rb
 - test/fixtures/apotomo.png
 - test/fixtures/cells.png
+- test/module_test.rb
+- test/operation/contract_test.rb
 - test/operation_test.rb
 - test/rails/controller_test.rb
 - test/rails/endpoint_test.rb
@@ -271,6 +274,8 @@ test_files:
 - test/dispatch_test.rb
 - test/fixtures/apotomo.png
 - test/fixtures/cells.png
+- test/module_test.rb
+- test/operation/contract_test.rb
 - test/operation_test.rb
 - test/rails/controller_test.rb
 - test/rails/endpoint_test.rb