ask-graph 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67250ca086cc687aff14bda7a2365e1f170eea92c8cd4f88565ec8b678ee8d9c
-  data.tar.gz: 3450ffce0b35cadd19798757116e2bbc6a82a9460f4686187131061f63ba8663
+  metadata.gz: 99d66a3b6b63d97a13187b67bbefd25c291d5ab80a63146e61639a0b7949689d
+  data.tar.gz: ab66b1d0586ee8570e71f2612938d6d87a9e3c5a3d44b93b046ef95343a5951a
 SHA512:
-  metadata.gz: cbef57c596215023c161198fc5951316777ba9686428fce403ce62e498b24e22edc1d40d9a1eec56ad010c397419ad1069219e16bad22b1768ff516e03df7cff
-  data.tar.gz: 830f3ea4c53e3db5ef8e26ba1bb22f105bf05e2419dba92bc6a113d1b2ae7fe6f40d3c866fc8cf4429d7f5649717ad9c9f6a1d389e7d0cda49f4a49444b7b8b3
+  metadata.gz: 8cd5ca7104c5ea6f643e9f9333ec8a7578b53f0fcda6c0f8a5a4273ac9cbb856025024e192a9f89c4a30fc3c8072b6b2b46283ccdf3805db05faade627fef81c
+  data.tar.gz: f8f4e2494be0350b17b86f568c1de1428a1731b73f9599132f6fe408a70fed15649c803847cf01a36ba009b819f2bcfaf3f37df6d8db2a8dd36dface2c8ae01b

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [0.6.1] — 2026-07-27
+
+### Fixed
+
+- **Hooks leak between classes** — `inherited` now deep-copies lifecycle
+  hook arrays instead of sharing them. Previously, a child class's
+  `after_step :foo` would mutate the parent class's hook arrays, causing
+  hooks to fire multiple times in sibling classes.
+
+### Changed
+
+- **Docs updated** to use the `Module::Workflow` convention throughout.
+  Recommended layout:
+
+  ```
+  app/workflows/
+    notify_customer/
+      workflow.rb          # module NotifyCustomer; class Workflow < Ask::Graph
+      steps/
+        send_email.rb
+        log_notification.rb
+    order_fulfillment/
+      workflow.rb
+      steps/
+        validate_payment.rb
+        notify_customer.rb
+        ship_order.rb
+  ```
+
+  Sub-graph composition via `Workflow.call(context)` or `context.run(Workflow)`.
+
+### Tested
+
+- 85 tests, 111 assertions, 0 failures
+
 ## [0.6.0] — 2026-07-27
 
 ### Changed

data/README.md

@@ -6,28 +6,30 @@
 gem "ask-graph"
 ```
 
-## Quick Start
-
-```ruby
-require "ask-graph"
-
-# Define a workflow
-class ProcessOrder < Ask::Graph
-  step ValidateOrder
-  step ChargeCustomer,  if: :valid?
-  step SendConfirmation, if: :valid?
-  step NotifyAdmin,     unless: :valid?
-
-  private
-
-  def valid?
-    context.order.valid?
-  end
-end
-
-# Run it
-result = ProcessOrder.run(order: order)
-```
+	## Quick Start
+	
+	```ruby
+	require "ask-graph"
+	
+	# Define a workflow
+	module ProcessOrder
+	  class Workflow < Ask::Graph
+	    step ValidateOrder
+	    step ChargeCustomer,  if: :valid?
+	    step SendConfirmation, if: :valid?
+	    step NotifyAdmin,     unless: :valid?
+	
+	    private
+	
+	    def valid?
+	      context.order.valid?
+	    end
+	  end
+	end
+	
+	# Run it
+	result = ProcessOrder::Workflow.call(order: order)
+	```
 
 ## Steps
 
@@ -41,86 +43,96 @@ class ValidateOrder
 end
 ```
 
