convenient_service 0.1.0

data/lib/convenient_service/support/middleware/stack_builder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module Middleware
+      ##
+      # @internal
+      #   TODO: Contribute.
+      #
+      #   NOTE: Minimal `ibsciss-middleware` version - `0.4.2`.
+      #   https://github.com/marian13/ruby-middleware/tree/v0.4.2
+      #
+      class StackBuilder < Dependencies::Extractions::RubyMiddleware::Middleware::Builder
+        ##
+        # @param opts [Hash]
+        # @param block [Proc]
+        # @return [void]
+        #
+        # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L43
+        #
+        def initialize(opts = {}, &block)
+          super
+
+          ##
+          # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L174
+          #
+          self.stack = opts[:stack] if opts.has_key?(:stack)
+        end
+
+        ##
+        # @param other [ConvenientService::Support::Middleware::StackBuilder, Object]
+        # @return [Boolean, nil]
+        #
+        def ==(other)
+          return unless other.instance_of?(self.class)
+
+          return false if name != other.name
+          return false if stack != other.stack
+
+          true
+        end
+
+        ##
+        # @return [Array]
+        #
+        # @internal
+        #   NOTE: `use` can accept additional arguments and block, that is why `stack` contains tuples like [middleware, args, block].
+        #   https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L76
+        #
+        #   TODO: better name than just `to_a`.
+        #
+        def to_a
+          stack
+        end
+
+        ##
+        # @return [ConvenientService::Support::Middleware::StackBuilder]
+        #
+        def dup
+          self.class.new(
+            ##
+            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L45
+            #
+            runner_class: @runner_class,
+            ##
+            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L46
+            #
+            name: @middleware_name.dup,
+            ##
+            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L167
+            #
+            stack: stack.dup
+          )
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/middleware.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "middleware/stack_builder"

data/lib/convenient_service/support.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "support/concern"
+
+require_relative "support/abstract_method"
+require_relative "support/castable"
+require_relative "support/command"
+require_relative "support/copyable"
+require_relative "support/delegate"
+require_relative "support/finite_loop"
+require_relative "support/middleware"

