job-workflow 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ff0a254ebd8fee848ab5eb26036e0bd98392700811e0bd55ffeaf4c348e04b6
+  data.tar.gz: ada2c0170fe7776a15802416f65070911e464f98abff416f9cbb15ed207bc7a8
+SHA512:
+  metadata.gz: d406e2e4ed2671b79aac352abe0405c009d0f4b089b4ecd2fb400b2a79c7676689cdbb9992e365063f17fb7160bb45084bc18966ff101097b39c6f6e5d3ecb60
+  data.tar.gz: 8d51653d18ed1769e513c2c3b854ac21663e1a9ed168dbac1713689912fa24b0c9cb9c66469a892e946e014905fc825934b555e4d657786efd5becd99fd9a866

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,91 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+  - rubocop-rbs_inline
+  - rubocop-thread_safety
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - examples/**/*
+    - tmp/**/*
+
+Layout/LeadingCommentSpace:
+  Enabled: true
+  AllowDoxygenCommentStyle: false
+  AllowGemfileRubyComment: false
+  AllowRBSInlineAnnotation: true
+
+Layout/LineLength:
+  Enabled: true
+  Max: 120
+  AllowHeredoc: true
+  AllowURI: true
+  AllowQualifiedName: true
+  AllowRBSInlineAnnotation: true
+  AllowCopDirectives: true
+  AllowedPatterns:
+    - "^ *#"
+
+Metrics/BlockLength:
+  Enabled: true
+  CountComments: false
+  Max: 25
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/ClassLength:
+  Enabled: true
+  CountComments: false
+  Max: 100
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/MethodLength:
+  Enabled: true
+  CountComments: false
+  Max: 10
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/ModuleLength:
+  Enabled: true
+  CountComments: false
+  Max: 100
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Naming/FileName:
+  Exclude:
+    - lib/job-workflow.rb
+
+RSpec/ExampleLength:
+  Enabled: true
+  Max: 5
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+ThreadSafety/ClassAndModuleAttributes:
+  Enabled: false
+

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [Unreleased]
+
+## [0.1.3] - 2026-01-06
+
+### Changed
+
+- Rename library from `job-flow` to `job-workflow`
+
+## [0.1.2] - 2026-01-05
+
+### Fixed
+
+- Fix `enqueue_task` to use correct ActiveJob API `ActiveJob.perform_all_later` instead of non-existent `job.class.perform_all_later`
+- Fix SolidQueue adapter to use correct lifecycle hook API `SolidQueue::Worker.on_stop` instead of deprecated `on_worker_stop`
+- Fix SolidQueue job arguments extraction to handle both Hash and Array formats for compatibility with SolidQueue's serialization format
+
+## [0.1.1] - 2026-01-04
+
+- Added `spec.license` field to gemspec for better gem metadata
+
+## [0.1.0] - 2026-01-04
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 shoma07
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,47 @@
+# JobWorkflow
+
+> ⚠️ **Early Stage (v0.1.3):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
+
+## Overview
+
+JobWorkflow is a declarative workflow orchestration engine for Ruby on Rails applications, built on top of ActiveJob. It provides a simple DSL for defining workflows.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem 'job-workflow'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Documentation
+
+For comprehensive documentation, including step-by-step getting started instructions and in-depth feature guides, see the **[guides/](guides/README.md)** directory.
+
+[Reference the guides →](guides/README.md)
+
+## Requirements
+
+- Rails >= 8.1.0
+- SolidQueue >= 1.24.0
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/shoma07/job-workflow.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new(:lint) do |t|
+  t.formatters = %w[simple]
+  t.options = ["--parallel"]
+end
+
+namespace :lint do
+  desc "Lint safe fix (Rubocop)"
+  task fix: :autocorrect
+
+  desc "Lint all fix (Rubocop)"
+  task fixall: :autocorrect_all
+end
+
+namespace :rbs do
+  desc "Install RBS Collection"
+  task :install do
+    require "rbs"
+    require "rbs/cli"
+    RBS::CLI.new(stdout: $stdout, stderr: $stderr).run("collection install --frozen".split)
+  end
+
+  desc "Update RBS Collection"
+  task :update do
+    require "rbs"
+    require "rbs/cli"
+    RBS::CLI.new(stdout: $stdout, stderr: $stderr).run("collection update".split)
+  end
+
+  desc "Generated RBS files from rbs-inline"
+  task :inline do
+    require "rbs/inline"
+    require "rbs/inline/cli"
+    FileUtils.rm_r(File.expand_path("sig/generated", __dir__), secure: true)
+    RBS::Inline::CLI.new.run(%w[lib --output --opt-out])
+  end
+end
+
+desc "Typecheck Run (Steep)"
+task typecheck: %i[rbs:inline] do
+  require "steep"
+  require "steep/cli"
+  steep_options = { stdout: $stdout, stderr: $stderr, stdin: $stdin }
+  Steep::CLI.new(argv: ["check", "-j2"], **steep_options).run.zero? || exit(1)
+end
+
+task default: %i[lint typecheck spec]

data/Steepfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# D = Steep::Diagnostic
+#
+target :lib do
+  signature "sig"
+  signature "sig-private"
+
+  check "lib"
+end

data/guides/API_REFERENCE.md

@@ -0,0 +1,112 @@
+# API Reference
+
+Detailed reference for all DSL methods and classes in JobWorkflow.
+
+## DSL Methods
+
+### task
+
+Define an individual task.
+
+```ruby
+task(name, **options, &block)
+```
+
+**Parameters**:
+- `name` (Symbol): Task name
+- `options` (Hash): Task options
+  - `depends_on` (Symbol | Array[Symbol]): Dependent tasks
+  - `each` (Proc): Proc that returns an enumerable for map task execution
+  - `enqueue` (Hash | Proc | bool): Controls whether task iterations are enqueued as sub-jobs
+    - Hash format (recommended): `{ condition: Proc, queue: String, concurrency: Integer }`
+      - `condition` (Proc | bool): Determines if task should be enqueued (default: true if Hash is not empty)
+      - `queue` (String): Custom queue name for the task (optional)
+      - `concurrency` (Integer): Concurrency limit for parallel processing (default: unlimited)
+    - Proc format (legacy): Proc that returns boolean
+    - bool format: true/false for simple cases
+    - Default: nil (synchronous execution)
+  - `retry` (Integer | Hash): Retry configuration. Integer for simple retry count, Hash for advanced settings
+    - `count` (Integer): Maximum retry attempts (default: 3 when Hash)
+    - `strategy` (Symbol): `:linear` or `:exponential` (default: `:exponential`)
+    - `base_delay` (Integer): Base delay in seconds (default: 1)
+    - `jitter` (bool): Add randomness to delays (default: false)
+  - `timeout` (Numeric | nil): Execution timeout in seconds for **one attempt** (default: nil)
+    - You can pass Integer or Float seconds
+    - Timeout does **not** include retry time across attempts
+    - `nil` disables timeout
+  - `condition` (Proc): Execute only if returns true (default: `->(_ctx) { true }`)
+  - `throttle` (Hash): Throttling settings
+  - `output` (Hash): Task output definition
+- `block` (Proc): Task implementation (always takes `|ctx|`)
+  - Without `each`: regular task execution
+  - With `each`: access current element via `ctx.each_value`
+
+**Example**:
+
+```ruby
+argument :enabled, "bool", default: false
+argument :data, "Hash"
+
+task :simple, output: { result: "String" } do |ctx|
+  { result: "simple" }
+end
+
+task :with_dependencies,
+     depends_on: [:simple],
+     retry: 3,
+     output: { final: "String" } do |ctx|
+  result = ctx.output[:simple].first.result
+  { final: process(result) }
+end
+
+task :conditional,
+     condition: ->(ctx) { ctx.arguments.enabled },
+     output: { conditional_result: "String" } do |ctx|
+  { conditional_result: "executed" }
+end
+
+task :throttled,
+     throttle: { key: "api", limit: 10, ttl: 60 },
+     output: { response: "Hash" } do |ctx|
+  data = ctx.arguments.data
+  { response: ExternalAPI.call(data) }
+end
+
+# Parallel processing with collection
+task :process_items,
+     each: ->(ctx) { ctx.arguments.items },
+     enqueue: { concurrency: 5 },
+     output: { result: "String" } do |ctx|
+  item = ctx.each_value
+  { result: ProcessService.handle(item) }
+end
+```
+
+**Map Task Output**: When `each:` is specified, outputs are automatically collected as an array.
+
+**Example**:
+
+```ruby
+argument :items, "Array[String]"
+
+task :process_items,
+     each: ->(ctx) { ctx.arguments.items },
+     enqueue: { concurrency: 5 },
+     output: { result: "String", status: "Symbol" } do |ctx|
+  item = ctx.each_value
+  {
+    result: ProcessService.handle(item),
+    status: :success
+  }
+end
+
+task :summarize, depends_on: [:process_items] do |ctx|
+  # Access outputs as an array
+  outputs = ctx.output[:process_items]
+  puts "Processed #{outputs.size} items"
+
+  outputs.each do |output|
+    puts "Result: #{output.result}, Status: #{output.status}"
+  end
+end
+```

data/guides/BEST_PRACTICES.md

@@ -0,0 +1,113 @@
+# Best Practices
+
+Best practices, design patterns, and recommendations for effective JobWorkflow usage.
+
+## Workflow Design
+
+### Task Granularity
+
+#### Appropriate Division
+
+```ruby
+# ✅ Recommended: Follow single responsibility principle
+class WellDesignedWorkflowJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  argument :data, "Hash"
+  
+  task :validate_input do |ctx|
+    # Only validation
+    data = ctx.arguments.data
+    raise "Invalid" unless data.valid?
+  end
+  
+  task :fetch_dependencies, depends_on: [:validate_input], output: { dependencies: "Hash" } do |ctx|
+    # Only fetch data
+    { dependencies: fetch_required_data }
+  end
+  
+  task :transform_data, depends_on: [:fetch_dependencies], output: { transformed: "Hash" } do |ctx|
+    # Only transform
+    data = ctx.arguments.data
+    dependencies = ctx.output[:fetch_dependencies].first.dependencies
+    { transformed: transform(data, dependencies) }
+  end
+  
+  task :save_result, depends_on: [:transform_data] do |ctx|
+    # Only save
+    transformed = ctx.output[:transform_data].first.transformed
+    save_to_database(transformed)
+  end
+end
+
+# ❌ Not recommended: Multiple responsibilities in one task
+class PoorlyDesignedWorkflowJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  argument :data, "Hash"
+  
+  task :do_everything do |ctx|
+    # All in one task (hard to test, not reusable)
+    data = ctx.arguments.data
+    raise "Invalid" unless data.valid?
+    deps = fetch_required_data
+    transformed = transform(data, deps)
+    save_to_database(transformed)
+  end
+end
+```
+
+### Explicit Dependencies
+
+```ruby
+argument :raw_data, "String"
+
+# ✅ Explicit dependencies
+task :prepare_data, output: { prepared: "Hash" } do |ctx|
+  raw_data = ctx.arguments.raw_data
+  { prepared: prepare(raw_data) }
+end
+
+task :process_data, depends_on: [:prepare_data], output: { result: "String" } do |ctx|
+  prepared = ctx.output[:prepare_data].first.prepared
+  { result: process(prepared) }
+end
+
+# ❌ Implicit dependencies (unpredictable execution order)
+task :task1, output: { shared: "String" } do |ctx|
+  { shared: "data" }
+end
+
+task :task2 do |ctx|
+  # No guarantee task1 executes first - this may fail!
+  shared = ctx.output[:task1].first&.shared
+  use(shared)
+end
+```
+
+## Future Considerations
+
+The following features are under consideration for future releases:
+
+### Saga Pattern
+
+Built-in support for the Saga pattern (distributed transaction compensation) is not currently planned. For workflows requiring compensation logic, we recommend:
+
+1. **Using Lifecycle Hooks**: Implement cleanup/rollback logic in `after` or `around` hooks
+2. **Application-layer management**: Handle compensation in your service layer where domain logic resides
+3. **Idempotent task design**: Design tasks to be safely retryable
+
+```ruby
+# Example: Using around hook for compensation
+around :charge_payment do |ctx, task|
+  begin
+    task.call
+  rescue PaymentError => e
+    # Compensation logic
+    rollback_previous_reservations(ctx)
+    raise
+  end
+end
+```
+
+If there is significant demand for native Saga support, it may be reconsidered in future versions.

data/guides/CACHE_STORE_INTEGRATION.md

@@ -0,0 +1,145 @@
+# Cache Store Integration Guide
+
+JobWorkflow is designed to use `ActiveSupport::Cache::Store` compatible backends. Currently, the cache store infrastructure is in place, but no features are actively using the cache yet. This guide documents the cache store abstraction layer and its planned usage patterns.
+
+**Status**: Cache store detection and initialization are implemented. Feature implementations that utilize the cache (Workflow status persistence, Output storage, etc.) are planned for future releases.
+
+## Overview
+
+`JobWorkflow::CacheStoreAdapters` provides automatic cache store detection and a unified access interface. This allows JobWorkflow to transparently use available cache backends like SolidCache or memory-based caches.
+
+## Automatic Detection
+
+`JobWorkflow::CacheStoreAdapters.current` automatically detects and instantiates an appropriate cache store with the following priority:
+
+1. **SolidCache**: If `ActiveSupport::Cache::SolidCacheStore` is defined, a new instance is created with JobWorkflow's namespace configuration
+2. **Memory Store**: If neither is available, `ActiveSupport::Cache::MemoryStore` is used as the default fallback
+
+All stores are automatically namespaced with `"job_workflow"` to prevent key collisions with application-level caches.
+
+### Example
+
+```ruby
+# Access the auto-detected cache store
+cache = JobWorkflow::CacheStoreAdapters.current
+
+# Write to cache
+cache.write("my_key", { data: "value" }, expires_in: 24.hours)
+
+# Read from cache
+data = cache.read("my_key")
+
+# Delete from cache
+cache.delete("my_key")
+```
+
+## Supported Cache Backends
+
+### SolidCache (Recommended for Rails 8+)
+
+SolidCache is a database-backed cache store recommended for Rails 8 applications. JobWorkflow automatically uses SolidCache if available.
+
+For detailed SolidCache setup instructions, see the [official SolidCache documentation](https://github.com/rails/solid_cache).
+
+### Memory Store (Default)
+
+In environments where SolidCache is not available (development, tests, or minimal deployments), JobWorkflow uses `ActiveSupport::Cache::MemoryStore`:
+
+```ruby
+ActiveSupport::Cache::MemoryStore.new
+```
+
+## Design Decision: No Direct Rails.cache Usage
+
+JobWorkflow does NOT use `Rails.cache` directly. Instead, it creates dedicated cache store instances. This design choice provides:
+
+- **Namespace Isolation**: JobWorkflow caches are namespaced with `"job_workflow"` prefix to prevent key collisions with application-level caches
+- **Explicit Configuration**: JobWorkflow's cache is independently configurable without affecting Rails application caching
+- **Predictable Behavior**: No cache invalidations triggered by Rails application code
+
+This ensures that JobWorkflow's internal caching behavior is isolated and predictable, even in complex Rails applications with sophisticated caching strategies.
+
+## Test Environment
+
+In test environments, JobWorkflow automatically uses `MemoryStore`. You can reset the cache between tests:
+
+```ruby
+# spec/spec_helper.rb is pre-configured with:
+config.after do
+  JobWorkflow::CacheStoreAdapters.reset!
+end
+```
+
+To manually clear cache in tests:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each) do
+    JobWorkflow::CacheStoreAdapters.current.clear if JobWorkflow::CacheStoreAdapters.current.respond_to?(:clear)
+  end
+end
+```
+
+## Cache Key Format
+
+JobWorkflow generates cache keys with the following format:
+
+```
+job_workflow:<feature>:<workflow_id>:<identifier>
+```
+
+Examples:
+- `job_workflow:task_output:wf-123:task-1`
+- `job_workflow:dependency_wait:wf-456:dep-xyz`
+- `job_workflow:semaphore:wf-789:sem-lock`
+
+## Performance Considerations
+
+### Latency by Backend
+
+| Backend | Read/Write Latency |
+|---------|-------------------|
+| MemoryStore | < 1ms |
+| SolidCache (Database) | 5-50ms |
+| Redis | 1-10ms |
+| Memcached | 1-5ms |
+## Troubleshooting
+
+### Verify Current Cache Backend
+
+```ruby
+# Check which cache store is being used
+puts JobWorkflow::CacheStoreAdapters.current.class
+# => ActiveSupport::Cache::SolidCacheStore or ActiveSupport::Cache::MemoryStore
+```
+
+### Clear Cache
+
+```ruby
+# Clear all JobWorkflow caches
+if JobWorkflow::CacheStoreAdapters.current.respond_to?(:clear)
+  JobWorkflow::CacheStoreAdapters.current.clear
+end
+```
+
+### Reset to Default Configuration
+
+```ruby
+# Reset to auto-detected cache store
+JobWorkflow::CacheStoreAdapters.reset!
+```
+
+## Best Practices
+
+1. **Production**: Use SolidCache for database-backed persistence
+2. **Development**: Default MemoryStore is sufficient
+3. **Testing**: MemoryStore is automatically used and cleared between tests
+4. **Large Workflows**: Monitor cache size and choose appropriate backend (SolidCache for unlimited, MemoryStore for bounded)
+
+## Out of Scope
+
+The following are not supported or are intentionally excluded:
+
+- Custom adapter implementations by users
+- Automatic cache key prefixing (beyond JobWorkflow's internal namespace)
+- AWS S3 or other external storage backends (planned for future LargeStorageAdapters)

data/guides/CONDITIONAL_EXECUTION.md

@@ -0,0 +1,66 @@
+# Conditional Execution
+
+JobWorkflow provides conditional execution features to selectively execute tasks based on runtime state.
+
+## Basic Conditional Execution
+
+### condition: Option
+
+Execute task only if condition returns true.
+
+```ruby
+class UserNotificationJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  argument :user, "User"
+  argument :notification_type, "String"
+  
+  task :load_user_preferences, output: { preferences: "Hash" } do |ctx|
+    user = ctx.arguments.user
+    { preferences: user.notification_preferences }
+  end
+  
+  # Execute only for premium users
+  task :send_premium_notification,
+       depends_on: [:load_user_preferences],
+       condition: ->(ctx) { ctx.arguments.user.premium? } do |ctx|
+    user = ctx.arguments.user
+    notification_type = ctx.arguments.notification_type
+    PremiumNotificationService.send(user, notification_type)
+  end
+  
+  # Send simple notification to standard users
+  task :send_standard_notification,
+       depends_on: [:load_user_preferences],
+       condition: ->(ctx) { !ctx.arguments.user.premium? } do |ctx|
+    user = ctx.arguments.user
+    notification_type = ctx.arguments.notification_type
+    StandardNotificationService.send(user, notification_type)
+  end
+end
+```
+
+## Complex Conditions
+
+You can use any Ruby expression in the condition lambda.
+
+```ruby
+class DataSyncJob < ApplicationJob
+  include JobWorkflow::DSL
+  
+  argument :force_sync, "TrueClass | FalseClass", default: false
+  argument :last_sync_at, "Time", default: nil
+  
+  # Execute only if more than 1 hour since last sync
+  task :sync_data,
+       condition: ->(ctx) { 
+         return true if ctx.arguments.force_sync  # Always execute if force_sync is true
+         last_sync = ctx.arguments.last_sync_at
+         !last_sync || last_sync <= 1.hour.ago
+       },
+       output: { sync_time: "Time" } do |ctx|
+    SyncService.perform
+    { sync_time: Time.current }
+  end
+end
+```