-### Sequential steps
-
-```ruby
-class HandleCall < Ask::Graph
-  step Transcribe
-  step Classify
-  step Respond
-end
-```
-
-### Conditional steps
-
-```ruby
-class HandleCall < Ask::Graph
-  step BookAppointment,  if: :booking?
-  step EmergencyAlert,   if: :emergency?
-  step HandleInquiry,    unless: :known_intent?
-
-  private
-
-  def booking?   = context.intent == "booking"
-  def emergency? = context.intent == "emergency"
-  def known_intent? = %w[booking emergency inquiry].include?(context.intent)
-end
-```
-
-### Parallel steps
-
-Use `steps` (plural) to run multiple steps simultaneously:
-
-```ruby
-class SyncData < Ask::Graph
-  step FetchRecords
-
-  # All three run in parallel
-  steps CrmUpdate, CalendarSync, SendNotification
-
-  step ConfirmResponse
-end
-```
-
-### Human-in-the-loop (approve)
-
-`approve` runs a step, then pauses the workflow and waits for external input:
-
-```ruby
-class ProcessBooking < Ask::Graph
-  step BookAppointment
-  approve ReviewBooking, if: :expensive?
-  step ConfirmBooking
-end
-```
-
-After `approve` pauses, resume with:
-
-```ruby
-graph = ProcessBooking.new
-result = graph.run              # runs, pauses after ReviewBooking
-result = graph.resume(input: "approved")  # resumes, runs ConfirmBooking
-```
-
-### Per-item loops
-
-Use `context.each` inside a step for iteration with automatic checkpointing:
-
-```ruby
-class SendVoiceReminders
-  def call(context)
-    context.each(context.appointments) do |appt|
-      PhoneService.call(appt.number, appt.message)
-    end
-  end
-end
-
-class DailyReminders < Ask::Graph
-  step FetchAppointments
-  step SendVoiceReminders  # loops with per-item checkpointing
-  step MarkComplete
-end
-```
+	### Sequential steps
+	
+	```ruby
+	module HandleCall
+	  class Workflow < Ask::Graph
+	    step Transcribe
+	    step Classify
+	    step Respond
+	  end
+	end
+	```
+	
+	### Conditional steps
+	
+	```ruby
+	module HandleCall
+	  class Workflow < Ask::Graph
+	    step BookAppointment,  if: :booking?
+	    step EmergencyAlert,   if: :emergency?
+	    step HandleInquiry,    unless: :known_intent?
+	
+	    private
+	
+	    def booking?   = context.intent == "booking"
+	    def emergency? = context.intent == "emergency"
+	    def known_intent? = %w[booking emergency inquiry].include?(context.intent)
+	  end
+	end
+	```
+
+	### Parallel steps
+	
+	Use `steps` (plural) to run multiple steps simultaneously:
+	
+	```ruby
+	module SyncData
+	  class Workflow < Ask::Graph
+	    step FetchRecords
+	
+	    # All three run in parallel
+	    steps CrmUpdate, CalendarSync, SendNotification
+	
+	    step ConfirmResponse
+	  end
+	end
+	```
+	
+	### Human-in-the-loop (approve)
+	
+	`approve` runs a step, then pauses the workflow and waits for external input:
+	
+	```ruby
+	module ProcessBooking
+	  class Workflow < Ask::Graph
+	    step BookAppointment
+	    approve ReviewBooking, if: :expensive?
+	    step ConfirmBooking
+	  end
+	end
+	```
+	
+	After `approve` pauses, resume with:
+	
+	```ruby
+	graph = ProcessBooking::Workflow.new
+	result = graph.run              # runs, pauses after ReviewBooking
+	result = graph.resume(input: "approved")  # resumes, runs ConfirmBooking
+	```
+
+	### Per-item loops
+	
+	Use `context.each` inside a step for iteration with automatic checkpointing:
+	
+	```ruby
+	class SendVoiceReminders
+	  def call(context)
+	    context.each(context.appointments) do |appt|
+	      PhoneService.call(appt.number, appt.message)
+	    end
+	  end
+	end
+	
+	module DailyReminders
+	  class Workflow < Ask::Graph
+	    step FetchAppointments
+	    step SendVoiceReminders  # loops with per-item checkpointing
+	    step MarkComplete
+	  end
+	end
+	```
 
 If the process crashes mid-loop, it resumes from the last completed item.
 
@@ -146,33 +158,48 @@ end
 
 ### Sub-workflows
 
-A step can delegate to another workflow:
+A step can delegate to another workflow by calling `Workflow.call(context)`.
+The context is automatically exported, passed to the sub-workflow, and
+results are merged back on completion:
 
 ```ruby
-class IntentHandler
-  def call(context)
-    case context.intent
-    when "booking"
-      BookingWorkflow.new.call(context)  # sub-workflow as a step
-    when "emergency"
-      EmergencyWorkflow.new.call(context)
+module OrderFulfillment
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomer::Workflow.call(context)
     end
   end
+
+  class Workflow < Ask::Graph
+    step ValidatePayment
+    step NotifyCustomer
+    step ShipOrder
+  end
+end
+```
+
+Or use `context.run` for the same thing:
+
+```ruby
+class NotifyCustomer
+  def call(context)
+    context.run(NotifyCustomer::Workflow)
+  end
 end
 ```
 
 ### Checkpointing
 
