Trailblazer

https://github.com/welingtonsampaio/trailblazer-docs
Admin
Trailblazer is a collection of Ruby gems that provide higher-level architecture through new...
Tokens:69,380
Snippets:600
Trust Score:7.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Installing Trailblazer Test Suite in Minitest::Spec

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/test.md

This snippet shows the basic setup required to enable the Trailblazer Test Suite within a Minitest::Spec test class. Calling `Trailblazer::Test.module!(self, suite: true)` initializes the suite's merging logic and makes suite-specific helpers available within the test class.

```ruby
class MemoOperationTest < Minitest::Spec  # test/memo/operation_test.rb
  Trailblazer::Test.module!(self, suite: true)
```

--------------------------------

### Simulate APM Instrumentation Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Illustrates a hypothetical pattern for using an Advanced Performance Monitoring (APM) tool to start and stop a span around an operation or step. It shows basic API calls to start a span with initial payload and finish it with updated payload, providing context for the instrumentation taskWrap examples.

```Ruby
span = MyAPM.start_span("validate", payload: {time: Time.now})
# do whatever you have to...
span.finish(payload: {time: Time.now})
```

--------------------------------

### Example Call for Arbitrary Finder

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

This snippet shows an example of how an arbitrary finder method, such as `:[]`, is typically invoked by the Trailblazer Model macro, passing the value from `params[:id]` (or the configured key) as an argument.

```Ruby
Song[params[:id]]
```

--------------------------------

### Reform Prepopulator Using Options

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

This `:prepopulator` example shows how the prepopulator block can accept an `options` hash, allowing you to pass arbitrary data to the prepopulator logic when calling `prepopulate!`.

```Ruby
class AlbumForm < Reform::Form
  property :title, prepopulator: ->(options) { self.title = options[:def_title] }
end
```

--------------------------------

### Example Policy Step Implementation Class in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Provides an example of a standard Ruby class intended for use as a step in a Trailblazer Operation. It shows how a step typically receives context variables (e.g., `model`, `user`) and writes results (e.g., `status`, `message`) back to the context hash, demonstrating the data available *inside* a step before output filters are applied.

```Ruby
module Policy
  # Explicit policy, not ideal as it results in a lot of code.
  class Create
    def self.call(ctx, model:, user:, **)
      decision = ApplicationPolicy.can?(model, user, :create) # FIXME: how does pundit/cancan do this exactly?

      if decision.allowed?
        return true
      else
        ctx[:status]  = 422 # we're not interested in this field.
        ctx[:message] = "Command {create} not allowed!"
        return false
      end
    end
  end
end
```

--------------------------------

### Example Policy Step Requiring Specific Context Variables Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Provides an example implementation of a policy step (`Policy::Create`) that expects `:model` and `:user` as keyword arguments from the operation's context. This highlights a potential issue where a step relies on context variables that might not be named or provided as expected, leading to errors without variable mapping.

```Ruby
module Policy
  # Explicit policy, not ideal as it results in a lot of code.
  class Create
    def self.call(ctx, model:, user:, **)
      decision = ApplicationPolicy.can?(model, user, :create) # FIXME: how does pundit/cancan do this exactly?
      # ...
    end
  end
end
```

--------------------------------

### Example XML Output Representable XML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This is an example of the default XML output generated by the `SongRepresenter` when serializing a `Song` object. Each property and collection item is rendered as a separate tag.

```XML
<song>
  <title>Fallout</title>
  <composers>Stewart Copeland</composers>
  <composers>Sting</composers>
</song>
```

--------------------------------

### Example XML Output with Content Representable XML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This XML output example demonstrates how the `:title` property is rendered as the content within the top-level `<song>` tag, as configured by the `:content: true` option.

```XML
<song>Fallout</song>
```

--------------------------------

### Mimicking Default Nested Object Preparation Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

Shows an example of using the `:prepare` option to replicate the default behavior of decorating the nested object using the configured `:extend` representer.

```ruby
property :artist,
  prepare: ->(represented:,binding:,**) { binding[:extend].new(represented) }
```

--------------------------------

### Example YAML Output Representable YAML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This is an example of the YAML output generated by the `SongRepresenter`. It shows the `:title` and `:id` properties and the `:composers` collection rendered using the specified `:flow` style, appearing on a single line within square brackets.

```YAML
---
title: Fallout
id: 1
composers: [Stewart Copeland, Sting]
```

--------------------------------

### Example XML Output with Wrapped Collection Representable XML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This XML output example shows the result of using the `:wrap: :songs` option for the `:songs` collection. The individual `<song>` tags are correctly enclosed within a `<songs>` container tag.

```XML
<album>
  <songs>
    <song>Laundry Basket</song>
    <song>Two Kevins</song>
    <song>Wright and Rong</song>
  </songs>
</album>
```

--------------------------------

### Define TaskWrap Start Instrumentation Step Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Implements a taskWrap step method designed to start instrumentation (like an APM span) before an activity task runs. It accesses the activity context (ctx) and taskWrap context (wrap_ctx), retrieves activity and task information, starts a span, and stores the span object in wrap_ctx for subsequent taskWrap steps.

