better_service 1.0.0

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module BetterService
+  module Concerns
+    module Serviceable
+    module Cacheable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_cache_key, default: nil
+        class_attribute :_cache_ttl, default: 900  # 15 minutes in seconds
+        class_attribute :_cache_contexts, default: []
+
+        # Wrap call method with caching after class is loaded
+        # This is safe because included runs after Base defines call
+        if method_defined?(:call)
+          alias_method :call_without_cache, :call
+
+          define_method(:call) do
+            return call_without_cache unless cache_enabled?
+
+            cache_key_value = build_cache_key(user)
+
+            # Check if cache exists to publish appropriate event
+            cache_exists = Rails.cache.exist?(cache_key_value)
+
+            # Get cache context if available
+            cache_context = self.class._cache_contexts.first
+
+            # Publish cache hit/miss event if instrumentation methods are available
+            # These methods are added by Instrumentation concern which is prepended after
+            begin
+              if cache_exists
+                publish_cache_hit(cache_key_value, cache_context)
+              else
+                publish_cache_miss(cache_key_value, cache_context)
+              end
+            rescue NoMethodError
+              # Instrumentation methods not available - skip event publishing silently
+            end
+
+            Rails.cache.fetch(cache_key_value, expires_in: self.class._cache_ttl) do
+              call_without_cache
+            end
+          end
+        end
+      end
+
+      class_methods do
+        def cache_key(key)
+          self._cache_key = key
+        end
+
+        def cache_ttl(duration)
+          self._cache_ttl = duration
+        end
+
+        def cache_contexts(*contexts)
+          self._cache_contexts = contexts
+        end
+      end
+
+      private
+
+      def cache_enabled?
+        self.class._cache_key.present?
+      end
+
+      def build_cache_key(user)
+        user_part = user ? "user_#{user.id}" : "global"
+        "#{self.class._cache_key}:#{user_part}:#{cache_params_signature}"
+      end
+
+      def cache_params_signature
+        Digest::MD5.hexdigest(@params.to_json)
+      end
+
+      def invalidate_cache_for(user = nil)
+        return unless self.class._cache_contexts.present?
+
+        if user.present?
+          self.class._cache_contexts.each do |context|
+            CacheService.invalidate_for_context(user, context)
+          end
+        else
+          Rails.logger.info "[BetterService] Global cache invalidation for: #{self.class._cache_contexts.join(', ')}" if defined?(Rails)
+          self.class._cache_contexts.each do |context|
+            CacheService.invalidate_global(context)
+          end
+        end
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Serviceable
+    module Messageable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_messages_namespace, default: nil
+      end
+
+      class_methods do
+        def messages_namespace(namespace)
+          self._messages_namespace = namespace
+        end
+      end
+
+      private
+
+      def message(key_path, interpolations = {})
+        return key_path if self.class._messages_namespace.nil?
+
+        full_key = "#{self.class._messages_namespace}.services.#{key_path}"
+        I18n.t(full_key, **interpolations)
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Serviceable
+    module Presentable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_presenter_class, default: nil
+        class_attribute :_presenter_options, default: -> { {} }
+      end
+
+      class_methods do
+        def presenter(klass)
+          self._presenter_class = klass
+        end
+
+        def presenter_options(&block)
+          self._presenter_options = block
+        end
+      end
+
+      private
+
+      # Override transform phase
+      def transform(data)
+        # If custom transform_with block defined, use it
+        if self.class._transform_block
+          instance_exec(data, &self.class._transform_block)
+        # If presenter configured, apply it
+        elsif self.class._presenter_class
+          apply_presenter(data)
+        # Otherwise return data unchanged
+        else
+          data
+        end
+      end
+
+      def apply_presenter(data)
+        options = instance_exec(&self.class._presenter_options)
+
+        if data.key?(:items)
+          rest = data.dup
+          rest.delete(:items)
+          { items: present_collection(data[:items], options), **rest }
+        elsif data.key?(:resource)
+          rest = data.dup
+          rest.delete(:resource)
+          { resource: present_resource(data[:resource], options), **rest }
+        else
+          data
+        end
+      end
+
+      def present_collection(items, options)
+        items.map { |item| self.class._presenter_class.new(item, **options) }
+      end
+
+      def present_resource(resource, options)
+        self.class._presenter_class.new(resource, **options)
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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
+      #
+      # @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)
+        end
+        result
+      end
+    end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "dry-schema"
+
+module BetterService
+  module Concerns
+    module Serviceable
+      module Validatable
+        extend ActiveSupport::Concern
+
+        included do
+          class_attribute :_schema, default: nil
+          attr_reader :validation_errors
+        end
+
+        class_methods do
+          def schema(&block)
+            self._schema = Dry::Schema.Params(&block)
+          end
+
+          def schema_defined?
+            _schema.present?
+          end
+        end
+
+        def valid?
+          @validation_errors.empty?
+        end
+
+        private
+
+        def validate_params!
+          return unless self.class._schema
+
+          result = self.class._schema.call(@params)
+          return if result.success?
+
+          # Raise ValidationError instead of setting validation_errors
+          raise Errors::Runtime::ValidationError.new(
+            "Validation failed",
+            code: ErrorCodes::VALIDATION_FAILED,
+            context: {
+              service: self.class.name,
+              params: @params,
+              validation_errors: format_validation_errors(result.errors)
+            }
+          )
+        end
+
+        def format_validation_errors(errors)
+          errors.to_h.transform_values do |messages|
+            messages.is_a?(Array) ? messages : [ messages ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Serviceable
+    module Viewable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_viewer_enabled, default: false
+        class_attribute :_viewer_block, default: nil
+      end
+
+      class_methods do
+        def viewer(enabled = true, &block)
+          self._viewer_enabled = enabled
+          self._viewer_block = block if block_given?
+        end
+      end
+
+      private
+
+      # Override respond to add viewer phase
+      def respond(data)
+        # Get base result from parent respond
+        if self.class._respond_block
+          result = instance_exec(data, &self.class._respond_block)
+        else
+          result = success_result("Operation completed successfully", data)
+        end
+
+        # Add viewer if enabled
+        return result unless viewer_enabled?
+
+        view_config = execute_viewer(data, data, result)
+        result.merge(view: view_config)
+      end
+
+      def viewer_enabled?
+        self.class._viewer_enabled && self.class._viewer_block.present?
+      end
+
+      def execute_viewer(processed, transformed, result)
+        instance_exec(processed, transformed, result, &self.class._viewer_block)
+      end
+    end
+    end
+  end
+end

data/lib/better_service/concerns/serviceable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    # Serviceable - Namespace for all service-related concerns
+    #
+    # This module groups all concerns that are specific to BetterService services,
+    # such as validation, authorization, transactions, presentation, caching, etc.
+    module Serviceable
+    end
+  end
+end

data/lib/better_service/concerns/workflowable/callbacks.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Concerns
+    module Workflowable
+      # Callbacks - Adds lifecycle callbacks to workflows
+    #
+    # Provides before_workflow, after_workflow, and around_step hooks
+    # that allow executing custom logic at different stages of the workflow.
+    #
+    # Example:
+    #   class OrderWorkflow < BetterService::Workflow
+    #     before_workflow :validate_prerequisites
+    #     after_workflow :cleanup_resources
+    #     around_step :log_step_execution
+    #
+    #     private
+    #
+    #     def validate_prerequisites(context)
+    #       context.fail!("Cart is empty") if context.cart_items.empty?
+    #     end
+    #
+    #     def cleanup_resources(context)
+    #       context.user.clear_cart! if context.success?
+    #     end
+    #
+    #     def log_step_execution(step, context)
+    #       start_time = Time.current
+    #       yield # Execute the step
+    #       duration = Time.current - start_time
+    #       Rails.logger.info "Step #{step.name} completed in #{duration}s"
+    #     end
+    #   end
+      module Callbacks
+        extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_before_workflow_callbacks, default: []
+        class_attribute :_after_workflow_callbacks, default: []
+        class_attribute :_around_step_callbacks, default: []
+      end
+
+      class_methods do
+        # Define a callback to run before the workflow starts
+        #
+        # @param method_name [Symbol] Name of the method to call
+        def before_workflow(method_name)
+          self._before_workflow_callbacks += [ method_name ]
+        end
+
+        # Define a callback to run after the workflow completes
+        #
+        # @param method_name [Symbol] Name of the method to call
+        def after_workflow(method_name)
+          self._after_workflow_callbacks += [ method_name ]
+        end
+
+        # Define a callback to run around each step execution
+        #
+        # @param method_name [Symbol] Name of the method to call
+        # The method will receive the step and context as arguments
+        # and should yield to execute the step
+        def around_step(method_name)
+          self._around_step_callbacks += [ method_name ]
+        end
+      end
+
+      private
+
+      # Run all before_workflow callbacks
+      def run_before_workflow_callbacks(context)
+        self.class._before_workflow_callbacks.each do |callback|
+          send(callback, context)
+          # Stop execution if context was marked as failed
+          break if context.failure?
+        end
+      end
+
+      # Run all after_workflow callbacks
+      def run_after_workflow_callbacks(context)
+        self.class._after_workflow_callbacks.each do |callback|
+          send(callback, context)
+        end
+      end
+
+      # Run around_step callbacks for a specific step
+      def run_around_step_callbacks(step, context, &block)
+        callbacks = self.class._around_step_callbacks.dup
+
+        if callbacks.empty?
+          # No callbacks, just execute the block
+          yield
+        else
+          # Build a chain of callbacks
+          execute_callback_chain(callbacks, step, context, &block)
+        end
+      end
+
+      # Execute callback chain recursively
+      def execute_callback_chain(callbacks, step, context, &block)
+        if callbacks.empty?
+          # End of chain, execute the actual step
+          yield
+        else
+          # Pop the first callback and execute it
+          callback = callbacks.shift
+          send(callback, step, context) do
+            # Continue the chain
+            execute_callback_chain(callbacks, step, context, &block)
+          end
+        end
+      end
+      end
+    end
+  end
+end

data/lib/better_service/concerns/workflowable/context.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module BetterService
+  module Workflowable
+    # Context - Container for shared data between workflow steps
+    #
+    # The Context object holds all data that flows through the workflow pipeline.
+    # Each step can read from and write to the context. The context also tracks
+    # the success/failure state of the workflow.
+    #
+    # Example:
+    #   context = Context.new(user: current_user, cart_items: [...])
+    #   context.order = Order.create!(...)
+    #   context.success? # => true
+    #
+    #   context.fail!("Payment failed", payment_error: "Card declined")
+    #   context.success? # => false
+    #   context.errors # => { payment_error: "Card declined" }
+    class Context
+      attr_reader :user, :errors, :_called
+
+      def initialize(user, **initial_data)
+        @user = user
+        @data = initial_data
+        @errors = {}
+        @failed = false
+        @_called = false
+      end
+
+      # Check if workflow has succeeded (no failure called)
+      def success?
+        !@failed
+      end
+
+      # Check if workflow has failed
+      def failure?
+        @failed
+      end
+
+      # Mark workflow as failed with error message and optional error details
+      #
+      # @param message [String] Error message
+      # @param errors [Hash] Optional hash of detailed errors
+      def fail!(message, **errors)
+        @failed = true
+        @errors[:message] = message
+        @errors.merge!(errors) if errors.any?
+      end
+
+      # Mark workflow as called (used internally)
+      def called!
+        @_called = true
+      end
+
+      # Check if workflow has been called
+      def called?
+        @_called
+      end
+
+      # Add data to context
+      #
+      # @param key [Symbol] Key to store data under
+      # @param value [Object] Value to store
+      def add(key, value)
+        @data[key] = value
+      end
+
+      # Get data from context
+      #
+      # @param key [Symbol] Key to retrieve
+      def get(key)
+        @data[key]
+      end
+
+      # Allow reading context data via method calls
+      # Example: context.order instead of context.get(:order)
+      def method_missing(method_name, *args)
+        method_str = method_name.to_s
+
+        if method_str.end_with?("=")
+          # Setter: context.order = value
+          key = method_str.chomp("=").to_sym
+          @data[key] = args.first
+        elsif @data.key?(method_name)
+          # Getter: context.order
+          @data[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        method_str = method_name.to_s
+        method_str.end_with?("=") || @data.key?(method_name) || super
+      end
+
+      # Return all context data as hash
+      def to_h
+        @data.dup
+      end
+
+      # Inspect for debugging
+      def inspect
+        "#<BetterService::Workflowable::Context success=#{success?} data=#{@data.inspect} errors=#{@errors.inspect}>"
+      end
+    end
+  end
+end