omni_service 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59a4a467df9c0035688d7084b232905e2e08690848f94155e848b19e892925d6
+  data.tar.gz: ea6a85ee1658f791d642e5ce3c2751e97a372458baeeecbb0f9c2715ccb2b01e
+SHA512:
+  metadata.gz: 2b10b64150672cb32353ef97ee6a88f598e12cd1702e354a3966d7858b481e0a463e311524eb7a820ac9730af0484c3118a8b9f761b45a9b9569e5e2f158ac30
+  data.tar.gz: 29c6d905f728eaac6c7737b94d22bf2f7c5fc96c48f6176185e7fa3105176183c61965ceb30d102bba6543ab22c3499d49f036b7e06e6788a9f3c4aea9e95d4d

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Arkadiy Zabazhanov
+
+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,209 @@
+# OmniService Framework
+
+Composable business operations with railway-oriented programming.
+
+## Quick Start
+
+```ruby
+class Posts::Create
+  extend OmniService::Convenience
+
+  option :post_repo, default: -> { PostRepository.new }
+
+  def self.system
+    @system ||= sequence(
+      input,
+      transaction(create, on_success: [notify])
+    )
+  end
+
+  def self.input
+    @input ||= parallel(
+      params { required(:title).filled(:string) },
+      FindOne.new(:author, repository: AuthorRepository.new, with: :author_id)
+    )
+  end
+
+  def self.create
+    ->(params, author:, **) { post_repo.create(params.merge(author:)) }
+  end
+end
+
+result = Posts::Create.system.call({ title: 'Hello', author_id: 1 })
+result.success?  # => true
+result.context   # => { author: <Author>, post: <Post> }
+```
+
+## Core Concepts
+
+### Components
+Any callable returning `Success(context_hash)` or `Failure(errors)`.
+
+```ruby
+# Lambda
+->(params, **ctx) { Success(post: Post.new(params)) }
+
+# Class with #call
+class ValidateTitle
+  def call(params, **)
+    params[:title].present? ? Success({}) : Failure([{ code: :blank, path: [:title] }])
+  end
+end
+```
+
+### Result
+Structured output with: `context`, `params`, `errors`, `on_success`, `on_failure`.
+
+```ruby
+result.success?  # no errors?
+result.failure?  # has errors?
+result.context   # { post: <Post>, author: <Author> }
+result.errors    # [#<Error code=:blank path=[:title]>]
+result.to_monad  # Success(result) or Failure(result)
+```
+
+## Composition
+
+### sequence
+Runs components in order. Short-circuits on first failure.
+
+```ruby
+sequence(
+  validate_params,  # Failure stops here
+  find_author,      # Adds :author to context
+  create_post       # Receives :author
+)
+```
+
+### parallel
+Runs all components, collects all errors.
+
+```ruby
+parallel(
+  validate_title,  # => Failure([{ path: [:title], code: :blank }])
+  validate_body    # => Failure([{ path: [:body], code: :too_short }])
+)
+# => Result with both errors collected
+```
+
+### transaction
+Wraps in DB transaction with callbacks.
+
+```ruby
+transaction(
+  sequence(validate, create),
+  on_success: [send_email, update_cache],  # After commit
+  on_failure: [log_error]                   # After rollback
+)
+```
+
+### namespace
+Scopes params/context under a key.
+
+```ruby
+# params: { post: { title: 'Hi' }, author: { name: 'John' } }
+parallel(
+  namespace(:post, validate_post),
+  namespace(:author, validate_author)
+)
+# Errors: [:post, :title], [:author, :name]
+```
+
+### collection
+Iterates over arrays.
+
+```ruby
+# params: { comments: [{ body: 'A' }, { body: '' }] }
+collection(validate_comment, namespace: :comments)
+# Errors: [:comments, 1, :body]
+```
+
+### optional
+Swallows failures.
+
+```ruby
+sequence(
+  create_user,
+  optional(fetch_avatar),  # Failure won't stop pipeline
+  send_email
+)
+```
+
+### shortcut
+Early exit on success.
+
+```ruby
+sequence(
+  shortcut(find_existing),  # Found? Exit early
+  create_new                 # Not found? Create
+)
+```
+
+## Entity Lookup
+
+### FindOne
+
+```ruby
+FindOne.new(:post, repository: repo)
+# params: { post_id: 1 } => Success(post: <Post>)
+
+# Options
+FindOne.new(:post, repository: repo, with: :slug)           # Custom param key
+FindOne.new(:post, repository: repo, by: [:author_id, :slug])  # Multi-column
+FindOne.new(:post, repository: repo, nullable: true)        # Allow nil
+FindOne.new(:post, repository: repo, omittable: true)       # Allow missing key
+FindOne.new(:post, repository: repo, skippable: true)       # Skip not found
+
+# Polymorphic
+FindOne.new(:item, repository: { 'Post' => post_repo, 'Article' => article_repo })
+# params: { item_id: 1, item_type: 'Post' }
+```
+
+### FindMany
+
+```ruby
+FindMany.new(:posts, repository: repo)
+# params: { post_ids: [1, 2, 3] } => Success(posts: [...])
+
+# Nested IDs
+FindMany.new(:products, repository: repo, by: { id: [:items, :product_id] })
+# params: { items: [{ product_id: 1 }, { product_id: [2, 3] }] }
+```
+
+## Error Format
+
+```ruby
+Failure(:not_found)
+# => Error(code: :not_found, path: [])
+
+Failure([{ code: :blank, path: [:title] }])
+# => Error(code: :blank, path: [:title])
+
+Failure([{ code: :too_short, path: [:body], tokens: { min: 100 } }])
+# => Error with interpolation tokens for i18n
+```
+
+## Async Execution
+
+```ruby
+class Posts::Create
+  extend OmniService::Convenience
+  extend OmniService::Async::Convenience[queue: 'default']
+
+  def self.system
+    @system ||= sequence(...)
+  end
+end
+
+Posts::Create.system_async.call(params, context)
+# => Success(job_id: 'abc-123')
+```
+
+## Strict Mode
+
+```ruby
+operation.call!(params)  # Raises OmniService::OperationFailed on failure
+
+# Or via convenience
+Posts::Create.system!.call(params)
+```

data/lib/omni_service/async.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Wraps operation execution in a background job (ActiveJob).
+# Returns immediately with Success(job_id: ...) instead of operation result.
+#
+# @example Direct usage
+#   async = OmniService::Async.new(Posts::Create, :system, job_class: PostJob)
+#   async.call({ title: 'Hello' }, author: user)
+#   # => Success(job_id: 'abc-123')
+#
+# @example Via Convenience module (recommended)
+#   class Posts::Create
+#     extend OmniService::Convenience
+#     extend OmniService::Async::Convenience[queue: 'default', retry: 3]
+#
+#     def self.system
+#       @system ||= sequence(validate_params, create_post)
+#     end
+#   end
+#
+#   Posts::Create.system_async.call({ title: 'Hello' }, author: user)
+#
+class OmniService::Async
+  extend Dry::Initializer
+  include Dry::Equalizer(:container_class, :container_method, :job_class, :job_options)
+  include OmniService::Inspect.new(:container_class, :container_method, :job_class, :job_options)
+  include Dry::Monads[:result]
+
+  # A helper module to simplify async operation creation.
+  #
+  # @example Basic usage
+  #
+  #   class MyOperation
+  #     extend OmniService::Convenience
+  #     extend OmniService::Async::Convenience[queue: 'important', retry: 3]
+  #
+  #     def self.system
+  #       @system ||= sequence(...)
+  #     end
+  #   end
+  #
+  #   MyOperation.system_async.call!(...)
+  #
+  # @example With custom job class
+  #
+  #   class MyOperation
+  #     extend OmniService::Convenience
+  #     extend OmniService::Async::Convenience[job_class: MyCustomJob]
+  #
+  #     def self.system
+  #       @system ||= sequence(...)
+  #     end
+  #   end
+  #
+  module Convenience
+    def self.[](**job_options)
+      job_class = job_options.delete(:job_class) || OperationJob
+
+      Module.new do
+        define_singleton_method(:extended) do |base|
+          base.extend OmniService::Async::Convenience
+          base.instance_variable_set(:@job_options, job_options)
+          base.instance_variable_set(:@job_class, job_class)
+        end
+      end
+    end
+
+    def method_missing(name, ...)
+      name_without_suffix = name.to_s.delete_suffix('_async').to_sym
+
+      if name.to_s.end_with?('_async') && respond_to?(name_without_suffix)
+        ivar_name = :"@#{name}"
+
+        if instance_variable_defined?(ivar_name)
+          instance_variable_get(ivar_name)
+        else
+          instance_variable_set(
+            ivar_name,
+            OmniService::Async.new(
+              self,
+              name_without_suffix,
+              job_class: @job_class || OperationJob,
+              job_options: @job_options || {}
+            )
+          )
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, *)
+      (name.to_s.end_with?('_async') && respond_to?(name.to_s.delete_suffix('_async').to_sym)) || super
+    end
+  end
+
+  param :container_class, OmniService::Types::Class
+  param :container_method, OmniService::Types::Symbol
+  option :job_class, OmniService::Types::Class, default: proc { OperationJob }
+  option :job_options, OmniService::Types::Hash, default: proc { {} }
+
+  def call(*params, **context)
+    job = job_class.set(job_options).perform_later(container_class, container_method, params, context)
+    Success(job_id: job.provider_job_id)
+  end
+end

data/lib/omni_service/collection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Iterates component over arrays in namespaced params and context.
+# Collects results from all iterations; errors include array index in path.
+#
+# Extracts arrays from params[namespace] and context[namespace].
+# Iteration count is max of array lengths. Missing indices get empty values.
+# Error paths are prefixed with [namespace, index, ...].
+#
+# @example Create multiple comments for a post
+#   # params: { comments: [{ body: 'First' }, { body: '' }] }
+#   # context: { comments: [{ author: user1 }, { author: user2 }] }
+#   collection(create_comment, namespace: :comments)
+#   # => Result(
+#   #      context: { comments: [{ comment: <Comment> }, { comment: nil }] },
+#   #      errors: [{ path: [:comments, 1, :body], code: :blank }]
+#   #    )
+#
+# @example Validate nested items
+#   collection(validate_line_item, namespace: :line_items)
+#   # Errors: [:line_items, 0, :quantity], [:line_items, 2, :price]
+#
+class OmniService::Collection
+  extend Dry::Initializer
+  include Dry::Equalizer(:component)
+  include OmniService::Inspect.new(:component)
+  include OmniService::Strict
+
+  param :component, OmniService::Types::Interface(:call)
+  option :namespace, OmniService::Types::Symbol
+
+  def call(*params, **context)
+    params_array = params.map { |param| param.symbolize_keys.fetch(namespace, []) }
+    context_array = context.fetch(namespace, [])
+    size = [*params_array.map(&:size), context_array.size].max
+
+    results = (0...size).map do |index|
+      call_wrapper(params_array, context_array, context, index)
+    end
+
+    compose_result(results, context)
+  end
+
+  def signature
+    @signature ||= [component_wrapper.signature.first, true]
+  end
+
+  private
+
+  def call_wrapper(params_array, context_array, context, index)
+    component_wrapper.call(
+      *params_array.pluck(index),
+      **context.except(namespace),
+      **(context_array[index] || {})
+    )
+  end
+
+  def compose_result(results, context)
+    OmniService::Result.build(
+      self,
+      params: results.map(&:params).transpose.map { |param| { namespace => param } },
+      context: context.merge(namespace => results.map(&:context)),
+      errors: compose_errors(results),
+      on_success: results.flat_map(&:on_success),
+      on_failure: results.flat_map(&:on_failure)
+    )
+  end
+
+  def compose_errors(results)
+    results.flat_map.with_index do |result, index|
+      result.errors.map { |error| error.new(path: [namespace, index, *error.path]) }
+    end
+  end
+
+  def component_wrapper
+    @component_wrapper ||= OmniService::Component.wrap(component)
+  end
+end

data/lib/omni_service/component.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Wraps any callable (lambda, proc, object responding to #call) and normalizes its execution.
+# Detects callable signature to properly dispatch params and context.
+#
+# Supported signatures:
+#   - `(**context)` - receives only context
+#   - `(params)` - receives only first param
+#   - `(params, **context)` - receives first param and context
+#   - `(p1, p2, ..., **context)` - receives multiple params and context
+#
+# @example Lambda with params and context
+#   component = OmniService::Component.new(->(params, **ctx) { Success(post: params) })
+#   component.call({ title: 'Hello' }, author: current_user)
+#   # => Result(context: { author: current_user, post: { title: 'Hello' } })
+#
+# @example Context-only callable
+#   component = OmniService::Component.new(->(**ctx) { Success(greeted: ctx[:user].name) })
+#   component.call({}, user: User.new(name: 'John'))
+#   # => Result(context: { user: ..., greeted: 'John' })
+#
+class OmniService::Component
+  extend Dry::Initializer
+  include Dry::Monads[:result]
+  include Dry::Equalizer(:callable)
+  include OmniService::Inspect.new(:callable)
+  include OmniService::Strict
+
+  MONADS_DO_WRAPPER_SIGNATURES = [
+    [%i[rest *], %i[block &]],
+    [%i[rest], %i[block &]], # Ruby 3.0, 3.1
+    [%i[rest *], %i[keyrest **], %i[block &]],
+    [%i[rest], %i[keyrest], %i[block &]] # Ruby 3.0, 3.1
+  ].freeze
+  DEFAULT_NAMES_MAP = { rest: '*', keyrest: '**' }.freeze # Ruby 3.0, 3.1
+
+  param :callable, OmniService::Types::Interface(:call)
+
+  def self.wrap(value)
+    if value.is_a?(Array)
+      value.map { |item| wrap(item) }
+    elsif value.respond_to?(:signature)
+      value
+    else
+      new(value)
+    end
+  end
+
+  def call(*params, **context)
+    callable_result = case signature
+    in [0, true]
+      callable.call(**context)
+    in [n, false]
+      callable.call(*params[...n])
+    in [n, true]
+      callable.call(*params[...n], **context)
+    end
+
+    OmniService::Result.build(callable, params:, context:).merge(OmniService::Result.process(callable, callable_result))
+  end
+
+  def signature
+    @signature ||= [
+      call_args(%i[rest]).empty? ? call_args(%i[req opt]).size : call_args(%i[rest]).size,
+      !call_args(%i[key keyreq keyrest]).empty?
+    ]
+  end
+
+  private
+
+  def call_args(types)
+    call_method = callable.respond_to?(:parameters) ? callable : callable.method(:call)
+    # calling super_method here because `OmniService::Convenience`
+    # calls `include Dry::Monads::Do.for(:call)` which creates
+    # a delegator method around the original one.
+    call_method = call_method.super_method if MONADS_DO_WRAPPER_SIGNATURES.include?(call_method.parameters)
+    call_method.parameters.filter_map do |(type, name)|
+      name || DEFAULT_NAMES_MAP[type] if types.include?(type)
+    end
+  end
+end

data/lib/omni_service/context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Validates caller-provided context values against type specifications.
+# Use for values passed at call time (current_user, request), not fetched entities.
+# Raises Dry::Types::CoercionError on type mismatches (not validation errors).
+# Only validates keys defined in schema; passes through undefined keys unchanged.
+#
+# @example Validate caller-provided context
+#   context(
+#     current_user: Types::Instance(User),
+#     correlation_id: Types::String.optional,
+#     logger: Types::Interface(:info, :error)
+#   )
+#
+class OmniService::Context
+  extend Dry::Initializer
+  include Dry::Monads[:result]
+
+  param :schema, OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Interface(:call))
+
+  def call(*params, **context)
+    validated = schema.to_h { |key, type| [key, type.call(context[key])] }
+    OmniService::Result.build(self, params:, context: context.merge(validated))
+  end
+
+  def signature
+    [-1, true]
+  end
+end

data/lib/omni_service/convenience.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# DSL module for building operations with composable components.
+# Provides factory methods and includes common dependencies.
+#
+# Includes: Dry::Initializer, Dry::Monads[:result], Dry::Monads::Do, Dry::Core::Constants
+#
+# Factory methods: sequence, parallel, transaction, optional, shortcut,
+#                  namespace, collection, context, params, noop
+#
+# Bang methods: Appending ! to any method returns a callable that uses call!
+#               e.g., MyOp.create! returns MyOp.create.method(:call!)
+#
+# @example Typical operation class
+#   class Posts::Create
+#     extend OmniService::Convenience
+#
+#     option :post_repo, default: -> { PostRepository.new }
+#
+#     def self.system
+#       @system ||= sequence(
+#         input,
+#         transaction(create, on_success: [notify])
+#       )
+#     end
+#
+#     def self.input
+#       @input ||= parallel(
+#         params { required(:title).filled(:string) },
+#         find_author
+#       )
+#     end
+#
+#     def self.create
+#       ->(params, author:, **) { post_repo.create(params.merge(author:)) }
+#     end
+#   end
+#
+#   Posts::Create.system.call({ title: 'Hello' }, current_user:)
+#   Posts::Create.system!.call({ title: 'Hello' }, current_user:)  # raises on failure
+#
+module OmniService::Convenience
+  def self.extended(mod)
+    mod.extend Dry::Initializer
+    mod.include Dry::Monads[:result]
+    mod.include Dry::Monads::Do.for(:call)
+    mod.include Dry::Core::Constants
+    mod.include OmniService::Helpers
+  end
+
+  def method_missing(name, ...)
+    name_without_suffix = name.to_s.delete_suffix('!').to_sym
+    if name.to_s.end_with?('!') && respond_to?(name_without_suffix)
+      public_send(name_without_suffix, ...).method(:call!)
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(name, *)
+    (name.to_s.end_with?('!') && respond_to?(name.to_s.delete_suffix('!').to_sym)) || super
+  end
+
+  def noop
+    ->(_, **) { Dry::Monads::Success({}) }
+  end
+
+  def sequence(...)
+    OmniService::Sequence.new(...)
+  end
+
+  def parallel(...)
+    OmniService::Parallel.new(...)
+  end
+
+  def collection(...)
+    OmniService::Collection.new(...)
+  end
+
+  def transaction(...)
+    OmniService::Transaction.new(...)
+  end
+
+  def shortcut(...)
+    OmniService::Shortcut.new(...)
+  end
+
+  def optional(...)
+    OmniService::Optional.new(...)
+  end
+
+  def namespace(...)
+    OmniService::Namespace.new(...)
+  end
+
+  def params(**, &)
+    OmniService::Params.params(**, &)
+  end
+
+  def context(schema)
+    OmniService::Context.new(schema)
+  end
+
+  def component(name, from = Object, **options, &block)
+    raise ArgumentError, "Please provide either a superclass or a block for #{name}" unless from || block
+
+    klass = Class.new(from)
+    klass.extend(Dry::Initializer) unless klass.include?(Dry::Initializer)
+    klass.include(Dry::Monads[:result]) unless klass.is_a?(Dry::Monads[:result])
+    klass.class_eval do
+      options.each do |name, type|
+        option name, type
+      end
+    end
+    klass.define_method(:call, &block) if block
+
+    const_set(name.to_s.camelize, klass)
+  end
+
+  %w[policy precondition callback].each do |kind|
+    define_method kind do |prefix = nil, from: OmniService::Component, &block|
+      component([prefix, kind].compact.join('_'), from:, &block)
+    end
+  end
+end