shikibu 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b3b677128439973fcda2120c7377d1de6cc358bd4cd0b3fd9857e089d85de62
-  data.tar.gz: 6826b04fff743009f655282d55451c9850066116343c2da1211e7178d451ed6b
+  metadata.gz: 3bf06e3a63cc523afe19105e1ed5debd74a949dc3faec06a35ee9d3853d9d4ae
+  data.tar.gz: 9877fbfe7dec08f504d067999bd6e83ffd483c050192e7057f29b6d50e2317c1
 SHA512:
-  metadata.gz: 3d7c8eb5b7c2722cbb6569659c61fc02540ba5ef9d9d9da55281e9b482e0ff0a567b4434f309010d3faa35aed0ebd6592a97b77826410db3476a34dd80ea4d8b
-  data.tar.gz: 842f548cc2394a5a4a0aeb1641812c6e26f9e24d3f9f73bfeba6d262e3598429e102b560069897a75a6ea0ea9319c4fa27b67689c00714e5d6be3a5ccf6156e2
+  metadata.gz: a9adb5bfbda37f44168434adccde9e22cc65a1c101f1cf2bf2350a003ebd848f2778493b40ade87a4c7e17efa293f949c2c2ac18ce9645bd53fa9c3a42e12a56
+  data.tar.gz: 16102137dc003ab1d8b787edd5d78770e84228529f55318d3d0a0b3a7a7cf1e7050acc3826431f48cc96483b30e300df34877b8cbb6891a869b367f4f2a2d88f

data/README.md

@@ -198,6 +198,45 @@ end
 
 **Activity IDs**: Activities are automatically identified with IDs like `"create_user:1"` for deterministic replay.
 
+### Typed Workflows (dry-struct)
+
+Shikibu supports typed input/output with [dry-struct](https://dry-rb.org/gems/dry-struct/) for validation and type coercion:
+
+```ruby
+require 'dry-struct'
+
+module Types
+  include Dry.Types()
+end
+
+class OrderInput < Dry::Struct
+  attribute :order_id, Types::String
+  attribute :amount, Types::Coercible::Decimal
+end
+
+class OrderResult < Dry::Struct
+  attribute :order_id, Types::String
+  attribute :status, Types::String
+end
+
+class TypedOrderSaga < Shikibu::Workflow
+  workflow_name 'typed_order'
+  input OrderInput
+  output OrderResult
+
+  def execute(order)
+    # order is an OrderInput instance with validated/coerced types
+    OrderResult.new(order_id: order.order_id, status: 'completed')
+  end
+end
+
+# Run with automatic type coercion
+instance_id = app.start_workflow(TypedOrderSaga, order_id: 'ORD-123', amount: '99.99')
+result = app.get_typed_result(instance_id, TypedOrderSaga)  # Returns OrderResult
+```
+
+**Note**: `dry-struct` is an optional dependency. Add it to your Gemfile if you want typed workflows.
+
 ### Durable Execution
 
 Shikibu ensures workflow progress is never lost through **deterministic replay**:

data/lib/shikibu/app.rb

@@ -162,6 +162,18 @@ module Shikibu
       }
     end
 
+    # Get workflow result with typed output deserialization
+    # @param instance_id [String] Instance ID
+    # @param workflow_class [Class] Workflow class with output type definition
+    # @return [Object, nil] Typed output or nil if no output
+    # @raise [WorkflowNotFoundError] If instance not found
+    def get_typed_result(instance_id, workflow_class)
+      result = get_result(instance_id)
+      return nil unless result[:output]
+
+      workflow_class.deserialize_output(result[:output])
+    end
+
     # Get workflow status
     # @param instance_id [String] Instance ID
     # @return [String] Status

data/lib/shikibu/replay.rb

@@ -14,9 +14,12 @@ module Shikibu
     # Start a new workflow instance
     # @param workflow_class [Class] Workflow class
     # @param instance_id [String] Instance ID
-    # @param input [Hash] Input parameters
+    # @param input [Hash, Object] Input parameters (Hash for untyped, typed object for typed workflows)
     # @return [Object, nil] Workflow result or nil if suspended
     def start_workflow(workflow_class, instance_id:, **input)
