eventish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08c9cf6785fc35a3174bf04df8a3f46011a10f1dc465ed24903d3924c293927a'
+  data.tar.gz: 53efbd04a12d69149c594f375b3b79da0cda0a9ed6a339e09d88ff4a9d4d830b
+SHA512:
+  metadata.gz: 3aabb2135effcd4234379ef10beda4cb8cd2a5489b6b7318e7bc9cc84de6ef84daa5972b35496636dc3d439f7829cf2ef3ef27786c7512339a24b87404b4bce8
+  data.tar.gz: 63197732c22986bfc7f9d647808350886b71121cc9ccd3125ba35fa3f6eb3db2cc152b36c4f0fbd347224c46b9be50381a18e595014088341879769590593535

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2022 Mattia Roccoberton
+
+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,158 @@
+# Eventish
+
+Yet another opinionated events library which proposes a simple API to handle... events 🎉
+
+The main features:
+- composable: just require the components that you need;
+- with adapters: support _ActiveSupport::Notifications_;
+- with async events: support _ActiveJob_;
+- with callbacks: support _ActiveRecord_.
+
+## Install
+
+- Add to your Gemfile: `gem 'eventish'` (and execute `bundle`)
+- Create an initializer - _config/initializers/eventish.rb_:
+
+```rb
+require 'eventish/adapters/active_support'
+
+Eventish.setup do |config|
+  config.adapter = Eventish::Adapters::ActiveSupport
+end
+
+Rails.configuration.to_prepare do
+  # NOTE: required to load the event descendants when eager_load is off
+  unless Rails.configuration.eager_load
+    events = Rails.root.join('app/events/**/*.rb').to_s
+    Dir[events].sort.each { |event| require event }
+  end
+end
+
+Rails.configuration.after_initialize do
+  Eventish::SimpleEvent.subscribe_all # NOTE: events will be available after this point
+
+  Eventish.adapter.publish('app_loaded') # just a test event
+end
+```
+
+- Create some events - _app/events/main/app_loaded_event.rb_:
+
+```rb
+module Main
+  class AppLoadedEvent < Eventish::SimpleEvent
+    def call(_none, _options = {})
+      puts '> App loaded event'
+    end
+  end
+end
+```
+
+For a complete example please take a look at the [dummy app](spec/dummy) in the specs.
+
+### Adatpers
+
+Only _ActiveSupport_ is supported for now.
+
+```rb
+# initializer setup
+require 'eventish/adapters/active_support'
+
+Eventish.setup do |config|
+  config.adapter = Eventish::Adapters::ActiveSupport
+end
+```
+
+### Simple events
+
+Generic events not related to a specific component.
+
+```rb
+# initializer setup
+Rails.configuration.after_initialize do
+  # Subscribe all Eventish::SimpleEvent descendants using the configured adapter
+  # The descendants event classes must be loaded before this point - see eager_load notes in the Install section
+  Eventish::SimpleEvent.subscribe_all
+end
+```
+
+Sample event - _app/events/main/test_event.rb_:
+
+```rb
+module Main
+  class TestEvent < Eventish::SimpleEvent
+    def call(_none, _options = {})
+      puts '> A test event'
+    end
+
+    class << self
+      def event_name
+        # this is optional, if not set the event name will be inferred from the class name
+        # in this sample it would be "test" - TestEvent => underscore => remove _event suffix
+        'some_event'
+      end
+    end
+  end
+end
+```
+
+Publish the event: `Eventish.adapter.publish('some_event')`
+
+### Async events
+
+Events executed in a background process. Only _ActiveJob_ is supported for now.
+
+```rb
+# initializer setup
+require 'eventish/active_job_event'
+
+Rails.configuration.after_initialize do
+  Eventish::ActiveJobEvent.subscribe_all
+end
+```
+
+Sample event - _app/events/notifications/user_after_save_commit_event.rb_:
+
+```rb
+module Notifications
+  class UserAfterCommitEvent < Eventish::ActiveJobEvent
+    def call(user, _options = {})
+      Rails.logger.info ">>> User ##{user.id} after commit notification"
+    end
+  end
+end
+```
+
+### Callbacks
+
+Wrapper for callbacks. Only _ActiveRecord_ is supported for now.
+This is just a glue component to have callbacks with a nice syntax.
+
+```rb
+# initializer setup
+require 'eventish/callback'
+```
+
+Sample model usage:
+
+```rb
+class User < ActiveRecord::Base
+  before_validation ::Eventish::Callback
+  after_save_commit ::Eventish::Callback
+end
+```
+
+For events definition see Simple or Async events.
+
+## Do you like it? Star it!
+
+If you use this component just star it. A developer is more motivated to improve a project when there is some interest.
+
+Or consider offering me a coffee, it's a small thing but it is greatly appreciated: [about me](https://www.blocknot.es/about-me).
+
+## Contributors
+
+- [Mattia Roccoberton](https://www.blocknot.es): author
+
+## License
+
+The gem is available as open-source under the terms of the [MIT](LICENSE.txt).

data/lib/eventish/active_job_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Eventish
+  class ActiveJobEvent < ::ActiveJob::Base
+    def call(_target, _args, &_block)
+      raise NotImplementedError
+    end
+
+    def perform(target, args)
+      call(target, args)
+    end
+
+    class << self
+      include Eventish::EventApi
+
+      def trigger(target, args, &_block)
+        perform_later(target, args)
+      end
+    end
+  end
+end

data/lib/eventish/adapters/active_support.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Eventish
+  class Adapters
+    class ActiveSupport
+      class << self
+        def publish(event_name, target = nil, options: {})
+          ::ActiveSupport::Notifications.instrument(event_name, target: target, event_options: options)
+        end
+
+        def subscribe(event_name, handler)
+          ::ActiveSupport::Notifications.subscribe(event_name) do |name, start, finish, id, payload|
+            args = { event: name, id: id, start: start, finish: finish }
+            handler.trigger(payload[:target], args, &payload[:block])
+          end
+        end
+
+        def unsubscribe(event_name)
+          ::ActiveSupport::Notifications.unsubscribe(event_name)
+        end
+      end
+    end
+  end
+end

data/lib/eventish/callback.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Eventish
+  class Callback
+    class << self
+      def callback_event(target, &block)
+        event = "#{Eventish.underscore(target.class.to_s)}_#{__callee__}"
+        Eventish.adapter.publish(event, target, &block)
+      end
+
+      def callback_commit_event(target, &block)
+        event = "#{Eventish.underscore(target.class.to_s)}_after_commit"
+        Eventish.adapter.publish(event, target, &block)
+      end
+
+      alias_method :after_initialize, :callback_event
+      alias_method :after_find, :callback_event
+
+      alias_method :before_validation, :callback_event
+      alias_method :after_validation, :callback_event
+
+      alias_method :before_create, :callback_event
+      alias_method :around_create, :callback_event
+      alias_method :after_create, :callback_event
+
+      alias_method :before_update, :callback_event
+      alias_method :around_update, :callback_event
+      alias_method :after_update, :callback_event
+
+      alias_method :before_save, :callback_event
+      alias_method :around_save, :callback_event
+      alias_method :after_save, :callback_event
+
+      alias_method :before_destroy, :callback_event
+      alias_method :around_destroy, :callback_event
+      alias_method :after_destroy, :callback_event
+
+      alias_method :after_commit, :callback_commit_event
+      alias_method :after_save_commit, :callback_commit_event # => after_commit
+      alias_method :after_create_commit, :callback_commit_event # => after_commit
+      alias_method :after_update_commit, :callback_commit_event # => after_commit
+      alias_method :after_destroy_commit, :callback_commit_event # => after_commit
+      alias_method :after_rollback, :callback_event
+
+      alias_method :after_touch, :callback_event
+    end
+  end
+end

data/lib/eventish/event_api.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Eventish
+  module EventApi
+    def <=>(other)
+      other&.priority <=> priority
+    end
+
+    def event_name
+      # If event_name is not set, infer the event from the class name
+      @event_name ||= Eventish.underscore(to_s).delete_suffix('_event')
+    end
+
+    def priority
+      0
+    end
+
+    def subscribe
+      Eventish.adapter.subscribe(event_name, self)
+    end
+
+    def subscribe_all
+      # iterate the descendants
+      ObjectSpace.each_object(singleton_class).sort.each(&:subscribe)
+    end
+  end
+end

data/lib/eventish/simple_event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Eventish
+  class SimpleEvent
+    def call(_target, _args, &_block)
+      raise NotImplementedError
+    end
+
+    class << self
+      include EventApi
+
+      def trigger(target, args, &block)
+        new.call(target, args, &block)
+      end
+    end
+  end
+end

data/lib/eventish/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Eventish # :nodoc:
+  VERSION = '0.1.0'
+end

data/lib/eventish.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'eventish/event_api'
+require_relative 'eventish/simple_event'
+
+module Eventish
+  OPTIONS = %i[adapter].freeze
+
+  MissingAdapterError = Class.new(StandardError)
+
+  module_function
+
+  def adapter
+    config.adapter
+  end
+
+  def config
+    @options ||= Struct.new(*OPTIONS).new # rubocop:disable Naming/MemoizedInstanceVariableName
+  end
+
+  def setup
+    @options ||= Struct.new(*OPTIONS).new
+    yield(@options) if block_given?
+    raise MissingAdapterError, 'Please specify an event adapter' unless @options.adapter
+
+    @options
+  end
+
+  def underscore(camel_cased_word)
+    return camel_cased_word.to_s unless /[A-Z-]|::/.match?(camel_cased_word)
+
+    word = camel_cased_word.to_s.gsub(/\A.*::/, '')
+    word.gsub!(/([A-Z]+)(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { ($1 || $2) << "_" }
+    word.tr!("-", "_")
+    word.downcase!
+    word
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: eventish
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mattia Roccoberton
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-05-17 00:00:00.000000000 Z
+dependencies: []
+description: A simple and composable event library
+email: mat@blocknot.es
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/eventish.rb
+- lib/eventish/active_job_event.rb
+- lib/eventish/adapters/active_support.rb
+- lib/eventish/callback.rb
+- lib/eventish/event_api.rb
+- lib/eventish/simple_event.rb
+- lib/eventish/version.rb
+homepage: https://github.com/blocknotes/eventish
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/blocknotes/eventish
+  source_code_uri: https://github.com/blocknotes/eventish
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Yet another events library
+test_files: []