ask-graph 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3062914e848e9fea15dd9b02bd001946b7a3fd0ab015a1805b4e21a371b68bf
-  data.tar.gz: 17866f6bfaf40d6e195c71655ac134430747e3690ce32c355036a8e30a62bbf1
+  metadata.gz: 67250ca086cc687aff14bda7a2365e1f170eea92c8cd4f88565ec8b678ee8d9c
+  data.tar.gz: 3450ffce0b35cadd19798757116e2bbc6a82a9460f4686187131061f63ba8663
 SHA512:
-  metadata.gz: ac9dad679a58246c1bd04d67de6812e9126f8f341edad4a72e842b80b759bcf2e020a2ad0c5bedd625eff861f22f0cbb224d4d2dc058a136d4c13087c4420248
-  data.tar.gz: b0f7285fd1e447c3f48e06d061aa441f64bb37de1952022e22e44835c3b549c639bceec13d9a690d0d14becb5eb724e1d2f31c05ea47a514ba2be57d9680de3b
+  metadata.gz: cbef57c596215023c161198fc5951316777ba9686428fce403ce62e498b24e22edc1d40d9a1eec56ad010c397419ad1069219e16bad22b1768ff516e03df7cff
+  data.tar.gz: 830f3ea4c53e3db5ef8e26ba1bb22f105bf05e2419dba92bc6a113d1b2ae7fe6f40d3c866fc8cf4429d7f5649717ad9c9f6a1d389e7d0cda49f4a49444b7b8b3

data/CHANGELOG.md

@@ -1,3 +1,126 @@
+## [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 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
+  # 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
+    step ShipOrder
+  end
+  ```
+
+  - `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
+
+- **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.
+
+- **`Context#run(graph_class)`** — convenience method wrapping the
+  export → create → call → import pattern.
+
+  ```ruby
+  def call(context)
+    context.run(NotifyCustomerWorkflow)
+  end
+  ```
+
+### Changed
+
+- **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
+
+- 85 tests, 111 assertions, 0 failures
+
 ## [0.4.0] — 2026-07-27
 
 ### Changed

data/lib/ask/graph/context.rb

@@ -31,7 +31,12 @@ module Ask
         @item = nil
         @mutex = Mutex.new
         @resume_input = nil
-        @store[:input] = input if input
+        if input.is_a?(Hash)
+          @store[:input] = input
+          @store.merge!(input)
+        elsif input
+          @store[:input] = input
+        end
       end
 
       # @return [Object, nil] input provided on resume for approval steps
@@ -102,6 +107,42 @@ module Ask
         end
       end
 
+      # @return [Hash] raw store data with original object references.
+      # Unlike {to_h}, this returns the actual Ruby objects without
+      # serialization. Useful for passing state to sub-graphs.
+      def export_data
+        @mutex.synchronize { @store.dup }
+      end
+
+      # Merge data from another context (or hash) into this one.
+      # Existing keys in this context are overwritten.
+      #
+      # @param other [Context, Hash] source of data to merge in
+      def import(other)
+        data = other.is_a?(Context) ? other.export_data : other
+        @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/version.rb

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

data/lib/ask/graph.rb

@@ -6,8 +6,9 @@ require_relative "graph/runner"
 
 module Ask
   # Define durable workflow graphs with named steps, conditional routing,
-  # parallel execution, human-in-the-loop approval, per-item checkpointing
-  # loops, step timeouts, retry policies, and lifecycle hooks.
+  # parallel execution, sub-graph composition, human-in-the-loop approval,
+  # per-item checkpointing loops, step timeouts, retry policies, and
+  # lifecycle hooks.
   #
   # @example Basic workflow
   #   class HandleCall < Ask::Graph
@@ -16,6 +17,27 @@ module Ask
   #     step BookAppointment
   #   end
   #
+  # @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
+  #     step ShipOrder
+  #   end
+  #
   # @example With timeout and retry
   #   class ApiWorkflow < Ask::Graph
   #     step FetchData, timeout: 30, retry: 3
@@ -174,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
 
@@ -211,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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto