Class: RubyEventStore::Specification

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_event_store/specification.rb

Overview

Used for building and executing the query specification.

Constant Summary collapse

DEFAULT_BATCH_SIZE = 
100

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(reader, result = SpecificationResult.new) ⇒ Specification

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Specification.



10
11
12
13
 
# File 'lib/ruby_event_store/specification.rb', line 10

def initialize(reader, result = SpecificationResult.new)
  @reader = reader
  @result = result
end

Instance Attribute Details

#result ⇒ Object (readonly)

Returns the value of attribute result.



349
350
351
 
# File 'lib/ruby_event_store/specification.rb', line 349

def result
  @result
end

Instance Method Details

#as_at ⇒ Specification

Sets the order of time sorting using transaction time Find out more

Returns:



125
126
127
 
# File 'lib/ruby_event_store/specification.rb', line 125

def as_at
  Specification.new(reader, result.dup { |r| r.time_sort_by = :as_at })
end

#as_of ⇒ Specification

Sets the order of time sorting using validity time Find out more

Returns:



133
134
135
 
# File 'lib/ruby_event_store/specification.rb', line 133

def as_of
  Specification.new(reader, result.dup { |r| r.time_sort_by = :as_of })
end

#backward ⇒ Specification

Sets the order of reading events to descending (backward from the start). Find out more.

Returns:



149
150
151
 
# File 'lib/ruby_event_store/specification.rb', line 149

def backward
  Specification.new(reader, result.dup { |r| r.direction = :backward })
end

#between(time_range) ⇒ Specification

Limits the query to events within given time range. Find out more.

Parameters:

  • time_range (Range)

Returns:



113
114
115
116
117
118
119
 
# File 'lib/ruby_event_store/specification.rb', line 113

def between(time_range)
  if time_range.exclude_end?
    newer_than_or_equal(time_range.first).older_than(time_range.last)
  else
    newer_than_or_equal(time_range.first).older_than_or_equal(time_range.last)
  end
end

#count ⇒ Integer

Calculates the size of result set based on the specification build up to this point. Find out more.

Returns:

  • (Integer) —

    Number of events to read



212
213
214
 
# File 'lib/ruby_event_store/specification.rb', line 212

def count
  reader.count(result)
end

#each {|Event| ... } ⇒ Enumerator?

Executes the query based on the specification built up to this point. Yields events read from the store if block given. Otherwise, returns enumerable collection. Find out more.

Yields:

Returns:

  • (Enumerator, nil) —

    Enumerator is returned when block not given



181
182
183
184
185
 
# File 'lib/ruby_event_store/specification.rb', line 181

def each
  return to_enum unless block_given?

  each_batch { |batch| batch.each { |event| yield event } }
end

#each_batch {|Array<Event>| ... } ⇒ Enumerator?

Executes the query based on the specification built up to this point. Yields each batch of records that was retrieved from the store. Find out more.

Yields:

  • (Array<Event>) —

    batch of events

Returns:

  • (Enumerator, nil) —

    Enumerator is returned when block not given



169
170
171
172
173
 
# File 'lib/ruby_event_store/specification.rb', line 169

def each_batch
  return to_enum(:each_batch) unless block_given?

  reader.each(in_batches(result.batch_size).result) { |batch| yield batch }
end

#event(event_id) ⇒ Event?

Reads single event from repository. Returns the event with specified id or nil if event is not found in specified collection of events. Find out more.

Returns:



324
325
326
 
# File 'lib/ruby_event_store/specification.rb', line 324

def event(event_id)
  reader.one(read_first.with_id([event_id]).result)
end

#event!(event_id) ⇒ Event

Reads single existing event from repository. Returns the event with specified id or raises [EventNotFound] error if event is not found in specified collection of events. Find out more.

Returns:



334
335
336
 
# File 'lib/ruby_event_store/specification.rb', line 334

def event!(event_id)
  event(event_id) or raise EventNotFound.new(event_id)
end

#events(event_ids) {|Event| ... } ⇒ Enumerator

Reads all events of given ids from repository. Yields each event (found by id in specified collection of events) read from the store if block given. Otherwise, returns enumerable collection. Find out more.

Yields:

Returns:

  • (Enumerator) —

    Enumerator is returned when block not given



345
346
347
 
# File 'lib/ruby_event_store/specification.rb', line 345

