next_station 0.1.0

data/lib/next_station/operation.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+require_relative 'operation/errors'
+require_relative 'operation/node'
+require_relative 'operation/class_methods'
+
+module NextStation
+  # The core class for defining operations.
+  #
+  # Operations are composed of steps and branches, and they return a NextStation::Result.
+  class Operation
+    extend ClassMethods
+
+    errors do
+      error_type :validation do
+        message en: 'One or more parameters are invalid. See validation details.',
+                sp: 'Uno o más parámetros son inválidos. Ver detalles de validación.'
+      end
+    end
+
+    # @example Example usage, simple initialization:
+    #   CreateUser.new
+    # Use ` .new(deps: ...) ` to inject dependencies (e.g. test doubles).
+    # @example Example usage, `.new` with override of dependencies:
+    #   # Assuming Mailer is a class that sends emails:
+    #   # class CreateUser < NextStation::Operation
+    #   #   depends mailer: -> { Mailer.new }
+    #   #   # rest of the class definition
+    #   # end
+    #   #
+    #   # You can then inject the mock mailer in tests:
+    #   mock_mailer = mock('mailer')
+    #   CreateUser.new(deps: { mailer: mock_mailer })
+    # @param deps [Hash] Allows to override the default dependencies.
+    def initialize(deps: {})
+      @injected_deps = deps
+      @resolved_deps = {}
+    end
+
+    # Resolves a dependency by name.
+    # @param name [Symbol]
+    # @return [Object] The resolved dependency.
+    def dependency(name)
+      return @resolved_deps[name] if @resolved_deps.key?(name)
+
+      if @injected_deps.key?(name)
+        @resolved_deps[name] = @injected_deps[name]
+      else
+        default = self.class.dependencies.fetch(name)
+        @resolved_deps[name] = default.is_a?(Proc) ? default.call : default
+      end
+    end
+
+    # Executes the operation.
+    # @param params [Hash] Input parameters.
+    # @param context [Hash] Execution context (e.g. :lang).
+    # @example operation.call(name: 'john', age: 25)
+    # @example operation.call(params: { name: 'john', age: 25 }, context: { lang: :en })
+    # @return [NextStation::Result]
+    def call(params = {}, context = {})
+      monitor = NextStation.config.monitor
+
+      monitor.publish('operation.start', operation: self.class.name, params: params, context: context)
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      if self.class.validation_enforced? && !self.class.has_step?(:validation)
+        raise ValidationError, 'Validation is enforced but step :validation is missing from process block'
+      end
+
+      @state = State.new(params, context, self.class.loaded_plugins)
+      lang = context[:lang] || :en
+
+      self.class.loaded_plugins.each do |mod|
+        mod.on_operation_start(self, @state) if mod.respond_to?(:on_operation_start)
+      end
+
+      begin
+        @state = execute_nodes(self.class.steps, @state)
+      rescue Halt => e
+        result = if e.error
+                   Result::Failure.new(e.error)
+                 else
+                   definition = self.class.error_definitions[e.type]
+                   raise "Undeclared error type: #{e.type}" unless definition
+
+                   message = definition.resolve_message(lang, e.msg_keys)
+                   Result::Failure.new(
+                     Result::Error.new(
+                       type: e.type,
+                       message: message,
+                       help_url: definition.help_url,
+                       details: e.details,
+                       msg_keys: e.msg_keys
+                     )
+                   )
+                 end
+
+        self.class.loaded_plugins.each do |mod|
+          mod.on_operation_stop(self, result) if mod.respond_to?(:on_operation_stop)
+        end
+
+        monitor.publish('operation.stop',
+                        operation: self.class.name,
+                        duration: duration(start_time),
+                        result: result,
+                        state: @state)
+        return result
+      rescue NextStation::ValidationError => e
+        raise e
+      rescue NextStation::Error => e
+        raise e
+      rescue StandardError => e
+        result = Result::Failure.new(
+          Result::Error.new(
+            type: :exception,
+            message: e.message,
+            details: { backtrace: e.backtrace }
+          )
+        )
+
+        self.class.loaded_plugins.each do |mod|
+          mod.on_operation_stop(self, result) if mod.respond_to?(:on_operation_stop)
+        end
+
+        monitor.publish('operation.stop',
+                        operation: self.class.name,
+                        duration: duration(start_time),
+                        result: result,
+                        state: @state)
+        return result
+      end
+
+      key = self.class.result_key || :result
+      unless @state.key?(key)
+        raise NextStation::MissingResultKeyError, "Missing result key #{key.inspect} in state. " \
+                                                 'Operations must set this key or use result_at to specify another one.'
+      end
+
+      result = Result::Success.new(
+        @state[key],
+        schema: self.class.result_class,
+        enforced: self.class.schema_enforced?
+      )
+
+      self.class.loaded_plugins.each do |mod|
+        mod.on_operation_stop(self, result) if mod.respond_to?(:on_operation_stop)
+      end
+
+      monitor.publish('operation.stop',
+                      operation: self.class.name,
+                      duration: duration(start_time),
+                      result: result,
+                      state: @state)
+      result
+    end
+
+    # Built-in step for performing validation.
+    # @param state [NextStation::State]
+    # @return [NextStation::State]
+    def validation(state)
+      contract_class = self.class.validation_contract_class
+      raise ValidationError, 'Step :validation called but no contract defined via validate_with' unless contract_class
+
+      return state unless self.class.validation_enforced?
+
+      lang = state.context[:lang] || :en
+      contract = self.class.validation_contract_instance
+      result = contract.call(state.params)
+
+      if result.success?
+        state[:params] = result.to_h
+        state
+      else
+        # Attempt to get localized errors from dry-validation, fallback to default if it fails
+        # (e.g. if I18n is not configured for that language in dry-validation)
+        validation_errors = begin
+          result.errors(locale: lang).to_h
+        rescue StandardError
+          result.errors.to_h
+        end
+
+        error!(
+          type: :validation,
+          msg_keys: { errors: validation_errors }.merge(state.params),
+          details: validation_errors
+        )
+      end
+    end
+
+    # Halts the operation and returns a failure result.
+    # @param type [Symbol]
+    # @param msg_keys [Hash]
+    # @param details [Hash]
+    def error!(type:, msg_keys: {}, details: {})
+      raise Halt.new(type: type, msg_keys: msg_keys, details: details)
+    end
+
+    # Publishes a log event to the default monitor.
+    #
+    # NextStation provides a built-in event system powered by dry-monitor to track user-defined logs.
+    # Inside your operation steps, you can use publish_log to broadcast custom events.
+    # These are automatically routed to the configured logger by default.
+    #
+    # By default, NextStation logs to STDOUT using the standard Ruby Logger.
+    # @param [Symbol] level The log level.
+    # @option level [Symbol] :info Informational message
+    # @option level [Symbol] :warn  Warning condition
+    # @option level [Symbol] :error Error condition
+    # @option level [Symbol] :fatal Fatal error
+    # @option level [Symbol] :debug Debugging message
+    # @param message [String] The log message.
+    # @param payload [Hash] Additional metadata for the log.
+    # @example publish_log :info, 'simple log message'
+    # @example publish_log :info, 'log with custom payload', user_id: 5, hello: 'world'
+    def publish_log(level, message, payload = {})
+      NextStation.config.monitor.publish(
+        'log.custom',
+        level: level,
+        message: message,
+        operation: self.class.name,
+        step_name: @state&.current_step,
+        payload: payload
+      )
+    end
+
+    # Calls another operation and integrates its result into the current state.
+    # @param state [NextStation::State]
+    # @param operation_class [Class, Object] The operation to call.
+    # @param with_params [Hash, Proc] Params for the child operation.
+    # @param store_result_in_key [Symbol, nil] Where to store the child's result value.
+    # @return [NextStation::State]
+    def call_operation(state, operation_class, with_params:, store_result_in_key: nil)
+      params = with_params.is_a?(Proc) ? with_params.call(state) : with_params
+
+      operation = if operation_class.is_a?(Class)
+                    operation_class.new(deps: @injected_deps)
+                  else
+                    operation_class
+                  end
+
+      result = operation.call(params, state.context)
+
+      if result.success?
+        state[store_result_in_key] = result.value if store_result_in_key
+        state
+      else
+        child_error = result.error
+        raise Halt.new(error: child_error) unless self.class.error_definitions.key?(child_error.type)
+
+        error!(
+          type: child_error.type,
+          msg_keys: child_error.msg_keys,
+          details: child_error.details
+        )
+
+      end
+    end
+
+    private
+
+    def duration(start_time)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+    end
+
+    def execute_nodes(nodes, state)
+      nodes.reduce(state) do |current_state, node|
+        execute_node(node, current_state)
+      end
+    end
+
+    def execute_node(node, state)
+      case node.type
+      when :step
+        execute_step(node, state)
+      when :branch
+        execute_branch(node, state)
+      when :wrapper
+        handler = node.options[:handler]
+        send(handler, node, state)
+      else
+        state
+      end
+    end
+
+    def execute_step(node, state)
+      skip_condition = node.options[:skip_if]
+      return state if skip_condition&.call(state)
+
+      state.set_current_step(node.name)
+
+      retry_if = node.options[:retry_if]
+      max_attempts = node.options[:attempts] || 1
+      delay = node.options[:delay] || 0
+      attempts = 0
+      monitor = NextStation.config.monitor
+
+      loop do
+        attempts += 1
+        state.set_step_attempt(attempts)
+
+        monitor.publish('step.start', operation: self.class.name, step: node.name, state: state, attempt: attempts)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          result = wrap_in_hooks(node, state) do |current_state|
+            send(node.name, current_state)
+          end
+
+          unless result.is_a?(NextStation::State)
+            class_name = self.class.name || 'AnonymousOperation'
+            raise NextStation::StepReturnValueError,
+                  "Step '#{node.name}' in #{class_name} must return a NextStation::State object, but it returned #{result.class} (#{result.inspect})."
+          end
+
+          if retry_if && attempts < max_attempts && retry_if.call(result, nil)
+            monitor.publish('step.retry',
+                            operation: self.class.name,
+                            step: node.name,
+                            state: result,
+                            attempt: attempts,
+                            duration: duration(start_time))
+            sleep(delay) if delay.positive?
+            next
+          end
+
+          self.class.loaded_plugins.each do |mod|
+            mod.on_step_success(self, node, result) if mod.respond_to?(:on_step_success)
+          end
+
+          monitor.publish('step.stop',
+                          operation: self.class.name,
+                          step: node.name,
+                          state: result,
+                          attempt: attempts,
+                          duration: duration(start_time))
+          return result
+        rescue StandardError => e
+          if retry_if && attempts < max_attempts && retry_if.call(state, e)
+            monitor.publish('step.retry',
+                            operation: self.class.name,
+                            step: node.name,
+                            state: state,
+                            attempt: attempts,
+                            error: e,
+                            duration: duration(start_time))
+            sleep(delay) if delay.positive?
+            next
+          end
+
+          self.class.loaded_plugins.each do |mod|
+            mod.on_step_failure(self, node, state, e) if mod.respond_to?(:on_step_failure)
+          end
+
+          monitor.publish('step.stop',
+                          operation: self.class.name,
+                          step: node.name,
+                          state: state,
+                          attempt: attempts,
+                          error: e,
+                          duration: duration(start_time))
+          raise e
+        end
+      end
+    end
+
+    def execute_branch(node, state)
+      condition = node.options[:condition]
+      if condition.call(state)
+        execute_nodes(node.children, state)
+      else
+        state
+      end
+    end
+
+    def wrap_in_hooks(node, state, &block)
+      around_hooks = self.class.loaded_plugins.select { |p| p.respond_to?(:around_step) }
+      run_around_hooks(around_hooks, node, state, &block)
+    end
+
+    def run_around_hooks(hooks, node, state, &block)
+      if hooks.empty?
+        yield state
+      else
+        hook = hooks.first
+        remaining = hooks[1..]
+        hook.around_step(self, node, state) do
+          run_around_hooks(remaining, node, state, &block)
+        end
+      end
+    end
+  end
+end

