event_stream 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4eb7f64821b9716f61474ae0fbeb45933544a449
-  data.tar.gz: 7b2dff88c4593999dffab1121a20cda3bafaaedf
+  metadata.gz: 283f487e987c22198cfa937ac6a34f1c4492ee9a
+  data.tar.gz: 5eee28a869ccf165a4960d7fe0213974e790753b
 SHA512:
-  metadata.gz: 63b1d01de337fcedd119ec1b89435bb0153c886297ef1958420cc6c395571333466781876a71360233113eee119a0ee8d63c9d7417904b492d3c98dfff822970
-  data.tar.gz: 81f0a46e4dcf4e4dca4637d8c5b0f78cfcae07ac0e0bb5b90e26de4d91a9590f606c00b25005ad1b18a364822abdf5907c7a1f52a646806c0108dbd10e911e03
+  metadata.gz: 5ca1ee9fa91b46e21e0059f14db66cc54bbba9f6fdd63b1fb4b6bfa9136c5305e3ecc0a7c6c4e4366f1ee8fc62fb25003eb609dfb6c642a2d9e46662255ebf70
+  data.tar.gz: b81ebc9b66b60125261f76b7bf67003e9e5b4d2d9bea7bc5f840611da944e12193fe278c5014bb93955ca5c3a94d98155e3b30c8133eec386ab0b3fde21c23cd

data/README.md

@@ -17,7 +17,7 @@ Then fire an event:
 EventStream.publish(:my_event, :description => "An example event.")
 ```
 
-An event is just an OpenStruct with a name and a bundle of other attributes, so the use of `:description` here is arbitrary.
+An event is just an immutable value object with a name and a bundle of other attributes, so the use of `:description` here is arbitrary.
 
 Events can be subscribed to by name, as above, but many other ways are supported:
 
@@ -49,6 +49,22 @@ stream.subscribe(...) { |e| ... }
 stream.publish(...)
 ```
 
+### The Stream Registry
+
+To allow for easy access to different streams from different call points, a registry is available for storing and
+retrieving streams. To register a stream:
+
+```ruby
+stream = EventStream::Stream.new
+EventStream.register_stream(:my_stream_name)
+```
+
+To access the stream from the registry and publish an event:
+
+```ruby
+EventStream[:my_stream_name].publish(...)
+```
+
 ### Subscriber DSL
 
 It's sometimes useful to separate the definition of a subscriber action

data/lib/event_stream.rb

@@ -1,79 +1,34 @@
 require 'ostruct'
+require_relative 'event_stream/event'
+require_relative 'event_stream/stream'
+require_relative 'event_stream/subscriber'
+require_relative 'event_stream/registry'
 require_relative 'event_stream/subscriber_dsl'
 
 module EventStream
   class << self
     extend Forwardable
 
-    # The default event stream
+    # Returns the stream for a stream name from the stream registry.
+    # @param stream_name [Symbol]
     # @return [Stream]
-    def default_stream
-      @default_stream ||= Stream.new
-    end
-
-    def_delegators :default_stream, :publish, :subscribe, :clear_subscribers
-  end
-
-  # An Event. Each event is an OpenStruct with a name as well as any number of other optional fields.
-  # @!attribute name
-  #   @return [Symbol]
-  class Event < OpenStruct; end
-
-  class Stream
-    def initialize
-      @subscribers = []
-    end
-
-    # Publishes an event to this event stream
-    # @param name [Symbol] name of this event
-    # @param attrs [Hash] optional attributes representing this event
-    def publish(name, attrs = {})
-      e = Event.new(attrs.merge(:name => name))
-      @subscribers.each { |l| l.consume(e) }
-    end
-
-    # Registers a subscriber to this event stream.
-    # @param filter [Object] Filters which events this subscriber will consume.
-    # If a string or regexp is provided, these will be matched against the event name.
-    # A hash will be matched against the attributes of the event.
-    # Or, any arbitrary predicate on events may be provided.
-    # @yield [Event] action to perform when the event occurs.
-    def subscribe(filter = nil, &action)
-      add_subscriber(Subscriber.create(filter, &action))
-    end
-
-    # Clears all subscribers from this event stream.
-    def clear_subscribers
-      @subscribers = []
+    def [](stream_name)
+      Registry.lookup(stream_name)
     end
 
-    # Returns all subscribers for this stream
-    # @return [Array<EventStream::Subscriber]
-    def subscribers
-      @subscribers
+    # Registers a stream, associating it with a specific stream name
+    # @param stream_name [Symbol]
+    # @param stream [Stream]
+    def register_stream(stream_name, stream)
+      Registry.register(stream_name, stream)
     end
 
-    # Adds a subscriber to this stream
-    # @param [EventStream::Subscriber]
-    def add_subscriber(subscriber)
-      @subscribers << subscriber
-    end
-  end
-
-  class Subscriber < Struct.new(:filter, :action)
-    def self.create(filter = nil, &action)
-      filter ||= lambda { |e| true }
-      filter_predicate = case filter
-                         when Symbol, String then lambda { |e| e.name.to_s == filter.to_s }
-                         when Regexp then lambda { |e| e.name =~ filter }
-                         when Hash then lambda { |e| filter.all? { |k,v| e[k] === v } }
-                         else filter
-                         end
-      new(filter_predicate, action)
+    # The default event stream
+    # @return [Stream]
+    def default_stream
+      self[:default]
     end
 
-    def consume(event)
-      action.call(event) if filter.call(event)
-    end
+    def_delegators :default_stream, :publish, :subscribe, :clear_subscribers
   end
 end

data/lib/event_stream/event.rb

@@ -0,0 +1,44 @@
+require 'json'
+
+module EventStream
+  # Events are immutable collections of fields with convenience methods for accessing and json serialization
+  class Event
+
+    # @param fields [Hash<Symbol, Object>] The attributes of this event
+    def initialize(fields)
+      @fields = Hash[fields.map { |k,v| [k.to_sym, v] }].freeze
+    end
+
+    # An alternate field accessor
+    # @param key [Symbol]
+    # @return [Object]
+    def [](key)
+      @fields[key.to_sym]
+    end
+
+    # @return [Hash<Symbol, Object>]
+    def to_h
+      @fields
+    end
+
+    # @return [String]
+    def to_json
+      JSON.dump(to_h)
+    end
+
+    # Parses an event object from JSON
+    # @param json_event [String] The JSON event representation, such as created by `event.to_json`
+    # @return [Event]
+    def self.from_json(json_event)
+      new(JSON.parse(json_event))
+    end
+
+    def method_missing(method_name, *args)
+      @fields.has_key?(method_name) ? @fields[method_name] : super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @fields.has_key?(method_name) || super
+    end
+  end
+end

data/lib/event_stream/registry.rb

@@ -0,0 +1,19 @@
+require 'active_support/core_ext/class/attribute'
+
+module EventStream
+  class Registry
+
+    class UnregisteredStream < StandardError; end
+
+    class_attribute :streams
+    self.streams = { default: Stream.new }
+
+    def self.register(stream_name, stream)
+      streams[stream_name] = stream
+    end
+
+    def self.lookup(stream_name)
+      streams[stream_name] || (raise UnregisteredStream)
+    end
+  end
+end

data/lib/event_stream/stream.rb

@@ -0,0 +1,45 @@
+module EventStream
+  class Stream
+    def initialize
+      @subscribers = []
+    end
+
+    # Publishes an event to this event stream
+    # @param name [Symbol] name of this event
+    # @param attrs [Hash] optional attributes representing this event
+    def publish(name_or_event, attrs = {})
+      event = case name_or_event
+              when Event then name_or_event
+              else Event.new(attrs.merge(:name => name_or_event))
+              end
+      @subscribers.each { |l| l.consume(event) }
+    end
+
+    # Registers a subscriber to this event stream.
+    # @param filter [Object] Filters which events this subscriber will consume.
+    # If a string or regexp is provided, these will be matched against the event name.
+    # A hash will be matched against the attributes of the event.
+    # Or, any arbitrary predicate on events may be provided.
+    # @yield [Event] action to perform when the event occurs.
+    def subscribe(filter = nil, &action)
+      add_subscriber(Subscriber.create(filter, &action))
+    end
+
+    # Clears all subscribers from this event stream.
+    def clear_subscribers
+      @subscribers = []
+    end
+
+    # Returns all subscribers for this stream
+    # @return [Array<EventStream::Subscriber]
+    def subscribers
+      @subscribers
+    end
+
+    # Adds a subscriber to this stream
+    # @param [EventStream::Subscriber]
+    def add_subscriber(subscriber)
+      @subscribers << subscriber
+    end
+  end
+end

data/lib/event_stream/subscriber.rb

@@ -0,0 +1,18 @@
+module EventStream
+  class Subscriber < Struct.new(:filter, :action)
+    def self.create(filter = nil, &action)
+      filter ||= lambda { |e| true }
+      filter_predicate = case filter
+                         when Symbol, String then lambda { |e| e.name.to_s == filter.to_s }
+                         when Regexp then lambda { |e| e.name =~ filter }
+                         when Hash then lambda { |e| filter.all? { |k,v| e[k] === v } }
+                         else filter
+                         end
+      new(filter_predicate, action)
+    end
+
+    def consume(event)
+      action.call(event) if filter.call(event)
+    end
+  end
+end