def events(event_ids)
  with_id(event_ids).each
end

#first ⇒ Event?

Executes the query based on the specification built up to this point. Returns the first event in specified collection of events. Find out more.

Returns:



278
279
280
 
# File 'lib/ruby_event_store/specification.rb', line 278

def first
  reader.one(read_first.result)
end

#forward ⇒ Specification

Sets the order of reading events to ascending (forward from the start). Find out more.

Returns:



141
142
143
 
# File 'lib/ruby_event_store/specification.rb', line 141

def forward
  Specification.new(reader, result.dup { |r| r.direction = :forward })
end

#from(start) ⇒ Specification

Limits the query to events before or after another event. Find out more.

Parameters:

  • start (String) —

    id of event to start reading from.

Returns:

Raises:



29
30
31
32
 
# File 'lib/ruby_event_store/specification.rb', line 29

def from(start)
  raise InvalidPageStart if start.nil? || start.empty?
  Specification.new(reader, result.dup { |r| r.start = start })
end

#in_batches(batch_size = DEFAULT_BATCH_SIZE) ⇒ Specification

Specifies that events should be obtained in batches. Find out more.

Looping through a collection of events from the store can be inefficient since it will try to instantiate all the events at once.

In that case, batch processing methods allow you to work with the records in batches, thereby greatly reducing memory consumption.

Parameters:

  • batch_size (Integer) (defaults to: DEFAULT_BATCH_SIZE) —

    number of events to read in a single batch

Returns:



238
239
240
241
242
243
244
245
246
 
# File 'lib/ruby_event_store/specification.rb', line 238

def in_batches(batch_size = DEFAULT_BATCH_SIZE)
  Specification.new(
    reader,
    result.dup do |r|
      r.read_as = :batch
      r.batch_size = batch_size
    end,
  )
end

#in_batches_of(batch_size = DEFAULT_BATCH_SIZE) ⇒ Object 



248
249
250
251
252
253
254
255
 
# File 'lib/ruby_event_store/specification.rb', line 248

def in_batches_of(batch_size = DEFAULT_BATCH_SIZE)
  warn <<~EOW
    RubyEventStore::Specification#in_batches_of is deprecated and will be removed in the next major release.

    Use #in_batches instead.
  EOW
  in_batches(batch_size)
end

#last ⇒ Event?

Executes the query based on the specification built up to this point. Returns the last event in specified collection of events. Find out more.

Returns:



287
288
289
 
# File 'lib/ruby_event_store/specification.rb', line 287

def last
  reader.one(read_last.result)
end

#limit(count) ⇒ Specification

Limits the query to specified number of events. Find out more.

Parameters:

  • count (Integer) —

    maximal number of events to retrieve

Returns:

Raises:



158
159
160
161
 
# File 'lib/ruby_event_store/specification.rb', line 158

def limit(count)
  raise InvalidPageSize unless count && count > 0
  Specification.new(reader, result.dup { |r| r.count = count })
end

#map(&block) ⇒ Array

Executes the query based on the specification built up to this point and maps the result using provided block. Find out more.

Returns:

  • (Array) —

    of mapped result

Raises:

  • (ArgumentError) 


192
193
194
195
 
# File 'lib/ruby_event_store/specification.rb', line 192

def map(&block)
  raise ArgumentError.new("Block must be given") unless block_given?
  each.map(&block)
end

#newer_than(time) ⇒ Specification

Limits the query to events that occurred after given time. Find out more.

Parameters:

  • time (Time)

Returns:

Raises:

  • (ArgumentError) 


81
82
83
84
85
86
87
88
89
90
 
# File 'lib/ruby_event_store/specification.rb', line 81

def newer_than(time)
  raise ArgumentError unless time.respond_to?(:to_time)
  Specification.new(
    reader,
    result.dup do |r|
      r.newer_than_or_equal = nil
      r.newer_than = time
    end,
  )
end

#newer_than_or_equal(time) ⇒ Specification

Limits the query to events that occurred on or after given time. Find out more.

Parameters:

  • time (Time)

Returns:

Raises:

  • (ArgumentError) 


97
98
99
100
101
102
103
104
105
106
 
# File 'lib/ruby_event_store/specification.rb', line 97

