omni_service 0.1.0

data/lib/omni_service/optional.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Swallows component failures, returning empty success instead.
+# Useful for non-critical operations that shouldn't block the pipeline.
+#
+# On success: returns component result unchanged.
+# On failure: returns Success({}) with empty context, discarding errors.
+#
+# @example Optional profile enrichment
+#   sequence(
+#     create_user,
+#     optional(fetch_avatar_from_gravatar),  # Failure won't stop pipeline
+#     send_welcome_email
+#   )
+#
+# @example Optional cache warming
+#   sequence(
+#     update_post,
+#     optional(warm_cache)  # Cache failure is acceptable
+#   )
+#
+class OmniService::Optional
+  extend Dry::Initializer
+  include Dry::Equalizer(:component)
+  include OmniService::Inspect.new(:component)
+  include OmniService::Strict
+
+  param :component, OmniService::Types::Interface(:call)
+
+  def call(*params, **context)
+    result = component_wrapper.call(*params, **context)
+
+    if result.success?
+      result
+    else
+      OmniService::Result.build(self, params: result.params, context: {})
+    end
+  end
+
+  def signature
+    @signature ||= [component_wrapper.signature.first, true]
+  end
+
+  private
+
+  def component_wrapper
+    @component_wrapper ||= OmniService::Component.wrap(component)
+  end
+end

data/lib/omni_service/parallel.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Executes all components, collecting errors from all instead of short-circuiting.
+# Useful for validation where you want to report all issues at once.
+# Context merges from all components; params can be distributed or packed.
+#
+# @example Validate multiple fields, collect all errors
+#   parallel(
+#     validate_title,    # => Failure([{ path: [:title], code: :blank }])
+#     validate_body,     # => Failure([{ path: [:body], code: :too_short }])
+#     validate_author    # => Success(...)
+#   )
+#   # => Result with all errors collected
+#
+# @example Pack params from multiple sources into single hash
+#   parallel(
+#     parse_post_params,     # => Success({ title: 'Hi' }, ...)
+#     parse_metadata_params, # => Success({ tags: [...] }, ...)
+#     pack_params: true
+#   )
+#   # => Result(params: [{ title: 'Hi', tags: [...] }])
+#
+class OmniService::Parallel
+  extend Dry::Initializer
+  include Dry::Equalizer(:components)
+  include OmniService::Inspect.new(:components)
+  include OmniService::Strict
+
+  param :components, OmniService::Types::Array.of(OmniService::Types::Interface(:call))
+  option :pack_params, OmniService::Types::Bool, default: proc { false }
+
+  def initialize(*args, **)
+    super(args.flatten(1), **)
+  end
+
+  def call(*params, **context) # rubocop:disable Metrics/AbcSize
+    leftovers, result = component_wrappers
+      .inject([params, OmniService::Result.build(self, context:)]) do |(params_left, result), component|
+        break [params_left, result] if result.shortcut?
+
+        component_params = params_left[...component.signature.first]
+        component_result = component.call(*component_params, **result.context)
+        result_params = if pack_params
+          [(result.params.first || {}).merge(component_result.params.first)]
+        else
+          result.params + component_result.params
+        end
+
+        [
+          params.one? ? params : params_left[component_params.size..],
+          result.merge(component_result, params: result_params)
+        ]
+      end
+
+    params.one? ? result : result.merge(params: result.params + leftovers)
+  end
+
+  def signature
+    @signature ||= begin
+      param_counts = component_wrappers.map { |component| component.signature.first }
+      [param_counts.all? ? param_counts.sum : nil, true]
+    end
+  end
+
+  private
+
+  def component_wrappers
+    @component_wrappers ||= OmniService::Component.wrap(components)
+  end
+end