data/lib/event_stream/version.rb

@@ -1,3 +1,3 @@
 module EventStream
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

data/test/event_stream/event_stream_test.rb

@@ -2,12 +2,12 @@ require_relative '../test_helper'
 
 class EventStreamTest < Minitest::Should::TestCase
 
-  def pub_sub(name, attrs = {}, filter = nil)
+  def pub_sub(name_or_event, attrs = {}, filter = nil)
     event = nil
     EventStream.subscribe(filter) do |e|
       event = e
     end
-    EventStream.publish(name, attrs)
+    EventStream.publish(name_or_event, attrs)
     event
   end
 
@@ -22,6 +22,12 @@ class EventStreamTest < Minitest::Should::TestCase
       assert_equal :test, event.name
     end
 
+    should 'allow publishing of pre-constructed events' do
+      event = EventStream::Event.new(name: 'test', a: 1)
+      subscribed = pub_sub(event)
+      assert_equal event, subscribed
+    end
+
     should 'expose all event attributes to the subscriber' do
       event = pub_sub(:test, :x => 1)
       assert_equal 1, event.x
@@ -51,4 +57,32 @@ class EventStreamTest < Minitest::Should::TestCase
 
     end
   end
+
+  context 'managing multiple event streams' do
+    setup do
+      @stream = EventStream::Stream.new
+      EventStream.register_stream(:test_stream, @stream)
+    end
+
+    should 'allow streams to be registered and retrieved' do
+      assert_equal @stream, EventStream[:test_stream]
+    end
+
+    should 'allow separate publishes and subscriptions to different streams' do
+      test_event = nil
+
+      EventStream[:test_stream].subscribe(//) do |e|
+        test_event = e
+      end
+
+      EventStream[:test_stream].publish(:test_event)
+      assert test_event, "Event was expected to be published to the test stream"
+      assert_equal test_event.name, :test_event
+
+      test_event = nil
+
+      EventStream.publish(:test_event)
+      refute test_event, "No event should have been published to the test stream"
+    end
+  end
 end

data/test/event_stream/event_test.rb

@@ -0,0 +1,49 @@
+require_relative '../test_helper'
+
+module EventStream
+  class EventTest < Minitest::Should::TestCase
+
+    context 'an event' do
+
+      context 'creating and accessing values' do
+        should 'exposed values passed in as a hash' do
+          event = Event.new(a: 1, b: 2)
+          assert_equal 1, event.a
+          assert_equal 2, event.b
+        end
+
+        should 'expose values passed in as string keys' do
+          event = Event.new('a' => 1, b: 2)
+          assert_equal 1, event.a
+        end
+
+        should 'properly respond to existing (but not nonexisting) values' do
+          event = Event.new('a' => 1, b: 2)
+          assert event.respond_to?(:a)
+          assert event.respond_to?(:b)
+          refute event.respond_to?(:c)
+        end
+      end
+
+      context '#to_json' do
+        should 'serialize to json' do
+          event = Event.new(a: 1, b: 2)
+          assert_equal '{"a":1,"b":2}', event.to_json
+        end
+      end
+
+      context '#from_json' do
+        should 'deserialize from json' do
+          json = '{"a":1,"b":2}'
+          event = Event.from_json(json)
+          assert_equal 1, event.a
+          assert_equal 2, event.b
+        end
+
+        should 'raise an error if json is not valid' do
+          assert_raises(JSON::ParserError) { Event.from_json('not valid') }
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_stream
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Arron Norwell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-15 00:00:00.000000000 Z
+date: 2016-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,10 +94,15 @@ files:
 - Rakefile
 - event_stream.gemspec
 - lib/event_stream.rb
+- lib/event_stream/event.rb
+- lib/event_stream/registry.rb
+- lib/event_stream/stream.rb
+- lib/event_stream/subscriber.rb
 - lib/event_stream/subscriber_dsl.rb
 - lib/event_stream/test_helper.rb
 - lib/event_stream/version.rb
 - test/event_stream/event_stream_test.rb
+- test/event_stream/event_test.rb
 - test/event_stream/subscriber_dsl_test.rb
 - test/event_stream/test_helper_test.rb
 - test/test_helper.rb
@@ -127,7 +132,7 @@ specification_version: 4
 summary: A minimal library for synchronously publishing and subscribing to events.
 test_files:
 - test/event_stream/event_stream_test.rb
+- test/event_stream/event_test.rb
 - test/event_stream/subscriber_dsl_test.rb
 - test/event_stream/test_helper_test.rb
 - test/test_helper.rb
-has_rdoc: