trailblazer 1.1.1 → 2.1.0

data/README.md

@@ -1,25 +1,34 @@
 # Trailblazer
 
-_Trailblazer is a thin layer on top of Rails. It gently enforces encapsulation, an intuitive code structure and gives you an object-oriented architecture._
+_Trailblazer provides new high-level abstractions for Ruby frameworks. It gently enforces encapsulation, an intuitive code structure and approaches the modeling of complex business workflows with a functional mind-set._
 
 [![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
 [![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)
+[![Open Source Helpers](https://www.codetriage.com/trailblazer/trailblazer/badges/users.svg)](https://www.codetriage.com/trailblazer/trailblazer)
 
+## Documentation
+
+**This document discusses Trailblazer 2.1.** An overview about the additions are [on our website](http://2019.trailblazer.to/2.1/docs/trailblazer.html#trailblazer-2-1-migration).
+
+We're working on several new example applications!
+
+* *Refactoring to Trailblazer* discusses how the cfp-app is converted into a TRB app.
+* *BPMN and workflows* shows in-detail how the new 2.1 features in Trailblazer are used.
+
+The [1.x documentation is here](http://trailblazer.to/gems/operation/1.1/).
 
 ## Trailblazer In A Nutshell
 
 1. All business logic is encapsulated in [operations](#operation) (service objects).
-  * An optional Reform [form](#validations) object in the operation deserializes and validates input. The form object can also be used for rendering.
-  * An optional [policy](#policies) object blocks unauthorized users from running the operation.
-  * Optional [callback](#callbacks) objects allow declaring post-processing logic.
 3. [Controllers](#controllers) instantly delegate to an operation. No business code in controllers, only HTTP-specific logic.
 4. [Models](#models) are persistence-only and solely define associations and scopes. No business code is to be found here. No validations, no callbacks.
 5. The presentation layer offers optional [view models](#views) (Cells) and [representers](#representers) for document APIs.
+6. More complex business flows and life-cycles are modeled using workflows.
 
 Trailblazer is designed to handle different contexts like user roles by applying [inheritance](#inheritance) between and [composing](#composing) of operations, form objects, policies, representers and callbacks.
 
-Wanna see some code? Jump [right here](#controllers)!
+Want code? Jump [right here](#controllers)!
 
 ## Mission
 
@@ -31,36 +40,33 @@ Again, you can pick which layers you want. Trailblazer doesn't impose technical
 
 Trailblazer is no "complex web of objects and indirection". It solves many problems that have been around for years with a cleanly layered architecture. Only use what you like. And that's the bottom line.
 
-## Trailblazer Likes 'Em All
-
-Since Trailblazer decouples the High-Level Stack from the framework, it runs with virtually any Ruby framework. We are constantly working on documenting how to do that.
-
-* Trailblazer with Rails [Book](http://trailblazer.to/books/trailblazer.html) | [Repository](https://github.com/apotonick/gemgem-trbrb)
-* Trailblazer with Sinatra [Guide](http://trailblazer.to/guides/sinatra/getting-started.html) | [Repository](https://github.com/apotonick/gemgem-sinatra)
-* Trailblazer with Hanami - coming soon!
-* Trailblazer with Roda - coming soon!
-* Trailblazer with Grape - coming _very_ soon!
+## Concepts over Technology
 
-
-## A Concept-Driven OOP Framework
-
-Trailblazer offers you a new, more intuitive file layout in Rails apps where you structure files by *concepts*.
+Trailblazer offers you a new, more intuitive file layout in applications.
 
 ```
 app
 ├── concepts
-│   ├── comment
-│   │   ├── cell.rb
-│   │   ├── views
+│   ├── song
+│   │   ├── operation
+│   │   │   ├── create.rb
+│   │   │   ├── update.rb
+│   │   ├── contract
+│   │   │   ├── create.rb
+│   │   │   ├── update.rb
+│   │   ├── cell
+│   │   │   ├── show.rb
+│   │   │   ├── index.rb
+│   │   ├── view
 │   │   │   ├── show.haml
-│   │   │   ├── list.haml
-│   │   ├── assets
-│   │   │   ├── comment.css.sass
-│   │   ├── operation.rb
-│   │   ├── twin.rb
+│   │   │   ├── index.rb
+│   │   │   ├── song.css.sass
 ```
 
-Files, classes and views that logically belong to one _concept_ are kept in one place. You are free to use additional namespaces within a concept. Trailblazer tries to keep it as simple as possible, though.
+Instead of grouping by technology, classes and views are structured by *concept*, and then by technology. A concept can relate to a model, or can be a completely abstract concern such as `invoicing`.
+
+Within a concept, you can have any level of nesting. For example, `invoicing/pdf/` could be one.
+
 
 ## Architecture
 
@@ -68,7 +74,7 @@ Trailblazer extends the conventional MVC stack in Rails. Keep in mind that addin
 
 The opposite is the case: Controller, view and model become lean endpoints for HTTP, rendering and persistence. Redundant code gets eliminated by putting very little application code into the right layer.
 
-![The Trailblazer stack.](https://raw.github.com/apotonick/trailblazer/master/doc/Trb-The-Stack.png)
+![The Trailblazer stack.](https://raw.github.com/apotonick/trailblazer/master/doc/operation-2017.png)
 
 ## Routing
 
@@ -76,7 +82,7 @@ Trailblazer uses Rails routing to map URLs to controllers, because it works.
 
 ```ruby
 Rails.application.routes.draw do
-  resources :comments
+  resources :songs
 end
 ```
 
@@ -85,23 +91,25 @@ end
 Controllers are lean endpoints for HTTP. They do not contain any business logic. Actions immediately dispatch to an operation.
 
 ```ruby
-class CommentsController < ApplicationController
+class SongsController < ApplicationController
   def create
-    run Comment::Create # Comment::Create is an operation class.
+    run Song::Create # Song::Create is an operation class.
   end
+end
 ```
 
 The `#run` method invokes the operation. It allows you to run a conditional block of logic if the operation was successful.
 
 ```ruby
-class CommentsController < ApplicationController
+class SongsController < ApplicationController
   def create
-    run Comment::Create do |op|
-      return redirect_to(comment_path op.model) # success!
+    run Song::Create do |op|
+      return redirect_to(song_path op.model) # success!
     end
 
     render :new # invalid. re-render form.
   end
+end
 ```
 
 Again, the controller only dispatchs to the operation and handles successful/invalid processing on the HTTP level. For instance by redirecting, setting flash messages, or signing in a user.
@@ -112,86 +120,39 @@ Again, the controller only dispatchs to the operation and handles successful/inv
 
 Operations encapsulate business logic and are the heart of a Trailblazer architecture.
 
-Operations don't know about HTTP or the environment. You could use an operation in Rails, Hanami, or Roda, it wouldn't know. This makes them an ideal replacement for test factories.
-
-An operation is not just a monolithic replacement for your business code. It's a simple orchestrator between the form object, models and your business code.
-
-```ruby
-class Comment::Create < Trailblazer::Operation
-  def process(params)
-    # do whatever you feel like.
-  end
-end
-```
-
-Operations only need to implement `#process` which receives the params from the caller.
-
-[Learn more.](http://trailblazer.to/gems/operation)
+The bare bones operation without any Trailblazery is implemented in [the `trailblazer-operation` gem](https://github.com/trailblazer/trailblazer-operation) and can be used without our stack.
 
-## Validations
+Operations don't know about HTTP or the environment. You could use an operation in Rails, Hanami, or Roda, it wouldn't know.
 
-In Trailblazer, an operation (usually) has a form object which is simply a `Reform::Form` class. All the [API documented in Reform](https://github.com/apotonick/reform) can be applied and used.
-
-The operation makes use of the form object using the `#validate` method.
+An operation is not just a monolithic replacement for your business code. It's a simple orchestrator between the form objects, models, your business code and all other layers needed to get the job done.
 
 ```ruby
-class Comment::Create < Trailblazer::Operation
-  contract do
-    # this is a Reform::Form class!
-    property :body, validates: {presence: true}
-  end
+class Song::Create < Trailblazer::Operation
+  step :model
+  step :validate
 
-  def process(params)
-    @model = Comment.new
+  def model(ctx, **)
+    # do whatever you feel like.
+    ctx[:model] = Song.new
+  end
 
-    validate(params[:comment], @model) do |f|
-      f.save
-    end
+  def validate(ctx, params:, **)
+    # ..
   end
 end
 ```
 
-The contract (aka _form_) is defined in the `::contract` block. You can implement nested forms, default values, validations, and everything else Reform provides.
-
-In the `#process` method you can define your business logic.
+Operations define the flow of their logic using the DSL and implement the particular steps with pure Ruby.
 
-[Learn more.](http://trailblazer.to/gems/operation/api.html)
-
-## Callbacks
-
-Post-processing logic (also known as _callbacks_) is configured in operations.
-
-Callbacks can be defined in groups. They use the form object's state tracking to find out whether they should be run.
+You cannot instantiate them per design. The only way to invoke them is `call`.
 
 ```ruby
-class Comment::Create < Trailblazer::Operation
-  include Callback
-  callback(:after_save) do
-    on_change :markdownize_body! # this is only run when the form object has changed.
-  end
+Song::Create.(params: {whatever: "goes", in: "here"})
 ```
 
-Callbacks are never triggered automatically, you have to invoke them! This is called _Imperative Callback_.
+Their high degree of encapsulation makes them a [replacement for test factories](#test), too.
 
-```ruby
-class Comment::Create < Trailblazer::Operation
-  include Callback
-  def process(params)
-    validate(params) do
-      contract.save
-      callback!(:after_save) # run markdownize_body!, but only if form changed.
-    end
-  end
-
-  def markdownize_body!(comment)
-    comment.body = Markdownize.(comment.body)
-  end
-end
-```
-
-No magical triggering of unwanted logic anymore, but explicit invocations where you want it.
-
-[Learn more.](http://trailblazer.to/gems/operation/callback.html)
+[Learn more.](http://trailblazer.to/gems/operation)
 
 ## Models
 
@@ -200,7 +161,7 @@ Models for persistence can be implemented using any ORM you fancy, for instance
 In Trailblazer, models are completely empty. They solely contain associations and finders. No business logic is allowed in models.
 
 ```ruby
-class Comment < ActiveRecord::Base
+class Song < ActiveRecord::Base
   belongs_to :thing
 
   scope :latest, lambda { all.limit(9).order("id DESC") }
@@ -209,78 +170,6 @@ end
 
 Only operations and views/cells can access models directly.
 
-## Policies
-
-You can abort running an operation using a policy. "[Pundit](https://github.com/elabs/pundit)-style" policy classes define the rules.
-
-```ruby
-class Comment::Policy
-  def initialize(user, comment)
-    @user, @comment = user, comment
-  end
-
-  def create?
-    @user.admin?
-  end
-end
-```
-
-The rule is enabled via the `::policy` call.
-
-```ruby
-class Comment::Create < Trailblazer::Operation
-  include Policy
-
-  policy Comment::Policy, :create?
-```
-
-The policy is evaluated in `#setup!`, raises an exception if `false` and suppresses running `#process`.
-
-[Learn more.](http://trailblazer.to/gems/operation/policy.html)
-
-## Views
-
-View rendering can happen using the controller as known from Rails. This is absolutely fine for simple views.
-
-More complex UI logic happens in _View Models_ as found in [Cells](https://github.com/apotonick/cells). View models also replace helpers.
-
-The operation's form object can be rendered in views, too.
-
-```ruby
-class CommentsController < ApplicationController
-  def new
-    form Comment::Create # will assign the form object to @form.
-  end
-```
-
-Since Reform objects can be passed to form builders, you can use the operation to render and process the form!
-
-```haml
-= simple_form_for @form do |f|
-  = f.input :body
-```
-
-
-## Representers
-
-Operations can use representers from [Roar](https://github.com/apotonick/roar) to serialize and parse JSON and XML documents for APIs.
-
-Representers can be inferred automatically from your contract, then may be refined, e.g. with hypermedia or a format like `JSON-API`.
-
-```ruby
-class Comment::Create < Trailblazer::Operation
-  representer do
-    # inherited :body
-    include Roar::JSON::HAL
-
-    link(:self) { comment_path(represented.id) }
-  end
-```
-
-The operation can then parse incoming JSON documents in `validate` and render a document via `to_json`.
-
-[Learn more.](http://trailblazer.to/gems/operation/representer.html)
-
 ## Tests
 
 In Trailblazer, you only have operation unit tests and integration smoke tests to test the operation/controller wiring.
@@ -288,19 +177,18 @@ In Trailblazer, you only have operation unit tests and integration smoke tests t
 Operations completely replace the need for leaky factories.
 
 ```ruby
-describe Comment::Update do
-  let(:comment) { Comment::Create.(comment: {body: "[That](http://trailblazer.to)!"}) }
+describe Song::Update do
+  let(:song) { Song::Create.(song: {body: "[That](http://trailblazer.to)!"}) }
+end
 ```
 
-## More
+## Workflows
 
-Trailblazer has many more architectural features such as
+Operations are a great way to clean up controllers and models. However, Trailblazer goes further and provides an approach to model entire life-cycles of business objects, such as "a song" or "the root user".
 
-* Polymorphic builders and operations
-* Inheritance and composition support
-* Polymorphic views
+Those workflows dramatically reduce the usage of control flow logic in your code and allow for visually designing and discussing flows.
 
-Check the project website and the book.
+Learn more about BPMN and workflows [on our website](https://2019.trailblazer.to/docs/workflow).
 
 ## Installation
 
@@ -309,16 +197,7 @@ The obvious needs to be in your `Gemfile`.
 ```ruby
 gem "trailblazer"
 gem "trailblazer-rails" # if you are in rails.
-gem "cells"
+gem "trailblazer-cells"
 ```
 
 Cells is _not_ required per default! Add it if you use it, which is highly recommended.
-
-## The Book
-
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
-
-Please buy it: [Trailblazer - A new architecture for Rails](https://leanpub.com/trailblazer).
-
-The [demo application](https://github.com/apotonick/gemgem-trbrb) implements what we discuss in the book.
-

data/Rakefile

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

data/lib/trailblazer/version.rb

@@ -1,3 +1,5 @@
 module Trailblazer
-  VERSION = "1.1.1"
+  module Version
+    VERSION = "2.1.0"
+  end
 end

data/lib/trailblazer.rb

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

data/test/test_helper.rb

@@ -1,9 +1,38 @@
-require 'trailblazer'
-require 'minitest/autorun'
+require "pp"
+require "delegate"
+require "trailblazer"
+require "minitest/autorun"
 
+# TODO: convert tests to non-rails.
+require "reform"
 require "reform/form/active_model/validations"
 Reform::Form.class_eval do
   include Reform::Form::ActiveModel::Validations
 end
+# require "trailblazer/deprecation/context.rb"
 
-require "trailblazer/operation/model"
+module Mock
+  class Result
+    def initialize(bool); @bool = bool end
+    def success?; @bool end
+    def errors; ["hihi"] end
+  end
+end
+
+module Test
+  module ReturnCall
+    def self.included(includer)
+      includer._insert :_insert, ReturnResult, {replace: Trailblazer::Operation::Result::Build}, ReturnResult, ""
+    end
+  end
+  ReturnResult = ->(last, input, options) { input }
+end
+
+Minitest::Spec::Operation = Trailblazer::Operation
+
+Memo = Struct.new(:id, :body) do
+  def self.find(id)
+    return new(id, "Yo!") if id
+    nil
+  end
+end

data/trailblazer.gemspec

@@ -4,31 +4,27 @@ require 'trailblazer/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "trailblazer"
-  spec.version       = Trailblazer::VERSION
+  spec.version       = Trailblazer::Version::VERSION
   spec.authors       = ["Nick Sutterer"]
   spec.email         = ["apotonick@gmail.com"]
-  spec.description   = %q{A high-level, modular architecture for Ruby framworks with domain and form objects, view models, twin decorators and representers.}
+  spec.description   = %q{A high-level architecture introducing new abstractions such as operations and control flow, form objects and policies.}
   spec.summary       = %q{A high-level architecture for Ruby and Rails.}
   spec.homepage      = "http://trailblazer.to"
-  spec.license       = "MIT"
+  spec.license       = "LGPL-3.0"
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|doc)/})
+  end
+  spec.test_files    = `git ls-files -z test`.split("\x0")
   spec.require_paths = ["lib"]
 
-
-  spec.add_dependency "uber", ">= 0.0.15"
-  spec.add_dependency "reform", ">= 2.0.0", "< 3.0.0"
-  spec.add_dependency "declarative"
-
-  spec.add_development_dependency "activemodel" # for Reform::AM::V
+  spec.add_dependency "trailblazer-macro", ">= 2.1.0", "< 2.2.0"
+  spec.add_dependency "trailblazer-macro-contract", ">= 2.1.0", "< 2.2.0"
+  spec.add_dependency "trailblazer-operation" # TODO: why do we need this here?
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest"
-  spec.add_development_dependency "sqlite3"
-  spec.add_development_dependency "database_cleaner"
 
-  spec.add_development_dependency "roar"
+  spec.required_ruby_version = '>= 2.1.0'
 end