refactor: rename aggregate::Saver method, move repositories into aggregate::repository mod (#249)

* refactor: rename aggregate::Saver::store in aggregate::Saver::save

* refactor: move aggregate::{Saver, Getter} to aggregate::repository::{Getter, Saver}

* feat: add .editorconfig

* chore: update CONTRIBUTING.md guidelines doc

* test(eventually-postgres): unmask errors with the integration test when conflict error is not detected

Author: ar3s3ru

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = 160
+tab_width = 4
+trim_trailing_whitespace = true
+
+[*.{json, md, yaml, yml, proto}]
+indent_size = 2
+

CONTRIBUTING.md

@@ -2,14 +2,14 @@
 
 Thank you so much for considering contributing to `eventually`! :tada:
 
-- [Contributing to `eventually`](#contributing-to-eventually)
-  - [What should I know before I get started?](#what-should-i-know-before-i-get-started)
-    - [I want to contribute, but I don't know what can I contribute to...](#i-want-to-contribute-but-i-dont-know-what-can-i-contribute-to)
-  - [Pull Requests](#pull-requests)
-  - [How should my Pull Request look like?](#how-should-my-pull-request-look-like)
-    - [Describe the scope of the PR](#describe-the-scope-of-the-pr)
-    - [Git commit messages](#git-commit-messages)
-    - [Rust styleguide](#rust-styleguide)
+-   [Contributing to `eventually`](#contributing-to-eventually)
+    -   [What should I know before I get started?](#what-should-i-know-before-i-get-started)
+        -   [I want to contribute, but I don't know what can I contribute to...](#i-want-to-contribute-but-i-dont-know-what-can-i-contribute-to)
+    -   [Pull Requests](#pull-requests)
+    -   [How should my Pull Request look like?](#how-should-my-pull-request-look-like)
+        -   [Describe the scope of the PR](#describe-the-scope-of-the-pr)
+        -   [Git commit messages](#git-commit-messages)
+        -   [Rust styleguide](#rust-styleguide)
 
 ## What should I know before I get started?
 
@@ -18,27 +18,22 @@ where all the crates share the same dependencies and lock file.
 (This might be changed in the future)
 
 The workspace has the following crates:
-- [`eventually`]\: the main crate, users should depend solely on this crate
-- [`eventually-app-example`]\: an example application to showcase a (not-so) real-world example of how to use the library
 
-Although `eventually-postgres` and `eventually-redis` are currently in the workspace, they might be moved outside the repository, into their own respective repository inside the organization. (For more info, check out #131 and #132)
+-   [`eventually`]\: the main crate, users should depend solely on this crate
+-   [`eventually-macros`]\: the crate that contains procedural macros to make the development experience nicer for users,
+-   [`eventually-postgres`]\: the crate that contains implementations of abstractions from `eventually` for PostgreSQL databases,
 
 When submitting a PR involving one or more of these crates, please make sure to use the **corresponding label**.
 
 ### I want to contribute, but I don't know what can I contribute to...
 
 If you want to contribute but you have no idea how, or what specific features are
-missing, please check the [_What next?_ tracking issue](https://github.com/get-eventually/eventually-rs/issues/133).
+missing, please check the [issues] page: we usually have some issues that are marked as "good for
+beginners".
 
 Being an open-source project, we are always looking for new contributors, so no matter
 your level of Event Sourcing skills or language mastery, your PRs are always welcome :heart:
 
-If you want to experiment and/or get familiar with the library, you can consider
-trying to write a small application using the crate and send a message to our
-[Gitter chat][gitter] to give visibility: we can add your example project to the
-repository's `README` in order for other users to find it and draw inspiration
-from your experience.
-
 ## Pull Requests
 
 Before opening a Pull Request, check the [Issues section][issues] for an issue that might describe the feature you're considering adding.
@@ -48,11 +43,12 @@ implementation before the code review process. You can also reach out to our [Gi
 features or other technical aspects of the crate.
 
 In order to submit a PR, follow these steps:
+
 1. **Fork** the repository
 2. **Clone** your fork of the repository in your local machine
 3. Add the upstream repository in your local machine copy:
     ```bash
-    git remote add upstream git@github.com:eventually-rs/eventually-rs
+    git remote add upstream git@github.com:get-eventually/eventually-rs
     git fetch upstream
     ```
 4. Create a new branch starting from `upstream/main`:
@@ -98,8 +94,8 @@ Make sure you run `rustfmt` **before committing any changes**, as failing to do
 
 [workspace]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
 [`eventually`]: ./eventually
-[`eventually-app-example`]: ./eventually-app-example
+[`eventually-macros`]: ./eventually-macros
+[`eventually-postgres`]: ./eventually-postgres
 [issues]: https://github.com/get-eventually/eventually-rs/issues
 [new-issue]: https://github.com/get-eventually/eventually-rs/issues/new
-[gitter]: https://gitter.im/eventually-rs/community
 [conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/

eventually-postgres/src/aggregate.rs

@@ -141,7 +141,7 @@ where
 }
 
 #[async_trait]
-impl<T, OutT, OutEvt, TSerde, EvtSerde> aggregate::Getter<T>
+impl<T, OutT, OutEvt, TSerde, EvtSerde> aggregate::repository::Getter<T>
     for Repository<T, OutT, OutEvt, TSerde, EvtSerde>
 where
     T: Aggregate + TryFrom<OutT> + Send + Sync,
@@ -158,7 +158,7 @@ where
     async fn get(
         &self,
         id: &T::Id,
-    ) -> Result<aggregate::Root<T>, aggregate::RepositoryGetError<Self::Error>> {
+    ) -> Result<aggregate::Root<T>, aggregate::repository::GetError<Self::Error>> {
         let aggregate_id = id.to_string();
 
         let row = sqlx::query(
@@ -171,8 +171,8 @@ where
         .fetch_one(&self.pool)
         .await
         .map_err(|err| match err {
-            sqlx::Error::RowNotFound => aggregate::RepositoryGetError::AggregateRootNotFound,
-            _ => aggregate::RepositoryGetError::Inner(GetError::FetchAggregateRow(err)),
+            sqlx::Error::RowNotFound => aggregate::repository::GetError::NotFound,
+            _ => aggregate::repository::GetError::Inner(GetError::FetchAggregateRow(err)),
         })?;
 
         let version: i32 = row.try_get("version").map_err(GetError::Database)?;
@@ -194,7 +194,7 @@ where
 }
 
 #[async_trait]
-impl<T, OutT, OutEvt, TSerde, EvtSerde> aggregate::Saver<T>
+impl<T, OutT, OutEvt, TSerde, EvtSerde> aggregate::repository::Saver<T>
     for Repository<T, OutT, OutEvt, TSerde, EvtSerde>
 where
     T: Aggregate + TryFrom<OutT> + Send + Sync,
@@ -208,7 +208,7 @@ where
 {
     type Error = SaveError;
 
-    async fn store(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error> {
+    async fn save(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error> {
         let events_to_commit = root.take_uncommitted_events();
 
         if events_to_commit.is_empty() {

eventually-postgres/tests/aggregate_repository.rs

@@ -1,5 +1,5 @@
 use eventually::{
-    aggregate::{Getter, RepositoryGetError, Saver},
+    aggregate::repository::{GetError, Getter, Saver},
     serde::json::Json,
     version,
 };
@@ -31,7 +31,7 @@ async fn it_works() {
         .expect_err("should fail");
 
     match result {
-        RepositoryGetError::AggregateRootNotFound => (),
+        GetError::NotFound => (),
         _ => panic!(
             "unexpected error received, should be 'not found': {:?}",
             result
@@ -45,7 +45,7 @@ async fn it_works() {
     root.delete().unwrap();
 
     aggregate_repository
-        .store(&mut root)
+        .save(&mut root)
         .await
         .expect("storing the new aggregate root should be successful");
 
@@ -86,10 +86,10 @@ async fn it_detects_data_races_and_returns_conflict_error() {
 
     let result = futures::join!(
         aggregate_repository
-            .store(&mut root)
+            .save(&mut root)
             .map_err(Option::<version::ConflictError>::from),
         aggregate_repository
-            .store(&mut cloned_root)
+            .save(&mut cloned_root)
             .map_err(Option::<version::ConflictError>::from),
     );
 

eventually-postgres/tests/event_store.rs

@@ -185,8 +185,9 @@ async fn it_handles_concurrent_writes_to_the_same_stream() {
     );
 
     match result {
-        (Ok(_), Err(Some(_))) => (),
-        (Err(Some(_)), Ok(_)) => (),
+        (Ok(_), Err(err)) | (Err(err), Ok(_)) => {
+            assert!(Option::<version::ConflictError>::from(err).is_some())
+        }
         (first, second) => panic!(
             "invalid state detected, first: {:?}, second: {:?}",
             first, second

eventually/src/aggregate.rs

@@ -27,11 +27,9 @@
 
 use crate::{event, message, version::Version};
 
-mod repository;
-pub use repository::{
-    EventSourced as EventSourcedRepository, GetError as RepositoryGetError, Getter, Repository,
-    Saver,
-};
+pub mod repository;
+
+pub use repository::{EventSourced as EventSourcedRepository, Repository};
 
 /// An Aggregate represents a Domain Model that, through an Aggregate [Root],
 /// acts as a _transactional boundary_.
@@ -390,8 +388,8 @@ mod test {
 
     use crate::{
         aggregate,
+        aggregate::repository::{Getter, Saver},
         aggregate::test_user_domain::{User, UserEvent},
-        aggregate::{Getter, Saver},
         event,
         event::store::EventStoreExt,
         version,
@@ -411,9 +409,9 @@ mod test {
             .expect("user should be created successfully");
 
         user_repository
-            .store(&mut user)
+            .save(&mut user)
             .await
-            .expect("user should be stored successfully");
+            .expect("user should be saved successfully");
 
         let expected_events = vec![event::Persisted {
             stream_id: email.clone(),
@@ -438,9 +436,9 @@ mod test {
             .expect("user should be created successfully");
 
         user_repository
-            .store(&mut user)
+            .save(&mut user)
             .await
-            .expect("user should be stored successfully");
+            .expect("user should be saved successfully");
 
         // Reset the event recorded while storing the User for the first time.
         tracking_event_store.reset_recorded_events();
@@ -456,9 +454,9 @@ mod test {
             .expect("user password should be changed successfully");
 
         user_repository
-            .store(&mut user)
+            .save(&mut user)
             .await
-            .expect("new user version should be stored successfully");
+            .expect("new user version should be saved successfully");
 
         let expected_events = vec![event::Persisted {
             stream_id: email.clone(),
@@ -489,16 +487,15 @@ mod test {
 
         // Saving the first User to the Repository.
         user_repository
-            .store(&mut user)
+            .save(&mut user)
             .await
-            .expect("user should be stored successfully");
+            .expect("user should be saved successfully");
 
         // Simulating data race by duplicating the call to the Repository
         // with the same UserRoot instance that has already been committeed.
-        let error = user_repository
-            .store(&mut cloned_user)
-            .await
-            .expect_err("the repository should fail on the second store call with the cloned user");
+        let error = user_repository.save(&mut cloned_user).await.expect_err(
+            "the repository should fail on the second .save() call with the cloned user",
+        );
 
         let error: Box<dyn Error> = error.into();
 

eventually/src/aggregate/repository.rs

@@ -12,7 +12,7 @@ pub enum GetError<I> {
     /// This error is retured by [`Repository::get`] when the
     /// desired Aggregate [Root] could not be found in the data store.
     #[error("aggregate root was not found")]
-    AggregateRootNotFound,
+    NotFound,
     #[error(transparent)]
     Inner(#[from] I),
 }
@@ -36,8 +36,8 @@ where
 {
     type Error: Send + Sync;
 
-    /// Stores a new version of an Aggregate Root instance to the data store.
-    async fn store(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error>;
+    /// Saves a new version of an Aggregate Root instance to the data store.
+    async fn save(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error>;
 }
 
 /// A Repository is an object that allows to load and save
@@ -141,7 +141,7 @@ where
             })
             .await?;
 
-        ctx.ok_or(GetError::AggregateRootNotFound)
+        ctx.ok_or(GetError::NotFound)
     }
 }
 
@@ -159,7 +159,7 @@ where
         <S as event::Appender<T::Id, T::Event>>::Error,
     >;
 
-    async fn store(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error> {
+    async fn save(&self, root: &mut aggregate::Root<T>) -> Result<(), Self::Error> {
         let events_to_commit = root.take_uncommitted_events();
         let aggregate_id = root.aggregate_id();
 

eventually/src/command.rs

@@ -85,12 +85,12 @@ mod test_user_domain {
 
     struct CreateUserHandler<R>(R)
     where
-        R: aggregate::Saver<User>;
+        R: aggregate::repository::Saver<User>;
 
     #[async_trait]
     impl<R> command::Handler<CreateUser> for CreateUserHandler<R>
     where
-        R: aggregate::Saver<User>,
+        R: aggregate::repository::Saver<User>,
         R::Error: std::error::Error + Send + Sync + 'static,
     {
         type Error = anyhow::Error;
@@ -99,7 +99,7 @@ mod test_user_domain {
             let command = command.message;
             let mut user = aggregate::Root::<User>::create(command.email, command.password)?;
 
-            self.0.store(&mut user).await?;
+            self.0.save(&mut user).await?;
 
             Ok(())
         }
@@ -124,8 +124,9 @@ mod test_user_domain {
     impl<R> command::Handler<ChangeUserPassword> for ChangeUserPasswordHandler<R>
     where
         R: aggregate::Repository<User>,
-        <R as aggregate::Getter<User>>::Error: std::error::Error + Send + Sync + 'static,
-        <R as aggregate::Saver<User>>::Error: std::error::Error + Send + Sync + 'static,
+        <R as aggregate::repository::Getter<User>>::Error:
+            std::error::Error + Send + Sync + 'static,
+        <R as aggregate::repository::Saver<User>>::Error: std::error::Error + Send + Sync + 'static,
     {
         type Error = anyhow::Error;
 
@@ -139,7 +140,7 @@ mod test_user_domain {
 
             user.change_password(command.password)?;
 
-            self.0.store(&mut user).await?;
+            self.0.save(&mut user).await?;
 
             Ok(())
         }