├── .github
├── dependabot.yml
└── workflows
│ └── ci.yml
├── .gitignore
├── CHANGES.md
├── CODE_OF_CONDUCT.md
├── COMM-LICENSE
├── CONTRIBUTING.md
├── Gemfile
├── LICENSE
├── README.md
├── Rakefile
├── THOUGHTS
├── doc
├── Trb-The-Stack.png
├── operation-2017.png
├── s_hero.png
├── song_operation_create.png
├── song_operation_create_trace.png
└── trb.jpg
├── lib
├── trailblazer.rb
└── trailblazer
│ └── version.rb
├── test
├── test_helper.rb
└── trailblazer_test.rb
└── trailblazer.gemspec
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | version: 2
2 | updates:
3 | - package-ecosystem: "github-actions"
4 | directory: "/"
5 | schedule:
6 | interval: "weekly"
7 |
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on: [push, pull_request]
3 | jobs:
4 | test:
5 | strategy:
6 | fail-fast: false
7 | matrix:
8 | ruby: [2.5, 2.6, 2.7, '3.0', '3.1', '3.2', 'head', 'jruby']
9 | runs-on: ubuntu-latest
10 | steps:
11 | - uses: actions/checkout@v3
12 | - uses: ruby/setup-ruby@v1
13 | with:
14 | ruby-version: ${{ matrix.ruby }}
15 | bundler-cache: true # runs 'bundle install' and caches installed gems automatically
16 | - run: bundle exec rake
17 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.gem
2 | *.rbc
3 | .bundle
4 | .config
5 | .yardoc
6 | Gemfile.lock
7 | InstalledFiles
8 | _yardoc
9 | coverage
10 | lib/bundler/man
11 | pkg
12 | rdoc
13 | spec/reports
14 | test/tmp
15 | test/version_tmp
16 | tmp
17 | /**/*.log
18 | GemfileCustom
19 |
--------------------------------------------------------------------------------
/CHANGES.md:
--------------------------------------------------------------------------------
1 | # 2.1.3
2 |
3 | * Require `trailblazer-developer` 0.1 line which brings tracing performance increase by
4 | factor 4-10.
5 | * Introduce `Operation.left` as an alias for `#fail`.
6 | * Better debugging API for the upcoming web debugger.
7 |
8 | # 2.1.2
9 |
10 | * Use `trailblazer-activity-dsl-linear` >= 1.1.0.
11 |
12 | # 2.1.1
13 |
14 | * Use `trailblazer-activity-dsl-linear` >= 1.0.0.
15 |
16 | # 2.1.0
17 |
18 | * Remove `declarative` dependency.
19 | * Macros now always have to provide an `:id`. This was a bit fuzzy in 2.0.
20 |
21 | * Nested
22 | if Nested( Edit ), outputs will automatically be connected, see editor.
23 | * Wrap
24 | dropped the `pipe` option. This is now `options, flow_options, *`
25 | `false` is now automatically connected to End.failure.
26 | * remove `Uber::Callable`.
27 |
28 | * `operation.new` step removed.
29 | * Undocumented step behavior removed. You can't write to `self` anymore.
30 |
31 | ```ruby
32 | step :process
33 | def process(*)
34 | self["x"] = true
35 | end
36 | ```
37 |
38 | Always write to `options`.
39 |
40 | * Fixed `Guard` where procs could receive one argument, only. Guards follow the step interface: `Policy::Guard( ->(options, **) { .. } )
41 | * Removed `Operation::Callback` which was a poor idea and luckily no one was using it.
42 |
43 | # 2.1.0.rc13
44 |
45 | * Use newest `macro` and `macro-context`. They use symbols keys now everywhere.
46 |
47 | # 2.1.0.rc12
48 |
49 | * Update dependencies.
50 |
51 | # 2.1.0.rc11
52 |
53 | * Remove all macros. They're not located in `trailblazer-macro` and `trailblazer-macro-contract`.
54 | * Remove DSL
55 |
56 | # 2.1.0.rc1
57 |
58 | * Remove `task` and `input_output`, those are implemented in `activity`.
59 |
60 | # 2.1.0.beta7
61 |
62 | * Use new `activity-0.3.2` where `VariableMapping` is included now.
63 |
64 | # 2.1.0.beta6
65 |
66 | * Use new `activity-0.3.0`.
67 |
68 | # 2.1.0.beta5
69 |
70 | * All macros are now cleanly extracted to `trailblazer-macro` and `trailblazer-macro-contract`.
71 |
72 | # 2.1.0.beta4
73 |
74 | * Simple maintenance release to establish `activity-0.5.0`.
75 |
76 | # 2.1.0.beta3
77 |
78 | * More simplifications because of `activity`.
79 |
80 | # 2.1.0.beta2
81 |
82 | * Simplify `Nested` and several other internals by using the new `Activity` API.
83 |
84 | # 2.1.0.beta1
85 |
86 | * Add `deprecation/call` and `deprecation/context` that help with the new `call` API and symbols for `options` keys.
87 |
88 | # 2.0.7
89 |
90 | * Allow to use any method with the Model macro, e.g.
91 |
92 | ```ruby
93 | step Model( Comment, :[] )
94 | ```
95 |
96 | will now invoke `Comment[ params[:id] ]`, which makes using Sequel a breeze.
97 | code: `contract do .. end` etc needs to be moved to a new gem if we want to keep it alive.
98 |
99 | # 2.0.6
100 |
101 | * Fix what we broke in 2.0.5, where `Wrap` would always use the current operation subclass and not the empty `Trailblazer::Operation`. Thanks to @mensfeld.
102 |
103 | # 2.0.5
104 |
105 | * In Wrap, use `self` instead of a hard class reference. This allows using Wrap in the compat gem.
106 |
107 | # 2.0.4
108 |
109 | * When using `Nested(X)`, the automatic `:name` option is now `"Nested(X)"` instead of the cryptic proc string.
110 |
111 | # 2.0.3
112 |
113 | * `Guard` now allows kw args for its option.
114 | * Fix a bug where `Nested( ->{} )` wouldn't `_call` the nested operation and did too much work on re-nested the already nested params. Thanks to @eliranf for spotting this.
115 | * Add `Nested(..., input: )` to dynamically decide the input to the nested operation. http://trailblazer.to/gems/operation/2.0/api.html#nested-input
116 | * Add `Nested(..., output: )`: http://trailblazer.to/gems/operation/2.0/api.html#nested-output
117 |
118 | # 2.0.2
119 |
120 | * Remove `uber` dependency as we use our own `Option::KW` now.
121 | * In `Contract::Build( builder: )` you now also have access to the `name:` keyword. Note that you need to double-splat in builders.
122 |
123 | ```ruby
124 | Contract::Build( builder: ->(options, constant:, **) )
125 | ```
126 | Same for `:method` and `Callable`.
127 | * `Policy::Guard( :method )` now works.
128 |
129 | # 2.0.1
130 |
131 | * Add `fail_fast: true` for `step` and `failure` to short-circuit the pipe. Note that more "eloquent" semantics are coming in `trailblazer-bpmn`.
132 | * Add `fail!`, `fail_fast!`, `pass!`, and `pass_fast!`. Note that they are all experimental API and not documented, yet.
133 | * Remove Builder and allow [dynamic `Nested`](http://trailblazer.to/gems/operation/2.0/api.html#nested-callable).
134 |
135 | ```ruby
136 | step Nested( ->(options, params:) { params[:type] == "moderated" ? Moderated : Comment } )
137 | ```
138 | * Remove `override` in favor of `step .., override: true`. Note that this method wasn't documented.
139 | * Numerous internal simplifications [documented here](https://github.com/trailblazer/trailblazer-operation/blob/master/CHANGES.md#0010).
140 |
141 |
142 | # 2.0.0
143 |
144 | All old semantics will be available via [trailblazer-compat](https://github.com/trailblazer/trailblazer-compat).
145 |
146 | * Removed `Operation::run` as it was a bad decision. Raising an exception on invalid is a very test-specific scenario and shouldn't have been handled in the core doce.
147 | * Removed `Operation::present`, since you can simply call `Operation::new` (without builders) or `Operation::build_operation` (with builders).
148 | * Removed `Operation::valid?`. This is in the result object via `result.success?`.
149 | * Removed `Operation#errors`. This is in the result object via `result[:errors]` if the operation was invalid.
150 | * Removed the private option `:raise_on_invalid`. Use `Contract::Raise` instead, if you need it in tests.
151 |
152 | * Removed `Operation::contract` (without args). Please use `Operation::["contract.default.class"]`.
153 | * Removed `Operation::callbacks` (without args). Please use `Operation::["callback.<name>.class"]`.
154 | * Removed `Operation::contract_class`. Please use `Operation::["contract.default.class"]`.
155 | * Removed `Operation::contract_class=`. Please use `Operation::["contract.default.class"]=`. Doesn't inherit.
156 |
157 | ## Model
158 |
159 | * The `model` method doesn't exist anymore, use `self["model"]` or write your own.
160 | * `:find_by` diverts to left track.
161 | * `:create` is `:new` now.
162 |
163 | ## Builder
164 |
165 | * It's `include Builder` now, not `extend Builder`.
166 | * `builds` now receives one options hash.
167 |
168 | ## Policy
169 |
170 | * No exception anymore, but `Operation#["policy.result"]`.
171 | * Access the current user via `self["current_user"]` now.
172 | * `Policy` is `Policy::Pundit` now as `Policy` is Trailblazer's (upcoming) authorization style.
173 |
174 | ## Representer
175 |
176 | * Removed `Operation::representer_class`. Please use `Operation::["representer.class"]`.
177 | * Removed `Operation::representer_class=`. Please use `Operation::["representer.class"]=`.
178 | * You can now have any number of named representers: `Operation.representer :parser, ParsingRepresenter`.
179 | * Automatic infering of the representer from a `contract` is not so automatic anymore. This feature was barely used and is now available via `include Representer::InferFromContract`.
180 | * Reform 2.0 is not supported in `Representer` anymore, meaning you can't automatically infer representers from 2.0 contracts. Reform 2.0 works with all remaining components.
181 | * Removed `Operation::contract_class`. Please use `Operation::["contract.default.class"]`.
182 | * Removed `Operation::contract_class=`. Please use `Operation::["contract.default.class"]=`. Doesn't inherit.
183 |
184 | ## Callback
185 |
186 | * Removed `Operation::Dispatch`, it's called `Operation::Callback`.
187 |
188 |
189 | ## Collection
190 |
191 | * Removed `Operation::Collection`. Please use `Operation::present`.
192 |
193 | ## Controller
194 |
195 | * Removed `Controller`, this is now in [trailblazer-rails](https://github.com/trailblazer/trailblazer-rails/).
196 |
197 | ## Contract
198 |
199 | * You can't call `Create.().contract` anymore. The contract instance(s) are available through the `Result` object via `["contract.default"]`.
200 | * Removed the deprecation for `validate`, signature is `(params[, model, options, contract_class])`.
201 | * Removed the deprecation for `contract`, signature is `([model, options, contract_class])`.
202 |
203 | # 2.0.0.rc1
204 |
205 | * `consider` got removed since `step` now evaluates the step's result and deviates (or not).
206 |
207 | # 2.0.0.rc2
208 |
209 | * It's now Contract::Persist( name: "params" ) instead of ( name: "contract.params" ).
210 |
211 | # 2.0.0.beta3
212 |
213 | * New, very slick keyword arguments for steps.
214 |
215 | # 2.0.0.beta2
216 |
217 | * Removed `Operation::Controller`.
218 | * Renamed `Persist` to `Contract::Persist`.
219 | * Simplify inheritance by introducing `Operation::override`.
220 | * `Contract` paths are now consistent.
221 |
222 | # 2.0.0.beta1
223 |
224 | * Still undefined `self.~`.
225 |
226 | # 1.1.2
227 |
228 | * Stricter `uber` dependency.
229 |
230 | # 1.1.1
231 |
232 | * Rename `Operation::Representer::ClassMethods` to `Operation::Representer::DSL` and allow to use `DSL` and `Rendering` without `Deserialization` so you can use two different representers.
233 | * `Policy::Guard::policy` now also accepts a `Callable` object.
234 | * Add `Operation#model=`.
235 |
236 | # 1.1.0
237 |
238 | * `Representer#represented` defaults to `model` now, not to `contract` anymore.
239 | * The only way to let Trailblazer pass a document to the operation is via `is_document: true`. There is _no guessing_ anymore based on whether or not `Representer` is mixed into the operation or not.
240 | * Add `Operation#params!` that works exactly like `#model!`: return another params hash here if you want to change the `params` structure while avoiding modifying the original one.
241 | * Add `Controller#params!` that works exactly like `Operation#params!` and allows returning an arbitrary params object in the controller. Thanks to @davidpelaez for inspiration.
242 | * Deprecate `Dispatch` in favor of `Callback`. In operations, please include `Operation::Callback`. Also, introduced `Operation#callback!` which aliases to `#dispatch!`. Goal is having to think less, and now all naming is in line.
243 |
244 | ## Fixes
245 |
246 | * `Representer#to_json` now allows passing options.
247 | * The `:params` key never got propagated to `prepopulate!` when using `Controller#form`. This is now fixed.
248 |
249 | # 1.0.4
250 |
251 | * Fix `Controller#run`, which now returns the operation instance instead of the `Else` object.
252 |
253 | # 1.0.3
254 |
255 | * Remove unprofessional `puts`, @smathy.
256 |
257 | # 1.0.2
258 |
259 | * Treat all requests as `params` requests unless the operation has a representer mixed in. If you don't want that, you can override using `is_document: false`. This appears to be the smoothest solution for all.
260 | * In `Controller#form`, the options argument is now passed into `form.prepopulate!(options)`. This allows to use arbitrary options and the `options[:params]` for prepopulation.
261 |
262 | # 1.0.1
263 |
264 | * Treat `:js` requests as non-document, too.
265 | * `Controller#form` now returns the form object and not the operation.
266 | * In `Controller`, `#form`, `#present`, `#run` and `#respond` now all have the same API: `run(constant, options)`. If you want to pass a custom params hash, use `run Comment::Create, params: {..}`.
267 |
268 | # 1.0.0
269 |
270 | * All Rails-relevant files are now in the `trailblazer-rails` gem. You have to include it should you be in a Rails environment.
271 | * `Operation[{..}]` is deprecated in favor of `Operation.({..})`.
272 | * `Operation::CRUD` is now `Operation::Model`.
273 | * `Controller#form` now invokes `#prepopulate!` before rendering the view.
274 | * `Controller#present` does not instantiate and assign `@form` anymore.
275 | * The internal `Operation` API has changed from `#initialize()` and `#run(params)` to `#initialize(params)` and `#run`.
276 |
277 | # 0.3.4
278 |
279 | * Added `Operation::Policy`.
280 | * Added `Operation::Resolver`.
281 |
282 | # 0.3.3
283 |
284 | * Add `Operation::reject` which will run the block when _invalid_.
285 | * In the railtie, require `trailblazer/autoloading` as I am assuming Rails users want maximum comfort.
286 |
287 | # 0.3.2
288 |
289 | * 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`.
290 | * New signature for `Operation#contract_for(model, contract_class)`. It used to be contract, then model.
291 |
292 | # 0.3.1
293 |
294 | * Autoload `Dispatch`.
295 |
296 | # 0.3.0
297 |
298 | ## Changes
299 |
300 | * In Railtie, use `ActionDispatch::Reloader.to_prepare` for autoloading, nothing else. This should fix spring reloading.
301 | * Allow `Op#validate(params, model, Contract)` with CRUD.
302 | * Allows prefixed table names, e.g. `admin.users` in `Controller`. The instance variables will be `@user`. Thanks to @fernandes and especially @HuckyDucky.
303 | * Added `Operation::Collection` which will allow additional behavior like pagination and scoping. Thanks to @fernandes for his work on this.
304 | * Added `Operation::collection` to run `setup!` without instantiating a contract. This is called in the new `Controller#collection` method.
305 | * Added `Operation#model` as this is a fundamental concept now.
306 | * Improved the undocumented `Representer` module which allows inferring representers from contract, using them to deserialize documents for the form, and rendering documents.
307 | * Changed `Operation::Dispatch` which now provides imperative callbacks.
308 |
309 | ## API change
310 |
311 | 1. The return value of #process is no longer returned from ::run and ::call. They always return the operation instance.
312 | 2. The return value of #validate is `true` or `false`. This allows a more intuitive operation body.
313 |
314 | ```ruby
315 | def process(params)
316 | if validate(params)
317 | .. do valid
318 | else
319 | .. handle invalid
320 | end
321 | end
322 | ```
323 |
324 | * `Worker` only works with Reform >= 2.0.0.
325 |
326 | # 0.2.3
327 |
328 |
329 | # 0.2.2
330 |
331 | # Added Operation#errors as every operation maintains a contract.
332 |
333 | # 0.2.1
334 |
335 | * Added `Operation#setup_model!(params)` that can be overridden to add nested objects or process models right after `model!`. Don't add deserialization logic here, let Reform/Representable do that.
336 | * Added `Operation#setup_params!(params)` to normalize parameters before `#process`. Thanks to @gogogarrett.
337 | * Added `Controller::ActiveRecord` that will setup a named controller instance variable for your operation model. Thanks @gogogarrett!
338 | * Added `CRUD::ActiveModel` that currently infers the contract's `::model` from the operation's model.
339 |
340 | # 0.2.0
341 |
342 | ## API Changes
343 |
344 | * `Controller#present` no longer calls `respond_to`, but lets you do the rendering. This will soon be re-introduced using `respond(present: true)`.
345 | * `Controller#form` did not respect builders, this is fixed now.
346 | * Use `request.body.read` in Unicorn/etc. environments in `Controller#respond`.
347 |
348 | ## Stuff
349 |
350 | * Autoloading changed, again. We now `require_dependency` in every request in dev.
351 |
352 | # 0.1.3
353 |
354 | * `crud_autoloading` now simply `require_dependency`s model files, then does the same for the CRUD operation file. This should fix random undefined constant problems in development.
355 | * `Controller#form` did not use builders. This is fixed now.
356 |
357 | # 0.1.2
358 |
359 | * Add `crud_autoloading`.
360 |
361 | # 0.1.1
362 |
363 | * Use reform-1.2.0.
364 |
365 | # 0.1.0
366 |
367 | * First stable release after almost 6 months of blood, sweat and tears. I know, this is a ridiculously brief codebase but it was a hell of a job to structure everything the way it is now. Enjoy!
368 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | Trailblazer Code of Conduct
2 |
3 | Like the technical community as a whole, the Trailblazer team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
4 |
5 | Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
6 |
7 | This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
8 |
9 | This code of conduct applies to all spaces managed by the Trailblazer project. This includes our Zulip chat, the issue trackers, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
10 |
11 | If you believe someone is violating the code of conduct, we ask that you report it by emailing info@trailblazer.to. All reports will be kept confidential.
12 |
13 | * **Be friendly and patient**.
14 | * **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
15 | * **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
16 | * **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Trailblazer community should be respectful when dealing with other members as well as with people outside the Trailblazer community.
17 |
18 | **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
19 |
20 | * Violent threats or language directed against another person.
21 | * Discriminatory jokes and language.
22 | * Posting sexually explicit or violent material.
23 | * Posting (or threatening to post) other people's personally identifying information ("doxing").
24 | * Personal insults, especially those using racist or sexist terms.
25 | * Unwelcome sexual attention.
26 | * Advocating for, or encouraging, any of the above behavior.
27 | * Repeated harassment of others. In general, if someone asks you to stop, then stop.
28 |
29 |
30 | **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and Trailblazer is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of Trailblazer comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
31 |
32 | Original text courtesy of the [Django project](https://www.djangoproject.com/conduct/).
33 |
--------------------------------------------------------------------------------
/COMM-LICENSE:
--------------------------------------------------------------------------------
1 | TRAILBLAZER LICENSE AGREEMENT
2 | VERSION 1.1
3 |
4 |
5 | IMPORTANT: THIS SOFTWARE LICENSE AGREEMENT IS A LEGAL AGREEMENT (“AGREEMENT”) BETWEEN LICENSEE (“LICENSEE”) AND TRAILBLAZER GMBH. READ IT CAREFULLY BEFORE COMPLETING THE INSTALLATION PROCESS AND USING TRAILBLAZER GEMS (AT GITHUB.COM/TRAILBLAZER), TRAILBLAZER PRO AND RELATED TRAILBLAZER PRO COMPONENTS (SOURCE URL WILL BE PROVIDED AFTER PURCHASE) (“SOFTWARE”). IT PROVIDES A LICENSE TO USE THE SOFTWARE AND CONTAINS WARRANTY INFORMATION AND LIABILITY DISCLAIMERS. IN CONSIDERATION OF LICENSEE’S INSTALLATION AND USE OF THE SOFTWARE, LICENSEE HEREBY CONFIRMS THE ACCEPTANCE OF THE SOFTWARE AND AGREES TO BECOME BOUND BY THE TERMS OF THIS AGREEMENT.
6 |
7 |
8 | In order to use the Software under this Agreement (“Commercial Version”), Licensee must receive a source URL at the time of purchase, in accordance with the scope of use and other terms specified for each type of Software and as set forth in this Section 1 of this Agreement.
9 |
10 | 1. License Grant.
11 | 1.1 General Use. This Agreement grants Licensee a worldwide, non-exclusive, non-transferable license, valid for the license term, to use the Software, without the right to grant sublicenses, subject to the terms and conditions in this Agreement. The Software is licensed, not sold.
12 | 1.2 Installations. Licensee may install the Software on an unlimited number of Hosts per project. “Host” means any physical or virtual machine which is controlled by Licensee. A project may involve multiple repositories.
13 | 1.3 Applications. Licensee may distribute the Software in any applications, frameworks, or elements (collectively referred to as an “Application” or “Applications”) that Licensee develops using the Software in accordance with this Agreement, provided that such distribution does not violate the restrictions set forth in section 3 of this Agreement. Licensee must not remove, obscure or interfere with any copyright, acknowledgment, attribution, trademark, warning or disclaimer statement affixed to, incorporated in or otherwise applied in connection with the Software. Licensee is required to ensure that the Software is not reused by or with any applications other than those with which Licensee distribute it as permitted herein. For example, if Licensee installs the Software on a customer’s server, that customer is not permitted to use the Software independently of Licensee’s Application. Licensee must inform Trailblazer GmbH of any infringing use of the Software by any of Licensee’s customers. Licensee is liable for compliance by those third parties with the terms and conditions of this Agreement. Licensee shall not owe Trailblazer GmbH any royalties for Licensee’s distribution of the Software in accordance with this Agreement.
14 | 1.4 Archive Copies. Licensee is entitled to make a reasonable amount of copies of the Software for archival purposes. Each copy must reproduce all copyright and other proprietary rights notices on or in the Software.
15 | 1.5 Electronic Delivery. All Software and license documentation shall be delivered by electronic means unless otherwise specified on the applicable invoice (“Invoice”) or at the time of purchase. Software shall be deemed delivered when it is made available for download by Licensee (“Delivery”).
16 |
17 | 2. Modifications.
18 | Trailblazer GmbH shall provide Licensee with source code so that Licensee can create Modifications of the Software. “Modification” means: (a) any addition to or deletion from the contents of a file included in the original Software or previous Modifications created by Licensee, or (b) any new file that contains any part of the original Software or previous Modifications. While Licensee retains all rights to any original work authored by Licensee as part of the Modifications, Trailblazer GmbH continues to own all copyright and other intellectual property rights in the Software.
19 |
20 | 3. Restricted Uses.
21 | 3.1 Licensee shall not (and shall not allow any third party to): (a) decompile, disassemble, or otherwise reverse engineer the Software or attempt to reconstruct or discover any source code, underlying ideas, algorithms, file formats or programming interfaces of the Software by any means whatsoever (except and only to the extent that applicable law prohibits or restricts reverse engineering restrictions); (b) distribute, sell, sublicense, rent, lease or use the Software for time sharing, hosting, service provider or like purposes, except as expressly permitted under this Agreement; (c) redistribute the Software or Modifications other than by including the Software or a portion thereof within Licensee’s own product, which must have substantially different functionality than the Software or Modifications and must not allow any third party to use the Software or Modifications, or any portions thereof, for software development or application development purposes; (d) redistribute the Software as part of an "appliance" or "virtual server"; (e) redistribute the Software on any server which is not directly under Licensee’s control; (f) remove any product identification, proprietary, copyright or other notices contained in the Software; (g) modify any part of the Software, create a derivative work of any part of the Software (except as permitted in Section 2), or incorporate the Software, except to the extent expressly authorized in writing by Trailblazer GmbH; (h) publicly disseminate performance information or analysis (including, without limitation, benchmarks) from any source relating to the Software; (i) utilize any equipment, device, software, or other means designed to circumvent or remove any form of Source URL or copy protection used by Trailblazer GmbH in connection with the Software, or use the Software together with any authorization code, Source URL, serial number, or other copy protection device not supplied by Trailblazer GmbH; (j) use the Software to develop a product which is competitive with any Trailblazer GmbH product offerings (unless such development is allowed by applicable law); or (k) use unauthorized Source URLS or keycode(s) or distribute or publish Source URLs or keycode(s), except as may be expressly permitted by Trailblazer GmbH in writing. If Licensee’s unique Source URL is ever published, Trailblazer GmbH reserves the right to terminate Licensee’s access without notice.
22 | 3.2 UNDER NO CIRCUMSTANCES MAY LICENSEE USE THE SOFTWARE AS PART OF A PRODUCT OR SERVICE THAT PROVIDES SIMILAR FUNCTIONALITY AS THE SOFTWARE ITSELF.
23 |
24 | 4. Ownership.
25 | Notwithstanding anything to the contrary contained herein, except for the limited license rights expressly provided herein, Trailblazer GmbH and its suppliers have and will retain all rights, title and interest (including, without limitation, all patent, copyright, trademark, trade secret and other intellectual property rights) in and to the Software and all copies, modifications and derivative works thereof (including any changes which incorporate any of Licensee’s ideas, feedback or suggestions). Licensee acknowledges that Licensee is obtaining only a limited license right to the Software, and that irrespective of any use of the words “purchase”, “sale” or like terms hereunder no ownership rights are being conveyed to Licensee under this Agreement or otherwise.
26 |
27 | 5. Fees and Payment.
28 | The Software license fees will be due and payable in full as set forth in the Invoice or at the time of purchase. Licensee shall be responsible for all taxes, withholdings, duties and levies arising from the order (excluding taxes based on the net income of Trailblazer GmbH).
29 |
30 | 6. Support, Maintenance and Services.
31 | Subject to the terms and conditions of this Agreement, as set forth in the Invoice, and as set forth on the Trailblazer PRO support page (http://pro.trailblazer.to), support and maintenance services may be included with the purchase of Licensee’s license subscription.
32 |
33 | 7. Term of Agreement.
34 | 7.1 Term. This Agreement is effective as of the Delivery of the Software and expires at such time as all license and service subscriptions hereunder have expired in accordance with their own terms (the “Term”). For clarification, the term of the license under this Agreement may be perpetual or designated as a fixed-term license in the Invoice and shall be specified at Licensee’s time of purchase. Either party may terminate this Agreement (including all related Invoices) if the other party: (a) fails to cure any material breach of this Agreement within thirty (30) days after written notice of such breach, provided that Trailblazer GmbH may terminate this Agreement immediately upon any breach of Section 3 or if Licensee exceeds any other restrictions contained in Section 1, unless otherwise specified in this agreement; (b) ceases operation without a successor; or (c) seeks protection under any bankruptcy, receivership, trust deed, creditors arrangement, composition or comparable proceeding, or if any such proceeding is instituted against such party (and not dismissed within sixty (60) days)). Termination is not an exclusive remedy and the exercise by either party of any remedy under this Agreement will be without prejudice to any other remedies it may have under this Agreement, by law, or otherwise.
35 | 7.2 Termination. Upon any termination of this Agreement, Licensee shall cease any and all use of any Software and destroy all copies thereof.
36 | 7.3 Expiration of License. Upon the expiration of any term under this Agreement, (a) all Software updates and services pursuant to the license shall cease, (b) Licensee may only continue to run existing installations of the Software, (c) Licensee may not install the Software on any additional Hosts, and (d) any new installation of the Software shall require the purchase of a new license subscription from Trailblazer GmbH.
37 |
38 | 8. Disclaimer of Warranties.
39 | The Software is provided "as is", with all faults, defects and errors, and without warranty of any kind. Trailblazer GmbH does not warrant that the Software will be free of bugs, errors, viruses or other defects, and Trailblazer GmbH shall have no liability of any kind for the use of or inability to use the Software, the Software content or any associated service, and Licensee acknowledges that it is not technically practicable for Trailblazer GmbH to do so.
40 | To the maximum extent permitted by applicable law, Trailblazer GmbH disclaims all warranties, express, implied, arising by law or otherwise, regarding the Software, the Software content and their respective performance or suitability for Licensee’s intended use, including without limitation any implied warranty of merchantability, fitness for a particular purpose.
41 |
42 | 9. Limitation of Liability.
43 | To the maximum extent permitted by applicable law, Trailblazer GmbH will not be liable for any direct, indirect, consequential, incidental, special, exemplary, or punitive damages or liabilities whatsoever arising from or relating to the Software, the Software content or this Agreement, whether based on contract, tort (including negligence), strict liability or other theory, even if Trailblazer GmbH has been advised of the possibility of such damages. In no event will Trailblazer GmbH's liability exceed the Software license price as indicated in the Invoice. The existence of more than one claim will not enlarge or extend this limit. Claims for damages under the Product Liability Act shall remain unaffected, as shall liability for damage to life, body or health.
44 |
45 | 10. Remedies.
46 | Licensee’s exclusive remedy and Trailblazer GmbH’s entire liability for breach of this Agreement shall be limited, at Trailblazer GmbH’s sole and exclusive discretion, to (a) replacement of any defective software or documentation; or (b) refund of the license fee paid to Trailblazer GmbH.
47 |
48 | 11. Miscellaneous
49 | 11.1 Entire Agreement. This Agreement sets forth our entire agreement with respect to the Software and the subject matter hereof and supersedes all prior and contemporaneous understandings and agreements whether written or oral.
50 | 11.2 No Assignment. Licensee may not assign this Agreement or any of its rights under this Agreement without the prior written consent of Trailblazer GmbH and any attempted assignment without such consent shall be void.
51 | 11.3 Export Compliance. Licensee agrees to comply with all applicable laws and regulations, including laws, regulations, orders or other restrictions on export, re-export or redistribution of software.
52 | 11.4 Indemnification. Licensee agrees to defend, indemnify, and hold harmless Trailblazer GmbH from and against any lawsuits, claims, losses, damages, fines and expenses (including attorneys' fees and costs) arising out of Licensee’s use of the Software or breach of this Agreement.
53 | 11.5 Governing Law. This Agreement is governed and construed in accordance with the law of The Federal Republic of Germany and shall be subject to the exclusive jurisdiction of the Courts of Berlin, Germany. The operation of the United Nations Convention on the International Sale of Goods is hereby expressly excluded.
54 | 11.6 Dispute Resolution. In the event of any dispute arising from or in connection with this Agreement, the parties undertake to make all their best efforts to settle the dispute amicably through negotiations, failing which either party may submit the dispute for resolution by the Courts of Berlin, Germany.
55 | 11.7 Attorneys’ Fees and Costs. The prevailing party in any action to enforce this Agreement shall be entitled to recover its attorneys’ fees and costs in connection with such action.
56 | 11.8 Severability. If any provision of this Agreement is held by a court of competent jurisdiction to be invalid, illegal, or unenforceable, the remainder of this Agreement shall remain in full force and effect.
57 | 11.9 Waiver. Failure or neglect by either party to enforce at any time any of the provisions of this Agreement shall not be construed or deemed to be a waiver of that party's rights under this Agreement.
58 | 11.10 Modifications. No modification of this Agreement shall be effective unless contained in writing and executed by an authorized representative of each party. No term or condition in Licensee’s Purchase Order or Terms and Conditions shall apply unless expressly accepted by Trailblazer GmbH.
59 | 11.11 Force Majeure. Trailblazer GmbH shall not be liable for any delay or non-performance of its obligations under this Agreement in the event and to the extent that such delay or non-performance is due to an unforeseeable catastrophic event that prevents Trailblazer GmbH to fulfill its obligations under this Agreement and which Trailblazer GmbH cannot avoid or circumvent (“Force Majeure Event”). If the Force Majeure Event results in a delay or non-performance of Trailblazer GmbH for a period of three (3) months or longer, then Licensee shall have the right to terminate this Agreement with immediate effect without any liability (except for the obligations of payment arising prior to the event of Force Majeure).
60 |
61 |
62 | The Open Source version of the TRAILBLAZER GEMS (“LGPL Version”) is licensed under the terms of the GNU Lesser General Public License versions 3.0 (“LGPL”) and not under this Agreement.
63 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing to Trailblazer
2 | Trailblazer is an open source project and we would love you to help us make it better.
3 |
4 | ## Questions/Help
5 | 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.
6 |
7 | Keep in mind when asking questions though, an example will get you help faster than anything else you do.
8 |
9 | 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.
10 |
11 | ## Reporting Issues
12 | A well formatted issue is appreciated, and goes a long way in helping us help you.
13 |
14 | * Make sure you have a [GitHub account](https://github.com/signup/free)
15 | * Submit a [Github issue][issues-link] by:
16 | * Clearly describing the issue
17 | * Provide a descriptive summary
18 | * Provide sample code where possible (preferably in the form of a test, in a [Gist][gist] for bonus points)
19 | * Explain the expected behavior
20 | * Explain the actual behavior
21 | * Provide steps to reproduce the actual behavior
22 | * Provide your application's complete `Gemfile.lock` as text (in a [Gist][gist] for bonus points)
23 | * Any relevant stack traces
24 |
25 | If you provide code, make sure it is formatted with the triple backticks (\`).
26 |
27 | At this point, we'd love to tell you how long it will take for us to respond, but we just don't know.
28 |
29 | ## Pull requests
30 | We accept pull requests to Trailblazer for:
31 |
32 | * Adding documentation
33 | * Fixing bugs
34 | * Adding new features
35 |
36 | Not all features proposed will be added but we are open to having a conversation about a feature you are championing.
37 |
38 | ###Here's a quick guide:
39 | #### Fork the Project
40 | Fork the [project repository][project-repo-link] on Github and check out your copy.
41 |
42 | ```
43 | git clone https://github.com/YOUR_HANDLE/trailblazer.git
44 | cd trailblazer
45 | git remote add upstream https://github.com/trailblazer/trailblazer.git
46 | ```
47 |
48 | #### Create a Topic Branch
49 | Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
50 | ```
51 | git checkout master
52 | git pull upstream master
53 | git checkout -b my-feature-branch
54 | ```
55 |
56 | #### Bundle and Test
57 | Run bundle install/update to gather any and all dependencies. Run the tests. This is to make sure your starting point works.
58 |
59 | ```
60 | bundle install
61 | bundle exec rake
62 | ```
63 |
64 | #### Write Tests
65 | 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].
66 |
67 | We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
68 |
69 | #### Write Code
70 | Implement your feature or bug fix.
71 |
72 | Ruby style is enforced with [RuboCop](https://github.com/bbatsov/rubocop), run `bundle exec rubocop` and fix any style issues highlighted.
73 |
74 | Make sure that `bundle exec rake` completes without errors.
75 |
76 | #### Write Documentation
77 | Document any external behavior in the [README](README.md).
78 |
79 | #### Commit Changes
80 | Make sure git knows your name and email address:
81 |
82 | ```
83 | git config --global user.name "Your Name"
84 | git config --global user.email "contributor@example.com"
85 | ```
86 |
87 | Writing good commit logs is important. A commit log should describe what has changed and why, but be brief.
88 |
89 | ```
90 | git add your_filename.rb (File names to add content from, or fileglobs e.g. *.rb)
91 | git commit
92 | ```
93 |
94 | #### Push
95 | ```
96 | git push origin my-feature-branch
97 | ```
98 |
99 | #### Make a Pull Request
100 | 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.
101 |
102 | #### Rebase
103 | If you've been working on a change for a while, rebase with upstream/master.
104 |
105 | ```
106 | git fetch upstream
107 | git rebase upstream/master
108 | git push origin my-feature-branch -f
109 | ```
110 |
111 | #### Update CHANGELOG Again
112 | Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
113 |
114 | ```
115 | * [#123](https://github.com/trailblazer/trailblazer/pull/123): Your brief description - [@your_gh_handle](https://github.com/your_gh_handle).
116 | ```
117 |
118 | Amend your previous commit and force push the changes.
119 |
120 | ```
121 | git commit --amend
122 | git push origin my-feature-branch -f
123 | ```
124 |
125 | #### Check on Your Pull Request
126 | 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.
127 |
128 | ## Quality
129 |
130 | Committing to OSS projects is always difficult, because all maintainers will adhere to their own quality standards that you don't know. Every projects wants "good code design", and so do we, so here are a few things that you should follow when contributing.
131 |
132 | * Good design matters: sometimes a feature could be added with a simple `if <my new case>` to an existing block of code. Usually, an `if` implies that the original design didn't plan on handling multiple cases, or in other words, **a refactoring of the code structure might be necessary**. If you're unsure: [Talk to us!](https://gitter.im/trailblazer/chat)
133 | * Make smaller pull requests. It is so much easier to discuss something graspable and not a "37 files changed" PR. The sooner we see your code, the earlier we can decide about which way to go. It is incredibly appreciated, though, to send us a link to a branch of yours where we can see the desired changes in total. We can then help splitting those into smaller steps.
134 | * **Never ever use `if respond_to?`** to add a feature. This is a pattern as seen a lot in Rails core that causes incredibly hard to find ~bugs~ behavior. In Trailblazer, we use "Tell, don't ask!", which means, never try to find out the type of an object via `respond_to?`. If you really have to introspect the type, use `is_a?`. Treat it as a duck, ducks don't speak.
135 |
136 |
137 | ## Releasing
138 |
139 | When you have release rights, please follow these rules.
140 |
141 | * When tagging a commit for a release, use the format `vX.X.X` for the tag, e.g. `git tag v2.1.0`.
142 | * The tagged commit **must contain the line** "Releasing vX.X.X" so it can be quickly spotted later in the commit list.
143 |
144 | #### What now?
145 | At this point you're waiting on us. Expect a conversation regarding your pull request; Questions, clarifications, and so on.
146 |
147 | Some things that will increase the chance that your pull request is accepted:
148 | * Use Trailblazer idioms and follow the Trailblazer ideology
149 | * Include tests that fail without your code, and pass with it
150 | * Update the documentation, guides, etc.
151 |
152 | ## What do we need help with?
153 | ### Helping others!
154 | 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:
155 |
156 | - Hang out on [the chat][chat]
157 | - Watch the [trailblazer repositories][repositories] for issues or requests that you could help with
158 |
159 | ### Contributing to community
160 | - Create Macros!
161 | - Write blog posts!
162 | - Record screencasts
163 | - Write examples.
164 |
165 | ### Contributing to the core
166 | - Tests are always helpful!
167 | - Any of the issues in GitHub, let us know if you have some time to fix one.
168 |
169 | ## Thank You
170 | Please do know that we really appreciate and value your time and work.
171 |
172 | [gist]: https://gist.github.com
173 | [guides]: https://www.trailblazer.to
174 | [api-docs]: https://www.trailblazer.to/api-docs
175 | [chat]: https://gitter.im/trailblazer/chat
176 | [repositories]: https://github.com/trailblazer
177 | [test-link]: https://github.com/trailblazer/trailblazer/tree/master/test
178 | [project-repo-link]: https://github.com/trailblazer/trailblazer
179 | [issues-link]: https://www.github.com/trailblazer/trailblazer/issues
180 |
--------------------------------------------------------------------------------
/Gemfile:
--------------------------------------------------------------------------------
1 | source 'https://rubygems.org'
2 |
3 | # Specify your gem's dependencies in trailblazer.gemspec
4 | gemspec
5 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Copyright (c) 2018 Trailblazer GmbH
2 |
3 | Trailblazer is an Open Source project licensed under the terms of
4 | the LGPLv3 license. Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
5 | for license text.
6 |
7 | Trailblazer PRO has a commercial-friendly license allowing private forks
8 | and modifications of Trailblazer. Please see http://trailblazer.to/pro for
9 | more detail.
10 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Trailblazer
2 |
3 | _Battle-tested Ruby framework to help structuring your business logic._
4 |
5 | [](http://badge.fury.io/rb/trailblazer)
6 |
7 | ## What's Trailblazer?
8 |
9 | Trailblazer introduces new abstraction layers into Ruby applications to help you structure your business logic.
10 |
11 | It ships with our canonical "service object" implementation called *operation*, many conventions, gems for testing, Rails support, optional form objects and much more.
12 |
13 | ## Should I use Trailblazer?
14 |
15 | Give us a chance if you say "yes" to this!
16 |
17 | * You hate messy controller code but don't know where to put it?
18 | * Moving business code into the "fat model" gives you nightmares?
19 | * "Service objects" are great?
20 | * Anyhow, you're tired of 12 different "service object" implementations throughout your app?
21 | * You keep asking for additional layers such as forms, policies, decorators?
22 |
23 | Yes? Then we got a well-seasoned framework for you: [Trailblazer](https://trailblazer.to/2.1).
24 |
25 | Here are the main concepts.
26 |
27 | ## Operation
28 |
29 | The operation encapsulates business logic and is the heart of the Trailblazer architecture.
30 |
31 | 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.
32 |
33 | ```ruby
34 | # app/concepts/song/operation/create.rb
35 | module Song::Operation
36 | class Create < Trailblazer::Operation
37 | step :create_model
38 | step :validate
39 | left :handle_errors
40 | step :notify
41 |
42 | def create_model(ctx, **)
43 | # do whatever you feel like.
44 | ctx[:model] = Song.new
45 | end
46 |
47 | def validate(ctx, params:, **)
48 | # ..
49 | end
50 | # ...
51 | end
52 | end
53 | ```
54 |
55 | The `step` DSL takes away the pain of flow control and error handling. You focus on _what_ happens: creating models, validating data, sending out notifications.
56 |
57 | ### Control flow
58 |
59 | The operation takes care _when_ things happen: the flow control. Internally, this works as depicted in this beautiful diagram.
60 |
61 | 
62 |
63 | The best part: the only way to invoke this operation is `Operation.call`. The single entry-point saves programmers from shenanigans with instances and internal state - it's proven to be an almost bullet-proof concept in the past 10 years.
64 |
65 | ```ruby
66 | result = Song::Operation::Create.(params: {title: "Hear Us Out", band: "Rancid"})
67 |
68 | result.success? #=> true
69 | result[:model] #=> #<Song title="Hear Us Out" ...>
70 | ```
71 |
72 | Data, computed values, statuses or models from within the operation run are exposed through the `result` object.
73 |
74 | Operations can be nested, use composition and inheritance patterns, provide [variable mapping](https://trailblazer.to/2.1/docs/activity#activity-variable-mapping) around each step, support dependency injection, and save you from reinventing the wheel - over and over, again.
75 |
76 | Leveraging those functional mechanics, operations encourage a high degree of encapsulation while giving you all the conventions and tools for free (except for a bit of a learning curve).
77 |
78 | ### Tracing
79 |
80 | In the past years, we learnt from some old mistakes and improved developer experience. As a starter, check out our built-in tracing!
81 |
82 | ```ruby
83 | result = Song::Operation::Create.wtf?(params: {title: "", band: "Rancid"})
84 | ```
85 |
86 | 
87 |
88 | Within a second you know which step failed - a thing that might seem trivial, but when things grow and a deeply nested step in an iteration fails, you will start loving `#wtf?`! It has saved us days of debugging.
89 |
90 | We even provide a [visual debugger](https://trailblazer.to/2.1/pro) to inspect traces on the webs.
91 |
92 | ## There's a lot more
93 |
94 | All our abstraction layers such as [operations](https://trailblazer.to/2.1/docs/operation), [form objects](https://trailblazer.to/2.1/docs/reform.html), [view components](https://trailblazer.to/2.1/docs/cells.html) and much more are used in [hundreds of OSS projects](https://github.com/trailblazer/trailblazer/network/dependents) and commercial applications in the Ruby world.
95 |
96 | Recently, we [released](https://dev.to/trailblazer/unit-tests-in-trailblazer-less-code-more-coverage-4oig) the [trailblazer-test](https://trailblazer.to/2.1/docs/test/) gem along with support for RSpec to easily write operation unit tests.
97 |
98 | ```ruby
99 | it "passes with valid input" do
100 | assert_pass Song::Operation::Create, valid_input,
101 | title: "Hear us out",
102 | persisted?: true
103 | end
104 | ```
105 |
106 | We provide a [visual debugger](https://pro.trailblazer.to), a [BPMN editor](https://trailblazer.to/2.1/docs/workflow) for long-running business processes, [thorough documentation](https://trailblazer.to/2.1/docs/trailblazer.html) and a growing list of onboarding videos ([**TRAILBLAZER TALES**](https://www.youtube.com/channel/UCi2P0tFMtjMUsWLYAD1Ezsw)).
107 |
108 | Trailblazer is both used for refactoring legacy apps (we support Ruby 2.5+) and helps big teams organizing, structuring and debugging modern, growing (Rails) applications.
109 |
110 | ## Documentation
111 |
112 | * **The current version is Trailblazer 2.1.** We do have comprehensive [API documenation](https://trailblazer.to/2.1/docs/trailblazer.html) ready for you. If you're new to TRB start with our [LEARN page](https://trailblazer.to/2.1/docs/trailblazer/#trailblazer-learn).
113 | * A migration guide from 2.0 can be found [on our website](https://trailblazer.to/2.1/docs/trailblazer.html#trailblazer-2-1-migration).
114 | * The [1.x documentation is here](http://trailblazer.to/2.0/gems/operation/1.1/index.html).
115 |
116 | Make sure to check out the new beginner's guide to learning Trailblazer. The [new book](https://leanpub.com/buildalib) discusses all aspects in a step-wise approach you need to understand Trailblazer's mechanics and design ideas.
117 |
118 | 
119 |
120 |
--------------------------------------------------------------------------------
/Rakefile:
--------------------------------------------------------------------------------
1 | require "bundler/gem_tasks"
2 | require "rake/testtask"
3 |
4 | task :default => %i[test]
5 |
6 | Rake::TestTask.new(:test) do |test|
7 | test.libs << 'test'
8 | test.test_files = FileList['test/**/*_test.rb'] - FileList["test/deprecation/*_test.rb"]
9 | test.verbose = true
10 | end
11 |
--------------------------------------------------------------------------------
/THOUGHTS:
--------------------------------------------------------------------------------
1 | by adding new abstraction layers
2 | * automatical think about interfaces
3 | * testability
4 | * 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
5 |
6 | the less associations in models the better
7 |
8 | hi-level APIs: Invoice::Flow instead of creating I:Item out-of-sync
9 | if your factories have 5 lines or more, your API is wrong, (Invoice::Flow)
10 |
11 |
12 | i don't wanna show anti-patterns, i wanna show how you can make things work.
--------------------------------------------------------------------------------
/doc/Trb-The-Stack.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/Trb-The-Stack.png
--------------------------------------------------------------------------------
/doc/operation-2017.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/operation-2017.png
--------------------------------------------------------------------------------
/doc/s_hero.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/s_hero.png
--------------------------------------------------------------------------------
/doc/song_operation_create.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/song_operation_create.png
--------------------------------------------------------------------------------
/doc/song_operation_create_trace.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/song_operation_create_trace.png
--------------------------------------------------------------------------------
/doc/trb.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/trailblazer/trailblazer/4d49a1601875d2223c3ac78c5c0d52610f9e2a6f/doc/trb.jpg
--------------------------------------------------------------------------------
/lib/trailblazer.rb:
--------------------------------------------------------------------------------
1 | require "trailblazer/version"
2 | require "trailblazer/operation"
3 | require "trailblazer/macro"
4 | require "trailblazer/macro/contract"
5 |
--------------------------------------------------------------------------------
/lib/trailblazer/version.rb:
--------------------------------------------------------------------------------
1 | module Trailblazer
2 | module Version
3 | VERSION = "2.1.3"
4 | end
5 | end
6 |
--------------------------------------------------------------------------------
/test/test_helper.rb:
--------------------------------------------------------------------------------
1 | require "minitest/autorun"
2 |
3 | require "trailblazer"
4 |
--------------------------------------------------------------------------------
/test/trailblazer_test.rb:
--------------------------------------------------------------------------------
1 | require "test_helper"
2 | require "reform/form/dry"
3 | require "trailblazer/macro"
4 | require "trailblazer/macro/contract"
5 |
6 | class TrailblazerTest < Minitest::Spec
7 | Song = Struct.new(:title)
8 |
9 |
10 | class Create < Trailblazer::Operation
11 | class Form < Reform::Form
12 | include Reform::Form::Dry
13 | property :title
14 |
15 | validation do
16 | params do
17 | required(:title).filled(min_size?: 2)
18 | end
19 | end
20 | end
21 |
22 | step Model(Song, :new)
23 | step Contract::Build(constant: Form)
24 | step Contract::Validate()
25 | step Contract::Persist(method: :sync)
26 | end
27 |
28 | it do
29 | result = nil
30 |
31 | output, _ = capture_io do
32 | result = Create.wtf?(params: {title: "Dead and Gone"})
33 | end
34 |
35 | assert_equal output, %(TrailblazerTest::Create
36 | |-- \e[32mStart.default\e[0m
37 | |-- \e[32mmodel.build\e[0m
38 | |-- \e[32mcontract.build\e[0m
39 | |-- contract.default.validate
40 | | |-- \e[32mStart.default\e[0m
41 | | |-- \e[32mcontract.default.params_extract\e[0m
42 | | |-- \e[32mcontract.default.call\e[0m
43 | | `-- End.success
44 | |-- \e[32mpersist.save\e[0m
45 | `-- End.success
46 | )
47 | assert_equal result.success?, true
48 | assert_equal result[:model].to_h, {:title=>"Dead and Gone"}
49 |
50 | # invalid!
51 | result = Create.wtf?(params: {})
52 | output, _ = capture_io do
53 | result = Create.wtf?(params: {})
54 | end
55 |
56 | assert_equal output, %(TrailblazerTest::Create
57 | |-- \e[32mStart.default\e[0m
58 | |-- \e[32mmodel.build\e[0m
59 | |-- \e[32mcontract.build\e[0m
60 | |-- contract.default.validate
61 | | |-- \e[32mStart.default\e[0m
62 | | |-- \e[32mcontract.default.params_extract\e[0m
63 | | |-- \e[33mcontract.default.call\e[0m
64 | | `-- End.failure
65 | `-- End.failure
66 | )
67 |
68 | assert_equal result.success?, false
69 | assert_equal result[:mode].to_h, {}
70 | end
71 | end
72 |
73 | # Song = Struct.new(:title)
74 | # class Song
75 | # module Operation
76 | # class Create < Trailblazer::Operation
77 | # step :create_model
78 | # step :validate
79 | # fail :handle_errors
80 | # step :notify
81 |
82 | # def create_model(ctx, **)
83 | # # do whatever you feel like.
84 | # ctx[:model] = Song.new
85 | # end
86 |
87 | # def validate(ctx, params:, **)
88 | # # ..
89 | # end
90 |
91 | # def handle_errors(ctx, **)
92 | # true
93 | # end
94 | # end
95 |
96 | # end
97 | # end
98 |
99 | # Song::Operation::Create.wtf?(params: {})
100 |
--------------------------------------------------------------------------------
/trailblazer.gemspec:
--------------------------------------------------------------------------------
1 | lib = File.expand_path('../lib', __FILE__)
2 | $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
3 | require 'trailblazer/version'
4 |
5 | Gem::Specification.new do |spec|
6 | spec.name = "trailblazer"
7 | spec.version = Trailblazer::Version::VERSION
8 | spec.authors = ["Nick Sutterer"]
9 | spec.email = ["apotonick@gmail.com"]
10 | spec.summary = %q{Ruby framework for structuring your business logic.}
11 | spec.homepage = "https://trailblazer.to"
12 | spec.license = "LGPL-3.0"
13 | spec.metadata = {
14 | "bug_tracker_uri" => "https://github.com/trailblazer/trailblazer/issues",
15 | "changelog_uri" => "https://github.com/trailblazer/trailblazer/blob/master/CHANGES.md",
16 | "documentation_uri" => "https://trailblazer.to/docs",
17 | "homepage_uri" => "https://trailblazer.to/",
18 | "mailing_list_uri" => "https://trailblazer.zulipchat.com/",
19 | "source_code_uri" => "https://github.com/trailblazer/trailblazer",
20 | "wiki_uri" => "https://github.com/trailblazer/trailblazer/wiki"
21 | }
22 |
23 | spec.files = `git ls-files -z`.split("\x0").reject do |f|
24 | f.match(%r{^(test|doc)/})
25 | end
26 | spec.test_files = `git ls-files -z test`.split("\x0")
27 | spec.require_paths = ["lib"]
28 |
29 | spec.add_dependency "trailblazer-macro", ">= 2.1.15", "< 2.2.0"
30 | spec.add_dependency "trailblazer-developer", ">= 0.1.0", "< 0.2.0"
31 | spec.add_dependency "trailblazer-macro-contract", ">= 2.1.4", "< 2.2.0"
32 | spec.add_dependency "trailblazer-operation", ">= 0.9.0", "< 1.0.0"
33 | spec.add_dependency "trailblazer-activity-dsl-linear", ">= 1.2.3", "< 1.3.0" # this can be removed at some point.
34 |
35 | spec.add_development_dependency "bundler"
36 | spec.add_development_dependency "rake"
37 | spec.add_development_dependency "minitest"
38 | spec.add_development_dependency "minitest-line"
39 | spec.add_development_dependency "dry-validation"
40 |
41 | spec.required_ruby_version = '>= 2.5.0'
42 | end
43 |
--------------------------------------------------------------------------------