pg_eventstore 0.4.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256d7be42cb993955eb3c387b27fa63bf9992852da2375c785f181b873fe7568
-  data.tar.gz: 4101d8f0706f402a8e97bce4864c2ab2c61a587845e1051826d7d26417c199bd
+  metadata.gz: 6af4900fd9dc0524bcc7abcf7becd913c33fc50e1f0cb097c124ab48ee9cf3cd
+  data.tar.gz: c5626c8b58e6265b7deed496b6531881ea352049cbaea6f29b2281abd7a7d5b9
 SHA512:
-  metadata.gz: 548512c6c8ec7161380848b1975313222173dd41db13d45c0216948bf769eb513d8593dc0e22263c4cc59c9210a7c90fab21f7a64b26a38217253422457582b4
-  data.tar.gz: 777aecbd9e7ad84882fbf0c20847fc79e8495addac77a5887db3dface85b7dec7aa3679e91849272109f6f6745cdbfd143628d8dc53d78b73559ba9fad31722f
+  metadata.gz: 6c4c6425faea1168e3396b14c7cd66fb3c7f10097d2e2645ebf7dba6ba2b9800ddb6372bac3f6c8d39baf4c78a46bbfc907b352274b3839ef5eeb7acd8dbec02
+  data.tar.gz: '09a4f239984bffc88abaa5e08aa4c4fa31df1856aebcb4c8b5fcd6bdd5e77806d556584680cdc5702cfd5f720bc5f91ecf19bdc98bdf15c4a16f3024e5df0151'

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [Unreleased]
+
+## [0.5.2] - 2024-02-06
+
+- Improve speed of `PgEventstore::Stream#eql?` a bit
+
+## [0.5.1] - 2024-02-06
+
+- Fix `PgEventstore::Stream` to be properly recognizable inside Hash
+
+## [0.5.0] - 2024-02-05
+
+- Fix event class resolving when providing `resolve_link_tos: true` option
+- Return correct stream revision of the `Event#stream` object of the appended event
+- Implement events linking feature
+- Implement paginated read
+- Remove duplicated `idx_events_event_type_id` index
+
 ## [0.4.0] - 2024-01-29
 
 - Implement asynchronous subscriptions. Refer to the documentation for more info

data/CODE_OF_CONDUCT.md

@@ -39,7 +39,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at intale.a@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at ivan.dzyzenko@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

data/README.md

@@ -52,6 +52,7 @@ Documentation chapters:
 - [Configuration](docs/configuration.md)
 - [Events and streams definitions](docs/events_and_streams.md)
 - [Appending events](docs/appending_events.md)
+- [Linking events](docs/linking_events.md)
 - [Reading events](docs/reading_events.md)
 - [Subscriptions](docs/subscriptions.md)
 - [Writing middlewares](docs/writing_middleware.md)

data/db/migrations/13_remove_duplicated_index.sql

@@ -0,0 +1 @@
+DROP INDEX idx_events_event_type_id;

data/docs/linking_events.md

@@ -0,0 +1,96 @@
+# Linking Events
+
+## Linking single event
+
+You can create a link to an existing event. Next example demonstrates how you can link an existing event from another stream:
+
+```ruby
+class SomethingHappened < PgEventstore::Event
+end
+
+event = SomethingHappened.new(
+  type: 'some-event', data: { title: 'Something happened' }
+)
+
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+# Persist our event
+event = PgEventstore.client.append_to_stream(events_stream, event)
+
+# Link event into your projection
+PgEventstore.client.link_to(projection_stream, event)
+```
+
+The linked event can later be fetched by providing the `:resolve_link_tos` option when reading from the stream:
+
+```ruby
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+PgEventstore.client.read(projection_stream, options: { resolve_link_tos: true })
+```
+
+If you don't provide the `:resolve_link_tos` option, the linked event will be returned instead of the original one.
+
+## Linking multiple events
+
+You can provide an array of events to link to the target stream:
+
+```ruby
+class SomethingHappened < PgEventstore::Event
+end
+
+events = 3.times.map { |i| SomethingHappened.new(type: 'some-event', data: { title: "Something happened-#{i}" }) }
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+events = PgEventstore.client.append_to_stream(events_stream, events)
+# Link events
+PgEventstore.client.link_to(projection_stream, events)
+```
+
+## Handling concurrency
+
+Linking concurrency is implemented the same way as appending concurrency. You can check [**Handling concurrency**](appending_events.md#handling-concurrency) chapter of **Appending Events** section.
+
+Example:
+
+```ruby
+require 'securerandom'
+class SomethingHappened < PgEventstore::Event
+end
+
+event1 = SomethingHappened.new
+event2 = SomethingHappened.new
+
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: SecureRandom.uuid)
+
+event1, event2 = PgEventstore.client.append_to_stream(events_stream, [event1, event2])
+
+# Links first event
+PgEventstore.client.link_to(projection_stream, event1, options: { expected_revision: :no_stream })
+# Raises PgEventstore::WrongExpectedVersionError error because stream already exists
+PgEventstore.client.link_to(projection_stream, event2, options: { expected_revision: :no_stream })
+```
+
+## Middlewares
+
+If you would like to modify your link events before they get persisted - you should use the `:middlewares` argument which allows you to pass the list of middlewares you would like to use. **By default no middlewares will be applied to the link event despite on `config.middlewares` option**.
+
+Let's say you have these registered middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  config.middlewares = { foo: FooMiddleware.new, bar: BarMiddleware.new, baz: BazMiddleware.new }
+end
+```
+
+And you want to use `FooMiddleware` and `BazMiddleware`. You simply have to provide an array of corresponding middleware keys you would like to use:
+
+```ruby
+events_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+projection_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeProjection', stream_id: '1')
+
+event = PgEventstore.client.append_to_stream(events_stream, PgEventstore::Event.new)
+PgEventstore.client.link_to(projection_stream, event, middlewares: %i[foo baz])
+```
+
+See [Writing middleware](writing_middleware.md) chapter for info about what is middleware and how to implement it.

data/docs/reading_events.md

@@ -159,3 +159,59 @@ You can also mix filtering by stream's attributes and event types. The result wi
 ```ruby
 PgEventstore.client.read(PgEventstore::Stream.all_stream, options: { filter: { streams: [{ context: 'MyAwesomeContext' }], event_types: %w[Foo Bar] } })
 ```
+
+
+## Pagination
+
+You can use `#read_paginated` to iterate over all (filtered) events. It yields each batch of records that was found according to the filter options:
+
+```ruby
+# Read from the specific stream
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'User', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.read_paginated(stream).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Read from "all" stream
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+```
+
+Options are the same as for `#read` method. Several examples:
+
+```ruby
+# Read "Foo" events only from the specific stream
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'User', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.read_paginated(stream, options: { filter: { event_types: ['Foo'] } }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Backwards read from "all" stream
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream, options: { direction: 'Backwards' }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Set batch size to 100
+PgEventstore.client.read_paginated(PgEventstore::Stream.all_stream, options: { max_count: 100 }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+
+# Reading from projection stream
+projection_stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'MyAwesomeProjection', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae') 
+PgEventstore.client.read_paginated(projection_stream, options: { resolve_link_tos: true }).each do |events|
+  events.each do |event|
+    # iterate through events
+  end
+end
+```

data/lib/pg_eventstore/client.rb

@@ -109,6 +109,36 @@ module PgEventstore
         call(stream, options: { max_count: config.max_count }.merge(options))
     end
 
+    # @see {#read} for available params
+    # @return [Enumerator] enumerator will yield PgEventstore::Event
+    def read_paginated(stream, options: {}, middlewares: nil)
+      cmd_class = stream.system? ? Commands::SystemStreamReadPaginated : Commands::RegularStreamReadPaginated
+      cmd_class.
+        new(Queries.new(streams: stream_queries, events: event_queries(middlewares(middlewares)))).
+        call(stream, options: { max_count: config.max_count }.merge(options))
+    end
+
+    # Links event from one stream into another stream. You can later access it by providing :resolve_link_tos option
+    # when reading from a stream. Only existing events can be linked.
+    # @param stream [PgEventstore::Stream]
+    # @param events_or_event [PgEventstore::Event, Array<PgEventstore::Event>]
+    # @param options [Hash]
+    # @option options [Integer] :expected_revision provide your own revision number
+    # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+    # @param middlewares [Array] provide a list of middleware names to use. Defaults to empty array, meaning no
+    #   middlewares will be applied to the "link" event
+    # @return [PgEventstore::Event, Array<PgEventstore::Event>] persisted event(s)
+    # @raise [PgEventstore::WrongExpectedRevisionError]
+    def link_to(stream, events_or_event, options: {}, middlewares: [])
+      result =
+        Commands::LinkTo.new(
+          Queries.new(
+            streams: stream_queries, events: event_queries(middlewares(middlewares)), transactions: transaction_queries
+          )
+        ).call(stream, *events_or_event, options: options)
+      events_or_event.is_a?(Array) ? result : result.first
+    end
+
     private
 
     # @param middlewares [Array, nil]

data/lib/pg_eventstore/commands/append.rb

@@ -9,9 +9,10 @@ module PgEventstore
       # @param options [Hash]
       # @option options [Integer] :expected_revision provide your own revision number
       # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+      # @param event_modifier [#call]
       # @return [Array<PgEventstore::Event>] persisted events
       # @raise [PgEventstore::WrongExpectedRevisionError]
-      def call(stream, *events, options: {})
+      def call(stream, *events, options: {}, event_modifier: EventModifiers::PrepareRegularEvent)
         raise SystemStreamError, stream if stream.system?
 
         queries.transactions.transaction do
@@ -19,7 +20,7 @@ module PgEventstore
           revision = stream.stream_revision
           assert_expected_revision!(revision, options[:expected_revision]) if options[:expected_revision]
           events.map.with_index(1) do |event, index|
-            queries.events.insert(stream, prepared_event(event, revision + index))
+            queries.events.insert(stream, event_modifier.call(event, revision + index))
           end.tap do
             queries.streams.update_stream_revision(stream, revision + events.size)
           end
@@ -28,15 +29,6 @@ module PgEventstore
 
       private
 
-      # @param event [PgEventstore::Event]
-      # @param revision [Integer]
-      # @return [PgEventstore::Event]
-      def prepared_event(event, revision)
-        event.class.new(
-          id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
-        )
-      end
-
       # @param revision [Integer]
       # @param expected_revision [Symbol, Integer]
       # @raise [PgEventstore::WrongExpectedRevisionError] in case if revision does not satisfy expected revision

data/lib/pg_eventstore/commands/event_modifiers/prepare_link_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    module EventModifiers
+      # Defines how to transform regular event into a link event
+      # @!visibility private
+      class PrepareLinkEvent
+        class << self
+          # @param event [PgEventstore::Event]
+          # @param revision [Integer]
+          # @return [PgEventstore::Event]
+          def call(event, revision)
+            Event.new(link_id: event.id, type: Event::LINK_TYPE, stream_revision: revision).tap do |e|
+              %i[link_id type stream_revision].each { |attr| e.readonly!(attr) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/event_modifiers/prepare_regular_event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    module EventModifiers
+      # Defines how to transform regular event before appending it to the stream
+      # @!visibility private
+      class PrepareRegularEvent
+        class << self
+          # @param event [PgEventstore::Event]
+          # @param revision [Integer]
+          # @return [PgEventstore::Event]
+          def call(event, revision)
+            event.class.new(
+              id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
+            ).tap do |e|
+              %i[link_id stream_revision].each { |attr| e.readonly!(attr) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/link_to.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class LinkTo < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param events [Array<PgEventstore::Event>]
+      # @param options [Hash]
+      # @option options [Integer] :expected_revision provide your own revision number
+      # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+      # @return [Array<PgEventstore::Event>] persisted events
+      # @raise [PgEventstore::WrongExpectedRevisionError]
+      # @raise [PgEventstore::NotPersistedEventError]
+      def call(stream, *events, options: {})
+        events.each(&method(:check_id_presence))
+        append_cmd = Append.new(queries)
+        append_cmd.call(stream, *events, options: options, event_modifier: EventModifiers::PrepareLinkEvent)
+      end
+
+      private
+
+      # Checks if Event#id is present. An event must have the #id value in order to be linked.
+      # @param event [PgEventstore::Event]
+      # @return [void]
+      def check_id_presence(event)
+        return unless event.id.nil?
+
+        raise NotPersistedEventError, event
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/regular_stream_read_paginated.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class RegularStreamReadPaginated < AbstractCommand
+      # @see PgEventstore::Commands::Read for docs
+      def call(stream, options: {})
+        revision = calc_initial_revision(stream, options)
+        Enumerator.new do |yielder|
+          loop do
+            events = read_cmd.call(stream, options: options.merge(from_revision: revision))
+            yielder << events if events.any?
+            raise StopIteration if end_reached?(events, options[:max_count])
+
+            revision = calc_next_revision(events, revision, options[:direction])
+            raise StopIteration if revision.negative?
+          end
+        end
+      end
+
+      private
+
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash]
+      # @return [Integer]
+      def calc_initial_revision(stream, options)
+        return options[:from_revision] if options[:from_revision]
+        return 0 if forwards?(options[:direction])
+
+        read_cmd.call(stream, options: options.merge(max_count: 1)).first.stream_revision
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param max_count [Integer]
+      # @return [Boolean]
+      def end_reached?(events, max_count)
+        events.size < max_count
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param revision [Integer]
+      # @param direction [String, Symbol, nil]
+      # @return [Integer]
+      def calc_next_revision(events, revision, direction)
+        return revision + events.size if forwards?(direction)
+
+        revision - events.size
+      end
+
+      # @param direction [String, Symbol, nil]
+      # @return [Boolean]
+      def forwards?(direction)
+        QueryBuilders::EventsFiltering::SQL_DIRECTIONS[direction] == QueryBuilders::EventsFiltering::SQL_DIRECTIONS[:asc]
+      end
+
+      # @return [PgEventstore::Commands::Read]
+      def read_cmd
+        @read_cmd ||= Read.new(queries)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/system_stream_read_paginated.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class SystemStreamReadPaginated < AbstractCommand
+      # @see PgEventstore::Commands::Read for docs
+      def call(stream, options: {})
+        position = calc_initial_position(stream, options)
+        Enumerator.new do |yielder|
+          loop do
+            events = read_cmd.call(stream, options: options.merge(from_position: position))
+            yielder << events if events.any?
+            raise StopIteration if end_reached?(events, options[:max_count])
+
+            position = calc_next_position(events, options[:direction])
+            raise StopIteration if position <= 0
+          end
+        end
+      end
+
+      private
+
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash]
+      # @return [Integer]
+      def calc_initial_position(stream, options)
+        return options[:from_position] if options[:from_position]
+        return 1 if forwards?(options[:direction])
+
+        read_cmd.call(stream, options: options.merge(max_count: 1)).first.global_position
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param max_count [Integer]
+      # @return [Boolean]
+      def end_reached?(events, max_count)
+        events.size < max_count
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param direction [String, Symbol, nil]
+      # @return [Integer]
+      def calc_next_position(events, direction)
+        return events.last.global_position + 1 if forwards?(direction)
+
+        events.last.global_position - 1
+      end
+
+      # @param direction [String, Symbol, nil]
+      # @return [Boolean]
+      def forwards?(direction)
+        QueryBuilders::EventsFiltering::SQL_DIRECTIONS[direction] == QueryBuilders::EventsFiltering::SQL_DIRECTIONS[:asc]
+      end
+
+      # @return [PgEventstore::Commands::Read]
+      def read_cmd
+        @read_cmd ||= Read.new(queries)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'abstract_command'
+require_relative 'commands/event_modifiers/prepare_link_event'
+require_relative 'commands/event_modifiers/prepare_regular_event'
 require_relative 'commands/append'
 require_relative 'commands/read'
+require_relative 'commands/regular_stream_read_paginated'
+require_relative 'commands/system_stream_read_paginated'
 require_relative 'commands/multiple'
+require_relative 'commands/link_to'

data/lib/pg_eventstore/errors.rb

@@ -137,8 +137,8 @@ module PgEventstore
 
     # @return [String]
     def user_friendly_message
-      <<~TEXT
-        Could not lock Subscription from #{set.inspect} set with #{name.inspect} name. It is already locked by \
+      <<~TEXT.strip
+        Could not lock subscription from #{set.inspect} set with #{name.inspect} name. It is already locked by \
         #{lock_id.inspect} set.
       TEXT
     end
@@ -161,10 +161,27 @@ module PgEventstore
 
     # @return [String]
     def user_friendly_message
-      <<~TEXT
-        Failed to unlock Subscription from #{set.inspect} set with #{name.inspect} name by \
+      <<~TEXT.strip
+        Failed to unlock subscription from #{set.inspect} set with #{name.inspect} name by \
         #{expected_locked_by.inspect} lock id. It is currently locked by #{actual_locked_by.inspect} lock id.
       TEXT
     end
   end
+
+  class NotPersistedEventError < Error
+    attr_reader :event
+
+    # @param event [PgEventstore::Event]
+    def initialize(event)
+      @event = event
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT.strip
+        Event#id must be present, got #{event.id.inspect} instead.
+      TEXT
+    end
+  end
 end

data/lib/pg_eventstore/event_deserializer.rb

@@ -12,18 +12,9 @@ module PgEventstore
       @event_class_resolver = event_class_resolver
     end
 
-    # @param pg_result [PG::Result]
-    # @return [Array<PgEventstore::Event>]
-    def deserialize_pg_result(pg_result)
-      pg_result.map(&method(:deserialize))
-    end
-
-    # @param pg_result [PG::Result]
-    # @return [PgEventstore::Event, nil]
-    def deserialize_one_pg_result(pg_result)
-      return if pg_result.ntuples.zero?
-
-      deserialize(pg_result.first)
+    # @param raw_events [Array<Hash>]
+    def deserialize_many(raw_events)
+      raw_events.map(&method(:deserialize))
     end
 
     # @param attrs [Hash]

data/lib/pg_eventstore/extensions/options_extension.rb

@@ -50,7 +50,11 @@ module PgEventstore
           self.options = (options + Set.new([opt_name])).freeze
           warn_already_defined(opt_name)
           warn_already_defined(:"#{opt_name}=")
-          attr_writer opt_name
+          define_method "#{opt_name}=" do |value|
+            readonly_error(opt_name) if readonly?(opt_name)
+
+            instance_variable_set(:"@#{opt_name}", value)
+          end
 
           define_method opt_name do
             result = instance_variable_get(:"@#{opt_name}")
@@ -77,6 +81,8 @@ module PgEventstore
         end
       end
 
+      ReadonlyAttributeError = Class.new(StandardError)
+
       def self.included(klass)
         klass.singleton_class.attr_accessor(:options)
         klass.options = Set.new.freeze
@@ -84,11 +90,8 @@ module PgEventstore
       end
 
       def initialize(**options)
-        self.class.options.each do |option|
-          # init default values of options
-          value = options.key?(option) ? options[option] : public_send(option)
-          public_send("#{option}=", value)
-        end
+        @readonly = Set.new
+        init_default_values(options)
       end
 
       # Construct a hash from options, where key is the option's name and the value is option's
@@ -100,6 +103,41 @@ module PgEventstore
         end
       end
       alias attributes_hash options_hash
+
+      # @param opt_name [Symbol]
+      # @return [Boolean]
+      def readonly!(opt_name)
+        return false unless self.class.options.include?(opt_name)
+
+        @readonly.add(opt_name)
+        true
+      end
+
+      # @param opt_name [Symbol]
+      # @return [Boolean]
+      def readonly?(opt_name)
+        @readonly.include?(opt_name)
+      end
+
+      private
+
+      # @param opt_name [Symbol]
+      # @raise [PgEventstore::Extensions::OptionsExtension::ReadOnlyError]
+      def readonly_error(opt_name)
+        raise(
+          ReadonlyAttributeError, "#{opt_name.inspect} attribute was marked as read only. You can no longer modify it."
+        )
+      end
+
+      # @param options [Hash]
+      # @return [void]
+      def init_default_values(options)
+        self.class.options.each do |option|
+          # init default values of options
+          value = options.key?(option) ? options[option] : public_send(option)
+          public_send("#{option}=", value)
+        end
+      end
     end
   end
 end

data/lib/pg_eventstore/pg_connection.rb

@@ -19,11 +19,28 @@ module PgEventstore
 
       sql = sql.gsub(/\$\d+/).each do |matched|
         value = params[matched[1..].to_i - 1]
-
-        value = type_map_for_queries[value.class]&.encode(value) || value
-        value.is_a?(String) ? "'#{value}'" : value
+        value = encode_value(value)
+        normalize_value(value)
       end unless params&.empty?
       PgEventstore.logger.debug(sql)
     end
+
+    def encode_value(value)
+      encoder = type_map_for_queries[value.class]
+      return type_map_for_queries.send(encoder, value).encode(value) if encoder.is_a?(Symbol)
+
+      type_map_for_queries[value.class]&.encode(value) || value
+    end
+
+    def normalize_value(value)
+      case value
+      when String
+        "'#{value}'"
+      when NilClass
+        'NULL'
+      else
+        value
+      end
+    end
   end
 end

data/lib/pg_eventstore/queries/event_queries.rb

@@ -22,10 +22,11 @@ module PgEventstore
     def stream_events(stream, options)
       options = event_type_queries.include_event_types_ids(options)
       exec_params = events_filtering(stream, options).to_exec_params
-      pg_result = connection.with do |conn|
+      raw_events = connection.with do |conn|
         conn.exec_params(*exec_params)
-      end
-      deserializer.deserialize_pg_result(pg_result)
+      end.to_a
+      preloader.preload_related_objects(raw_events)
+      deserializer.deserialize_many(raw_events)
     end
 
     # @param stream [PgEventstore::Stream] persisted stream
@@ -44,10 +45,10 @@ module PgEventstore
           RETURNING *, $#{attributes.values.size + 1} as type
       SQL
 
-      pg_result = connection.with do |conn|
+      raw_event = connection.with do |conn|
         conn.exec_params(sql, [*attributes.values, event.type])
-      end
-      deserializer.without_middlewares.deserialize_one_pg_result(pg_result).tap do |persisted_event|
+      end.to_a.first
+      deserializer.without_middlewares.deserialize(raw_event).tap do |persisted_event|
         persisted_event.stream = stream
       end
     end
@@ -56,17 +57,21 @@ module PgEventstore
 
     # @param stream [PgEventstore::Stream]
     # @param options [Hash]
-    # @param offset [Integer]
     # @return [PgEventstore::EventsFilteringQuery]
-    def events_filtering(stream, options, offset: 0)
-      return QueryBuilders::EventsFiltering.all_stream_filtering(options, offset: offset) if stream.all_stream?
+    def events_filtering(stream, options)
+      return QueryBuilders::EventsFiltering.all_stream_filtering(options) if stream.all_stream?
 
-      QueryBuilders::EventsFiltering.specific_stream_filtering(stream, options, offset: offset)
+      QueryBuilders::EventsFiltering.specific_stream_filtering(stream, options)
     end
 
     # @return [PgEventstore::EventTypeQueries]
     def event_type_queries
       EventTypeQueries.new(connection)
     end
+
+    # @return [PgEventstore::Preloader]
+    def preloader
+      Preloader.new(connection)
+    end
   end
 end

data/lib/pg_eventstore/queries/event_type_queries.rb

@@ -33,6 +33,17 @@ module PgEventstore
       end.to_a.dig(0, 'id')
     end
 
+    # @param ids [Array<Integer>]
+    # @return [Array<Hash>]
+    def find_by_ids(ids)
+      return [] if ids.empty?
+
+      builder = SQLBuilder.new.from('event_types').where('id = ANY(?)', ids.uniq)
+      connection.with do |conn|
+        conn.exec_params(*builder.to_exec_params)
+      end.to_a
+    end
+
     # @param types [Array<String>]
     # @return [Array<Integer, nil>]
     def find_event_types(types)

data/lib/pg_eventstore/queries/preloader.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # @!visibility private
+  class Preloader
+    attr_reader :connection
+    private :connection
+
+    # @param connection [PgEventstore::Connection]
+    def initialize(connection)
+      @connection = connection
+    end
+
+    # @param raw_events [Array<Hash>]
+    # @return [Array<Hash>]
+    def preload_related_objects(raw_events)
+      streams = stream_queries.find_by_ids(raw_events.map { _1['stream_id'] }).to_h { [_1['id'], _1] }
+      types = event_type_queries.find_by_ids(raw_events.map { _1['event_type_id'] }).to_h { [_1['id'], _1] }
+      raw_events.each do |event|
+        event['stream'] = streams[event['stream_id']]
+        event['type'] = types[event['event_type_id']]['type']
+      end
+    end
+
+    private
+
+    # @return [PgEventstore::EventTypeQueries]
+    def event_type_queries
+      EventTypeQueries.new(connection)
+    end
+
+    # @return [PgEventstore::StreamQueries]
+    def stream_queries
+      StreamQueries.new(connection)
+    end
+  end
+end

data/lib/pg_eventstore/queries/stream_queries.rb

@@ -26,6 +26,17 @@ module PgEventstore
       deserialize(pg_result) if pg_result.ntuples == 1
     end
 
+    # @param ids [Array<Integer>]
+    # @return [Array<Hash>]
+    def find_by_ids(ids)
+      return [] if ids.empty?
+
+      builder = SQLBuilder.new.from('streams').where('id = ANY(?)', ids.uniq.sort)
+      connection.with do |conn|
+        conn.exec_params(*builder.to_exec_params)
+      end.to_a
+    end
+
     # @param stream [PgEventstore::Stream]
     # @return [PgEventstore::RawStream] persisted stream
     def create_stream(stream)
@@ -44,13 +55,15 @@ module PgEventstore
     end
 
     # @param stream [PgEventstore::Stream] persisted stream
-    # @return [void]
+    # @return [PgEventstore::Stream]
     def update_stream_revision(stream, revision)
       connection.with do |conn|
         conn.exec_params(<<~SQL, [revision, stream.id])
           UPDATE streams SET stream_revision = $1 WHERE id = $2
         SQL
       end
+      stream.stream_revision = revision
+      stream
     end
 
     private

data/lib/pg_eventstore/queries/subscription_queries.rb

@@ -79,9 +79,10 @@ module PgEventstore
       return [] if query_options.empty?
 
       final_builder = union_builders(query_options.map { |id, opts| query_builder(id, opts) })
-      connection.with do |conn|
+      raw_events = connection.with do |conn|
         conn.exec_params(*final_builder.to_exec_params)
       end.to_a
+      preloader.preload_related_objects(raw_events)
     end
 
     # @param id [Integer] subscription's id
@@ -151,6 +152,11 @@ module PgEventstore
       EventTypeQueries.new(connection)
     end
 
+    # @return [PgEventstore::Preloader]
+    def preloader
+      Preloader.new(connection)
+    end
+
     # @param hash [Hash]
     # @return [Hash]
     def deserialize(hash)

data/lib/pg_eventstore/queries.rb

@@ -10,6 +10,7 @@ require_relative 'queries/subscription_queries'
 require_relative 'queries/subscriptions_set_queries'
 require_relative 'queries/subscription_command_queries'
 require_relative 'queries/subscriptions_set_command_queries'
+require_relative 'queries/preloader'
 
 module PgEventstore
   # @!visibility private

data/lib/pg_eventstore/query_builders/events_filtering_query.rb

@@ -4,7 +4,6 @@ module PgEventstore
   module QueryBuilders
     # @!visibility private
     class EventsFiltering
-      DEFAULT_OFFSET = 0
       DEFAULT_LIMIT = 1_000
       SQL_DIRECTIONS = {
         'asc' => 'ASC',
@@ -26,14 +25,12 @@ module PgEventstore
         end
 
         # @param options [Hash]
-        # @param offset [Integer]
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
-        def all_stream_filtering(options, offset: 0)
+        def all_stream_filtering(options)
           event_filter = new
           options in { filter: { event_type_ids: Array => event_type_ids } }
           event_filter.add_event_types(event_type_ids)
           event_filter.add_limit(options[:max_count])
-          event_filter.add_offset(offset)
           event_filter.resolve_links(options[:resolve_link_tos])
           options in { filter: { streams: Array => streams } }
           streams&.each { |attrs| event_filter.add_stream_attrs(**attrs) }
@@ -44,14 +41,12 @@ module PgEventstore
 
         # @param stream [PgEventstore::Stream]
         # @param options [Hash]
-        # @param offset [Integer]
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
-        def specific_stream_filtering(stream, options, offset: 0)
+        def specific_stream_filtering(stream, options)
           event_filter = new
           options in { filter: { event_type_ids: Array => event_type_ids } }
           event_filter.add_event_types(event_type_ids)
           event_filter.add_limit(options[:max_count])
-          event_filter.add_offset(offset)
           event_filter.resolve_links(options[:resolve_link_tos])
           event_filter.add_stream(stream)
           event_filter.add_revision(options[:from_revision], options[:direction])
@@ -64,13 +59,10 @@ module PgEventstore
         @sql_builder =
           SQLBuilder.new.
             select('events.*').
-            select('row_to_json(streams.*) as stream').
-            select('event_types.type as type').
             from('events').
             join('JOIN streams ON streams.id = events.stream_id').
             join('JOIN event_types ON event_types.id = events.event_type_id').
-            limit(DEFAULT_LIMIT).
-            offset(DEFAULT_OFFSET)
+            limit(DEFAULT_LIMIT)
       end
 
       # @param context [String, nil]
@@ -144,14 +136,6 @@ module PgEventstore
         @sql_builder.limit(limit)
       end
 
-      # @param offset [Integer, nil]
-      # @return [void]
-      def add_offset(offset)
-        return unless offset
-
-        @sql_builder.offset(offset)
-      end
-
       # @param should_resolve [Boolean]
       # @return [void]
       def resolve_links(should_resolve)
@@ -160,7 +144,6 @@ module PgEventstore
         @sql_builder.
           unselect.
           select("(COALESCE(original_events.*, events.*)).*").
-          select('row_to_json(streams.*) as stream').
           join("LEFT JOIN events original_events ON original_events.id = events.link_id")
       end
 

data/lib/pg_eventstore/stream.rb

@@ -18,7 +18,8 @@ module PgEventstore
       end
     end
 
-    attr_reader :context, :stream_name, :stream_id, :id, :stream_revision
+    attr_reader :context, :stream_name, :stream_id, :id
+    attr_accessor :stream_revision
 
     # @param context [String]
     # @param stream_name [String]
@@ -63,6 +64,19 @@ module PgEventstore
       deconstruct_keys(nil)
     end
 
+    # @return [Integer]
+    def hash
+      to_hash.hash
+    end
+
+    # @param another [Object]
+    # @return [Boolean]
+    def eql?(another)
+      return false unless another.is_a?(Stream)
+
+      hash == another.hash
+    end
+
     def ==(other_stream)
       return false unless other_stream.is_a?(Stream)
 

data/lib/pg_eventstore/tasks/setup.rake

@@ -59,6 +59,10 @@ namespace :pg_eventstore do
         DROP TABLE IF EXISTS public.streams;
         DROP TABLE IF EXISTS public.event_types;
         DROP TABLE IF EXISTS public.migrations;
+        DROP TABLE IF EXISTS public.subscriptions_set;
+        DROP TABLE IF EXISTS public.subscriptions;
+        DROP TABLE IF EXISTS public.subscription_commands;
+        DROP TABLE IF EXISTS public.subscriptions_set_commands;
         DROP EXTENSION IF EXISTS "uuid-ossp";
         DROP EXTENSION IF EXISTS pgcrypto;
       SQL

data/lib/pg_eventstore/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgEventstore
-  VERSION = "0.4.0"
+  VERSION = "0.5.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pg_eventstore
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Ivan Dzyzenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-29 00:00:00.000000000 Z
+date: 2024-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -57,6 +57,7 @@ files:
 - db/migrations/10_create_subscription_commands.sql
 - db/migrations/11_create_subscriptions_set_commands.sql
 - db/migrations/12_improve_events_indexes.sql
+- db/migrations/13_remove_duplicated_index.sql
 - db/migrations/1_improve_specific_stream_indexes.sql
 - db/migrations/2_adjust_global_position_index.sql
 - db/migrations/3_extract_type_into_separate_table.sql
@@ -69,6 +70,7 @@ files:
 - docs/appending_events.md
 - docs/configuration.md
 - docs/events_and_streams.md
+- docs/linking_events.md
 - docs/multiple_commands.md
 - docs/reading_events.md
 - docs/subscriptions.md
@@ -79,8 +81,13 @@ files:
 - lib/pg_eventstore/client.rb
 - lib/pg_eventstore/commands.rb
 - lib/pg_eventstore/commands/append.rb
+- lib/pg_eventstore/commands/event_modifiers/prepare_link_event.rb
+- lib/pg_eventstore/commands/event_modifiers/prepare_regular_event.rb
+- lib/pg_eventstore/commands/link_to.rb
 - lib/pg_eventstore/commands/multiple.rb
 - lib/pg_eventstore/commands/read.rb
+- lib/pg_eventstore/commands/regular_stream_read_paginated.rb
+- lib/pg_eventstore/commands/system_stream_read_paginated.rb
 - lib/pg_eventstore/config.rb
 - lib/pg_eventstore/connection.rb
 - lib/pg_eventstore/errors.rb
@@ -96,6 +103,7 @@ files:
 - lib/pg_eventstore/queries.rb
 - lib/pg_eventstore/queries/event_queries.rb
 - lib/pg_eventstore/queries/event_type_queries.rb
+- lib/pg_eventstore/queries/preloader.rb
 - lib/pg_eventstore/queries/stream_queries.rb
 - lib/pg_eventstore/queries/subscription_command_queries.rb
 - lib/pg_eventstore/queries/subscription_queries.rb