pg_eventstore 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 402dc90a012b5e1ee934da4f62c4af4ba62e69693a45dac1a84d461950da5717
-  data.tar.gz: 6c5d1fdc2e9475eca72b5ef27d0081e0aec6331f76639b7172e676d8b6e63e3d
+  metadata.gz: e0de14f58d080bcab32005e045530ca7888761e5415d013dbb262746a02806ba
+  data.tar.gz: fee7b7335212796361b5ded87497c7d744ed5ddfd011a47d54cc2b545991b227
 SHA512:
-  metadata.gz: b20c1124f2108b671bd28f3677fb3b2ae88f3b19d2470eb5a31102eb597d4bd5af1080f9bd337b1528107eef2e4bce6b882d434aa8536abc0a5a80b373bfe3a3
-  data.tar.gz: 9fd5af079cedc277e278b2e0b50e628601880a81ec5bf7c94700595f6472be389b2fa3d3a2ba2f5d311c8844da40de2c4a52e4dc6c2bda2ca3559e94b267f7f2
+  metadata.gz: 0dbdd04e5778b292177062e5a44ed9ee4c2fc03e98da945a73523036f62ed09cc27ac00d1a5853e99975b82fc798f2f83639bbb2cd4f1745150ff121ca5d7056
+  data.tar.gz: 060f8b1b51cda7be2c472f914dc611fee2db052a2cd773676013b2175e58cf12c3895e8b631a0d79443804f3a733ca25d7012fac6519551308c890df065457d5

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [1.12.0]
+
+- Introduce `#read_grouped` API method that allows to group events by type
+
 ## [1.11.0]
 
 - Add a global position that caused an error to the subscription's error JSON info. This will help you understand what event caused your subscription to fail.

data/docs/reading_events.md

@@ -230,3 +230,101 @@ PgEventstore.client.read_paginated(projection_stream, options: { resolve_link_to
   end
 end
 ```
+
+## Grouping events by type
+
+`pg_eventstore` implements an ability to group events by type when reading from a stream. Example:
+
+```ruby
+stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Foo', stream_id: '1')
+event1 = PgEventstore::Event.new(type: 'Foo', data: { foo: 1 })
+event2 = PgEventstore::Event.new(type: 'Foo', data: { foo: 2 })
+event3 = PgEventstore::Event.new(type: 'Bar', data: { bar: 2 })
+
+PgEventstore.client.append_to_stream(stream, [event1, event2, event3])
+
+PgEventstore.client.read_grouped(stream) # => returns event1 and event3
+```
+
+API is very similar to the API of `#read`, but it ignores `:max_count` options as the result is always returns a set of event types in your stream.
+
+Reading most recent events:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :desc })
+```
+
+Filtering the result by stream attributes:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }] } }
+)
+```
+
+Filtering the result by event types:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { event_types: ['Foo', 'Bar'] } }
+)
+```
+
+Filtering by stream attributes and event types:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }], event_types: ['Foo', 'Bar'] } }
+)
+```
+
+Reading most recent events until the certain stream revision:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :desc, from_revision: 1 })
+```
+
+Reading the oldest events from the certain stream revision:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :asc, from_revision: 1 })
+```
+
+Reading most recent events until the certain global position:
+
+```ruby
+PgEventstore.client.read_grouped(PgEventstore::Stream.all_stream, options: { direction: :desc, from_position: 5 })
+```
+
+Reading the oldest events from the certain global position:
+
+```ruby
+PgEventstore.client.read_grouped(PgEventstore::Stream.all_stream, options: { direction: :asc, from_position: 5 })
+```
+
+### Event types list lookup
+
+If you do not provide event types filter - event types list will be determined based on the rest of arguments(a stream argument or a stream filters option).
+
+### Multiple events of same type in the result
+
+If same event type appear in different streams(different by `#context` and `#stream_name`) - those events will appear in the result. This is because even though `Event#type` value may be the same - its meaning may have different meaning in different `context`/`stream_name` couple. Example:
+
+```ruby
+stream1 = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Foo', stream_id: '1')
+stream2 = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Bar', stream_id: '1')
+
+event1 = PgEventstore::Event.new(type: 'Foo', data: { foo: 1 })
+event2 = PgEventstore::Event.new(type: 'Foo', data: { foo: 2 })
+
+PgEventstore.client.append_to_stream(stream1, event1)
+PgEventstore.client.append_to_stream(stream2, event2)
+
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }] } }
+) # => returns both events even though they are of "Foo" type
+```

data/lib/pg_eventstore/client.rb

@@ -55,10 +55,11 @@ module PgEventstore
     # Read events from the specific stream or from "all" stream.
     # @param stream [PgEventstore::Stream]
     # @param options [Hash] request options
-    # @option options [String] :direction read direction - 'Forwards' or 'Backwards'
+    # @option options [String] :direction read direction. Allowed values are "Forwards", "Backwards", "asc", "desc",
+    #   :asc, :desc
     # @option options [Integer] :from_revision a starting revision number. **Use this option when stream name is a
     #   normal stream name**
