stenotype 0.1.0 → 0.1.1

data/lib/stenotype/context_handlers.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'stenotype/context_handlers/base'
-require 'stenotype/context_handlers/rails/controller'
-require 'stenotype/context_handlers/rails/active_job'
-require 'stenotype/context_handlers/klass'
-require 'stenotype/context_handlers/collection'
+require "stenotype/context_handlers/base"
+require "stenotype/context_handlers/rails/controller"
+require "stenotype/context_handlers/rails/active_job"
+require "stenotype/context_handlers/klass"
+require "stenotype/context_handlers/collection"
 
 module Stenotype
   #
@@ -24,9 +24,7 @@ module Stenotype
       #
       # @param handler {#publish} A handler with implemented method [#publish]
       #
-      def register(handler)
-        known.register(handler)
-      end
+      delegate :register, to: :known
     end
   end
 end

data/lib/stenotype/context_handlers/base.rb

@@ -9,6 +9,18 @@ module Stenotype
     # @attr_reader {Object} context A context in which the event was emitted
     # @attr_reader {Hash} options A hash of additional options
     #
+    # @example Defining a custom Handler
+    #   class MyCustomHandler < Stenotype::ContextHandlers::Base
+    #     self.context_name = :custom_handler
+    #
+    #     def as_json(*_args)
+    #       {
+    #         value1: context.value1,
+    #         value2: context.value2
+    #       }
+    #     end
+    #   end
+    #
     class Base
       attr_reader :context, :options
 
@@ -18,7 +30,7 @@ module Stenotype
       #
       # @return {#as_json} A context handler implementing [#as_json]
       #
-      def initialize(context, options = {})
+      def initialize(context, options: {})
         @context = context
         @options = options
       end
@@ -43,8 +55,7 @@ module Stenotype
         # @raise {NotImplementedError} in case handler name is not specified.
         #
         def handler_name
-          @handler_name || raise(NotImplementedError,
-                                 "Please, specify the handler_name of #{self}")
+          @handler_name || raise(NotImplementedError, "Please, specify the handler_name of #{self}")
         end
       end
     end

data/lib/stenotype/context_handlers/collection.rb

@@ -4,61 +4,105 @@ module Stenotype
   module ContextHandlers
     #
     # A class representing a list of available context handlers
+    # @example Complete usage overview
+    #   class MyCustomHander
+    #     self.handler_name = :custom_handler
     #
-    class Collection < Array
+    #     def as_json(*_args)
+    #       {
+    #         key: :value
+    #       }
+    #     end
+    #   end
+    #
+    #   collection = Stenotype::ContextHandlers::Collection.new
+    #   collection.register(MyCustomHandler)
+    #
+    #   collection.registered?(MyCustomHandler) #=> true
+    #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+    #   collection.unregister(MyCustomHandler)
+    #   collection.registered?(MyCustomHandler) #=> false
+    #
+    #   collection.register(SomeRandomClass) #=> ArgumentError
+    #   collection.unregister(SomeRandomClass) #=> ArgumentError
+    #   collection.choose(handler_name: :unknown) #=> Stenotype::UnknownHandlerError
+    #
+    class Collection < ::Collectible::CollectionBase
+      #
+      # Return a handler with given handler_name if found in collection,
+      # raises if a handler is not registered
       #
       # @param handler_name {Symbol} a handler to be found in the collection
-      # @raise {Stenotype::Exceptions::UnknownHandler} in case a handler is not registered
+      # @raise {Stenotype::Errors::UnknownHandler} in case a handler is not registered
       # @return {#as_json} A handler which respond to #as_json
       #
+      # @example When a handler is present in the collection
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+      #
+      # @example When a handler is not present in the collection
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+      #
       def choose(handler_name:)
-        handler = detect { |e| e.handler_name == handler_name }
-        handler || raise(Stenotype::Exceptions::UnknownHandler,
-                         "Handler '#{handler_name}' is not found. " \
-                         "Please make sure the handler you've specified is " \
-                         'registered in the list of known handlers. ' \
-                         "See #{Stenotype::ContextHandlers} for more information.")
+        handler = find_by(handler_name: handler_name)
+        handler || raise(
+          Stenotype::UnknownHandlerError,
+          "Handler '#{handler_name}' is not found. "\
+          "Please make sure the handler you've specified is "\
+          "registered in the list of known handlers. "\
+          "See #{Stenotype::ContextHandlers} for more information.",
+        )
       end
 
       #
-      # @param handler {#as_json} a new handler to be added to collection
-      # @raise {ArgumentError} in case handler does not inherit from {Stenotype::ContextHandlers::Base}
-      # @return {Stenotype::ContextHandlers::Collection} a collection object
+      # @!method register(handler)
+      #   Registers a new handler.
+      #   @!scope instance
+      #   @param handler {#as_json} a new handler to be added to collection
+      #   @return {Stenotype::ContextHandlers::Collection} a collection object
+      #   @example Registering a new handler
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.register(MyCustomHandler) # with handler_name = :custom_handler
       #
-      def register(handler)
-        unless handler < Stenotype::ContextHandlers::Base
-          raise ArgumentError,
-                "Handler must inherit from #{Stenotype::ContextHandlers::Base}, " \
-                "but inherited from #{handler.superclass}"
-        end
-
-        push(handler) unless registered?(handler)
-        self
-      end
+      alias_method :register, :push
 
+      #
+      # Removes a registered handler.
+      #
+      # @example Register and unregister a handler
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #   collection.unregister(MyCustomHandler) # removes MyCustomHandler from the list of handlers
       #
       # @param handler {#as_json} a handler to be removed from the collection of known handlers
-      # @raise {ArgumentError} in case handler does not inherit from {Stenotype::ContextHandlers::Base}
       # @return {Stenotype::ContextHandlers::Collection} a collection object
       #
+      # @todo Add delete to the collectible delegation list
+      #   and then use `alias_method :unregister, :delete`
       def unregister(handler)
-        unless handler < Stenotype::ContextHandlers::Base
-          raise ArgumentError,
-                "Handler must inherit from #{Stenotype::ContextHandlers::Base}, " \
-                "but inherited from #{handler.superclass}"
-        end
-
-        delete(handler) if registered?(handler)
+        items.delete(handler)
         self
       end
 
       #
-      # @param handler {#as_json} a handler to be checked for presence in a collection
-      # @return [true, false]
+      # @!method registered?(handler)
+      #   Checks whether a given handler is registered in collection
+      #   @!scope instance
+      #   @param handler {#as_json} a handler to be checked for presence in a collection
+      #   @return [true, false]
+      #   @example When a handler is registered
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #     collection.registered?(MyCustomHandler) # true
       #
-      def registered?(handler)
-        include?(handler)
-      end
+      #   @example When a handler is not registered
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.registered?(UnregisteredHandler) # false
+      #
+
+      alias_method :registered?, :include?
     end
   end
 end

data/lib/stenotype/context_handlers/rails/active_job.rb

@@ -22,21 +22,13 @@ module Stenotype
         def as_json(*_args)
           {
             job_id: job_id,
-            enqueued_at: Time.now,
+            enqueued_at: Time.now.utc,
             queue_name: queue_name,
-            class: context.class.name
+            class: context.class.name,
           }
         end
 
-        private
-
-        def job_id
-          context.job_id
-        end
-
-        def queue_name
-          context.queue_name
-        end
+        delegate :job_id, :queue_name, to: :context
       end
     end
   end

data/lib/stenotype/context_handlers/rails/controller.rb

@@ -14,20 +14,19 @@ module Stenotype
         #
         def as_json(*_args)
           {
-            class: request.controller_class.name,
-            method: request.method,
-            url: request.url,
-            referer: request.referer,
-            params: request.params.except('controller', 'action'),
-            ip: request.remote_ip
+            class: controller_class.name,
+            method: method,
+            url: url,
+            referer: referer,
+            params: params.except("controller", "action"),
+            ip: remote_ip,
           }
         end
 
-        private
-
-        def request
-          context.request
-        end
+        delegate :request, to: :context
+        delegate :method, :url, :referer, :remote_ip, :params,
+                 :controller_class, to: :request
+        private :request, :method, :url, :referer, :remote_ip, :params, :controller_class
       end
     end
   end

data/lib/stenotype/dispatcher.rb

@@ -9,8 +9,7 @@ module Stenotype
     #
     # Publishes an event to the list of configured targets.
     #
-    # @example
-    #
+    # @example Manually dispatching an event
     #   event = Stenotype::Event.new(data, options, eval_context)
     #   Stenotype::Dispatcher.new.publish(event)
     #