data/lib/next_station/plugins.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module NextStation
+  # Central registry for NextStation plugins.
+  module Plugins
+    @registry = {}
+
+    # Registers a plugin.
+    # @param name [Symbol] The plugin name.
+    # @param mod [Module] The plugin module.
+    def self.register(name, mod)
+      @registry[name] = mod
+    end
+
+    # Loads a plugin by name.
+    # @param name [Symbol]
+    # @return [Module]
+    # @raise [KeyError] If the plugin is not registered.
+    def self.load_plugin(name)
+      @registry.fetch(name)
+    end
+  end
+end

data/lib/next_station/result.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module NextStation
+  # Represents the result of an operation.
+  class Result
+    # @example result.success? => true
+    # @example result.success? => false
+    # @return [Boolean] true if the result is a success.
+    def success?
+      false
+    end
+
+    # @example result.failure? => true
+    # @example result.failure? => false
+    # @return [Boolean] true if the result is a failure.
+    def failure?
+      false
+    end
+
+    # @return [Object, nil] The value of a successful result.
+    def value
+      nil
+    end
+
+    # @see NextStation::Result::Error
+    # @example result.error => #<NextStation::Result::Error: ...>
+    # @example Example methods inside of an NextStation::Result::Error
+    #   result.error.type
+    #   result.error.message
+    #   result.error.details
+    # @return [NextStation::Result::Error, nil] The error object if it's a failure.
+    def error
+      nil
+    end
+
+    # Represents a successful operation result.
+    class Success < Result
+      # @param value [Object] The result value.
+      # @param schema [Class, nil] The Dry::Struct schema to validate against.
+      # @param enforced [Boolean] Whether schema validation is enforced.
+      def initialize(value, schema: nil, enforced: false)
+        @raw_value = value
+        @schema = schema
+        @enforced = enforced
+        @validated_value = nil
+      end
+
+      def value
+        if @enforced && @schema.nil?
+          raise NextStation::Error, 'Result schema enforcement is enabled but no result_schema is defined.'
+        end
+
+        return @raw_value unless @enforced && @schema
+
+        @value ||= begin
+          @schema.new(@raw_value)
+        rescue StandardError => e
+          raise NextStation::ResultShapeError, e.message
+        end
+      end
+
+      def success?
+        true
+      end
+    end
+
+    # Represents a failed operation result.
+    class Failure < Result
+      attr_reader :error
+
+      # @param error [NextStation::Result::Error]
+      def initialize(error)
+        @error = error
+      end
+
+      def failure?
+        true
+      end
+    end
+
+    # Structured error information.
+    class Error
+      # The error type.
+      # @example :invalid_input
+      # @example :not_found
+      # @example :email_taken
+      # @return [Symbol]
+      attr_reader :type
+
+      # A human-readable message describing the error.
+      # @example "Email is already taken"
+      # @example "User not found"
+      # @example "Something went wrong, please try again."
+      # @return [String, nil]
+      attr_reader :message
+
+      # An optional URL to help the end user resolve the error.
+      # @example "https://example.com/help/invalid_input"
+      # @return [String, nil]
+      attr_reader :help_url
+
+      # Additional error details.
+      # @example { age: ["must be greater than 18"] }
+      # @example { existing_email: true }
+      # @return [Hash]
+      attr_reader :details
+      # @return [Hash]
+      attr_reader :msg_keys
+
+      # @param type [Symbol]
+      # @param message [String, nil]
+      # @param help_url [String, nil]
+      # @param details [Hash]
+      # @param msg_keys [Hash]
+      def initialize(type:, message: nil, help_url: nil, details: {}, msg_keys: {})
+        @type = type
+        @message = message
+        @help_url = help_url
+        @details = details
+        @msg_keys = msg_keys
+      end
+    end
+  end
+end

