railway_operation 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "railway_operation"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/railway_operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'terminal-table'
+
+require 'railway_operation/version'
+require 'railway_operation/generic/ensured_access'
+require 'railway_operation/generic/filled_matrix'
+require 'railway_operation/generic/typed_array'
+require 'railway_operation/stepper'
+require 'railway_operation/strategy'
+require 'railway_operation/surround'
+require 'railway_operation/steps_array'
+require 'railway_operation/operation'
+require 'railway_operation/operator'
+require 'railway_operation/info'
+
+module RailwayOperation
+  def self.included(base)
+    base.extend Operator::ClassMethods
+    base.send :include, Operator::InstanceMethods
+  end
+end

data/lib/railway_operation/generic/ensured_access.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  module Generic
+    # Ensures that the default value is available for use
+    # The problem with normal default values is that they are returned,
+    # they are not part of the actually collection.
+    #
+    # hash = Hash.new { [] }
+    # hash['a'] == []
+    #
+    # However, if you do the following
+    # hash['a'] << 2
+    # hash == {}
+    # hash['a'] != 2
+    #
+    # With this you can:
+    #
+    # ensured_hash = EnsuredAccess({}) { [] }
+    # ensured_hash['a'] << 2
+    # ensured_hash == { 'a' => 2 }
+    class EnsuredAccess < Delegator
+      def initialize(obj, default = nil, &block)
+        @obj = obj
+        @default = default || block
+      end
+
+      def __setobj__(obj)
+        @obj = obj
+      end
+
+      def __getobj__
+        @obj
+      end
+
+      def [](key)
+        @obj[key] ||= @default.respond_to?(:call) ? @default.call : @default
+        @obj[key]
+      end
+    end
+  end
+end

data/lib/railway_operation/generic/filled_matrix.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  module Generic
+    class FilledMatrix
+      include Enumerable
+
+      def initialize(*rows, row_type: Array)
+        @row_type = row_type
+        @matrix = EnsuredAccess.new(@row_type.new(rows)) do
+          EnsuredAccess.new(@row_type.new)
+        end
+
+        ensure_rows_length_are_equal!
+      end
+
+      def [](row_index, column_index = nil)
+        if column_index
+          @matrix.__getobj__[row_index] &&
+            @matrix.__getobj__[row_index][column_index]
+        else
+          @matrix.__getobj__[row_index] || EnsuredAccess.new(@row_type.new)
+        end
+      end
+
+      def []=(row_index, column_index, entry)
+        @max_column_index = nil # bust the max_column_index cache
+
+        @matrix[row_index][column_index] = entry
+        ensure_rows_length_are_equal!
+
+        @matrix
+      end
+
+      def each
+        @matrix.each do |row|
+          yield row
+        end
+      end
+
+      def max_column_index
+        @max_column_index ||= (@matrix.compact.max_by(&:length) || []).length - 1
+      end
+
+      private
+
+      def ensure_rows_length_are_equal!
+        @matrix.each_with_index do |_column, index|
+          @matrix[index][max_column_index] ||= nil
+        end
+      end
+    end
+  end
+end

data/lib/railway_operation/generic/typed_array.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  module Generic
+    # Ensure that only elements of specified type(s) are accepted in the array
+    class TypedArray < Delegator
+      class UnacceptableMember < StandardError; end
+      DEFAULT_MESSAGE = ->(type) { "unacceptable element in array, all elements must be of type #{type}" }.freeze
+
+      def initialize(array = [], ensure_type_is:, error_message: nil)
+        raise(ArgumentError, 'must be initialized with an array') unless array.is_a?(Array)
+
+        @types = wrap(ensure_type_is)
+        @error_message = error_message || DEFAULT_MESSAGE.(ensure_type_is)
+        __setobj__(array)
+      end
+
+      def __setobj__(arr)
+        raise UnacceptableMember, @error_message unless array_acceptable?(arr)
+        @arr = arr
+      end
+
+      def __getobj__
+        @arr
+      end
+
+      def <<(element)
+        raise UnacceptableMember, @error_message unless element_acceptable?(element)
+        @arr << element
+      end
+
+      def array_acceptable?(arr)
+        arr&.all? { |a| element_acceptable?(a) }
+      end
+
+      def element_acceptable?(element)
+        class_acceptable?(element) || instance_acceptable?(element)
+      end
+
+      private
+
+      def class_acceptable?(element)
+        return false unless element.is_a?(Class)
+        @types.detect { |type| element <= type }
+      end
+
+      def instance_acceptable?(element)
+        @types.detect { |type| element.is_a?(type) }
+      end
+
+      # Taken from ActiveSupport Array.wrap https://apidock.com/rails/Array/wrap/class
+      def wrap(object)
+        if object.respond_to?(:to_ary)
+          object.to_ary || [object]
+        else
+          [object]
+        end
+      end
+    end
+  end
+end

