easyop 0.1.0

data/lib/easyop/configuration.rb

@@ -0,0 +1,31 @@
+module Easyop
+  class Configuration
+    # Which type adapter to use for Schema validation.
+    # Options: :none, :native, :literal, :dry, :active_model
+    attr_accessor :type_adapter
+
+    # When true, type mismatches in schemas raise Ctx::Failure.
+    # When false (default), mismatches emit a warning and execution continues.
+    attr_accessor :strict_types
+
+    def initialize
+      @type_adapter = :native
+      @strict_types = false
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Reset config (useful in tests)
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/easyop/ctx.rb

@@ -0,0 +1,187 @@
+module Easyop
+  # Easyop::Ctx is the shared data bag passed through an operation (or flow of
+  # operations). It replaces Interactor's Context with a faster, Hash-backed
+  # implementation that avoids the deprecated OpenStruct.
+  #
+  # It doubles as the result object returned from Operation.call — the caller
+  # inspects ctx.success? / ctx.failure? and reads output attributes directly.
+  #
+  # Key API:
+  #   ctx.fail!                       # mark failed (raises Ctx::Failure internally)
+  #   ctx.fail!(error: "Boom!")        # set attrs AND fail
+  #   ctx.success? / ctx.ok?          # true unless fail! was called
+  #   ctx.failure? / ctx.failed?      # true after fail!
+  #   ctx.error                       # shortcut for ctx[:error]
+  #   ctx.errors                      # shortcut for ctx[:errors] ({} by default)
+  #   ctx[:key] / ctx.key             # attribute read
+  #   ctx[:key] = v / ctx.key = v     # attribute write
+  #   ctx.merge!(hash)                # bulk-set attributes
+  #   ctx.on_success { |ctx| ... }    # chainable callback
+  #   ctx.on_failure { |ctx| ... }    # chainable callback
+  class Ctx
+    # Raised (and swallowed by Operation#run) when fail! is called.
+    # Propagates to callers of Operation#run! and Operation#call!.
+    class Failure < StandardError
+      attr_reader :ctx
+
+      def initialize(ctx)
+        @ctx = ctx
+        super("Operation failed#{": #{ctx.error}" if ctx.error}")
+      end
+    end
+
+    # ── Construction ────────────────────────────────────────────────────────
+
+    def self.build(attrs = {})
+      return attrs if attrs.is_a?(self)
+      new(attrs)
+    end
+
+    def initialize(attrs = {})
+      @attributes  = {}
+      @failure     = false
+      @rolled_back = false
+      @called      = []   # interactors already run (for rollback)
+      attrs.each { |k, v| self[k] = v }
+    end
+
+    # ── Attribute access ─────────────────────────────────────────────────────
+
+    def [](key)
+      @attributes[key.to_sym]
+    end
+
+    def []=(key, val)
+      @attributes[key.to_sym] = val
+    end
+
+    def merge!(attrs = {})
+      attrs.each { |k, v| self[k] = v }
+      self
+    end
+
+    def to_h
+      @attributes.dup
+    end
+
+    def key?(key)
+      @attributes.key?(key.to_sym)
+    end
+
+    # Returns a plain Hash with only the specified keys.
+    def slice(*keys)
+      keys.each_with_object({}) do |k, h|
+        sym = k.to_sym
+        h[sym] = @attributes[sym] if @attributes.key?(sym)
+      end
+    end
+
+    # ── Status ───────────────────────────────────────────────────────────────
+
+    def success?
+      !@failure
+    end
+    alias ok? success?
+
+    def failure?
+      @failure
+    end
+    alias failed? failure?
+
+    # ── Fail! ────────────────────────────────────────────────────────────────
+
+    # Mark the operation as failed. Accepts an optional hash of attributes to
+    # merge into ctx before raising (e.g. error:, errors:).
+    def fail!(attrs = {})
+      merge!(attrs)
+      @failure = true
+      raise Failure, self
+    end
+
+    # ── Error conveniences ───────────────────────────────────────────────────
+
+    def error
+      self[:error]
+    end
+
+    def error=(msg)
+      self[:error] = msg
+    end
+
+    def errors
+      self[:errors] || {}
+    end
+
+    def errors=(hash)
+      self[:errors] = hash
+    end
+
+    # ── Chainable result callbacks ────────────────────────────────────────────
+
+    def on_success
+      yield self if success?
+      self
+    end
+
+    def on_failure
+      yield self if failure?
+      self
+    end
+
+    # ── Rollback support ──────────────────────────────────────────────────────
+
+    # Called by Flow to track which operations have run.
+    def called!(operation)
+      @called << operation
+      self
+    end
+
+    # Roll back already-called operations in reverse order.
+    # Errors in individual rollbacks are swallowed to ensure all run.
+    def rollback!
+      return if @rolled_back
+      @rolled_back = true
+      @called.reverse_each do |op|
+        op.rollback rescue nil
+      end
+    end
+
+    # ── Pattern matching ──────────────────────────────────────────────────────
+
+    # Supports: case result; in { success: true, user: } ...
+    def deconstruct_keys(keys)
+      base = { success: success?, failure: failure? }
+      base.merge(@attributes).then do |all|
+        keys ? all.slice(*keys) : all
+      end
+    end
+
+    # ── Dynamic attribute access (method_missing) ─────────────────────────────
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if key.end_with?("=")
+        self[key.chomp("=")] = args.first
+      elsif key.end_with?("?")
+        base = key.chomp("?").to_sym
+        return !!self[base]
+      elsif @attributes.key?(name.to_sym)
+        self[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key = name.to_s
+      return true if key.end_with?("=")
+      return true if key.end_with?("?")
+      @attributes.key?(name.to_sym) || super
+    end
+
+    def inspect
+      status = @failure ? "FAILED" : "ok"
+      "#<Easyop::Ctx #{@attributes.inspect} [#{status}]>"
+    end
+  end
+end

data/lib/easyop/flow.rb

@@ -0,0 +1,94 @@
+module Easyop
+  # Compose a sequence of operations that share a single ctx.
+  #
+  # If any step calls ctx.fail!, execution halts and rollback runs in reverse.
+  # Each step can define a `rollback` method which will be called on failure.
+  #
+  # Usage:
+  #   class ProcessOrder
+  #     include Easyop::Flow
+  #
+  #     flow ValidateCart, ChargeCard, CreateOrder, NotifyUser
+  #   end
+  #
+  #   result = ProcessOrder.call(user: user, cart: cart)
+  #   result.on_success { |ctx| redirect_to order_path(ctx.order) }
+  #   result.on_failure { |ctx| flash[:alert] = ctx.error }
+  #
+  # Steps are run via `.call!` so a failure raises and stops the chain.
+  # Individual steps can also be conditionally skipped:
+  #
+  #   flow ValidateCart,
+  #        -> (ctx) { ctx.coupon_code? },  ApplyCoupon,   # conditional
+  #        ChargeCard,
+  #        CreateOrder
+  #
+  # A Lambda/Proc before a step is treated as a guard — the step only runs
+  # if the lambda returns truthy when called with ctx.
+  module Flow
+    # Prepended so that Flow's `call` takes precedence over Operation's no-op
+    # even though Operation is included inside Flow.included (which would
+    # otherwise place Operation earlier in the ancestor chain than Flow itself).
+    module CallBehavior
+      def call
+        pending_guard = nil
+
+        self.class._flow_steps.each do |step|
+          if step.is_a?(Proc)
+            pending_guard = step
+            next
+          end
+
+          # Evaluate lambda guard if present (placed before step in flow list)
+          if pending_guard
+            skip = !pending_guard.call(ctx)
+            pending_guard = nil
+            next if skip
+          end
+
+          # Evaluate class-level skip_if predicate declared on the step itself
+          next if step.respond_to?(:skip?) && step.skip?(ctx)
+
+          instance = step.new
+          instance._easyop_run(ctx, raise_on_failure: true)
+          ctx.called!(instance)
+        end
+      rescue Ctx::Failure
+        ctx.rollback!
+        raise
+      end
+    end
+
+    def self.included(base)
+      base.include(Operation)
+      base.extend(ClassMethods)
+      base.prepend(CallBehavior)
+    end
+
+    module ClassMethods
+      # Declare the ordered list of operation classes (and optional guards).
+      def flow(*steps)
+        @_flow_steps = steps.flatten
+      end
+
+      def _flow_steps
+        @_flow_steps ||= []
+      end
+
+      # Returns a FlowBuilder for pre-registering callbacks before .call.
+      #
+      #   ProcessCheckout.prepare
+      #     .on_success { |ctx| redirect_to order_path(ctx.order) }
+      #     .on_failure { |ctx| flash[:error] = ctx.error }
+      #     .call(user: current_user, cart: current_cart)
+      #
+      #   ProcessCheckout.prepare
+      #     .bind_with(self)
+      #     .on(success: :order_placed, fail: :show_errors)
+      #     .call(user: current_user, cart: current_cart)
+      def prepare
+        FlowBuilder.new(self)
+      end
+    end
+  end
+end

data/lib/easyop/flow_builder.rb

@@ -0,0 +1,80 @@
+module Easyop
+  # FlowBuilder accumulates callbacks before executing a flow.
+  # Returned by FlowClass.flow (no args) and FlowClass.result.
+  #
+  # Usage:
+  #   ProcessCheckout.flow
+  #     .on_success { |ctx| redirect_to order_path(ctx.order) }
+  #     .on_failure { |ctx| flash[:error] = ctx.error; redirect_back }
+  #     .call(user: current_user, cart: current_cart)
+  #
+  #   # With bound object (e.g. a Rails controller):
+  #   ProcessCheckout.flow
+  #     .bind_with(self)
+  #     .on(success: :redirect_to_dashboard, fail: :render_form)
+  #     .call(user: current_user, cart: current_cart)
+  class FlowBuilder
+    def initialize(flow_class)
+      @flow_class        = flow_class
+      @success_callbacks = []
+      @failure_callbacks = []
+      @bound_object      = nil
+    end
+
+    # Register a callback to run when the flow succeeds.
+    def on_success(&block)
+      @success_callbacks << block
+      self
+    end
+
+    # Register a callback to run when the flow fails.
+    def on_failure(&block)
+      @failure_callbacks << block
+      self
+    end
+
+    # Bind a context object for use with symbol shortcuts in `.on(...)`.
+    # Typically `self` in a Rails controller.
+    def bind_with(obj)
+      @bound_object = obj
+      self
+    end
+
+    # Register named-method callbacks. Requires bind_with to have been called
+    # when the methods live on another object.
+    #
+    #   .on(success: :redirect_to_dashboard, fail: :render_form)
+    def on(success: nil, fail: nil)
+      bound = @bound_object
+      if success
+        success_name = success
+        @success_callbacks << ->(ctx) { _invoke_named(bound, success_name, ctx) }
+      end
+      if fail
+        fail_name = fail
+        @failure_callbacks << ->(ctx) { _invoke_named(bound, fail_name, ctx) }
+      end
+      self
+    end
+
+    # Execute the flow with the given attributes, then fire the registered callbacks.
+    # Returns the ctx (Easyop::Ctx).
+    def call(attrs = {})
+      ctx = @flow_class.call(attrs)
+      callbacks = ctx.success? ? @success_callbacks : @failure_callbacks
+      callbacks.each { |cb| cb.call(ctx) }
+      ctx
+    end
+
+    private
+
+    def _invoke_named(obj, name, ctx)
+      if obj
+        m = obj.method(name)
+        m.arity == 0 ? m.call : m.call(ctx)
+      else
+        raise ArgumentError, "bind_with(obj) must be called before using symbol callbacks in .on()"
+      end
+    end
+  end
+end

data/lib/easyop/hooks.rb

@@ -0,0 +1,108 @@
+module Easyop
+  # Lightweight before/after/around hook system with no ActiveSupport dependency.
+  #
+  # Hook lists are inherited — a subclass starts with a copy of its parent's
+  # hooks and may add its own without affecting the parent.
+  #
+  # Usage:
+  #   before :method_name
+  #   before { ctx.email = ctx.email.downcase }
+  #   after  :send_notification
+  #   around :with_logging
+  #   around { |inner| Sentry.with_scope { inner.call } }
+  #
+  # Execution order:
+  #   around hooks wrap everything (outermost first).
+  #   Inside the around chain: before hooks → call → after hooks.
+  #   after hooks run in an `ensure` block so they always execute.
+  module Hooks
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Add a before hook (method name or block).
+      def before(*methods, &block)
+        methods.each { |m| _before_hooks << m }
+        _before_hooks << block if block_given?
+      end
+
+      # Add an after hook (method name or block).
+      def after(*methods, &block)
+        methods.each { |m| _after_hooks << m }
+        _after_hooks << block if block_given?
+      end
+
+      # Add an around hook (method name or block).
+      # The hook must yield (or call its first argument) to continue the chain.
+      def around(*methods, &block)
+        methods.each { |m| _around_hooks << m }
+        _around_hooks << block if block_given?
+      end
+
+      # Hook lists, inherited from superclass (returns a dup so additions
+      # on a subclass don't pollute the parent).
+      def _before_hooks
+        @_before_hooks ||= _inherited_hooks(:_before_hooks)
+      end
+
+      def _after_hooks
+        @_after_hooks ||= _inherited_hooks(:_after_hooks)
+      end
+
+      def _around_hooks
+        @_around_hooks ||= _inherited_hooks(:_around_hooks)
+      end
+
+      private
+
+      def _inherited_hooks(name)
+        parent = superclass
+        parent.respond_to?(name, true) ? parent.send(name).dup : []
+      end
+    end
+
+    # Run the full hook chain around the user's `call` method.
+    # around hooks wrap before+call+after; after hooks always run (ensure).
+    def with_hooks(&block)
+      inner = proc do
+        run_hooks(self.class._before_hooks)
+        begin
+          block.call
+        ensure
+          run_hooks(self.class._after_hooks)
+        end
+      end
+
+      call_through_around(self.class._around_hooks, inner)
+    end
+
+    private
+
+    def run_hooks(hooks)
+      hooks.each do |hook|
+        case hook
+        when Symbol then send(hook)
+        when Proc   then instance_exec(&hook)
+        end
+      end
+    end
+
+    # Build a nested lambda chain so the first around hook is the outermost.
+    def call_through_around(around_hooks, inner)
+      chain = around_hooks.reverse.reduce(inner) do |acc, hook|
+        proc do
+          case hook
+          when Symbol
+            # Method must accept a block: def with_logging; yield; end
+            send(hook) { acc.call }
+          when Proc
+            # Block receives a callable: around { |inner| ...; inner.call }
+            instance_exec(acc, &hook)
+          end
+        end
+      end
+      chain.call
+    end
+  end
+end

data/lib/easyop/operation.rb

@@ -0,0 +1,115 @@
+module Easyop
+  # The core module. Include this in any class to turn it into an operation.
+  #
+  # Usage:
+  #   class DoSomething
+  #     include Easyop::Operation
+  #
+  #     def call
+  #       ctx.fail!(error: "nope") unless ctx.allowed
+  #       ctx.result = do_work(ctx.input)
+  #     end
+  #   end
+  #
+  #   ctx = DoSomething.call(input: "data", allowed: true)
+  #   ctx.success?  # => true
+  #   ctx.result    # => ...
+  module Operation
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(Hooks)
+      base.include(Rescuable)
+      base.include(Skip)
+      base.include(Schema)
+    end
+
+    # ── Class-level API ───────────────────────────────────────────────────────
+
+    module ClassMethods
+      # Call the operation. Always returns ctx, never raises on ctx.fail!.
+      # Other (unhandled) exceptions propagate normally.
+      def call(attrs = {})
+        new._easyop_run(Ctx.build(attrs), raise_on_failure: false)
+      end
+
+      # Call the operation. Returns ctx on success, raises Ctx::Failure on fail!.
+      def call!(attrs = {})
+        new._easyop_run(Ctx.build(attrs), raise_on_failure: true)
+      end
+
+      # Install a plugin onto this operation class.
+      #
+      #   plugin Easyop::Plugins::Instrumentation
+      #   plugin Easyop::Plugins::Recording, model: OperationLog
+      #   plugin Easyop::Plugins::Async, queue: "operations"
+      #
+      # The plugin must respond to `.install(base_class, **options)`.
+      def plugin(plugin_mod, **options)
+        plugin_mod.install(self, **options)
+        _registered_plugins << { plugin: plugin_mod, options: options }
+      end
+
+      def _registered_plugins
+        @_registered_plugins ||= []
+      end
+    end
+
+    # ── Instance API ─────────────────────────────────────────────────────────
+
+    # The shared context. Available inside `call`, hooks, and rescue handlers.
+    def ctx
+      @ctx
+    end
+
+    # Override this in subclasses.
+    def call
+      # no-op default
+    end
+
+    # Override to add rollback logic for use in Flow.
+    def rollback
+      # no-op default
+    end
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    # @api private — called by ClassMethods.call / call!
+    def _easyop_run(ctx, raise_on_failure:)
+      @ctx = ctx
+      if raise_on_failure
+        _run_raising
+      else
+        _run_safe
+      end
+      ctx
+    end
+
+    private
+
+    # run! — propagates Ctx::Failure to caller
+    def _run_raising
+      with_hooks { call }
+    rescue Ctx::Failure
+      raise
+    rescue => e
+      raise unless rescue_with_handler(e)
+    end
+
+    # run — swallows Ctx::Failure (ctx.failure? will be true)
+    def _run_safe
+      with_hooks { call }
+    rescue Ctx::Failure
+      # swallow — caller checks ctx.failure?
+    rescue => e
+      begin
+        unless rescue_with_handler(e)
+          # Unhandled exception: mark ctx failed and re-raise
+          @ctx.fail!(error: e.message) rescue nil
+          raise e
+        end
+      rescue Ctx::Failure
+        # The rescue handler itself called ctx.fail! — swallow it
+      end
+    end
+  end
+end