+      # Serialize input for storage (handles typed inputs)
+      serialized_input = workflow_class.serialize_input(input)
+
       # Save workflow definition
       storage.save_workflow_definition(
         workflow_name: workflow_class.workflow_name,
@@ -30,12 +33,12 @@ module Shikibu
         workflow_name: workflow_class.workflow_name,
         source_hash: workflow_class.source_hash,
         owner_service: 'default',
-        input_data: input,
+        input_data: serialized_input,
         status: Status::RUNNING
       )
 
       # Execute the workflow
-      execute_workflow(instance_id, workflow_class, input, replaying: false)
+      execute_workflow(instance_id, workflow_class, serialized_input, replaying: false)
     end
 
     # Resume a workflow from its current state
@@ -197,12 +200,22 @@ module Shikibu
         workflow.instance_variable_set(:@pending_compensations, [])
         workflow.context = ctx
 
-        # Symbolize input keys
-        symbolized_input = symbolize_keys(input)
-        result = workflow.execute(**symbolized_input)
+        # Handle typed vs untyped input
+        result = if workflow_class.typed_input?
+                   # Typed workflow: deserialize and pass single object
+                   typed_input = workflow_class.deserialize_input(input)
+                   workflow.execute(typed_input)
+                 else
+                   # Legacy: symbolize and spread as keyword args
+                   symbolized_input = symbolize_keys(input)
+                   workflow.execute(**symbolized_input)
+                 end
+
+        # Serialize output
+        serialized_output = workflow_class.serialize_output(result)
 
         # Mark completed
-        storage.update_instance_status(instance_id, Status::COMPLETED, output_data: result)
+        storage.update_instance_status(instance_id, Status::COMPLETED, output_data: serialized_output)
         storage.clear_compensations(instance_id)
 
         # Cleanup direct subscriptions