data/lib/convenient_service/utils/array/contain_exactly.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      ##
+      # @internal
+      #   IMPORTANT: Since `contain_exactly` uses hashes under the hood, `first_array` and `second_array` items should be comparable by `hash` and `eql?`.
+      #   It may sometimes introduce hash collisions, which in turn can degrade the performance.
+      #   But since the probability is relatively low, because it is NOT too common to have hashes that contain keys with different classes,
+      #   hashes comparison is still preferred over array comparison.
+      #   Check specs for more details.
+      #   - https://github.com/ruby/spec/blob/master/core/hash/shared/eql.rb
+      #   - https://stackoverflow.com/questions/54961311/ruby-why-does-hash-need-to-overridden-whenever-eql-is-overridden
+      #   - https://ruby-doc.org/core-3.1.2/Object.html#method-i-hash
+      #
+      #   NOTE: Inspired by `contain_exactly` from `RSpec`.
+      #   - https://relishapp.com/rspec/rspec-expectations/docs/built-in-matchers/contain-exactly-matcher
+      #
+      class ContainExactly < Support::Command
+        ##
+        # @!attribute [r] first_array
+        #   @return [Array]
+        #
+        attr_reader :first_array
+
+        ##
+        # @!attribute [r] second_array
+        #   @return [Array]
+        #
+        attr_reader :second_array
+
+        ##
+        # @param first_array [Array]
+        # @param second_array [Array]
+        # @return [Boolean]
+        #
+        def initialize(first_array, second_array)
+          @first_array = first_array
+          @second_array = second_array
+        end
+
+        ##
+        # @return [Boolean]
+        #
+        def call
+          first_array_counts = first_array.each_with_object(::Hash.new { |h, k| h[k] = 0 }) { |item, counts| counts[item] += 1 }
+
+          second_array_counts = second_array.each_with_object(::Hash.new { |h, k| h[k] = 0 }) { |item, counts| counts[item] += 1 }
+
+          first_array_counts == second_array_counts
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/drop_while.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class DropWhile < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] inclusively
+        #   @return [Boolean]
+        #
+        attr_reader :inclusively
+
+        ##
+        # @!attribute [r] condition_block
+        #   @return [Proc]
+        #
+        attr_reader :condition_block
+
+        ##
+        # @param array [Array]
+        # @param inclusively [Boolean]
+        # @param condition_block [Proc]
+        # @return [void]
+        #
+        def initialize(array, inclusively: false, &condition_block)
+          @array = array
+          @inclusively = inclusively
+          @condition_block = condition_block
+        end
+
+        ##
+        # @return [Array]
+        #
+        def call
+          remained_items = array.drop_while(&condition_block)
+
+          remained_items = remained_items.drop(1) if inclusively
+
+          remained_items
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      module Errors
+        class NonIntegerIndex < Error
+          def initialize(index:)
+            message = <<~TEXT
+              Index `#{index.inspect}` is NOT an integer.
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/find_last.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class FindLast < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] block
+        #   @return [Proc]
+        #
+        attr_reader :block
+
+        ##
+        # @param array [Array]
+        # @param block [Proc]
+        # @return [void]
+        #
+        def initialize(array, &block)
+          @array = array
+          @block = block
+        end
+
+        ##
+        # @return [Object] Can be any type.
+        #
+        def call
+          array.reverse.find(&block)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/find_yield.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      ##
+      # @example
+      #   Preconditions (pseudo-real world):
+      #
+      #   - Both `match?` and `match` do exactly the same thing, only their return values are different.
+      #   - `match?` returns `true` when the string matches the regex, otherwise - `false`.
+      #   - `match` returns regex match data when the string matches the regex, otherwise - `nil`.
+      #   - Regex matching is a very resource-heavy process.
+      #
+      #   - `test` is defined like this:
+      #     def test
+      #       string = strings.find { |string| string.match?(regexp) }
+      #
+      #       return unless string
+      #
+      #       string.match(regexp)
+      #     end
+      #
+      #   - To simplify the example, imagine that `strings` return an array with only one string and that string matches regex.
+      #     def strings
+      #       ["foo bar"]
+      #     end
+      #
+      #     def regexp
+      #       /\w+/
+      #     end
+      #   - This way regex matching (a very resource-heavy process) is executed twice.
+      #   - First time during the `match?` method call.
+      #   - The second time during the `match` method call.
+      #
+      #   Task:
+      #   - How to implement `test` in a way that regexp matching (very resource-heavy process) is executed only once for the preconditions above?
+      #
+      #   Solution:
+      #   - Use `ConvenientService::Utils::Array.find_yield`
+      #   - `test` should be rewritten like this:
+      #     def test
+      #       ConvenientService::Utils::Array.find_yield(strings) { |string| string.match(regexp) }
+      #     end
+      #
+      #   Inspiration:
+      #   - https://github.com/rubyworks/facets/blob/3.1.0/lib/core/facets/enumerable/find_yield.rb#L28
+      #   - https://stackoverflow.com/a/38457218/12201472
+      #
+      #   Note: `String#match?` and `String#match` docs.
+      #   - https://ruby-doc.org/core-2.7.0/String.html#method-i-match-3F
+      #   - https://ruby-doc.org/core-2.7.0/String.html#method-i-match
+      #
+      class FindYield < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] block
+        #   @return [Proc]
+        #
+        attr_reader :block
+
+        ##
+        # @param array [Array]
+        # @param block [Proc]
+        # @return [void]
+        #
+        def initialize(array, &block)
+          @array = array
+          @block = block
+        end
+
+        ##
+        # @return [Object, nil] Can be any type.
+        # @see https://github.com/rubyworks/facets/blob/main/lib/core/facets/enumerable/find_yield.rb#L28
+        #
+        def call
+          array.each do |item|
+            block_value = block.call(item)
+
+            return block_value if block_value
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/keep_after.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class KeepAfter < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @param array [Array]
+        # @param object [Object] Can be any type.
+        # @return [void]
+        #
+        def initialize(array, object)
+          @array = array
+          @object = object
+        end
+
+        ##
+        # @return [Object, nil] Can be any type.
+        # @see https://github.com/rubyworks/facets/blob/main/lib/core/facets/array/before.rb#L35
+        #
+        def call
+          return [] unless array.include?(object)
+
+          Utils::Array.drop_while(array, inclusively: true) { |item| item != object }
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/merge.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class Merge < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] overrides
+        #   @return [Hash]
+        #
+        attr_reader :overrides
+
+        ##
+        # @!attribute [r] raise_on_non_integer_index
+        #   @return [Boolean]
+        #
+        attr_reader :raise_on_non_integer_index
+
+        ##
+        # @param array [Array]
+        # @param overrides [Hash]
+        # @param raise_on_non_integer_index [Boolean]
+        # @return [void]
+        #
+        def initialize(array, overrides, raise_on_non_integer_index: true)
+          @array = array
+          @overrides = overrides
+          @raise_on_non_integer_index = raise_on_non_integer_index
+        end
+
+        ##
+        # @return [Array]
+        # @raise [ConvenientService::Utils::Array::Errors::NonIntegerIndex]
+        #
+        def call
+          ensure_valid_overrides!
+
+          integer_key_overrides.each_with_object(array.dup) { |(index, value), array| array[index] = value }
+        end
+
+        private
+
+        ##
+        # @return [void]
+        # @raise [ConvenientService::Utils::Array::Errors::NonIntegerIndex]
+        #
+        def ensure_valid_overrides!
+          return integer_key_overrides unless raise_on_non_integer_index
+
+          return if overrides.size == integer_key_overrides.size
+
+          raise Errors::NonIntegerIndex.new(index: non_integer_index)
+        end
+
+        ##
+        # @return [Hash]
+        #
+        def integer_key_overrides
+          @integer_key_overrides ||= overrides.dup.keep_if { |index| index.is_a?(::Integer) }
+        end
+
+        ##
+        # @return [Object] Can be any type.
+        #
+        def non_integer_index
+          @non_integer_index ||= overrides.keys.find { |index| !index.is_a?(::Integer) }
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/rjust.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class Rjust < Support::Command
+        ##
+        # @!attribute [r] array
+        #   @return [Array]
+        #
+        attr_reader :array
+
+        ##
+        # @!attribute [r] size
+        #   @return [Integer]
+        #
+        attr_reader :size
+
+        ##
+        # @!attribute [r] pad
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :pad
+
+        ##
+        # @param array [Array]
+        # @param size [Integer]
+        # @param pad [Object] Can be any type.
+        # @return [void]
+        #
+        def initialize(array, size, pad = nil)
+          @array = array
+          @size = size
+          @pad = pad
+        end
+
+        ##
+        # @return [Array]
+        #
+        def call
+          return array if size <= array.size
+
+          count = size - array.size
+
+          array + [pad] * count
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array/wrap.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Array
+      class Wrap < Support::Command
+        ##
+        # @!attribute [r] pad
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @param object [Object] Can be any type.
+        # @return [void]
+        #
+        def initialize(object)
+          @object = object
+        end
+
+        ##
+        # @return [Array]
+        #
+        # @internal
+        #   Copied without any modifications from:
+        #   https://api.rubyonrails.org/classes/Array.html#method-c-wrap
+        #
+        def call
+          if object.nil?
+            []
+          elsif object.respond_to?(:to_ary)
+            object.to_ary || [object]
+          else
+            [object]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/array.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "array/errors"
+
+require_relative "array/contain_exactly"
+require_relative "array/drop_while"
+require_relative "array/find_last"
+require_relative "array/find_yield"
+require_relative "array/keep_after"
+require_relative "array/merge"
+require_relative "array/rjust"
+require_relative "array/wrap"
+
+module ConvenientService
+  module Utils
+    module Array
+      class << self
+        def contain_exactly?(...)
+          ContainExactly.call(...)
+        end
+
+        def drop_while(...)
+          DropWhile.call(...)
+        end
+
+        def find_last(...)
+          FindLast.call(...)
+        end
+
+        def find_yield(...)
+          FindYield.call(...)
+        end
+
+        def keep_after(...)
+          KeepAfter.call(...)
+        end
+
+        def merge(...)
+          Merge.call(...)
+        end
+
+        def rjust(...)
+          Rjust.call(...)
+        end
+
+        def wrap(...)
+          Wrap.call(...)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/bool/to_bool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Bool
+      ##
+      # Converts objects to boolean.
+      # Implementation is very basic just to serve the need of this library.
+      # More comprehensive solution can be found in Rails, wannabe_bool, etc:
+      # - https://api.rubyonrails.org/classes/ActiveModel/Type/Boolean.html
+      # - https://github.com/prodis/wannabe_bool
+      #
+      class ToBool < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @param object [Object] Can be any type.
+        # @return [void]
+        #
+        def initialize(object)
+          @object = object
+        end
+
+        ##
+        # @return [Boolean]
+        #
+        def call
+          !!object
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/bool.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "bool/to_bool"
+
+module ConvenientService
+  module Utils
+    module Bool
+      class << self
+        def to_bool(...)
+          ToBool.call(...)
+        end
+      end
+    end
+  end
+end