eventstore_ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fac7abdb7fc8945f65b67176313c544971082fc5abca57a48fffe8f4b7b574e3
+  data.tar.gz: 773ecb26de6d7279e66c6963586b0c8f0f38e51c58d32e1f1ec2dbb47914a1f2
+SHA512:
+  metadata.gz: 61960c4a2a20672f1783777bbccc5032642de43cc507010b62d1e4578ddc0e4b15163c3f6c4d5a9d0270fd20f9676dbce4ac66b2cc7f3e7392377d8778d0afc2
+  data.tar.gz: aec2ebe2ba8c175202fd07be3e8fd255f3d3669ceebc2bc216f3427b434b2885292a5775089d3c56ab443b51e80ba8d6d3d0e915b8715d4c4de5fe6e6db5582e

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] – 2025-08-01
+### Added
+* First public release of **eventstore_ruby** – a 100 % feature-parity port of the `@eventstore-typescript` library.
+* Core value objects: `Event`, `EventRecord`, `EventFilter`, `QueryResult`.
+* In-memory infrastructure:
+  * `EventStream` (append-only log)
+  * `ReadWriteLockFIFO` (fair RW lock)
+  * `MemoryEventStore` with optimistic locking.
+  * `MemoryEventStreamNotifier` for real-time subscriptions.
+* PostgreSQL store:
+  * DDL helpers (`schema.rb`)
+  * SQL builders (`query.rb`, `insert.rb`)
+  * Data mappers (`transform.rb`)
+  * `PostgresEventStore` (optimistic locking, auto-notification, database initialisation helper).
+* Query tooling: recursive predicate matching in `QueryProcessor`.
+* Example Banking CLI app with fully-featured domain (open / list / deposit / withdraw / transfer / analytics) and rebuild commands.
+* Extensive Minitest suite mirroring original Jest tests.
+* Documentation (README) with quick-start instructions.
+
+### Changed
+* None – first release.
+
+### Fixed
+* N/A 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Manuel Ortega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

data/README.md

@@ -0,0 +1,125 @@
+# EventStoreRuby
+
+A faithful Ruby port of the [@ricofritzsche/eventstore](https://www.npmjs.com/package/@ricofritzsche/eventstore) TypeScript library.
+
+It provides the same event-sourcing primitives, including:
+
+* **EventStore implementations**
+  * `EventStoreRuby::MemoryEventStore` – fully in-memory (great in tests)
+  * `EventStoreRuby::PostgresEventStore` – persistent, PostgreSQL-backed
+* **Notifier** – `MemoryEventStreamNotifier` for real-time fan-out of appended events
+* **Query engine** – powerful payload-predicate matching identical to the original TS implementation
+* **Optimistic locking** – conditional `append` with `expected_max_sequence_number`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'eventstore_ruby', git: 'https://github.com/gazpachoteam/eventstore-ruby.git'
+# ⬆ until the gem is published to RubyGems
+```
+
+or (once released):
+
+```bash
+$ gem install eventstore_ruby
+```
+
+## Quick start (Memory)
+
+```ruby
+require 'eventstore_ruby'
+
+store = EventStoreRuby::MemoryEventStore.new
+
+# Subscribe **before** writing so you get real-time notifications
+subscription = store.subscribe do |events|
+  puts "got #{events.size} event(s): #{events.map(&:event_type).join(', ')}"
+end
+
+# Append events
+store.append([
+  EventStoreRuby::Event.new(event_type: 'UserRegistered', payload: {user_id: 1}),
+  EventStoreRuby::Event.new(event_type: 'EmailVerified',  payload: {user_id: 1})
+])
+
+# Historical query
+filter  = EventStoreRuby.create_filter(%w[UserRegistered EmailVerified])
+result  = store.query(filter)
+puts "history has #{result.events.size} events, max seq ##{result.max_sequence_number}"
+
+subscription.unsubscribe
+```
+
+## Quick start (PostgreSQL)
+
+```bash
+# launch Postgres
+$ docker run --name eventstore-pg -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15
+$ export DATABASE_URL="postgres://postgres:postgres@localhost:5432/postgres"
+```
+
+```ruby
+require 'eventstore_ruby'
+
+store = EventStoreRuby::PostgresEventStore.new
+store.initialize_database # creates table & indexes on first run
+
+# same API as memory store …
+```
+
+## API overview
+
+```ruby
+# Building filters
+filter = EventStoreRuby.create_filter(%w[UserRegistered], [{user_id: 1}])
+
+# Querying
+qr = store.query(filter)        # => QueryResult (events + max_sequence_number)
+
+# Combining multiple filters with OR – EventQuery
+
+Often you need to fetch events that match **any** of several filter criteria.  
+Instead of doing multiple round-trips you can combine `EventFilter`s into a single
+`EventQuery` (logical OR):
+
+```ruby
+# Build individual filters
+f_users  = EventStoreRuby.create_filter(['UserRegistered'])
+f_orders = EventStoreRuby.create_filter(['OrderPlaced'], [{country: 'DE'}])
+
+# Combine them
+query = EventStoreRuby.create_query([f_users, f_orders])
+
+# Works with both query and append
+result = store.query(query)
+
+# Conditional write based on the same logical context
+store.append(new_events, query, expected_max_sequence_number: result.max_sequence_number)
+```
+
+`EventQuery` is supported by **both** the in-memory and PostgreSQL stores. Under
+the hood it is translated into `OR` conditions in SQL for Postgres, and on the
+in-memory store it simply checks each contained filter one after another.
+
+# Conditional append (optimistic locking)
+store.append(events, filter, expected_max_sequence_number: qr.max_sequence_number)
+
+# Subscriptions
+sub = store.subscribe do |events| … end
+sub.unsubscribe
+```
+
+For detailed objects & methods see the YARD docs or the source under `lib/eventstore_ruby/`.
+
+## Development / Tests
+
+```bash
+$ bundle install
+$ rake test   # runs Minitest suite (ports of all original Jest specs)
+```
+
+## License
+
+MIT © 2024 – originally by Ralf Westphal & Rico Fritzsche. Ruby port by Gazpacho Dev team (Manuel Ortega). 

data/lib/eventstore_ruby/event.rb

@@ -0,0 +1,24 @@
+module EventStoreRuby
+  # Base application-level event.
+  # Immutable: attributes are frozen after initialization.
+  class Event
+    attr_reader :event_type, :payload
+
+    def initialize(event_type:, payload: {})
+      @event_type = event_type.to_s.freeze
+      @payload    = payload.freeze
+      freeze
+    end
+  end
+
+  # Persisted event enriched with sequence number and timestamp.
+  class EventRecord < Event
+    attr_reader :sequence_number, :timestamp
+
+    def initialize(sequence_number:, timestamp: Time.now, event_type:, payload: {})
+      @sequence_number = Integer(sequence_number)
+      @timestamp       = timestamp
+      super(event_type: event_type, payload: payload)
+    end
+  end
+end 

data/lib/eventstore_ruby/event_filter.rb

@@ -0,0 +1,19 @@
+module EventStoreRuby
+  # Describes the subset of events to select when querying the store.
+  # Immutable and thread-safe.
+  class EventFilter
+    attr_reader :event_types, :payload_predicates
+
+    # event_types: [String] (required, can be empty for "all types")
+    # payload_predicates: Array<Hash> (optional) – each hash is a partial payload that must match.
+    def initialize(event_types:, payload_predicates: nil)
+      unless event_types.is_a?(Array) && event_types.all? { |t| t.is_a?(String) }
+        raise ArgumentError, 'event_types must be an array of strings'
+      end
+
+      @event_types = event_types.freeze
+      @payload_predicates = payload_predicates&.map(&:freeze)&.freeze
+      freeze
+    end
+  end
+end 

data/lib/eventstore_ruby/event_query.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module EventStoreRuby
+  # EventQuery represents a logical OR composition of multiple EventFilter
+  # instances. An event matches the query if it matches at least one of the
+  # contained filters.
+  class EventQuery
+    attr_reader :filters
+
+    def initialize(filters:)
+      unless filters.is_a?(Array) && filters.all? { |f| f.is_a?(EventFilter) }
+        raise ArgumentError, 'filters must be an Array<EventFilter>'
+      end
+      raise ArgumentError, 'filters array cannot be empty' if filters.empty?
+
+      @filters = filters.freeze
+      freeze
+    end
+  end
+end 

data/lib/eventstore_ruby/event_stream.rb

@@ -0,0 +1,30 @@
+module EventStoreRuby
+  # In-memory append-only event sequence.
+  class EventStream
+    attr_reader :event_records
+
+    def initialize
+      @event_records = []
+      @last_sequence_number = 0
+      @mutex = Mutex.new
+    end
+
+    # Appends Event objects, returns newly created EventRecord objects.
+    def append(events)
+      raise ArgumentError, 'events must be an Array' unless events.is_a?(Array)
+
+      @mutex.synchronize do
+        records = events.map do |event|
+          EventRecord.new(
+            sequence_number: (@last_sequence_number += 1),
+            timestamp: Time.now,
+            event_type: event.event_type,
+            payload: event.payload
+          )
+        end
+        @event_records.concat(records)
+        records
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/event_subscription.rb

@@ -0,0 +1,16 @@
+module EventStoreRuby
+  # Represents an active subscription to an EventStore.
+  class EventSubscription
+    attr_reader :id
+
+    def initialize(id, unsubscribe_proc)
+      @id = id
+      @unsubscribe_proc = unsubscribe_proc
+      freeze
+    end
+
+    def unsubscribe
+      @unsubscribe_proc.call
+    end
+  end
+end 

data/lib/eventstore_ruby/filter.rb

@@ -0,0 +1,20 @@
+module EventStoreRuby
+  # Factory/helper for building EventFilter objects conveniently.
+  # Usage: EventStoreRuby.create_filter(%w[UserCreated], [{ 'user_id' => 42 }])
+  def create_filter(event_types, payload_predicates = nil)
+    EventFilter.new(event_types: event_types, payload_predicates: payload_predicates)
+  end
+
+  module_function :create_filter
+
+  # Build an EventQuery combining multiple EventFilter objects with OR
+  # semantics. Example:
+  #   f1 = create_filter(['UserCreated'])
+  #   f2 = create_filter(['OrderPlaced'])
+  #   query = create_query([f1, f2])
+  def create_query(filters)
+    EventQuery.new(filters: filters)
+  end
+
+  module_function :create_query
+end 

data/lib/eventstore_ruby/memory_event_store.rb

@@ -0,0 +1,59 @@
+module EventStoreRuby
+  # Fully in-memory EventStore implementation.
+  class MemoryEventStore
+    def initialize(notifier: MemoryEventStreamNotifier.new)
+      @event_stream = EventStream.new
+      @notifier = notifier
+      @lock = ReadWriteLockFIFO.new
+    end
+
+    # Query events with optional filter.
+    # Returns QueryResult.
+    def query(filter = nil)
+      query_with_lock(filter, @lock)
+    end
+
+    # Convenience: return all events in the store
+    def query_all
+      query(nil)
+    end
+
+    def append(events, filter = nil, expected_max_sequence_number: nil)
+      raise ArgumentError, 'events must be an Array' unless events.is_a?(Array)
+
+      @lock.acquire_write
+      begin
+        if expected_max_sequence_number
+          current_query_result = query_with_lock(filter, nil) # Already under write lock, no read lock needed
+          if current_query_result.max_sequence_number != expected_max_sequence_number
+            raise 'eventstore-stores-memory-err05: Context changed: events were modified between query() and append()'
+          end
+        end
+
+        event_records = @event_stream.append(events)
+        @notifier.notify(event_records)
+      ensure
+        @lock.release_write
+      end
+    end
+
+    def subscribe(&handle)
+      @notifier.subscribe(handle)
+    end
+
+    private
+
+    def query_with_lock(filter, lock)
+      lock&.acquire_read
+      begin
+        matching = QueryProcessor.process(@event_stream.event_records, filter)
+        max_seq = matching.empty? ? 0 : matching.last.sequence_number
+        # With deterministic ReadWriteLockFIFO the additional sleep is no
+        # longer needed to satisfy ordering expectations in tests.
+        QueryResult.new(events: matching, max_sequence_number: max_seq)
+      ensure
+        lock&.release_read
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/memory_event_stream_notifier.rb

@@ -0,0 +1,55 @@
+require 'concurrent'
+
+module EventStoreRuby
+  # In-memory notifier broadcasting EventRecord arrays to subscribers.
+  class MemoryEventStreamNotifier
+    def initialize
+      @subscriptions = {}
+      @counter = 0
+      @mutex = Mutex.new
+    end
+
+    # Subscribe with a handler Proc accepting events Array<EventRecord>.
+    # Returns EventSubscription.
+    def subscribe(handle)
+      raise ArgumentError, 'handle must respond_to :call' unless handle.respond_to?(:call)
+
+      id = nil
+      unsubscribe_proc = nil
+
+      @mutex.synchronize do
+        id = "notifier-sub-#{@counter += 1}"
+        @subscriptions[id] = handle
+        unsubscribe_proc = -> {
+          @mutex.synchronize { @subscriptions.delete(id) }
+        }
+      end
+
+      EventSubscription.new(id, unsubscribe_proc)
+    end
+
+    # Notify subscribers concurrently; errors are rescued and printed.
+    def notify(events)
+      return if events.empty?
+      subs = nil
+      @mutex.synchronize { subs = @subscriptions.values.dup }
+
+      # run each handler in a future so notification order is preserved per subscription but not blocked by others
+      futures = subs.map do |handle|
+        Concurrent::Future.execute do
+          begin
+            handle.call(events)
+          rescue StandardError => e
+            Kernel.warn "notifiers-memory-err01: Error notifying subscriber: #{e.message}\n#{e.backtrace.join("\n")}"
+          end
+        end
+      end
+
+      futures.each(&:wait) # Equivalent to Promise.allSettled
+    end
+
+    def close
+      @mutex.synchronize { @subscriptions.clear }
+    end
+  end
+end 

data/lib/eventstore_ruby/postgres/insert.rb

@@ -0,0 +1,30 @@
+module EventStoreRuby
+  module Postgres
+    module InsertBuilder
+      module_function
+
+      # Returns [sql, params]
+      def build_cte_insert_query(filter, expected_max_seq)
+        version_sql, version_params = QueryBuilder.build_context_version_query(filter)
+        context_param_count = version_params.length
+        event_types_param = context_param_count + 1
+        payloads_param = context_param_count + 2
+
+        sql = <<~SQL
+          WITH context AS (
+            SELECT MAX(sequence_number) AS max_seq
+            FROM events
+            WHERE #{version_sql}
+          )
+          INSERT INTO events (event_type, payload)
+          SELECT unnest($#{event_types_param}::text[]), unnest($#{payloads_param}::jsonb[])
+          FROM context
+          WHERE COALESCE(max_seq, 0) = #{expected_max_seq}
+          RETURNING *
+        SQL
+
+        [sql, version_params]
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/postgres/query.rb

@@ -0,0 +1,63 @@
+module EventStoreRuby
+  module Postgres
+    module QueryBuilder
+      module_function
+
+      def pg_array_literal(strings)
+        '{' + strings.map { |s| s.gsub('"', '""') }.join(',') + '}'
+      end
+
+      # Returns [sql, params] for a SELECT query returning all matching events,
+      # ordered by ascending sequence number. Accepts an EventFilter or an
+      # EventQuery (logical OR of filters).
+      def build_context_query(filter_or_query)
+        where_sql, params = compile_conditions(filter_or_query)
+        ["SELECT * FROM events WHERE #{where_sql} ORDER BY sequence_number ASC", params]
+      end
+
+      # Returns [where_sql, params] for usage inside CTEs (no SELECT/ORDER BY).
+      def build_context_version_query(filter_or_query)
+        compile_conditions(filter_or_query)
+      end
+
+      # ------------------------------------------------------------------
+      # Internal helpers
+      # ------------------------------------------------------------------
+
+      def compile_conditions(filter_or_query)
+        sql_fragments = []
+        params = []
+
+        if filter_or_query.is_a?(EventStoreRuby::EventQuery)
+          filter_or_query.filters.each do |flt|
+            sql_fragments << single_filter_condition(flt, params)
+          end
+        else
+          sql_fragments << single_filter_condition(filter_or_query, params)
+        end
+
+        [sql_fragments.join(' OR '), params]
+      end
+
+      # Builds the SQL condition for a single EventFilter and pushes the
+      # corresponding parameters onto +params+ Array. Returns the condition
+      # string wrapped in parentheses.
+      def single_filter_condition(filter, params)
+        param_index = params.length + 1
+        params << pg_array_literal(filter.event_types)
+        condition = "event_type = ANY($#{param_index}::text[])"
+
+        if filter.payload_predicates&.any?
+          or_conditions = filter.payload_predicates.map do |predicate|
+            param_index = params.length + 1
+            params << predicate.to_json
+            "payload @> $#{param_index}"
+          end
+          condition += " AND (#{or_conditions.join(' OR ')})"
+        end
+
+        "(#{condition})"
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/postgres/schema.rb

@@ -0,0 +1,51 @@
+require 'pg'
+require 'uri'
+
+module EventStoreRuby
+  module Postgres
+    CREATE_EVENTS_TABLE = <<~SQL.freeze
+      CREATE TABLE IF NOT EXISTS events (
+        sequence_number BIGSERIAL PRIMARY KEY,
+        occurred_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        event_type TEXT NOT NULL,
+        payload JSONB NOT NULL
+      )
+    SQL
+
+    CREATE_EVENT_TYPE_INDEX = <<~SQL.freeze
+      CREATE INDEX IF NOT EXISTS idx_events_type ON events(event_type)
+    SQL
+
+    CREATE_OCCURRED_AT_INDEX = <<~SQL.freeze
+      CREATE INDEX IF NOT EXISTS idx_events_occurred_at ON events(occurred_at)
+    SQL
+
+    CREATE_PAYLOAD_GIN_INDEX = <<~SQL.freeze
+      CREATE INDEX IF NOT EXISTS idx_events_payload_gin ON events USING gin(payload)
+    SQL
+
+    module_function
+
+    def create_database_query(db_name)
+      # Safe quote identifier without needing PG C-extension helpers
+      quoted = '"' + db_name.gsub('"', '""') + '"'
+      "CREATE DATABASE #{quoted}"
+    end
+
+    # Replace DB name in a postgres connection url. naive but effective.
+    def change_database_in_connection_string(conn_str, new_db_name)
+      uri = URI.parse(conn_str)
+      uri.path = "/#{new_db_name}"
+      uri.to_s
+    end
+
+    def get_database_name_from_connection_string(conn_str)
+      uri = URI.parse(conn_str)
+      dbname = uri.path.start_with?('/') ? uri.path[1..] : uri.path
+      dbname.empty? ? nil : dbname
+    rescue URI::InvalidURIError
+      warn 'eventstore-stores-postgres-err01: Invalid connection string'
+      nil
+    end
+  end
+end 

data/lib/eventstore_ruby/postgres/transform.rb

@@ -0,0 +1,67 @@
+require 'json'
+
+module EventStoreRuby
+  module Postgres
+    module Transform
+      module_function
+
+      def deserialize_event(row)
+        raw_payload = row['payload'].is_a?(String) ? JSON.parse(row['payload']) : row['payload']
+        normalized = deep_snake_symbolize(raw_payload)
+        EventRecord.new(
+          sequence_number: row['sequence_number'].to_i,
+          timestamp: row['occurred_at'],
+          event_type: row['event_type'],
+          payload: normalized
+        )
+      end
+
+      # Recursively convert hash keys from camelCase / PascalCase strings to snake_case symbols
+      def deep_snake_symbolize(obj)
+        case obj
+        when Array
+          obj.map { |v| deep_snake_symbolize(v) }
+        when Hash
+          obj.each_with_object({}) do |(k, v), h|
+            snake = k.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+            h[snake] = deep_snake_symbolize(v)
+          end
+        else
+          obj
+        end
+      end
+
+      def map_records_to_events(result)
+        result.map { |row| deserialize_event(row) }
+      end
+
+      def extract_max_sequence_number(result)
+        return 0 if result.nil?
+
+        if result.respond_to?(:ntuples)
+          return 0 if result.ntuples.zero?
+          last_row = result[result.ntuples - 1]
+          return last_row['sequence_number'].to_i
+        elsif result.is_a?(Array)
+          return 0 if result.empty?
+          return result.last['sequence_number'].to_i
+        else
+          0
+        end
+      end
+
+      def prepare_insert_params(events, context_params)
+        event_types_arr = []
+        payload_strings = []
+        events.each do |event|
+          event_types_arr << event.event_type
+          payload_strings << event.payload.to_json
+        end
+
+        evtypes_literal = '{' + event_types_arr.map { |s| s.gsub('"', '""') }.join(',') + '}'
+        payload_literal = '{' + payload_strings.map { |j| '"' + j.gsub('"','\"').gsub('\\','\\\\') + '"' }.join(',') + '}'
+        context_params + [evtypes_literal, payload_literal]
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/postgres_event_store.rb

@@ -0,0 +1,111 @@
+require 'pg'
+require 'uri'
+require 'json'
+
+module EventStoreRuby
+  # Postgres-backed EventStore implementation.
+  class PostgresEventStore
+    NON_EXISTENT_EVENT_TYPE = "__NON_EXISTENT__#{rand(36**8).to_s(36)}".freeze
+
+    Options = Struct.new(:connection_string, :notifier, keyword_init: true)
+
+    def initialize(options = {})
+      opts = Options.new(options)
+      conn_str = opts.connection_string || ENV['DATABASE_URL']
+      raise 'eventstore-stores-postgres-err02: Connection string missing. DATABASE_URL environment variable not set.' unless conn_str
+
+      @database_name = Postgres.get_database_name_from_connection_string(conn_str)
+      raise "eventstore-stores-postgres-err03: Database name not found. Invalid connection string: #{conn_str}" unless @database_name
+
+      @conn_str = conn_str
+      @notifier = opts.notifier || MemoryEventStreamNotifier.new
+      @conn = PG.connect(conn_str)
+    end
+
+    # Returns QueryResult
+    def query(filter)
+      sql, params = Postgres::QueryBuilder.build_context_query(filter)
+      result = @conn.exec_params(sql, params)
+      QueryResult.new(
+        events: Postgres::Transform.map_records_to_events(result),
+        max_sequence_number: Postgres::Transform.extract_max_sequence_number(result)
+      )
+    end
+
+    def subscribe(&handle)
+      @notifier.subscribe(handle)
+    end
+
+    def append(events, filter = nil, expected_max_sequence_number: nil)
+      return if events.empty?
+
+      # Normalize the +filter+ to always be an EventQuery so the SQL helpers
+      # can work consistently. The TypeScript original expects an EventQuery
+      # (logical OR combination of EventFilter objects).
+
+      if filter.nil?
+        # No filter supplied – treat this as an "append to empty stream" use
+        # case.  Create a dummy filter that can never match so the CTE INSERT
+        # only succeeds when the table is still empty (max_seq = 0).
+        dummy_filter = EventStoreRuby.create_filter([NON_EXISTENT_EVENT_TYPE])
+        filter = EventStoreRuby.create_query([dummy_filter])
+        expected_max_sequence_number = 0
+      elsif filter.is_a?(EventFilter)
+        # Wrap single EventFilter in an EventQuery for uniform handling
+        filter = EventStoreRuby.create_query([filter])
+      end
+
+      # At this point +filter+ is guaranteed to be an EventQuery with at least
+      # one inner EventFilter, so no further guard needed.
+
+      raise 'eventstore-stores-postgres-err04: Expected max sequence number is required when a filter is provided!' if expected_max_sequence_number.nil?
+
+      cte_sql, context_params = Postgres::InsertBuilder.build_cte_insert_query(filter, expected_max_sequence_number)
+      params = Postgres::Transform.prepare_insert_params(events, context_params)
+
+      result = @conn.exec_params(cte_sql, params)
+      if result.ntuples.zero?
+        raise 'eventstore-stores-postgres-err05: Context changed: events were modified between query() and append()'
+      end
+
+      inserted_events = Postgres::Transform.map_records_to_events(result)
+      @notifier.notify(inserted_events)
+    end
+
+    # Creates the database (if possible) and tables/indexes
+    def initialize_database
+      create_database
+      create_table_and_indexes
+    end
+
+    def close
+      @notifier.close
+      @conn.close
+    end
+
+    private
+
+    def create_database
+      # Connect to postgres default db to create target database
+      admin_conn_str = Postgres.change_database_in_connection_string(@conn_str, 'postgres')
+      admin_conn = PG.connect(admin_conn_str)
+      begin
+        admin_conn.exec(Postgres.create_database_query(@database_name))
+        puts "Database created: #{@database_name}"
+      rescue PG::DuplicateDatabase
+        puts "eventstore-stores-postgres-err06: Database already exists: #{@database_name}"
+      ensure
+        admin_conn.close
+      end
+    end
+
+    def create_table_and_indexes
+      [Postgres::CREATE_EVENTS_TABLE,
+       Postgres::CREATE_EVENT_TYPE_INDEX,
+       Postgres::CREATE_OCCURRED_AT_INDEX,
+       Postgres::CREATE_PAYLOAD_GIN_INDEX].each do |sql|
+        @conn.exec(sql)
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/query_processor.rb

@@ -0,0 +1,66 @@
+module EventStoreRuby
+  # In-memory filtering helpers. Mirrors the behaviour of the TypeScript queryprocessor.
+  module QueryProcessor
+    module_function
+
+    # Public: returns an array of EventRecord that satisfy the given filter.
+    # events  - Array<EventRecord>
+    # filter  - EventFilter or nil
+    def process(events, filter = nil)
+      return events.dup if filter.nil? # return a shallow copy to avoid mutating original array
+
+      events.select { |event| check_event(event, filter) }
+    end
+
+    # Internal -----------------------------------------------------------------
+
+    def check_event(event, filter)
+      if filter.is_a?(EventQuery)
+        # Match if any inner filter matches
+        filter.filters.any? { |inner| check_event(event, inner) }
+      else
+        check_event_types(event.event_type, filter.event_types) &&
+          check_predicates(event.payload, filter.payload_predicates)
+      end
+    end
+
+    def check_event_types(event_type, event_types)
+      return true if event_types.nil? || event_types.empty?
+      event_types.include?(event_type)
+    end
+
+    def check_predicates(payload, predicates)
+      return true if predicates.nil? || predicates.empty?
+      predicates.any? { |predicate| subset?(payload, predicate) }
+    end
+
+    # Recursive inclusion check: is predicate a subset of payload?
+    def subset?(payload, predicate)
+      return true if predicate.nil?
+      return false if payload.nil?
+
+      # Primitive values
+      if !payload.is_a?(Array) && !payload.is_a?(Hash)
+        return payload == predicate
+      end
+
+      if predicate.is_a?(Array)
+        return false unless payload.is_a?(Array)
+        # Every element of predicate must match at least one element of payload.
+        return predicate.all? do |pred_elem|
+          payload.any? { |payload_elem| subset?(payload_elem, pred_elem) }
+        end
+      elsif predicate.is_a?(Hash)
+        return false unless payload.is_a?(Hash)
+        predicate.each do |key, pred_val|
+          return false unless payload.key?(key)
+          return false unless subset?(payload[key], pred_val)
+        end
+        true
+      else
+        # Non-Array, non-Hash but payload might be Array/Hash when predicate is primitive.
+        payload == predicate
+      end
+    end
+  end
+end 

data/lib/eventstore_ruby/query_result.rb

@@ -0,0 +1,13 @@
+module EventStoreRuby
+  # Result object returned from EventStore#query.
+  # Contains the matching events and the max sequence_number observed.
+  class QueryResult
+    attr_reader :events, :max_sequence_number
+
+    def initialize(events:, max_sequence_number: 0)
+      @events = events.freeze
+      @max_sequence_number = Integer(max_sequence_number)
+      freeze
+    end
+  end
+end 

data/lib/eventstore_ruby/read_write_lock_fifo.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module EventStoreRuby
+  # A deterministic FIFO read-write lock mirroring the original TypeScript logic
+  # but using explicit ticket numbers so Ruby thread scheduling cannot reorder
+  # requests. Readers queued before a writer are granted together; writers get
+  # exclusive access in the exact order they arrived.
+  class ReadWriteLockFIFO
+    Entry = Struct.new(:type, :ticket, :cond, :granted)
+
+    def initialize
+      @read_count = 0
+      @write_locked = false
+      @queue = []
+      @next_ticket = 0
+      @mutex = Mutex.new
+    end
+
+    # Acquire a read lock (blocks until granted)
+    def acquire_read
+      wait_for_grant(create_entry(:read))
+    end
+
+    # Acquire a write lock (blocks until granted)
+    def acquire_write
+      wait_for_grant(create_entry(:write))
+    end
+
+    def release_read
+      @mutex.synchronize do
+        raise 'No read locks to release' if @read_count.zero?
+        @read_count -= 1
+        process_queue if @read_count.zero?
+      end
+    end
+
+    def release_write
+      @mutex.synchronize do
+        raise 'No write lock to release' unless @write_locked
+        @write_locked = false
+        process_queue
+      end
+    end
+
+    private
+
+    def create_entry(type)
+      @mutex.synchronize do
+        ticket = (@next_ticket += 1)
+        entry = Entry.new(type, ticket, ConditionVariable.new, false)
+        @queue << entry
+        process_queue
+        entry
+      end
+    end
+
+    def wait_for_grant(entry)
+      @mutex.synchronize do
+        entry.cond.wait(@mutex) until entry.granted
+      end
+      nil
+    end
+
+    # Grant locks according to arrival order
+    def process_queue
+      # called with mutex held
+      loop do
+        break if @queue.empty?
+
+        head = @queue.first
+
+        if head.type == :write
+          # writers need exclusive access
+          break if @read_count.positive? || @write_locked
+
+          grant_write(head)
+          @queue.shift
+          break # single writer granted
+        else
+          # grant all contiguous readers at front
+          break if @write_locked
+
+          readers = take_contiguous_front_readers
+          break if readers.empty?
+
+          readers.each { |e| grant_read(e) }
+          break
+        end
+      end
+    end
+
+    def take_contiguous_front_readers
+      readers = []
+      while (entry = @queue.first) && entry.type == :read
+        readers << @queue.shift
+      end
+      readers
+    end
+
+    def grant_read(entry)
+      entry.granted = true
+      @read_count += 1
+      entry.cond.signal
+    end
+
+    def grant_write(entry)
+      entry.granted = true
+      @write_locked = true
+      entry.cond.signal
+    end
+  end
+end 

data/lib/eventstore_ruby/version.rb

@@ -0,0 +1,3 @@
+module EventStoreRuby
+  VERSION = '0.1.1'
+end 

data/lib/eventstore_ruby.rb

@@ -0,0 +1,21 @@
+module EventStoreRuby
+  require_relative 'eventstore_ruby/version'
+  require_relative 'eventstore_ruby/event'
+  require_relative 'eventstore_ruby/event_query'
+  require_relative 'eventstore_ruby/event_filter'
+  require_relative 'eventstore_ruby/query_result'
+  require_relative 'eventstore_ruby/filter'
+  require_relative 'eventstore_ruby/query_processor'
+  require_relative 'eventstore_ruby/read_write_lock_fifo'
+  require_relative 'eventstore_ruby/event_stream'
+  require_relative 'eventstore_ruby/event_subscription'
+  require_relative 'eventstore_ruby/memory_event_stream_notifier'
+  require_relative 'eventstore_ruby/memory_event_store'
+  require_relative 'eventstore_ruby/postgres/schema'
+  require_relative 'eventstore_ruby/postgres/query'
+  require_relative 'eventstore_ruby/postgres/insert'
+  require_relative 'eventstore_ruby/postgres/transform'
+  require_relative 'eventstore_ruby/postgres_event_store'
+
+  # Additional requires will be added here as we port more classes.
+end 

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: eventstore_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Manuel Ortega
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-08-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.18'
+description: A Ruby gem providing the same event-sourcing primitives and in-memory/Postgres
+  stores as the @eventstore-typescript package.
+email:
+- maoc84@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/eventstore_ruby.rb
+- lib/eventstore_ruby/event.rb
+- lib/eventstore_ruby/event_filter.rb
+- lib/eventstore_ruby/event_query.rb
+- lib/eventstore_ruby/event_stream.rb
+- lib/eventstore_ruby/event_subscription.rb
+- lib/eventstore_ruby/filter.rb
+- lib/eventstore_ruby/memory_event_store.rb
+- lib/eventstore_ruby/memory_event_stream_notifier.rb
+- lib/eventstore_ruby/postgres/insert.rb
+- lib/eventstore_ruby/postgres/query.rb
+- lib/eventstore_ruby/postgres/schema.rb
+- lib/eventstore_ruby/postgres/transform.rb
+- lib/eventstore_ruby/postgres_event_store.rb
+- lib/eventstore_ruby/query_processor.rb
+- lib/eventstore_ruby/query_result.rb
+- lib/eventstore_ruby/read_write_lock_fifo.rb
+- lib/eventstore_ruby/version.rb
+homepage: https://github.com/gazpachoteam/eventstore-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gazpachoteam/eventstore-ruby
+  changelog_uri: https://github.com/gazpachoteam/eventstore-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Ruby port of the @eventstore-typescript library.
+test_files: []