New docs version — 2.17.0

Author: mostlyobvious

railseventstore.org/versioned_docs/version-2.17.0/advanced-topics/bi-temporal.md

@@ -0,0 +1,38 @@
+---
+title: Bi-Temporal EventSourcing
+---
+
+Sometimes in the Event-Sourced world knowing when a specific event happened is not enough. In some business cases, there's also a necessity to know at which point in time a particular event was valid.
+This approach is called Bi-Temporal EventSourcing.
+
+## Example
+
+Consider you're an HR person responsible for dealing with employee salaries. Your tool of choice to gather the data is an Excel sheet and email.
+When you gather the information from managers, you put them into an Excel sheet and mail them to payroll. Payroll is taking care of the money getting into employees' bank accounts. You also import the Excel sheet into your HR system, which happens to be Event Sourced.
+
+Usually, things go great and we build our stream of salary-tracking events like this:
+![BiTemporalEventSourcingWhenThingsGoSmoothly](/images/bi_temporal_event_sourcing_when_things_go_smoothly.jpg)
+However an error might happen. The error might happen when gathering the data from manager or putting it into an Excel sheet.
+
+Instead of asking a developer to modify the event data (events should always be immutable!), you could use a bi-temporal event. Consider the example below:
+![BiTemporalEventSourcingValidAt](/images/bi_temporal_valid_at_event_sourcing.jpg)
+In this example, the salary was raised on January 1, 2020, and it was also paid out on February 1, 2020. Then the mistake was detected. Instead of modifying the history of events, the new one has been published. The new event describes the proper value of the salary and specifies when the salary is valid.
+
+## Usage
+
+If you decide to use the Bi-Temporal EventSourcing approach for a stream, you have to include the `valid_at` property to the event's metadata.
+`valid_at` describes when the event was actually valid, despite when it occurred. Such an event is also often called a Retroactive event.
+
+```ruby
+event_store.publish(Event.new(data: {}, metadata: {valid_at: Time.utc(2020,1,1)}))
+```
+
+When reading a stream with bi-temporal events you can either read the events by using:
+
+* `as_at` scope, which orders events by `timestamp`, which is the time of appending the event to the stream
+* `as_of` scope, which orders events by `valid_at`, which is the time of when the event was actually valid
+
+```ruby
+event_store.read.stream("my-stream").as_at.to_a # ordered by time of appending (timestamp)
+event_store.read.stream("my-stream").as_of.to_a # ordered by validity time (valid_at)
+```

railseventstore.org/versioned_docs/version-2.17.0/advanced-topics/command-bus.md

@@ -0,0 +1,87 @@
+---
+title: Command Bus
+---
+
+_Command Pattern - decoupling what is done from who does it._
+
+## Usage
+
+### Registering commands and their handlers
+
+```ruby
+require "arkency/command_bus"
+
+command_bus = Arkency::CommandBus.new
+register = command_bus.method(:register)
+
+{ FooCommand => FooService.new(event_store: event_store).method(:foo), BarCommand => BarService.new }.map(&register)
+```
+
+### Invoking command bus with a command
+
+```ruby
+command_bus.(FooCommand.new)
+```
+
+Will call `FooService#foo` method with the command you just passed.
+
+## New instance of a service for every invoked command
+
+If you need a new instance of a service, every time it is called with a command, or you want to lazily load the responsible services, use `Proc` when registering commands.
+
+```ruby
+command_bus = Arkency::CommandBus.new
+command_bus.register(FooCommand, ->(foo_cmd) { FooService.new(dependency: dep).foo(foo_cmd) })
+command_bus.register(BarCommand, ->(bar_cmd) { BarService.new.call(bar_cmd) })
+```
+
+## Working with Rails development mode
+
+In Rails `development` mode when you change a registered class, it is reloaded, and a new class with same name is constructed.
+
+```ruby
+a = User
+a.object_id
+# => 40737760
+
+reload!
+# Reloading...
+
+b = User
+b.object_id
+# => 48425300
+
+h = { a => 1, b => 2 }
+h[User]
+# => 2
+
+a == b
+# => false
+```
+
+so your `Hash` with mapping from command class to service may not find the new version of reloaded class.
+
+To workaround this problem you can use [`to_prepare`](http://api.rubyonrails.org/classes/Rails/Railtie/Configuration.html#method-i-to_prepare) callback which is executed before every code reload in development, and once in production.
+
+```ruby
+config.to_prepare do
+  config.command_bus = Arkency::CommandBus.new
+  register = command_bus.method(:register)
+
+  { FooCommand => FooService.new(event_store: event_store).method(:foo), BarCommand => BarService.new }.map(&register)
+end
+```
+
+and call it with
+
+```ruby
+Rails.configuration.command_bus.call(FooCommand.new)
+```
+
+## Convenience alias
+
+```ruby
+require "arkency/command_bus/alias"
+```
+
+From now on you can use top-level `CommandBus` instead of `Arkency::CommandBus`.

railseventstore.org/versioned_docs/version-2.17.0/advanced-topics/custom-repository.md

@@ -0,0 +1,81 @@
+---
+title: Custom Repository
+---
+
+## Installation with Bundler
+
+By default RailsEventStore will use the ActiveRecord event repository. If you want to use another event repository without loading unnecessary ActiveRecord dependency, you'll need to do:
+
+```ruby
+gem "rails_event_store", require: "rails_event_store/all"
+gem "your_custom_repository"
+```
+
+After running `bundle install`, Rails Event Store should be ready to be used.
+See custom repository README to learn how to setup its data store.
+
+## Configure custom repository
+
+```ruby
+Rails.application.configure do
+  config.to_prepare do
+    Rails.configuration.event_store = RailsEventStore::Client.new(repository: YourCustomRepository.new)
+  end
+end
+```
+
+## Community event repositories
+
+Those repositories were written by community members and are not guaranteed to be up to date with latest Rails event store.
+
+- [rails_event_store_mongoid](https://github.com/gottfrois/rails_event_store_mongoid) by [Pierre-Louis Gottfrois](https://github.com/gottfrois)
+
+## Writing your own repository
+
+If you want to write your own repository, we provide [a suite of tests that you can re-use](https://github.com/RailsEventStore/rails_event_store/blob/master/ruby_event_store/lib/ruby_event_store/spec/event_repository_lint.rb). Just [require](https://github.com/RailsEventStore/rails_event_store/blob/a6ffb8a535373023296222bbbb5dd6ee131a6792/rails_event_store_active_record/spec/event_repository_spec.rb#L3) and [include it](https://github.com/RailsEventStore/rails_event_store/blob/a6ffb8a535373023296222bbbb5dd6ee131a6792/rails_event_store_active_record/spec/event_repository_spec.rb#L26) in your repository spec. Make sure to meditate on which [expected_version option](./../core-concepts/expected-version/) you are going to support and how.
+
+## Using RubyEventStore::InMemoryRepository for faster tests
+
+RubyEventStore comes with `RubyEventStore::InMemoryRepository` that you can use in tests instead of the default one. `InMemoryRepository` does not persist events but offers the same characteristics as `RailsEventStoreActiveRecord::EventRepository`. It is tested with the same test suite and raises identical exceptions.
+
+```ruby
+RSpec.configure do |c|
+  c.around(:each)
+    Rails.configuration.event_store = RailsEventStore::Client.new(
+      repository: RubyEventStore::InMemoryRepository.new
+    )
+    # add subscribers here
+  end
+end
+```
+
+If you want even faster tests you can additionally skip event's serialization.
+
+```ruby
+RSpec.configure do |c|
+  c.around(:each)
+    Rails.configuration.event_store = RailsEventStore::Client.new(
+      repository: RubyEventStore::InMemoryRepository.new,
+      mapper: RubyEventStore::Mappers::NullMapper.new,
+    )
+    # add subscribers here
+  end
+end
+```
+
+We don't recommend using `InMemoryRepository` in production even if you don't need to persist events because the repository keeps all published events in memory. This is acceptable in testing because you can throw the instance away for every test and garbage collector reclaims the memory. In production, your memory would keep growing until you restart the application server.
+
+## Using Ruby Object Mapper (ROM) for SQL without ActiveRecord or Rails
+
+RubyEventStore comes with `RubyEventStore::ROM::EventRepository` that you can use with a SQL database without requiring ActiveRecord or when not using Rails altogether. It is tested with the same test suite as the ActiveRecord implementation and raises identical exceptions.
+
+See [Using Ruby Event Store without Rails](./without-rails) for information on how to use ROM (and Sequel).
+
+## Using PgLinearizedEventRepository for linearized writes
+
+`rails_event_store_active_record` comes with additional version of repository named `RailsEventStoreActiveRecord::PgLinearizedEventRepository`.
+It is almost the same as regular active record repository, but has linearized writes to the database and is only restricted to work in `PostgreSQL` database (as the name suggests).
+
+There are usecases, where you may want to use event store as a queue. For example, you may want to build some read models on separate server and in order to build them correctly, you need to process the facts in the order they were written. In general case it is not that easy, because SQL databases auto-increment rows in the moment of insertion, not commit. So that allows event numbered 42 be already committed, but event numbered 40 still be somewhere in transaction, not readable from outside world. Therefore, the easiest implementation of such queue: "Remember the last processed event id" would not work in that case.
+
+There are many subtleties in this topic, but one of the simplest solutions is to linearize all writes to event store. That's what `RailsEventStoreActiveRecord::PgLinearizedEventRepository` is for. Of course by linearizing your writes you lose performance and you make it impossible to scale your application above certain level. As usually, your mileage may vary, but such solution is undoubtedly the simplest and _good enough_ in some usecases.

railseventstore.org/versioned_docs/version-2.17.0/advanced-topics/event-serialization-formats.md

@@ -0,0 +1,126 @@
+---
+title: Event serialization formats
+---
+
+By default RailsEventStore will use `YAML` as a
+serialization format. The reason is that `YAML` is available out of box
+and can serialize and deserialize data types which are not easily
+handled in other formats.
+
+However, if you don't like `YAML` or you have different needs you can
+choose to use different serializers or even replace mappers entirely.
+
+## Configuring a different serializer
+
+You can pass a different `serializer` as a dependency when [instantiating
+the client](../getting-started/install).
+
+Here is an example on how to configure RailsEventStore to serialize
+events' `data` and `metadata` using `Marshal`.
+
+```ruby
+# config/environments/*.rb
+
+Rails.application.configure do
+  config.to_prepare do
+    Rails.configuration.event_store = RailsEventStore::Client.new(
+      repository: RailsEventStoreActiveRecord::EventRepository.new(serializer: Marshal)
+    )
+  end
+end
+```
+
+The provided `serializer` must respond to `load` and `dump`.
+
+Serialization is needed not only when writing to and reading from storage, but also when scheduling events for background processing by async handlers:
+
+```ruby
+Rails.configuration.event_store = RailsEventStore::Client.new(
+  message_broker: RubyEventStore::Broker.new( 
+    dispatcher: RubyEventStore::ComposedDispatcher.new(
+      RailsEventStore::AfterCommitAsyncDispatcher.new(scheduler: ActiveJobScheduler.new(serializer: Marshal)),
+      RubyEventStore::Dispatcher.new
+    )
+  )
+)
+```
+
+```ruby
+class SomeHandler < ActiveJob::Base
+  include RailsEventStore::AsyncHandler.with(serializer: Marshal)
+
+  def perform(event)
+    # ...
+  end
+end
+```
+
+## Configuring for Postgres JSON/B data type
+
+In Postgres database, you can store your events data and metadata in json or jsonb format.
+
+To generate migration containing event table schemas run
+
+```console
+$ rails generate rails_event_store_active_record:migration --data-type=jsonb
+```
+
+Next, configure your event store client to the JSON client:
+
+```ruby
+Rails.configuration.event_store = RailsEventStore::JSONClient.new
+```
+
+If you need additional configuration beyond the included JSON client, continue from here. In your `RailsEventStore::Client` initialization, set repository serialization to ` RailsEventStoreActiveRecord::EventRepository.new(serializer: RubyEventStore::NULL)`
+
+```ruby
+# config/environments/*.rb
+
+Rails.application.configure do
+  config.to_prepare do
+    Rails.configuration.event_store = RailsEventStore::Client.new(
+      repository: RailsEventStoreActiveRecord::EventRepository.new(serializer: RubyEventStore::NULL)
+    )
+  end
+end
+```
+
+Using the `RubyEventStore::NULL` serializer will prevent the event store from serializing the event data and metadata. This is necessary because the Active Record will handle serialization before putting the data into the database. And will do otherwise when reading. Database itself expect data to be json already.
+
+<div class="px-4 py-1 text-blue-600 bg-blue-100 border-l-4 border-blue-500" role="alert">
+  <p class="text-base font-bold">Note that <code>JSON</code> converts symbols to strings. Ensure your code accounts for this when retrieving events.</p>
+  
+```ruby
+JSON.load(JSON.dump({foo: :bar}))
+=> {"foo"=>"bar"}
+```
+
+One way to approach this is to have your own event adapter, specific for the project you're working on.
+
+```ruby
+class MyEvent < RailsEventStore::Event
+  def data
+    ActiveSupport::HashWithIndifferentAccess.new(super)
+  end
+end
+
+OrderPlaced = Class.new(MyEvent)
+```
+
+
+That shields you from data keys being transformed from symbols into strings. It doesn't do anything with data values associated to those keys.
+
+```ruby
+event_store.publish(OrderPlaced.new(event_id: 'e34fc19a-a92f-4c21-8932-a10f6fb2602b', data: { foo: :bar }))
+event = event_store.read.event('e34fc19a-a92f-4c21-8932-a10f6fb2602b')
+
+event.data[:foo]
+\# => "bar"
+
+event.data['foo']
+\# => "bar"
+```
+
+Another way to achieve that could be define your own <a href="../advanced-topics/mappers#custom-mapper">custom mapper and transformation</a>
+
+</div>