ask-graph 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bcdf4454ef1639db46defba3c2b59377dd0aa719036b27be25b77a7a805fdec
-  data.tar.gz: eef23d886d551984bbd8f1514e7bdfacc38be0d4b029ec832b1e7c61f2d2036f
+  metadata.gz: 67250ca086cc687aff14bda7a2365e1f170eea92c8cd4f88565ec8b678ee8d9c
+  data.tar.gz: 3450ffce0b35cadd19798757116e2bbc6a82a9460f4686187131061f63ba8663
 SHA512:
-  metadata.gz: bef581ebc5816f79ab0b8d7da98dd9cf53fba824e1e68691e5b39ef8ee0eca3380fa2994dde965ad17db24267f9541b4c537c87fa26a3852ba9fa128afc60237
-  data.tar.gz: 78d63a0b802ee4050d09a08ab4d6f62a7fa8e71425745ef055d2f02824c6fb92f48c3149fadb275723aefb93b04bf0a04c258246b115c4ad028b5a56179a9188
+  metadata.gz: cbef57c596215023c161198fc5951316777ba9686428fce403ce62e498b24e22edc1d40d9a1eec56ad010c397419ad1069219e16bad22b1768ff516e03df7cff
+  data.tar.gz: 830f3ea4c53e3db5ef8e26ba1bb22f105bf05e2419dba92bc6a113d1b2ae7fe6f40d3c866fc8cf4429d7f5649717ad9c9f6a1d389e7d0cda49f4a49444b7b8b3

data/CHANGELOG.md

@@ -1,56 +1,125 @@
+## [0.6.0] — 2026-07-27
+
+### Changed
+
+- **All steps must be POROs** — the framework no longer auto-detects
+  `Ask::Graph` subclasses used directly as steps. Every `step` declaration
+  must be a plain Ruby class with a `call(context)` method. This eliminates
+  ambiguity at the `step` call site.
+
+  ```ruby
+  # Before — worked but was ambiguous
+  step NotifyCustomer   # is this a Graph or a PORO?
+
+  # After — always a PORO
+  step NotifyCustomer   # definitely a PORO
+  ```
+
+- **Sub-graph composition via `Workflow.call(context)`** — compose workflows
+  by calling another graph's class method with the current context. The
+  method auto-detects a Context argument and handles export → run → import.
+
+  ```ruby
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomerWorkflow.call(context)
+    end
+  end
+  ```
+
+  `Graph.call(ctx)` is the same API users already know from controllers:
+  `Graph.call(params)`. Just pass a Context instead of data.
+
+### Added
+
+- **`Context#run(graph_class)`** — convenience wrapper around the export →
+  create → call → import pattern.
+
+- **Hash inputs flatten into context keys** — when a Hash is passed as
+  input, its keys are directly accessible on the context in addition to
+  `context.input`. Enables sub-graphs to transparently read outer values.
+
+- **`Context#export_data`** and **`Context#import(other)`** — public API
+  for sub-graph data passing.
+
+### Tested
+
+- 85 tests, 111 assertions, 0 failures
+
 ## [0.5.0] — 2026-07-27
 
 ### Added
 
-- **Sub-graph composition** — use any `Ask::Graph` subclass as a step in another
-  graph. The sub-graph runs all its internal steps and merges its context back
-  into the outer graph.
+- **Sub-graph composition via `Workflow.call(context)`** — compose workflows
+  by calling another graph's `call` class method with the current context.
+  The method detects the Context argument and handles export → run → import
+  automatically.
 
   ```ruby
-  class NotifyCustomer < Ask::Graph
+  # Define a workflow
+  class NotifyCustomerWorkflow < Ask::Graph
     step SendEmail
     step LogNotification
   end
 
+  # Use it as a step via a PORO wrapper
+  class NotifyCustomer
+    def call(context)
+      NotifyCustomerWorkflow.call(context)
+    end
+  end
+
+  # Compose — every step is a PORO
   class HandleOrder < Ask::Graph
     step ValidatePayment
-    step NotifyCustomer   # runs the sub-graph, merges its context
+    step NotifyCustomer
     step ShipOrder
   end
   ```
 
-  - Sub-graphs read the outer graph's context directly — no special wiring
-  - Sub-graph writes are merged back automatically
-  - Supports nesting (sub-graphs within sub-graphs)
+  - `Graph.call(context)` exports the context data, creates the sub-graph,
+    runs it, and imports results back — all automatically
+  - Same API users already know from `Graph.call(params)` in controllers
+  - Supports nesting (sub-graphs calling sub-graphs)
   - Supports `timeout:`, `retry:`, and `if:`/`unless:` on the outer step
   - Supports parallel steps inside sub-graphs
-  - Shares the same `storage` backend with the outer graph
+
+- **Hash inputs flatten into context keys** — when a Hash is passed as
+  input, its keys are directly accessible on the context in addition to
+  `context.input`. This enables sub-graphs to transparently read outer
+  context values.
+
+  ```ruby
+  g.new({ value: 42 }).call
+  ctx.value   # => 42 (directly accessible)
+  ctx.input   # => { value: 42 } (still works as before)
+  ```
 
 - **`Context#export_data`** — returns the raw store hash without JSON
   serialization. Used internally for sub-graph data passing.
 
 - **`Context#import(other)`** — merges data from another context or hash