```Ruby
module MyAPM # Advanced performance monitoring, done right!
  module Extension
    def self.start_instrumentation(wrap_ctx, original_args)
      (ctx, _flow_options), circuit_options = original_args

      activity  = circuit_options[:activity] # currently running Activity.
      task      = wrap_ctx[:task]            # the current "step".

      task_id   = Trailblazer::Activity::Introspect.Nodes(activity, task: task).id

      span      = MyAPM.start_span("operation.step", payload: {id: task_id})

      wrap_ctx[:span] = span

      return wrap_ctx, original_args
    end
  end
end
```

--------------------------------

### Implementing Step Methods in Path Activity Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Provides example implementations for the `:validate` and `:create` steps within a `Trailblazer::Activity::Path` class. It shows how steps receive the context (`ctx`) and specific parameters (`params:`, `input:`) and return a value (implicitly true/false for validation).

```Ruby
class Create < Trailblazer::Activity::Path
  # ...
  def validate(ctx, params:, **)
    ctx[:input] = Form.validate(params) # true/false
  end

  def create(ctx, input:, **)
    Memo.create(input)
  end
end
```

--------------------------------

### Rendering Activity Structure (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Shows how to use `Trailblazer::Developer.render` to output a textual representation of an activity's structure to the console. This helps visualize the steps, outputs, and connections within the activity's circuit, making complex activity flows easier to understand.

```Ruby
puts Trailblazer::Developer.render(Memo::Create)
```

--------------------------------

### Implementing a Dataset Provider Method in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Provides an example of a dataset provider method, `composers_for_each`, which receives the context (`ctx`) and model, and returns an enumerable object (e.g., an array) to be iterated over by the `Each()` macro. It explicitly avoids writing to the `ctx`.

```ruby
def composers_for_each(ctx, model:, **)
  model.composers
end
```

--------------------------------

### Defining Example Models for Twin Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/disposable.md

Defines simple Ruby Struct classes (`Song`, `Artist`, `Album`) to serve as basic model examples for demonstrating the Disposable::Twin functionality. These structs provide the data structure that twins will wrap and interact with.

```Ruby
Song   = Struct.new(:name, :index)
Artist = Struct.new(:full_name)
Album  = Struct.new(:title, :songs, :artist)
```

--------------------------------

### Using Trailblazer Test Suite in Minitest::Spec

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/test.md

This snippet shows a full example of a Minitest::Spec test class configured to use the Trailblazer Test Suite. It demonstrates enabling the suite with `Trailblazer::Test.module!(self, suite: true)`, defining default operation context (`default_ctx`), expected model attributes (`expected_attributes`), the operation under test (`operation`), and the key for parameters (`key_in_params`) using `let` helper methods. It also includes an example test case using `assert_pass` with overrides.

```ruby
  # ...
  Trailblazer::Test.module!(self, suite: true)

  # The default ctx passed into the tested operation.
  let(:default_ctx) do
    {
      params: {
        memo: { # Note the {:memo} key here!
          title:   "Todo",
          content: "Stock up beer",
        }
      }
    }
  end

  # What will the model look like after running the operation?
  let(:expected_attributes) do
    {
      title:   "Todo",
      content:  "Stock up beer",
    }
  end

  let(:operation)     { Memo::Operation::Create }
  let(:key_in_params) { :memo }

  it "accepts {tag_list} and converts it to an array" do
    assert_pass(
      {tag_list: "fridge,todo"}, # input + default_ctx
      {tag_list: ["fridge", "todo"]}) # what's expected on the model.
  end
  # ...
end
```

--------------------------------

### Setup Reform with dry-validation (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Provides instructions for setting up the Reform gem to use `dry-validation`. It requires adding both gems to the Gemfile and including the `Reform::Form::Dry` module in `Reform::Form` via an initializer.

```Ruby
Add this your Gemfile.

    gem "reform"
    gem "dry-validation"

  Please use [dry-validation](http://dry-rb.org/gems/dry-validation), which is our recommended validation engine. Put the following snippet into an initializer.

    require "reform/form/dry"

    Reform::Form.class_eval do
      include Reform::Form::Dry
    end
```

--------------------------------

### Initializing Graph and Finding Node by ID (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Shows how to create a graph instance representing the structure of a Trailblazer activity using `Trailblazer::Developer::Introspect.Graph`. It then demonstrates retrieving a specific node from this graph by providing its symbolic ID (e.g., `:validate`) using the `Graph#find` method.

```Ruby
graph = Trailblazer::Developer::Introspect.Graph(Memo::Update)

node = graph.find(:validate)
```

--------------------------------

### Tracing Activity with Trailblazer::Developer.wtf? (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Illustrates how to use the lower-level `Trailblazer::Developer.wtf?` method to trace the execution of a `Trailblazer::Activity` subclass (like `Railway`) that doesn't have the standard `wtf?` class method. It shows how to pass arguments using the circuit interface format and the expected return values (signal and context tuple).

