Steps DSL and Composition

Relevant source files

• CHANGELOG.md
• README.md
• docs/REFERENCE.md
• docs/overview/010_KEY_CONCEPTS.md
• docs/overview/020_BASIC_USAGE.md
• docs/overview/030_INTERMEDIATE_USAGE.md
• lib/solid/process/version.rb

Purpose and Scope

This document explains the Steps DSL provided by Solid::Process for expressing multi-step workflows and composing processes together. The Steps DSL implements a railway-oriented programming model where each step can continue the flow or short-circuit with a result.

Related Pages:

• For basic process structure and the call method, see Solid::Process - The Core Abstraction
• For results and outcome handling, see Results and Outcomes
• For dependency injection, see Dependencies and Injection
• For the execution lifecycle, see Process Lifecycle and Caller Module

---

Steps DSL Overview

The Steps DSL provides four core methods for chaining operations together in a process's call method:

Method	Purpose	Return Behavior
Given(hash)	Starts the step chain with initial data	Returns a Solid::Result containing the data
and_then(:method_name)	Calls a private method if previous result was successful	Skips on Failure, executes on Success
Continue(hash)	Merges data into the accumulated result and continues	Returns a Solid::Result for chaining
and_expose(:type, [:keys])	Finalizes the chain with a Success containing only specified keys	Returns Success(:type, ...)

Sources: docs/REFERENCE.md607-621 docs/overview/030_INTERMEDIATE_USAGE.md1-61

---

Steps DSL Flow Diagram

Sources: docs/REFERENCE.md662-670 docs/overview/030_INTERMEDIATE_USAGE.md9-42

---

Given - Starting the Chain

Given(hash) initiates a step chain by wrapping the provided hash in a Solid::Result object. It serves as the entry point for railway-oriented flow control.

Typical Usage:

The attributes parameter is the validated input hash passed from the process invocation. Given makes this data available to subsequent steps.

Sources: docs/REFERENCE.md632-633 docs/REFERENCE.md664

---

and_then - Conditional Step Execution

and_then(:method_name) calls a private instance method if the previous result was successful. If the previous result was a Failure or Success (not Continue), the chain short-circuits and that result becomes the final output.

Method Signature Requirements

Step methods invoked via and_then must:

1. Accept keyword arguments matching the accumulated data
2. Use the ** splat operator to ignore extra keys
3. Return Continue(), Success(), or Failure()

Example Step Method:

The ** splat is essential because the accumulated data hash may contain keys the current step doesn't need.

Sources: docs/REFERENCE.md617-618 docs/REFERENCE.md674-679

---

Step Data Flow Diagram

Sources: docs/REFERENCE.md709-717

---

Continue - Merging Data

Continue(hash) serves two purposes:

1. Signals continuation: Tells and_then to proceed to the next step
2. Merges data: Adds new key-value pairs to the accumulated data hash

Continue Variants

The merged data becomes available to all subsequent steps in the chain.

Sources: docs/REFERENCE.md618 docs/REFERENCE.md695-703

---

Success and Failure - Short-Circuiting

Returning Success(:type, ...) or Failure(:type, ...) from a step immediately stops the chain. The result bypasses all remaining and_then calls and becomes the process's final output.

Short-Circuit Example

Sources: docs/REFERENCE.md681-693 docs/REFERENCE.md695-703

---

and_expose - Finalizing Results

and_expose(:type, array_of_keys) creates the final Success result with only the specified keys from the accumulated data. This prevents leaking internal data to callers.

Example:

The first argument is the result type symbol. The second argument is an array of keys to extract from the accumulated data.

Sources: docs/REFERENCE.md619-621 docs/REFERENCE.md705-717

---

Complete Steps DSL Example

Sources: docs/REFERENCE.md623-659 docs/overview/030_INTERMEDIATE_USAGE.md11-41

---

Process Composition Patterns

Process composition allows building complex workflows by calling one process from within another. The deps block facilitates this by declaring process dependencies.

Composition Architecture

Sources: docs/REFERENCE.md933-982 docs/overview/040_ADVANCED_USAGE.md

---

Nested Process Invocation

When calling a process from within a step, you must explicitly handle the nested result using pattern matching or conditional logic.

Pattern Matching Approach

Key Points:

