meddleware 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 453a4fea42903735f1b7e502f5fb5ba323ecfd1240db7d476453dabd0e773f8d
-  data.tar.gz: c459598e2a9145a7ad8a4128cefc5de8ed3a018db28e1cf95a24a26b15b42883
+  metadata.gz: '0197bd468d02ee66541d9ae7b369afc2ad0632cb6058cc3d8856a2b87f8ff897'
+  data.tar.gz: 4dab2733ff8907db8abbe3b3b11d45ba536d2bc76831d7128b68a4db5847900e
 SHA512:
-  metadata.gz: 94db19316854023dece52b027bd87f0c423936c3ccf4fba424b85eaa798672aa936820ecb0b5e427c5832c29fe7deb6dce876563c70c3869b15b1b137d26b511
-  data.tar.gz: 57188689d33ca8a987e4cdcde3792da430b86946c6c0ec99ace62b6e7be05c9658eacbc83f6e3cc26c20d3c8e06a47ef53fa4937919d7d4c1e49a556469cc0c3
+  metadata.gz: 305a9da953ca540f424296aca10836829cff777c39698b1938f998f7f425045cd3fb69fef9563a34579858e87b8fd38d02971a7fc72b1ef34df3b242f80d18f2
+  data.tar.gz: '08023838c15da52c5339ad7efeb6124eea151aa8d4ea334dd15b01f64c191ae8f4d4eaf01e7f9171a10606c368aa70a87c30ac297792d7c2e443dec575820b81'

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+###  v0.3.0  (2022-10-11)
+- extendable
+- drop ruby 2.5 (#4)
+- remove rake
+
+###  v0.2.0  (2021-09-14)
+- ruby 3 compatibility
+- usage spec
+- fix tests
+- simplify: move dedup functionality out of build method
+- array support
+
+###  v0.1.0  (2021-04-05)
+- spec examples
+- Update README.md
+- test coverage
+- bugs and tests
+- Meddleware.replace
+- proc support
+- validation and currying
+- test coverage
+- support instances and procs
+- gemfile cleanup
+- fix github actions
+- add specs, clean up
+- thanks
+
+###  v0.0.1  (2021-03-31)
+- skeleton

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Daniel Pepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+Meddleware
+======
+A middleware framework to make meddling easy.  Middleware is a popular pattern from Rack and Rails, which provides callers a way to execute code before and after yours.  This gives callers the ability to modify parameters or results, conditionally skip execution, and log activity without the need to monkey patch or subclass.
+
+
+```ruby
+require 'meddleware'
+
+# lib/mywidget.rb
+class MyWidget
+  extend Meddleware
+
+  def do_the_thing
+    # invoke middleware chain
+    middleware.call do
+      # do your thing
+      ...
+    end
+  end
+end
+
+# config/initializers/mywidget.rb
+MyWidget.middleware do
+  # add a logger
+  use { puts "before the thing" }
+
+  # add another middleware
+  use MyMiddleware
+end
+
+
+# use it from whereever
+MyWidget.new.do_the_thing
+```
+
+
+## Usage
+Extend your class with Meddleware to add a `middleware` method.  Or use `include` to give each instance its own, individual middleware.
+
+```ruby
+class MyWidget
+  extend Meddleware
+end
+
+MyWidget.middleware
+```
+
+Then wrap your class's functionality so it will get executed along with the all the registered middleware.
+
+```ruby
+class MyWidget
+  extend Meddleware
+
+  def do_the_thing
+    # invoke middleware chain
+    middleware.call(*args) do
+      # do your thing
+      ...
+    end
+  end
+end
+```
+
+
+See [documentation](https://github.com/dpep/meddleware_rb/wiki/DSL) for full DSL.
+
+
+----
+## Full Example
+```ruby
+# lib/mylist.rb
+module MyList
+  extend Meddleware
+
+  # generate an array from 1 to n
+  def self.generate(n)
+    # invoke middleware chain
+    middleware.call(n) do |n|
+      # do the actual work of generating your results 
+      (1..n).to_a
+    end
+  end
+end
+
+# app/initializers/mylist.rb
+class OneExtra
+  def call(n)
+    # adds one to the argument being passed in
+    yield(n + 1)
+  end
+end
+
+class Doubler
+  def call(*)
+    # modifies the results by doubles each value
+    yield.map {|x| x * 2 }
+  end
+end
+
+MyList.middleware do
+  use OneExtra
+  use Doubler
+
+  # loggers
+  prepend {|x| puts "n starts as #{x}" }
+  append  {|x| puts "n ends as #{x}" }
+end
+
+
+# use it
+> MyList.generate(2)
+
+# would normally output [ 1, 2 ]
+# but with middleware:
+
+n starts as 2
+n ends as 3
+=> [2, 4, 6]
+```
+
+----
+## Contributing
+
+Yes please  :)
+
+1. Fork it
+1. Create your feature branch (`git checkout -b my-feature`)
+1. Ensure the tests pass (`bundle exec rspec`)
+1. Commit your changes (`git commit -am 'awesome new feature'`)
+1. Push your branch (`git push origin my-feature`)
+1. Create a Pull Request
+
+
+----
+### Inspired by / Thanks to
+
+[@mitchellh](https://github.com/mitchellh) + [middleware](https://github.com/mitchellh/middleware/tree/master/lib/middleware)
+
+[@mperham](https://github.com/mperham) + [Sidekiq](https://github.com/mperham/sidekiq/blob/master/lib/sidekiq/middleware/chain.rb)
+
+[Rails](https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/middleware/stack.rb)
+
+
+----
+![Gem](https://img.shields.io/gem/dt/meddleware?style=plastic)
+[![codecov](https://codecov.io/gh/dpep/meddleware_rb/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/meddleware_rb)

data/lib/meddleware/stack.rb

@@ -0,0 +1,192 @@
+module Meddleware
+  class Stack
+    def initialize(&block)
+      instance_eval(&block) if block_given?
+    end
+
+    def use(*args, **kwargs, &block)
+      entry = create_entry(args, kwargs, block)
+      remove(entry[0])
+      stack << entry
+      self
+    end
+    alias append use
+
+    def prepend(*args, **kwargs, &block)
+      entry = create_entry(args, kwargs, block)
+      remove(entry[0])
+      stack.insert(0, entry)
+      self
+    end
+
+    def after(after_klass, *args, **kwargs, &block)
+      entry = create_entry(args, kwargs, block)
+      remove(entry[0])
+
+      i = if after_klass.is_a? Array
+        after_klass.map {|x| index(x) }.compact.max
+      else
+        index(after_klass)
+      end
+      i ||= count - 1 # last element
+
+      stack.insert(i + 1, entry)
+      self
+    end
+
+    def before(before_klass, *args, **kwargs, &block)
+      entry = create_entry(args, kwargs, block)
+      remove(entry[0])
+
+      i = if before_klass.is_a? Array
+        before_klass.map {|x| index(x) }.compact.min
+      else
+        index(before_klass)
+      end
+      i ||= 0 # first element
+
+      stack.insert(i, entry)
+      self
+    end
+
+    def include?(*klass)
+      klass.all? {|x| index(x) }
+    end
+
+    def remove(*klass)
+      stack.reject! { |entry| klass.include?(entry[0]) }
+      self
+    end
+
+    def replace(old_klass, *args, **kwargs, &block)
+      entry = create_entry(args, kwargs, block)
+      remove(entry[0])
+
+      i = index(old_klass)
+
+      unless i
+        raise RuntimeError, "middleware not present: #{old_klass}"
+      end
+
+      stack[i] = entry
+      self
+    end
+
+    def count
+      stack.count
+    end
+    alias size count
+
+    def clear
+      stack.clear
+    end
+
+    def empty?
+      stack.empty?
+    end
+
+    def call(*args, **kwargs)
+      chain = build_chain
+      default_args = args
+      default_kwargs = kwargs
+
+      traverse = proc do |*args, **kwargs|
+        if args.empty? && kwargs.empty?
+          args = default_args
+          kwargs = default_kwargs
+        else
+          default_args = args
+          default_kwargs = kwargs
+        end
+
+        if chain.empty?
+          yield(*args, **kwargs) if block_given?
+        else
+          middleware = chain.shift
+
+          if middleware.is_a?(Proc) && !middleware.lambda?
+            middleware.call(*args, **kwargs)
+
+            # implicit yield
+            traverse.call(*args, **kwargs)
+          else
+            middleware.call(*args, **kwargs, &traverse)
+          end
+        end
+      end
+
+      traverse.call(*args, **kwargs)
+    end
+
+
+    protected
+
+    def stack
+      @stack ||= []
+    end
+
+    def index(klass)
+      stack.index {|entry| entry[0] == klass }
+    end
+
+    def create_entry(args, kwargs, block)
+      klass, *args = args
+
+      if [ klass, block ].none?
+        raise ArgumentError, 'either a middleware or block must be provided'
+      end
+
+      if klass
+        # validate
+        if klass.is_a? Class
+          unless klass.method_defined?(:call)
+            raise ArgumentError, "middleware must implement `.call`: #{klass}"
+          end
+        else
+          unless klass.respond_to?(:call)
+            raise ArgumentError, "middleware must respond to `.call`: #{klass}"
+          end
+
+          unless block.nil?
+            raise ArgumentError, 'can not supply middleware instance and block'
+          end
+        end
+
+        [ klass, args, kwargs, block ].compact
+      else
+        [ block ]
+      end
+    end
+
+    def build_chain
+      # build the middleware stack
+      stack.map do |klass, args, kwargs, block|
+        if klass.is_a? Class
+          klass.new(*args, **kwargs, &block)
+        else
+          if args.nil? && kwargs.nil?
+            # middleware is a block
+            klass
+          elsif args.empty? && kwargs.empty?
+            # nothing to curry, just pass through middleware instance
+            klass
+          else
+            # curry args
+            ->(*more_args, **more_kwargs, &block) do
+              klass.call(
+                *(args + more_args),
+                **kwargs.merge(more_kwargs),
+                &block
+              )
+            end
+          end
+        end
+      end
+    end
+
+    if RUBY_VERSION < '3'
+      require 'meddleware/v2_7'
+      prepend Meddleware::V2_7
+    end
+  end
+end

data/lib/meddleware/v2_7.rb

@@ -0,0 +1,143 @@
+# backwards compatible functionality for Ruby 2.7
+
+module Meddleware
+  module V2_7
+    def use(*klass_and_args, &block)
+      entry = create_entry(klass_and_args, block)
+      remove(entry[0])
+      stack << entry
+      self
+    end
+    alias append use
+
+    def prepend(*klass_and_args, &block)
+      entry = create_entry(klass_and_args, block)
+      remove(entry[0])
+      stack.insert(0, entry)
+      self
+    end
+
+    def after(after_klass, *klass_and_args, &block)
+      entry = create_entry(klass_and_args, block)
+      remove(entry[0])
+
+      i = if after_klass.is_a? Array
+        after_klass.map {|x| index(x) }.compact.max
+      else
+        index(after_klass)
+      end
+      i ||= count - 1 # last element
+
+      stack.insert(i + 1, entry)
+      self
+    end
+
+    def before(before_klass, *klass_and_args, &block)
+      entry = create_entry(klass_and_args, block)
+      remove(entry[0])
+
+      i = if before_klass.is_a? Array
+        before_klass.map {|x| index(x) }.compact.min
+      else
+        index(before_klass)
+      end
+      i ||= 0 # first element
+
+      stack.insert(i, entry)
+      self
+    end
+
+    def replace(old_klass, *klass_and_args, &block)
+      entry = create_entry(klass_and_args, block)
+      remove(entry[0])
+
+      i = index(old_klass)
+
+      unless i
+        raise RuntimeError, "middleware not present: #{old_klass}"
+      end
+
+      stack[i] = entry
+      self
+    end
+
+    def call(*args)
+      chain = build_chain
+      default_args = args
+
+      traverse = proc do |*args|
+        if args.empty?
+          args = default_args
+        else
+          default_args = args
+        end
+
+        if chain.empty?
+          yield(*args) if block_given?
+        else
+          middleware = chain.shift
+
+          if middleware.is_a?(Proc) && !middleware.lambda?
+            middleware.call(*args)
+
+            # implicit yield
+            traverse.call(*args)
+          else
+            middleware.call(*args, &traverse)
+          end
+        end
+      end
+      traverse.call(*args)
+    end
+
+
+    private
+
+    def create_entry(klass_and_args, block)
+      klass, *args = klass_and_args
+
+      if [ klass, block ].compact.count == 0
+        raise ArgumentError, 'either a middleware or block must be provided'
+      end
+
+      if klass
+        # validate
+        if klass.is_a? Class
+          unless klass.method_defined?(:call)
+            raise ArgumentError, "middleware must implement `.call`: #{klass}"
+          end
+        else
+          unless klass.respond_to?(:call)
+            raise ArgumentError, "middleware must respond to `.call`: #{klass}"
+          end
+
+          unless block.nil?
+            raise ArgumentError, 'can not supply middleware instance and block'
+          end
+        end
+
+        [ klass, args, block ].compact
+      else
+        [ block ]
+      end
+    end
+
+    def build_chain
+      # build the middleware stack
+      stack.map do |klass, args, block|
+        if klass.is_a? Class
+          klass.new(*args, &block)
+        else
+          if args.nil? || args.empty?
+            klass
+          else
+            # curry args
+            ->(*more_args, &block) do
+              klass.call(*args, *more_args, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/meddleware/version.rb

@@ -1,3 +1,3 @@
-class Meddleware
-  VERSION = '0.1.0'
+module Meddleware
+  VERSION = "0.3.0"
 end