gaskit 0.1.0

data/lib/gaskit/operation_result.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Gaskit
+  # Represents the result of an operation, encapsulating success/failure, values, errors, and execution duration.
+  #
+  # @example Using OperationResult to handle success and failure
+  #   result = Gaskit::BaseResult.new(true, "data", nil, 1.23)
+  #   if result.success?
+  #     puts "Operation succeeded with value: #{result.value}"
+  #   else
+  #     puts "Operation failed with reason: #{result.to_h[:error]}"
+  #   end
+  class OperationResult
+    # @return [Boolean] Whether the operation was successful.
+    attr_reader :success
+
+    # @return [Object, nil] The result value of the operation, if any.
+    attr_reader :value
+
+    # @return [Exception, nil] The error that occurred during the operation, if any.
+    attr_reader :error
+
+    # @return [Float] The duration of the operation in seconds.
+    attr_reader :duration
+
+    # @return [Hash] The context used during the operation.
+    attr_reader :context
+
+    # Initializes a new instance of OperationResult.
+    #
+    # @param [Boolean] success Whether the operation was successful.
+    # @param [Object, nil] value The value obtained as a result of the operation.
+    # @param [Exception, nil] error The error encountered during the operation.
+    # @param [Float, String] duration The time taken to complete the operation in seconds.
+    # @param [Hash] context Optional context metadata for this operation.
+    def initialize(success, value, error, duration:, context: {})
+      @success = success
+      @value = value
+      @error = error
+      @duration = format_duration(duration)
+      @context = context
+    end
+
+    # Provides a human-readable string representation of the result.
+    #
+    # @return [String] The formatted inspection string.
+    def inspect
+      "#<#{self.class.name} success=#{success?} value=#{value.inspect} duration=#{duration}>"
+    end
+
+    # Indicates whether the operation was successful.
+    #
+    # @return [Boolean] `true` if the operation was successful, `false` otherwise.
+    def success?
+      @success
+    end
+
+    # Indicates whether the operation failed.
+    #
+    # @return [Boolean] `true` if the operation failed, `false` otherwise.
+    def failure?
+      !@success
+    end
+
+    # Indicates whether the operation exited early using `exit(:key)`.
+    #
+    # @return [Boolean] `true` if the operation exited early, `false` otherwise.
+    def early_exit?
+      !@success && error.is_a?(Gaskit::OperationExit)
+    end
+
+    # Returns the status of the operation result.
+    #
+    # @return [Symbol] :success, :failure, or :early_exit
+    def status
+      return :early_exit if early_exit?
+
+      success? ? :success : :failure
+    end
+
+    # Converts the operation result to a structured hash.
+    #
+    # - Includes `:value` on success
+    # - Includes `:exit` if early_exit?
+    # - Includes `:error` if a failure occurred
+    # - Always includes `:meta` with duration and context
+    #
+    # @return [Hash] A nested representation of the result.
+    def to_h
+      hash = {
+        success: success?,
+        status: status,
+        value: value
+      }.compact
+
+      hash = failure_to_hash(hash) if failure?
+
+      hash[:meta] = {
+        duration: duration,
+        context: context
+      }.compact
+
+      hash.freeze
+    end
+
+    # Serializes the result to a JSON string.
+    #
+    # @param options [Hash] Optional hash passed to `JSON.generate`
+    # @return [String] JSON representation of the operation result
+    def to_json(options = {})
+      to_h.to_json(options)
+    end
+
+    private
+
+    # Formats duration as a 6-digit string.
+    #
+    # @param duration [Float, String]
+    # @return [String]
+    def format_duration(duration)
+      duration = duration.to_f
+      format("%.6f", duration)
+    end
+
+    # Builds the exit section of the result hash.
+    #
+    # @return [Hash] Details about the early exit, including key and message.
+    def exit_to_hash
+      {
+        key: error.key,
+        message: error.message,
+        code: error.respond_to?(:code) ? error.code : nil
+      }.compact
+    end
+
+    # Builds the error section of the result hash.
+    #
+    # @return [Hash] Details about the raised exception (if any).
+    def error_to_hash
+      {
+        type: error.class.name,
+        message: error.message,
+        class: error.class.name,
+        backtrace: error.backtrace
+      }.compact
+    end
+
+    def failure_to_hash(hash)
+      hash[:exit] = exit_to_hash if early_exit?
+      hash[:error] = error_to_hash if failure? && !early_exit? && error
+
+      hash
+    end
+  end
+end

