emittance 0.0.1 → 0.0.2

data/lib/emittance/event/event_builder.rb

@@ -1,74 +1,154 @@
-# @private
-class Emittance::Event::EventBuilder
-  KLASS_NAME_SUFFIX = 'Event'.freeze
-
-  class << self
-    def object_to_klass(obj)
-      return obj if pass_klass_through?(obj)
-
-      klass_name = klassable_name_for obj
-      klass_name = dress_up_klass_name klass_name
-      find_or_create_event_klass klass_name
-    end
-
-    def klass_to_identifier(klass)
-      identifier_str = klass.name
-      identifier_str = undress_klass_name identifier_str
-      identifier_str = snake_case identifier_str
-
-      identifier_str.to_sym
-    end
-
-    private
-
-    def pass_klass_through?(obj)
-      obj.is_a?(Class) && obj < Emittance::Event
-    end
-
-    def klassable_name_for(obj)
-      name_str = obj.to_s
-      name_str = camel_case name_str
-      name_str = clean_up_punctuation name_str
+# frozen_string_literal: true
+
+module Emittance
+  # @private
+  class Event
+    class EventBuilder
+      KLASS_NAME_SUFFIX = 'Event'
+
+      class << self
+        def klass_exists_for_identifier?(identifier)
+          klass_name = generate_event_klass_name identifier
+          !!lookup_event_klass(klass_name)
+        end
+
+        def objects_to_klass(*objs)
+          klass = nil
+
+          klass ||= pass_klass_through(*objs)
+          klass ||= find_by_custom_identifier(*objs)
+          klass ||= generate_event_klass(*objs)
+
+          klass
+        end
+
+        def klass_to_identifier(klass)
+          identifier = nil
+
+          identifier ||= reverse_find_by_custom_identifier(klass)
+          identifier ||= convert_klass_to_identifier(klass)
+
+          identifier
+        end
+
+        def register_custom_identifier(klass, identifier)
+          CustomIdentifiers.set identifier, klass
+        end
+
+        private
+
+        def pass_klass_through(*objs)
+          objs.length == 1 && objs[0].is_a?(Class) && objs[0] < Emittance::Event ? objs[0] : nil
+        end
+
+        def find_by_custom_identifier(*objs)
+          if objs.length == 1
+            CustomIdentifiers.event_klass_for objs[0]
+          else
+            nil
+          end
+        end
+
+        def reverse_find_by_custom_identifier(klass)
+          CustomIdentifiers.identifier_for klass
+        end
+
+        def generate_event_klass_name(*objs)
+          klass_name_parts = objs.map { |obj| klassable_name_for obj }
+          dress_up_klass_name klass_name_parts
+        end
+
+        def generate_event_klass(*objs)
+          klass_name = generate_event_klass_name(*objs)
+          find_or_create_event_klass klass_name
+        end
+
+        def convert_klass_to_identifier(klass)
+          identifier_str = klass.name
+          identifier_str = undress_klass_name identifier_str
+          identifier_str = snake_case identifier_str
+
+          identifier_str.to_sym
+        end
+
+        def klassable_name_for(obj)
+          name_str = obj.to_s
+          name_str = camel_case name_str
+          name_str = clean_up_punctuation name_str
+
+          name_str
+        end
+
+        def camel_case(str)
+          str = str.sub(/^[a-z\d]*/) { $&.capitalize }
+          str.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }
+        end
+
+        def snake_case(str)
+          str.gsub(/::/, '_')
+            .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+            .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+            .tr("-", "_")
+            .downcase
+        end
+
+        def clean_up_punctuation(str)
+          str.gsub /[^A-Za-z\d]/, ''
+        end
+
+        def dress_up_klass_name(klass_name_parts)
+          "#{Array(klass_name_parts).join}#{KLASS_NAME_SUFFIX}"
+        end
+
+        def undress_klass_name(klass_name_str)
+          klass_name_str.gsub /#{KLASS_NAME_SUFFIX}$/, ''
+        end
+
+        def lookup_event_klass(klass_name)
+          if Object.const_defined? klass_name
+            Object.const_get klass_name
+          else
+            nil
+          end
+        end
+
+        def find_or_create_event_klass(klass_name)
+          lookup_event_klass(klass_name) || create_event_klass(klass_name)
+        end
+
+        def create_event_klass(klass_name)
+          new_klass = Class.new(Emittance::Event)
+          Object.const_set klass_name, new_klass
+        end
+      end
 
-      name_str
-    end
+      class CustomIdentifiers
+        @mappings = {}
 
-    def camel_case(str)
-      str = str.sub(/^[a-z\d]*/) { $&.capitalize }
-      str.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }
-    end
+        class << self
+          def mapping_exists?(identifier)
+            !!mappings[identifier] || Emittance::Event::EventBuilder.klass_exists_for_identifier?(identifier)
+          end
 