```Ruby
signal, (ctx, _) = Trailblazer::Developer.wtf?(
  Memo::Operation::Create, [{params: {title: "Remember me.."}}, {}]
)
```

--------------------------------

### Defining a Step Method within an Operation

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/test.md

Provides an example of a method definition within a Trailblazer Operation class that serves as a 'step' in the operation's workflow, showing how it accesses context (`ctx`) and parameters (`params`).

```Ruby
def save(ctx, params:, **)
  Memo.create(params[:memo])
end
```

--------------------------------

### Setup Reform with ActiveModel and reform-rails (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Provides instructions for setting up the Reform gem with `ActiveModel` validations, which requires the `reform-rails` gem. It requires adding both gems to the Gemfile and including `Reform::Form::ActiveModel::Validations` in `Reform::Form` via an initializer (though this is automatic in a Rails environment).

```Ruby
Add this to your Gemfile.

    gem "reform"
    gem "reform-rails"

  To use `ActiveModel` for validations put this into an initializer.

    require "reform/form/active_model/validations"

    Reform::Form.class_eval do
      include Reform::Form::ActiveModel::Validations
    end

  Things you should know when using ActiveModel with Reform.

  * `ActiveModel` support is provided by the `reform-rails` gem. You have to add it to your `Gemfile`.
  * The above last step of including `ActiveModel::Validations` is done automatically in a Rails environment.
  * Reform works fine with Rails 3.1-4.2. However, inheritance of validations with `ActiveModel::Validations` is broken in Rails 3.2 and 4.0.
```

--------------------------------

### Define Activity for Introspection Examples Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Provides a simple Trailblazer Activity definition used specifically as an example to demonstrate the Activity Introspection API. It includes basic steps and a subprocess with an explicit ID, showcasing elements that can be queried via introspection.

```Ruby
module Song::Activity
  class Create < Trailblazer::Activity::Railway
    step :validate
    step Subprocess(Save),
      id: :save
  end
end
```

--------------------------------

### Examples of Populator Return Values in Reform

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

This snippet provides examples of valid and invalid return values for a Reform `:populator`. It is crucial that a populator returns the *nested form instance* representing the fragment, not the underlying model object, for deserialization to succeed.

```Ruby
populator: -> (collection:, index:, **) do
  songs[index]              # works, unless nil
  collection[index]         # identical to above
  songs.insert(1, Song.new) # works, returns form
  songs.append(Song.new)    # works, returns form
  Song.new                  # crashes, that's no form
  Song.find(1)              # crashes, that's no form
end
```

--------------------------------

### Example XML Output with Attribute Representable XML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This XML output example shows how the `:title` property is rendered as an attribute (`title="Fallout"`) on the top-level `<song>` tag, as configured by the `:attribute: true` option in the representer.

```XML
<song title="Fallout">
  <composers>Stewart Copeland</composers>
  <composers>Sting</composers>
</song>
```

--------------------------------

### Using Trailblazer Test Suite with Minitest::Test

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/test.md

This snippet demonstrates enabling and configuring the Trailblazer Test Suite when using the `Minitest::Test` style instead of `Minitest::Spec`. This requires passing `spec: false` to `Trailblazer::Test.module!` and defining defaults (`operation`, `default_ctx`, `expected_attributes`, `key_in_params`) as instance methods (`def method_name`) instead of using `let`. Includes an example test method.

```ruby
class MemoCreateTest < Minitest::Test
  Trailblazer::Test.module!(self, suite: true, spec: false)
  # ...
  def operation; Memo::Operation::Create end
  def default_ctx; {params: {memo: {title: "Note to self", content: "Remember me!"}}} end
  def expected_attributes; {title: "Note to self", content: "Remember me!"} end
  def key_in_params; :memo end

  def test_our_assertions
    assert_pass({}, {})
  end
end
```

--------------------------------

### Using Various Callable Types as Trailblazer Operation Steps (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/internals.md

Shows examples of using different callable objects as steps in a Trailblazer operation: a Module, a Symbol (referencing a method), and a Proc/Lambda. Illustrates the flexibility of the step API provided by `Trailblazer::Option`.

```Ruby
class Song::Create < Trailblazer::Operation
  step Authorize				# Module callable
  step :model					# Method callable
  step ->(ctx, model:, **) { puts model }	# Proc callable
end
```

--------------------------------

### Defining Basic Trailblazer Cell Anatomy (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/cells.md

Illustrates the basic anatomy of a cell class inheriting from `Cell::ViewModel`. The `#show` method is the default public method, and calling `#render` without arguments renders the corresponding view template (`app/cells/comment/show.haml` in this example).

```Ruby
class CommentCell < Cell::ViewModel
  def show
    render # renders app/cells/comment/show.haml
  end
end
```

--------------------------------

### Defining a Pundit-Compatible Policy Class

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

This snippet shows a simple example of a Ruby class compatible with Pundit. It includes an `initialize` method accepting `user` and `model`, and rule methods (like `create?`, `new?`) that return boolean based on permissions.

```Ruby
class MyPolicy
  def initialize(user, model)
    @user, @model = user, model
  end

  def create?
    @user == Module && @model.id.nil?
  end

  def new?
    @user == Class
  end
end
```

