trailblazer 0.0.1 → 0.1.0

data/Rakefile

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

data/THOUGHTS

@@ -0,0 +1,12 @@
+by adding new abstraction layers
+* automatical think about interfaces
+* testability
+* more optional features, e.g. by using a representer you get HAL etc for free once included. how would that work with rabl? or easy nested forms with reform
+
+the less associations in models the better
+
+hi-level APIs: Invoice::Flow instead of creating I:Item out-of-sync
+  if your factories have 5 lines or more, your API is wrong, (Invoice::Flow)
+
+
+i don't wanna show anti-patterns, i wanna show how you can make things work.

data/TODO.md

@@ -0,0 +1,6 @@
+* allow `Op[{body: "Great!"}, {additional: true}]` to save merge.
+* make `Op[]` not require wrap like `comment: {}`
+* in tests, make Op[].model return the reloaded model!
+
+* don't pass contract in validate, we have #contract.
+* abstract validate/success/fail into methods to make it easily overrideable.

data/gemfiles/Gemfile.rails

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gemspec path: '../'
+
+gem "railties"
+gem "activerecord"
+gem "sqlite3"

data/gemfiles/Gemfile.rails.lock

@@ -0,0 +1,99 @@
+PATH
+  remote: ../
+  specs:
+    trailblazer (0.0.1)
+      actionpack (>= 3.0.0)
+      reform (= 1.2.0.beta1)
+      representable (>= 2.1.1, < 2.2.0)
+      uber (>= 0.0.10)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionpack (4.1.1)
+      actionview (= 4.1.1)
+      activesupport (= 4.1.1)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
+    actionview (4.1.1)
+      activesupport (= 4.1.1)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+    activemodel (4.1.1)
+      activesupport (= 4.1.1)
+      builder (~> 3.1)
+    activerecord (4.1.1)
+      activemodel (= 4.1.1)
+      activesupport (= 4.1.1)
+      arel (~> 5.0.0)
+    activesupport (4.1.1)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    arel (5.0.1.20140414130214)
+    builder (3.2.2)
+    celluloid (0.16.0)
+      timers (~> 4.0.0)
+    connection_pool (2.0.0)
+    disposable (0.0.8)
+      representable (~> 2.0)
+      uber
+    erubis (2.7.0)
+    hitimes (1.2.2)
+    i18n (0.6.11)
+    json (1.8.1)
+    mini_portile (0.6.0)
+    minitest (5.4.2)
+    multi_json (1.10.1)
+    nokogiri (1.6.3.1)
+      mini_portile (= 0.6.0)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    railties (4.1.1)
+      actionpack (= 4.1.1)
+      activesupport (= 4.1.1)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.3.2)
+    redis (3.1.0)
+    redis-namespace (1.5.1)
+      redis (~> 3.0, >= 3.0.4)
+    reform (1.2.0.beta1)
+      activemodel
+      disposable (~> 0.0.5)
+      representable (~> 2.1.0)
+      uber (~> 0.0.8)
+    representable (2.1.3)
+      multi_json
+      nokogiri
+      uber (~> 0.0.7)
+    sidekiq (3.1.4)
+      celluloid (>= 0.15.2)
+      connection_pool (>= 2.0.0)
+      json
+      redis (>= 3.0.6)
+      redis-namespace (>= 1.3.1)
+    sqlite3 (1.3.9)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    timers (4.0.1)
+      hitimes
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    uber (0.0.10)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  bundler (~> 1.3)
+  minitest
+  railties
+  rake
+  sidekiq (~> 3.1.0)
+  sqlite3
+  trailblazer!

data/lib/trailblazer.rb

@@ -1,4 +1,6 @@
+require "trailblazer/operation"
 require "trailblazer/version"
+require "uber/inheritable_attr"
 
 module Trailblazer
   # Your code goes here...

data/lib/trailblazer/autoloading.rb

@@ -0,0 +1,5 @@
+Trailblazer::Operation.class_eval do
+  autoload :Controller, 'trailblazer/operation/controller'
+  autoload :Responder,  'trailblazer/operation/responder'
+  autoload :CRUD,       'trailblazer/operation/crud'
+end

data/lib/trailblazer/operation.rb

