gaskit 0.1.0 → 0.1.1

data/lib/gaskit/hook_registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Gaskit
+  # Gaskit::HookRegistry manages registration and retrieval of global hooks for
+  # operation-style lifecycles (e.g., `before`, `after`, `around`).
+  #
+  # Hooks are grouped by type and tag. They are used in classes that include `Gaskit::Hookable`.
+  class HookRegistry
+    def initialize
+      @hooks = {
+        before: Hash.new { |h, k| h[k] = [] },
+        after: Hash.new { |h, k| h[k] = [] },
+        around: Hash.new { |h, k| h[k] = [] }
+      }
+    end
+
+    # Registers a new hook under a given type and tag.
+    #
+    # @param type [Symbol] The lifecycle type: `:before`, `:after`, or `:around`
+    # @param tag [Symbol, String] A symbolic tag to group related hooks (e.g., :audit, :metrics)
+    # @param callable [#call, nil] A callable object (optional if block is given)
+    # @yield [hook] A block to be registered as a hook if no callable is passed
+    # @return [void]
+    # @raise [ArgumentError] If the hook is not callable or the type is invalid
+    def register(type, tag, callable = nil, &block)
+      hook = callable || block
+      raise ArgumentError, "Hook must respond to #call" unless hook.respond_to?(:call)
+      raise ArgumentError, "Unknown hook type: #{type}" unless @hooks.key?(type)
+
+      @hooks[type][tag.to_sym] << hook
+    end
+
+    # Checks if a hook tag is registered under a specific type.
+    #
+    # @param type [Symbol] The hook type (`:before`, `:after`, or `:around`)
+    # @param tag [Symbol, String] The tag to check
+    # @return [Boolean] Whether a hook with that tag exists for the given type
+    def registered?(type, tag)
+      @hooks[type].key?(tag.to_sym)
+    end
+
+    # Fetches hooks for the given type, filtered by tags.
+    #
+    # @param type [Symbol] The hook type (`:before`, `:after`, or `:around`)
+    # @param tags [Array<Symbol, String>, nil] One or more tags to filter hooks by. If nil or empty,
+    #   returns all hooks of that type.
+    # @return [Array<#call>] An array of callable hooks
+    def fetch(type, tags = nil)
+      return @hooks[type].values.flatten if tags.nil? || tags.empty?
+
+      (tags || []).flat_map { |tag| @hooks[type][tag.to_sym] }
+    end
+
+    # Returns all registered tags for a given hook type.
+    #
+    # @param type [Symbol] The hook type (`:before`, `:after`, or `:around`)
+    # @return [Array<Symbol>] List of registered tags under that type
+    def registered_tags(type)
+      @hooks[type].keys
+    end
+  end
+end

data/lib/gaskit/hookable.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Gaskit
+  module Hookable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      VALID_HOOK_TYPES = %i[before after around].freeze
+
+      def use_hooks(*tags, all: tags.empty?)
+        registered_hooks.concat(tags.map(&:to_sym)).uniq!
+
+        @run_all_hooks = all
+        @enabled = true
+      end
+
+      def use_hook(type, proc = nil, &block)
+        hook = block_given? ? block : proc
+        type, hook = validate_hook!(type, hook)
+
+        inline_hooks[type] << hook
+        @enabled = true
+      end
+
+      def before(proc = nil, &block)
+        use_hook(:before, proc, &block)
+      end
+
+      def around(proc = nil, &block)
+        use_hook(:around, proc, &block)
+      end
+
+      def after(proc = nil, &block)
+        use_hook(:after, proc, &block)
+      end
+
+      def hooks_enabled?
+        @enabled || false
+      end
+
+      def run_all_hooks?
+        @run_all_hooks || false
+      end
+
+      def registered_hooks
+        @registered_hooks ||= []
+      end
+
+      def inline_hooks
+        @inline_hooks ||= Concurrent::Hash.new { |h, k| h[k] = [] }
+      end
+
+      private
+
+      def validate_hook!(type, hook)
+        type = type.to_sym
+
+        unless VALID_HOOK_TYPES.include?(type)
+          raise ArgumentError, "#{type} is not a valid hook type (valid types are #{VALID_HOOK_TYPES.join(", ")})"
+        end
+
+        raise ArgumentError, "Hook must be callable" unless hook.respond_to?(:call)
+
+        [type, hook]
+      end
+    end
+
+    def apply_hooks(*types, &block)
+      return block.call unless self.class.hooks_enabled?
+
+      types = types.map(&:to_sym)
+      result = nil
+
+      apply_type_hooks(:before) if types.include?(:before)
+      result = apply_type_hooks(:around, &block) if types.include?(:around)
+      apply_type_hooks(:after, result: result) if types.include?(:after)
+
+      result
+    end
+
+    def apply_before_hooks
+      apply_type_hooks(:before)
+    end
+
+    def apply_around_hooks(&block)
+      apply_type_hooks(:around, &block)
+    end
+
+    def apply_after_hooks(result)
+      apply_type_hooks(:after, result: result)
+    end
+
+    private
+
+    def collect_hooks(type)
+      inline = self.class.inline_hooks[type]
+      registered =
+        if self.class.run_all_hooks?
+          Gaskit.hooks.fetch(type)
+        else
+          Gaskit.hooks.fetch(type, self.class.registered_hooks)
+        end
+
+      (registered + inline).uniq
+    end
+
+    def apply_type_hooks(type, result: nil, &block)
+      return result unless self.class.hooks_enabled?
+
+      hooks = collect_hooks(type)
+      process_hooks(type, hooks, result, &block)
+    end
+
+    def process_hooks(type, hooks, result, &block)
+      case type
+      when :before
+        hooks.each { |hook| instance_exec(&hook) }
+      when :around
+        result = hooks.reverse.inject(block) do |acc, hook|
+          proc { instance_exec(acc, &hook) }
+        end.call
+      when :after
+        hooks.each { |hook| instance_exec(result, &hook) }
+      end
+
+      result
+    end
+  end
+end

data/lib/gaskit/logger.rb

@@ -123,10 +123,11 @@ module Gaskit
         lambda do |severity, time, _progname, msg|
           message, context = extract_message_and_context(msg)
           context ||= {}
+          class_name = context.delete(:class)
 
           tags = %W[[#{time.utc.iso8601}] [#{severity}]]
-          tags << "[#{context[:class]}]" if context[:class]
-          tags += context.map { |k, v| "[#{k}=#{v}]" }
+          tags << "[#{class_name}]" if class_name
+          tags += flatten_context(context).map { |k, v| "[#{k}=#{v}]" }
 
           "#{tags.join(" ")} #{message}\n"
         end
@@ -143,18 +144,43 @@ module Gaskit
 
         [msg.to_s, {}]
       end
+
+      # Recursively flattens a nested hash by concatenating keys using underscores.
+      #
+      # @example
+      #   flatten_context({ a: { b: 1, c: { d: 2 } } })
+      #   # => { "a_b" => 1, "a_c_d" => 2 }
+      #
+      # @param hash [Hash] The hash to flatten.
+      # @param prefix [String, nil] The prefix to prepend to keys (used during recursion).
+      # @return [Hash] A flat hash with underscore-separated keys.
+      def flatten_context(hash, prefix = nil)
+        result = {}
+
+        hash.each do |key, value|
+          full_key = prefix ? "#{prefix}_#{key}" : key.to_s
+
+          if value.is_a?(Hash)
+            result.merge!(flatten_context(value, full_key))
+          else
+            result[full_key] = value
+          end
+        end
+
+        result
+      end
     end
 
     attr_reader :context
 
     # Initializes a new logger instance.
     #
-    # @param klass [Class] The name of the class being logged.
+    # @param klass [Class, Object, String, Symbol] The name of the class being logged.
     # @param context [Hash] Optional additional context to include in every log entry.
     def initialize(klass, context: {})
-      @class_name = resolve_name(klass)
-      @context = apply_context(context)
+      @class_name = Gaskit::Helpers.resolve_name(klass)
 
+      @context = apply_context(context).merge(class: @class_name)
       @logger = Gaskit.configuration.logger || ::Logger.new($stdout)
     rescue StandardError
       ::Logger.new($stdout).error "Failed to initialize logger: #{$ERROR_INFO}"
@@ -226,20 +252,6 @@ module Gaskit
 
     private
 
-    # Resolves the class name provided when instantiating the logger.
-    #
-    # @return [String] The resolved class name.
-    def resolve_name(source)
-      case source
-      when String, Symbol
-        source.to_s
-      when Class
-        source.name
-      else
-        source.class.name
-      end
-    end
-
     def apply_context(context)
       default_context = Gaskit.configuration.context_provider.call
       context = default_context.merge(context)

data/lib/gaskit/operation.rb

@@ -4,16 +4,14 @@ require_relative "core"
 require_relative "operation_result"
 require_relative "operation_exit"
 require_relative "helpers"
+require_relative "hookable"
 
 module Gaskit
   # The Gaskit::Operation class defines a structured and extensible pattern for building application operations.
   # It enforces consistent behavior across operations while supporting customization via contracts.
   #
   # # Features
-  # - Pluggable contracts via `use_contract`, allowing you to define or reference a `result` and
-  #   `early_exit` class.
-  # - A **contract** is a pairing of a result and early_exit class, either manually defined or registered
-  #   under a symbol.
+  # - Pluggable contracts via `use_contract`, allowing you to define or reference a `result` class.
   # - Integrated duration tracking, structured logging, and early exits.
   # - Supports `.call` (non-raising) and `.call!` (raising) styles.
   #
@@ -50,6 +48,8 @@ module Gaskit
   #
   # @abstract Subclass this and define `#call` or `#call!` to create a new operation.
   class Operation
+    include Gaskit::Hookable
+
     class << self
       def result_class
         return @result_class if defined?(@result_class) && @result_class
@@ -58,30 +58,26 @@ module Gaskit
         nil
       end
 
-      # Defines the result and early exit classes for this operation.
-      # Can reference a named contract registered in `Gaskit::Registry`, override either part manually,
-      # or define both without using a named contract.
+      # Defines the result class for this operation.
+      # Can reference a named contract registered in `Gaskit::Registry`, or define one without
+      # using a registered contract.
       #
       # @example Use a registered contract
       #   use_contract :service
       #
-      # @example Override only result class
-      #   use_contract :service, result: CustomResult
-      #
-      # @example Define both without using a contract name
-      #   use_contract result: CustomResult, early_exit: CustomExit
+      # @example Define a contract that has not been registered
+      #   use_contract result: CustomResult
       #
       # @param contract [Symbol, nil] A registered contract name (e.g., `:service`)
       # @param result [Class, nil] A class that inherits from `Gaskit::BaseResult`
       # @raise [ArgumentError] if contract is not a symbol or unexpected args are passed
       # @raise [ResultTypeError] if `result` is not a subclass of `Gaskit::BaseResult`
-      # @raise [EarlyExitTypeError] if `early_exit` is not a subclass of `Gaskit::BaseExit`
       # @return [void]
       def use_contract(contract = nil, result: nil)
         if contract
           raise ArgumentError, "use_contract must be called with a symbol or keyword args" unless contract.is_a?(Symbol)
 
-          result = Gaskit.fetch_contract(contract)
+          result = Gaskit.contracts.fetch(contract)
         end
 
         Gaskit::ContractRegistry.verify_result_class!(result)
@@ -98,6 +94,10 @@ module Gaskit
       # @param code [String, nil] Optional error code.
       # @return [void]
       def error(key, message, code: nil)
+        raise ArgumentError, "Error key must be a symbol or a string, received #{key}" unless key.is_a?(Symbol)
+        raise ArgumentError, "Error message must be a string" unless message.is_a?(String)
+        raise ArgumentError, "Error key :#{key} is already registered" if errors_registry.key?(key)
+
         errors_registry[key.to_sym] = { message: message, code: code }
       end
 
@@ -108,24 +108,24 @@ module Gaskit
         @errors_registry ||= {}
       end
 
-      # Execute the operation without raising an exception on failure.
+      # Executes the operation with soft-failure handling
       #
-      # @param [Array] args Positional arguments passed.
-      # @param [Hash] kwargs Keyword arguments passed (with optional :context).
-      # @yield [Block] Additional block logic to pass during the operation.
-      # @return [OperationResult] The result of the operation.
-      def call(*args, **kwargs, &block)
-        invoke(false, *args, **kwargs, &block)
+      # @param args [Array] Positional arguments for the first step
+      # @param context [Hash] Shared context across all steps
+      # @param kwargs [Hash] Keyword arguments for the first step
+      # @return [Gaskit::OperationResult]
+      def call(*args, context: {}, **kwargs, &block)
+        invoke(false, context, *args, **kwargs, &block)
       end
 
-      # Execute the operation with raising an exception on failure.
+      # Executes the operation with hard-failure handling (raises on unhandled errors)
       #
-      # @param [Array] args Positional arguments passed.
-      # @param [Hash] kwargs Keyword arguments passed (with optional :context).
-      # @yield [Block] Additional block logic to pass during the operation.
-      # @return [OperationResult] The result of the operation.
-      def call!(*args, **kwargs, &block)
-        invoke(true, *args, **kwargs, &block)
+      # @param args [Array] Positional arguments for the first step
+      # @param context [Hash] Shared context across all steps
+      # @param kwargs [Hash] Keyword arguments for the first step
+      # @return [Gaskit::OperationResult]
+      def call!(*args, context: {}, **kwargs, &block)
+        invoke(true, context, *args, **kwargs, &block)
       end
 
       private
@@ -138,21 +138,26 @@ module Gaskit
       # @yield [Block] Additional block logic during execution.
       # @raise [NotImplementedError] If operation type is not set in subclasses.
       # @return [OperationResult] The result of the operation.
-      def invoke(raise_on_failure, *args, **kwargs, &block)
+      def invoke(raise_on_failure, context, *args, **kwargs, &block)
         unless result_class
           raise NotImplementedError, "No result_class defined for #{name} or its ancestors. " \
                                      "Did you forget to call `use_contract`?"
         end
 
-        context = kwargs.delete(:context) || {}
         operation = new(raise_on_failure, context: context)
         duration, (result, error) = execute(operation, *args, **kwargs, &block)
 
-        operation.logger.debug(context: { duration: duration }) do
-          "Operation completed in #{duration} seconds"
+        result = build_result(result, error, duration, operation.context)
+
+        begin
+          operation.apply_after_hooks(result)
+        rescue StandardError => e
+          result = handle_after_hook_error(operation, result, e, duration)
         end
 
-        result_class.new(error.nil?, result, error, duration: duration, context: context)
+        log_execution_debug(operation, duration)
+
+        result
       end
 
       # Executes the operation logic and handles potential exceptions.
@@ -164,16 +169,40 @@ module Gaskit
       # @return [Array] The execution duration, result, and error if any.
       def execute(operation, *args, **kwargs, &block)
         Helpers.time_execution do
-          [operation.call(*args, **kwargs, &block), nil]
+          operation.apply_hooks(:before, :around) do
+            [operation.call(*args, **kwargs, &block), nil]
+          end
         rescue StandardError => e
-          if e.is_a?(Gaskit::OperationExit)
-            log_exit(operation, e)
-          else
-            log_exception(operation, e)
-            raise e if operation.raise_on_failure
+          handle_execution_error(operation, e)
+        end
+      end
 
-          end
-          [nil, e]
+      # Builds an OperationResult instance.
+      #
+      # @param [Object, nil] result The result of the operation.
+      # @param [StandardError] error The error, if any.
+      # @param [Float] duration The duration of the operation.
+      # @param [Gaskit::Context] context The operation context.
+      # @return [OperationResult]
+      def build_result(result, error, duration, context)
+        result_class.new(
+          error.nil?,
+          result,
+          error,
+          duration: duration,
+          context: context
+        )
+      end
+
+      # Logs execution information about the operation if Gaskit.debug? == true.
+      #
+      # @param [Gaskit::Operation] operation The operation instance.
+      # @param [Float] duration The operation's duration.
+      def log_execution_debug(operation, duration)
+        return unless Gaskit.debug?
+
+        operation.logger.debug(context: { duration: duration }) do
+          "Operation completed in #{duration} seconds"
         end
       end
 
@@ -189,16 +218,40 @@ module Gaskit
       # Logs any unhandled exception during the operation.
       #
       # @param [Gaskit::Operation] operation The operation instance.
-      # @param [Exception] exception The raised exception.
+      # @param [StandardError] exception The raised exception.
       # @return [void]
       def log_exception(operation, exception)
         operation.logger.error { "[#{exception.class}] #{exception.message}" }
         operation.logger.error { exception.backtrace&.join("\n") }
       end
 
-      # @return [String] The name of the operation class (e.g., "MyOperation").
-      def operation_name
-        @operation_name ||= self.class.name.to_s
+      # Handles exceptions during execution.
+      #
+      # @param [Gaskit::Operation] operation The operation instance.
+      # @param [StandardError] error The raised error.
+      # @return [Array] The result and the error.
+      def handle_execution_error(operation, error)
+        if error.is_a?(Gaskit::OperationExit)
+          log_exit(operation, error)
+        else
+          log_exception(operation, error)
+          raise error if operation.raise_on_failure?
+        end
+
+        [nil, error]
+      end
+
+      # Handles errors raised after executing hooks.
+      #
+      # @param [Gaskit::Operation] operation The operation instance.
+      # @param [OperationResult] result The current operation result.
+      # @param [StandardError] error The encountered error.
+      # @param [Float] duration The execution duration.
+      def handle_after_hook_error(operation, result, error, duration)
+        log_exception(operation, error)
+        raise error if operation.raise_on_failure?
+
+        build_result(result, error, duration, operation.context)
       end
     end
 
@@ -212,16 +265,15 @@ module Gaskit
     def initialize(raise_on_failure, context: {})
       @raise_on_failure = raise_on_failure
       @context = apply_context(context)
-      @logger = Gaskit::Logger.new(self.class, context: @context)
+      @logger = Gaskit::Logger.new(self, context: @context)
+
+      return unless self.class.result_class.nil?
+
+      raise Gaskit::Error, "No result_class defined for #{self.class.name} or its ancestors."
     end
 
-    # Applies global context, if set, from Gaskit.configuration.context_provider.
-    #
-    # @param context [Hash] The context provided directly to the Flow.
-    # @return [Hash] The fully applied context Hash.
-    def apply_context(context)
-      default_context = Gaskit.configuration.context_provider.call
-      Helpers.deep_compact(default_context.merge(context))
+    def raise_on_failure?
+      @raise_on_failure
     end
 
     # Executes the operation logic.
@@ -239,22 +291,34 @@ module Gaskit
     # If the key was previously registered via `self.error`, it uses the declared message and code.
     # Otherwise, it uses the key as the message.
     #
-    # @param exit_key [Symbol] The symbolic reason for exiting.
+    # @param error_key [Symbol] The symbolic reason for exiting.
     # @param message [String, nil] Optional message override.
+    # @param code [String, nil] Optional error code.
     # @raise [OperationExit] always raises an instance with message and optional code
-    def exit(exit_key, message = nil)
-      exit_key = exit_key.to_sym
-      definition = self.class.errors_registry[exit_key]
+    def exit(error_key, message = nil, code: nil)
+      error_key = error_key.to_sym
+      definition = self.class.errors_registry.fetch(error_key, nil)
 
       if definition
         message ||= definition[:message]
-        code = definition[:code]
+        code ||= definition[:code]
       end
 
-      raise OperationExit.new(exit_key, message, code: code)
+      raise OperationExit.new(error_key, message, code: code)
     end
 
     # @see #exit
     alias abort exit
+
+    private
+
+    # Applies global context, if set, from Gaskit.configuration.context_provider.
+    #
+    # @param context [Hash] The context provided directly to the Flow.
+    # @return [Hash] The fully applied context Hash.
+    def apply_context(context = {})
+      default_context = Gaskit.configuration.context_provider.call
+      Helpers.deep_compact(default_context.merge(context))
+    end
   end
 end

data/lib/gaskit/operation_exit.rb

@@ -31,9 +31,13 @@ module Gaskit
     # @param message [String, nil] A human-readable message (defaults to key if not provided)
     # @param code [String, nil] A structured error code for analytics or debugging
     def initialize(key, message = nil, code: nil)
-      super(message || key.to_s)
+      super(message || "early exit")
       @key = key
       @code = code
     end
+
+    def inspect
+      "#<#{self.class} key=#{key.inspect} message=#{message.inspect} code=#{code.inspect}>"
+    end
   end
 end

data/lib/gaskit/operation_result.rb

@@ -30,11 +30,11 @@ module Gaskit
 
     # 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.
+    # @param success [Boolean] Whether the operation was successful.
+    # @param value [Object, nil] The value obtained as a result of the operation.
+    # @param error [StandardError, nil] The error encountered during the operation.
+    # @param duration [Float, String] The time taken to complete the operation in seconds.
+    # @param context [Hash] Optional context metadata for this operation.
     def initialize(success, value, error, duration:, context: {})
       @success = success
       @value = value
@@ -47,7 +47,7 @@ module Gaskit
     #
     # @return [String] The formatted inspection string.
     def inspect
-      "#<#{self.class.name} success=#{success?} value=#{value.inspect} duration=#{duration}>"
+      "#<#{self.class.name} status=#{status} value=#{value.inspect} duration=#{duration}>"
     end
 
     # Indicates whether the operation was successful.

data/lib/gaskit/version.rb

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

data/lib/gaskit.rb

@@ -27,7 +27,7 @@ require_relative "gaskit/railtie" if defined?(Rails::Railtie)
 #   end
 #
 # @example Registering a contract
-#   Gaskit.register_contract(:service, MyResultClass)
+#   Gaskit.contracts.register(:service, MyResultClass)
 #
 # @example Defining a service
 #   class MyService < Gaskit::Service

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gaskit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nathan Lucas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-09 00:00:00.000000000 Z
+date: 2025-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -83,6 +83,7 @@ files:
 - LICENSE.txt
 - README.md
 - gasket-0.1.0.gem
+- gaskit-0.1.0.gem
 - gaskit.gemspec
 - lib/gaskit.rb
 - lib/gaskit/boot/query.rb
@@ -94,6 +95,8 @@ files:
 - lib/gaskit/flow.rb
 - lib/gaskit/flow_result.rb
 - lib/gaskit/helpers.rb
+- lib/gaskit/hook_registry.rb
+- lib/gaskit/hookable.rb
 - lib/gaskit/logger.rb
 - lib/gaskit/operation.rb
 - lib/gaskit/operation_exit.rb