data/lib/stenotype/emitter.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # An extension for a plain Ruby class in order to track invocation of
+  # instance methods.
+  #
+  module Emitter
+    #
+    # Class methods for target to be extended by
+    #
+    ClassMethodsExtension = Class.new(Module)
+    #
+    # Instance methods to be included into target class ancestors chain
+    #
+    InstanceMethodsExtension = Class.new(Module)
+
+    # @!visibility private
+    def self.included(klass)
+      instance_mod = InstanceMethodsExtension.new
+      class_mod = ClassMethodsExtension.new
+
+      build_instance_methods(instance_mod)
+      build_class_methods(class_mod)
+
+      klass.const_set(:InstanceProxy, Module.new)
+      klass.const_set(:ClassProxy, Module.new)
+
+      klass.public_send(:include, instance_mod)
+      klass.extend(class_mod)
+
+      super
+    end
+
+    #
+    # @!method emit_event(data = {}, method: caller_locations.first.label, eval_context: nil)
+    #   A method injected into target class to manually track events
+    #   @!scope instance
+    #   @param data {Hash} Data to be sent to the targets
+    #   @param method {String} An optional method name
+    #   @param eval_context {Hash} A hash linking object to context handler
+    #   @return {Stenotype::Event} An instance of emitted event
+    #   @example Usage of emit_event
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #
+    #       def some_method
+    #         data = collection_data
+    #         emit_event(data, eval_context: self) # Track event with given data
+    #         data
+    #       end
+    #     end
+    #
+
+    #
+    # @!method emit_event_before(*methods)
+    #   A class method injected into target class to track instance methods invocation
+    #   @param methods {Array<Symbol>} A list of method before which an event will be emitted
+    #   @!scope class
+    #   @example Usage of emit_event_before
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #       emit_event_before :some_method # Triggers an event upon calling some_method
+    #
+    #       def some_method
+    #         # do something
+    #       end
+    #     end
+    #
+
+    #
+    # @!method emit_klass_event_before(*class_methods)
+    #   A class method injected into a target class to track class methods invocation
+    #   @!scope class
+    #   @param class_methods {Array<Symbol>} A list of class method before which
+    #     an event will be emitted
+    #   @example Usage emit_klass_event_before
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #       emit_klass_event_before :some_method # Triggers an event upon calling some_method
+    #
+    #       def self.some_method
+    #         # do something
+    #       end
+    #     end
+    #
+
+    #
+    # Adds an instance method: [#emit_event] to a target class
+    #   where {Stenotype::Emitter} in included in
+    #
+    def self.build_instance_methods(instance_mod)
+      instance_mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def emit_event(data = {}, method: caller_locations.first.label, eval_context: nil)
+          Stenotype::Event.emit!(
+            {
+              type: "class_instance",
+              **data,
+            },
+            options: {
+              class: self.class.name,
+              method: method.to_sym
+            },
+            eval_context: (eval_context || { klass: self })
+          )
+        end
+      RUBY
+    end
+
+    #
+    # Adds class method [#emit_klass_event_before] to every class
+    #   inherited from [Object]
+    #
+    def self.build_class_methods(class_mod)
+      class_mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def emit_event_before(*methods)
+          proxy = const_get(:InstanceProxy)
+
+          methods.each do |method|
+            proxy.module_eval do
+              define_method(method) do |*args, **rest_args, &block|
+                Stenotype::Event.emit!(
+                  { type: "class_instance" },
+                  options: {
+                    class: self.class.name,
+                    method: __method__
+                  },
+                  eval_context: { klass: self }
+                )
+                super(*args, **rest_args, &block)
+              end
+            end
+          end
+
+          send(:prepend, proxy)
+        end
+
+        def emit_klass_event_before(*class_methods)
+          proxy = const_get(:ClassProxy)
+
+          class_methods.each do |method|
+            proxy.module_eval do
+              define_method(method) do |*args, **rest_args, &block|
+                Stenotype::Event.emit!(
+                  { type: "class" },
+                  options: {
+                    class: self.name,
+                    method: __method__
+                  },
+                  eval_context: { klass: self }
+                )
+                super(*args, **rest_args, &block)
+              end
+            end
+
+            singleton_class.send(:prepend, proxy)
+          end
+        end
+      RUBY
+    end
+  end
+end

data/lib/stenotype/event.rb

@@ -8,8 +8,7 @@ module Stenotype
     #
     # Delegates event to instance of {Stenotype::Event}.
     #
-    # @example
-    #
+    # @example Emit an event using class method
     #   Stenotype::Event.emit!(data, options, eval_context)
     #
     # @param data {Hash} Data to be published to the targets.
@@ -27,9 +26,10 @@ module Stenotype
     attr_reader :data, :options, :eval_context, :dispatcher
 
     #
-    # @example
-    #
-    #   Stenotype::Event.emit!(data, options, eval_context)
+    # @example Create an event
+    #   event = Stenotype::Event.new(data, options, eval_context)
+    # @example Create an event with custom dispatcher
+    #   event = Stenotype::Event.new(data, options, eval_context, dispatcher: MyDispatcher.new)
     #
     # @param {Hash} data Data to be published to the targets.
     # @param {Hash} options A hash of additional options to be tracked.
@@ -41,16 +41,15 @@ module Stenotype
       @data = data
       @options = options
       @eval_context = eval_context
-      @dispatcher = dispatcher
+      @dispatcher = dispatcher.new
     end
 
     #
     # Emits a {Stenotype::Event}.
     #
-    # @example
-    #
+    # @example Emit an instance of event
     #   event = Stenotype::Event.new(data, options, eval_context)
-    #   event.emit!
+    #   event.emit! #=> Publishes the event to targets
     #
     def emit!
       dispatcher.publish(self)