Plan a trek across a hut network
In this tutorial we build the booking side of a mountain hut network. We start with a typed Hut, nest it into bookings and JSON, write the action that reserves places, handle what goes wrong, split the work into small actions, and put the result behind a controller, a job and a spec.
Checked against field_struct 1.0.0.pre1 and actionable-rb 2.0.0.pre1, the versions in this repository.
The six chapters
Section titled “The six chapters”| Chapter | We make | Gem |
|---|---|---|
| 1. A typed Hut | a Hut with typed, coerced, validated fields |
field_struct |
| 2. Bookings and JSON | nested bookings, JSON round trips, a masked token | field_struct |
| 3. Reserving places | the first action, with typed input and a declared failure | actionable |
| 4. When things go wrong | skips, metadata, pattern matching, exceptions | actionable |
| 5. Composing actions | a trek plan built from small actions, with an undo | actionable |
| 6. Into an app | a controller, a flaky pass-report lookup, a job and a spec | actionable |
Each chapter takes about 20 minutes, and chapters 1 and 2 need only field_struct.
What you need
Section titled “What you need”Ruby 3.3 or newer, and these two gems:
gem 'field_struct', '~> 1.0.0.pre1'gem 'actionable-rb', '~> 2.0.0.pre1'How to follow along
Section titled “How to follow along”Type each example into irb, or paste a whole chapter into one script. Begin with these two lines.
require 'field_struct'require 'actionable'Every chapter declares the classes it needs again, so you can start at any of them. Inside a chapter the examples build on each other, in order.
A line like hut.places # => 24 shows the value that expression returns. All of them are checked: the site’s build runs every example in order and fails when a result differs from its comment, so the code you read is code that ran.
Where an example needs a web server, a queue or RSpec, the tutorial uses a plain Ruby stand-in or a plain code block, and says so.
Where to go after
Section titled “Where to go after”- How-to guides: one task each
- Reference: every option and method
- Explanation: why the gems are shaped this way
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.