-    # @option options [Integer, Symbol] :from_position a starting global position number. **Use this option when reading
+    # @option options [Integer] :from_position a starting global position number. **Use this option when reading
     #   from "all" stream**
     # @option options [Integer] :max_count max number of events to return in one response. Defaults to config.max_count
     # @option options [Boolean] :resolve_link_tos When using projections to create new events you
@@ -94,7 +95,7 @@ module PgEventstore
     #       }
     #     )
     #
-    #     # Filtering the a mix of context and event type
+    #     # Filtering a mix of context and event type
     #     PgEventstore.client.read(
     #       PgEventstore::Stream.all_stream,
     #       options: { filter: { streams: [{ context: 'User' }], event_types: ['MyAwesomeEvent'] } }
@@ -123,6 +124,23 @@ module PgEventstore
         call(stream, options: { max_count: config.max_count }.merge(options))
     end
 
+    # Takes a stream, determines a list of even types in it and returns most recent(or very first - depending on
+    # :direction option) events, one of each type. If :event_types filter is provided - uses it instead of automatic
+    # event types lookup logic. The result size is almost always less than or equal to event types list size, so passing
+    # :max_count option does not make any effect. In case if event of same type appears in different context/stream
+    # name - it will be counted as a different event, thus, may appear several times in the result.
+    # @see {#read} for the detailed docs
+    # @param stream [PgEventstore::Stream]
+    # @param options [Hash] request options
+    # @param middlewares [Array, nil]
+    # @return [Array<PgEventstore::Event>]
+    def read_grouped(stream, options: {}, middlewares: nil)
+      cmd_class = stream.all_stream? ? Commands::AllStreamReadGrouped : Commands::RegularStreamReadGrouped
+      cmd_class.
+        new(Queries.new(partitions: partition_queries, events: event_queries(middlewares(middlewares)))).
+        call(stream, options: 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]
@@ -149,7 +167,7 @@ module PgEventstore
     private
 
     # @param middlewares [Array, nil]
-    # @return [Array<Object<#serialize, #deserialize>>]
+    # @return [Array<PgEventstore::Middleware>]
     def middlewares(middlewares = nil)
       return config.middlewares.values unless middlewares
 

data/lib/pg_eventstore/commands/all_stream_read_grouped.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class AllStreamReadGrouped < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash] request options
+      # @option options [String] :direction read direction
+      # @option options [Integer, Symbol] :from_position. **Use this option when reading from "all" stream**
+      # @option options [Boolean] :resolve_link_tos
+      # @option options [Hash] :filter provide it to filter events
+      # @return [Array<PgEventstore::Event>]
+      # @raise [PgEventstore::StreamNotFoundError]
+      def call(stream, options: {})
+        event_types = QueryBuilders::PartitionsFiltering.extract_event_types_filter(options)
+        stream_filters = QueryBuilders::PartitionsFiltering.extract_streams_filter(options)
+        stream_ids_grouped = group_stream_ids(options)
+        options_by_event_type =
+          queries.partitions.partitions(stream_filters, event_types).flat_map do |partition|
+            stream_ids = stream_ids_grouped[[partition.context, partition.stream_name]]
+            next build_filter_options_for_streams(partition, stream_ids, options) if stream_ids
+
+            build_filter_options_for_partitions(partition, options)
+          end
+        queries.events.grouped_events(stream, options_by_event_type, **options.slice(:resolve_link_tos))
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [Hash]
+      def group_stream_ids(options)
+        event_stream_filters = QueryBuilders::EventsFiltering.extract_streams_filter(options)
+        event_stream_filters.each_with_object({}) do |attrs, res|
+          next unless attrs[:stream_id]
+
+          res[[attrs[:context], attrs[:stream_name]]] ||= []
+          res[[attrs[:context], attrs[:stream_name]]].push(attrs[:stream_id])
+        end
+      end
+
+      # @param partition [PgEventstore::Partition]
+      # @param stream_ids [Array<String>]
+      # @param options [Hash]
+      # @return [Array<Hash>]
+      def build_filter_options_for_streams(partition, stream_ids, options)
+        stream_ids.map do |stream_id|
+          filter = {
+            streams: [{ context: partition.context, stream_name: partition.stream_name, stream_id: stream_id }],
+            event_types: [partition.event_type]
+          }
+          options.merge(filter: filter, max_count: 1)
+        end
+      end
+
+      # @param partition [PgEventstore::Partition]
+      # @param options [Hash]
+      # @return [Hash]
+      def build_filter_options_for_partitions(partition, options)
+        filter = {
+          streams: [{ context: partition.context, stream_name: partition.stream_name }],
+          event_types: [partition.event_type]
+        }
+        options.merge(filter: filter, max_count: 1)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/regular_stream_read_grouped.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class RegularStreamReadGrouped < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash] request options
+      # @option options [String] :direction read direction
+      # @option options [Integer, Symbol] :from_revision. **Use this option when stream name is a normal stream name**
+      # @option options [Integer, Symbol] :from_position. **Use this option when reading from "all" stream**
+      # @option options [Boolean] :resolve_link_tos
+      # @option options [Hash] :filter provide it to filter events
+      # @return [Array<PgEventstore::Event>]
+      # @raise [PgEventstore::StreamNotFoundError]
+      def call(stream, options: {})
+        queries.events.stream_revision(stream) || raise(StreamNotFoundError, stream)
+
+        event_types = QueryBuilders::PartitionsFiltering.extract_event_types_filter(options)
+        stream_filters = QueryBuilders::PartitionsFiltering.extract_streams_filter(
+          filter: { streams: [{ context: stream.context, stream_name: stream.stream_name }] }
+        )
+        options_by_event_type = queries.partitions.partitions(stream_filters, event_types).map do |partition|
+          filter = { event_types: [partition.event_type] }
+          options.merge(filter: filter, max_count: 1)
+        end
+        queries.events.grouped_events(stream, options_by_event_type, **options.slice(:resolve_link_tos))
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands.rb

@@ -5,6 +5,8 @@ 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_grouped'
+require_relative 'commands/all_stream_read_grouped'
 require_relative 'commands/regular_stream_read_paginated'
 require_relative 'commands/system_stream_read_paginated'
 require_relative 'commands/multiple'

data/lib/pg_eventstore/partition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  class Partition
+    include Extensions::OptionsExtension
+
+    # @!attribute id
+    #   @return [Integer]
+    option(:id)
+    # @!attribute context
+    #   @return [String]
+    option(:context)
+    # @!attribute stream_name
+    #   @return [String, nil]
+    option(:stream_name)
+    # @!attribute event_type
+    #   @return [String, nil]
+    option(:event_type)
+    # @!attribute table_name
+    #   @return [String]
+    option(:table_name)
+  end
+end

data/lib/pg_eventstore/queries/event_queries.rb

@@ -98,6 +98,24 @@ module PgEventstore
       end
     end
 
+    # @param stream [PgEventstore::Stream]
+    # @param options_by_event_type [Array<Hash>] a set of options per an event type
+    # @param options [Hash]
+    # @option options [Boolean] :resolve_link_tos
+    # @return [Array<PgEventstore::Event>]
+    def grouped_events(stream, options_by_event_type, **options)
+      builders = options_by_event_type.map do |filter|
+        QueryBuilders::EventsFiltering.events_filtering(stream, filter)
+      end
+      final_builder = SQLBuilder.union_builders(builders.map(&:to_sql_builder))
+
+      raw_events = connection.with do |conn|
+        conn.exec_params(*final_builder.to_exec_params)
+      end.to_a
+      raw_events = links_resolver.resolve(raw_events) if options[:resolve_link_tos]
+      deserializer.deserialize_many(raw_events)
+    end
+
     private
 
     # @param stream [PgEventstore::Stream]

data/lib/pg_eventstore/queries/partition_queries.rb

@@ -176,6 +176,19 @@ module PgEventstore
       end.to_a
     end
 
+    # @param stream_filters [Array<Hash[Symbol, String]>]
+    # @param event_filters [Array<String>]
+    # @return [Array<PgEventstore::Partition>]
+    def partitions(stream_filters, event_filters)
+      partitions_filter = QueryBuilders::PartitionsFiltering.new
+      stream_filters.each { |attrs| partitions_filter.add_stream_attrs(**attrs) }
+      partitions_filter.add_event_types(event_filters)
+      partitions_filter.with_event_types
+      connection.with do |conn|
+        conn.exec_params(*partitions_filter.to_exec_params)
+      end.map(&method(:deserialize))
+    end
+
     # @param stream [PgEventstore::Stream]
     # @return [String]
     def context_partition_name(stream)
@@ -194,5 +207,13 @@ module PgEventstore
     def event_type_partition_name(stream, event_type)
       "event_types_#{Digest::MD5.hexdigest("#{stream.context}-#{stream.stream_name}-#{event_type}")[0..5]}"
     end
+
+    private
+
+    # @param attrs [Hash]
+    # @return [PgEventstore::Partition]
+    def deserialize(attrs)
+      Partition.new(**attrs.transform_keys(&:to_sym))
+    end
   end
 end

data/lib/pg_eventstore/queries.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require_relative 'sql_builder'
+require_relative 'query_builders/basic_filtering'
 require_relative 'query_builders/events_filtering'
+require_relative 'query_builders/partitions_filtering'
 require_relative 'queries/transaction_queries'
 require_relative 'queries/event_queries'
 require_relative 'queries/partition_queries'

data/lib/pg_eventstore/query_builders/basic_filtering.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module QueryBuilders
+    # @!visibility private
+    class BasicFiltering
+      def initialize
+        @sql_builder = SQLBuilder.new.select("#{to_table_name}.*").from(to_table_name)
+      end
+
+      # @return [String]
+      def to_table_name
+        raise NotImplementedError
+      end
+
+      # @return [PgEventstore::SQLBuilder]
+      def to_sql_builder
+        @sql_builder
+      end
+
+      # @return [Array]
+      def to_exec_params
+        @sql_builder.to_exec_params
+      end
+    end
+  end
+end

data/lib/pg_eventstore/query_builders/events_filtering.rb

@@ -3,7 +3,11 @@
 module PgEventstore
   module QueryBuilders
     # @!visibility private
-    class EventsFiltering
+    class EventsFiltering < BasicFiltering
+      # @return [String]
+      TABLE_NAME = 'events'
+      private_constant :TABLE_NAME
+
       # @return [Integer]
       DEFAULT_LIMIT = 1_000
       # @return [Hash<String => String, Symbol => String>]
@@ -26,6 +30,7 @@ module PgEventstore
         # @return [PgEventstore::EventsFiltering]
         def events_filtering(stream, options)
           return all_stream_filtering(options) if stream.all_stream?
+
           if stream.system? && Stream::KNOWN_SYSTEM_STREAMS.include?(stream.context)
             return system_stream_filtering(stream, options)
           end
@@ -43,11 +48,9 @@ module PgEventstore
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
         def all_stream_filtering(options)
           event_filter = new
-          options in { filter: { event_types: Array => event_types } }
-          event_filter.add_event_types(event_types)
+          event_filter.add_event_types(extract_event_types_filter(options))
           event_filter.add_limit(options[:max_count])
-          options in { filter: { streams: Array => streams } }
-          streams&.each { |attrs| event_filter.add_stream_attrs(**attrs) }
+          extract_streams_filter(options).each { |attrs| event_filter.add_stream_attrs(**attrs) }
           event_filter.add_global_position(options[:from_position], options[:direction])
           event_filter.add_all_stream_direction(options[:direction])
           event_filter
@@ -58,8 +61,7 @@ module PgEventstore
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
         def specific_stream_filtering(stream, options)
           event_filter = new
-          options in { filter: { event_types: Array => event_types } }
-          event_filter.add_event_types(event_types)
+          event_filter.add_event_types(extract_event_types_filter(options))
           event_filter.add_limit(options[:max_count])
           event_filter.add_stream_attrs(**stream.to_hash)
           event_filter.add_revision(options[:from_revision], options[:direction])
@@ -75,14 +77,39 @@ module PgEventstore
             event_filter.set_source(stream.context)
           end
         end
+
+        # @param options [Hash]
+        # @return [Array<String>]
+        def extract_event_types_filter(options)
+          options in { filter: { event_types: Array => event_types } }
+          event_types&.select! do
+            _1.is_a?(String)
+          end
+          event_types || []
+        end
+
+        # @param options [Hash]
+        # @return [Array<Hash[Symbol, String]>]
+        def extract_streams_filter(options)
+          options in { filter: { streams: Array => streams } }
+          streams = streams&.map do
+            _1 in { context: String | NilClass => context }
+            _1 in { stream_name: String | NilClass => stream_name }
+            _1 in { stream_id: String | NilClass => stream_id }
+            { context: context, stream_name: stream_name, stream_id: stream_id }
+          end
+          streams || []
+        end
       end
 
       def initialize
-        @sql_builder =
-          SQLBuilder.new.
-            select('events.*').
-            from('events').
-            limit(DEFAULT_LIMIT)
+        super
+        @sql_builder.limit(DEFAULT_LIMIT)
+      end
+
+      # @return [String]
+      def to_table_name
+        TABLE_NAME
       end
 
       # @param context [String, nil]
@@ -95,21 +122,20 @@ module PgEventstore
 
         stream_attrs.compact!
         sql = stream_attrs.map do |attr, _|
-          "events.#{attr} = ?"
+          "#{to_table_name}.#{attr} = ?"
         end.join(" AND ")
         @sql_builder.where_or(sql, *stream_attrs.values)
       end
 
-      # @param event_types [Array<String>, nil]
+      # @param event_types [Array<String>]
       # @return [void]
       def add_event_types(event_types)
-        return if event_types.nil?
         return if event_types.empty?
 
         sql = event_types.size.times.map do
           "?"
         end.join(", ")
-        @sql_builder.where("events.type IN (#{sql})", *event_types)
+        @sql_builder.where("#{to_table_name}.type IN (#{sql})", *event_types)
       end
 
       # @param revision [Integer, nil]
@@ -118,7 +144,7 @@ module PgEventstore
       def add_revision(revision, direction)
         return unless revision
 
-        @sql_builder.where("events.stream_revision #{direction_operator(direction)} ?", revision)
+        @sql_builder.where("#{to_table_name}.stream_revision #{direction_operator(direction)} ?", revision)
       end
 
       # @param position [Integer, nil]
@@ -127,19 +153,19 @@ module PgEventstore
       def add_global_position(position, direction)
         return unless position
 
-        @sql_builder.where("events.global_position #{direction_operator(direction)} ?", position)
+        @sql_builder.where("#{to_table_name}.global_position #{direction_operator(direction)} ?", position)
       end
 
       # @param direction [String, Symbol, nil]
       # @return [void]
       def add_stream_direction(direction)
-        @sql_builder.order("events.stream_revision #{SQL_DIRECTIONS[direction]}")
+        @sql_builder.order("#{to_table_name}.stream_revision #{SQL_DIRECTIONS[direction]}")
       end
 
       # @param direction [String, Symbol, nil]
       # @return [void]
       def add_all_stream_direction(direction)
