emittance 0.0.2 → 0.0.3

data/lib/emittance/emitter.rb

@@ -36,33 +36,33 @@ module Emittance
         "_non_emitting_#{method_name}".to_sym
       end
 
-      # @private
-      def emitting_method_event(emitter_klass, method_name)
-        Emittance::Event.event_klass_for(emitter_klass, method_name)
-      end
-
       # @private
       def emitter_eval(klass, *args, &blk)
         if klass.respond_to? :class_eval
-          klass.class_eval *args, &blk
+          klass.class_eval(*args, &blk)
         else
-          klass.singleton_class.class_eval *args, &blk
+          klass.singleton_class.class_eval(*args, &blk)
         end
       end
     end
     # :nocov:
 
+    ##
     # Included and extended whenever {Emittance::Emitter} is extended.
+    #
     module ClassAndInstanceMethods
       # Emits an {Emittance::Event event object} to watchers.
       #
       # @param identifier [Symbol, Emittance::Event] either an explicit Event object or the identifier that can be
       #   parsed into an Event object.
       # @param payload [*] any additional information that might be helpful for an event's handler to have. Can be
-      #   standardized on a per-event basis by pre-defining the class associated with the
+      #   standardized on a per-event basis by pre-defining the class associated with the identifier and validating
+      #   the payload. See {Emittance::Event} for more details.
+      # @param broker [Symbol] the identifier for the broker you wish to handle the event. Requires additional gems
+      #   if not using the default.
       #
       # @return the payload
-      def emit(identifier, payload = nil, broker: :synchronous)
+      def emit(identifier, payload: nil, broker: :synchronous)
         now = Time.now
         event_klass = _event_klass_for identifier
         event = event_klass.new(self, now, payload)
@@ -76,56 +76,64 @@ module Emittance
       #
       # @param identifiers [*] anything that can be used to generate an +Event+ class.
       # @param payload (@see #emit)
+      # @param broker (@see #emit)
       def emit_with_dynamic_identifier(*identifiers, payload:, broker: :synchronous)
         now = Time.now
-        event_klass = _event_klass_for *identifiers
+        event_klass = _event_klass_for(*identifiers)
         event = event_klass.new(self, now, payload)
         _send_to_broker event, broker
 
         payload
       end
 
-      private
-
-      # @private
-      def _event_klass_for(*identifiers)
-        Emittance::Event.event_klass_for *identifiers
-      end
-
-      # @private
-      def _send_to_broker(event, broker)
-        Emittance::Brokerage.send_event event, broker
-      end
-
-      # Tells the class to emit an event when a any of the given set of methods. By default, the event classes are named
-      # accordingly: If a +Foo+ object +emits_on+ +:bar+, then the event's class will be named +FooBarEvent+, and will
-      # be a subclass of +Emittance::Event+.
+      # Tells the object to emit an event when a any of the given set of methods. By default, the event classes are
+      # named accordingly: If a +Foo+ object +emits_on+ +:bar+, then the event's class will be named +FooBarEvent+, and
+      # will be a subclass of +Emittance::Event+.
       #
       # The payload for this event will be the value returned from the method call.
       #
       # @param method_names [Symbol, String, Array<Symbol, String>] the methods whose calls emit an event
-      def emits_on(*method_names)
+      def emits_on(*method_names, identifier: nil)
         method_names.each do |method_name|
           non_emitting_method = Emittance::Emitter.non_emitting_method_for method_name
 
-          Emittance::Emitter.emitter_eval(self) do
-            if method_defined?(non_emitting_method)
-              warn "Already emitting on #{method_name.inspect}"
-              return
-            end
+          Emittance::Emitter.emitter_eval(self, &_method_patch_block(method_name, non_emitting_method, identifier))
+        end
+      end
+
+      private
 
-            alias_method non_emitting_method, method_name
+      def _method_patch_block(method_name, non_emitting_method, identifier)
+        lambda do |_klass|
+          return if method_defined?(non_emitting_method)
 
-            module_eval <<-RUBY, __FILE__, __LINE__ + 1
-              def #{method_name}(*args, &blk)
-                return_value = #{non_emitting_method}(*args, &blk)
-                emit_with_dynamic_identifier self.class, __method__, payload: return_value
-                return_value
-              end
-            RUBY
-          end
+          alias_method non_emitting_method, method_name
+
+          module_eval _method_patch_str(method_name, non_emitting_method, identifier), __FILE__, __LINE__ + 1
         end
       end
+
+      def _method_patch_str(method_name, non_emitting_method, identifier)
+        <<~RUBY
+          def #{method_name}(*args, &blk)
+            return_value = #{non_emitting_method}(*args, &blk)
+            if #{!identifier.nil? ? true : false}
+              emit #{!identifier.nil? ? identifier : false}, payload: return_value
+            else
+              emit_with_dynamic_identifier self.class, __method__, payload: return_value
+            end
+            return_value
+          end
+        RUBY
+      end
+
+      def _event_klass_for(*identifiers)
+        Emittance::Event.event_klass_for(*identifiers)
+      end
+
+      def _send_to_broker(event, broker)
+        Emittance::Brokerage.send_event event, broker
+      end
     end
   end
 end

data/lib/emittance/errors.rb

@@ -1,12 +1,15 @@
-# froze_string_literal: true
+# frozen_string_literal: true
 
 module Emittance
   # Raised when an identifier (for the purposes of identifying an event class) cannot be parsed, or an event class
   # can otherwise not be found or generated.
   class InvalidIdentifierError < StandardError; end
 
+  # Raised when an identifier couldn't be generated from a class. Typically a validation error.
+  class IdentifierGenerationError < StandardError; end
+
   # Raised when an identifier registration is attempted, but there exists an event registered to the given identifiered.
-  class IdentifierTakenError < StandardError; end
+  class IdentifierCollisionError < StandardError; end
 
   # Used when a custom event type undergoes payload validation.
   class InvalidPayloadError < StandardError; end

data/lib/emittance/event.rb

@@ -26,48 +26,119 @@ module Emittance
   #     end
   #   end
   #
-  # == Custom Identifiers
+  # == Identifiers
+  #
+  # Events are identified by what we call "Identifiers." These come in the form of symbols, and can be used to identify
+  # specific event types.
+  #
+  # === Identifier Naming
+  #
+  # The naming convention for events and their identifiers goes like this: the name of an event class will be the
+  # CamelCase form of its identifier, plus the word +Event+. For example, +FooEvent+ can be identified with +:foo+.
+  # Thus, the events received by watchers of +:foo+ will be instances of `FooEvent`. Conversely, if you make an event
+  # class +BarEvent+ that inherits from +Emittance::Event+, its built-in identifier will be +:bar+. You can see what
+  # a +Emittance::Event+ subclass's identifier is by calling +.identifiers+ on it.
+  #
+  #   class SomethingHappenedEvent < Emittance::Event
+  #   end
+  #
+  #   MyEvent.identifiers
+  #   # => [:something_happened]
+  #
+  #   MyEvent.new.identifiers
+  #   # => [:something_happened]
+  #
+  # The namespace resultion operator (+::+) in an event's class name will translate to a +/+ in the identifier name:
+  #
+  #   class Foo::BarEvent < Emittance::Event
+  #   end
+  #
+  #   Foo::BarEvent.identifiers
+  #   #=> [:'foo/bar']
+  #
+  # === Custom Identifiers
   #
   # By default, the identifier for this event will be the snake_case form of the class name with +Event+ chopped off:
   #
-  #   FooEvent.identifier # => :foo
+  #   FooEvent.identifiers
+  #   # => [:foo]
   #
   # You can set a custom identifier for the event class like so:
   #
   #   FooEvent.add_identifier :bar
+  #   FooEvent.identifiers
+  #   # => [:foo, :bar]
+  #
+  # Now, when emitters emit +:bar+, this will be the event received by watchers. +#add_identifier+ will raise an
+  # {Emittance::IdentifierCollisionError} if you attempt to add an identifier that has already been claimed. This
+  # error will also be raised if you try to add an identifier that already has an associated class. For example:
+  #
+  #   class FooEvent < Emittance::Event
+  #   end
+  #
+  #   class BarEvent < Emittance::Event
+  #   end
+  #
+  #   BarEvent.add_identifier :foo
+  #   # => Emittance::IdentifierCollisionError
+  #
+  # This error is raised because, even though we haven't explicitly add the identifier +:foo+ for +FooEvent+, Emittance
+  # is smart enough to know that there exists a class whose name resolves to +:foo+.
+  #
+  # It's best to use custom identifiers very sparingly. One reason for this can be illustrated like so:
+  #
+  #   class FooEvent < Emittance::Event
+  #   end
+  #
+  #   FooEvent.add_identifier :bar
+  #   FooEvent.identifiers
+  #   # => [:foo, :bar]
+  #
+  #   class BarEvent < Emittance::Event
+  #   end
+  #
+  #   BarEvent.identifiers
+  #   # => []
   #
-  # Now, when emitters emit +:bar+, this will be the event received by watchers.
+  # Since +BarEvent+'s default identifier was already reserved when it was created, it could not claim that identifier.
+  # We can manually add an identifier post-hoc, but this would nevertheless become confusing.
   #
   class Event
     class << self
-      # @return [Symbol] the identifier that can be used by the {Emittance::Broker broker} to find event handlers
-      def identifier
-        EventBuilder.klass_to_identifier self
+      # @return [Array<Symbol>] the identifier that can be used by the {Emittance::Broker broker} to find event handlers
+      def identifiers
+        EventLookup.identifiers_for_klass(self).to_a
       end
 
       # Gives the Event object a custom identifier.
       #
       # @param sym [Symbol] the identifier you wish to identify this event by when emitting and watching for it
       def add_identifier(sym)
-        EventBuilder.register_custom_identifier self, sym
+        raise Emittance::InvalidIdentifierError, 'Identifiers must respond to #to_sym' unless sym.respond_to?(:to_sym)
+        EventLookup.register_identifier self, sym.to_sym
       end
 
-      # @private
+      # @param identifiers [*] anything that can be derived into an identifier (or the event class itself) for the
+      #   purposes of looking up an event class.
       def event_klass_for(*identifiers)
-        EventBuilder.objects_to_klass *identifiers
+        EventLookup.find_event_klass(*identifiers)
       end
     end
 
     attr_reader :emitter, :timestamp, :payload
 
+    # @param emitter the object that emitted the event
+    # @param timestamp [Time] the time at which the event occurred
+    # @param payload any useful data that might be of use to event watchers
     def initialize(emitter, timestamp, payload)
       @emitter = emitter
       @timestamp = timestamp
       @payload = payload
     end
 
-    def identifier
-      self.class.identifier
+    # @return [Array<Symbol>] all identifiers that can be used to identify the event
+    def identifiers
+      self.class.identifiers
     end
   end
 end

