event_sourcery-postgres 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e45ae5ad105bd165a2fb4b59be6032488ec925df
-  data.tar.gz: c36491b6e980803520d2b3a900207500f694b500
+  metadata.gz: 54611962fa99a62b63f2a97d432614e43aa2b10e
+  data.tar.gz: d4b6413ce323e94e950fb1d3276eaebacdb6dedd
 SHA512:
-  metadata.gz: a86c88d7db9e0368d3ddbea1b6b7ce869d8f3465dd1bce3990f0038edffcb5712da10d4182fd0ce46427b2e3aa08b67b7da6712d7aec0abd16f766741a492556
-  data.tar.gz: 3f286cd47b3eb36e3b3e65929d6df0d51a1bc8762f1256d1b21c6f8041861fc8087bde5978989c7abb58d6f274add9dca368ca992105a12e5e7af6069e390dc7
+  metadata.gz: 55e76d3c6300f678ddfefe9c4dc9be6cd1fa365ace92ebce6cc6be432e2d19553cc9313da54923307fc264bb6b4582fc23022349dfc3e70df56261756a021c6d
+  data.tar.gz: 12e02831936b8fe0203ba1f0c7908a00fbff4e74308d5a879f22f0a02e311f1a2aac1b3b068df80ad81f68a4029b0b31436362a9a815d10cba32b290dfeb9f01

data/CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+
+## [0.5.0] - 2017-7-27
+- First Version of YARD documentation.
+- Fix Sequel deprecation by globally loading pg extensions
+
 ## [0.4.0] - 2017-6-21
 ### Changed
 - Reactors store the UUID of the event being processed in the `causation_id`
@@ -26,14 +31,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   added to the `events` table and the `write_events` function has been
   altered. Event Sourcery apps will need to ensure these DB changes have
   been applied to use this version of Event Sourcery.
+- The emit_events method now accepts typed events instead of symbols
+- Remove dynamic emit events methods from reactors (e.g. emit_item_added)
 
 ## [0.2.0] - 2017-6-1
 ### Changed
 - Make `EventSourcery::Postgres::OptimisedEventPollWaiter#shutdown` private
 - Updated `EventSourcery::Postgres::OptimisedEventPollWaiter#poll` to ensure that `#shutdown!` is run when an error is raised
 or when the loop stops
-- Remove dynamic emit events methods from reactors (e.g. emit_item_added)
-- The emit_events method now accepts typed events instead of symbols
 
 ### Added
 - Configure projector tracker table name via `EventSourcery::Postgres.configure`

data/README.md

@@ -91,11 +91,8 @@ To release a new version:
 
 1. Update the version number in `lib/event_sourcery/postgres/version.rb`
 2. Get this change onto master via the normal PR process
-3. Run `gem_push=false be rake release`,
-   this will create a git tag for the version,
-   push tags up to GitHub, and package the code in a `.gem` file.
-4. Manually upload the generated gem file (`pkg/event_sourcery-postgres-#{version}.gem`) to
-   [rubygems.envato.com](https://rubygems.envato.com).
+3. Run `bundle exec rake release`, this will create a git tag for the
+   version, push tags up to GitHub, and upload the gem to rubygems.org.
 
 ## Contributing
 

data/lib/event_sourcery/postgres.rb

@@ -1,6 +1,5 @@
 require 'sequel'
 
-Sequel.extension :pg_json
 Sequel.default_timezone = :utc
 
 require 'event_sourcery'

data/lib/event_sourcery/postgres/config.rb

@@ -38,10 +38,26 @@ module EventSourcery
         @event_sink ||= ::EventSourcery::EventStore::EventSink.new(event_store)
       end
 
+      def event_store_database=(sequel_connection)
+        setup_connection(sequel_connection)
+
+        @event_store_database = sequel_connection
+      end
+
       def projections_database=(sequel_connection)
+        setup_connection(sequel_connection)
+
         @projections_database = sequel_connection
         @event_tracker = Postgres::Tracker.new(sequel_connection)
       end
+
+      private
+
+      def setup_connection(sequel_connection)
+        return unless sequel_connection
+
+        sequel_connection.extension :pg_json
+      end
     end
   end
 end

data/lib/event_sourcery/postgres/event_store.rb

@@ -15,6 +15,17 @@ module EventSourcery
         @event_builder = event_builder
       end
 
+      # Like water flowing into a sink evenually it will go down the drain
+      # into the goodness of the plumbing system.
+      # So to will the given events you put in this 'sink'. Except the plumbing
+      # system is the data base events table.
+      # This can raise db connection errors.
+      #
+      # @param event_or_events the event or events to save
+      # @param expected_version the version to save with the event, default nil
+      #
+      # @raise [DatabaseError] if something goes wrong with the database
+      # @raise [ConcurrencyError] if there was a concurrency conflict
       def sink(event_or_events, expected_version: nil)
         events = Array(event_or_events)
         aggregate_ids = events.map(&:aggregate_id).uniq
@@ -31,6 +42,15 @@ module EventSourcery
         end
       end
 
+      # Get the next set of events from the given event id. You can
+      # specify event typs and a limit.
+      # Default limit is 1000 and the default event types will be all.
+      #
+      # @param id the event id to get next envents from
+      # @param event_types the event types to filter, default nil = all
+      # @param limit the limit to the results, default 1000
+      #
+      # @return [Array] array of found events
       def get_next_from(id, event_types: nil, limit: 1000)
         query = events_table.
           order(:id).
@@ -40,6 +60,11 @@ module EventSourcery
         query.map { |event_row| build_event(event_row) }
       end
 
+      # Get last event id for a given event types.
+      #
+      # @param event_types the type of event(s) to filter
+      #
+      # @return the latest event id
       def latest_event_id(event_types: nil)
         latest_event = events_table
         latest_event = latest_event.where(type: event_types) if event_types
@@ -51,12 +76,23 @@ module EventSourcery
         end
       end
 
+      # Get the events for a given aggregate id.
+      #
+      # @param aggregate_id the aggregate id to filter for
+      #
+      # @return [Array] of found events
       def get_events_for_aggregate_id(aggregate_id)
         events_table.where(aggregate_id: aggregate_id.to_str).order(:version).map do |event_hash|
           build_event(event_hash)
         end
       end
 
+      # Subscribe to events.
+      #
+      # @param from_id subscribe from a starting event id. default will be from the start.
+      # @param event_types the event_types to subscribe to, default all.
+      # @param after_listen the after listen call back block. default nil.
+      # @param subscription_master the subscription master block
       def subscribe(from_id:, event_types: nil, after_listen: nil, subscription_master:, &block)
         poll_waiter = OptimisedEventPollWaiter.new(pg_connection: @pg_connection, after_listen: after_listen)
         args = {

data/lib/event_sourcery/postgres/reactor.rb

@@ -11,18 +11,29 @@ module EventSourcery
       end
 
       module ClassMethods
+        # Assign the types of events this reactor can emit.
+        #
+        # @param event_types the types of events this reactor can emit
         def emits_events(*event_types)
           @emits_event_types = event_types
         end
 
+        # @return [Array] an array of the types of events this reactor can emit
         def emit_events
           @emits_event_types ||= []
         end
 
+        # This will tell you if this reactor emits any type of event.
+        #
+        # @return [true, false] true if this emits events, false if not
         def emits_events?
           !emit_events.empty?
         end
 
+        # Will check if this reactor emits the given type of event.
+        #
+        # @param event_type the event type to check
+        # @return [true, false] true if it does emit the given event false if not
         def emits_event?(event_type)
           emit_events.include?(event_type)
         end

data/lib/event_sourcery/postgres/schema.rb

@@ -3,6 +3,12 @@ module EventSourcery
     module Schema
       module_function
 
+      # This will create the event store tables and functions
+      # (event, aggregates, tracker and create or update functions)
+      # for the given Postgres database.
+      # The default will be the one specified in the config.
+      #
+      # @param db the Postgres database to use
       def create_event_store(db: EventSourcery::Postgres.config.event_store_database,
                              events_table_name: EventSourcery::Postgres.config.events_table_name,
                              aggregates_table_name: EventSourcery::Postgres.config.aggregates_table_name,
@@ -12,6 +18,11 @@ module EventSourcery
         create_or_update_functions(db: db, events_table_name: events_table_name, function_name: write_events_function_name, aggregates_table_name: aggregates_table_name)
       end
 
+      # Create the events table. Needs the database and the table name.
+      # The defaults will be whats specified in config.
+      #
+      # @param db the Postgres database to use
+      # @param table_name the name of the events table
       def create_events(db: EventSourcery::Postgres.config.event_store_database,
                         table_name: EventSourcery::Postgres.config.events_table_name)
         db.run 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'
@@ -34,6 +45,11 @@ module EventSourcery
         end
       end
 
+      # Create the aggregates table. Needs the database and the table name.
+      # The defaults will be whats specified in config.
+      #
+      # @param db the Postgres database to use
+      # @param table_name the name of the aggregates table
       def create_aggregates(db: EventSourcery::Postgres.config.event_store_database,
                             table_name: EventSourcery::Postgres.config.aggregates_table_name)
         db.create_table(table_name) do
@@ -42,6 +58,14 @@ module EventSourcery
         end
       end
 
+      # Create the 'create or update' fucntions.
+      # Needs the database, table name, function name and aggregates table name.
+      # The defaults will be whats specified in config.
+      #
+      # @param db the Postgres database to use
+      # @param function_name the name of the write events function
+      # @param events_table_name the name of the events table
+      # @param aggregates_table_name the name of the aggregates table
       def create_or_update_functions(db: EventSourcery::Postgres.config.event_store_database,
                                      function_name: EventSourcery::Postgres.config.write_events_function_name,
                                      events_table_name: EventSourcery::Postgres.config.events_table_name,
@@ -138,6 +162,11 @@ $$ language plpgsql;
 SQL
       end
 
+      # Create the projector tracker table. Needs the database and the table name.
+      # The defaults will be whats specified in config.
+      #
+      # @param db the Postgres database to use
+      # @param table_name the name of the aggregates table
       def create_projector_tracker(db: EventSourcery::Postgres.config.projections_database,
                                    table_name: EventSourcery::Postgres.config.tracker_table_name)
         db.create_table(table_name) do

data/lib/event_sourcery/postgres/table_owner.rb

@@ -9,15 +9,23 @@ module EventSourcery
       end
 
       module ClassMethods
+        # Hash of the tables and thier corresponding blocks.
+        #
+        # @return [Hash] hash keyed by table names and block values
         def tables
           @tables ||= {}
         end
 
+        # For the givent table name assign to give block as the value.
+        #
+        # @param name the name of the table
+        # @param block the block of code to assign for the table
         def table(name, &block)
           tables[name] = block
         end
       end
 
+      # Create each table.
       def setup
         self.class.tables.each do |table_name, schema_block|
           prefixed_name = table_name_prefixed(table_name)
@@ -26,6 +34,7 @@ module EventSourcery
         super if defined?(super)
       end
 
+      # Reset by dropping each table.
       def reset
         self.class.tables.keys.each do |table_name|
           prefixed_name = table_name_prefixed(table_name)
@@ -37,6 +46,8 @@ module EventSourcery
         setup
       end
 
+      # This will truncate all the tables and reset the tracker back to 0,
+      # done as a transaction.
       def truncate
         self.class.tables.each do |table_name, _|
           @db_connection.transaction do

data/lib/event_sourcery/postgres/tracker.rb

@@ -1,6 +1,8 @@
 module EventSourcery
   module Postgres
+    # This will set up a persisted event id tracker for processors.
     class Tracker
+
       def initialize(connection = EventSourcery::Postgres.config.projections_database,
                      table_name: EventSourcery::Postgres.config.tracker_table_name,
                      obtain_processor_lock: true)
@@ -9,6 +11,11 @@ module EventSourcery
         @obtain_processor_lock = obtain_processor_lock
       end
 
+      # Set up the given processor.
+      # This will create the projector tracker table if it does not exits.
+      # If given a processor_name it will then attempt to get a lock on the db.
+      #
+      # @param processor_name the name of the procerror
       def setup(processor_name = nil)
         create_table_if_not_exists if EventSourcery::Postgres.config.auto_create_projector_tracker
 
@@ -24,6 +31,11 @@ module EventSourcery
         end
       end
 
+      # This will updated the tracker table to the given event id value
+      # for the given processor name.
+      #
+      # @param processor_name the name of the processor to udpate
+      # @param event_id the event id number to update to
       def processed_event(processor_name, event_id)
         table.
           where(name: processor_name.to_s).
@@ -31,6 +43,12 @@ module EventSourcery
         true
       end
 
+      # This allows you to process an event and update the tracker table in
+      # a single transaction. Will yeild the given block first then update the
+      # the tracker table to the give event id for the given processor name.
+      #
+      # @param processor_name the name of the processor to update
+      # @param event_id the event id number to update to
       def processing_event(processor_name, event_id)
         @connection.transaction do
           yield
@@ -38,15 +56,25 @@ module EventSourcery
         end
       end
 
+      # This will reset the tracker to the start (0) for the given processor name.
+      #
+      # @param processor_name the name of the processor to reset to 0
       def reset_last_processed_event_id(processor_name)
         table.where(name: processor_name.to_s).update(last_processed_event_id: 0)
       end
 
+      # This will return the last processed event id for the given processor name.
+      #
+      # @param processor_name the name of the processor you want to look up
+      # @return [Int, nil] the value of the last event_id processed
       def last_processed_event_id(processor_name)
         track_entry = table.where(name: processor_name.to_s).first
         track_entry[:last_processed_event_id] if track_entry
       end
 
+      # Will return an array of all known tracked processors.
+      #
+      # @return [Array] array of all known tracked processors
       def tracked_processors
         table.select_map(:name)
       end

data/lib/event_sourcery/postgres/version.rb

@@ -1,5 +1,5 @@
 module EventSourcery
   module Postgres
-    VERSION = '0.4.0'.freeze
+    VERSION = '0.5.0'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: event_sourcery-postgres
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Envato
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-06-21 00:00:00.000000000 Z
+date: 2017-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -164,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Postgres event store for use with EventSourcery