data/lib/next_station/state.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module NextStation
+  # Holds the mutable state during operation execution.
+  #
+  # It wraps a data hash and provides access to params and context.
+  class State
+    extend Forwardable
+    def_delegators :@data, :[], :[]=, :fetch, :key?, :has_key?, :to_h, :merge, :merge!
+
+    # @return [Hash] The execution context.
+    attr_reader :context
+    # @return [Integer] The attempt number of the current step.
+    attr_reader :step_attempt
+    # @return [Symbol, nil] The name of the current step being executed.
+    attr_reader :current_step
+
+    # @param params [Hash] Initial parameters.
+    # @param context [Hash] Shared context (immutable).
+    def initialize(params = {}, context = {}, plugins = [])
+      @context = context.dup.freeze
+      @data = { params: unwrap_params(params).dup }
+      @step_attempt = 1
+      @current_step = nil
+      extend_with_plugins(plugins)
+    end
+
+    # Sets the current attempt number for the active step.
+    # @param value [Integer]
+    def set_step_attempt(value)
+      @step_attempt = value
+    end
+    
+    # Sets the name of the current step.
+    # @param value [Symbol, nil]
+    def set_current_step(value)
+      @current_step = value
+    end
+
+    # Returns the input parameters.
+    # @return [Hash]
+    def params
+      @data[:params]
+    end
+
+    private
+
+    def unwrap_params(params)
+      if params.is_a?(Hash) && params.key?(:params) && params.keys.size == 1
+        params[:params]
+      else
+        params
+      end
+    end
+
+    def extend_with_plugins(plugins)
+      plugins.each do |mod|
+        extend mod::State if mod.const_defined?(:State)
+      end
+    end
+  end
+end

