flows 0.2.0 → 0.6.0

data/lib/flows/railway.rb

@@ -1,48 +1,154 @@
-require_relative './railway/errors'
-
-require_relative './railway/dsl'
-require_relative './railway/builder'
-require_relative './railway/executor'
+require_relative 'railway/errors'
+require_relative 'railway/step'
+require_relative 'railway/step_list'
+require_relative 'railway/dsl'
 
 module Flows
-  # Railway DSL
-  module Railway
-    def self.included(mod)
-      mod.extend ::Flows::Railway::DSL
-    end
+  # Flows::Railway is an implementation of a Railway Programming pattern.
+  #
+  # You may read about this pattern in the following articles:
+  #
+  # * [Programming on rails: Railway Oriented Programming](http://sandordargo.com/blog/2017/09/27/railway_oriented_programming).
+  #   It's not about Ruby on Rails.
+  # * [Railway Oriented Programming: A powerful Functional Programming pattern](https://medium.com/@naveenkumarmuguda/railway-oriented-programming-a-powerful-functional-programming-pattern-ab454e467f31)
+  # * [Railway Oriented Programming in Elixir with Pattern Matching on Function Level and Pipelining](https://medium.com/elixirlabs/railway-oriented-programming-in-elixir-with-pattern-matching-on-function-level-and-pipelining-e53972cede98)
+  #
+  # Let's review a simple task and solve it using {Flows::Railway}:
+  #
+  # * you have to get a user by ID
+  # * get all user's blog posts
+  # * and convert it to an array of HTML-strings
+  #
+  # In such situation, we have to implement three parts of our task and compose it into something we can call,
+  # for example, from a Rails controller.
+  # Also, the first and third steps may fail (user not found, conversion to HTML failed).
+  # And if a step failed - we have to return failure info immediately.
+  #
+  #     class RenderUserBlogPosts < Flows::Railway
+  #       step :fetch_user
+  #       step :get_blog_posts
+  #       step :convert_to_html
+  #
+  #       def fetch_user(id:)
+  #         user = User.find_by_id(id)
+  #         user ? ok(user: user) : err(message: "User #{id} not found")
+  #       end
+  #
+  #       def get_blog_posts(user:)
+  #         ok(posts: User.posts)
+  #       end
+  #
+  #       def convert_to_html(posts:)
+  #         posts_html = post.map(&:text).map do |text|
+  #           html = convert(text)
+  #           return err(message: "cannot convert to html: #{text}")
+  #         end
+  #
+  #         ok(posts_html: posts_html)
+  #       end
+  #
+  #       private
+  #
+  #       # returns String or nil
+  #       def convert(text)
+  #         # some implementation here
+  #       end
+  #     end
+  #
+  #     RenderUserBlogPosts.call(id: 10)
+  #     # result object returned
+  #
+  # Let's describe how it works.
+  #
+  # First of all you have to inherit your railway from `Flows::Railway`.
+  #
+  # Then you must define list of your steps using `step` DSL method.
+  # Steps will be executed in the given order.
+  #
+  # The you have to provide step implementations. It should be done by using
+  # public methods with the corresponding names.
+  # _Please write your step implementations in the step definition order._
+  # _It will make your railway easier to read by other engineers._
+  #
+  # Each step should return {Flows::Result} Object.
+  # If Result Object is successful - next step will be called or
+  # this object becomes a railway execution result in the case of last step.
+  # If Result Object is failure - this object becomes execution result immediately.
+  #
+  # Place all the helpers methods in the private section of the class.
+  #
+  # To help with writing methods {Flows::Result::Helpers} is already included.
+  #
+  # {Railway} is a very simple but not very flexible abstraction.
+  # It has a good performance and a small overhead.
+  #
+  # ## `Flows::Railway` execution rules
+  #
+  # * steps execution happens from the first to the last step
+  # * input arguments (`Railway#call(...)`) becomes the input of the first step
+  # * each step should return Result Object (`Flows::Result::Helpers` already included)
+  # * if step returns failed result - execution stops and failed Result Object returned from Railway
+  # * if step returns successful result - result data becomes arguments of the following step
+  # * if the last step returns successful result - it becomes a result of a Railway execution
+  #
+  # ## Step definitions
+  #
+  # Two ways of step definition exist. First is by using an instance method:
+  #
+  #     step :do_something
+  #
+  #     def do_something(**arguments)
+  #       # some implementation
+  #       # Result Object as return value
+  #     end
+  #
+  # Second is by using lambda:
+  #
+  #     step :do_something, ->(**arguments) { ok(some: 'data') }
+  #
+  # Definition with lambda exists for debugging/testing purposes, it has higher priority than method implementation.
+  # _Do not use lambda implementations for your business logic!_
+  #
+  # __Think about Railway as about small book: you have a "table of contents"
+  # in a form of step definitions and actual "chapters" in the same order
+  # in a form of public methods. And your private methods becomes something like "appendix".__
+  #
+  # ## Advanced initialization
+  #
+  # In a simple case you can just invoke `YourRailway.call(..)`. Under the hood it works like `.new.call(...)`,
+  # but `.new` part will be executed ones and memoized ({Flows::Plugin::ImplicitInit} included).
+  #
+  # You can include {Flows::Plugin::DependencyInjector} into your Railway and in this case you will
+  # need to do `.new(...).call` manually.
+  class Railway
+    extend ::Flows::Plugin::ImplicitInit
 
     include ::Flows::Result::Helpers