1. deps.user_creation.call(owner) invokes the nested process
2. Pattern matching on Solid::Success extracts data from the nested result
3. Continue(user: user, user_token: token) merges nested data into parent flow
4. Pattern matching on Solid::Failure wraps the nested error

Sources: docs/REFERENCE.md940-982

---

Error Wrapping Pattern

When a nested process fails, wrap its failure type to provide context about which operation failed:

This creates a hierarchical failure structure:

• Outer type: :invalid_owner (what failed)
• Inner type: Preserved from nested process (why it failed)

Example nested failure:

Callers can match specific nested failures:

Sources: docs/REFERENCE.md985-1007

---

Composition with Transactions

The rollback_on_failure block wraps steps in an ActiveRecord transaction. If any step returns Failure, the transaction rolls back.

Transaction Scope with Composition

Rollback Behavior:

• If create_owner returns Failure, user creation is rolled back
• If create_account fails, both user and account are rolled back
• If link_owner fails, all three operations are rolled back

Sources: docs/REFERENCE.md940-982 docs/REFERENCE.md723-823

---

Selective Transaction Scoping

Sometimes only part of the workflow should be transactional. Use .then to wrap specific steps:

This pattern:

1. Validates email uniqueness outside the transaction (read-only)
2. Opens transaction only for database writes
3. Rolls back both writes if either fails

Sources: docs/REFERENCE.md773-810

---

Nested Process Hierarchy Example

Sources: docs/REFERENCE.md933-1038

---

Railway-Oriented Programming Model

The Steps DSL implements railway-oriented programming where:

1. Happy path (Success track): Each step adds data via Continue() and proceeds
2. Failure track: Any Failure short-circuits the chain
3. Early success: Any Success (not Continue) ends the chain

Railway Track Visualization

Sources: docs/REFERENCE.md662-670 docs/overview/030_INTERMEDIATE_USAGE.md46-53

---

Code Entity Mapping

DSL Method	Code Location	Returns
Given()	Available in Solid::Process#call instance method	Solid::Result (Success)
and_then(:symbol)	Method on Solid::Result instance	Calls private instance method, returns its result
Continue()	Available in private step methods	Solid::Result (Success with :continue type)
Success(:type, hash)	Available in private step methods	Solid::Success instance
Failure(:type, hash)	Available in private step methods	Solid::Failure instance
and_expose(:type, array)	Method on Solid::Result instance	Solid::Success instance
rollback_on_failure	Available in Solid::Process#call instance method	Returns a Solid::Result

Sources: docs/REFERENCE.md613-621 lib/solid/process/version.rb4

---

Idempotency Pattern

Steps can return early Success to make processes idempotent (safe to call multiple times):

Benefits:

• Calling the process multiple times with the same user returns the existing token
• No duplicate tokens are created
• The final result type indicates whether the token was created or already existed

Sources: docs/REFERENCE.md681-693

---

Best Practices

1. Use ** Splat in Step Methods

Always include ** in step method signatures to ignore unused keys:

2. Keep Steps Focused

Each step should perform one logical operation:

3. Use and_expose to Limit Exposed Data

Only expose keys that callers need:

4. Wrap Nested Failures with Context

Provide context when propagating nested failures:

Sources: docs/REFERENCE.md674-679 docs/REFERENCE.md985-1007

---

Testing Steps and Composition

Testing Individual Steps

Test step methods directly by invoking them with test data:

Testing Composed Processes with Mocks

Inject fake dependencies to test composition in isolation:

Sources: docs/REFERENCE.md1693-1729

---

Summary

The Steps DSL provides a structured way to express complex workflows:

1. Given starts the chain with initial data
2. and_then conditionally executes steps based on previous results
3. Continue merges data and signals continuation
4. Success/Failure short-circuit the chain
5. and_expose creates the final result with selected keys

Process composition enables building hierarchical workflows by:

1. Declaring process dependencies via deps
2. Invoking nested processes within step methods
3. Pattern matching on nested results
4. Wrapping failures to provide context

This architecture promotes:

• Explicit flow control via railway-oriented programming
• Data accumulation through the chain
• Early returns for idempotency and error handling
• Testability via dependency injection and isolated steps

Sources: docs/REFERENCE.md607-1038 docs/overview/030_INTERMEDIATE_USAGE.md docs/overview/040_ADVANCED_USAGE.md