better_service 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 622ac1a705ab117672d0e9c4896e65b66585c747023d1e00b34824e9c35606a0
-  data.tar.gz: f4c6f5b6ae7baaa3f61eeb123d4a2a493a7c8acc2ff835c6891396ed543efa1c
+  metadata.gz: 6ce89074c072a76a05a669dc079d3d4fbf1ba99a7f758f4ae45c9640b335c4c4
+  data.tar.gz: 34bcc32228b8c358f21f4713e783ef3f17e7e38047ab0116abad5a6e0d2a1aec
 SHA512:
-  metadata.gz: d4f06ae88607c9d4b6eec865811abbba0f80403914fbcac556ad3949a395ff0b43e16e6663c652959cc950fcb89d64be427eb6e8c20b19ed0aa6b1771012e7b0
-  data.tar.gz: d1a69946471e0e2f5bd7067889c4f675d0ea94a198d69f9e877283fa5166664f49283a45fd52f282288b690670a6d095f562935f3503c86dce81633d03858e74
+  metadata.gz: 1479b3e94a12463614adb2022aa8a8d725939224715c5f5ae876be036f96da3c3a63171d6ca1cda4dc10ac3c6e97f98a615a45b952a9441066f24f064161521d
+  data.tar.gz: 2a985c1abfdbb8dc352fdc34351439f35bf0f09ed8784593e04e113a3bd2a38c1d172a3fb1f69836ab24cfd25881b59b52a5c54e5a4a3a6c8b8eacb1fcdb31f8

data/lib/better_service/cache_service.rb

@@ -7,6 +7,9 @@ module BetterService
   # the Cacheable concern. It provides methods to invalidate cache keys
   # for specific users, contexts, or globally.
   #
+  # Supports cascading invalidation through INVALIDATION_MAP - when a context
+  # is invalidated, all related contexts are also invalidated automatically.
+  #
   # @example Invalidate cache for a specific context and user
   #   BetterService::CacheService.invalidate_for_context(current_user, "products")
   #
@@ -15,61 +18,169 @@ module BetterService
   #
   # @example Invalidate all cache for a user
   #   BetterService::CacheService.invalidate_for_user(current_user)
+  #
+  # @example Configure invalidation map
+  #   BetterService::CacheService.configure_invalidation_map(
+  #     'products' => %w[products inventory reports],
+  #     'orders' => %w[orders products reports]
+  #   )
   class CacheService
+    # Default invalidation map - can be customized via configure_invalidation_map
+    # Maps primary context to array of contexts that should be invalidated together
+    #
+    # @return [Hash<String, Array<String>>] Context invalidation mappings
+    @invalidation_map = {}
+
     class << self
+      # Get the current invalidation map
+      #
+      # @return [Hash<String, Array<String>>] Current invalidation mappings
+      attr_reader :invalidation_map
+
+      # Configure the invalidation map for cascading cache invalidation
+      #
+      # The invalidation map defines which cache contexts should be invalidated
+      # together. When a primary context is invalidated, all related contexts
+      # in the map are also invalidated.
+      #
+      # @param map [Hash<String, Array<String>>] Invalidation mappings
+      # @return [void]
+      #
+      # @example Configure invalidation relationships
+      #   BetterService::CacheService.configure_invalidation_map(
+      #     'products' => %w[products inventory reports],
+      #     'orders' => %w[orders products reports],
+      #     'users' => %w[users orders reports],
+      #     'categories' => %w[categories products reports],
+      #     'inventory' => %w[inventory products reports]
+      #   )
+      def configure_invalidation_map(map)
+        @invalidation_map = map.transform_keys(&:to_s).transform_values do |contexts|
+          Array(contexts).map(&:to_s)
+        end.freeze
+      end
+
+      # Add entries to the invalidation map without replacing existing ones
+      #
+      # @param entries [Hash<String, Array<String>>] New invalidation mappings to add
+      # @return [void]
+      #
+      # @example Add new context invalidation rules
+      #   BetterService::CacheService.add_invalidation_rules(
+      #     'payments' => %w[payments statistics invoices]
+      #   )
+      def add_invalidation_rules(entries)
+        new_entries = entries.transform_keys(&:to_s).transform_values do |contexts|
+          Array(contexts).map(&:to_s)
+        end
+        @invalidation_map = (@invalidation_map || {}).merge(new_entries).freeze
+      end
+
+      # Get all contexts that should be invalidated for a given context
+      #
+      # If the context exists in the invalidation map, returns all mapped contexts.
+      # Otherwise, returns an array containing just the original context.
+      #
+      # @param context [String, Symbol] The primary context
+      # @return [Array<String>] All contexts to invalidate
+      #
+      # @example
+      #   contexts_for('products')  # => ['products', 'inventory', 'reports']
+      #   contexts_for('unknown')   # => ['unknown']
+      def contexts_to_invalidate(context)
+        context_str = context.to_s
+        (@invalidation_map || {})[context_str] || [context_str]
+      end
+
       # Invalidate cache for a specific context and user
       #
       # Deletes all cache keys that match the pattern for the given user and context.
+      # Uses cascading invalidation - if the context exists in the invalidation map,
+      # all related contexts will also be invalidated.
+      #
       # This is useful when data changes that affects a specific user's cached results.
       #
       # @param user [Object] The user whose cache should be invalidated
       # @param context [String] The context name (e.g., "products", "sidebar")
       # @param async [Boolean] Whether to perform invalidation asynchronously
+      # @param cascade [Boolean] Whether to use cascading invalidation (default: true)
       # @return [Integer] Number of keys deleted (if supported by cache store)
       #
-      # @example
+      # @example Basic invalidation
       #   # After creating a product, invalidate products cache for user
       #   BetterService::CacheService.invalidate_for_context(user, "products")
-      def invalidate_for_context(user, context, async: false)
+      #
+      # @example With cascading (if map configured for orders -> [orders, products, reports])
+      #   BetterService::CacheService.invalidate_for_context(user, "orders")
+      #   # Invalidates: orders, products, reports caches
+      #
+      # @example Without cascading
+      #   BetterService::CacheService.invalidate_for_context(user, "orders", cascade: false)
+      #   # Invalidates: only orders cache
+      def invalidate_for_context(user, context, async: false, cascade: true)
         return 0 unless user && context && !context.to_s.strip.empty?
 
-        pattern = build_user_context_pattern(user, context)
+        # Get all contexts to invalidate (cascading or single)
+        contexts = cascade ? contexts_to_invalidate(context) : [context.to_s]
+        total_deleted = 0
 
-        if async
-          invalidate_async(pattern)
-          0
-        else
-          result = delete_matched(pattern)
-          # Ensure we return Integer, not Array
-          result.is_a?(Array) ? result.size : (result || 0)
+        contexts.each do |ctx|
+          pattern = build_user_context_pattern(user, ctx)
+
+          if async
+            invalidate_async(pattern)
+          else
+            result = delete_matched(pattern)
+            count = result.is_a?(Array) ? result.size : (result || 0)
+            total_deleted += count
+          end
         end
+
+        log_cascading_invalidation(context, contexts) if cascade && contexts.size > 1
+        total_deleted
       end
 
       # Invalidate cache globally for a context
       #
       # Deletes all cache keys for the given context across all users.
+      # Uses cascading invalidation - if the context exists in the invalidation map,
+      # all related contexts will also be invalidated.
+      #
       # This is useful when data changes that affects everyone (e.g., global settings).
       #
       # @param context [String] The context name
       # @param async [Boolean] Whether to perform invalidation asynchronously
+      # @param cascade [Boolean] Whether to use cascading invalidation (default: true)
       # @return [Integer] Number of keys deleted (if supported by cache store)
       #
-      # @example
+      # @example Basic global invalidation
       #   # After updating global sidebar settings
       #   BetterService::CacheService.invalidate_global("sidebar")
-      def invalidate_global(context, async: false)
+      #
+      # @example With cascading
+      #   BetterService::CacheService.invalidate_global("orders")
+      #   # Invalidates: orders, products, reports caches globally
+      def invalidate_global(context, async: false, cascade: true)
         return 0 unless context && !context.to_s.strip.empty?
 
-        pattern = build_global_context_pattern(context)
+        # Get all contexts to invalidate (cascading or single)
+        contexts = cascade ? contexts_to_invalidate(context) : [context.to_s]
+        total_deleted = 0
 
-        if async
-          invalidate_async(pattern)
-          0
-        else
-          result = delete_matched(pattern)
-          # Ensure we return Integer, not Array
-          result.is_a?(Array) ? result.size : (result || 0)
+        contexts.each do |ctx|
+          pattern = build_global_context_pattern(ctx)
+
+          if async
+            invalidate_async(pattern)
+          else
+            result = delete_matched(pattern)
+            count = result.is_a?(Array) ? result.size : (result || 0)
+            total_deleted += count
+          end
         end
+
+        log_cascading_invalidation(context, contexts, global: true) if cascade && contexts.size > 1
+        total_deleted
       end
 
       # Invalidate all cache for a specific user
@@ -175,7 +286,9 @@ module BetterService
         {
           cache_store: Rails.cache.class.name,
           supports_pattern_deletion: supports_delete_matched?,
-          supports_async: defined?(ActiveJob) ? true : false
+          supports_async: defined?(ActiveJob) ? true : false,
+          invalidation_map_configured: (@invalidation_map || {}).any?,
+          invalidation_map_contexts: (@invalidation_map || {}).keys
         }
       end
 
@@ -288,6 +401,20 @@ module BetterService
 
         Rails.logger.warn "[BetterService::CacheService] #{message}"
       end
+
+      # Log cascading invalidation
+      #
+      # @param primary_context [String] The primary context that triggered invalidation
+      # @param all_contexts [Array<String>] All contexts that were invalidated
+      # @param global [Boolean] Whether this was a global invalidation
+      # @return [void]
+      def log_cascading_invalidation(primary_context, all_contexts, global: false)
+        return unless defined?(Rails) && Rails.logger
+
+        scope = global ? "globally" : "for user"
+        Rails.logger.info "[BetterService::CacheService] Cascading invalidation #{scope}: " \
+                          "'#{primary_context}' -> [#{all_contexts.join(', ')}]"
+      end
     end
 
     # ActiveJob for async cache invalidation

data/lib/better_service/concerns/serviceable/repository_aware.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Serviceable
+      # RepositoryAware - DSL for declaring repository dependencies in services
+      #
+      # This concern provides a clean way to declare repository dependencies
+      # in service classes, promoting the repository pattern and enforcing
+      # separation between business logic and data access.
+      #
+      # @example Basic usage
+      #   class Products::CreateService < BetterService::Services::CreateService
+      #     include BetterService::Concerns::Serviceable::RepositoryAware
+      #
+      #     repository :product
+      #
+      #     process_with do |data|
+      #       { resource: product_repository.create!(params) }
+      #     end
+      #   end
+      #
+      # @example With custom class name
+      #   class Bookings::AcceptService < BetterService::Services::ActionService
+      #     include BetterService::Concerns::Serviceable::RepositoryAware
+      #
+      #     repository :booking, class_name: "Bookings::BookingRepository"
+      #     repository :user, class_name: "Users::UserRepository", as: :user_repo
+      #
+      #     search_with do
+      #       { booking: booking_repository.search({ id_eq: params[:id] }, limit: 1) }
+      #     end
+      #   end
+      #
+      # @example Multiple repositories shorthand
+      #   class Dashboard::IndexService < BetterService::Services::IndexService
+      #     include BetterService::Concerns::Serviceable::RepositoryAware
+      #
+      #     repositories :user, :booking, :payment
+      #   end
+      #
+      module RepositoryAware
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Declare a repository dependency
+          #
+          # Creates a memoized private accessor method for the repository.
+          #
+          # @param name [Symbol] Base name for the repository
+          # @param class_name [String, nil] Full class name of the repository
+          #   If nil, derives from name: :product -> "ProductRepository"
+          # @param as [Symbol, nil] Custom accessor name
+          #   If nil, uses "#{name}_repository"
+          # @return [void]
+          #
+          # @example Standard naming
+          #   repository :product  # -> product_repository -> ProductRepository
+          #
+          # @example Custom class
+          #   repository :booking, class_name: "Bookings::BookingRepository"
+          #
+          # @example Custom accessor
+          #   repository :user, as: :users  # -> users -> UserRepository
+          def repository(name, class_name: nil, as: nil)
+            accessor_name = as || "#{name}_repository"
+            repo_class_name = class_name || "#{name.to_s.camelize}Repository"
+
+            define_method(accessor_name) do
+              ivar = "@#{accessor_name}"
+              instance_variable_get(ivar) || begin
+                klass = repo_class_name.constantize
+                instance_variable_set(ivar, klass.new)
+              end
+            end
+
+            private accessor_name
+          end
+
+          # Declare multiple repository dependencies
+          #
+          # Shorthand for declaring multiple repositories with standard naming.
+          #
+          # @param names [Array<Symbol>] Repository names
+          # @return [void]
+          #
+          # @example
+          #   repositories :user, :booking, :payment
+          #   # Equivalent to:
+          #   # repository :user
+          #   # repository :booking
+          #   # repository :payment
+          def repositories(*names)
+            names.each { |name| repository(name) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_service/concerns/serviceable/transactional.rb

@@ -3,49 +3,54 @@
 module BetterService
   module Concerns
     module Serviceable
-    module Transactional
-      extend ActiveSupport::Concern
-
-      included do
-        class_attribute :_with_transaction, default: false
-      end
-
-      # Hook for prepend (same as included but triggered by prepend)
-      def self.prepended(base)
-        base.class_attribute :_with_transaction, default: false
-        base.extend(ClassMethods)
-      end
-
-      module ClassMethods
-      # Enable or disable database transactions for this service
+      # Provides transaction wrapping for service execution
       #
-      # @param value [Boolean] whether to wrap process in a transaction
+      # This concern is PREPENDED (not included) to Services::Base to wrap
+      # the process method in a database transaction when enabled.
       #
-      # @example Enable transactions
+      # @example Enable transactions in a service
       #   class Booking::CreateService < BetterService::CreateService
       #     with_transaction true
       #   end
-      #
-      # @example Disable transactions
-      #   class Booking::ImportService < BetterService::CreateService
-      #     with_transaction false  # Disable inherited transaction
-      #   end
-        def with_transaction(value)
-          self._with_transaction = value
+      module Transactional
+        extend ActiveSupport::Concern
+
+        # Hook for prepend - sets up class attributes and class methods
+        def self.prepended(base)
+          base.class_attribute :_with_transaction, default: false
+          base.extend(ClassMethods)
         end
-      end
 
-      # Override process to wrap in transaction if enabled
-      def process(data)
-        return super(data) unless self.class._with_transaction
+        module ClassMethods
+          # Enable or disable database transactions for this service
+          #
+          # @param value [Boolean] whether to wrap process in a transaction
+          #
+          # @example Enable transactions
+          #   class Booking::CreateService < BetterService::CreateService
+          #     with_transaction true
+          #   end
+          #
+          # @example Disable transactions
+          #   class Booking::ImportService < BetterService::CreateService
+          #     with_transaction false  # Disable inherited transaction
+          #   end
+          def with_transaction(value)
+            self._with_transaction = value
+          end
+        end
+
+        # Override process to wrap in transaction if enabled
+        def process(data)
+          return super(data) unless self.class._with_transaction
 
-        result = nil
-        ActiveRecord::Base.transaction do
-          result = super(data)
+          result = nil
+          ActiveRecord::Base.transaction do
+            result = super(data)
+          end
+          result
         end
-        result
       end
     end
-    end
   end
 end

data/lib/better_service/configuration.rb

@@ -11,6 +11,13 @@ module BetterService
   #     config.instrumentation_enabled = true
   #     config.instrumentation_include_args = false
   #     config.instrumentation_excluded_services = ["HealthCheckService"]
+  #
+  #     # Cache invalidation map for cascading cache invalidation
+  #     config.cache_invalidation_map = {
+  #       'products' => %w[products inventory reports],
+  #       'orders' => %w[orders products reports],
+  #       'users' => %w[users orders reports]
+  #     }
   #   end
   class Configuration
     # Enable/disable instrumentation globally
@@ -65,6 +72,31 @@ module BetterService
     # @return [Boolean] Default: false
     attr_accessor :stats_subscriber_enabled
 
+    # Cache invalidation map for cascading cache invalidation
+    #
+    # When a context is invalidated, all related contexts in the map
+    # are also invalidated automatically.
+    #
+    # @return [Hash<String, Array<String>>] Default: {}
+    #
+    # @example
+    #   config.cache_invalidation_map = {
+    #     'products' => %w[products inventory reports],
+    #     'orders' => %w[orders products reports]
+    #   }
+    attr_reader :cache_invalidation_map
+
+    # Set the cache invalidation map
+    #
+    # Automatically configures CacheService with the provided map.
+    #
+    # @param map [Hash<String, Array<String>>] Invalidation mappings
+    # @return [void]
+    def cache_invalidation_map=(map)
+      @cache_invalidation_map = map
+      CacheService.configure_invalidation_map(map) if map
+    end
+
     def initialize
       # Instrumentation defaults
       @instrumentation_enabled = true
@@ -76,6 +108,9 @@ module BetterService
       @log_subscriber_enabled = false
       @log_subscriber_level = :info
       @stats_subscriber_enabled = false
+
+      # Cache defaults
+      @cache_invalidation_map = {}
     end
   end
 

data/lib/better_service/repository/base_repository.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Repository
+    # BaseRepository - Generic repository pattern for data access
+    #
+    # Provides a clean abstraction layer between services and ActiveRecord models.
+    # Repositories handle all database queries using predicates-based search,
+    # enforcing separation of concerns and enabling easier testing.
+    #
+    # @example Basic usage
+    #   class ProductRepository < BetterService::Repository::BaseRepository
+    #     def initialize(model_class = Product)
+    #       super
+    #     end
+    #   end
+    #
+    #   repo = ProductRepository.new
+    #   products = repo.search({ status_eq: 'active' }, includes: [:category])
+    #
+    # @example With predicates
+    #   repo.search({
+    #     user_id_eq: user.id,
+    #     status_in: ['pending', 'confirmed'],
+    #     created_at_gteq: 1.week.ago
+    #   }, order: 'created_at DESC', per_page: 20)
+    #
+    class BaseRepository
+      attr_reader :model
+
+      # Initialize repository with a model class
+      #
+      # @param model_class [Class, nil] ActiveRecord model class
+      #   If nil, derives class name from repository name
+      def initialize(model_class = nil)
+        @model = model_class || derive_model_class
+      end
+
+      # Search records using predicates
+      #
+      # Supports flexible querying through predicates hash that gets
+      # translated to ActiveRecord scopes via model's Searchable concern.
+      #
+      # @param predicates [Hash] Search predicates (e.g., { status_eq: 'active' })
+      # @param page [Integer] Page number for pagination (default: 1)
+      # @param per_page [Integer] Records per page (default: 20)
+      # @param includes [Array] Associations to eager load
+      # @param joins [Array] Associations to join
+      # @param order [String, Hash, nil] Order clause
+      # @param order_scope [Hash, nil] Named scope for ordering { field:, direction: }
+      # @param limit [Integer, Symbol, nil] Limit results
+      #   - 1: returns single record (first)
+      #   - Integer > 1: limit to N records
+      #   - nil: no limit (returns all)
+      #   - :default: apply pagination
+      # @return [ActiveRecord::Relation, Object, nil] Query result
+      #
+      # @example Basic search
+      #   search({ status_eq: 'active' })
+      #
+      # @example With pagination
+      #   search({ user_id_eq: 1 }, page: 2, per_page: 25)
+      #
+      # @example Single record
+      #   search({ id_eq: 123 }, limit: 1)
+      #
+      # @example With eager loading
+      #   search({}, includes: [:user, :comments], order: 'created_at DESC')
+      def search(predicates = {}, page: 1, per_page: 20, includes: [],
+                 joins: [], order: nil, order_scope: nil, limit: :default)
+        cleaned_predicates = (predicates || {}).compact
+
+        scope = build_base_scope(cleaned_predicates)
+        scope = apply_joins(scope, joins)
+        scope = apply_includes(scope, includes)
+        scope = apply_ordering(scope, order, order_scope)
+        apply_limit_or_pagination(scope, limit, page, per_page)
+      end
+
+      # Delegate basic ActiveRecord methods to model
+      delegate :find, :find_by, :where, :all, :count, :exists?, to: :model
+
+      # Build a new unsaved record
+      #
+      # @param attributes [Hash] Attributes for the new record
+      # @return [ActiveRecord::Base] Unsaved model instance
+      def build(attributes = {})
+        model.new(attributes)
+      end
+      alias new build
+
+      # Create a new record (may return invalid record)
+      #
+      # @param attributes [Hash] Attributes for the new record
+      # @return [ActiveRecord::Base] Created model instance
+      def create(attributes = {})
+        model.create(attributes)
+      end
+
+      # Create a new record (raises on validation failure)
+      #
+      # @param attributes [Hash] Attributes for the new record
+      # @return [ActiveRecord::Base] Created model instance
+      # @raise [ActiveRecord::RecordInvalid] if validation fails
+      def create!(attributes = {})
+        model.create!(attributes)
+      end
+
+      # Update an existing record
+      #
+      # @param record_or_id [ActiveRecord::Base, Integer, String] Record or ID
+      # @param attributes [Hash] Attributes to update
+      # @return [ActiveRecord::Base] Updated model instance
+      # @raise [ActiveRecord::RecordInvalid] if validation fails
+      def update(record_or_id, attributes)
+        record = resolve_record(record_or_id)
+        record.update!(attributes)
+        record
+      end
+      alias update! update
+
+      # Destroy a record
+      #
+      # @param record_or_id [ActiveRecord::Base, Integer, String] Record or ID
+      # @return [ActiveRecord::Base] Destroyed model instance
+      def destroy(record_or_id)
+        record = resolve_record(record_or_id)
+        record.destroy!
+        record
+      end
+      alias destroy! destroy
+
+      # Delete a record without callbacks
+      #
+      # @param record_or_id [ActiveRecord::Base, Integer, String] Record or ID
+      # @return [Integer] Number of deleted records
+      def delete(record_or_id)
+        id = record_or_id.respond_to?(:id) ? record_or_id.id : record_or_id
+        model.where(id: id).delete_all
+      end
+
+      private
+
+      # Resolve a record from ID or return the record itself
+      #
+      # @param record_or_id [ActiveRecord::Base, Integer, String] Record or ID
+      # @return [ActiveRecord::Base] The resolved record
+      def resolve_record(record_or_id)
+        if record_or_id.is_a?(model)
+          record_or_id
+        else
+          find(record_or_id)
+        end
+      end
+
+      # Derive model class from repository name
+      #
+      # ProductRepository -> Product
+      # Bookings::BookingRepository -> Bookings::Booking
+      #
+      # @return [Class] The derived model class
+      # @raise [BetterService::Errors::Configuration::ConfigurationError]
+      def derive_model_class
+        class_name = self.class.name.gsub(/Repository$/, "")
+        class_name.constantize
+      rescue NameError
+        raise Errors::Configuration::ConfigurationError,
+              "Could not derive model class from #{self.class.name}. " \
+              "Pass model_class explicitly to initialize."
+      end
+
+      # Build base scope from predicates
+      #
+      # @param predicates [Hash] Search predicates
+      # @return [ActiveRecord::Relation] Base query scope
+      def build_base_scope(predicates)
+        if model.respond_to?(:search) && predicates.present?
+          model.search(predicates)
+        else
+          model.all
+        end
+      end
+
+      # Apply joins to scope
+      #
+      # @param scope [ActiveRecord::Relation] Current scope
+      # @param joins [Array] Associations to join
+      # @return [ActiveRecord::Relation] Scope with joins
+      def apply_joins(scope, joins)
+        return scope if joins.blank?
+
+        scope.joins(*joins)
+      end
+
+      # Apply includes to scope
+      #
+      # @param scope [ActiveRecord::Relation] Current scope
+      # @param includes [Array] Associations to eager load
+      # @return [ActiveRecord::Relation] Scope with includes
+      def apply_includes(scope, includes)
+        return scope if includes.blank?
+
+        scope.includes(*includes)
+      end
+
+      # Apply ordering to scope
+      #
+      # @param scope [ActiveRecord::Relation] Current scope
+      # @param order [String, Hash, nil] Order clause
+      # @param order_scope [Hash, nil] Named scope for ordering
+      # @return [ActiveRecord::Relation] Ordered scope
+      def apply_ordering(scope, order, order_scope)
+        if order_scope.present?
+          scope_name = "#{order_scope[:field]}_#{order_scope[:direction]}"
+          scope.respond_to?(scope_name) ? scope.send(scope_name) : scope
+        elsif order.present?
+          scope.order(order)
+        else
+          scope
+        end
+      end
+
+      # Apply limit or pagination to scope
+      #
+      # @param scope [ActiveRecord::Relation] Current scope
+      # @param limit [Integer, Symbol, nil] Limit specification
+      # @param page [Integer] Page number
+      # @param per_page [Integer] Records per page
+      # @return [ActiveRecord::Relation, Object, nil] Limited scope or record
+      def apply_limit_or_pagination(scope, limit, page, per_page)
+        case limit
+        when 1
+          scope.first
+        when Integer
+          scope.limit(limit)
+        when nil
+          scope
+        when :default
+          paginate(scope, page: page, per_page: per_page)
+        else
+          paginate(scope, page: page, per_page: per_page)
+        end
+      end
+
+      # Apply pagination to scope
+      #
+      # @param scope [ActiveRecord::Relation] Current scope
+      # @param page [Integer] Page number
+      # @param per_page [Integer] Records per page
+      # @return [ActiveRecord::Relation] Paginated scope
+      def paginate(scope, page:, per_page:)
+        offset_value = ([page.to_i, 1].max - 1) * per_page.to_i
+        scope.offset(offset_value).limit(per_page)
+      end
+    end
+  end
+end

data/lib/better_service/services/action_service.rb

@@ -9,21 +9,21 @@ module BetterService
   # Returns: { resource: {}, metadata: { action: :custom_action_name } }
   #
   # Example:
-  #   class Bookings::AcceptService < BetterService::Services::ActionService
-  #     action_name :accepted  # Sets metadata action
+  #   class Orders::ConfirmService < BetterService::Services::ActionService
+  #     action_name :confirmed  # Sets metadata action
   #
   #     schema do
   #       required(:id).filled(:integer)
   #     end
   #
   #     search_with do
-  #       { resource: user.bookings.find(params[:id]) }
+  #       { resource: user.orders.find(params[:id]) }
   #     end
   #
   #     process_with do |data|
-  #       booking = data[:resource]
-  #       booking.update!(status: 'accepted', accepted_at: Time.current)
-  #       { resource: booking }
+  #       order = data[:resource]
+  #       order.update!(status: 'confirmed', confirmed_at: Time.current)
+  #       { resource: order }
   #     end
   #   end
   class ActionService < Services::Base

data/lib/better_service/services/base.rb

@@ -298,6 +298,103 @@ module BetterService
       }
     end
 
+    # Build a failure response hash
+    #
+    # @param error_message [String] Human-readable error message
+    # @param errors [Hash, Array] Validation errors in various formats
+    # @return [Hash] Standardized failure response
+    #
+    # @example Simple error
+    #   failure_result("Record not found")
+    #
+    # @example With validation errors
+    #   failure_result("Validation failed", { email: ["is invalid"] })
+    def failure_result(error_message, errors = {})
+      {
+        success: false,
+        error: error_message,
+        errors: format_errors_for_response(errors)
+      }
+    end
+
+    # Build a validation failure response with the failed resource
+    #
+    # Used when ActiveRecord validation fails and the form
+    # needs to be re-rendered with the invalid model.
+    #
+    # @param failed_resource [ActiveRecord::Base] Model with validation errors
+    # @return [Hash] Failure response with errors and failed_resource
+    #
+    # @example
+    #   user = User.new(invalid_params)
+    #   user.valid? # => false
+    #   validation_failure_result(user)
+    def validation_failure_result(failed_resource)
+      {
+        success: false,
+        errors: format_model_validation_errors(failed_resource.errors),
+        failed_resource: failed_resource
+      }
+    end
+
+    # Check if data contains an error (for phase flow control)
+    #
+    # @param data [Hash] Data from previous phase
+    # @return [Boolean] true if data contains error
+    #
+    # @example
+    #   def process(data)
+    #     return data if error?(data)  # Pass through errors
+    #     # ... processing logic
+    #   end
+    def error?(data)
+      data.is_a?(Hash) && (data[:error] || data[:success] == false)
+    end
+
+    # Format errors into standard array format
+    #
+    # @param errors [Hash, Array] Errors in various formats
+    # @return [Array<Hash>] Standardized error array
+    def format_errors_for_response(errors)
+      case errors
+      when Hash
+        errors.flat_map do |key, messages|
+          Array(messages).map { |msg| { key: key.to_s, message: msg } }
+        end
+      when Array
+        errors.map do |err|
+          if err.is_a?(Hash) && err[:key] && err[:message]
+            err
+          elsif err.is_a?(String)
+            { key: "base", message: err }
+          else
+            { key: "base", message: err.to_s }
+          end
+        end
+      else
+        []
+      end
+    end
+
+    # Format ActiveRecord/ActiveModel errors into standard format
+    #
+    # Used specifically for ActiveModel::Errors objects (from Rails models).
+    # For Dry::Schema validation errors, the Validatable concern has its own
+    # format_validation_errors method.
+    #
+    # @param errors [ActiveModel::Errors] ActiveRecord errors object
+    # @return [Array<Hash>] Standardized error array
+    def format_model_validation_errors(errors)
+      return [] if errors.blank?
+
+      errors.map do |error|
+        {
+          key: error.attribute.to_s,
+          message: error.message
+        }
+      end
+    end
+
     # Prepend Instrumentation at the end, after call method is defined
     # This wraps the entire call method (including cache logic from Cacheable)
     prepend Concerns::Instrumentation

data/lib/better_service/services/create_service.rb

@@ -9,10 +9,10 @@ module BetterService
   # Returns: { resource: {}, metadata: { action: :created } }
   #
   # Example:
-  #   class Bookings::CreateService < BetterService::Services::CreateService
+  #   class Orders::CreateService < BetterService::Services::CreateService
   #     schema do
   #       required(:title).filled(:string)
-  #       required(:date).filled(:date)
+  #       required(:total).filled(:decimal)
   #     end
   #
   #     search_with do
@@ -20,11 +20,11 @@ module BetterService
   #     end
   #
   #     process_with do |data|
-  #       booking = user.bookings.create!(
+  #       order = user.orders.create!(
   #         title: params[:title],
-  #         date: params[:date]
+  #         total: params[:total]
   #       )
-  #       { resource: booking }
+  #       { resource: order }
   #     end
   #   end
   class CreateService < Services::Base

data/lib/better_service/services/destroy_service.rb

@@ -9,19 +9,19 @@ module BetterService
   # Returns: { resource: {}, metadata: { action: :deleted } }
   #
   # Example:
-  #   class Bookings::DestroyService < BetterService::Services::DestroyService
+  #   class Orders::DestroyService < BetterService::Services::DestroyService
   #     schema do
   #       required(:id).filled(:integer)
   #     end
   #
   #     search_with do
-  #       { resource: user.bookings.find(params[:id]) }
+  #       { resource: user.orders.find(params[:id]) }
   #     end
   #
   #     process_with do |data|
-  #       booking = data[:resource]
-  #       booking.destroy!
-  #       { resource: booking }
+  #       order = data[:resource]
+  #       order.destroy!
+  #       { resource: order }
   #     end
   #   end
   class DestroyService < Services::Base

data/lib/better_service/services/index_service.rb

@@ -9,9 +9,9 @@ module BetterService
   # Returns: { items: [], metadata: { action: :index, stats: {}, pagination: {} } }
   #
   # Example:
-  #   class Bookings::IndexService < BetterService::Services::IndexService
+  #   class Orders::IndexService < BetterService::Services::IndexService
   #     search_with do
-  #       { items: user.bookings.to_a }
+  #       { items: user.orders.to_a }
   #     end
   #
   #     process_with do |data|

data/lib/better_service/services/show_service.rb

@@ -9,9 +9,9 @@ module BetterService
   # Returns: { resource: {}, metadata: { action: :show } }
   #
   # Example:
-  #   class Bookings::ShowService < BetterService::Services::ShowService
+  #   class Orders::ShowService < BetterService::Services::ShowService
   #     search_with do
-  #       { resource: user.bookings.find(params[:id]) }
+  #       { resource: user.orders.find(params[:id]) }
   #     end
   #   end
   class ShowService < Services::Base

data/lib/better_service/services/update_service.rb

@@ -9,20 +9,20 @@ module BetterService
   # Returns: { resource: {}, metadata: { action: :updated } }
   #
   # Example:
-  #   class Bookings::UpdateService < BetterService::Services::UpdateService
+  #   class Orders::UpdateService < BetterService::Services::UpdateService
   #     schema do
   #       required(:id).filled(:integer)
   #       optional(:title).filled(:string)
   #     end
   #
   #     search_with do
-  #       { resource: user.bookings.find(params[:id]) }
+  #       { resource: user.orders.find(params[:id]) }
   #     end
   #
   #     process_with do |data|
-  #       booking = data[:resource]
-  #       booking.update!(params.except(:id))
-  #       { resource: booking }
+  #       order = data[:resource]
+  #       order.update!(params.except(:id))
+  #       { resource: order }
   #     end
   #   end
   class UpdateService < Services::Base

data/lib/better_service/version.rb

@@ -1,3 +1,3 @@
 module BetterService
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

data/lib/better_service/workflows/branch.rb

@@ -97,7 +97,7 @@ module BetterService
           if result[:success] == false && !result[:optional_failure]
             raise Errors::Workflowable::Runtime::StepExecutionError.new(
               "Step #{step_or_branch_group.name} failed in branch",
-              code: ErrorCodes::STEP_EXECUTION_FAILED,
+              code: ErrorCodes::STEP_FAILED,
               context: {
                 step: step_or_branch_group.name,
                 branch: @name,

data/lib/better_service.rb

@@ -4,6 +4,8 @@ require "better_service/configuration"
 require "better_service/errors/better_service_error"
 require "better_service/cache_service"
 require "better_service/presenter"
+require "better_service/repository/base_repository"
+require "better_service/concerns/serviceable/repository_aware"
 require "better_service/concerns/instrumentation"
 require "better_service/subscribers/log_subscriber"
 require "better_service/subscribers/stats_subscriber"

data/lib/generators/better_service/locale_generator.rb

@@ -8,7 +8,7 @@ module BetterService
     #
     # Usage:
     #   rails generate better_service:locale products
-    #   rails generate better_service:locale bookings
+    #   rails generate better_service:locale orders
     #
     # This generates config/locales/products_services.en.yml with scaffolded
     # translations for common service actions (create, update, destroy, etc.)

metadata

@@ -1,19 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: better_service
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - alessiobussolari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-13 00:00:00.000000000 Z
+date: 2025-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.1
@@ -21,6 +24,9 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.1
@@ -86,6 +92,7 @@ files:
 - lib/better_service/concerns/serviceable/cacheable.rb
 - lib/better_service/concerns/serviceable/messageable.rb
 - lib/better_service/concerns/serviceable/presentable.rb
+- lib/better_service/concerns/serviceable/repository_aware.rb
 - lib/better_service/concerns/serviceable/transactional.rb
 - lib/better_service/concerns/serviceable/validatable.rb
 - lib/better_service/concerns/serviceable/viewable.rb
@@ -117,6 +124,7 @@ files:
 - lib/better_service/errors/workflowable/runtime/workflow_runtime_error.rb
 - lib/better_service/presenter.rb
 - lib/better_service/railtie.rb
+- lib/better_service/repository/base_repository.rb
 - lib/better_service/services/action_service.rb
 - lib/better_service/services/base.rb
 - lib/better_service/services/create_service.rb
@@ -166,7 +174,6 @@ homepage: https://github.com/alessiobussolari/better_service
 licenses:
 - WTFPL
 metadata:
-  homepage_uri: https://github.com/alessiobussolari/better_service
   source_code_uri: https://github.com/alessiobussolari/better_service
   changelog_uri: https://github.com/alessiobussolari/better_service/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'