trailblazer-compat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f2156ecbbb4653bcc48e2fd0dca22528b7079e4f
+  data.tar.gz: 8558904f18e93de025483229552bd0ddc4f8134e
+SHA512:
+  metadata.gz: e41a477d030046014dce30b2aecef41efa6c5fa6bafa879e3b9a5037ed12d88ecfb53112f0840650f35b358bc6b7db112acfc7b84a9600d664dbe866906d35f1
+  data.tar.gz: 10bf310b9094eb11a0d0a431690afe9b528e145489cfacf7927e1a6d822aaa25c1b3a78501435fcc7f9eda3e31963eb095b060719a03d59df431bd2ce110e635

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.12.5

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in trailblazer-compat.gemspec
+gemspec
+
+gem "trailblazer", path: "../trailblazer"
+gem "trailblazer-operation", path: "../operation"

data/README.md

@@ -0,0 +1,76 @@
+# Trailblazer::Compat
+
+This gem provides a seamless-er™ upgrade from TRB 1.1 to 2.x.
+
+It allows to run both old TRB 1.1 operations along with new or refactored 2.x code in the same application, making it easier to upgrade operation code `step`-wise (no pun intended!) or add new TRB2 operations, workflows, etc. without having to change the old code.
+
+## Installation
+
+Your exisiting application's `Gemfile` should point to the new `trailblazer` gem.
+
+```ruby
+gem "trailblazer", ">= 2.0.0"
+gem "trailblazer-compat"
+```
+
+In a Rails application, you also need to pull the 1.x line of the `trailblazer-rails` gem.
+
+```ruby
+gem "trailblazer-rails", ">= 1.0.0"
+```
+
+## Upgrade Path / Overview
+
+The complete migration path is [documented here](http://trailblazer.to/gems/trailblazer/upgrading-1-to-2.html).
+
+1. You can keep old TRB1 operations.
+
+    ```ruby
+    # /app/concepts/song/create.rb
+    class Song
+      class Create < Trailblazer::Operation
+        model Song, :create
+        policy Song::Policy, :admin?
+
+        contract do
+          property :id
+          # ...
+        end
+
+        def process(params)
+          validate(params[:song]) do |form|
+            form.save
+          end
+        end
+      end
+    end
+    ```
+2. At any point, you can introduce new TRB2 operations or update old classes by inheriting from `Trailblazer::Operation.version(2)`.
+
+    ```ruby
+    # /app/concepts/song/create.rb
+    class Song
+      class Create < Trailblazer::Operation.version(2)
+        class Form < Reform::Form
+          property :id
+          # ...
+        end
+
+        class New < Trailblazer::Operation.version(2)
+          step Model( Song, :new )
+          step Policy::Pundit( Song::Policy, :admin? )
+          step Contract::Build( constant: Form )
+        end
+
+        step Nested(New)
+        step Contract::Validate( key: :admin )
+        step Contract::Persist()
+      end
+    end
+    ```
+
+3. Should you ever be finished updating your application, simply remove the `trailblazer-compat` gem from the `Gemfile`. You can then safely delete `.version(2)` across all files.
+
+## Development Status
+
+The `compat` gem tries to make the transition to newer versions as painless as possible. However, if you run into any problems specific to your application, please [don't hesitate to contact us](https://gitter.im/trailblazer/chat). Pull requests (even ugly hacks) are appreciated in this gem, and this gem only.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/lib/trailblazer/1.1/autoloading.rb

@@ -0,0 +1,15 @@
+Trailblazer::V1_1.class_eval do
+  autoload :NotAuthorizedError, "trailblazer/1.1/operation/policy"
+end
+
+Trailblazer::V1_1::Operation.class_eval do
+  autoload :Controller, "trailblazer/1.1/operation/controller"
+  autoload :Model,      "trailblazer/1.1/operation/model"
+  autoload :Collection, "trailblazer/1.1/operation/collection"
+  autoload :Dispatch,   "trailblazer/1.1/operation/dispatch" # TODO: remove in 1.2.
+  autoload :Callback,   "trailblazer/1.1/operation/callback"
+  autoload :Module,     "trailblazer/1.1/operation/module"
+  autoload :Representer,"trailblazer/1.1/operation/representer"
+  autoload :Policy,     "trailblazer/1.1/operation/policy"
+  autoload :Resolver,   "trailblazer/1.1/operation/resolver"
+end

data/lib/trailblazer/1.1/endpoint.rb

@@ -0,0 +1,31 @@
+module Trailblazer::V1_1
+  # Encapsulates HTTP-specific logic needed before running an operation.
+  # Right now, all this does is #document_body! which figures out whether or not to pass the request body
+  # into params, so the operation can use a representer to deserialize the original document.
+  # To be used in Hanami, Roda, Rails, etc.
+  class Endpoint
+    def initialize(operation_class, params, request, options)
+      @operation_class = operation_class
+      @params          = params
+      @request         = request
+      @is_document     = options[:is_document]
+    end
+
+    def call
+      document_body! if @is_document
+      yield @params# Create.run(params)
+    end
+
+  private
+    attr_reader :params, :operation_class, :request
+
+    def document_body!
+      # this is what happens:
+      # respond_with Comment::Update::JSON.run(params.merge(comment: request.body.string))
+      concept_name = operation_class.model_class.to_s.underscore # this could be renamed to ::concept_class soon.
+      request_body = request.body.respond_to?(:string) ? request.body.string : request.body.read
+
+      params.merge!(concept_name => request_body)
+    end
+  end
+end

data/lib/trailblazer/1.1/operation.rb

@@ -0,0 +1,175 @@
+require "reform"
+
+module Trailblazer::V1_1
+  class Operation
+    require "trailblazer/1.1/operation/builder"
+    extend Builder # imports ::builder_class and ::build_operation.
+
+    extend Uber::InheritableAttr
+    inheritable_attr :contract_class
+    self.contract_class = Reform::Form.clone
+
+    class << self
+      def run(params, &block) # Endpoint behaviour
+        res, op = build_operation(params).run
+
+        if block_given?
+          yield op if res
+          return op
+        end
+
+        [res, op]
+      end
+
+      # Like ::run, but yield block when invalid.
+      def reject(*args)
+        res, op = run(*args)
+        yield op if res == false
+        op
+      end
+
+      # ::call only returns the Operation instance (or whatever was returned from #validate).
+      # This is useful in tests or in irb, e.g. when using Op as a factory and you already know it's valid.
+      def call(params)
+        build_operation(params, raise_on_invalid: true).run.last
+      end
+
+      def [](*args) # TODO: remove in 1.2.
+        warn "[Trailblazer] Operation[] is deprecated. Please use Operation.() and have a nice day."
+        call(*args)
+      end
+
+      # Runs #setup! but doesn't process the operation.
+      def present(params)
+        build_operation(params)
+      end
+
+      # This is a DSL method. Use ::contract_class and ::contract_class= for the explicit version.
+      #   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(constant=nil, &block)
+        return contract_class unless constant or block_given?
+
+        self.contract_class= Class.new(constant) if constant
+        contract_class.class_eval(&block) if block_given?
+      end
+    end
+
+
+    def initialize(params, options={})
+      @options          = options
+      @valid            = true
+
+      setup!(params) # assign/find the model
+    end
+
+    #   Operation.run(body: "Fabulous!") #=> [true, <Comment body: "Fabulous!">]
+    def run
+      process(@params)
+
+      [valid?, self]
+    end
+
+    attr_reader :model
+
+    def errors
+      contract.errors
+    end
+
+    def valid?
+      @valid
+    end
+
+    def contract(*args)
+      contract!(*args)
+    end
+
+  private
+    module Setup
+      attr_writer :model
+
+      def setup!(params)
+        params = assign_params!(params)
+        setup_params!(params)
+        build_model!(params)
+        params # TODO: test me.
+      end
+
+      def assign_params!(params)
+        @params = params!(params)
+      end
+
+      # Overwrite #params! if you need to change its structure, by returning a new params object
+      # from this method.
+      # This is helpful if you don't want to change the original via #setup_params!.
+      def params!(params)
+        params
+      end
+
+      def setup_params!(params)
+      end
+
+      def build_model!(*args)
+        assign_model!(*args) # @model = ..
+        setup_model!(*args)
+      end
+
+      def assign_model!(*args)
+        @model = model!(*args)
+      end
+
+      # Implement #model! to find/create your operation model (if required).
+      def model!(params)
+      end
+
+      # Override to add attributes that can be infered from params.
+      def setup_model!(params)
+      end
+    end
+    include Setup
+
+    def validate(params, model=nil, contract_class=nil)
+      contract!(model, contract_class)
+
+      if @valid = validate_contract(params)
+        yield contract if block_given?
+      else
+        raise!(contract)
+      end
+
+      @valid
+    end
+
+    def validate_contract(params)
+      contract.validate(params)
+    end
+
+    def invalid!(result=self)
+      @valid = false
+      result
+    end
+
+    # When using Op.(), an invalid contract will raise an exception.
+    def raise!(contract)
+      raise InvalidContract.new(contract.errors.to_s) if @options[:raise_on_invalid]
+    end
+
+    # Instantiate the contract, either by using the user's contract passed into #validate
+    # or infer the Operation contract.
+    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
+    end
+  end
+end

data/lib/trailblazer/1.1/operation/builder.rb

@@ -0,0 +1,26 @@
+require "uber/builder"
+
+# Allows to add builders via ::builds.
+module Trailblazer::V1_1::Operation::Builder
+  def self.extended(extender)
+    extender.send(:include, Uber::Builder)
+  end
+
+  def builder_class
+    @builders
+  end
+
+  def builder_class=(constant)
+    @builders = constant
+  end
+
+private
+  # Runs the builders for this operation class to figure out the actual class.
+  def build_operation_class(*args)
+    class_builder(self).(*args) # Uber::Builder::class_builder(context)
+  end
+
+  def build_operation(params, options={})
+    build_operation_class(params).new(params, options)
+  end
+end

data/lib/trailblazer/1.1/operation/callback.rb

@@ -0,0 +1,53 @@
+require "declarative"
+require "disposable/callback"
+
+module Trailblazer::V1_1::Operation::Callback
+  def self.included(base)
+    base.extend ClassMethods
+
+    base.extend Declarative::Heritage::Inherited
+    base.extend Declarative::Heritage::DSL
+  end
+
+  def callback!(name=:default, options={ operation: self, contract: contract, params: @params }) # FIXME: test options.
+    config  = self.class.callbacks.fetch(name) # TODO: test exception
+    group   = config[:group].new(contract)
+
+    options[:context] ||= (config[:context] == :operation ? self : group)
+    group.(options)
+
+    invocations[name] = group
+  end
+
+  def dispatch!(*args, &block)
+    callback!(*args, &block)
+  end
+
+  def invocations
+    @invocations ||= {}
+  end
+
+  module ClassMethods
+    def callbacks
+      @callbacks ||= {}
+    end
+
+    def callback(name=:default, constant=nil, &block)
+      return callbacks[name][:group] unless constant or block_given?
+
+      add_callback(name, constant, &block)
+    end
+
+  private
+    def add_callback(name, constant, &block)
+      heritage.record(:add_callback, name, constant, &block)
+
+      callbacks[name] ||= {
+        group:   Class.new(constant || Disposable::Callback::Group),
+        context: constant ? nil : :operation # `context: :operation` when the callback is inline. `context: group` otherwise.
+      }
+
+      callbacks[name][:group].class_eval(&block) if block_given?
+    end
+  end
+end

data/lib/trailblazer/1.1/operation/collection.rb

@@ -0,0 +1,6 @@
+module Trailblazer::V1_1::Operation::Collection
+  # Collection does not produce a contract.
+  def present
+    self
+  end
+end

data/lib/trailblazer/1.1/operation/controller.rb

@@ -0,0 +1,87 @@
+require "trailblazer/1.1/endpoint"
+
+module Trailblazer::V1_1::Operation::Controller
+private
+  def form(operation_class, options={})
+    run_v2_for(operation_class, options) and return
+
+    res, op, options = operation!(operation_class, options)
+    op.contract.prepopulate!(options) # equals to @form.prepopulate!
+
+    op.contract
+  end
+
+  # Provides the operation instance, model and contract without running #process.
+  # Returns the operation.
+  def present(operation_class, options={})
+    run_v2_for(operation_class, options) and return
+
+    res, op = operation!(operation_class, options.merge(skip_form: true))
+    op
+  end
+
+  def collection(*args)
+    res, op = operation!(*args)
+    @collection = op.model
+    op
+  end
+
+  def run(operation_class, options={}, &block)
+    run_v2_for(operation_class, options, &block) and return
+
+    res, op = operation_for!(operation_class, options) { |params| operation_class.run(params) }
+
+    yield op if res and block_given?
+
+    op
+  end
+
+  # The block passed to #respond is always run, regardless of the validity result.
+  def respond(operation_class, options={}, &block)
+    res, op = operation_for!(operation_class, options) { |params| operation_class.run(params) }
+    namespace = options.delete(:namespace) || []
+
+    return respond_with *namespace, op, options if not block_given?
+    respond_with *namespace, op, options, &Proc.new { |formats| block.call(op, formats) } if block_given?
+  end
+
+private
+  def operation!(operation_class, options={}) # or #model or #setup.
+    operation_for!(operation_class, options) { |params| [true, operation_class.present(params)] }
+  end
+
+  def process_params!(params)
+  end
+
+  # Override and return arbitrary params object.
+  def params!(params)
+    params
+  end
+
+  # Normalizes parameters and invokes the operation (including its builders).
+  def operation_for!(operation_class, options, &block)
+    params = options[:params] || self.params # TODO: test params: parameter properly in all 4 methods.
+    params = params!(params)
+    process_params!(params) # deprecate or rename to #setup_params!
+
+    res, op = Trailblazer::V1_1::Endpoint.new(operation_class, params, request, options).(&block)
+    setup_operation_instance_variables!(op, options)
+
+    [res, op, options.merge(params: params)]
+  end
+
+  def setup_operation_instance_variables!(operation, options)
+    @operation = operation
+    @model     = operation.model
+    @form      = operation.contract unless options[:skip_form]
+  end
+
+  def run_v2_for(operation_class, *args, &block)
+    if operation_class < Trailblazer::V2::Operation
+      # run_v2(operation_class, *args)
+      run_v2(operation_class, &block)
+      return true
+    end
+    false
+  end
+end