--------------------------------

### Define Base Activity Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Defines a simple Trailblazer Activity using the Railway DSL, outlining a basic process flow with steps like create_model, validate, handle_errors, and notify. This activity serves as the base example for demonstrating taskWrap usage throughout the document.

```Ruby
module Song::Activity
  class Create < Trailblazer::Activity::Railway
    step :create_model
    step :validate
    left :handle_errors
    step :notify
    # ...
  end
end
```

--------------------------------

### Using Trailblazer Documentation code_tabs Helper (ERB)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/internals.md

Provides an example of using the `#code_tabs` helper within documentation markdown (likely ERB) to automatically generate tabs showing Activity and Operation code snippets based on a base filename (`"create"`). This helper simplifies presenting both forms of the same logic in documentation. This is a documentation-specific helper, not application code.

```ERB
< %= code_tabs "create" %>
```

--------------------------------

### Introspecting Base Trailblazer Operation Step IO - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

This snippet uses `Trailblazer::Developer::Render::TaskWrap` to visualize the input and output variable mapping configuration for the `:policy` step in the base `Memo::Operation::Create` operation. It helps understand the step's data flow setup before inheritance and modification. Requires the `trailblazer-developer` gem.

```Ruby
puts Trailblazer::Developer::Render::TaskWrap.(Memo::Operation::Create, id: :policy)
```

--------------------------------

### Defining Basic Trailblazer Activity (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Defines a simple Trailblazer Activity class inheriting from `Trailblazer::Activity::Railway`. It includes basic `step` definitions, illustrating the structure of a low-level activity that does not automatically inherit the `#wtf?` class method available on `Trailblazer::Operation`.

```Ruby
module Memo::Operation
  class Create < Trailblazer::Activity::Railway # Note that this is not an {Operation}!
    step :extract_markdown
    step :model
    # ...
  end
end
```

--------------------------------

### Accessing Graph Node Task (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Shows how to get the low-level `Trailblazer::Activity` task object associated with a specific node in the introspection graph using the `#task` method. This task object is the actual callable entity for that part of the activity circuit, potentially a wrapper around user code.

```Ruby
# puts node.task #=> #<Trailblazer::Activity::TaskBuilder::Task user_proc=validate>
```

--------------------------------

### Applying Default Protocol Block to Specific Trailblazer Endpoint (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/endpoint.md

Shows how a specific operation endpoint (`Memo::Operation::Update`) can implicitly or explicitly use a predefined protocol configuration (like the one set via `:protocol_block`). This example references a conceptual `MyProtocol` which includes the specified wiring.

```ruby
class MemosController < ApplicationController
  # ...
  endpoint Memo::Operation::Update, protocol: MyProtocol # {fail_fast} => {not_found}
  # ...
end
```

--------------------------------

### Defining Operation with Each Macro - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Similar to the Activity example, this snippet demonstrates the use of the `Each` macro within a Trailblazer Operation. It specifies a method (`:composers_for_each`) to provide the collection for iteration. The steps within the `Each` block (`step :notify_composers`) are executed once per item in the collection, making the item and its index available in the `ctx`, showcasing that `Each` works identically for both Activities and Operations.

```Ruby
module Song::Operation
  class Cover < Trailblazer::Operation
    step :model
    step Each(dataset_from: :composers_for_each) {
      step :notify_composers
    }
    step :rearrange

    # "decider interface"
    def composers_for_each(ctx, model:, **)
      model.composers
    end

    def notify_composers(ctx, index:, item:, **)
      Mailer.send(to: item.email, message: "#{index}) You, #{item.full_name}, have been warned about your song being copied.")
    end
    def model(ctx, params:, **)
      ctx[:model] = Song.find_by(id: params[:id])
    end

    include T.def_steps(:rearrange)
  end
end
```

--------------------------------

### Handling Manual Operation Outcome (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/rails_integration.md

Extends the manual invocation example to show handling the operation's result. It checks `result.success?` to redirect on success or assign the form object (`:"contract.default"`) and render on failure.

```Ruby
class SongsController < ApplicationController
  def create
    result = Song::Operation::Create.(params: params) # manual invocation.

    if result.success?
      redirect_to song_path(result[:model].id)
    else # failure
      @form = result[:"contract.default"]

      render
    end
  end
end
```

--------------------------------

### Invalid Trailblazer Operation Step Signatures (Old Style) - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

This Ruby snippet provides examples of step method signatures that were valid in older versions of Trailblazer but are no longer supported in 2.1. Signatures accepting only the `options` hash or only keyword arguments will cause errors. The new signature requires a positional `ctx`/`options` argument followed by keyword arguments.

```Ruby
class Memo::Create < Trailblazer::Operation
  def create_model(options)
    # ..
  end

  # or

  def create_model(model:, **)
    # ..
  end
end
```

--------------------------------

### Aliasing Step Outcomes for Migration Aid - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