-    def snake_case(str)
-      str.gsub(/::/, '_')
-        .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
-        .gsub(/([a-z\d])([A-Z])/,'\1_\2')
-        .tr("-", "_")
-        .downcase
-    end
+          def event_klass_for(identifier)
+            mappings[identifier]
+          end
 
-    def clean_up_punctuation(str)
-      str.gsub /[^A-Za-z\d]/, ''
-    end
+          def identifier_for(event_klass)
+            mappings.key event_klass
+          end
 
-    def dress_up_klass_name(klass_name)
-      "#{klass_name}#{KLASS_NAME_SUFFIX}"
-    end
+          def set(identifier, event_klass)
+            raise Emittance::InvalidIdentifierError, 'Event identifiers must be a Symbol.' unless identifier.is_a? Symbol
+            raise Emittance::IdentifierTakenError if mapping_exists? identifier
+            mappings[identifier] = event_klass
+          end
 
-    def undress_klass_name(klass_name_str)
-      klass_name_str.gsub /#{KLASS_NAME_SUFFIX}$/, ''
-    end
+          private
 
-    def find_or_create_event_klass(klass_name)
-      unless Object.const_defined? klass_name
-        create_event_klass klass_name
+          attr_reader :mappings
+        end
       end
-
-      Object.const_get klass_name
-    end
-
-    def create_event_klass(klass_name)
-      new_klass = Class.new(Emittance::Event)
-      Object.const_set klass_name, new_klass
     end
   end
 end

data/lib/emittance/event.rb

@@ -1,25 +1,73 @@
-class Emittance::Event
-  class << self
-    # @return [Symbol] the identifier that can be used by the {Emittance::Broker broker} to find event handlers.
-    def identifier
-      Emittance::Event::EventBuilder.klass_to_identifier self
-    end
+# frozen_string_literal: true
+
+module Emittance
+  ##
+  # Basic usage of Emittance doesn't require that you fiddle with objects of type +Emittance::Event+. However, this
+  # class is open for you to inherit from in the cases where you would like to customize some aspects of the event.
+  #
+  # To define a custom event, just inherit from +Emittance::Event+:
+  #
+  #   class FooEvent < Emittance::Event
+  #   end
+  #
+  # One common use case for this is to make sure all payloads share the same format. You can do this however you'd like.
+  # We've provided an +InvalidPayloadError+ class for that purpose. Here's one example of how that might happen:
+  #
+  #   class FooEvent < Emittance::Event
+  #     def initialize(emitter, timestamp, payload)
+  #       super
+  #       validate_payload
+  #     end
+  #
+  #     private
+  #
+  #     def validate_payload
+  #       raise Emittance::InvalidPayloadError unless payload.is_a?(String)
+  #     end
+  #   end
+  #
+  # == 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
+  #
+  # You can set a custom identifier for the event class like so:
+  #
+  #   FooEvent.add_identifier :bar
+  #
+  # Now, when emitters emit +:bar+, this will be the event received by watchers.
+  #
+  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
+      end
 
-    # @private
-    def event_klass_for(identifier)
-      Emittance::Event::EventBuilder.object_to_klass identifier
+      # 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
+      end
+
+      # @private
+      def event_klass_for(*identifiers)
+        EventBuilder.objects_to_klass *identifiers
+      end
     end
-  end
 
-  attr_reader :emitter, :timestamp, :payload
+    attr_reader :emitter, :timestamp, :payload
 
-  def initialize(emitter, timestamp, payload)
-    @emitter = emitter
-    @timestamp = timestamp
-    @payload = payload
-  end
+    def initialize(emitter, timestamp, payload)
+      @emitter = emitter
+      @timestamp = timestamp
+      @payload = payload
+    end
 
-  def identifier
-    self.class.identifier
+    def identifier
+      self.class.identifier
+    end
   end
 end

data/lib/emittance/registration.rb

@@ -1,13 +1,17 @@
-# @private
-class Emittance::Registration
-  attr_reader :identifier
+# frozen_string_literal: true
 
-  def initialize(identifier, &callback)
-    @identifier = identifier
-    @callback = callback
-  end
+module Emittance
+  # @private
+  class Registration
+    attr_reader :identifier
+
+    def initialize(identifier, &callback)
+      @identifier = identifier
+      @callback = callback
+    end
 
-  def call(event)
-    @callback.call event
+    def call(event)
+      @callback.call event
+    end
   end
 end

data/lib/emittance/version.rb

@@ -1,3 +1,5 @@
+# froze_string_literal: true
+
 module Emittance
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

data/lib/emittance/watcher.rb

@@ -1,9 +1,13 @@
-module Emittance::Watcher
-  def watch(identifier, callback_method = nil, &callback)
-    if callback_method
-      Emittance::Broker.register_method_call identifier, self, callback_method
-    else
-      Emittance::Broker.register identifier, &callback
+# frozen_string_literal: true
+
+module Emittance
+  module Watcher
+    def watch(identifier, callback_method = nil, &callback)
+      if callback_method
+        Emittance::Dispatcher.register_method_call identifier, self, callback_method
+      else
+        Emittance::Dispatcher.register identifier, &callback
+      end
     end
   end
 end

data/lib/emittance.rb

@@ -1,26 +1,41 @@
+# frozen_string_literal: true
+
 require 'emittance/version'
+require 'emittance/errors'
+
+require 'emittance/brokerage'
+require 'emittance/broker'
 require 'emittance/registration'
 require 'emittance/event'
 require 'emittance/event/event_builder'
 require 'emittance/emitter'
 require 'emittance/watcher'
 require 'emittance/action'
-require 'emittance/broker'
+require 'emittance/dispatcher'
 
+##
+# The base namespace for this library. You can do some basic configuration stuff by calling methods on its singleton.
+#
 module Emittance
   class << self
-    @enabled = true
+    # Enable eventing process-wide.
+    def enable!
+      Emittance::Dispatcher.enable!
+    end
 
-    def enabled?
-      !!@enabled
+    # Disable eventing process-wide.
+    def disable!
+      Emittance::Dispatcher.disable!
     end
 
-    def enable
-      @enabled = true
+    # @return [Boolean] true if eventing is enabled, false otherwise.
+    def enabled?
+      Emittance::Dispatcher.enabled?
     end
 
-    def disable
-      @enabled = false
+    # @private
+    def suppress(&blk)
+      Emittance::Dispatcher.suppress(&blk)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emittance
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Tyler Guillen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-30 00:00:00.000000000 Z
+date: 2017-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,27 +102,33 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".rspec_status"
+- ".rubocop.yml"
 - ".ruby-version"
+- ".travis.yml"
 - ".yardopts"
+- CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
+- LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
 - emittance.gemspec
-- lib/.DS_Store
 - lib/emittance.rb
-- lib/emittance/.DS_Store
 - lib/emittance/action.rb
 - lib/emittance/broker.rb
+- lib/emittance/brokerage.rb
+- lib/emittance/brokers/synchronous.rb
+- lib/emittance/dispatcher.rb
 - lib/emittance/emitter.rb
+- lib/emittance/errors.rb
 - lib/emittance/event.rb
 - lib/emittance/event/event_builder.rb
 - lib/emittance/registration.rb
 - lib/emittance/version.rb
 - lib/emittance/watcher.rb
+- pkg/emittance-0.0.1.gem
 homepage: https://github.com/aastronautss/emittance
 licenses:
 - MIT

data/.rspec_status

@@ -1,29 +0,0 @@
-example_id                                            | status | run_time        |
------------------------------------------------------ | ------ | --------------- |
-./spec/emittance/action_spec.rb[1:1:1]                | passed | 0.00947 seconds |
-./spec/emittance/action_spec.rb[1:1:2]                | passed | 0.0006 seconds  |
-./spec/emittance/broker_spec.rb[1:1:1]                | passed | 0.00151 seconds |
-./spec/emittance/broker_spec.rb[1:2:1]                | passed | 0.0004 seconds  |
-./spec/emittance/broker_spec.rb[1:2:2]                | passed | 0.00086 seconds |
-./spec/emittance/broker_spec.rb[1:3:1]                | passed | 0.00018 seconds |
-./spec/emittance/broker_spec.rb[1:3:2]                | passed | 0.00023 seconds |
-./spec/emittance/broker_spec.rb[1:4:1]                | passed | 0.00016 seconds |
-./spec/emittance/broker_spec.rb[1:4:2]                | passed | 0.00022 seconds |
-./spec/emittance/emitter_spec.rb[1:1:1]               | passed | 0.00038 seconds |
-./spec/emittance/emitter_spec.rb[1:1:2]               | passed | 0.00016 seconds |
-./spec/emittance/emitter_spec.rb[1:2:1]               | passed | 0.00033 seconds |
-./spec/emittance/emitter_spec.rb[1:2:2]               | passed | 0.00026 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:1] | passed | 0.00102 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:2] | passed | 0.00025 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:3] | passed | 0.00017 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:4] | passed | 0.0002 seconds  |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:5] | passed | 0.0002 seconds  |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:6] | passed | 0.00022 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:7] | passed | 0.00019 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:8] | passed | 0.00018 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:1:1:9] | passed | 0.00019 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:2:1]   | passed | 0.00018 seconds |
-./spec/emittance/event/event_builder_spec.rb[1:2:2]   | passed | 0.00016 seconds |
-./spec/emittance/watcher_spec.rb[1:1:1]               | passed | 0.0003 seconds  |
-./spec/emittance/watcher_spec.rb[1:1:2]               | passed | 0.00027 seconds |
-./spec/emittance/watcher_spec.rb[1:1:3]               | passed | 0.00039 seconds |