+    extend ::Flows::Result::Helpers
 
-    def initialize(method_source: nil, deps: {})
-      _flows_do_checks
-
-      flow = _flows_make_flow(method_source || self, deps)
-      @_flows_executor = _flows_make_executor(flow)
-    end
+    extend DSL
 
-    def call(**params)
-      @_flows_executor.call(**params)
-    end
+    def initialize
+      klass = self.class
+      steps = klass.steps
 
-    private
+      raise NoStepsError, klass if steps.empty?
 
-    def _flows_do_checks
-      raise NoStepsError if self.class.steps.empty?
+      @__flows_railway_flow = Flows::Flow.new(
+        start_node: steps.first_step_name,
+        node_map: steps.to_node_map(self)
+      )
     end
 
-    def _flows_make_flow(method_source, deps)
-      ::Flows::Railway::Builder.new(
-        steps: self.class.steps,
-        method_source: method_source,
-        deps: deps
-      ).call
-    end
+    # Executes Railway with provided keyword arguments, returns Result Object
+    #
+    # @return [Flows::Result]
+    def call(**kwargs)
+      context = {}
 
-    def _flows_make_executor(flow)
-      ::Flows::Railway::Executor.new(
-        flow: flow,
-        class_name: self.class.name
-      )
+      @__flows_railway_flow.call(ok(**kwargs), context: context).tap do |result|
+        result.meta[:last_step] = context[:last_step]
+      end
     end
   end
 end

data/lib/flows/railway/dsl.rb

@@ -1,27 +1,17 @@
 module Flows
-  module Railway
-    # DSL methods for Railway
+  class Railway
+    # @api private
     module DSL
       attr_reader :steps
 
-      def self.extended(mod, steps = nil)
-        mod.instance_variable_set(:@steps, steps || [])
+      SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
+        '@steps' => StepList.new
+      )
 
-        mod.class_exec do
-          def self.inherited(subclass)
-            ::Flows::Railway::DSL.extended(subclass, steps.map(&:dup))
-            super
-          end
-        end
-      end
-
-      include Flows::Result::Helpers
+      include SingletonVarsSetup
 
-      def step(name, custom_body = nil)
-        @steps << {
-          name: name,
-          custom_body: custom_body
-        }
+      def step(name, lambda = nil)
+        steps.add(name: name, lambda: lambda)
       end
     end
   end

data/lib/flows/railway/errors.rb

@@ -1,21 +1,17 @@
 module Flows
-  module Railway
-    # rubocop:disable Style/Documentation
-    class NoStepsError < ::Flows::Error
-      def message
-        'No steps defined'
-      end
-    end
+  class Railway
+    # Base class for Railway errors
+    class Error < StandardError; end
 
-    class NoStepImplementationError < ::Flows::Error
-      def initialize(step_name)
-        @step_name = step_name
+    # Raised when initializing Railway with no steps
+    class NoStepsError < Error
+      def initialize(klass)
+        @klass = klass
       end
 
       def message
-        "Missing step definition: #{@step_name}"
+        "No steps defined for #{@klass}"
       end
     end
-    # rubocop:enable Style/Documentation
   end
 end

data/lib/flows/railway/step.rb

@@ -0,0 +1,24 @@
+module Flows
+  class Railway
+    NODE_PREPROCESSOR = ->(input, _, _) { [[], input.unwrap] }
+
+    NODE_POSTPROCESSOR = lambda do |output, context, meta|
+      context[:last_step] = meta[:name]
+
+      output
+    end
+
+    # @api private
+    Step = Struct.new(:name, :lambda, :next_step, keyword_init: true) do
+      def to_node(method_source)
+        Flows::Flow::Node.new(
+          body: lambda || method_source.method(name),
+          router: Flows::Flow::Router::Simple.new(next_step || :end, :end),
+          meta: { name: name },
+          preprocessor: NODE_PREPROCESSOR,
+          postprocessor: NODE_POSTPROCESSOR
+        )
+      end
+    end
+  end
+end