This Ruby snippet provides a temporary workaround for migrating from the `success`/`failure` step keywords to the new `pass`/`fail` keywords in Trailblazer. By using `alias_method`, it maps the new names to the old methods, allowing developers to start using the new syntax before fully upgrading to Trailblazer 2.1. This code should be placed in an initializer and removed after the migration is complete.

```Ruby
Trailblazer::Operation::Pipetree::DSL.send(:alias_method, :pass, :success)
Trailblazer::Operation::Pipetree::DSL.send(:alias_method, :fail, :failure)
```

--------------------------------

### Define Operation for Introspection Examples Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Provides a simple Trailblazer Operation definition used as another example for the Activity Introspection API, showing that introspection also works on Operations (which internally wrap activities). It includes a step and a subprocess with an explicit ID, mirroring the activity example.

```Ruby
module Song::Operation
  class Create < Trailblazer::Operation
    step :validate
    step Subprocess(Save),
      id: :save
  end
end
```

--------------------------------

### Defining Activity with Multiple Tracks (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Defines a Trailblazer Activity subclass showing the use of `step` and `fail` DSL methods to define different execution tracks based on task outcomes. It also demonstrates mapping a specific output signal (`Output(:failure)`) from a step to a named end event (`End(:validation_error)`), controlling the circuit flow.

```Ruby
class Memo::Update < Trailblazer::Activity::Railway
  step :find_model
  step :validate, Output(:failure) => End(:validation_error)
  step :save
  fail :log_error
end
```

--------------------------------

### Referencing Trailblazer Activity Signals (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

This commented-out snippet provides examples of the standard signals used in Trailblazer Activities: `Trailblazer::Activity::Left` and `Trailblazer::Activity::Right`. These typically represent failure and success paths, respectively, and are fundamental to activity flow control.

```Ruby
# - Trailblazer::Activity::Left
# - Trailblazer::Activity::Right

```

--------------------------------

### Accessing Outgoing Connection Output Details (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Illustrates how to access the `Output` object associated with an outgoing connection using the `#output` method on the `Outgoing` object. This object contains details like the signal object that triggers the connection (`#signal`) and its semantic meaning (`#semantic`), providing insight into the transition logic.

```Ruby
# puts left.output.signal   #=> Trailblazer::Activity::Left
# puts left.output.semantic #=> :failure
```

--------------------------------

### Using Each Macro with dataset_from in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Demonstrates the basic syntax for using the `Each()` macro in a Trailblazer activity or operation, specifying the dataset provider method via the `:dataset_from` option.

```ruby
step Each(dataset_from: :composers_for_each) {
  step :notify_composers
}
```

--------------------------------

### Implementing Exception Handling Wrap Handler - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

This example shows a `Wrap` handler that uses a `rescue` block to catch exceptions thrown by the wrapped steps. If an exception occurs, the handler catches it, stores the exception message in the context (`ctx[:exception]`), and returns `Trailblazer::Activity::Left` to indicate failure to the main activity, allowing error handling logic to be triggered.

```Ruby
class MyRescue
  def self.call((ctx, flow_options), **, &block)
    signal, (ctx, flow_options) = yield # calls the wrapped steps

    return signal, [ctx, flow_options]
  rescue
    ctx[:exception] = $!.message
    return Trailblazer::Activity::Left, [ctx, flow_options]
  end
end
```

--------------------------------

### Create Runtime TaskWrap Extension Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Demonstrates how to define a runtime taskWrap extension by grouping the `start_instrumentation` and `finish_instrumentation` taskWrap steps. It uses `Trailblazer::Activity::TaskWrap::Extension` and specifies where these new steps should be inserted relative to the original task execution (using `prepend` and `append` relative to `task_wrap.call_task`).

```Ruby
apm_extension = Trailblazer::Activity::TaskWrap::Extension(
  [MyAPM::Extension.method(:start_instrumentation),  id: "my_apm.start_span",  prepend: "task_wrap.call_task"],
  [MyAPM::Extension.method(:finish_instrumentation), id: "my_apm.finish_span", append: "task_wrap.call_task"],
)
```

--------------------------------

### Building New Model using Model::Build in Trailblazer

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Demonstrates using the `Model::Build` macro with a method like `:new` to instantiate a new model instance for operations like Create. The new instance is assigned to `ctx[:model]`.

```Ruby
module Song::Activity
  class Create < Trailblazer::Activity::Railway
    step Model::Build(Song, :new)
    step :validate
    step :save
    # ...
  end
end
```

```Ruby
module Song::Operation
  class Create < Trailblazer::Operation
    step Model::Build(Song, :new)
    step :validate
    step :save
    # ...
  end
end
```

--------------------------------

### Accessing Graph Node Outputs (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/README.md

Shows how to retrieve an array of all `Output` objects directly from a node using the `#outputs` method. Each object in the array represents a potential output of the node, defining a possible exit point or signal, regardless of whether it currently has an outgoing connection defined in the graph.

```Ruby
outputs = node.outputs
left = outputs[0] #=> output object
```

--------------------------------

### Rewiring Step Failure Output to Success Track (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Illustrates using the Trailblazer Wiring API `Output()` and `Track()` helpers to modify the default flow of a step. This example shows how to explicitly route the `:failure` output of the `:save` step back to the `:success` track, rather than allowing it to proceed to the `:failure` track, demonstrating a custom success/failure handling scenario.

