hubbado-sequence 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf9d0a82e802923d5f0a04043400578eb8c90ad8c78a00073a30c99cab8784e6
-  data.tar.gz: 91e67b7ed3f8fc5fe428bcfea0eb359d4f8c03edb090ccba56d1a16799d2a48d
+  metadata.gz: 225c967e73e28a28effbc26e9c3bbdfce3357932a8374046dc46056d0dd8dd7d
+  data.tar.gz: 7a446faedf4bb88018c17a6130f29ec85f1fc354929864aaa2dd55f86753ffca
 SHA512:
-  metadata.gz: 902c46876f2df354ce46f340ef0fa6432d34c867eaff764c14e5ab54f54a8bb1dc466601c1c3da8f3823d5c0637af3d5c279e7bdb3596c8ff6a785488a333d31
-  data.tar.gz: 9edff4e5aa8e45dbdb20a31f7cfe360c6f03f8751986cef344146be16e5d5e771c1c8318ef89ab80baef61b89927aabe327ac29c175bbdc7246e00257db8086d
+  metadata.gz: f5ae7e6141a9d45576b0b93a0c25ac23a63a9d3a5b4ea5ba134103a91db20633a17a1dc4e41a7a73570dc6745446d55e4e22612249dd75211d9c2be1c02a3143
+  data.tar.gz: a741030d0046941b128a18bc8bb0f58f10bdb677cd8941857d8937263e4dd2c58aaaac6fd2c816deac3f8d310a256c67af516dc7e8428aa3e5e29791cafa3676

data/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.4.0] - Inline step blocks removed; Pipeline made internal
+
+### Removed (breaking)
+
+- **Inline block form of `step` removed.** `p.step(:name) { |ctx| ... }`
+  is no longer supported. Every step must be a method on the sequencer
+  with the same name:
+
+  ```ruby
+  # before
+  p.step(:notify) { |ctx| UserMailer.updated(ctx[:user]).deliver_later }
+
+  # after
+  p.step(:notify)          # dispatches to def notify(ctx)
+  ```
+
+  Migration: extract each inline block to a private method of the same
+  name. One method per step; one method per responsibility.
+
+- **`Pipeline` is no longer part of the public API.** `Pipeline.(ctx)`
+  and `Pipeline.new` are internal to the framework. Sequencers build
+  pipelines exclusively through the `pipeline(ctx)` helper.
+
+  Migration: any direct `Pipeline.(ctx)` or `Pipeline.new(ctx, ...)`
+  call sites must be replaced with a sequencer that uses `pipeline(ctx)`.
+
+### Changed
+
+- **`Pipeline#step` always auto-dispatches.** With inline blocks gone,
+  `step(:foo)` unconditionally dispatches to `self.foo(ctx)` on the
+  sequencer — no block-versus-dispatch ambiguity. Missing methods raise
+  `NoMethodError` with the step name and the sequencer class in the
+  message.
+
 ## [0.3.0] - Contract::Deserialize macro, Runner extraction, Path helper
 
 ### Added

data/README.md

@@ -114,29 +114,27 @@ class UsersController < ApplicationController
 end
 ```
 
-## The three step shapes
+## The two step shapes
 
 ```ruby
 pipeline(ctx) do |p|
-  p.invoke(:find, :user)                # declared dependency (macro or sequencer)
-  p.step(:scrub_params)                 # local method `def scrub_params(ctx)`
-  p.step(:audit) { |c| AuditLog.append(c[:user]) }   # inline block
+  p.invoke(:find, User, as: :user)  # declared dependency (macro or sequencer)
+  p.step(:scrub_params)             # local method `def scrub_params(ctx)`
 end
 ```
 
 - `p.invoke(:foo, *args, **kwargs)` — a `dependency :foo, …` declared on the
   sequencer (a macro or a nested sequencer). Calls
   `dispatcher.foo.(ctx, *args, **kwargs)`.
-- `p.step(:foo)` — a local instance method. Auto-dispatches to
-  `self.foo(ctx)`.
-- `p.step(:foo) { |ctx| … }` — explicit inline block.
+- `p.step(:foo)` — a local instance method. Dispatches to `self.foo(ctx)`.
 
-The `pipeline(ctx)` helper (lowercase `p`) is what enables blockless
-`p.step(:foo)` auto-dispatch — it builds a Pipeline that knows which
-sequencer to dispatch back to. `Pipeline.(ctx)` (capital `P`) is the bare
-constructor with no dispatcher and requires every `step` to have a block.
-Use `pipeline(ctx)` inside a sequencer; `Pipeline.(ctx)` is mainly useful
-for framework tests.
+Every `step` is a method on the sequencer with the same name as the step.
+This makes the `call` body a table of contents — scan `p.step(:...)` lines
+to see the sequence shape, jump to the method for details.
+
+`pipeline(ctx)` is the only way to build a pipeline. The underlying
+Pipeline class is an implementation detail; sequencers do not construct
+it directly.
 
 ## Built-in macros
 
@@ -273,9 +271,15 @@ def call(ctx)
       t.invoke(:persist)
     end
 
-    p.step(:notify) { |c| UserMailer.updated(c[:user]).deliver_later }
+    p.step(:notify)
   end
 end
+
+private
+
+def notify(ctx)
+  UserMailer.updated(ctx[:user]).deliver_later
+end
 ```
 
 Steps before the transaction run outside it (read-only lookups, policy

data/hubbado-sequence.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name = "hubbado-sequence"
-  s.version = "0.3.0"
+  s.version = "0.4.0"
   s.summary = "A small framework for orchestrating units of business behaviour"
   s.description = "Sequencer takes input, runs a sequence of steps, and returns a Result indicating success or failure plus the working context that was built up during execution."
 

data/lib/hubbado/sequence/pipeline.rb

@@ -1,84 +1,45 @@
 module Hubbado
   module Sequence
+    # Railway-style step runner that backs the Sequencer mixin's
+    # `pipeline(ctx)` helper. Not part of the public API — sequencers reach
+    # it through the helper.
     class Pipeline
-      # `Pipeline.(ctx) { |p| ... }` is the block form: yields the pipeline,
-      # runs the block (so steps can be added in statement form), and returns
-      # the final Result. The non-block form returns the Pipeline so chained
-      # `.step(...)...result` calls still work.
-      def self.call(ctx = nil, **kwargs, &block)
-        if ctx.nil?
-          ctx = Ctx.build(kwargs)
-        elsif !kwargs.empty?
-          raise ArgumentError, "Pipeline.() takes either a Ctx or keyword arguments, not both"
-        elsif !ctx.is_a?(Ctx)
-          ctx = Ctx.build(ctx)
-        end
-
-        pipe = new(ctx)
-
-        if block
-          block.call(pipe)
-          pipe.result
-        else
-          pipe
-        end
-      end
-
-      def initialize(ctx, dispatcher: nil)
+      def initialize(ctx, dispatcher:)
         @ctx = ctx
         @trail = []
         @failed_result = nil
         @dispatcher = dispatcher
       end
 
-      # `step(:name) { |ctx| ... }` runs the block. `step(:name)` with no
-      # block dispatches to `dispatcher.send(name, ctx)` on the sequencer
-      # that built this pipeline (via the mixin's `pipeline(ctx)` helper).
-      # Block beats dispatch when both are available; raises if neither.
-      #
-      # Lenient return convention: a step is treated as successful unless it
-      # explicitly returns a failed `Result`. Any other return value (nil,
-      # false, a model, a hash, `Result.ok(...)`) is taken as success and the
-      # pipeline continues with the same `@ctx`. Only `Result.fail(...)` /
-      # `failure(ctx, code: ...)` short-circuits the pipeline.
-      def step(name, &block)
+      # `step(:name)` dispatches to `dispatcher.send(name, ctx)`. The method
+      # is treated as successful unless it explicitly returns a failed
+      # `Result`; any other return value (nil, false, a model, `Result.ok`)
+      # continues the pipeline with the same ctx. Only `Result.fail(...)` /
+      # `failure(ctx, code: ...)` short-circuits.
+      def step(name)
         return self if @failed_result
 
-        return_value = invoke_step(name, block)
-
-        if return_value.is_a?(Result) && return_value.failure?
-          @failed_result = tag_failure(return_value, name)
-        else
-          @trail << name
-        end
-
+        record(name, invoke_step(name))
         self
       end
 
       # `invoke(:name, *args, **kwargs)` calls a declared dependency on the
-      # sequencer: gets the dependency via `dispatcher.send(name)` (the
-      # reader), then invokes it with `(ctx, *args, **kwargs)`. Same trail
-      # recording, failure short-circuiting, and lenient return convention as
-      # `step`.
+      # dispatcher: gets it via `dispatcher.send(name)` (the reader), then
+      # invokes it with `(ctx, *args, **kwargs)`. Same trail recording,
+      # failure short-circuiting, and lenient return convention as `step`.
       #
-      # Use this for any declared dependency — macros (`Macros::Model::Find`)
-      # and nested sequencers (`Seqs::Present`) alike. Use `step` for local
-      # instance methods like `def deserialize_contract(ctx)`.
+      # Use this for any declared dependency — macros
+      # (`Macros::Model::Find`) and nested sequencers (`Seqs::Present`)
+      # alike. Use `step` for local instance methods like
+      # `def deserialize_contract(ctx)`.
       def invoke(name, *args, **kwargs)
         return self if @failed_result
 
-        return_value = invoke_dependency(name, args, kwargs)
-
-        if return_value.is_a?(Result) && return_value.failure?
-          @failed_result = tag_failure(return_value, name)
-        else
-          @trail << name
-        end
-
+        record(name, invoke_dependency(name, args, kwargs))
         self
       end
 
-      def transaction(&block)
+      def transaction
         return self if @failed_result
 
         if defined?(::ActiveRecord::Base)
@@ -103,27 +64,16 @@ module Hubbado
 
       private
 
-      def invoke_step(name, block)
-        if block
-          block.call(@ctx)
-        elsif @dispatcher
-          unless @dispatcher.respond_to?(name, true)
-            raise NoMethodError,
-              "Pipeline step :#{name} expects #{@dispatcher.class.name} to define ##{name}, but it does not"
-          end
-          @dispatcher.send(name, @ctx)
-        else
-          raise ArgumentError,
-            "Pipeline step :#{name} needs either a block or a dispatcher (use the sequencer's `pipeline(ctx)` helper to enable auto-dispatch)"
+      def invoke_step(name)
+        unless @dispatcher.respond_to?(name, true)
+          raise NoMethodError,
+            "Pipeline step :#{name} expects #{@dispatcher.class.name} to define ##{name}, but it does not"
         end
+
+        @dispatcher.send(name, @ctx)
       end
 
       def invoke_dependency(name, args, kwargs)
-        unless @dispatcher
-          raise ArgumentError,
-            "Pipeline#invoke :#{name} requires a dispatcher (use the sequencer's `pipeline(ctx)` helper)"
-        end
-
         unless @dispatcher.respond_to?(name, true)
           raise NoMethodError,
             "Pipeline#invoke :#{name} expects #{@dispatcher.class.name} to declare a `dependency :#{name}, ...`"
@@ -132,6 +82,14 @@ module Hubbado
         @dispatcher.send(name).(@ctx, *args, **kwargs)
       end
 
+      def record(name, return_value)
+        if return_value.is_a?(Result) && return_value.failure?
+          @failed_result = tag_failure(return_value, name)
+        else
+          @trail << name
+        end
+      end
+
       def tag_failure(result, step_name)
         tagged_error = result.error.merge(step: step_name)
         Result.fail(result.ctx, error: tagged_error, trail: @trail.dup, i18n_scope: result.i18n_scope)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-sequence
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hubbado Devs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: evt-casing