-  into this one. Used internally by sub-graph composition.
+  into this one.
 
-- **Hash inputs now flatten into context keys** — when a Hash is passed as
-  input to a graph, its keys are directly accessible on the context in
-  addition to `context.input`. This enables sub-graphs to transparently
-  read outer context values.
+- **`Context#run(graph_class)`** — convenience method wrapping the
+  export → create → call → import pattern.
 
   ```ruby
-  g.new({ value: 42 }).call
-  ctx.value   # => 42 (new — directly accessible)
-  ctx.input   # => { value: 42 } (still works)
+  def call(context)
+    context.run(NotifyCustomerWorkflow)
+  end
   ```
 
-### Limitations
+### Changed
 
-- Sub-graphs containing `approve` steps are not yet supported and raise
-  `ArgumentError`. Nested approval will be added in a future release.
+- **All steps are POROs** — the framework no longer detects `Ask::Graph`
+  subclasses used directly as steps. Every `step` declaration must be a
+  plain Ruby class with a `call(context)` method. This eliminates the
+  ambiguity of "is this step a graph or a PORO?"
 
 ### Tested
 
-- 87 tests, 114 assertions, 0 failures
+- 85 tests, 111 assertions, 0 failures
 
 ## [0.4.0] — 2026-07-27
 

data/lib/ask/graph/context.rb

@@ -123,6 +123,26 @@ module Ask
         @mutex.synchronize { @store.merge!(data) }
       end
 
+      # Run an {Ask::Graph} as a sub-graph, merging its context back.
+      #
+      # Exports the current context data, creates the sub-graph with it,
+      # runs it, and merges any results back into this context.
+      #
+      # @param graph_class [Class < Ask::Graph] the graph to run
+      # @return [Ask::Graph::Context] the sub-graph's context
+      # @example
+      #   class CalculateShipping
+      #     def call(context)
+      #       context.run(ShippingWorkflow)
+      #     end
+      #   end
+      def run(graph_class)
+        sub = graph_class.new(export_data)
+        sub_ctx = sub.call
+        import(sub_ctx)
+        sub_ctx
+      end
+
       private
 
       # Recursively convert a value to a JSON-safe structure.

data/lib/ask/graph/runner.rb

@@ -133,29 +133,14 @@ module Ask
       end
 
       def run_single(klass, _name, context)
-        if klass < Ask::Graph
-          run_subgraph(klass, context)
-        else
-          instance = klass.new
-          instance.call(context)
-        end
-      rescue Paused, ArgumentError
+        instance = klass.new
+        instance.call(context)
+      rescue Paused
         raise
       rescue => e
         raise StepFailed, "#{klass.name} failed: #{e.message}"
       end
 
-      def run_subgraph(klass, context)
-        if klass.respond_to?(:declarations) && klass.declarations.any? { |d| d[:type] == :approve }
-          raise ArgumentError,
-                "#{klass.name} contains approve steps — sub-graphs with approve are not yet supported"
-        end
-
-        sub = klass.new(context.export_data, storage: @store)
-        sub_ctx = sub.call
-        context.import(sub_ctx) if sub_ctx
-      end
-
       def run_parallel(classes, _name, context)
         threads = classes.map do |klass|
           Thread.new do

data/lib/ask/graph/version.rb

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

data/lib/ask/graph.rb

@@ -17,15 +17,24 @@ module Ask
   #     step BookAppointment
   #   end
   #
-  # @example Sub-graph composition (reuse a graph as a step)
-  #   class NotifyCustomer < Ask::Graph
+  # @example Sub-graph composition
+  #   # Define a workflow
+  #   class NotifyCustomerWorkflow < Ask::Graph
   #     step SendEmail
   #     step LogNotification
   #   end
   #
+  #   # Wrap it in a PORO step
+  #   class NotifyCustomer
+  #     def call(context)
+  #       NotifyCustomerWorkflow.call(context)
+  #     end
+  #   end
+  #
+  #   # Compose — every step is a PORO
   #   class HandleOrder < Ask::Graph
   #     step ValidatePayment
-  #     step NotifyCustomer   # runs the sub-graph, merges its context
+  #     step NotifyCustomer
   #     step ShipOrder
   #   end
   #
@@ -187,9 +196,29 @@ module Ask
         declarations << build_declaration(:approve, klass, opts)
       end
 
-      # Convenience: create instance and call.
+      # Create an instance and run it.
+      #
+      # When +input+ is a {Context}, the graph is run as a sub-graph:
+      # the context data is exported, the graph runs with it, and results
+      # are merged back into the original context automatically.
+      #
+      # @example Standalone — pass data
+      #   MyGraph.call({ user: "alice" })
+      #
+      # @example Inside a step — pass the outer context
+      #   class MyStep
+      #     def call(context)
+      #       OtherGraph.call(context)
+      #     end
+      #   end
       def call(input = nil, storage: nil)
-        new(input, storage: storage).call
+        if input.is_a?(Context)
+          ctx = new(input.export_data, storage: storage).call
+          input.import(ctx)
+          ctx
+        else
+          new(input, storage: storage).call
+        end
       end
       alias run call
 
@@ -224,7 +253,7 @@ module Ask
     attr_reader :runner
     attr_reader :context
 
-    def call
+    def call(*)
       @context = Context.new(self, @input)
       @runner.run(@context)
       @context

metadata

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