```Ruby
module Memo::Operation
  class Create < Trailblazer::Operation
    step :validate
    step :save,
      Output(:failure) => Track(:success)
    left :handle_errors
    step :notify
    # ...
  end
end
```

--------------------------------

### Example Dry Validation Error Messages YAML - YAML

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Provides a simple example structure for a YAML file used to define custom error messages for `dry-validation`, showing how to map a rule name (e.g., `same_password?`) to a message string under the `en: errors:` namespace.

```YAML
en:
  errors:
    same_password?: "passwords not equal"
```

--------------------------------

### Correct Context Initialization with Trailblazer::Context Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Demonstrates the correct way to initialize context for a Trailblazer activity by wrapping a hash (even one with string keys) using `Trailblazer::Context`. This ensures that keys are properly handled (converted to symbols) for use within the activity's steps.

```Ruby
ctx = Trailblazer::Context({"message" => "Yes, works!"})

signal, (ctx, _) = Bla.([ctx])
```

--------------------------------

### Invoking Path Activity and Checking Result Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Shows how to instantiate a context (using a hash, implicitly wrapped by `Trailblazer::Context` by the activity's call method) and invoke a Trailblazer Activity class. It demonstrates capturing the returned signal and the updated context, then printing the signal.

```Ruby
ctx = {params: nil}
signal, (ctx, flow_options) = Memo::Create.([ctx, {}])

puts signal #=> #<Trailblazer::Activity::End semantic=:invalid>
```

--------------------------------

### Implementing skip_render Option in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This snippet illustrates how to use a lambda/proc with the `skip_render` option to conditionally prevent a property from being rendered. The example condition checks `user_options` and a property of the input object.

```Ruby
skip_render: lambda { |options|
# raise options[:represented].inspect
        options[:user_options][:skip?] and options[:input].name == "Rancid"

```

--------------------------------

### Define Static TaskWrap Extension Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Shows how to define a taskWrap extension statically at compile-time within the activity class definition. It uses the `Extension()` and `Trailblazer::Activity::TaskWrap::Extension::WrapStatic()` helpers on a specific step (`:validate`) to define the `start` and `finish` instrumentation methods and their placement around the step's execution.

```Ruby
module Song::Activity
  class Create < Trailblazer::Activity::Railway
    step :create_model
    step :validate,
      Extension() => Trailblazer::Activity::TaskWrap::Extension::WrapStatic(
        [MyAPM::Extension.method(:start_instrumentation),  id: "my_apm.start_span",  prepend: "task_wrap.call_task"],
        [MyAPM::Extension.method(:finish_instrumentation), id: "my_apm.finish_span", append: "task_wrap.call_task"],
      )
    left :handle_errors
    step :notify
    include T.def_steps(:create_model, :validate, :notify)
  end
end
```

--------------------------------

### Creating & Wiring Custom Track with Track() and magnetic_to - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Shows how to define a custom terminus (`:paypal`), initiate a custom track by wiring an output (`:failure` from `:find_provider`) to `Track(:paypal)`, and explicitly place a step (`:charge_paypal`) onto this track using `:magnetic_to: :paypal`.

```ruby
module Memo::Operation
  class Charge < Trailblazer::Operation
    terminus :paypal # add a custom terminus (if you need it)
    step :validate
    step :find_provider,
      Output(:failure) => Track(:paypal)
    step :charge_paypal,
      magnetic_to: :paypal, Output(:success) => Track(:paypal)
    step :charge_default
    # ...
  end
end
```

--------------------------------

### Manually Building Contract Instance with Builder Option (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Shows how to use the `builder:` option in the `Contract::Build` macro to provide a custom method (`default_contract!`) responsible for instantiating the contract, allowing for dependency injection like the current user.

```Ruby
class Create < Trailblazer::Operation

  class MyContract < Reform::Form
    property :title
    property :current_user, virtual: true

    validate :current_user?
    validates :title, presence: true

    def current_user?
      return true if defined?(current_user)
      false
    end
  end

  step Model( Song, :new )
  step Contract::Build( constant: MyContract, builder: :default_contract! )
  step Contract::Validate()
  step Contract::Persist( method: :sync )

  def default_contract!(options, constant:, model:, **)
    constant.new(model, current_user: options [:current_user])
  end
end
```

--------------------------------

### Patching Activity Block within Each Macro in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Shows how to use `Trailblazer::Activity::DSL::Linear::Patch` to modify the nested activity block executed by the `Each()` macro, for example, by inserting a new step.

```ruby
cover_patched = Trailblazer::Activity::DSL::Linear::Patch.(
  Song::Activity::Cover,
  ["Each/composers_for_each", "Each.iterate.block"],
  -> { step :log_email }
)
```

--------------------------------

### Nested Activity with Custom End Terminus - Trailblazer - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Provides an example structure for a nested activity (`VorbisComment`) that defines a custom end terminus (`End(:unsupported_file_format)`) using the `Output()` method in a step definition.