data/lib/shikibu/typed_payload.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Shikibu
+  # Module to detect and handle typed payload classes
+  # Supports dry-struct, Ruby 3.2+ Data classes, and duck-typed objects
+  #
+  # @example with dry-struct
+  #   require 'dry-struct'
+  #   class OrderInput < Dry::Struct
+  #     attribute :order_id, Types::String
+  #     attribute :amount, Types::Coercible::Decimal
+  #   end
+  #
+  #   TypedPayload.typed_class?(OrderInput)  # => true
+  #   TypedPayload.to_h(OrderInput.new(order_id: '123', amount: 99.99))
+  #   # => { order_id: '123', amount: 99.99 }
+  #
+  # @example with Data class
+  #   OrderInput = Data.define(:order_id, :amount)
+  #   TypedPayload.typed_class?(OrderInput)  # => true
+  #
+  module TypedPayload
+    class << self
+      # Check if dry-struct is available
+      # @return [Boolean]
+      def dry_struct_available?
+        return @dry_struct_available if defined?(@dry_struct_available)
+
+        @dry_struct_available = begin
+          require 'dry-struct'
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # Check if an object is a typed payload class (not instance)
+      # @param obj [Object] Object to check
+      # @return [Boolean]
+      def typed_class?(obj)
+        return false unless obj.is_a?(Class)
+
+        # Check for dry-struct
+        return true if dry_struct_class?(obj)
+
+        # Check for Ruby 3.2+ Data class
+        return true if data_class?(obj)
+
+        # Check for duck-typed class with required methods
+        duck_typed_class?(obj)
+      end
+
+      # Check if an object is a typed payload instance
+      # @param obj [Object] Object to check
+      # @return [Boolean]
+      def typed_instance?(obj)
+        return true if dry_struct_instance?(obj)
+        return true if data_instance?(obj)
+
+        duck_typed_instance?(obj)
+      end
+
+      # Serialize a typed instance to a hash
+      # @param obj [Object] Typed instance or any object
+      # @return [Hash, Object] Serialized hash or original object
+      def to_h(obj)
+        deep_serialize(obj)
+      end
+
+      # Deserialize a hash to a typed instance
+      # @param hash [Hash] Hash to deserialize
+      # @param type_class [Class] Target type class
+      # @return [Object] Typed instance or original hash
+      def from_h(hash, type_class)
+        return hash unless typed_class?(type_class)
+        return hash unless hash.is_a?(Hash)
+
+        # Symbolize keys for compatibility
+        symbolized = deep_symbolize_keys(hash)
+
+        # All typed classes support .new(**hash) interface
+        type_class.new(**symbolized)
+      end
+
+      # Deserialize an array of typed objects
+      # @param array [Array<Hash>] Array of hashes
+      # @param element_type [Class] Element type class
+      # @return [Array] Array of typed instances
+      def from_array(array, element_type)
+        return array unless array.is_a?(Array)
+        return array unless typed_class?(element_type)
+
+        array.map do |item|
+          item.is_a?(Hash) ? from_h(item, element_type) : item
+        end
+      end
+
+      private
+
+      def dry_struct_class?(obj)
+        return false unless dry_struct_available?
+
+        obj.is_a?(Class) && obj < Dry::Struct
+      end
+
+      def dry_struct_instance?(obj)
+        return false unless dry_struct_available?
+
+        obj.is_a?(Dry::Struct)
+      end
+
+      def data_class?(obj)
+        return false unless defined?(Data)
+
+        obj.is_a?(Class) && obj < Data
+      end
+
+      def data_instance?(obj)
+        return false unless defined?(Data)
+
+        obj.is_a?(Data)
+      end
+
+      def duck_typed_class?(obj)
+        # A class is considered typed if it has new and instances have to_h
+        # but exclude Hash itself
+        return false if obj == Hash
+
+        obj.respond_to?(:new) &&
+          obj.method_defined?(:to_h)
+      end
+
+      def duck_typed_instance?(obj)
+        # An instance is typed if it has to_h but is not a Hash/Array
+        return false if obj.is_a?(Hash)
+        return false if obj.is_a?(Array)
+        return false unless obj.respond_to?(:to_h)
+
+        # Additional check: should have proper to_h implementation
+        # (not just Object#to_h which doesn't exist or returns weird things)
+        begin
+          result = obj.to_h
+          result.is_a?(Hash)
+        rescue StandardError
+          false
+        end
+      end
+
+      # Recursively serialize typed objects to hashes
+      # Note: Symbols are preserved here. They are converted to strings
+      # only during JSON serialization in the storage layer.
+      def deep_serialize(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_serialize(v) }
+        when Array
+          obj.map { |v| deep_serialize(v) }
+        when ->(o) { dry_struct_instance?(o) || data_instance?(o) }
+          deep_serialize(obj.to_h)
+        when Time, DateTime
+          obj.iso8601
+        when Date
+          obj.to_s
+        when BigDecimal
+          obj.to_s('F')
+        else
+          # Symbols, Integers, Strings, etc. are preserved as-is
+          obj
+        end
+      end
+
+      # Recursively symbolize hash keys
+      def deep_symbolize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        symbolized = hash.transform_keys do |key|
+          key.is_a?(String) ? key.to_sym : key
+        end
+        symbolized.transform_values do |value|
+          case value
+          when Hash then deep_symbolize_keys(value)
+          when Array then value.map { |v| v.is_a?(Hash) ? deep_symbolize_keys(v) : v }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shikibu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Shikibu
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/shikibu/workflow.rb

@@ -59,6 +59,85 @@ module Shikibu
         end
       end
 