-        @sql_builder.order("events.global_position #{SQL_DIRECTIONS[direction]}")
+        @sql_builder.order("#{to_table_name}.global_position #{SQL_DIRECTIONS[direction]}")
       end
 
       # @param limit [Integer, nil]
@@ -150,20 +176,10 @@ module PgEventstore
         @sql_builder.limit(limit)
       end
 
-      # @return [PgEventstore::SQLBuilder]
-      def to_sql_builder
-        @sql_builder
-      end
-
-      # @return [Array]
-      def to_exec_params
-        @sql_builder.to_exec_params
-      end
-
       # @param table_name [String] system stream view name
       # @return [void]
       def set_source(table_name)
-        @sql_builder.from(%{ "#{PG::Connection.escape(table_name)}" events })
+        @sql_builder.from(%{ "#{PG::Connection.escape(table_name)}" #{to_table_name} })
       end
 
       private

data/lib/pg_eventstore/query_builders/partitions_filtering.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module QueryBuilders
+    # @!visibility private
+    class PartitionsFiltering < BasicFiltering
+      # @return [String]
+      TABLE_NAME = 'partitions'
+      private_constant :TABLE_NAME
+
+      class << self
+        # @param options [Hash]
+        # @return [Array<String>]
+        def extract_event_types_filter(options)
+          options in { filter: { event_types: Array => event_types } }
+          event_types&.select! do
+            _1.is_a?(String)
+          end
+          event_types || []
+        end
+
+        # @param options [Hash]
+        # @return [Array<Hash[Symbol, String]>]
+        def extract_streams_filter(options)
+          options in { filter: { streams: Array => streams } }
+          streams = streams&.map do
+            _1 in { context: String | NilClass => context }
+            _1 in { stream_name: String | NilClass => stream_name }
+            { context: context, stream_name: stream_name }
+          end
+          streams || []
+        end
+      end
+
+      # @return [String]
+      def to_table_name
+        TABLE_NAME
+      end
+
+      # @param context [String, nil]
+      # @param stream_name [String, nil]
+      # @return [void]
+      def add_stream_attrs(context: nil, stream_name: nil)
+        stream_attrs = { context: context, stream_name: stream_name }
+        return unless correct_stream_filter?(stream_attrs)
+
+        stream_attrs.compact!
+        sql = stream_attrs.map do |attr, _|
+          "#{to_table_name}.#{attr} = ?"
+        end.join(" AND ")
+        @sql_builder.where_or(sql, *stream_attrs.values)
+      end
+
+      # @param event_types [Array<String>]
+      # @return [void]
+      def add_event_types(event_types)
+        return if event_types.empty?
+
+        @sql_builder.where("#{to_table_name}.event_type = ANY(?::varchar[])", event_types)
+      end
+
+      # @return [void]
+      def with_event_types
+        @sql_builder.where('event_type IS NOT NULL')
+      end
+
+      private
+
+      # @param stream_attrs [Hash]
+      # @return [Boolean]
+      def correct_stream_filter?(stream_attrs)
+        result = (stream_attrs in { context: String, stream_name: String } | { context: String, stream_name: nil })
+        return true if result
+
+        PgEventstore&.logger&.debug(<<~TEXT)
+          Ignoring unsupported stream filter format for grouped read #{stream_attrs.compact.inspect}. \
+          See docs/reading_events.md docs for supported formats.
+        TEXT
+        false
+      end
+    end
+  end
+end

data/lib/pg_eventstore/sql_builder.rb

@@ -4,6 +4,16 @@ module PgEventstore
   # Deadly simple SQL builder
   # @!visibility private
   class SQLBuilder
+    class << self
+      # @param builders [Array<PgEventstore::SQLBuilder>]
+      # @return [PgEventstore::SQLBuilder]
+      def union_builders(builders)
+        builders[1..].each_with_object(builders[0]) do |builder, first_builder|
+          first_builder.union(builder)
+        end
+      end
+    end
+
     def initialize
       @select_values = []
       @from_value = nil

data/lib/pg_eventstore/subscriptions/queries/subscription_queries.rb

@@ -127,7 +127,7 @@ module PgEventstore
     def subscriptions_events(query_options)
       return {} if query_options.empty?
 
-      final_builder = union_builders(query_options.map { |id, opts| query_builder(id, opts) })
+      final_builder = SQLBuilder.union_builders(query_options.map { |id, opts| query_builder(id, opts) })
       raw_events = connection.with do |conn|
         conn.exec_params(*final_builder.to_exec_params)
       end.to_a
@@ -177,14 +177,6 @@ module PgEventstore
       builder.select("#{id} as runner_id")
     end
 
-    # @param builders [Array<PgEventstore::SQLBuilder>]
-    # @return [PgEventstore::SQLBuilder]
-    def union_builders(builders)
-      builders[1..].each_with_object(builders[0]) do |builder, first_builder|
-        first_builder.union(builder)
-      end
-    end
-
     # @return [PgEventstore::TransactionQueries]
     def transaction_queries
       TransactionQueries.new(connection)

data/lib/pg_eventstore/utils.rb

@@ -85,7 +85,8 @@ module PgEventstore
       def write_to_file(file_path, content)
         file = File.open(file_path, "w")
         file.write(content)
-        file.close
+      ensure
+        file&.close
       end
 
       # @param file_path [String]
@@ -99,10 +100,10 @@ module PgEventstore
       # @return [String, nil]
       def read_pid(file_path)
         file = File.open(file_path, "r")
-        file.readline.strip.tap do
-          file.close
-        end
+        file.readline.strip
       rescue Errno::ENOENT
+      ensure
+        file&.close
       end
 
       # @param exception [StandardError]

data/lib/pg_eventstore/version.rb

@@ -2,5 +2,5 @@
 
 module PgEventstore
   # @return [String]
-  VERSION = "1.11.0"
+  VERSION = "1.12.0"
 end

data/lib/pg_eventstore/web/application.rb

@@ -27,7 +27,7 @@ module PgEventstore
       helpers(Paginator::Helpers, Subscriptions::Helpers) do
         # @return [Array<Hash>, nil]
         def streams_filter
-          params in { filter: { streams: Array => streams } }
+          streams = QueryBuilders::EventsFiltering.extract_streams_filter(params)
           streams&.select { _1 in { context: String, stream_name: String, stream_id: String } }&.map do
             Hash[_1.reject { |_, value| value == '' }].transform_keys(&:to_sym)
           end&.reject { _1.empty? }
@@ -41,8 +41,9 @@ module PgEventstore
 
         # @return [Array<String>, nil]
         def events_filter
-          params in { filter: { events: Array => events } }
-          events&.select { _1.is_a?(String) && _1 != '' }
+          event_filters = { filter: { event_types: params.dig(:filter, :events) } }
+          events = QueryBuilders::EventsFiltering.extract_event_types_filter(event_filters)
+          events&.reject { _1 == '' }
         end
 
         # @return [Symbol]

data/lib/pg_eventstore.rb

@@ -9,6 +9,7 @@ require_relative 'pg_eventstore/extensions/callback_handlers_extension'
 require_relative 'pg_eventstore/extensions/using_connection_extension'
 require_relative 'pg_eventstore/event_class_resolver'
 require_relative 'pg_eventstore/config'
+require_relative 'pg_eventstore/partition'
 require_relative 'pg_eventstore/event'
 require_relative 'pg_eventstore/stream'
 require_relative 'pg_eventstore/commands'

data/sig/pg_eventstore/client.rbs

@@ -26,6 +26,8 @@ module PgEventstore
     # _@param_ `middlewares` — provide a list of middleware names to override a config's middlewares
     def read: (PgEventstore::Stream stream, ?options: ::Hash[untyped, untyped], ?middlewares: ::Array[::Symbol]?) -> ::Array[PgEventstore::Event]
 
+    def read_grouped: (Stream stream, ?options: Hash[untyped, untyped], ?middlewares: ::Array[::Symbol]?) -> ::Array[PgEventstore::Event]
+
     # _@param_ `stream`
     #
     # _@param_ `options` — request options

data/sig/pg_eventstore/commands/all_stream_read_grouped.rbs

@@ -0,0 +1,16 @@
+module PgEventstore
+  module Commands
+    class AllStreamReadGrouped < AbstractCommand
+
+      def call: (Stream stream, ?options: ::Hash[untyped, untyped]) -> Array[Event]
+
+      private
+
+      def build_filter_options_for_partitions: (Partition partition, Hash[untyped, untyped] options) -> Hash[untyped, untyped]
+
+      def build_filter_options_for_streams: (Partition partition, Array[String] stream_ids, Hash[untyped, untyped] options) -> Array[Hash[untyped, untyped]]
+
+      def group_stream_ids: (Hash[untyped, untyped] options) -> Hash[untyped, untyped]
+    end
+  end
+end

data/sig/pg_eventstore/commands/regular_stream_read_grouped.rbs

@@ -0,0 +1,8 @@
+module PgEventstore
+  module Commands
+    class RegularStreamReadGrouped < AbstractCommand
+
+      def call: (Stream stream, ?options: ::Hash[untyped, untyped]) -> Array[Event]
+    end
+  end
+end

data/sig/pg_eventstore/partition.rbs

@@ -0,0 +1,15 @@
+module PgEventstore
+  class Partition
+    include Extensions::OptionsExtension
+
+    attr_accessor id: Integer
+
+    attr_accessor context: String
+
+    attr_accessor stream_name: String?
+
+    attr_accessor event_type: String?
+
+    attr_accessor table_name: String
+  end
+end

data/sig/pg_eventstore/queries/event_queries.rbs

@@ -10,6 +10,8 @@ module PgEventstore
     # _@param_ `event`
     def event_exists?: (PgEventstore::Event event) -> bool
 
+    def grouped_events: (Stream stream, Array[Hash[untyped, untyped]] options_by_event_type, **untyped options)-> Array[Event]
+
     # _@param_ `events`
     def ids_from_db: (::Array[PgEventstore::Event] events) -> ::Array[String]
 

data/sig/pg_eventstore/queries/partition_queries.rbs

@@ -39,6 +39,8 @@ module PgEventstore
     # _@return_ — partition attributes
     def context_partition: (PgEventstore::Stream stream) -> ::Hash[untyped, untyped]?
 
+    def partitions: (Array[Hash[Symbol, String | nil]] stream_filters, Array[String] event_filters)-> Array[Partition]
+
     # _@param_ `stream`
     #
     # _@return_ — partition attributes
@@ -70,5 +72,9 @@ module PgEventstore
 
     # Returns the value of attribute connection.
     attr_accessor connection: PgEventstore::Connection
+
+    private
+
+    def deserialize: (Hash[untyped, untyped] attrs)-> Partition
   end
 end

data/sig/pg_eventstore/query_builders/basic_filtering.rbs

@@ -0,0 +1,15 @@
+module PgEventstore
+  module QueryBuilders
+    class BasicFiltering
+      @sql_builder: SQLBuilder
+
+      def initialize: -> void
+
+      def to_exec_params: -> [String, Array[untyped]]
+
+      def to_sql_builder: -> SQLBuilder
+
+      def to_table_name: -> String
+    end
+  end
+end

data/sig/pg_eventstore/query_builders/events_filtering_query.rbs

@@ -1,39 +1,37 @@
 module PgEventstore
   module QueryBuilders
     # @!visibility private
-    class EventsFiltering
+    class EventsFiltering < BasicFiltering
       DEFAULT_LIMIT: Integer
       SQL_DIRECTIONS: Hash[String | Symbol, String]
       SUBSCRIPTIONS_OPTIONS: ::Array[Symbol]
 
-      @sql_builder: PgEventstore::SQLBuilder
+      TABLE_NAME: String
+
+      def self.events_filtering: (Stream stream, ::Hash[untyped, untyped] options) -> EventsFiltering
+
+      def self.extract_event_types_filter: (Hash[untyped, untyped] options) -> Array[String]
+
+      def self.extract_streams_filter: (Hash[untyped, untyped] options) -> Array[Hash[untyped, untyped]]
 
-      def self.events_filtering: (PgEventstore::Stream stream, ::Hash[untyped, untyped] options) -> PgEventstore::QueryBuilders::EventsFiltering
-      
       # _@param_ `options`
-      def self.subscriptions_events_filtering: (::Hash[untyped, untyped] options) -> PgEventstore::QueryBuilders::EventsFiltering
+      def self.subscriptions_events_filtering: (::Hash[untyped, untyped] options) -> EventsFiltering
 
       # _@param_ `options`
-      def self.all_stream_filtering: (::Hash[untyped, untyped] options) -> PgEventstore::QueryBuilders::EventsFiltering
+      def self.all_stream_filtering: (::Hash[untyped, untyped] options) -> EventsFiltering
 
       # _@param_ `stream`
       #
       # _@param_ `options`
-      def self.specific_stream_filtering: (PgEventstore::Stream stream, ::Hash[untyped, untyped] options) -> PgEventstore::QueryBuilders::EventsFiltering
+      def self.specific_stream_filtering: (Stream stream, ::Hash[untyped, untyped] options) -> EventsFiltering
 
-      def self.system_stream_filtering: (PgEventstore::Stream stream, Hash[untyped, untyped] options) -> PgEventstore::QueryBuilders::EventsFiltering
+      def self.system_stream_filtering: (Stream stream, Hash[untyped, untyped] options) -> EventsFiltering
 
       def initialize: () -> void
 
-      # _@param_ `context`
-      #
-      # _@param_ `stream_name`
-      #
-      # _@param_ `stream_id`
       def add_stream_attrs: (?context: String?, ?stream_name: String?, ?stream_id: String?) -> void
 
-      # _@param_ `event_types`
-      def add_event_types: (::Array[String]? event_types) -> void
+      def add_event_types: (::Array[String] event_types) -> void
 
       # _@param_ `revision`
       #
@@ -54,9 +52,11 @@ module PgEventstore
       # _@param_ `limit`
       def add_limit: (Integer? limit) -> void
 
-      def to_sql_builder: () -> PgEventstore::SQLBuilder
+      def set_source: (String table_name)-> void
+
+      def to_sql_builder: () -> SQLBuilder
 
-      def to_exec_params: () -> ::Array[untyped]
+      def to_exec_params: () -> [String, Array[untyped]]
 
       # _@param_ `stream_attrs`
       def correct_stream_filter?: (::Hash[untyped, untyped] stream_attrs) -> bool

data/sig/pg_eventstore/query_builders/partitions_filtering.rbs

@@ -0,0 +1,21 @@
+module PgEventstore
+  module QueryBuilders
+    class PartitionsFiltering < BasicFiltering
+      TABLE_NAME: String
+
+      def self.extract_event_types_filter: (Hash[untyped, untyped] options) -> Array[String]
+
+      def self.extract_streams_filter: (Hash[untyped, untyped] options) -> Array[Hash[untyped, untyped]]
+
+      def add_event_types: (::Array[String] event_types) -> void
+
+      def add_stream_attrs: (?context: String?, ?stream_name: String?) -> void
+
+      def with_event_types: -> void
+
+      private
+
+      def correct_stream_filter?: (::Hash[untyped, untyped] stream_attrs) -> bool
+    end
+  end
+end

data/sig/pg_eventstore/sql_builder.rbs

@@ -46,7 +46,7 @@ module PgEventstore
 
     def remove_group: () -> self
 
-    def to_exec_params: () -> ::Array[(String | ::Array[untyped])]
+    def to_exec_params: () -> [String, ::Array[untyped]]
 
     def positional_values: () -> ::Array[Object]
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pg_eventstore
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Ivan Dzyzenko
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -116,6 +115,7 @@ files:
 - lib/pg_eventstore/cli/wait_for_subscriptions_set_shutdown.rb
 - lib/pg_eventstore/client.rb
 - lib/pg_eventstore/commands.rb
+- lib/pg_eventstore/commands/all_stream_read_grouped.rb
 - lib/pg_eventstore/commands/append.rb
 - lib/pg_eventstore/commands/delete_event.rb
 - lib/pg_eventstore/commands/delete_stream.rb
@@ -124,6 +124,7 @@ files:
 - 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_grouped.rb
 - lib/pg_eventstore/commands/regular_stream_read_paginated.rb
 - lib/pg_eventstore/commands/system_stream_read_paginated.rb
 - lib/pg_eventstore/config.rb
@@ -139,6 +140,7 @@ files:
 - lib/pg_eventstore/extensions/using_connection_extension.rb
 - lib/pg_eventstore/maintenance.rb
 - lib/pg_eventstore/middleware.rb
+- lib/pg_eventstore/partition.rb
 - lib/pg_eventstore/pg_connection.rb
 - lib/pg_eventstore/queries.rb
 - lib/pg_eventstore/queries/event_queries.rb
@@ -146,7 +148,9 @@ files:
 - lib/pg_eventstore/queries/maintenance_queries.rb
 - lib/pg_eventstore/queries/partition_queries.rb
 - lib/pg_eventstore/queries/transaction_queries.rb
+- lib/pg_eventstore/query_builders/basic_filtering.rb
 - lib/pg_eventstore/query_builders/events_filtering.rb
+- lib/pg_eventstore/query_builders/partitions_filtering.rb
 - lib/pg_eventstore/rspec/has_option_matcher.rb
 - lib/pg_eventstore/rspec/test_helpers.rb
 - lib/pg_eventstore/sql_builder.rb
@@ -271,6 +275,7 @@ files:
 - sig/pg_eventstore/cli/try_unlock_subscriptions_set.rbs
 - sig/pg_eventstore/cli/wait_for_subscriptions_set_shutdown.rbs
 - sig/pg_eventstore/client.rbs
+- sig/pg_eventstore/commands/all_stream_read_grouped.rbs
 - sig/pg_eventstore/commands/append.rbs
 - sig/pg_eventstore/commands/delete_event.rbs
 - sig/pg_eventstore/commands/delete_stream.rbs
@@ -279,6 +284,7 @@ files:
 - sig/pg_eventstore/commands/link_to.rbs
 - sig/pg_eventstore/commands/multiple.rbs
 - sig/pg_eventstore/commands/read.rbs
+- sig/pg_eventstore/commands/regular_stream_read_grouped.rbs
 - sig/pg_eventstore/commands/regular_stream_read_paginated.rbs
 - sig/pg_eventstore/commands/system_stream_read_paginated.rbs
 - sig/pg_eventstore/config.rbs
@@ -294,6 +300,7 @@ files:
 - sig/pg_eventstore/extensions/using_connection_extension.rbs
 - sig/pg_eventstore/maintenance.rbs
 - sig/pg_eventstore/middleware.rbs
+- sig/pg_eventstore/partition.rbs
 - sig/pg_eventstore/pg_connection.rbs
 - sig/pg_eventstore/queries.rbs
 - sig/pg_eventstore/queries/event_queries.rbs
@@ -301,7 +308,9 @@ files:
 - sig/pg_eventstore/queries/maintenance_queries.rbs
 - sig/pg_eventstore/queries/partition_queries.rbs
 - sig/pg_eventstore/queries/transaction_queries.rbs
+- sig/pg_eventstore/query_builders/basic_filtering.rbs
 - sig/pg_eventstore/query_builders/events_filtering_query.rbs
+- sig/pg_eventstore/query_builders/partitions_filtering.rbs
 - sig/pg_eventstore/sql_builder.rbs
 - sig/pg_eventstore/stream.rbs
 - sig/pg_eventstore/subscriptions/basic_runner.rbs
@@ -368,7 +377,6 @@ metadata:
   homepage_uri: https://github.com/yousty/pg_eventstore
   source_code_uri: https://github.com/yousty/pg_eventstore
   changelog_uri: https://github.com/yousty/pg_eventstore/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -383,8 +391,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: EventStore implementation using PostgreSQL
 test_files: []