```Ruby
module Song::Activity
  class VorbisComment < Trailblazer::Activity::Railway
    step :prepare_metadata
    step :encode_cover, Output(:failure) => End(:unsupported_file_format)
    # ...
  end
end
```

--------------------------------

### Debugging Activity with Each Macro in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Shows how to use `Trailblazer::Developer.wtf?` to trace the execution of a Trailblazer Activity that includes an `Each()` macro, allowing visualization of iterations.

```ruby
Trailblazer::Developer.wtf?(Song::Activity::Cover, [{
  params: {id: 1},
  # ...
}])
```

--------------------------------

### Example Nested Activity Structure - Trailblazer - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Shows a simple `Trailblazer::Activity::Railway` structure for an activity (`Id3Tag`) intended to be used as a nested activity within another operation via the `Nested()` macro.

```Ruby
module Song::Activity
  class Id3Tag < Trailblazer::Activity::Railway
    step :parse
    step :encode_id3
    # ...
  end
end
```

--------------------------------

### Invoking Reform Prepopulation with Options

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

This snippet demonstrates how to call the `prepopulate!` method and pass a hash of options. These options are then made available within the `:prepopulator` block or method configured for the form's properties.

```Ruby
form.title #=> nil

form.prepopulate!(def_title: "Roxanne")

form.title #=> "Roxanne"
```

--------------------------------

### Invoke Activity with Runtime TaskWrap (All Steps) Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Shows how to invoke an activity (`Song::Activity::Create`) and apply a runtime taskWrap extension to *every* step. This is achieved by providing a `Hash.new(apm_extension)` as the `wrap_runtime` option, making the specified extension the default for any task that doesn't have a specific wrap configured.

```Ruby
my_wrap = Hash.new(apm_extension)

Song::Activity::Create.invoke(
  [
    # ctx:
    {
      song: {title: "Timebomb"},
      seq: []
    }
  ],
  wrap_runtime: my_wrap # runtime taskWrap extensions!
)
```

--------------------------------

### Skipping Fragment Processing in Reform Populator

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

This `:populator` example shows how to use `return skip!` within the populator block to completely ignore an incoming fragment based on custom logic, preventing it from being processed further or matched/created.

```Ruby
collection :songs,
  populator: ->(fragment:, **) do
    return skip! if fragment["id"]
    # ..
  end
```

--------------------------------

### Using Assert_exposes with Custom Reader Method in Minitest

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/test.md

Shows how to use the `:reader` option with `assert_exposes` to specify a custom method name (e.g., `:get`) that the asserted object uses to read attributes (`object.get(:key)`).

```Ruby
it do
  assert_exposes model, {title: "Timebomb", band: "Rancid"}, reader: :get
end
```

--------------------------------

### Accessing Representer Options (Keyword Args) in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This snippet provides an alternative modern approach to accessing runtime information using keyword arguments directly in the `instance` proc's parameter list. It shows how to destructure `binding` and `user_options` directly.

```Ruby
property :artist, instance: ->(binding:, user_options:, **) do
  binding.represented  # the represented object
end
```

--------------------------------

### Accessing Collection Item in Reform Form (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Illustrates instantiating `AlbumForm` with a model that has a `song_titles` array. It then shows how to access individual elements within the `song_titles` collection on the form instance, which were read from the model during setup.

```Ruby
model = Album.new(song_titles: ["The Reflex", "Wild Boys"])

form = AlbumForm.new(model)
form.song_titles[0] #=> "The Reflex"
```

--------------------------------

### Instantiating Reform Form and Accessing Property (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Illustrates creating an `AlbumForm` instance by passing a model object. It then shows how to access the value of the `title` property on the form instance, which is read from the model during initialization (setup).

```Ruby
model = Album.new(title: "Greatest Hits")
form  = AlbumForm.new(model)

form.title #=> "Greatest Hits"
```

--------------------------------

### Composing an Activity in Each Macro in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Shows how to specify a separate Trailblazer Activity (`Notify`) to be executed for each item in the dataset instead of defining steps directly within the `Each()` macro block.

```ruby
module Song::Activity
  class Cover < Trailblazer::Activity::Railway
    step :model
    step Each(Notify, dataset_from: :composers_for_each)
    step :rearrange
    # ...
  end
end
```

--------------------------------

### Introspect Activity Node by Task Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Shows how to use the `Trailblazer::Activity::Introspect.Nodes()` API to find the attributes for a step when you only have the task object itself, rather than its ID. This is useful, for example, when iterating through tasks or dealing with subprocesses directly.

```Ruby
attrs = Trailblazer::Activity::Introspect.Nodes(Song::Activity::Create, task: Song::Activity::Save)
```

--------------------------------

### Initializing Disposable Twin Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/disposable.md

Shows how to create a new instance of a Disposable::Twin, passing the model object it will decorate and optionally passing an options hash. The subsequent code demonstrates reading properties, including one derived from the options hash, and overriding a property value during initialization.

```Ruby
album = Album.new("Nice Try")
twin  = AlbumTwin.new(album, playable?: current_user.can?(:play))
```