data/lib/omni_service/params.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Validates params against a Dry::Validation::Contract.
+class OmniService::Params
+  extend Dry::Initializer
+
+  param :contract, OmniService::Types::Instance(Dry::Validation::Contract)
+  option :optional, OmniService::Types::Bool, default: proc { false }
+
+  def self.to_failure(message)
+    {
+      code: (message.predicate if message.respond_to?(:predicate)) || :invalid,
+      message: message.dump,
+      path: message.path,
+      tokens: message.respond_to?(:meta) ? message.meta : {}
+    }
+  end
+
+  def self.params(**, &)
+    new(**) { params(&) }
+  end
+
+  def initialize(contract = nil, **, &)
+    contract_class = Class.new(Dry::Validation::Contract, &)
+    super(contract || contract_class.new, **)
+  end
+
+  def call(params = {}, **context)
+    contract_result = contract.call(params, context)
+
+    if optional && contract_result.to_h.empty?
+      OmniService::Result.build(self, params: [{}])
+    else
+      to_operation_result(contract_result)
+    end
+  end
+
+  private
+
+  def to_operation_result(contract_result)
+    OmniService::Result.build(
+      self,
+      params: [contract_result.to_h],
+      context: contract_result.context.each.to_h,
+      errors: contract_result.errors.map do |error|
+        OmniService::Error.build(self, **self.class.to_failure(error))
+      end
+    )
+  end
+end

data/lib/omni_service/result.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Structured result of component execution.
+#
+# Attributes:
+# - operation: the component that produced this result
+# - shortcut: component that triggered early exit (if any)
+# - params: array of transformed params
+# - context: accumulated key-value pairs from all components
+# - errors: array of OmniService::Error
+# - on_success: results from transaction success callbacks
+# - on_failure: results from transaction failure callbacks
+#
+# Components return Success/Failure monads which are converted to Result:
+# - Success(key: value) => Result(context: { key: value })
+# - Success(params, key: value) => Result(params: [params], context: { key: value })
+# - Failure(:code) => Result(errors: [Error(code: :code)])
+# - Failure([{ code:, path:, message: }]) => Result(errors: [...])
+#
+# @example Checking result
+#   result = operation.call(params, **context)
+#   result.success?  # => true/false
+#   result.failure?  # => true/false
+#   result.context   # => { post: <Post>, author: <Author> }
+#   result.errors    # => [#<Error code=:blank path=[:title]>]
+#
+# @example Converting to monad
+#   result.to_monad  # => Success(result) or Failure(result)
+#
+class OmniService::Result
+  extend Dry::Initializer
+  include Dry::Monads[:result]
+  include Dry::Equalizer(:operation, :params, :context, :errors, :on_success, :on_failure)
+  include OmniService::Inspect.new(:operation, :params, :context, :errors, :on_success, :on_failure)
+
+  option :operation, type: OmniService::Types::Interface(:call)
+  option :shortcut, type: OmniService::Types::Interface(:call).optional, default: proc {}
+  option :params, type: OmniService::Types::Array
+  option :context, type: OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Any)
+  option :errors, type: OmniService::Types::Array.of(OmniService::Error)
+  option :on_success, type: OmniService::Types::Array.of(
+    OmniService::Types::Instance(OmniService::Result) | OmniService::Types::Instance(Concurrent::Promises::Future)
+  ), default: proc { [] }
+  option :on_failure, type: OmniService::Types::Array.of(OmniService::Types::Instance(OmniService::Result)), default: proc { [] }
+
+  def self.process(component, result)
+    case result
+    in OmniService::Result
+      result
+    in Success(params, *other_params, Hash => context) if context.keys.all?(Symbol)
+      OmniService::Result.build(component, params: [params, *other_params], context:)
+    in Success(Hash => context) if context.keys.all?(Symbol)
+      OmniService::Result.build(component, context:)
+    in Failure[*failures]
+      OmniService::Result.build(component, errors: OmniService::Error.process(component, failures))
+    else
+      raise "Invalid callable result `#{result.inspect}` returned by `#{component.inspect}`"
+    end
+  end
+
+  def self.build(operation, **)
+    new(operation:, params: [], context: {}, errors: [], **)
+  end
+
+  def merge(other = nil, **changes)
+    if other
+      self.class.new(
+        operation:,
+        shortcut: shortcut || other.shortcut,
+        **merged_attributes(other),
+        **changes
+      )
+    else
+      self.class.new(**self.class.dry_initializer.attributes(self), **changes)
+    end
+  end
+
+  alias shortcut? shortcut
+
+  def success?
+    errors.empty?
+  end
+
+  def failure?
+    !success?
+  end
+
+  def to_monad
+    success? ? Success(self) : Failure(self)
+  end
+
+  def deconstruct_keys(_)
+    { operation:, params:, context:, errors: }
+  end
+
+  private
+
+  def merged_attributes(other)
+    {
+      params: other.params.empty? ? params : other.params,
+      context: context.merge(other.context),
+      errors: errors + other.errors,
+      on_success: on_success + other.on_success,
+      on_failure: on_failure + other.on_failure
+    }
+  end
+end

data/lib/omni_service/sequence.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Executes components sequentially, short-circuiting on first failure or shortcut.
+# Context accumulates across components; each receives merged context from previous.
+#
+# @example Blog post creation pipeline
+#   sequence(
+#     validate_params,           # Failure here stops the pipeline
+#     find_author,               # Adds :author to context
+#     create_post,               # Receives :author, adds :post
+#     notify_subscribers         # Receives :author and :post
+#   )
+#
+# @example With shortcut for idempotency
+#   sequence(
+#     shortcut(find_existing_post),  # Success here exits early
+#     validate_params,
+#     create_post
+#   )
+#
+class OmniService::Sequence
+  extend Dry::Initializer
+  include Dry::Equalizer(:components)
+  include OmniService::Inspect.new(:components)
+  include OmniService::Strict
+
+  param :components, OmniService::Types::Array.of(OmniService::Types::Interface(:call))
+
+  def initialize(*args, **)
+    super(args.flatten(1), **)
+  end
+
+  def call(*params, **context)
+    component_wrappers.inject(OmniService::Result.build(self, params:, context:)) do |result, component|
+      break result if result.failure? || result.shortcut?
+
+      result.merge(component.call(*result.params, **result.context))
+    end
+  end
+
+  def signature
+    @signature ||= begin
+      param_counts = component_wrappers.map { |component| component.signature.first }
+      [param_counts.all? ? param_counts.max : nil, true]
+    end
+  end
+
+  private
+
+  def component_wrappers
+    @component_wrappers ||= OmniService::Component.wrap(components)
+  end
+end

data/lib/omni_service/shortcut.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Enables early pipeline exit on success. Used for idempotency and guard clauses.
+#
+# On success: marks result with shortcut flag, causing Sequence to exit immediately.
+# On failure: returns empty success, allowing pipeline to continue.
+#
+# @example Idempotent post creation
+#   sequence(
+#     shortcut(find_existing_post),  # Found? Exit with existing post
+#     validate_params,                # Not found? Continue creation
+#     create_post
+#   )
+#
+# @example Guard clause
+#   sequence(
+#     shortcut(check_already_subscribed),  # Already subscribed? Done
+#     validate_subscription,
+#     create_subscription
+#   )
+#
+class OmniService::Shortcut
+  extend Dry::Initializer
+  include Dry::Equalizer(:component)
+  include OmniService::Inspect.new(:component)
+  include OmniService::Strict
+
+  param :component, OmniService::Types::Interface(:call)
+
+  def call(*params, **context)
+    result = component_wrapper.call(*params, **context)
+
+    if result.success?
+      result.merge(shortcut: component)
+    else
+      OmniService::Result.build(self, params:, context:)
+    end
+  end
+
+  def signature
+    @signature ||= [component_wrapper.signature.first, true]
+  end
+
+  private
+
+  def component_wrapper
+    @component_wrapper ||= OmniService::Component.wrap(component)
+  end
+end

data/lib/omni_service/strict.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OmniService
+  # Exception raised by call! when operation fails.
+  # Contains the full operation result for inspection.
+  class OperationFailed < StandardError
+    attr_reader :operation_result
+
+    def initialize(operation_result)
+      @operation_result = operation_result
+      super(operation_result.errors.pretty_inspect)
+    end
+  end
+
+  # Provides call! method that raises OperationFailed on failure.
+  # Included in all framework components.
+  #
+  # @example Raising on failure
+  #   operation.call!(params)  # => raises OperationFailed if result.failure?
+  #
+  # @example Rescuing
+  #   begin
+  #     operation.call!(params)
+  #   rescue OmniService::OperationFailed => e
+  #     e.operation_result.errors  # => [#<Error ...>]
+  #   end
+  #
+  module Strict
+    def call!(*params, **context)
+      result = call(*params, **context)
+      raise OmniService::OperationFailed, result if result.failure?
+
+      result
+    end
+  end
+end

data/lib/omni_service/transaction.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Wraps component execution in a database transaction with callback support.
+# Rolls back on failure; executes on_success callbacks after commit, on_failure after rollback.
+#
+# Callbacks run asynchronously by default (configurable via OmniService.with_sync_callbacks).
+# on_success callbacks receive the same params and context as the main component.
+# on_failure callbacks receive the failed Result as their first param.
+#
+# @example Post creation with notifications
+#   transaction(
+#     sequence(validate_params, create_post),
+#     on_success: [send_notifications, update_feed],
+#     on_failure: [log_failure, alert_admin]
+#   )
+#
+# @example Nested transactions
+#   transaction(
+#     sequence(
+#       create_post,
+#       transaction(create_comments, on_success: [notify_commenters])
+#     ),
+#     on_success: [notify_author]
+#   )
+#
+class OmniService::Transaction
+  extend Dry::Initializer
+  include Dry::Equalizer(:component, :on_success, :on_failure)
+  include OmniService::Inspect.new(:component, :on_success, :on_failure)
+  include OmniService::Strict
+
+  # Internal exception to trigger transaction rollback on component failure.
+  class Halt < StandardError
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super
+    end
+  end
+
+  param :component, OmniService::Types::Interface(:call)
+  option :on_success, OmniService::Types::Coercible::Array.of(OmniService::Types::Interface(:call)),
+    default: proc { [] }
+  option :on_failure, OmniService::Types::Coercible::Array.of(OmniService::Types::Interface(:call)),
+    default: proc { [] }
+
+  def call(*params, **context)
+    result = call_transaction(*params, **context).merge(operation: self)
+
+    return result if result.success?
+
+    on_failure_results = on_failure_callbacks.map { |callback| callback.call(result) }
+    result.merge(on_failure: result.on_failure + on_failure_results)
+  end
+
+  def signature
+    @signature ||= [component_wrapper.signature.first, true]
+  end
+
+  private
+
+  def call_transaction(*params, **context)
+    transaction_result = ActiveRecord::Base.transaction(requires_new: true) do |transaction|
+      result = component_wrapper.call(*params, **context)
+
+      return result if result.shortcut?
+      raise Halt, result if result.failure?
+
+      handle_on_success(transaction, result)
+    end
+
+    resolve_callback_promises(transaction_result)
+  rescue Halt => e
+    e.result
+  end
+
+  def component_wrapper
+    @component_wrapper ||= OmniService::Component.wrap(component)
+  end
+
+  def on_success_callbacks
+    @on_success_callbacks ||= OmniService::Component.wrap(on_success)
+  end
+
+  def on_failure_callbacks
+    @on_failure_callbacks ||= OmniService::Component.wrap(on_failure)
+  end
+
+  def on_success_promises(result)
+    captured_sync = OmniService.sync_callbacks?
+    executor = captured_sync ? :immediate : :io
+
+    on_success_callbacks.map do |callback|
+      promise = Concurrent::Promises
+        .delay_on(executor, callback, result, captured_sync) do |on_success_callback, operation_result, sync_value|
+          OmniService.with_sync_callbacks(sync_value) do
+            on_success_callback.call(*operation_result.params, **operation_result.context)
+          end
+        end
+
+      # In async mode, escape promise exception capture so error tracking services can catch it via thread reporting.
+      promise = promise.on_rejection { |error| Thread.new { raise error } } unless captured_sync
+      promise
+    end
+  end
+
+  def handle_on_success(transaction, result)
+    on_success_promises = on_success_promises(result)
+
+    if OmniService.sync_callbacks?
+      transaction.after_commit { Concurrent::Promises.zip(*on_success_promises).wait }
+    else
+      transaction.after_commit { on_success_promises.each(&:touch) }
+    end
+
+    result.merge(on_success: result.on_success + on_success_promises)
+  end
+
+  def resolve_callback_promises(result)
+    result.merge(on_success: result.on_success.map do |callback_result|
+      next callback_result unless callback_result.is_a?(Concurrent::Promises::Future)
+
+      OmniService.sync_callbacks? ? callback_result.value! : callback_result
+    end)
+  end
+end

data/lib/omni_service/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OmniService
+  VERSION = '0.1.0'
+end

data/lib/omni_service.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'dry/core/constants'
+require 'dry/monads'
+require 'dry/monads/do'
+require 'dry-struct'
+require 'dry-initializer'
+require 'dry/types'
+require 'active_support'
+require 'concurrent-ruby'
+
+# Framework for composable business operations with railway-oriented programming.
+#
+# Core concepts:
+# - Components: callables returning Success/Failure monads
+# - Results: structured output with context, params, and errors
+# - Composition: sequence, parallel, transaction, namespace, collection
+#
+# @example Simple operation
+#   class Posts::Create
+#     extend OmniService::Convenience
+#
+#     option :post_repo, default: -> { PostRepository.new }
+#
+#     def self.system
+#       @system ||= sequence(
+#         validate_params,
+#         transaction(create_post, on_success: [notify_subscribers])
+#       )
+#     end
+#   end
+#
+#   result = Posts::Create.system.call({ title: 'Hello' }, current_user: user)
+#   result.success?  # => true
+#   result.context   # => { post: <Post> }
+#
+# @see OmniService::Convenience DSL for building operations
+# @see OmniService::Result structured result object
+#
+module OmniService
+  include Dry::Core::Constants
+
+  Types = Dry.Types()
+
+  class << self
+    def sync_callbacks?
+      !!Thread.current[:omni_service_sync_callbacks]
+    end
+
+    def with_sync_callbacks(value = true) # rubocop:disable Style/OptionalBooleanParameter
+      old_value = Thread.current[:omni_service_sync_callbacks]
+      Thread.current[:omni_service_sync_callbacks] = value
+      yield
+    ensure
+      Thread.current[:omni_service_sync_callbacks] = old_value
+    end
+  end
+end
+
+require_relative 'omni_service/version'
+require_relative 'omni_service/strict'
+require_relative 'omni_service/helpers'
+require_relative 'omni_service/inspect'
+require_relative 'omni_service/error'
+require_relative 'omni_service/result'
+require_relative 'omni_service/component'
+require_relative 'omni_service/context'
+require_relative 'omni_service/sequence'
+require_relative 'omni_service/parallel'
+require_relative 'omni_service/collection'
+require_relative 'omni_service/optional'
+require_relative 'omni_service/find_one'
+require_relative 'omni_service/find_many'
+require_relative 'omni_service/namespace'
+require_relative 'omni_service/shortcut'
+require_relative 'omni_service/transaction'
+require_relative 'omni_service/convenience'
+require_relative 'omni_service/async'