@@ -0,0 +1,124 @@
+require 'uber/builder'
+# TODO: extract all reform-contract stuff into optional module.
+require 'reform'
+
+# TODO: OP[] without wrapper, OP.run with (eg for params)
+
+module Trailblazer
+  class Operation
+    extend Uber::InheritableAttr
+    inheritable_attr :contract_class
+    self.contract_class = Reform::Form.clone
+    self.contract_class.class_eval do
+      def self.name # FIXME: don't use ActiveModel::Validations in Reform, it sucks.
+        # for whatever reason, validations climb up the inheritance tree and require _every_ class to have a name (4.1).
+        "Reform::Form"
+      end
+    end
+
+    class << self
+      def run(*params, &block) # Endpoint behaviour
+        res, op = build_operation_class(*params).new.run(*params)
+
+        if block_given?
+          yield op if res
+          return op
+        end
+
+        [res, 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_class(*params).new(:raise_on_invalid => true).run(*params).last
+      end
+      alias_method :[], :call
+
+      # Runs #process without validate and returns the form object.
+      def present(*params)
+        build_operation_class(*params).new(:validate => false).run(*params).last
+      end
+
+      def contract(&block)
+        contract_class.class_eval(&block)
+      end
+
+
+    private
+      def build_operation_class(*params)
+        class_builder.call(*params) # Uber::Builder::class_builder
+      end
+    end
+
+    include Uber::Builder
+
+
+    def initialize(options={})
+      @valid            = true
+      # DISCUSS: use reverse_merge here?
+      @validate         = options[:validate] == false ? false : true
+      @raise_on_invalid = options[:raise_on_invalid] || false
+    end
+
+    #   Operation.run(body: "Fabulous!") #=> [true, <Comment body: "Fabulous!">]
+    def run(*params)
+      setup!(*params) # where do we assign/find the model?
+
+      [process(*params), valid?].reverse
+    end
+
+    attr_reader :contract
+
+    def valid?
+      @valid
+    end
+
+  private
+
+    def setup!(*params)
+    end
+
+    def validate(params, model, contract_class=nil) # NOT to be overridden?!! it creates Result for us.
+
+      @contract = contract_for(contract_class, model)
+
+      return self unless @validate # Op.contract will return here.
+
+      if @valid = contract.validate(params)
+        yield contract if block_given?
+      else
+        raise!(contract)
+      end
+
+      self
+    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 @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(contract_class, *model)
+      (contract_class || self.class.contract_class).new(*model)
+    end
+
+    class InvalidContract < RuntimeError
+    end
+  end
+end
+
+require 'trailblazer/operation/crud'
+
+# run
+#   setup
+#   process
+#     contract
+#     validate

data/lib/trailblazer/operation/controller.rb

@@ -0,0 +1,76 @@
+module Trailblazer::Operation::Controller
+  # TODO: test me.
+
+private
+  def form(operation_class, params=self.params) # consider private.
+    process_params!(params)
+
+    @operation = operation_class.new(:validate => false).run(params).last # FIXME: make that available via Operation.
+    @form      = @operation.contract
+    @model     = @operation.model
+
+    yield @operation if block_given?
+  end
+
+  # Doesn't run #validate.
+  # TODO: allow only_setup.
+  # TODO: dependency to CRUD (::model_name)
+  def present(operation_class, params=self.params)
+    res, op = operation!(operation_class, params) { [true, operation_class.present(params)] }
+
+    yield op if block_given?
+    respond_with op
+  end
+
+  # full-on Op[]
+  # Note: this is not documented on purpose as this concept is experimental. I don't like it too much and prefer
+  # returns in the valid block.
+  class Else
+    def initialize(op, run)
+      @op  = op
+      @run = run
+    end
+
+    def else
+      yield @op if @run
+    end
+  end
+
+  # Endpoint::Invocation
+  def run(operation_class, params=self.params, &block)
+    res, op = operation!(operation_class, params) { operation_class.run(params) }
+
+    yield op if res and block_given?
+
+    Else.new(op, !res)
+  end
+
+  # The block passed to #respond is always run, regardless of the validity result.
+  def respond(operation_class, params=self.params, &block)
+    res, op = operation!(operation_class, params) { operation_class.run(params) }
+
+    return respond_with op if not block_given?
+    respond_with op, &Proc.new { |formats| block.call(op, formats) } if block_given?
+  end
+
+  def process_params!(params)
+  end
+
+  # Normalizes parameters and invokes the operation (including its builders).
+  def operation!(operation_class, params)
+    process_params!(params)
+
+    unless request.format == :html
+      # this is what happens:
+      # respond_with Comment::Update::JSON.run(params.merge(comment: request.body.string))
+      concept_name = operation_class.model_class # this could be renamed to ::concept_class soon.
+      params.merge!(concept_name => request.body.string)
+    end
+
+    res, @operation = yield # Create.run(params)
+    @form  = @operation.contract
+    @model = @operation.model
+
+    [res, @operation] # DISCUSS: do we need result here? or can we just go pick op.valid?
+  end
+end

data/lib/trailblazer/operation/crud.rb

@@ -0,0 +1,61 @@
+module Trailblazer
+  class Operation
+    # The CRUD module will automatically create/find models for the configured +action+.
+    # It adds a public  +Operation#model+ reader to access the model (after performing).
+    module CRUD
+      attr_reader :model
+
+      def self.included(base)
+        base.extend Uber::InheritableAttr
+        base.inheritable_attr :config
+        base.config = {}
+
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def model(name, action=nil)
+          self.config[:model] = name
+          action(action) if action # coolest line ever.
+        end
+
+        def action(name)
+          self.config[:action] = name
+        end
+
+        def action_name # considered private.
+          self.config[:action] or :create
+        end
+
+        def model_class # considered private.
+          self.config[:model] or raise "[Trailblazer] You didn't call Operation::model." # TODO: infer model name.
+        end
+      end
+
+
+      # #validate no longer accepts a model since this module instantiates it for you.
+      def validate(params, *args)
+        super(params, @model, *args)
+      end
+
+    private
+      def setup!(params)
+        @model ||= instantiate_model(params)
+      end
+
+      def instantiate_model(params)
+        send("#{self.class.action_name}_model", params)
+      end
+
+      def create_model(params)
+        self.class.model_class.new
+      end
+
+      def update_model(params)
+        self.class.model_class.find(params[:id])
+      end
+
+      alias_method :find_model, :update_model
+    end
+  end
+end

data/lib/trailblazer/operation/representer.rb

@@ -0,0 +1,18 @@
+module Trailblazer::Operation::Representer
+  # TODO: test me.
+
+  def self.included(base)
+    base.extend Uber::InheritableAttr
+    base.inheritable_attr :representer_class
+    # TODO: allow representer without contract?!
+    # TODO: we have to extract the schema here, not subclass the contract.
+    base.representer_class = Class.new(base.contract_class.representer_class)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def representer(&block)
+      representer_class.class_eval(&block)
+    end
+  end
+end