serviced 0.1.0

data/lib/serviced/flow.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Serviced
+  # Composes several steps into a single callable pipeline.
+  #
+  # A step is anything that responds to +call(context)+ and returns a
+  # {Serviced::Result}: usually a {Serviced::Service} subclass, but a lambda or
+  # any callable works too. Steps run in order, each receiving an immutable
+  # context hash. The first failing step halts the flow and its failure is
+  # returned. When every step succeeds, whatever hash each step returned as its
+  # success value is merged into the context, and the final context is returned
+  # as the success value.
+  #
+  #   class RegisterPatient < Serviced::Flow
+  #     transactional # wrap every step in one database transaction
+  #
+  #     step CreatePatient   # returns success(patient: patient)
+  #     step CreateChart     # reads :patient from the context
+  #     step SendWelcome
+  #   end
+  #
+  #   result = RegisterPatient.call(name: "Ada", age: 36)
+  #   result.value # => merged context hash of everything the steps produced
+  #
+  # A flow can also be built inline:
+  #
+  #   RegisterPatient = Serviced::Flow.define(transaction: true) do
+  #     step CreatePatient
+  #     step CreateChart
+  #   end
+  class Flow
+    include ResultHelpers
+
+    @steps = []
+    @transactional = false
+
+    class << self
+      # @return [Array<#call>] the steps registered on this flow
+      def steps
+        @steps ||= []
+      end
+
+      # Registers a step. Steps run in the order they are declared.
+      # @param callable [#call] a Service subclass, lambda, or any callable
+      #   that returns a Serviced::Result
+      def step(callable)
+        steps << callable
+      end
+
+      # Marks the flow as transactional: all steps run inside a single
+      # transaction that rolls back if any step fails or raises.
+      def transactional
+        @transactional = true
+      end
+
+      # @return [Boolean] whether the flow runs inside a transaction
+      def transactional?
+        @transactional
+      end
+
+      # Builds an anonymous flow subclass from a block.
+      # @param transaction [Boolean] whether to wrap the steps in a transaction
+      # @return [Class] a new Serviced::Flow subclass
+      def define(transaction: false, &block)
+        Class.new(self) do
+          transactional if transaction
+          class_eval(&block) if block
+        end
+      end
+
+      # Runs the flow.
+      # @param context [Hash] initial context
+      # @return [Serviced::Result]
+      def call(context = {})
+        new(context).call
+      end
+
+      private
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@steps, steps.dup)
+        subclass.instance_variable_set(:@transactional, transactional?)
+      end
+    end
+
+    # @param context [Hash] initial context passed to the first step
+    def initialize(context = {})
+      @context = normalize(context).freeze
+    end
+
+    # @return [Serviced::Result]
+    def call
+      self.class.transactional? ? within_transaction { run_steps } : run_steps
+    end
+
+    private
+
+    def run_steps
+      context = @context
+      self.class.steps.each do |step|
+        result = invoke(step, context)
+        return result if result.failure?
+
+        context = merge(context, result.value)
+      end
+
+      success(context)
+    end
+
+    def invoke(step, context)
+      result = step.call(context)
+      return result if result.is_a?(Result)
+
+      raise ResultTypeError,
+            "Flow step #{step_name(step)} must return a Serviced::Result, got #{result.class}"
+    end
+
+    def within_transaction
+      handler = Serviced.configuration.transaction_handler
+      if handler.nil?
+        raise MissingTransactionHandler,
+              "#{self.class} is transactional but no transaction handler is configured. " \
+              "Load ActiveRecord or set Serviced.configuration.transaction_handler."
+      end
+
+      result = nil
+      begin
+        handler.call do
+          result = yield
+          raise Rollback if result.failure?
+        end
+      rescue Rollback
+        # Expected: a step failed, the transaction rolled back, and +result+
+        # already holds that failure.
+      end
+      result
+    end
+
+    def merge(context, value)
+      return context unless value.is_a?(Hash)
+
+      context.merge(normalize(value)).freeze
+    end
+
+    def normalize(hash)
+      (hash || {}).to_h.transform_keys(&:to_sym)
+    end
+
+    def step_name(step)
+      step.respond_to?(:name) ? step.name : step.class.name
+    end
+  end
+end

data/lib/serviced/query.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Serviced
+  # Base class for query objects: a named home for a complex read.
+  #
+  # A query has the same typed, immutable inputs as a {Serviced::Service} (see
+  # {Serviced::Typed}), but instead of a Result it returns whatever #call
+  # returns, usually an +ActiveRecord::Relation+. Returning a relation keeps the
+  # result composable: callers can still paginate, add includes, or chain more
+  # scopes. A service then consumes the query and wraps its result in a Result.
+  #
+  #   class EnrolledPatientsQuery < Serviced::Query
+  #     attribute :clinic
+  #     attribute :program_external_id, :string
+  #     attribute :sort_direction, :string, default: "asc"
+  #
+  #     validates :sort_direction, inclusion: { in: %w[asc desc] }
+  #
+  #     def call
+  #       clinic.patients
+  #             .where("enrolled_in(?)", program_external_id)
+  #             .order("enrolled_at #{sort_direction}")
+  #     end
+  #   end
+  #
+  #   relation = EnrolledPatientsQuery.call(clinic:, program_external_id: "cardio")
+  #   relation.page(params[:page]) # still a relation
+  #
+  # Invalid inputs raise {Serviced::InvalidQuery} (a query has no failure
+  # channel, so bad input is treated as a programming error).
+  #
+  # The SQL helpers (#quote, #count_of, ...) require ActiveRecord at runtime.
+  class Query
+    include Typed
+
+    class << self
+      # Builds the query, validates it, and runs #call.
+      # @param attributes [Hash] input values; unknown keys are ignored
+      # @return [Object] whatever #call returns (typically an ActiveRecord::Relation)
+      # @raise [Serviced::InvalidQuery] if inputs fail validation
+      def call(attributes = {})
+        query = new(attributes)
+        raise InvalidQuery, query.errors if query.invalid?
+
+        query.call
+      end
+    end
+
+    # The query body. Subclasses must implement it and return a relation (to
+    # stay composable) or a materialized value.
+    # @return [ActiveRecord::Relation, Object]
+    def call
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+
+    private
+
+    def connection
+      ActiveRecord::Base.connection
+    end
+
+    # Quotes a value for safe interpolation into raw SQL.
+    def quote(value)
+      connection.quote(value)
+    end
+
+    # Quotes a column or table name for safe interpolation into raw SQL.
+    def quote_column(name)
+      connection.quote_column_name(name)
+    end
+
+    # Builds a sanitized SQL fragment from a statement and bind values.
+    #   sanitize("state = ? AND age > ?", "active", 18)
+    def sanitize(statement, *binds)
+      ActiveRecord::Base.sanitize_sql_array([statement, *binds])
+    end
+
+    # Counts the rows of a relation without loading them, wrapping it in a
+    # subquery. Replaces a hand-rolled "SELECT COUNT(*) FROM (...)" idiom.
+    # @param relation [ActiveRecord::Relation]
+    # @param cte [String] optional leading CTE (e.g. "WITH foo AS (...)")
+    # @return [Integer]
+    def count_of(relation, cte: "")
+      sql = "#{cte} SELECT COUNT(*) FROM (#{relation.to_sql}) serviced_count".strip
+      connection.select_value(sql).to_i
+    end
+  end
+end

data/lib/serviced/result.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Serviced
+  # Outcome of a service or flow. Abstract: instances are always either a
+  # {Serviced::Success} or a {Serviced::Failure}. Results are frozen and
+  # therefore immutable.
+  #
+  # Consume a result through predicates, callbacks, railway chaining, or
+  # pattern matching:
+  #
+  #   result = CreatePatient.call(name: "Ada", age: 36)
+  #
+  #   result.success?                 # => true / false
+  #   result.value                    # success payload (nil on failure)
+  #
+  #   result
+  #     .on_success { |patient| render json: patient }
+  #     .on_failure { |failure| render json: { error: failure.message } }
+  #
+  #   case result
+  #   in Serviced::Success(value:)      then value
+  #   in Serviced::Failure(reason:)     then reason
+  #   end
+  class Result
+    # @return [Boolean] whether the operation succeeded.
+    def success?
+      raise NotImplementedError, "#{self.class} must implement #success?"
+    end
+
+    # @return [Boolean] whether the operation failed.
+    def failure?
+      !success?
+    end
+
+    # The success payload. Always nil for a failure.
+    # @return [Object, nil]
+    def value
+      nil
+    end
+
+    # Runs the block with the success value when successful. Returns self so
+    # calls can be chained with {#on_failure}.
+    # @yieldparam value [Object] the success payload
+    # @return [Serviced::Result] self
+    def on_success
+      yield(value) if success? && block_given?
+      self
+    end
+
+    # Runs the block with the failure when failed. Returns self so calls can be
+    # chained with {#on_success}.
+    # @yieldparam failure [Serviced::Failure] the failure itself
+    # @return [Serviced::Result] self
+    def on_failure
+      yield(self) if failure? && block_given?
+      self
+    end
+
+    # Railway-oriented chaining: runs the block only on success and returns the
+    # Result it produces; short-circuits (returns self) on failure. The block
+    # must return a Serviced::Result.
+    # @yieldparam value [Object] the success payload
+    # @return [Serviced::Result]
+    def and_then
+      return self unless success?
+
+      result = yield(value)
+      unless result.is_a?(Result)
+        raise ResultTypeError, "#and_then block must return a Serviced::Result, got #{result.class}"
+      end
+
+      result
+    end
+
+    # Transforms a success value into a new Success; leaves a failure untouched.
+    # @yieldparam value [Object] the success payload
+    # @return [Serviced::Result]
+    def map
+      return self unless success?
+
+      Success.new(yield(value))
+    end
+  end
+
+  # A successful outcome carrying a payload.
+  class Success < Result
+    # @return [Object, nil] the success payload
+    attr_reader :value
+
+    # @param value [Object, nil] the payload the caller cares about
+    def initialize(value = nil)
+      super()
+      @value = value
+      freeze
+    end
+
+    def success?
+      true
+    end
+
+    # @return [Object, nil] the payload (never raises for a success)
+    def value!
+      value
+    end
+
+    def deconstruct
+      [value]
+    end
+
+    def deconstruct_keys(_keys)
+      { value: value }
+    end
+  end
+
+  # A failed outcome. Carries a machine-readable +reason+ for branching, an
+  # optional human-readable +message+, and an optional +error+ payload (for
+  # example an exception or an ActiveModel::Errors object).
+  class Failure < Result
+    # @return [Symbol] machine-readable reason, suitable for case/when branching
+    attr_reader :reason
+
+    # @return [String, nil] human-readable description
+    attr_reader :message
+
+    # @return [Object, nil] structured error payload (exception, error object, details)
+    attr_reader :error
+
+    # @param reason [Symbol] machine-readable reason (defaults to :error)
+    # @param message [String, nil] human-readable description
+    # @param error [Object, nil] structured error payload
+    def initialize(reason = :error, message = nil, error: nil)
+      super()
+      @reason = reason
+      @message = message
+      @error = error
+      freeze
+    end
+
+    def success?
+      false
+    end
+
+    # Always raises: a failure has no value to unwrap.
+    # @raise [Serviced::InvalidResultAccess]
+    def value!
+      raise InvalidResultAccess,
+            "Called #value! on a Failure (reason: #{reason.inspect}, message: #{message.inspect})"
+    end
+
+    def deconstruct
+      [reason, message]
+    end
+
+    def deconstruct_keys(_keys)
+      { reason: reason, message: message, error: error }
+    end
+  end
+end

data/lib/serviced/result_helpers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Serviced
+  # Private helpers shared by services and flows for building results, so the
+  # construction of Success/Failure lives in one place.
+  module ResultHelpers
+    private
+
+    # Builds a success result. Pass a hash to contribute keys to a flow context,
+    # for example +success(patient: patient)+.
+    # @param value [Object, nil] the payload
+    # @return [Serviced::Success]
+    def success(value = nil)
+      Success.new(value)
+    end
+
+    # Builds a failure result.
+    # @param reason [Symbol] machine-readable reason for branching
+    # @param message [String, nil] human-readable description
+    # @param error [Object, nil] structured error payload
+    # @return [Serviced::Failure]
+    def failure(reason = :error, message = nil, error: nil)
+      Failure.new(reason, message, error: error)
+    end
+  end
+end

data/lib/serviced/service.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Serviced
+  # Base class for service objects.
+  #
+  # A service declares its inputs as typed attributes (see {Serviced::Typed}),
+  # which are coerced on assignment and read-only afterwards. Inputs can be
+  # validated with the full ActiveModel validation DSL. Calling a service always
+  # returns a {Serviced::Result}.
+  #
+  #   class CreatePatient < Serviced::Service
+  #     attribute :name,   :string
+  #     attribute :age,    :integer
+  #     attribute :active, :boolean, default: true
+  #     attribute :clinic # untyped: accepts any object
+  #
+  #     validates :name, presence: true
+  #     validates :age, numericality: { greater_than: 0 }
+  #
+  #     def call
+  #       patient = Patient.create!(name:, age:, active:)
+  #       success(patient)
+  #     rescue ActiveRecord::RecordInvalid => e
+  #       failure(:not_created, e.message, error: e)
+  #     end
+  #   end
+  #
+  #   result = CreatePatient.call(name: "Ada", age: 36)
+  #   result.success? # => true
+  #   result.value    # => #<Patient ...>
+  #
+  # Invalid inputs short-circuit to +failure(:invalid)+ without running #call,
+  # exposing the ActiveModel::Errors object through +result.error+.
+  class Service
+    include Typed
+    include ResultHelpers
+
+    class << self
+      # Builds the service, validates it, and runs #call.
+      #
+      # Unknown keys are ignored so a service can be dropped into a {Flow}
+      # without matching the exact shape of the flow context.
+      #
+      # @param attributes [Hash] input values
+      # @return [Serviced::Result]
+      # @raise [Serviced::ResultTypeError] if #call returns a non-Result
+      def call(attributes = {})
+        service = new(attributes)
+        return service.__send__(:invalid_result) if service.invalid?
+
+        result = service.call
+        unless result.is_a?(Result)
+          raise ResultTypeError, "#{self}#call must return a Serviced::Result, got #{result.class}"
+        end
+
+        result
+      end
+    end
+
+    # The business logic. Subclasses must implement it and return a
+    # {Serviced::Result} (use the +success+ / +failure+ helpers).
+    # @return [Serviced::Result]
+    def call
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+
+    private
+
+    def invalid_result
+      failure(:invalid, "Validation failed: #{Serviced.error_summary(errors)}", error: errors)
+    end
+  end
+end

data/lib/serviced/typed.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_model"
+
+module Serviced
+  # Shared foundation for typed, immutable, validatable inputs. Included by both
+  # {Serviced::Service} and {Serviced::Query}, and usable on its own for any
+  # plain value object that wants the same contract.
+  #
+  #   class DateRange
+  #     include Serviced::Typed
+  #     attribute :from, :date
+  #     attribute :to,   :date
+  #     validates :from, :to, presence: true
+  #   end
+  #
+  # Attributes are declared with the ActiveModel::Attributes DSL, so they are
+  # coerced to the declared type. Their writers are made private, so an instance
+  # cannot be rebound once built. Unknown keys are ignored, which lets these
+  # objects be fed from a wider hash (for example a {Serviced::Flow} context)
+  # without raising.
+  #
+  # Inputs are isolated by default: at construction each value is captured as an
+  # immutable snapshot (see {Serviced.snapshot}). Arrays, hashes, sets and
+  # strings are deep-copied and deep-frozen, so neither side can mutate the
+  # other. Objects with identity (ActiveRecord records and the like) are shared
+  # by reference and left alone, because a deep copy of a record is a different,
+  # non-persisted object. Pass +isolate: false+ to share a value by reference,
+  # for example a mutable accumulator you deliberately want the caller to see:
+  #
+  #   attribute :filters             # isolated snapshot (default)
+  #   attribute :sink, isolate: false # shared by reference
+  module Typed
+    extend ActiveSupport::Concern
+
+    include ActiveModel::API
+    include ActiveModel::Attributes
+
+    # @param attributes [Hash] input values; unknown keys are ignored
+    def initialize(attributes = {})
+      super()
+      assign_typed_attributes(attributes)
+      capture_isolated_snapshots
+    end
+
+    private
+
+    def assign_typed_attributes(attributes)
+      return if attributes.nil?
+
+      permitted = attributes.to_h.transform_keys(&:to_sym)
+      self.class.attribute_names.each do |name|
+        key = name.to_sym
+        __send__(:"#{name}=", permitted[key]) if permitted.key?(key)
+      end
+    end
+
+    # Forces each isolated attribute to snapshot its value now, so isolation
+    # holds against mutations made between construction and first read.
+    def capture_isolated_snapshots
+      self.class.isolated_attribute_names.each { |name| __send__(name) }
+    end
+
+    class_methods do
+      # @return [Array<String>] names of attributes captured as isolated snapshots
+      def isolated_attribute_names
+        @isolated_attribute_names ||=
+          superclass.respond_to?(:isolated_attribute_names) ? superclass.isolated_attribute_names.dup : []
+      end
+
+      # Declares a typed, read-only attribute. Same arguments as
+      # ActiveModel::Attributes.attribute, plus +isolate:+.
+      #
+      # @param name [Symbol] attribute name
+      # @param type [Symbol, ActiveModel::Type::Value, nil] the cast type
+      # @param isolate [Boolean] capture an immutable snapshot of the value at
+      #   construction (default); pass +false+ to share it by reference
+      # @param options [Hash] forwarded to ActiveModel (e.g. +default:+)
+      def attribute(name, type = nil, isolate: true, **options)
+        if type.nil?
+          super(name, **options)
+        else
+          super(name, type, **options)
+        end
+        private(:"#{name}=")
+        return unless isolate
+
+        isolated_attribute_names << name.to_s
+        define_isolated_reader(name)
+      end
+
+      private
+
+      def define_isolated_reader(name)
+        define_method(name) do
+          ivar = :"@__isolated_#{name}"
+          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+          instance_variable_set(ivar, Serviced.snapshot(super()))
+        end
+      end
+    end
+  end
+end

data/lib/serviced/version.rb

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

data/lib/serviced.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "serviced/version"
+require_relative "serviced/errors"
+require_relative "serviced/result"
+require_relative "serviced/result_helpers"
+require_relative "serviced/configuration"
+require_relative "serviced/typed"
+require_relative "serviced/service"
+require_relative "serviced/query"
+require_relative "serviced/flow"
+
+# Serviced provides small, explicit service objects: typed and immutable
+# inputs, a mandatory Success/Failure return value, and composable flows with
+# optional transactions.
+#
+# See {Serviced::Service} and {Serviced::Flow}.
+module Serviced
+  class << self
+    # @return [Serviced::Configuration] the current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for mutation.
+    # @yieldparam config [Serviced::Configuration]
+    def configure
+      yield(configuration)
+    end
+
+    # Resets configuration to defaults. Primarily useful in test suites.
+    # @return [Serviced::Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Renders an ActiveModel::Errors into a short human string. Falls back to
+    # the attribute names when full messages cannot be built: an anonymous
+    # class has no model_name, which ActiveModel needs to humanize messages.
+    # Building an error message must never itself raise.
+    # @param errors [ActiveModel::Errors]
+    # @return [String]
+    def error_summary(errors)
+      errors.full_messages.join(", ")
+    rescue StandardError
+      errors.attribute_names.join(", ")
+    end
+
+    # Returns an immutable snapshot of a value-like input. Arrays, hashes, sets
+    # and strings are deep-copied and frozen, so the result is isolated from the
+    # caller and cannot be mutated. Objects with identity (ActiveRecord records
+    # and other non-data objects) are returned by reference, unfrozen: a deep
+    # copy of a record is a different, non-persisted object, and freezing one in
+    # place would corrupt the caller's copy. Scalars are already immutable.
+    # @param value [Object]
+    # @return [Object] a frozen snapshot for value-like data, else the value itself
+    def snapshot(value)
+      case value
+      when Array then value.map { |element| snapshot(element) }.freeze
+      when Set then Set.new(value.map { |element| snapshot(element) }).freeze
+      when Hash then snapshot_hash(value)
+      when String then snapshot_string(value)
+      else value
+      end
+    end
+
+    private
+
+    def snapshot_hash(hash)
+      hash.each_with_object({}) { |(key, value), copy| copy[snapshot(key)] = snapshot(value) }.freeze
+    end
+
+    def snapshot_string(string)
+      string.frozen? ? string : string.dup.freeze
+    end
+  end
+end