data/lib/emittance/event_lookup.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Emittance
+  ##
+  # For looking up event classes by their identifiers. Can perform a reverse lookup of identifiers by their associated
+  # event class.
+  #
+  module EventLookup
+    class << self
+      include Emittance::Helpers::StringHelpers
+
+      # Look up an {Emittance::Event} class by an identifier. Generates an Event class if no such class exists for
+      # that identifier.
+      #
+      #   EventLookup.find_event_klass :foo
+      #   # => FooEvent
+      #
+      # When passed subclass of {Emittance::Event}, it returns that event class.
+      #
+      #   class BarEvent < Emittance::Event
+      #   end
+      #
+      #   EventLookup.find_event_klass BarEvent
+      #   # => BarEvent
+      #
+      # Instances of an {Emittance::Event} will fetch the class of that instance.
+      #
+      #   EventLookup.find_event_klass BarEvent.new(nil, nil, nil)
+      #   # => BarEvent
+      #
+      # Can be passed multiple arguments as a composite identifier. Useful for identifying events by Class#method.
+      #
+      #   # Not entirely necessary, but for illustrative purposes.
+      #   class Baz
+      #     def greet
+      #     end
+      #   end
+      #
+      #   EventLookup.find_event_klass Baz, :greet
+      #   # => BazGreetEvent
+      #
+      # @param objs [*] anything that can be used to identify an Event class
+      # @return [Emittance::Event] the event class identifiable by the params
+      def find_event_klass(*objs)
+        klass = nil
+
+        klass ||= pass_klass_through(*objs)
+        klass ||= klass_of_event(*objs)
+        klass ||= find_by_identifier(*objs)
+
+        klass
+      end
+
+      # @param klass [Class] a subclass of {Emittance::Event} you wish to find the identifiers for
+      # @return [Set<Symbol>] a collection of identifiers that can be used to identify that event class
+      def identifiers_for_klass(klass)
+        Emittance::EventLookup::Registry.identifiers_for_klass(klass)
+      end
+
+      # Registers an identifier for an Event class. After registering, that identifier can be used to identify those
+      # events.
+      #
+      # @param klass [Class] the class you wish to register the identifier for
+      # @param identifier [Symbol] identifier you want to identify the class as
+      # @return [Class] the class for which you've just registered an identifier
+      def register_identifier(klass, identifier)
+        Emittance::EventLookup::Registry.register_identifier klass: klass, identifier: identifier
+      end
+
+      private
+
+      def pass_klass_through(*objs)
+        objs.length == 1 && event_klass?(objs[0]) ? objs[0] : nil
+      end
+
+      def klass_of_event(*objs)
+        objs.length == 1 && event_object?(objs[0]) ? objs[0].class : nil
+      end
+
+      def find_by_identifier(*objs)
+        identifier = CompositeIdentifier.new(*objs).generate
+        lookup_identifier identifier
+      end
+
+      def event_klass?(obj)
+        obj.is_a?(Class) && obj < Emittance::Event
+      end
+
+      def event_object?(obj)
+        obj.is_a? Emittance::Event
+      end
+
+      def lookup_identifier(identifier)
+        Emittance::EventLookup::Registry.fetch_event_klass(identifier)
+      end
+    end
+
+    ##
+    # Shared behavior for things that want to convert back and forth between event classes and identifiers
+    #
+    class EventKlassConverter
+      include Emittance::Helpers::StringHelpers
+
+      # The thing we want to append to every event class name
+      KLASS_NAME_SUFFIX = 'Event'
+    end
+
+    ##
+    # Converts a collection of objects to a ready-to-go identifier.
+    #
+    class CompositeIdentifier < EventKlassConverter
+      def initialize(*objs)
+        @objs = objs
+      end
+
+      # Compiles the objects and generates an event class name for them.
+      def generate
+        parts = objs.map { |obj| identifier_name_for obj }
+        compose_identifier_parts parts
+      end
+
+      private
+
+      attr_reader :objs
+
+      def identifier_name_for(obj)
+        name_str = obj.to_s
+        name_str = clean_up_punctuation name_str
+        name_str = snake_case name_str
+
+        name_str
+      end
+
+      def compose_identifier_parts(parts)
+        parts.join('_').to_sym
+      end
+    end
+
+    ##
+    # Derives an event class name from an identifier.
+    #
+    class EventKlassName < EventKlassConverter
+      def initialize(identifier)
+        @identifier = identifier
+      end
+
+      # Generates an event class name for the given identifier.
+      def generate
+        base_name = camel_case identifier.to_s
+        decorate_klass_name base_name
+      end
+
+      private
+
+      attr_reader :identifier
+
+      def decorate_klass_name(klass_name_str)
+        "#{klass_name_str}#{KLASS_NAME_SUFFIX}"
+      end
+    end
+
+    ##
+    # Derives an identifier from the name of an event class.
+    #
+    class EventIdentifier < EventKlassConverter
+      def initialize(klass)
+        @klass = klass
+        validate_klass
+      end
+
+      # Generates an identifier name for the given event class.
+      def generate
+        camel_cased_name = undecorate_klass_name(klass.name)
+        snake_case(camel_cased_name).to_sym
+      end
+
+      private
+
+      attr_reader :klass
+
+      def validate_klass
+        subklass_error_msg = "#{klass.name} is not a subclass of Emittance::Event!"
+        raise Emittance::IdentifierGenerationError, subklass_error_msg unless klass < Emittance::Event
+      end
+
+      def undecorate_klass_name(klass_name)
+        klass_name.gsub(/#{KLASS_NAME_SUFFIX}$/, '')
+      end
+    end
+
+    ##
+    # Caches event-to-identifier and identifier-to-event mappings. The strategy here is to lazily store/load those
+    # mappings. They are created on lookup. The other option would be to add a +.inherited+ method to
+    # {Emittance::Event} that would make subclasses register themselves, but would cause some unwanted entanglement.
+    #
+    module Registry
+      @identifier_to_klass_mappings = {}
+      @klass_to_identifier_mappings = {}
+
+      class << self
+        include Emittance::Helpers::ConstantHelpers
+
+        # Finds or generates the event class associated with the identifier.
+        #
+        # @param identifier [Symbol] the identifier registered to the event class you wish to fetch
+        # @return [Class] the event class you wish to fetch
+        def fetch_event_klass(identifier)
+          klass = nil
+
+          klass ||= identifier_to_klass_mappings[identifier]
+          klass ||= derive_event_klass(identifier)
+
+          klass
+        end
+
+        # Retrieves all identifiers associated with the event class.
+        #
+        # @param event_klass [Class] the class you want the identifiers for
+        # @return [Set<Symbol>] all identifiers that can be used to identify the given event class
+        def identifiers_for_klass(event_klass)
+          lookup_klass_to_identifier_mapping(event_klass) ||
+            (create_mapping_for_klass(event_klass) && lookup_klass_to_identifier_mapping(event_klass))
+        end
+
+        # Registers the given identifier for the given event class.
+        #
+        # @param klass [Class] the event class you would like to register the identifier for
+        # @param identifier [Symbol] the identifier with which you want to identify the event class
+        # @return [Class] the event class for which you've registered the identifier
+        def register_identifier(klass:, identifier:)
+          raise Emittance::InvalidIdentifierError unless valid_identifier? identifier
+          raise Emittance::IdentifierCollisionError if identifier_reserved? identifier, klass
+
+          identifier_to_klass_mappings[identifier] = klass
+
+          klass_to_identifier_mappings[klass] ||= empty_collection
+          klass_to_identifier_mappings[klass] << identifier
+
+          klass
+        end
+
+        # Clears all registrations.
+        #
+        # @return [Boolean] true
+        def clear_registrations!
+          identifier_to_klass_mappings.clear
+          klass_to_identifier_mappings.clear
+        end
+
+        private
+
+        attr_reader :identifier_to_klass_mappings, :klass_to_identifier_mappings
+
+        def identifier_reserved?(identifier, klass)
+          klass_already_exists_for_identifier?(identifier, klass) || !!identifier_to_klass_mappings[identifier]
+        end
+
+        def klass_already_exists_for_identifier?(identifier, klass)
+          derived_klass_name = klass_name_for identifier
+          Object.const_defined?(derived_klass_name) && klass.name != derived_klass_name
+        end
+
+        def lookup_klass_to_identifier_mapping(event_klass)
+          klass_to_identifier_mappings[event_klass]
+        end
+
+        def create_mapping_for_klass(event_klass)
+          new_identifier = derive_identifier_from_klass(event_klass)
+          register_identifier(identifier: new_identifier, klass: event_klass)
+
+          new_identifier
+        end
+
+        def valid_identifier?(identifier)
+          identifier.is_a? Symbol
+        end
+
+        def derive_event_klass(identifier)
+          klass_name = klass_name_for identifier
+          event_klass = find_or_create_event_klass klass_name
+          register_identifier(identifier: identifier, klass: event_klass)
+
+          event_klass
+        end
+
+        def derive_identifier_from_klass(event_klass)
+          EventIdentifier.new(event_klass).generate
+        end
+
+        def klass_name_for(identifier)
+          EventKlassName.new(identifier).generate
+        end
+
+        def find_or_create_event_klass(klass_name)
+          lookup_event_klass(klass_name) || create_event_klass(klass_name)
+        end
+
+        def lookup_event_klass(klass_name)
+          Object.const_defined?(klass_name) ? Object.const_get(klass_name) : nil
+        end
+
+        def create_event_klass(klass_name)
+          new_klass = Class.new(Emittance::Event)
+          set_namespaced_constant_by_name klass_name, new_klass
+        end
+
+        def empty_collection
+          Set.new
+        end
+      end
+    end
+  end
+end