pg_eventstore 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 330df61b6d77cd8211f42750b42eaef7165c66a22fc1f33a6a138248fe8beb9b
+  data.tar.gz: 021b611a40e2392020600ad4650467e14113295bd332de5d42a16f2354e38561
+SHA512:
+  metadata.gz: 200fd40463fe2fc715c0680dff345a333c39aa1ef280b2654df9f69973ab5c34d0698eb7d6ef473b04bd1085b0c646ca05910157e8c1f22d639bfcd30b29d3ad
+  data.tar.gz: 1e059c402affcac9ab5666e2263c953c27bdb9648c75dfe9a16bfa942c16cbd4429e3b1bc2fc717ee8281167a241d3be89a5e67da7f93e2bf3c9ec6d82056793

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [0.1.0] - 2023-12-12
+
+Initial release.
+
+- Implement Read command
+- Implement AppendToStream command
+- Implement Multiple command

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at intale.a@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Ivan Dzyzenko
+
+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,90 @@
+# PgEventstore
+
+Implements database and API to store and read events in event sourced systems.
+
+## Requirements
+
+`pg_eventstore` requires a PostgreSQL database with jsonb data type support (which means you need to have v9.2+). However it is recommended to use a non [EOL](https://www.postgresql.org/support/versioning/) PostgreSQL version, because the development of this gem is targeted at current PostgreSQL versions.
+`pg_eventstore` requires ruby v3+. The development of this gem is targeted at [current](https://endoflife.date/ruby) ruby versions.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add pg_eventstore
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install pg_eventstore
+
+## Usage
+
+Before you start, make sure you created a database where events will be stored. A PostgreSQL user must be a superuser to be able to create tables, indexes, primary/foreign keys, etc. Please don't use an existing database/user for this purpose. Example of creating such database and user:
+
+```bash
+sudo -u postgres createuser pg_eventstore --superuser
+sudo -u postgres psql --command="CREATE DATABASE eventstore OWNER pg_eventstore"
+sudo -u postgres psql --command="CREATE DATABASE eventstore OWNER pg_eventstore"
+```
+
+If necessary - adjust your `pg_hba.conf` to allow `pg_eventstore` user to connect to your PostgreSQL server. 
+
+Next step will be configuring a db connection. Please check the **Configuration** chapter bellow to find out how to do it.
+
+After the db connection is configured, it is time to create necessary database objects. Please include this line into your `Rakefile`:
+
+```ruby
+load "pg_eventstore/tasks/setup.rake"
+```
+
+This will include necessary rake tasks. You can now run 
+```bash
+bundle exec rake pg_eventstore:create
+```
+to create necessary database objects. After this step your `pg_eventstore` is ready to use.
+
+Documentation chapters:
+
+- [Configuration](docs/configuration.md)
+- [Events and streams definitions](docs/events_and_streams.md)
+- [Appending events](docs/appending_events.md)
+- [Reading events](docs/reading_events.md)
+- [Writing middlewares](docs/writing_middleware.md)
+- [How to make multiple commands atomic](docs/multiple_commands.md)
+
+## Development
+
+After checking out the repo, run:
+- `bundle` to install dependencies
+- `docker-compose up` to start dev/test services
+- `bin/setup_db` to create/re-create development and test databases, tables and related objects 
+
+Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Benchmarks
+
+There is a script to help you to tests the `pg_eventstore` implementation performance. You can run it using next command:
+
+```bash
+./benchmark/run
+```
+
+### Publishing new version
+
+1. Push commit with updated `version.rb` file to the `release` branch. The new version will be automatically pushed to [rubygems](https://rubygems.org).
+2. Create release on GitHub.
+3. Update `CHANGELOG.md`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/pg_eventstore. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yousty/pg_eventstore/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PgEventstore project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yousty/pg_eventstore/blob/master/CODE_OF_CONDUCT.md).

data/db/extensions.sql

@@ -0,0 +1,2 @@
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS pgcrypto;

data/db/indexes.sql

@@ -0,0 +1,13 @@
+CREATE UNIQUE INDEX idx_streams_context_and_stream_name_and_stream_id ON public.streams USING btree (context, stream_name, stream_id);
+-- This index is used when searching by the specific stream and event's types
+CREATE INDEX idx_events_stream_id_and_revision_and_type ON public.events USING btree (stream_id, stream_revision, type);
+
+-- This index is used when searching by "all" stream using stream's attributes(context, stream_name, stream_id) and
+-- event's types. PG's query planner picks this index when none of the given event's type exist
+CREATE INDEX idx_events_type_and_stream_id_and_position ON public.events USING btree (type, stream_id, global_position);
+
+-- This index is used when searching by "all" stream using stream's attributes(context, stream_name, stream_id) and
+-- event's types. PG's query planner picks this index when some of the given event's types exist
+CREATE INDEX idx_events_position_and_type ON public.events USING btree (global_position, type);
+
+CREATE INDEX idx_events_link_id ON public.events USING btree (link_id);

data/db/primary_and_foreign_keys.sql

@@ -0,0 +1,11 @@
+ALTER TABLE ONLY public.streams
+    ADD CONSTRAINT streams_pkey PRIMARY KEY (id);
+ALTER TABLE ONLY public.events
+    ADD CONSTRAINT events_pkey PRIMARY KEY (id);
+
+ALTER TABLE ONLY public.events
+    ADD CONSTRAINT events_stream_fk FOREIGN KEY (stream_id)
+        REFERENCES public.streams (id) ON DELETE CASCADE;
+ALTER TABLE ONLY public.events
+    ADD CONSTRAINT events_link_fk FOREIGN KEY (link_id)
+        REFERENCES public.events (id) ON DELETE CASCADE;

data/db/tables.sql

@@ -0,0 +1,21 @@
+CREATE TABLE public.streams
+(
+    id              bigserial         NOT NULL,
+    context         character varying NOT NULL,
+    stream_name     character varying NOT NULL,
+    stream_id       character varying NOT NULL,
+    stream_revision int DEFAULT -1    NOT NULL
+);
+
+CREATE TABLE public.events
+(
+    id              uuid                        NOT NULL DEFAULT public.gen_random_uuid(),
+    stream_id       bigint                      NOT NULL,
+    type            character varying           NOT NULL,
+    global_position bigserial                   NOT NULL,
+    stream_revision int                         NOT NULL,
+    data            jsonb                       NOT NULL DEFAULT '{}'::jsonb,
+    metadata        jsonb                       NOT NULL DEFAULT '{}'::jsonb,
+    link_id         uuid,
+    created_at      timestamp without time zone NOT NULL DEFAULT now()
+);

data/docs/appending_events.md

@@ -0,0 +1,170 @@
+# Appending Events
+
+## Append your first event
+
+The easiest way to append an event is to create an event object and a stream object and call the client's `#append_to_stream` method.
+
+```ruby
+require 'securerandom'
+
+class SomethingHappened < PgEventstore::Event
+end
+
+event = SomethingHappened.new(data: { user_id: SecureRandom.uuid, title: "Something happened" })
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.append_to_stream(stream, event)
+# => #<SomethingHappened:0x0 @context="MyAwesomeContext", @created_at=2023-11-30 14:47:31.296229 UTC, @data={"title"=>"Something happened", "user_id"=>"be52a81c-ad5b-4cfd-a039-0b7276974e6b"}, @global_position=7, @id="0b01137b-bdd8-4f0d-8ccf-f8c959e3a324", @link_id=nil, @metadata={}, @stream_id="f37b82f2-4152-424d-ab6b-0cc6f0a53aae", @stream_name="SomeStream", @stream_revision=0, @type="SomethingHappened">
+```
+
+## Appending multiple events
+
+You can pass an array of events to the `#append_to_stream` method. This way events will be appended one-by-one. **This operation is atomic and it guarantees that events are added to the stream in the given order.**
+
+```ruby
+require 'securerandom'
+
+class SomethingHappened < PgEventstore::Event
+end
+
+event1 = SomethingHappened.new(data: { user_id: SecureRandom.uuid, title: "Something happened 1" })
+event2 = SomethingHappened.new(data: { user_id: SecureRandom.uuid, title: "Something happened 2" })
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.append_to_stream(stream, [event1, event2])
+```
+
+### Duplicated event id
+
+If two events with the same id are appended to any stream - `pg_eventstore` will only append one event, and the second command will raise an error.
+
+```ruby
+class SomethingHappened < PgEventstore::Event
+end
+
+event = SomethingHappened.new(id: SecureRandom.uuid)
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.append_to_stream(stream, event)
+# Raises PG::UniqueViolation error
+PgEventstore.client.append_to_stream(stream, event)
+```
+
+## Handling concurrency
+
+When appending events to a stream you can supply a stream state or stream revision. You can use this to tell `pg_eventstore` what state or version you expect the stream to be in when you append. If the stream isn't in that state then an exception will be thrown.
+
+For example if we try to append two records expecting both times that the stream doesn't exist we will get an exception on the second:
+
+```ruby
+require 'securerandom'
+
+class SomethingHappened < PgEventstore::Event
+end
+
+event1 = SomethingHappened.new(data: { foo: :bar })
+event2 = SomethingHappened.new(data: { bar: :baz })
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: SecureRandom.uuid)
+
+# Successfully appends an event
+PgEventstore.client.append_to_stream(stream, event1, options: { expected_revision: :no_stream })
+# Raises PgEventstore::WrongExpectedRevisionError error
+PgEventstore.client.append_to_stream(stream, event2, options: { expected_revision: :no_stream })
+```
+
+Here are possible values of `:expected_revision` option:
+
+- `:any`. Doesn't perform any checks. This is the default.
+- `:no_stream`. Expects a stream to be absent when appending an event
+- `:stream_exists`. Expects a stream to be present when appending an event
+- a revision number(Integer). Expects a stream to be in the given revision.
+
+This check can be used to implement optimistic concurrency. When you retrieve a stream, you take note of the current version number, then when you save it back you can determine if somebody else has modified the record in the meantime.
+
+```ruby
+require 'securerandom'
+
+class SomethingHappened < PgEventstore::Event
+end
+
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: SecureRandom.uuid)
+event1 = SomethingHappened.new(data: { foo: :bar })
+event2 = SomethingHappened.new(data: { bar: :baz })
+
+# Pre-populate stream with some event
+PgEventstore.client.append_to_stream(stream, event1)
+# Get the revision number of latest event
+revision = PgEventstore.client.read(stream, options: { max_count: 1, direction: 'Backwards' }).first.stream_revision
+# Expected revision matches => will succeed
+PgEventstore.client.append_to_stream(stream, event2, options: { expected_revision: revision })
+# Will fail with PgEventstore::WrongExpectedRevisionError error, because stream version is 1 now, but :expected_revision 
+# option is 0
+PgEventstore.client.append_to_stream(stream, event2, options: { expected_revision: revision })
+```
+
+### What to do when a PgEventstore::WrongExpectedRevisionError error is risen?
+
+Imagine the following scenario:
+1. You load events of a stream to build the state of your business object represented by the stream.
+2. You check your business rules to see if you can change that object's state the way you want to change it.
+3. If no business rules have been violated, you have the go to publish the event representing the state change.
+4. To make sure the new event will follow the last event you used to build your object state, you retrieve that last event's revision and increase it by one. You now have the expected revision for the event to be published.
+5. You publish the event but retrieve a `WrongExpectedRevisionError`. This means another process has appended an event to the same stream, after you were loading your business object, while you were checking your business rules.
+6. Now you need to repeat the process: load your business objects from the updated events stream, apply your business rules and if there is still no violation, try to append the event with the updated stream revision. You can do this procedure until the event is published or a maximum number of retries has been reached.
+
+The following example shows the described retry procedure, with a simple business rule that does not allow adding an event after a `UserRemoved` event:
+
+```ruby
+require 'securerandom'
+class UserAboutMeChanged < PgEventstore::Event
+end
+
+class UserRemoved < PgEventstore::Event
+end
+
+def latest_event(stream)
+  PgEventstore.client.read(stream, options: { max_count: 1, direction: 'Backwards' }).first
+rescue PgEventstore::StreamNotFoundError  
+end
+
+def publish_event(stream, event)
+  retries_count = 0
+  begin
+    last_event = latest_event(stream)
+    # Ensure that the last event is not 'UserRemoved' event
+    return if last_event&.type == 'UserRemoved'
+
+    PgEventstore.client.append_to_stream(stream, event, options: { expected_revision: last_event&.stream_revision })
+  rescue PgEventstore::WrongExpectedRevisionError => e
+    # Parallel process has appended another event after we read the latest event, but before we appended our event. Such
+    # scenarios can be safely retried.
+    retries_count += 1
+    raise if retries_count > 3
+    retry
+  end  
+end
+
+stream = PgEventstore::Stream.new(context: 'UserProfile', stream_name: 'User', stream_id: SecureRandom.uuid)
+event = UserAboutMeChanged.new(data: { user_id: '123', about_me: 'hi there!' })
+
+publish_event(stream, event)
+```
+
+## Middlewares
+
+If you would like to skip some of your registered middlewares from processing events before they get appended to a stream - you should use the `:middlewares` argument which allows you to override the list of middlewares you would like to use.
+
+Let's say you have these registered middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  config.middlewares = { foo: FooMiddleware.new, bar: BarMiddleware.new, baz: BazMiddleware.new }
+end
+```
+
+And you want to skip `FooMiddleware` and `BazMiddleware`. You simply have to provide an array of corresponding middleware keys you would like to use:
+
+```ruby
+event = PgEventstore::Event.new
+stream = PgEventstore::Stream.new(context: 'MyAwesomeContext', stream_name: 'SomeStream', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+PgEventstore.client.append_to_stream(stream, event, middlewares: %i[bar])
+```
+
+See [Writing middleware](writing_middleware.md) chapter for info about what is middleware and how to implement it.

data/docs/configuration.md

@@ -0,0 +1,82 @@
+# Configuration
+
+Configuration options:
+
+| name                    | value    | default value                                                | description                                                                                                                                                                                                                                                            |
+|-------------------------|----------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| pg_uri                  | String   | `'postgresql://postgres:postgres@localhost:5432/eventstore'` | PostgreSQL connection string. See PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) for more information.                                                                                                            |
+| max_count               | Integer  | `1000`                                                       | Number of events to return in one response when reading from a stream.                                                                                                                                                                                                 |
+| middlewares             | Array    | `{}`                                                         | A hash where a key is a name of your middleware and value is an object that respond to `#serialize` and `#deserialize` methods. See [**Writing middleware**](writing_middleware.md) chapter.                                                                           |
+| event_class_resolver    | `#call`  | `PgEventstore::EventClassResolver.new`                       | A `#call`-able object that accepts a string and returns an event's class. See **Resolving events classes** chapter bellow for more info.                                                                                                                               |
+| logger                  | `Logger` | `nil`                                                        | A logger that logs messages from `pg_eventstore` gem.                                                                                                                                                                                                                  |
+| connection_pool_size    | Integer  | `5`                                                          | Max number of connections per ruby process. It must equal the number of threads of your application.                                                                                                                                                                   |
+| connection_pool_timeout | Integer  | `5`                                                          | Time in seconds to wait for the connection in pool to be released. If no connections are available during this time - `ConnectionPool::TimeoutError` will be raised. See `connection_pool` gem [docs](https://github.com/mperham/connection_pool#usage) for more info. |
+
+## Multiple configurations
+
+`pg_eventstore` allows you to have as many configs as you want. This allows you, for example, to have different
+databases, or to have a different set of middlewares for specific cases only. To do so, you have to name your
+configuration, and later provide that name to `PgEventstore` client.
+
+Setup your configs:
+
+```ruby
+PgEventstore.configure(name: :pg_db_1) do |config|
+  # adjust your config here
+  config.pg_uri = 'postgresql://postgres:postgres@localhost:5432/eventstore'
+end
+PgEventstore.configure(name: :pg_db_2) do |config|
+  # adjust your second config here
+  config.pg_uri = 'postgresql://postgres:postgres@localhost:5532/eventstore'
+end
+```
+
+Tell `PgEventstore` which config you want to use:
+
+```ruby
+# Read from "all" stream using :pg_db_1 config
+PgEventstore.client(:pg_db_1).read(PgEventstore::Stream.all_stream)
+# Read from "all" stream using :pg_db_2 config
+PgEventstore.client(:pg_db_2).read(PgEventstore::Stream.all_stream)
+```
+
+### Default config
+
+If you have one config only - you don't have to bother naming it or passing a config name to the client when performing
+any operations. You can configure it as usual.
+
+Setup your default config:
+
+```ruby
+PgEventstore.configure do |config|
+  # config goes here
+  config.pg_uri = 'postgresql://postgres:postgres@localhost:5432/eventstore'
+end
+```
+
+Use it:
+
+```ruby
+
+# Read from "all" stream using your default config
+EventStoreClient.client.read(PgEventstore::Stream.all_stream)
+```
+
+## Resolving event classes
+
+During the deserialization process `pg_eventstore` tries to pick the correct class for an event. By default it does it
+using the `PgEventstore::EventClassResolver` class. All it does is `Object.const_get(event_type)`. By default, if you
+don't provide the `type` attribute for an event explicitly, it will grab the event's class name, meaning by default:
+
+- event's type is event's class name
+- when instantiating an event - `pg_eventstore` tries to lookup an event class based on the value of event's `type`
+  attribute with a fallback to `PgEventstore::Event` class
+
+You can override the default event class resolver by providing any `#call`-able object. It should accept event's type
+and return event's class based on it. Example:
+
+```ruby
+PgEventstore.configure do |config|
+  config.event_class_resolver = proc { |event_type| Object.const_get(event_type.gsub('Foo', 'Bar')) rescue PgEventstore::Event }
+end
+```

data/docs/events_and_streams.md

@@ -0,0 +1,45 @@
+# The description of Event and Stream definitions
+
+`pg_eventstore` provides classes to prepare the events to be inserted into the eventstore. The most important are:
+
+- `PgEventstore::Event` class which represents an event object
+- `PgEventstore::Stream` class which represents a stream object
+
+## Event object and its defaults
+
+`PgEventstore::Event` has the following attributes:
+
+- `id` - String(UUIDv4, optional, not `nil`). If no provided - the value will be autogenerated.
+- `type` - String(optional, not `nil`). Default is an event's class name. Types which start from `$` indicate system events. It is not recommended to prefix your events types with `$` sign.
+- `global_position` - Integer(optional, read only). Event's global position in the eventstore, aka the "all" stream position (inspired by the popular EventstoreDB). Manually assigning this attribute has no effect. It is internally set when reading events from the database.
+- `stream` - PgEventstore::Stream(optional, read only). A Stream an event belongs to, see description below. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
+- `stream_revision` - Integer(optional, read only). A revision of an event inside its stream.
+- `data` - Hash(optional). Event's payload data. For example, if you have a `DescriptionChanged` event class, then you may want to have a description value in the event payload data. Example: `DescriptionChanged.new(data: { 'description' => 'Description of something', 'post_id' => SecureRandom.uuid })`
+- `metadata` - Hash(optional). Event metadata. Event meta information which is not part of an events data payload. Example: `{ published_by: publishing_user.id }`
+- `link_id` - String(UUIDv4, optional, read only). If an event is a link event (link events are pointers to other events), this attribute contains the `id` of the original event. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
+- `created_at` - Time(optional, read only). Database's timestamp when an event was appended to a stream. You may want to put your own timestamp into a `metadata` attribute - it may be useful when migrating between different databases. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
+
+Example:
+
+```ruby
+PgEventstore::Event.new(data: { 'foo' => 'bar' })
+```
+
+## Stream object
+
+To be able to manipulate a stream, you have to compute a stream's object first. It can be achieved by using the `PgEventstore::Stream` class. Here is a description of its attributes:
+
+- `context` - String(required). A Bounded Context, read more [here](https://martinfowler.com/bliki/BoundedContext.html). Values which start from `$` sign are reserved by `pg_eventstore`. Such contexts can't be used to append events.
+- `stream_name` - String(required). A stream name.
+- `stream_id` - String(required). A stream id.
+- `id` - Integer(optional, read only). Internal id. It is set when a stream is returned from the database as part of the deserialization process. Manually assigning this attribute has no effect.
+- `stream_revision` - Integer(optional, read only). Current stream's revision. You can rely on this value when setting the `:expected_revision` option when appending events to a stream. It is set when a stream is returned from the database a part of the deserialization process. Manually assigning this attribute has no effect.
+
+Example:
+
+```ruby
+PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: '1')
+PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
+```
+
+There is a special stream, called the "all" stream. You can get this object by calling the`PgEventstore::Stream.all_stream` method. Read more about the "all" stream in the `Reading from the "all" stream` section of [Reading events](reading_events.md) chapter.

data/docs/multiple_commands.md

@@ -0,0 +1,46 @@
+# Multiple commands
+
+`pg_eventstore` implements the `#multiple` method to allow you to make several different commands atomic. Example:
+
+```ruby
+PgEventstore.client.multiple do
+  unless PgEventstore.client.read(stream3, options: { max_count: 1, direction: 'Backwards' }).last&.type == 'Removed'
+    PgEventstore.client.append_to_stream(stream1, event1)
+    PgEventstore.client.append_to_stream(stream2, event2)
+  end  
+end
+```
+
+All commands inside a `multiple` block either all succeed or all fail. This allows you to easily implement complex business rules. However, it comes with a price of performance. The more you put in a single block, the higher the chance it will have conflicts with other commands run in parallel, increasing overall time to complete. **Because of this performance implications, do not put more events than needed in a `multple` block.** You may still want to use it though as it could simplify your implementation.
+
+**Please take into account that due to concurrency of parallel commands, a block of code may be re-run several times before succeeding.** So, if you put any piece of code besides `pg_evenstore`'s commands - make sure it is ready for re-runs. A good and a bad examples:
+
+## Bad
+
+```ruby
+PgEventstore.client.multiple do
+  old_email = PgEventstore.client.read(user_stream, options: { filter: { event_types: ['UserEmailChanged'] }, max_count: 1, direction: 'Backwards' }).first&.data&.dig('email')
+  # Email hasn't changed - prevent publishing unnecessary changes
+  next if old_email == user.email
+  
+  PgEventstore.client.append_to_stream(user_stream, UserEmailChanged.new(data: { email: user.email }))
+  # This is the mistake. UserMailer.notify_email_changed may be triggered several times
+  UserMailer.notify_email_changed(user.id, old_email: old_email, new_email: user.email).deliver_later
+end
+```
+
+## Good
+
+```ruby
+old_email =
+  PgEventstore.client.multiple do
+    old_email = PgEventstore.client.read(user_stream, options: { filter: { event_types: ['UserEmailChanged'] }, max_count: 1, direction: 'Backwards' }).first&.data&.dig('email')
+    # Email hasn't changed - prevent publishing unnecessary changes
+    next if old_email == user.email
+
+    PgEventstore.client.append_to_stream(user_stream, UserEmailChanged.new(data: { email: user.email }))
+    old_email
+  end
+# Sending email outside multiple block to prevent potential re-triggering of it 
+UserMailer.notify_email_changed(user.id, old_email: old_email, new_email: user.email).deliver_later
+```