+      # Set the input type for this workflow
+      # @param type_class [Class, nil] A Dry::Struct, Data, or duck-typed class
+      # @example
+      #   class OrderSaga < Shikibu::Workflow
+      #     input OrderInput
+      #     output OrderResult
+      #   end
+      def input(type_class = nil)
+        if type_class
+          unless TypedPayload.typed_class?(type_class)
+            raise ArgumentError, "#{type_class} must be a Dry::Struct, Data, or respond to .new and #to_h"
+          end
+
+          @input_type = type_class
+        else
+          @input_type
+        end
+      end
+
+      # Set the output type for this workflow (optional)
+      # @param type_class [Class, nil] A Dry::Struct, Data, or duck-typed class
+      def output(type_class = nil)
+        if type_class
+          unless TypedPayload.typed_class?(type_class)
+            raise ArgumentError, "#{type_class} must be a Dry::Struct, Data, or respond to .new and #to_h"
+          end
+
+          @output_type = type_class
+        else
+          @output_type
+        end
+      end
+
+      # Check if this workflow has typed input
+      # @return [Boolean]
+      def typed_input?
+        !@input_type.nil?
+      end
+
+      # Check if this workflow has typed output
+      # @return [Boolean]
+      def typed_output?
+        !@output_type.nil?
+      end
+
+      # Serialize input for storage
+      # @param input_value [Object] Input to serialize
+      # @return [Hash] Serialized hash
+      def serialize_input(input_value)
+        TypedPayload.to_h(input_value)
+      end
+
+      # Deserialize input from storage
+      # @param data [Hash] Stored data
+      # @return [Object] Typed input or hash
+      def deserialize_input(data)
+        return data unless typed_input?
+        return data unless data.is_a?(Hash)
+
+        TypedPayload.from_h(data, @input_type)
+      end
+
+      # Serialize output for storage
+      # @param output_value [Object] Output to serialize
+      # @return [Hash, Object] Serialized output
+      def serialize_output(output_value)
+        TypedPayload.to_h(output_value)
+      end
+
+      # Deserialize output from storage
+      # @param data [Object] Stored data
+      # @return [Object] Typed output or original data
+      def deserialize_output(data)
+        return data unless typed_output?
+        return data unless data.is_a?(Hash)
+
+        TypedPayload.from_h(data, @output_type)
+      end
+
       # Get the source hash for this workflow
       def source_hash
         @source_hash ||= begin
@@ -130,9 +209,15 @@ module Shikibu
     # Execute an activity with automatic retry and history tracking
     # @param name [Symbol, String] Activity name
     # @param retry_policy [RetryPolicy] Retry policy
+    # @param returns [Class, nil] Return type class for type restoration during replay
     # @param block [Proc] Activity logic
     # @return [Object] Activity result
-    def activity(name, retry_policy: nil, &)
+    # @raise [ArgumentError] If returns is not a valid typed class
+    def activity(name, retry_policy: nil, returns: nil, &)
+      if returns && !TypedPayload.typed_class?(returns)
+        raise ArgumentError, "returns: must be a typed class (Dry::Struct, Data, or duck-typed), got #{returns.inspect}"
+      end
+
       activity_id = ctx.generate_activity_id(name.to_s)
       ctx.current_activity_id = activity_id
 
@@ -141,7 +226,17 @@ module Shikibu
         cached = ctx.get_cached_result(activity_id)
         handle_cached_result(activity_id, cached)
         ctx.record_last_activity_id(activity_id)
-        return cached[:result] if cached[:event_type] == EventType::ACTIVITY_COMPLETED
+
+        if cached[:event_type] == EventType::ACTIVITY_COMPLETED
+          result = cached[:result]
+
+          # Restore type if specified
+          if returns && TypedPayload.typed_class?(returns) && result.is_a?(Hash)
+            result = TypedPayload.from_h(result, returns)
+          end
+
+          return result
+        end
 
         # Re-raise cached error
         raise reconstruct_error(cached)

data/lib/shikibu.rb

@@ -132,6 +132,7 @@ require_relative 'shikibu/notify/wake_event'
 require_relative 'shikibu/locking'
 require_relative 'shikibu/channels'
 require_relative 'shikibu/context'
+require_relative 'shikibu/typed_payload'
 require_relative 'shikibu/workflow'
 require_relative 'shikibu/activity'
 require_relative 'shikibu/storage/migrations'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shikibu
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yasushi Itoh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-21 00:00:00.000000000 Z
+date: 2025-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: mysql2
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +206,7 @@ files:
 - lib/shikibu/retry_policy.rb
 - lib/shikibu/storage/migrations.rb
 - lib/shikibu/storage/sequel_storage.rb
+- lib/shikibu/typed_payload.rb
 - lib/shikibu/version.rb
 - lib/shikibu/worker.rb
 - lib/shikibu/workflow.rb