data/lib/next_station/types.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'dry-types'
+
+module NextStation
+  module Types
+    include Dry.Types
+    StrippedString = Types::String.constructor(&:strip)
+    Email = Types::String.constructor { |v| v.strip.downcase }.constrained(format: /\A[^@\s]+@[^@\s]+\z/)
+  end
+end

data/lib/next_station/version.rb

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

data/lib/next_station.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'next_station/config'
+
+# NextStation is a lightweight, service-object like framework for Ruby
+# that emphasizes structured operations, railway-oriented programming,
+# and strong validation.
+module NextStation
+
+ # Base error class for all NextStation errors
+  class Error < StandardError; end
+
+  # Raised when a step method returns something other than a NextStation::State object.
+  # This ensures that the Railway flow is maintained throughout the operation.
+  class StepReturnValueError < Error; end
+
+  # Raised when the operation finishes but the expected result key is missing from the state.
+  class MissingResultKeyError < Error; end
+
+  # Raised when the result does not match the defined schema.
+  class ResultShapeError < Error; end
+
+  # Raised when both a Dry::Struct class and a block are provided to result_schema.
+  class DoubleResultSchemaError < Error; end
+
+  # Raised when there is a configuration error related to validations.
+  class ValidationError < Error; end
+end
+
+require_relative 'next_station/version'
+require_relative 'next_station/types'
+require_relative 'next_station/errors'
+require_relative 'next_station/plugins'
+require_relative 'next_station/state'
+require_relative 'next_station/result'
+require_relative 'next_station/operation'