-Pass a checkpoint store to make workflows durable across crashes:
+Pass a `storage` backend to make workflows durable across crashes:
 
 ```ruby
 store = Ask::State::Memory.new  # or Redis, SQLite, etc.
 
 # Runs through all steps, saving after each
-result = MyWorkflow.run(input, checkpoint_store: store)
+result = OrderFulfillment::Workflow.call(input, storage: store)
 
 # If a crash occurs, resume from the last completed step
-result = MyWorkflow.run(input, checkpoint_store: store)
+result = OrderFulfillment::Workflow.call(input, storage: store)
 ```
 
 ### Error handling
@@ -180,12 +207,14 @@ result = MyWorkflow.run(input, checkpoint_store: store)
 Failed steps raise `Ask::Graph::StepFailed` with the step name:
 
 ```ruby
-class MyGraph < Ask::Graph
-  step RiskyOperation
+module MyWorkflow
+  class Workflow < Ask::Graph
+    step RiskyOperation
+  end
 end
 
 begin
-  MyGraph.run
+  MyWorkflow::Workflow.call
 rescue Ask::Graph::StepFailed => e
   puts e.message  # => "RiskyOperation failed: connection timeout"
 end

data/lib/ask/graph/context.rb

@@ -131,9 +131,10 @@ module Ask
       # @param graph_class [Class < Ask::Graph] the graph to run
       # @return [Ask::Graph::Context] the sub-graph's context
       # @example
+      #   # Inside a step PORO
       #   class CalculateShipping
       #     def call(context)
-      #       context.run(ShippingWorkflow)
+      #       context.run(Shipping::Workflow)
       #     end
       #   end
       def run(graph_class)

data/lib/ask/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   class Graph
-    VERSION = "0.6.0"
+    VERSION = "0.6.1"
   end
 end

data/lib/ask/graph.rb

@@ -11,28 +11,32 @@ module Ask
   # lifecycle hooks.
   #
   # @example Basic workflow
-  #   class HandleCall < Ask::Graph
+  #   class HandleCall::Workflow < Ask::Graph
   #     step Transcribe
   #     step Classify, if: :needs_classification?
   #     step BookAppointment
   #   end
   #
   # @example Sub-graph composition
-  #   # Define a workflow
-  #   class NotifyCustomerWorkflow < Ask::Graph
-  #     step SendEmail
-  #     step LogNotification
+  #   # Define a reusable workflow
+  #   module NotifyCustomer
+  #     class Workflow < Ask::Graph
+  #       step SendEmail
+  #       step LogNotification
+  #     end
   #   end
   #
   #   # Wrap it in a PORO step
-  #   class NotifyCustomer
-  #     def call(context)
-  #       NotifyCustomerWorkflow.call(context)
+  #   module OrderFulfillment
+  #     class NotifyCustomer
+  #       def call(context)
+  #         NotifyCustomer::Workflow.call(context)
+  #       end
   #     end
   #   end
   #
   #   # Compose — every step is a PORO
-  #   class HandleOrder < Ask::Graph
+  #   class OrderFulfillment::Workflow < Ask::Graph
   #     step ValidatePayment
   #     step NotifyCustomer
   #     step ShipOrder
@@ -65,7 +69,8 @@ module Ask
       def inherited(subclass)
         super
         subclass.instance_variable_set(:@declarations, declarations.dup)
-        subclass.instance_variable_set(:@lifecycle_hooks, lifecycle_hooks.dup)
+        subclass.instance_variable_set(:@lifecycle_hooks,
+          lifecycle_hooks.transform_values(&:dup))
       end
 
       # --- Timeout ---
@@ -203,12 +208,12 @@ module Ask
       # are merged back into the original context automatically.
       #
       # @example Standalone — pass data
-      #   MyGraph.call({ user: "alice" })
+      #   OrderFulfillment::Workflow.call({ user: "alice" })
       #
       # @example Inside a step — pass the outer context
-      #   class MyStep
+      #   class ValidatePayment
       #     def call(context)
-      #       OtherGraph.call(context)
+      #       PaymentGateway::Workflow.call(context)
       #     end
       #   end
       def call(input = nil, storage: nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-graph
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto