omni_service 0.1.0

data/lib/omni_service/error.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Structured validation/operation error.
+#
+# Attributes:
+# - component: the component that produced the error
+# - code: symbolic error code (e.g., :blank, :not_found, :invalid)
+# - message: human-readable message (optional)
+# - path: array of keys/indices to error location (e.g., [:author, :email])
+# - tokens: interpolation values for message templates (e.g., { min: 5 })
+#
+# Components return failures that are converted to Error:
+# - Failure(:code) => Error(code: :code)
+# - Failure("message") => Error(message: "message")
+# - Failure({ code:, path:, message:, tokens: }) => Error(...)
+# - Failure([...]) => multiple Errors
+#
+# @example Simple error
+#   Failure(:not_found)
+#   # => Error(code: :not_found, path: [])
+#
+# @example Error with path
+#   Failure([{ code: :blank, path: [:title] }])
+#   # => Error(code: :blank, path: [:title])
+#
+# @example Error with tokens for i18n
+#   Failure([{ code: :too_short, path: [:body], tokens: { min: 100 } }])
+#
+class OmniService::Error < Dry::Struct
+  attribute :component, OmniService::Types::Interface(:call)
+  attribute :message, OmniService::Types::Strict::String.optional
+  attribute :code, OmniService::Types::Strict::Symbol.optional
+  attribute :path, OmniService::Types::Coercible::Array.of(OmniService::Types::Symbol | OmniService::Types::Integer)
+  attribute :tokens, OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Any)
+
+  def self.process(component, failure)
+    case failure
+    in Array
+      failure.flat_map { |error| process(component, error) }
+    in OmniService::Error
+      failure.new(component:)
+    in String
+      [build(component, message: failure)]
+    in Symbol
+      [build(component, code: failure)]
+    in Hash
+      [build(component, **failure)]
+    else
+      raise "Invalid failure `#{failure.inspect}` returned by `#{component.inspect}`"
+    end
+  end
+
+  def self.build(component, **)
+    new(message: nil, code: nil, path: [], tokens: {}, **, component:)
+  end
+end

data/lib/omni_service/find_many.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+# Finds multiple entities by IDs via repository#get_many.
+# Accepts array of IDs or nested structures with IDs.
+# Returns deduplicated entities; reports not-found errors with array indices.
+#
+# Options:
+# - :with - param key for IDs array (default: :"#{context_key.singularize}_ids")
+# - :by - column mapping with nested paths: { id: [:items, :product_id] }
+# - :repository - single repo or Hash for polymorphic lookup
+# - :type - path to type discriminator for polymorphic lookup
+#
+# Flags:
+# - :nullable - skip nil values in array instead of reporting errors
+# - :omittable - allow missing param key, returns Success({})
+#
+# @example Basic bulk lookup
+#   FindMany.new(:posts, repository: post_repo)
+#   # params: { post_ids: [1, 2, 3] } => Success(posts: [<Post>, <Post>, <Post>])
+#
+# @example Nested IDs in array of hashes
+#   FindMany.new(:products, repository: repo, by: { id: [:items, :product_id] })
+#   # params: { items: [{ product_id: 1 }, { product_id: [2, 3] }] }
+#   # => Success(products: [<Product>, <Product>, <Product>])
+#
+# @example Error reporting with indices
+#   # params: { post_ids: [1, 999, 3] } where 999 doesn't exist
+#   # => Failure([{ code: :not_found, path: [:post_ids, 1] }])
+#
+# @example Polymorphic lookup
+#   FindMany.new(:attachments, repository: { 'Image' => img_repo, 'Video' => vid_repo },
+#                by: { id: [:files, :id] }, type: [:files, :type])
+#   # params: { files: [{ type: 'Image', id: 1 }, { type: 'Video', id: 2 }] }
+#
+# @example Nullable for optional associations
+#   FindMany.new(:tags, repository: repo, nullable: true)
+#   # params: { tag_ids: [1, nil, 2] } => Success(tags: [<Tag>, <Tag>])
+#
+class OmniService::FindMany
+  extend Dry::Initializer
+  include Dry::Core::Constants
+  include Dry::Monads[:result]
+  include OmniService::Inspect.new(:context_key, :repository, :lookup, :omittable)
+
+  PRIMARY_KEY = :id
+
+  Reference = Class.new(Dry::Struct) do
+    attribute :path, OmniService::Types::Array.of(OmniService::Types::Symbol | OmniService::Types::Integer)
+    attribute :value, OmniService::Types::Any
+
+    def undefined?
+      Undefined.equal?(value)
+    end
+
+    def missing_id_path
+      path if undefined?
+    end
+
+    def missing_type_path; end
+
+    def normalized_value
+      Array.wrap(value)
+    end
+  end
+
+  PolymorphicReference = Class.new(Dry::Struct) do
+    attribute :type, Reference
+    attribute :id, Reference
+
+    delegate :path, :missing_id_path, to: :id
+
+    def undefined?
+      type.undefined? || id.undefined?
+    end
+
+    def missing_type_path
+      type.missing_id_path unless id.value.nil?
+    end
+  end
+
+  param :context_key, OmniService::Types::Symbol
+  option :repository, OmniService::Types::Interface(:get_many) |
+    OmniService::Types::Hash.map(OmniService::Types::String, OmniService::Types::Interface(:get_many))
+  option :type, OmniService::Types::Coercible::Array.of(OmniService::Types::Symbol), default: proc { :type }
+  option :with, OmniService::Types::Symbol, default: proc { :"#{context_key.to_s.singularize}_ids" }
+  option :by, OmniService::Types::Symbol |
+    OmniService::Types::Array.of(OmniService::Types::Symbol) |
+    OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Symbol |
+      OmniService::Types::Array.of(OmniService::Types::Symbol)), optional: true
+  option :omittable, OmniService::Types::Bool, default: proc { false }
+  option :nullable, OmniService::Types::Bool, default: proc { false }
+
+  def call(params, **context)
+    return Success({}) if already_found?(context)
+
+    references, *missing_paths = references(params)
+    no_errors = missing_paths.all?(&:empty?)
+
+    if references.values.all?(&:empty?) && no_errors
+      Success({})
+    elsif !no_errors
+      missing_keys_result(*missing_paths)
+    else
+      find(references)
+    end
+  end
+
+  private
+
+  def already_found?(context)
+    context[context_key].respond_to?(:to_ary)
+  end
+
+  def missing_keys_result(missing_paths, invalid_type_paths)
+    if omittable || missing_paths.all?(&:empty?) && invalid_type_paths.empty?
+      Success({})
+    else
+      Failure(
+        missing_paths.map { |path| { code: :missing, path: } } +
+        invalid_type_paths.map { |path| { code: :included, path:, tokens: { allowed_values: repository.keys } } }
+      )
+    end
+  end
+
+  def references(params)
+    result = pointers.index_with do |pointer|
+      undefined_references, references = pointer_references(params, *pointer).partition(&:undefined?)
+
+      [references, missing_paths(undefined_references), invalid_type_paths(references)]
+    end
+
+    [result.transform_values(&:first), result.values.flat_map(&:second), result.values.flat_map(&:third)]
+  end
+
+  def pointer_references(params, segment = nil, *pointer, path: [], type_reference: Undefined)
+    return [id_reference(params, path, type_reference)] unless segment
+
+    case params
+    when Array
+      params.flat_map.with_index do |value, index|
+        pointer_references(value, segment, *pointer, path: [*path, index], type_reference:)
+      end
+    when Hash
+      hash_pointer_references(params, segment, *pointer, path:, type_reference:)
+    else
+      []
+    end
+  end
+
+  def hash_pointer_references(params, segment, *pointer, path:, type_reference:)
+    type_reference = type_reference(params, path) if polymorphic? && path.grep(Symbol) == type[..-2]
+    pointer_references(
+      params.key?(segment) ? params[segment] : Undefined,
+      *pointer,
+      path: [*path, segment],
+      type_reference:
+    )
+  end
+
+  def type_reference(params, path)
+    Reference.new(path: [*path, type.last], value: params.key?(type.last) ? params[type.last] : Undefined)
+  end
+
+  def id_reference(params, path, type_reference)
+    id_reference = Reference.new(path:, value: params)
+    polymorphic? ? PolymorphicReference.new(type: type_reference, id: id_reference) : id_reference
+  end
+
+  def missing_paths(undefined_references)
+    missing_id_paths = omittable ? [] : undefined_references.filter_map(&:missing_id_path)
+    missing_type_paths = undefined_references.filter_map(&:missing_type_path)
+
+    missing_id_paths + missing_type_paths
+  end
+
+  def invalid_type_paths(references)
+    if polymorphic?
+      references.filter_map { |reference| reference.type.path unless repository.key?(reference.type.value) }
+    else
+      []
+    end
+  end
+
+  def find(references)
+    # TODO: use all columns/pointer somehow
+    pointer = pointers.first
+    column = columns.first
+
+    if polymorphic?
+      type_references = references[pointer].group_by { |reference| reference.type.value }
+      result, not_found_paths = fetch_polymorphic(type_references, column)
+    else
+      result, not_found_paths = fetch(references[pointer], column, repository)
+    end
+
+    find_result(result, not_found_paths)
+  end
+
+  def fetch(references, column, repository)
+    ids = references.flat_map(&:normalized_value).uniq
+    result = repository.get_many(column => ids).to_a
+    not_found_paths = not_found_paths(result.index_by(&column), references)
+    [result, not_found_paths]
+  end
+
+  def fetch_polymorphic(type_references, column)
+    type_references
+      .map { |(type, references)| fetch(references.map(&:id), column, repository[type]) }
+      .transpose.map { |a| a.flatten(1) }
+  end
+
+  def not_found_paths(entities_index, references)
+    references.flat_map do |reference|
+      if reference.value.is_a?(Array)
+        reference.value.filter_map.with_index { |v, i| [*reference.path, i] if missing_value?(entities_index, v) }
+      else
+        missing_value?(entities_index, reference.value) ? [reference.path] : []
+      end
+    end
+  end
+
+  def missing_value?(entities_index, value)
+    !(entities_index.key?(value) || (nullable && value.nil?))
+  end
+
+  def find_result(entities, not_found_paths)
+    if not_found_paths.empty?
+      Success(context_key => entities.compact)
+    else
+      not_found_failure(not_found_paths)
+    end
+  end
+
+  def not_found_failure(paths)
+    Failure(paths.map { |path| { code: :not_found, path: } })
+  end
+
+  def lookup
+    @lookup ||= columns.zip(pointers).to_h
+  end
+
+  def pointers
+    @pointers ||= if by.is_a?(Hash)
+      by.values
+    else
+      Array.wrap(by || with)
+    end.map { |path| Array.wrap(path) }
+  end
+
+  def columns
+    @columns ||= if by.is_a?(Hash)
+      by.keys
+    else
+      Array.wrap(by || PRIMARY_KEY)
+    end
+  end
+
+  def polymorphic?
+    repository.is_a?(Hash)
+  end
+end

data/lib/omni_service/find_one.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# Finds a single entity by ID or attributes via repository#get_one.
+# Skips lookup if entity already exists in context.
+#
+# Options:
+# - :with - param key for lookup (default: :"#{context_key}_id")
+# - :by - column mapping, supports nested paths: { id: [:deep, :post_id] }
+# - :repository - single repo or Hash for polymorphic lookup
+# - :type - path to type discriminator for polymorphic lookup
+#
+# Flags:
+# - :nullable - allow nil param value, returns Success(key: nil)
+# - :omittable - allow missing param key, returns Success({})
+# - :skippable - return Success({}) when entity not found instead of Failure
+#
+# @example Basic lookup
+#   FindOne.new(:post, repository: post_repo)
+#   # params: { post_id: 123 } => Success(post: <Post>)
+#
+# @example Custom lookup key
+#   FindOne.new(:post, repository: post_repo, with: :slug)
+#   # params: { slug: 'hello' } => get_one(id: 'hello')
+#
+# @example Nested param path
+#   FindOne.new(:post, repository: post_repo, by: { id: [:data, :post_id] })
+#   # params: { data: { post_id: 123 } } => get_one(id: 123)
+#
+# @example Multi-column lookup
+#   FindOne.new(:post, repository: post_repo, by: [:author_id, :slug])
+#   # params: { author_id: 1, slug: 'hi' } => get_one(author_id: 1, slug: 'hi')
+#
+# @example Polymorphic lookup
+#   FindOne.new(:comment, repository: { 'Post' => post_repo, 'Article' => article_repo })
+#   # params: { comment_id: 1, comment_type: 'Post' } => post_repo.get_one(id: 1)
+#
+# @example Nullable association (for clearing)
+#   FindOne.new(:category, repository: repo, nullable: true)
+#   # params: { category_id: nil } => Success(category: nil)
+#
+# @example Omittable for partial updates
+#   FindOne.new(:category, repository: repo, omittable: true)
+#   # params: {} => Success({}) - doesn't touch association
+#
+# @example Skippable for soft-deleted lookups
+#   FindOne.new(:post, repository: repo, skippable: true)
+#   # params: { post_id: 999 } (not found) => Success({})
+#
+class OmniService::FindOne
+  extend Dry::Initializer
+  include Dry::Monads[:result]
+  include OmniService::Inspect.new(:context_key, :repository, :lookup, :omittable, :nullable)
+
+  PRIMARY_KEY = :id
+
+  param :context_key, OmniService::Types::Symbol
+  option :repository, OmniService::Types::Interface(:get_one) |
+    OmniService::Types::Hash.map(OmniService::Types::String, OmniService::Types::Interface(:get_one))
+  option :type, OmniService::Types::Coercible::Array.of(OmniService::Types::Symbol), default: proc { :"#{context_key}_type" }
+  option :with, OmniService::Types::Symbol, default: proc { :"#{context_key}_id" }
+  option :by, OmniService::Types::Symbol |
+    OmniService::Types::Array.of(OmniService::Types::Symbol) |
+    OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Symbol |
+      OmniService::Types::Array.of(OmniService::Types::Symbol)), optional: true
+  option :omittable, OmniService::Types::Bool, default: proc { false }
+  option :nullable, OmniService::Types::Bool, default: proc { false }
+  option :skippable, OmniService::Types::Bool, default: proc { false }
+
+  def call(params, **context)
+    return Success({}) if already_found?(context)
+
+    missing_keys = missing_keys(params, pointers)
+    return missing_keys_result(missing_keys, context) unless missing_keys.empty?
+
+    values = values(params)
+    return Success(context_key => nil) if nullable && values.all?(&:nil?)
+
+    repository = resolve_repository(params)
+    return repository_failure(params, values) unless repository
+
+    find(values, repository:)
+  end
+
+  private
+
+  def already_found?(context)
+    nullable ? context.key?(context_key) : !context[context_key].nil?
+  end
+
+  def missing_keys(params, paths)
+    paths.reject do |path|
+      deep_object = path.one? ? params : params.dig(*path[..-2])
+      deep_object.is_a?(Hash) && deep_object.key?(path.last)
+    end
+  end
+
+  def missing_keys_result(missing_keys, context)
+    if nil_in_context?(context)
+      not_found_failure
+    elsif omittable && missing_keys.size == pointers.size
+      Success({})
+    else
+      missing_keys_failure(missing_keys)
+    end
+  end
+
+  def nil_in_context?(context)
+    !nullable && context.key?(context_key) && context[context_key].nil?
+  end
+
+  def values(params)
+    pointers.map { |pointer| params.dig(*pointer) }
+  end
+
+  def resolve_repository(params)
+    if repository.is_a?(Hash)
+      repository[params.dig(*type)]
+    else
+      repository
+    end
+  end
+
+  def repository_failure(params, values)
+    missing_keys = missing_keys(params, [type])
+
+    if values.all?(&:nil?)
+      not_found_failure
+    elsif missing_keys.empty?
+      Failure([{ code: :included, path: type, tokens: { allowed_values: repository.keys } }])
+    else
+      missing_keys_failure(missing_keys)
+    end
+  end
+
+  def find(values, repository:)
+    result = repository.get_one(**columns.zip(values).to_h)
+
+    if result.nil?
+      skippable ? Success({}) : not_found_failure
+    else
+      Success(context_key => result)
+    end
+  end
+
+  def missing_keys_failure(paths)
+    Failure(paths.map { |path| { code: :missing, path: } })
+  end
+
+  def not_found_failure
+    Failure(pointers.map { |pointer| { code: :not_found, path: pointer } })
+  end
+
+  def lookup
+    @lookup ||= columns.zip(pointers).to_h
+  end
+
+  def pointers
+    @pointers ||= if by.is_a?(Hash)
+      by.values
+    else
+      Array.wrap(by || with)
+    end.map { |path| Array.wrap(path) }
+  end
+
+  def columns
+    @columns ||= if by.is_a?(Hash)
+      by.keys
+    else
+      Array.wrap(by || PRIMARY_KEY)
+    end
+  end
+end

data/lib/omni_service/helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Instance-level utility methods included via OmniService::Convenience.
+#
+# @example Converting external failures to OmniService errors
+#   def call(params, **)
+#     result = external_service.validate(params)
+#     yield process_errors(result, path_prefix: [:external])
+#     # Failure from external becomes: [{ path: [:external, :field], code: :invalid }]
+#   end
+#
+module OmniService::Helpers
+  def process_errors(result, path_prefix: [])
+    return result if result.success?
+
+    Failure(OmniService::Error.process(self, result.failure).map do |error|
+      error.new(path: [*path_prefix, *error.path])
+    end)
+  end
+end

data/lib/omni_service/inspect.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Module factory for custom pretty_print output.
+# Generates a module that defines pretty_print showing specified attributes.
+#
+# @example Adding inspection to a class
+#   class MyComponent
+#     include OmniService::Inspect.new(:name, :options)
+#     # Now `pp my_component` shows: #<MyComponent name=..., options=...>
+#   end
+#
+class OmniService::Inspect < Module
+  extend Dry::Initializer
+
+  param :attributes, OmniService::Types::Coercible::Array.of(OmniService::Types::Symbol), reader: false
+  param :value_methods, OmniService::Types::Hash.map(OmniService::Types::Symbol, OmniService::Types::Symbol)
+
+  def initialize(*attributes, **kwargs)
+    super(attributes.flatten(1), kwargs)
+
+    define_pretty_print(@attributes, @value_methods)
+  end
+
+  private
+
+  def define_pretty_print(attributes, value_methods)
+    define_method(:pretty_print) do |pp|
+      object_group_method = self.class.name ? :object_group : :object_address_group
+      pp.public_send(object_group_method, self) do
+        pp.seplist(attributes, -> { pp.text ',' }) do |name|
+          pp.breakable ' '
+          pp.group(1) do
+            pp.text name.to_s
+            pp.text '='
+            pp.pp __send__(value_methods[name] || name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omni_service/namespace.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Scopes component execution under a namespace key.
+#
+# Behavior:
+# - Extracts params from params[namespace] (disable with shared_params: true)
+# - Merges context[namespace] into component context with priority
+# - Wraps returned context under namespace key
+# - Prefixes error paths with namespace
+#
+# @example Nested author creation
+#   # params: { title: 'Hello', author: { name: 'John', email: 'j@test.com' } }
+#   namespace(:author, create_author)
+#   # Inner receives: { name: 'John', email: 'j@test.com' }
+#   # Result context: { author: { author: <Author> } }
+#   # Error paths: [:author, :email] instead of [:email]
+#
+# @example Shared params for multiple processors
+#   parallel(
+#     namespace(:cache, warm_cache, shared_params: true),
+#     namespace(:search, index_search, shared_params: true)
+#   )
+#   # Both receive full params; results namespaced separately
+#
+# @example Sequential namespace accumulation
+#   sequence(
+#     namespace(:author, validate_author),  # => { author: { validated: true } }
+#     namespace(:author, create_author)     # => { author: { validated: true, author: <Author> } }
+#   )
+#
+class OmniService::Namespace
+  extend Dry::Initializer
+  include Dry::Monads[:result]
+  include Dry::Equalizer(:namespace, :component, :shared_params)
+  include OmniService::Inspect.new(:namespace, :component, :shared_params)
+  include OmniService::Strict
+
+  param :namespace, OmniService::Types::Symbol
+  param :component, OmniService::Types::Interface(:call)
+  option :shared_params, OmniService::Types::Bool, default: -> { false }
+
+  delegate :signature, to: :component_wrapper
+
+  def call(*params, **context)
+    inner_params = prepare_params(params)
+    inner_context = prepare_context(context)
+    inner_result = component_wrapper.call(*inner_params, **inner_context)
+
+    transform_result(inner_result, params:, context:, inner_context_keys: inner_context.keys)
+  end
+
+  private
+
+  def component_wrapper
+    @component_wrapper ||= OmniService::Component.wrap(component)
+  end
+
+  def transform_result(inner_result, params:, context:, inner_context_keys:)
+    merged_context = build_merged_context(inner_result, context:, inner_context_keys:)
+
+    if inner_result.success?
+      inner_result.merge(params:, context: merged_context)
+    else
+      inner_result.merge(params:, context: merged_context, errors: prefix_errors(inner_result.errors))
+    end
+  end
+
+  def build_merged_context(inner_result, context:, inner_context_keys:)
+    returned_keys = inner_result.context.keys - inner_context_keys
+    inner_returned_context = inner_result.context.slice(*returned_keys)
+
+    existing_namespaced = context[namespace].is_a?(Hash) ? context[namespace] : {}
+    new_namespaced = existing_namespaced.merge(inner_returned_context)
+
+    context.except(namespace).merge(wrap_context(new_namespaced))
+  end
+
+  def prepare_params(params)
+    return params if shared_params || params.empty?
+
+    params_count = component_wrapper.signature[0]
+    return params if params_count.zero?
+
+    params.each_with_index.map { |param, index| extract_namespaced_param(param, index, params_count) }
+  end
+
+  def extract_namespaced_param(param, index, params_count)
+    return param unless index < params_count && param.key?(namespace)
+
+    param[namespace] || {}
+  end
+
+  def prepare_context(context)
+    namespaced = context[namespace]
+    base = context.except(namespace)
+
+    namespaced.is_a?(Hash) ? base.merge(namespaced) : base
+  end
+
+  def wrap_context(inner_context)
+    return {} if inner_context.empty?
+
+    { namespace => inner_context }
+  end
+
+  def prefix_errors(errors)
+    errors.map do |error|
+      error.new(path: [namespace, *error.path])
+    end
+  end
+end