trailblazer 2.1.0.beta4 → 2.1.0.beta5

data/CHANGES.md

@@ -30,6 +30,10 @@ document Task API and define step API
 deprecate step->(options) ?
 injectable, per-operation step arguments strategy?
 
+# 2.1.0.beta5
+
+* All macros are now cleanly extracted to `trailblazer-macro` and `trailblazer-macro-contract`.
+
 # 2.1.0.beta4
 
 * Simple maintenance release to establish `activity-0.5.0`.

data/CONTRIBUTING.md

@@ -0,0 +1,170 @@
+# Contributing to Trailblazer
+Trailblazer is an open source project and we would love you to help us make it better.
+
+## Questions/Help
+If our [guides][guides] nor [docs][api-docs] can help you figure things out, and you're stuck, refrain from posting questions on github issues, and please just find us on the [trailblazer gitter chat][chat] and drop us a line.
+
+Keep in mind when asking questions though, an example will get you help faster than anything else you do.
+
+If you file an issue with a question, it will be closed. We're not trying to be mean, don't get us wrong, we're just trying to stay sane.
+
+## Reporting Issues
+A well formatted issue is appreciated, and goes a long way in helping us help you.
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a [Github issue][issues-link] by:
+  * Clearly describing the issue
+    * Provide a descriptive summary
+    * Provide sample code where possible (preferably in the form of a test, in a [Gist][gist] for bonus points)
+    * Explain the expected behavior
+    * Explain the actual behavior
+    * Provide steps to reproduce the actual behavior
+    * Provide your application's complete `Gemfile.lock` as text (in a [Gist][gist] for bonus points)
+    * Any relevant stack traces
+
+If you provide code, make sure it is formatted with the triple backticks (\`).
+
+At this point, we'd love to tell you how long it will take for us to respond, but we just don't know.
+
+## Pull requests
+We accept pull requests to Trailblazer for:
+
+* Adding documentation
+* Fixing bugs
+* Adding new features
+
+Not all features proposed will be added but we are open to having a conversation about a feature you are championing.
+
+###Here's a quick guide:
+#### Fork the Project
+Fork the [project repository][project-repo-link] on Github and check out your copy.
+
+```
+git clone https://github.com/YOUR_HANDLE/trailblazer.git
+cd trailblazer
+git remote add upstream https://github.com/trailblazer/trailblazer.git
+```
+
+#### Create a Topic Branch
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+#### Bundle and Test
+Run bundle install/update to gather any and all dependencies. Run the tests. This is to make sure your starting point works.
+
+```
+bundle install
+bundle exec rake
+```
+
+#### Write Tests
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [test][test-link].
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+#### Write Code
+Implement your feature or bug fix.
+
+Ruby style is enforced with [RuboCop](https://github.com/bbatsov/rubocop), run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+#### Write Documentation
+Document any external behavior in the [README](README.md).
+
+#### Commit Changes
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what has changed and why, but be brief.
+
+```
+git add your_filename.rb (File names to add content from, or fileglobs e.g. *.rb)
+git commit
+```
+
+#### Push
+```
+git push origin my-feature-branch
+```
+
+#### Make a Pull Request
+Go to https://github.com/YOUR_GH_HANDLE/trailblazer and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days, but no need to rush us if it takes longer.
+
+#### Rebase
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+#### Update CHANGELOG Again
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/trailblazer/trailblazer/pull/123): Your brief description - [@your_gh_handle](https://github.com/your_gh_handle).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+#### Check on Your Pull Request
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+## Releasing
+
+When you have release rights, please follow these rules.
+
+* When tagging a commit for a release, use the format `vX.X.X` for the tag, e.g. `git tag v2.1.0`.
+* The tagged commit **must contain the line** "Releasing vX.X.X" so it can be quickly spotted later in the commit list.
+
+#### What now?
+At this point you're waiting on us. Expect a conversation regarding your pull request; Questions, clarifications, and so on.
+
+Some things that will increase the chance that your pull request is accepted:
+* Use Trailblazer idioms and follow the Trailblazer idealogy
+* Include tests that fail without your code, and pass with it
+* Update the documentation, guides, etc.
+
+## What do we need help with?
+### Helping others!
+There are a lot of questions from people as they get started using Trailblazer. If you could **please do the following things**, that would really help:
+
+- Hang out on [the chat][chat]
+- Watch the [trailblazer repositories][repositories] for issues or requests that you could help with
+
+### Contributing to community
+- Create Macros!
+- Write blog posts!
+- Record screencasts
+- Write examples.
+
+### Contributing to the core
+- Tests are always helpful!
+- Any of the issues in GitHub, let us know if you have some time to fix one.
+
+## Thank You
+Please do know that we really appreciate and value your time and work.
+
+[gist]: https://gist.github.com
+[guides]: https://www.trailblazer.to
+[api-docs]: https://www.trailblazer.to/api-docs
+[chat]: https://gitter.im/trailblazer/chat
+[repositories]: https://github.com/trailblazer
+[test-link]: https://github.com/trailblazer/trailblazer/tree/master/test
+[project-repo-link]: https://github.com/trailblazer/trailblazer
+[issues-link]: https://www.github.com/trailblazer/trailblazer/issues

data/Gemfile

@@ -14,13 +14,16 @@ gem "dry-auto_inject"
 gem "dry-matcher"
 gem "dry-validation"
 
+# gem "trailblazer-operation", path: "../operation"
+gem "trailblazer-macro", github: "trailblazer/trailblazer-macro"
+gem "trailblazer-macro-contract", github: "trailblazer/trailblazer-macro-contract"
 gem "trailblazer-operation", path: "../operation"
 # gem "trailblazer-operation", github: "trailblazer/trailblazer-operation"
 
 gem "minitest-line"
 
 gem "rubocop", require: false
-# gem "trailblazer-activity", path: "../trailblazer-circuit"
+gem "trailblazer-activity", path: "../trailblazer-circuit"
 # gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"
 # gem "trailblazer-activity", path: "../trailblazer-circuit"
 # gem "trailblazer-activity", github: "trailblazer/trailblazer-activity"

data/README.md

@@ -42,7 +42,7 @@ Trailblazer offers you a new, more intuitive file layout in applications.
 ```
 app
 ├── concepts
-│   ├── comment
+│   ├── song
 │   │   ├── operation
 │   │   │   ├── create.rb
 │   │   │   ├── update.rb
@@ -55,7 +55,7 @@ app
 │   │   ├── view
 │   │   │   ├── show.haml
 │   │   │   ├── index.rb
-│   │   │   ├── comment.css.sass
+│   │   │   ├── song.css.sass
 ```
 
 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`.
@@ -81,7 +81,7 @@ Trailblazer uses Rails routing to map URLs to controllers, because it works.
 
 ```ruby
 Rails.application.routes.draw do
-  resources :comments
+  resources :songs
 end
 ```
 
@@ -90,9 +90,9 @@ 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
 ```
@@ -100,10 +100,10 @@ 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.
@@ -126,7 +126,7 @@ Operations don't know about HTTP or the environment. You could use an operation
 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
+class Song::Create < Trailblazer::Operation
   step :process!
 
   def process!(options)
@@ -140,44 +140,188 @@ Operations only need to define and implement steps, like the `#process!` steps.
 You cannot instantiate them per design. The only way to invoke them is `call`.
 
 ```ruby
-Comment::Create.call(whatever: "goes", in: "here")
+Song::Create.call(whatever: "goes", in: "here")
 # same as
-Comment::Create.(whatever: "goes", in: "here")
+Song::Create.(whatever: "goes", in: "here")
 ```
 
 Their high degree of encapsulation makes them a [replacement for test factories](#test), too.
 
 [Learn more.](http://trailblazer.to/gems/operation)
 
-## Validation
+### 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.
 
-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.
+```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
+```
 
-Validations can also be implemented in pure Dry-validation.
+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.
 
-The operation makes use of the form object using the `#validate` method.
+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
-class Comment::Create < Trailblazer::Operation
-  extend Contract::DSL
+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"]}
+```
 
-  contract do
-    # this is a Reform::Form class!
-    property :body, validates: {presence: true}
-  end
+#### 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.
 
-  step Model( Comment, :new )
-  step Contract::Build()
-  step Contract::Validate( key: :comment )
+#### 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
 ```
 
-The contract (aka _form_) is defined in the `::contract` block. You can implement nested forms, default values, validations, and everything else Reform provides.
+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
+```
 
-In the `#process` method you can define your business logic.
+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...
+```
 
-[Learn more.](http://trailblazer.to/gems/operation/2.0/contract.html)
+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.
 
 ## Models
 
@@ -186,7 +330,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") }
@@ -200,9 +344,9 @@ Only operations and views/cells can access models directly.
 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
+class Song::Policy
+  def initialize(user, song)
+    @user, @song = user, song
   end
 
   def create?
@@ -214,8 +358,8 @@ end
 The rule is enabled via the `::policy` call.
 
 ```ruby
-class Comment::Create < Trailblazer::Operation
-  step Policy( Comment::Policy, :create? )
+class Song::Create < Trailblazer::Operation
+  step Policy( Song::Policy, :create? )
 end
 ```
 
@@ -233,9 +377,9 @@ More complex UI logic happens in _View Models_ as found in [Cells](https://githu
 The operation's form object can be rendered in views, too.
 
 ```ruby
-class CommentsController < ApplicationController
+class SongsController < ApplicationController
   def new
-    form Comment::Create # will assign the form object to @form.
+    form Song::Create # will assign the form object to @form.
   end
 end
 ```
@@ -255,12 +399,12 @@ Operations can use representers from [Roar](https://github.com/apotonick/roar) t
 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
+class Song::Create < Trailblazer::Operation
   representer do
     # inherited :body
     include Roar::JSON::HAL
 
-    link(:self) { comment_path(represented.id) }
+    link(:self) { song_path(represented.id) }
   end
 end
 ```
@@ -276,8 +420,8 @@ 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
 ```
 
@@ -302,4 +446,3 @@ gem "trailblazer-cells"
 ```
 
 Cells is _not_ required per default! Add it if you use it, which is highly recommended.
-

data/Rakefile

@@ -2,7 +2,7 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 require "rubocop/rake_task"
 
-task :default => [:test]
+task :default => %i[test rubocop]
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
@@ -16,4 +16,8 @@ Rake::TestTask.new(:testdep) do |test|
   test.verbose = true
 end
 
-RuboCop::RakeTask.new
+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/version.rb

@@ -1,3 +1,3 @@
 module Trailblazer
-  VERSION = "2.1.0.beta4"
+  VERSION = "2.1.0.beta5"
 end

data/lib/trailblazer.rb

@@ -6,17 +6,8 @@ require "trailblazer/dsl"
 require "trailblazer/task"
 
 require "trailblazer/operation/deprecations"
-
-require "trailblazer/operation/model"
-require "trailblazer/operation/contract"
-require "trailblazer/operation/validate"
-require "trailblazer/operation/representer"
-require "trailblazer/operation/policy"
-require "trailblazer/operation/pundit"
-require "trailblazer/operation/guard"
-require "trailblazer/operation/persist"
-require "trailblazer/operation/nested"
-require "trailblazer/operation/wrap"
-require "trailblazer/operation/rescue"
 require "trailblazer/operation/inject"
 require "trailblazer/operation/input_output"
+
+require "trailblazer/macro"
+require "trailblazer/macro/contract"

data/test/{operation/dsl → dsl}/contract_test.rb

@@ -38,7 +38,7 @@ class DslContractTest < MiniTest::Spec
   end
 
   # no inheritance with setter.
-  it { CreateOrFind["contract.default.class"].must_be_nil }
+  it { CreateOrFind["contract.default.class"].must_equal nil }
 
   # ---
   # Op::contract Constant
@@ -197,7 +197,7 @@ class DslContractTest < MiniTest::Spec
       form.sync
 
       song.genre.must_equal "Punkrock"
-      song.band.must_be_nil
+      song.band.must_equal nil
     end
   end
 

data/trailblazer.gemspec

@@ -17,10 +17,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "trailblazer-operation", ">= 0.2.3", "< 0.3.0"
-  spec.add_dependency "trailblazer-activity",  ">= 0.4.3", "< 0.6.0"
+  spec.add_dependency "trailblazer-operation", ">= 0.2.4", "< 0.3.0"
+  spec.add_dependency "trailblazer-macro", ">= 2.1.0.beta2", "< 2.2.0"
+  spec.add_dependency "trailblazer-macro-contract", ">= 2.1.0.beta2", "< 2.2.0"
 
-  spec.add_dependency "reform", ">= 2.2.0", "< 3.0.0"
   spec.add_dependency "declarative"
 
   spec.add_development_dependency "activemodel" # for Reform::AM::V