data/lib/gaskit/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Gaskit
+  class Railtie < Rails::Railtie
+    config.app_generators do |g|
+      g.templates.unshift File.expand_path("../../generators", __dir__)
+    end
+  end
+end

data/lib/gaskit/repository.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Gaskit
+  class Repository
+    COMMON_AR_METHODS = %i[
+      find find_by find_by! find_each
+      where order limit offset group having
+      pluck select exists? create create!
+      update update_all destroy destroy_all
+      count any? none? all?
+    ].freeze
+
+    class << self
+      # Prevents instantiation of repository classes.
+      #
+      # This ensures that subclasses of `Gaskit::Repository` cannot be instantiated
+      # directly. If an attempt is made, a `TypeError` will be raised with the class name.
+      #
+      # @param subclass [Class] the inheriting class
+      # @return [void]
+      # @raise [TypeError] if the subclass attempts to be instantiated
+      def inherited(subclass)
+        subclass.define_singleton_method(:new) do
+          raise TypeError, "Repositories cannot be instantiated: #{subclass.name}"
+        end
+        super
+      end
+
+      # Defines or retrieves the base model for this repository.
+      #
+      # When a model is defined, common ActiveRecord-like methods are delegated
+      # to the model automatically. The model can only be set once per repository class.
+      #
+      # @param klass [Class, nil] The model class (e.g., an ActiveRecord model)
+      # @return [Class, nil] Returns the currently defined model
+      # @raise [StandardError] If a model is set more than once
+      #
+      # @example Define a model
+      #   UserRepository.model(User)
+      #
+      # @example Retrieve the model
+      #   UserRepository.model
+      def model(klass = nil)
+        return get_model_class! unless klass
+
+        raise "#{name} already has a model set" if instance_variable_defined?(:@model_class)
+
+        instance_variable_set(:@model_class, klass)
+        delegate_common_model_methods
+      end
+
+      # Returns a logger instance for this repository.
+      #
+      # The logger is specifically scoped to the repository class, allowing for
+      # structured and context-based logging.
+      #
+      # @return [Gaskit::Logger] The logger instance associated with the class
+      #
+      # @example Log a message
+      #   UserRepository.logger.debug("This is a debug message")
+      def logger
+        @logger ||= Gaskit::Logger.new(self)
+      end
+
+      # Logs the execution time of a block of code.
+      #
+      # This method measures the duration of the given block. It conditionally logs
+      # the timing information based on the log level and configuration settings.
+      #
+      # If the block raises an exception, the duration is still logged, and the exception
+      # is re-raised after logging the error.
+      #
+      # @param context [Hash] Optional additional context to include in the log
+      # @param log_level [Symbol] The log level (default: `:debug`)
+      # @yield The block of code to be measured
+      # @return [Object] The result of the block execution
+      #
+      # @raise [StandardError] If the block raises an error
+      #
+      # @example Log execution time
+      #   UserRepository.log_execution_time(log_level: :info) do
+      #     perform_work
+      #   end
+      def log_execution_time(context: {}, log_level: :debug, &block)
+        return yield unless should_log_execution_time?(log_level)
+
+        method_name = caller_locations(1, 1)&.first&.label
+        duration, result = Gaskit::Helpers.time_execution(&block)
+
+        logger.log(log_level, "#{method_name} completed", context: context.merge(duration: duration))
+
+        result
+      rescue StandardError => e
+        duration ||= "0.000000"
+        logger.error("#{method_name} failed", context: context.merge(duration: duration, error: e.message))
+
+        raise
+      end
+
+      private
+
+      # Retrieves the base model for the repository.
+      #
+      # @return [Class] The model class associated with the repository
+      # @raise [StandardError] If no model is defined
+      def get_model_class!
+        instance_variable_get(:@model_class) || raise("#{name} must declare a model using `model YourModel`")
+      end
+
+      # Delegates common ActiveRecord-like methods to the base model.
+      #
+      # This method iterates through a predefined list of methods (`COMMON_AR_METHODS`)
+      # and dynamically defines singleton methods for the repository. These methods
+      # call the corresponding methods on the associated model.
+      #
+      # @return [void]
+      #
+      # @note This method is called automatically when a model is defined using {#model}.
+      def delegate_common_model_methods
+        COMMON_AR_METHODS.each do |method_name|
+          define_singleton_method(method_name) do |*args, **kwargs, &block|
+            model.public_send(method_name, *args, **kwargs, &block)
+          end
+        end
+      end
+
+      # Determines whether execution time logging should occur.
+      #
+      # This checks various conditions (e.g., debug mode or logger level)
+      # to decide if execution timing should be logged.
+      #
+      # @param log_level [Symbol] The desired log level
+      # @return [Boolean] `true` if execution time logging is enabled, otherwise `false`
+      def should_log_execution_time?(log_level)
+        return true if Gaskit.configuration.debug
+        return true if log_level == :debug
+        return true if logger.respond_to?(:level) && logger.level <= Logger::DEBUG
+
+        false
+      end
+    end
+  end
+end

data/lib/gaskit/version.rb

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

data/lib/gaskit.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "gaskit/version"
+require_relative "gaskit/error"
+require_relative "gaskit/operation_result"
+require_relative "gaskit/logger"
+require_relative "gaskit/operation"
+require_relative "gaskit/repository"
+require_relative "gaskit/flow"
+require_relative "gaskit/core"
+
+require_relative "gaskit/boot/service"
+require_relative "gaskit/boot/query"
+
+require_relative "gaskit/railtie" if defined?(Rails::Railtie)
+
+# Gaskit is a lightweight, extensible framework for building structured application operations.
+#
+# It provides a clear architecture for defining, executing, and managing operations,
+# supporting common patterns like services and queries, early exits, context-aware logging,
+# and standardized result wrapping.
+#
+# @example Configuring Gaskit
+#   Gaskit.config do |c|
+#     c.setup_logger(Logger.new(STDOUT), level: ::Logger::INFO, formatter: Gaskit::Logger.formatter(:json))
+#     c.context_provider = -> { { request_id: SecureRandom.uuid } }
+#   end
+#
+# @example Registering a contract
+#   Gaskit.register_contract(:service, MyResultClass)
+#
+# @example Defining a service
+#   class MyService < Gaskit::Service
+#     def call
+#       # do work
+#       "done"
+#     end
+#   end
+#
+# @see Gaskit::Operation
+# @see Gaskit::Service
+# @see Gaskit::Query
+# @see Gaskit::Configuration
+module Gaskit; end

data/lib/generators/gaskit/operation/flow_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Gaskit
+  module Generators
+    # Generates a new Gaskit::Flow class using the class-based DSL.
+    #
+    # This generator creates a flow subclass using statically defined steps.
+    #
+    # @example Generates a class like:
+    #   class CheckoutFlow < Gaskit::Flow
+    #     step AddToCart
+    #     step ApplyDiscount
+    #     step Finalize
+    #   end
+    #
+    #   CheckoutFlow.call(user_id: 123)
+    #
+    #   rails generate gaskit:flow Checkout AddToCart ApplyDiscount Finalize
+    #
+    # @see templates/flow.rb.tt for the ERB template used.
+    class FlowGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      # List of operation steps for the flow
+      argument :steps, type: :array, default: [], banner: "StepOne StepTwo"
+
+      def create_flow_file
+        template "flow.rb.tt", File.join("app/flows", class_path, "#{file_name}_flow.rb")
+      end
+    end
+  end
+end

data/lib/generators/gaskit/operation/operation_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Gaskit
+  module Generators
+    # A Rails generator for creating new operation classes that inherit from `Gaskit::Operation`,
+    # `Gaskit::Service`, or `Gaskit::Query`, depending on the specified `--type` option.
+    #
+    # This generator supports namespaced operations and places them under `app/operations`.
+    #
+    # @example Generate a base operation
+    #   rails generate gaskit:operation CreateUser
+    #
+    # @example Generate a service operation
+    #   rails generate gaskit:operation CreateUser --type=service
+    #
+    # @example Generate a query operation
+    #   rails generate gaskit:operation FetchUsers --type=query
+    #
+    # @see templates/operation.rb.tt for the ERB template used.
+    class OperationGenerator < Rails::Generators::NamedBase
+      SUPPORTED_TYPES = %w[base service query].freeze
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :type,
+                   type: :string,
+                   default: "base",
+                   desc: "Operation type (base, service, query)"
+
+      def validate_type!
+        return if SUPPORTED_TYPES.include?(options["type"])
+
+        raise ArgumentError, "Invalid type: #{options["type"]}. Supported types are: #{SUPPORTED_TYPES.join(", ")}"
+      end
+
+      def create_operation_file
+        validate_type!
+
+        subdir = case options["type"]
+                 when "service" then "services"
+                 when "query" then "queries"
+                 else "operations"
+                 end
+
+        template "operation.rb.tt", File.join("app", subdir, class_path, "#{file_name}.rb")
+      end
+    end
+  end
+end

data/lib/generators/gaskit/operation/query_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Gaskit
+  module Generators
+    # A Rails generator for creating new service classes that inherit from `Gaskit::Query`.
+    #
+    # This generator supports namespaced queries and places them under `app/queries`.
+    #
+    # @example Generate a base operation
+    #   rails generate gaskit:query FetchUserQuery
+    #
+    # @see templates/operation.rb.tt for the ERB template used.
+    class QueryGenerator < OperationGenerator
+      def initialize(*args)
+        super
+        options[:type] = "query"
+      end
+    end
+  end
+end

data/lib/generators/gaskit/operation/repository_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Gaskit
+  module Generators
+    # Generates a repository for a given model name
+    #
+    # @example
+    #   rails generate gaskit:repository User
+    #
+    #   # Creates:
+    #   # app/repositories/user_repository.rb
+    #
+    #   # With contents:
+    #   # class UserRepository < Gaskit::Repository
+    #   #   model User
+    #   # end
+    class RepositoryGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_repository_file
+        @model_name = class_name
+        @repository_class_name = "#{class_name}Repository"
+        @file_path = File.join("app/repositories", class_path, "#{file_name}_repository.rb")
+
+        template "repository.rb.tt", @file_path
+      end
+
+      private
+
+      def file_name
+        super.underscore
+      end
+    end
+  end
+end

data/lib/generators/gaskit/operation/service_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Gaskit
+  module Generators
+    # A Rails generator for creating new service classes that inherit from `Gaskit::Service`.
+    #
+    # This generator supports namespaced services and places them under `app/services`.
+    #
+    # @example Generate a base operation
+    #   rails generate gaskit:service CreateUserService
+    #
+    # @see templates/operation.rb.tt for the ERB template used.
+    class ServiceGenerator < OperationGenerator
+      def initialize(*args)
+        super
+        options[:type] = "service"
+      end
+    end
+  end
+end

data/lib/generators/gaskit/operation/templates/flow.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Flow < Gaskit::Flow
+<% steps.each do |step| -%>
+  step <%= step %>
+<% end -%>
+end

data/lib/generators/gaskit/operation/templates/operation.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+<% gaskit_type = case options["type"] %>
+<% when "service" then "Gaskit::Service" %>
+<% when "query" then "Gaskit::Query" %>
+<% else "Gaskit::Operation" %>
+<% end %>
+
+class <%= class_name %> < <%= gaskit_type %>
+  # This is a generated Gaskit operation. Add your logic below.
+
+  def call(*args, **kwargs)
+    # Your operation logic goes here.
+    "ok"
+  end
+end

data/lib/generators/gaskit/operation/templates/repository.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class <%= @repository_class_name %> < Gaskit::Repository
+  model <%= @model_name %>
+
+  # Define additional methods here as needed
+end

data/sig/gaskit.rbs

@@ -0,0 +1,4 @@
+module Gaskit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end