data/lib/railway_operation/info.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  class Info < DelegateClass(Hash)
+    def new(maybe_obj)
+      maybe_obj.is_a?(Info) ? maybe_obj : super
+    end
+
+    def initialize(operation:, **info)
+      super info.merge(operation: operation)
+    end
+
+    def operation
+      self[:operation]
+    end
+
+    def operation=(op)
+      self[:operation] = op
+    end
+
+    def execution
+      self[:execution] = Execution.new(self[:execution] || [])
+    end
+  end
+
+  # This is intended to extend the functionality of a normal
+  # hash to make it easier to inspect the log
+  class Execution < DelegateClass(Array)
+    def new(maybe_obj)
+      maybe_obj.is_a?(Execution) ? maybe_obj : super
+    end
+
+    def initialize(obj = [])
+      super
+    end
+
+    def <<(value)
+      super Step.new(value)
+    end
+
+    def []=(index, value)
+      super index, Step.new(value)
+    end
+
+    def first_step
+      first
+    end
+
+    def last_step
+      last
+    end
+
+    def add_error(error)
+      last.add_error(error)
+    end
+
+    def errored?
+      any?(&:errored?)
+    end
+
+    def success?
+      all?(&:success?)
+    end
+
+    def failed?
+      !success?
+    end
+
+    def completed?
+      all?(&:completed?)
+    end
+
+    def add_step(argument:, track_identifier:, step_index:)
+      self << {
+        argument: argument,
+        track_identifier: track_identifier,
+        step_index: step_index
+      }
+
+      last
+    end
+
+    def display
+      table = Terminal::Table.new
+      table.title = 'Execution'
+      table.headings = ['', 'Track', 'Success', 'Method', 'Errors']
+      table.rows = self.map do |s|
+        [
+          s[:step_index],
+          s[:track_identifier],
+          s.success?,
+          s[:noop] ? '--' : (s[:method].is_a?(Proc) ? 'Proc' : s[:method]),
+          s[:errors]
+        ]
+      end
+
+      table.to_s
+    end
+  end
+
+  class Step < DelegateClass(Hash)
+    def new(maybe_obj)
+      maybe_obj.is_a?(Step) ? maybe_obj : super
+    end
+
+    def initialize(obj = {})
+      super
+    end
+
+    def started_at
+      self[:started_at]
+    end
+
+    def ended_at
+      self[:ended_at]
+    end
+
+    def completed_at
+      ended_at
+    end
+
+    def started?
+      self[:started_at]
+    end
+
+    def completed?
+      started? && self[:ended_at]
+    end
+
+    def success?
+      errors.empty? && !self[:failed]
+    end
+
+    def errored?
+      !errors.empty?
+    end
+
+    def failed?
+      !!self[:failed]
+    end
+
+    def noop?
+      self[:noop]
+    end
+
+    def start!
+      self[:started_at] = timestamp
+    end
+
+    def end!
+      raise 'cannot complete step that has not yet started' unless started?
+      self[:ended_at] = timestamp
+    end
+
+    def fail!(error)
+      self[:failed_at] = timestamp
+      add_error(error)
+    end
+
+    def add_error(error)
+      errors << error if error
+    end
+
+    def noop!
+      self[:started_at] = self[:ended_at] = timestamp
+      self[:method] = nil
+      self[:noop] = true
+    end
+
+    def errors
+      self[:errors] ||= []
+      self[:errors]
+    end
+
+    def track_identifier
+      self[:track_identifier]
+    end
+
+    def step_index
+      self[:step_index]
+    end
+
+    def timestamp
+      Time.respond_to?(:current) ? Time.current : Time.now
+    end
+  end
+end

data/lib/railway_operation/operation.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module RailwayOperation
+  # This is the value object that holds the information necessary to
+  # run an operation
+  class Operation
+    class NonExistentTrack < StandardError; end
+    extend Forwardable
+
+    attr_reader :name, :track_alias
+    attr_accessor :operation_surrounds,
+                  :step_surrounds
+
+    def self.new(operation_or_name)
+      return operation_or_name if operation_or_name.is_a?(Operation)
+      super
+    end
+
+    def self.format_name(op_or_name)
+      case op_or_name
+      when Operation
+        op_or_name.name
+      when String, Symbol
+        op_or_name.to_s.gsub(/\s+/, '_').downcase.to_sym
+      else
+        raise 'invalid operation name'
+      end
+    end
+
+    def initialize(name)
+      @name = self.class.format_name(name)
+      @operation_surrounds = []
+      @step_surrounds = Generic::EnsuredAccess.new({}) { StepsArray.new }
+      @track_alias = [noop_track]
+      @tracks = Generic::FilledMatrix.new(row_type: StepsArray)
+    end
+
+    def [](track_identifier, step_index = nil)
+      tracks[
+        track_index(track_identifier),
+        step_index
+      ]
+    end
+
+    def []=(track_identifier, step_index, step)
+      tracks[
+        track_index(track_identifier),
+        step_index
+      ] = step
+    end
+
+    def add_step(track_identifier, method = nil, &block)
+      self[track_identifier, last_step_index + 1] = block || method
+    end
+
+    def stepper_function(fn = nil, &block)
+      @stepper_function ||= fn || block
+    end
+
+    def tracks(*names)
+      return @tracks if names.empty?
+      @track_alias = [noop_track, *names]
+    end
+
+    def strategy(tracks, stepper_fn)
+      tracks(*tracks)
+      stepper_function(stepper_fn)
+    end
+
+    def last_step_index
+      tracks.max_column_index
+    end
+
+    def successor_track(track_id)
+      next_index = track_index(track_id) + 1
+      return if tracks.count <= next_index
+
+      if track_id.is_a?(Numeric)
+        next_index
+      else
+        track_identifier(next_index)
+      end
+    end
+
+    def track_identifier(index_or_id)
+      return index_or_id unless index_or_id.is_a?(Integer)
+      validate_index(index_or_id)
+
+      @track_alias[index_or_id] || index_or_id
+    end
+
+    def track_index(track_identifier)
+      index = @track_alias.index(track_identifier) || track_identifier
+      validate_index(index)
+
+      index
+    end
+
+    def noop_track
+      :noop_track
+    end
+
+    def initial_track
+      track_identifier(1)
+    end
+
+    private
+
+    def validate_index(index)
+      unless index.is_a?(Integer) && index.positive?
+        raise "Invalid track `#{index}`, must be a positive integer"
+      end
+    end
+  end
+end