data/lib/flows/railway/step_list.rb

@@ -0,0 +1,38 @@
+module Flows
+  class Railway
+    # @api private
+    class StepList
+      def initialize
+        @list = []
+      end
+
+      def initialize_dup(_other)
+        @list = @list.map(&:dup)
+      end
+
+      def add(name:, lambda: nil)
+        step = Step.new(name: name, lambda: lambda)
+        last_step = @list.last
+
+        last_step.next_step = name if last_step
+
+        @list << step
+
+        self
+      end
+
+      def first_step_name
+        @list.first.name
+      end
+
+      # `:reek:FeatureEnvy` is false positive here.
+      def to_node_map(method_source)
+        @list.map { |step| [step.name, step.to_node(method_source)] }.to_h
+      end
+
+      def empty?
+        @list.empty?
+      end
+    end
+  end
+end

data/lib/flows/result.rb

@@ -1,11 +1,197 @@
 module Flows
-  # Result object with context
+  # @abstract
+  #
+  # Result Object is a way of presenting the result of a calculation. The result may be successful or failed.
+  #
+  # For example, if you calculate expression `a / b`:
+  #
+  # * for `a = 6` and `b = 2` result will be successful with data `3`.
+  # * for `a = 6` and `b = 0` result will be failed with data, for example, `"Cannot divide by zero"`.
+  #
+  # Examples of such approach may be found in other libraries and languages:
+  #
+  # * [Either Monad](https://hackage.haskell.org/package/category-extras-0.52.0/docs/Control-Monad-Either.html)
+  #   in Haskell.
+  # * [Result Type](https://doc.rust-lang.org/std/result/enum.Result.html) in Rust.
+  # * [Faraday gem](https://www.rubydoc.info/gems/faraday/Faraday/Response) has `Faraday::Response` object
+  #   which contains data and status.
+  # * [dry-rb Result Monad](https://dry-rb.org/gems/dry-monads/1.3/result/) has `Dry::Monads::Result`.
+  #
+  # So, why do you need Result Object?
+  # Why not just return `nil` on a failure or raise an error (like in the standard library)?
+  # Here are several reasons:
+  #
+  # * Raising errors and exceptions is a [bad way](https://martinfowler.com/articles/replaceThrowWithNotification.html)
+  #   of handling errors.
+  #   Moreover, it is slow and looks like `goto`.
+  #   However, it is still a good way to abort execution on an unexpected error.
+  # * Returning `nil` does not work when you have to deal with different types of errors or
+  #   an error has some data payload.
+  # * Using specific Result Objects (like `Faraday::Response`) brings inconsistency -
+  #   you have to learn how to deal with each new type of Result.
+  #
+  # That's why `Flows` should have Result Object implementation.
+  # If any executable Flows entity will return Result Object with the same API -
+  # composing your app components becomes trivial.
+  # Result Objects should also be as fast and lightweight as possible.
+  #
+  # Flows' implementation is inspired mainly by [Rust Result Type](https://doc.rust-lang.org/std/result/enum.Result.html)
+  # and focused on following features:
+  #
+  # * Use idiomatic Ruby: no methods named with first capital letter (`Name(1, 2)`), etc.
+  # * Use `case` and `===` (case equality) for matching results and writing routing logic.
+  # * Provide helpers for convenient creation and matching of Result Objects ({Helpers}).
+  # * Result Object may be successful ({Ok}) or failure ({Err}).
+  # * Result Object has an {#status} (some symbol: `:saved`, `:zero_division_error`).
+  # * Status usage is optional. Default statuses for successful and failure results are `:ok` and `:err`.
+  # * Result may have metadata ({#meta}).
+  #   Metadata is something unrelated to your business logic
+  #   (execution time, for example, or some info about who created this result).
+  #   This data must not be used in business logic, it's for a library code.
+  # * Different accessors for successful and failure results -
+  #   prevents treating failure results as successful and vice versa.
+  #
+  # ## General Recommendations
+  #
+  # Let's assume that you have some code returning Result Object.
+  #
+  # * if an error happened and may be handled somehow - return failure result.
+  # * if an error happened and cannot be handled - raise exception to abort execution.
+  # * if you don't handle any errors for now - don't check result type and
+  #   use {#unwrap} to access data. It will raise exception when called on a failure result.
+  #
+  # @example Creating Result Objects
+  #   # Successful result with data {a: 1}
+  #   x = Flows::Result::Ok.new(a: 1)
+  #
+  #   # Failure result with data {msg: 'error'}
+  #   x = Flows::Result::Err.new(msg: 'error')
+  #
+  #   # Successful result with data {a: 1} and status `:done`
+  #   x = Flows::Result::Ok.new({ a: 1 }, status: :done)
+  #
+  #   # Failure result with data {msg: 'error'} and status `:http_error`
+  #   x = Flows::Result::Err.new({ msg: 'error' }, status: :http_error)
+  #
+  #   # Successful result with data {a: 1} and metadata { time: 123 }
+  #   x = Flows::Result::Ok.new({ a: 1 }, meta: { time: 123 })
+  #
+  #   # Failure result with data {msg: 'error'} and metadata { time: 123 }
+  #   x = Flows::Result::Err.new({ msg: 'error' }, meta: { time: 123 })
+  #
+  # @example Create Result Objects using helpers
+  #   class Demo
+  #     # You cannot provide metadata using helpers and it's ok:
+  #     # you shouldn't populate metadata in your business code.
+  #     # Metadata is designed to use in library code and
+  #     # when you have to provide some metadata from your library -
+  #     # just use `.new` instead of helpers.
+  #     include Flows::Result::Helpers
+  #
+  #     def demo
+  #       # Successful result with data {a: 1}
+  #       x = ok(a: 1)
+  #
+  #       # Failure result with data {msg: 'error'}
+  #       x = err(msg: 'error')
+  #
+  #       # Successful result with data {a: 1} and status `:done`
+  #       x = ok(:done, a: 1)
+  #
+  #       # Failure result with data {msg: 'error'} and status `:http_error`
+  #       x = err(:http_error, msg: 'error')
+  #     end
+  #   end
+  #
+  # @example Inspecting Result Objects
+  #   # Behaviour of any result object:
+  #   result.status # returns status, example: `:ok`
+  #   result.meta # returns metadata, example: `{}`
+  #
+  #   # Behaviour specific to successful results:
+  #   result.ok? # true
+  #   result.err? # false
+  #   result.unwrap # returns result data
+  #   result.error # raises exception
+  #
+  #   # Behaviour specific to failure results:
+  #   result.ok? # false
+  #   result.err? # true
+  #   result.unwrap # raises exception
+  #   result.error # returns result data
+  #
+  # @example Matching Results with case
+  #   case result
+  #   when Flows::Result::Ok then do_job
+  #   when Flows::Result::Err then give_up
+  #   end
+  #
+  # @example Matching Results with case and helpers
+  #   class Demo
+  #     include Flows::Result::Helpers
+  #
+  #     def simple_usage
+  #       case result
+  #       when match_ok then do_job
+  #       when match_err then give_up
+  #       end
+  #     end
+  #
+  #     def with_status_matching
+  #       case result
+  #       when match_ok(:create) then do_create
+  #       when match_ok(:update) then do_update
+  #       when match_err(:http_error) then retry
+  #       when match_err then give_up
+  #       end
+  #     end
+  #   end
+  #
+  # @!method ok?
+  #   @abstract
+  #   @return [Boolean] `true` if result is successful
+  # @!method err?
+  #   @abstract
+  #   @return [Boolean] `true` if result is failure
+  # @!method unwrap
+  #   @abstract
+  #   @return [Object] result data
+  #   @raise [AccessError] if called on failure object
+  # @!method error
+  #   @abstract
+  #   @return [Object] result data
+  #   @raise [AccessError] if called on successful object
+  #
+  # @since 0.4.0
   class Result
-    attr_reader :status, :meta
+    # @return [Symbol] status of Result Object, default is `:ok` for successful results
+    #   and `:err` for failure results.
+    attr_reader :status
 
+    # @return [Hash] metadata, don't use it to store business data
+    attr_reader :meta
+
+    # Direct creation of this abstract class is forbidden.
+    #
+    # @raise [StandardError] you will get an error
     def initialize(**)
       raise 'Use Flows::Result::Ok or Flows::Result::Err for build result objects'
     end
+
+    # Results are equal if have same type and data.
+    #
+    # Metadata is ignored in comparison.
+    #
+    # @return [Boolean]
+    def ==(other)
+      return false if self.class != other.class
+
+      (status == other.status) && (data == other.send(:data))
+    end
+
+    private
+
+    attr_accessor :data
   end
 end