def newer_than_or_equal(time)
  raise ArgumentError unless time.respond_to?(:to_time)
  Specification.new(
    reader,
    result.dup do |r|
      r.newer_than_or_equal = time
      r.newer_than = nil
    end,
  )
end

#of_type(*types) ⇒ Specification

Limits the query to certain event type(s). Find out more.

Returns:



296
297
298
 
# File 'lib/ruby_event_store/specification.rb', line 296

def of_type(*types)
  Specification.new(reader, result.dup { |r| r.with_types = types.flatten })
end

#of_types(*types) ⇒ Object 



300
301
302
303
304
305
306
307
 
# File 'lib/ruby_event_store/specification.rb', line 300

def of_types(*types)
  warn <<~EOW
    RubyEventStore::Specification#of_types is deprecated and will be removed in the next major release.

    Use #of_type instead.
  EOW
  of_type(*types)
end

#older_than(time) ⇒ Specification

Limits the query to events that occurred before given time. Find out more.

Parameters:

  • time (Time)

Returns:

Raises:

  • (ArgumentError) 


49
50
51
52
53
54
55
56
57
58
 
# File 'lib/ruby_event_store/specification.rb', line 49

def older_than(time)
  raise ArgumentError unless time.respond_to?(:to_time)
  Specification.new(
    reader,
    result.dup do |r|
      r.older_than = time
      r.older_than_or_equal = nil
    end,
  )
end

#older_than_or_equal(time) ⇒ Specification

Limits the query to events that occurred on or before given time. Find out more.

Parameters:

  • time (Time)

Returns:

Raises:

  • (ArgumentError) 


65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ruby_event_store/specification.rb', line 65

def older_than_or_equal(time)
  raise ArgumentError unless time.respond_to?(:to_time)
  Specification.new(
    reader,
    result.dup do |r|
      r.older_than = nil
      r.older_than_or_equal = time
    end,
  )
end

#read_first ⇒ Specification

Specifies that only first event should be read. Find out more.

Returns:



261
262
263
 
# File 'lib/ruby_event_store/specification.rb', line 261

def read_first
  Specification.new(reader, result.dup { |r| r.read_as = :first })
end

#read_last ⇒ Specification

Specifies that only last event should be read. Find out more.

Returns:



269
270
271
 
# File 'lib/ruby_event_store/specification.rb', line 269

def read_last
  Specification.new(reader, result.dup { |r| r.read_as = :last })
end

#reduce(accumulator = nil, &block) ⇒ Object

Reduces the results of the query based on the specification built up to this point result using provided block. Find out more.

Parameters:

  • accumulator (defaults to: nil) —

    starting state for reduce operation

Returns:

  • reduce result as defined by block given

Raises:

  • (ArgumentError) 


203
204
205
206
 
# File 'lib/ruby_event_store/specification.rb', line 203

def reduce(accumulator = nil, &block)
  raise ArgumentError.new("Block must be given") unless block_given?
  each.reduce(accumulator, &block)
end

#stream(stream_name) ⇒ Specification

Limits the query to certain stream. Find out more.

Parameters:

  • stream_name (String) —

    name of the stream to get events from

Returns:



20
21
22
 
# File 'lib/ruby_event_store/specification.rb', line 20

def stream(stream_name)
  Specification.new(reader, result.dup { |r| r.stream = Stream.new(stream_name) })
end

#to(stop) ⇒ Specification

Limits the query to events before or after another event. Find out more.

Parameters:

  • stop (String) —

    id of event to start reading from.

Returns:

Raises:



39
40
41
42
 
# File 'lib/ruby_event_store/specification.rb', line 39

def to(stop)
  raise InvalidPageStop if stop.nil? || stop.empty?
  Specification.new(reader, result.dup { |r| r.stop = stop })
end

#to_a ⇒ Array<Event>

Executes the query based on the specification built up to this point. Returns array of domain events. Find out more.

Returns:



221
222
223
 
# File 'lib/ruby_event_store/specification.rb', line 221

def to_a
  each.to_a
end

#with_id(event_ids) ⇒ Specification

Limits the query to certain events by given even ids. Find out more.

Parameters:

  • event_ids (Array(String)) —

    ids of event to look for.

Returns:



314
315
316
 
# File 'lib/ruby_event_store/specification.rb', line 314

def with_id(event_ids)
  Specification.new(reader, result.dup { |r| r.with_ids = event_ids })
end