```Ruby
twin.title     #=> "Nice Try"
twin.playable? #=> true
```

```Ruby
twin = AlbumTwin.new(album, title: "Plasticash")
twin.title #=> "Plasticash"
```

--------------------------------

### Manually Extracting Parameters in Trailblazer Operation (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Provides an example of adding a custom step (`:extract_params!`) to manually process or extract parameters before the `Contract::Validate` step. The extracted parameters are placed at `options[:"contract.default.params"]`.

```Ruby
class Create < Trailblazer::Operation
  class MyContract < Reform::Form
    property :title
  end

  def type
    "evergreen" # this is how you could do polymorphic lookups.
  end

  step Model( Song, :new )
  step Contract::Build(constant: MyContract)
  step :extract_params!
  step Contract::Validate( skip_extract: true )
  step Contract::Persist( method: :sync )

  def extract_params!(options, **)
    options[:"contract.default.params"] = options[:params][type]
  end
end
```

--------------------------------

### Defining a Custom Rescue Handler Class

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

This snippet provides an example definition for a custom handler class intended for use with the `Rescue()` macro's `:handler` option. The `call` method receives the exception and the circuit context arguments.

```Ruby
class MyHandler
  def self.call(exception, (ctx), *)
    ctx[:exception_class] = exception.class
  end
end
```

--------------------------------

### Tracing Wrap Macro Execution with WTF? - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

This snippet demonstrates how to use the Trailblazer developer debugger (`Trailblazer::Developer.wtf?`) to visualize the execution trace of an activity that incorporates the `Wrap` macro. This helps in understanding the flow, including the execution of the wrapped steps and the control transfer between the main activity and the wrapped block.

```Ruby

Trailblazer::Developer.wtf?(Song::Activity::Upload, params: {id: 1})

```

--------------------------------

### Defining Another Trailblazer Endpoint (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/endpoint.md

This Ruby snippet provides another example of defining a Trailblazer endpoint in a Rails controller, associating the `Memo::Operation::Update` operation with the custom `MyProtocol` using the `::endpoint` method.

```Ruby
class MemosController < ApplicationController
  # ...
  endpoint Memo::Operation::Update, protocol: MyProtocol
  # ...
end
```

--------------------------------

### Deprecated Render Filter Syntax Representable Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/representable.md

This snippet shows an example of the deprecated syntax for defining a render filter option (like `:render_filter`). It uses positional arguments for the lambda, which is no longer the recommended approach in newer Representable versions.

```Ruby
:render_filter => lambda { |val, options| "#{val.upcase},#{options[:doc]},#{options[:options][:user_options]}" }
```

--------------------------------

### Connecting Output to Next Step on Track with Track() - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Demonstrates using the `Track()` helper to connect a step's output (`:failure` from `:save`) to the next available step (`:notify`) located on the specified track (`:success`). This helper finds the appropriate step dynamically.

```ruby
module Memo::Operation
  class Create < Trailblazer::Operation
    step :validate
    step :save,
      Output(:failure) => Track(:success)
    left :handle_errors
    step :notify
    # ...
  end
end
```

--------------------------------

### Validating Collection Input with Reform

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

This snippet shows an example of the input hash structure used when validating a form with a collection property named `songs`. Each element in the `songs` array is a hash representing a nested item's data.

```JSON
form.validate({
  songs: [
    {name: "Midnight Rendezvous"},
    {name: "Information Error"}
  ]
})
```

--------------------------------

### Creating Path Leading to Terminus with Path() - Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/operation.md

Demonstrates using the `Path()` macro with the `:terminus` option to create a branching path (`:charge_paypal`) that is executed when the preceding step's output (`:failure` from `:find_provider`) is triggered. The path terminates at the specified terminus (`:paypal`).

```ruby
module Memo::Operation
  class Charge < Trailblazer::Operation
    step :validate
    step :find_provider,
      Output(:failure) => Path(terminus: :paypal) do
        # step :authorize # you can have multiple steps on a path.
        step :charge_paypal
      end
    step :charge_default
    # ...
  end
end
```

--------------------------------

### Executing Activity with Collected Data in Ruby

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/macro.md

Demonstrates executing a Trailblazer Activity that uses the `Each()` macro with the `:collect` option and then accessing the collected data from `ctx[:collected_from_each]` after the activity completes.

```ruby
ctx = {params: {id: 1}} # Song 1 has two composers.

signal, (ctx, _) = Trailblazer::Activity.(Song::Activity::Cover, ctx)

puts ctx[:collected_from_each] #=> [[0, "Fat Mike"], [1, "El Hefe"]]
```

--------------------------------

### Overriding Property Accessor in Reform Form (Ruby)

Source: https://github.com/welingtonsampaio/trailblazer-docs/blob/main/reform.md

Demonstrates overriding the `title` getter method on `AlbumForm`. It calls `super` to get the original value from the form (which was read from the model or deserialized input) and then applies the `capitalize` method before returning it.

```Ruby
class AlbumForm < Reform::Form
  property :title

  def title
    super.capitalize
  end
end
```
Tokens:
Raw