refactor: changes to aggregate::Repository, event::Store, documentation and more (#289)

In the scope of a closer v0.5.0 release, this PR introduces quite some
refactorings to different APIs, which are still experimental:

### refactor: generalize `event::StreamVersionExpected` into
`version::Check`

`version::Check` is a more general phrasing and naming for optimistic
locking, yet expressing quite more precisely its role.

### feat: add new `aggregate::test::Scenario`

It is now possible to write test assertions on `aggregate::Root`
methods, rather than having that only available through a
`command::test::Scenario`.

### refactor(aggregate::repository): split `Repository` traits once
again, use concrete error type

After trying the approach of having an unified `aggregate::Repository`
trait, and use an `AnyRepository` with `Error = anyhow::Error` (so,
opaque) for better usage in trait objects, we've reverted back to
Interface Segregation:
1. Have two separate interfaces -- `Saver` and `Getter` -- and a
`Repository` one, which extends both,
2. The errors returned by those are concrete types, using `thiserror`,
rather than using an associated type to abstract over it.

While this has required the introduction of opaque errors with
`anyhow::Error` in the concrete error types, this should provide a
better ergonomics for consumers of this API.

### refactor(event::store): move symbols to this module, add
`AppendError` concrete type

The `event::Store` follows the same approach as `aggregate::Repository`
now: split interfaces, concrete error types. The only exception being
`Streamer::stream`, where it seems to be fine to abstract over the error
type returned (for now).

### refactor(eventually-macros): remove derive(Message), as it requires
better design

`#[derive(Message)]` requires better design; we've implemented that with
a specific idea in mind, but that's very limiting and wouldn't be used
most of the time.

We remove it for now while we collect some ideas on how it should work.

### chore: add vscode setting for rust-analyzer to use all features

Finally rust-analyzer under VSCode will compile and check the workspace
using all feature flags.

### docs(eventually): add missing documentation

There was A LOT of missing documentation. This PR addresses some of the
missing stuff.
It's not great by any means, we'd likely need some dedicated effort
before releasing.

### refactor: split Serde trait into separate ones, implement
`serde::Convert` and `serde::ProtoJson`

After some production usage, we've collected some different ideas on how
this trait should work, and have implemented that following the previous
concepts: split methods/traits, concrete error types.

### chore: update all versions

Too many open dependabot PRs, this will take care of them all at once
(but `syn`, which is a major change).

Author: ar3s3ru

.github/workflows/ci.yml

@@ -148,11 +148,11 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v4
 
-      - name: Install nightly toolchain
+      - name: Install stable toolchain
         uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: nightly
+          toolchain: stable
           override: true
           components: clippy,rustfmt
 

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "rust-analyzer.cargo.features": "all",
+  "rust-analyzer.check.command": "clippy"
+}

eventually-macros/Cargo.toml

@@ -1,12 +1,25 @@
 [package]
 name = "eventually-macros"
+description = "Macros for eventually crate"
 version = "0.1.0"
 edition = "2021"
+authors = ["Danilo Cianfrone <danilocianfr@gmail.com>"]
+license = "MIT"
+readme = "../README.md"
+repository = "https://github.com/get-eventually/eventually-rs"
+
+categories = [
+    "rust-patterns",
+    "web-programming",
+    "asynchronous",
+    "data-structures",
+]
+keywords = ["architecture", "ddd", "event-sourcing", "cqrs", "es"]
 
 [lib]
 proc-macro = true
 
 [dependencies]
 syn = { version = "1.0.109", features = ["full"] }
-quote = "1.0.33"
+quote = "1.0.35"
 eventually = { path = "../eventually" }

eventually-macros/src/lib.rs

@@ -1,55 +1,21 @@
-//! Module containing useful macros for the [eventually] crate.
+//! `eventually-macros` contains useful macros that provides
+//! different implementations of traits and functionalities from [eventually].
 
-#![deny(unsafe_code, unused_qualifications, trivial_casts)]
-#![warn(missing_docs)]
-#![deny(clippy::all)]
-#![warn(clippy::pedantic)]
+#![deny(unsafe_code, unused_qualifications, trivial_casts, missing_docs)]
+#![deny(clippy::all, clippy::pedantic, clippy::cargo)]
 
 use proc_macro::TokenStream;
 use quote::quote;
-use syn::{parse_macro_input, AttributeArgs, Fields, ItemEnum, ItemStruct, Meta, NestedMeta, Path};
+use syn::{parse_macro_input, AttributeArgs, Fields, ItemStruct, Meta, NestedMeta, Path};
 
-#[proc_macro_derive(Message)]
-pub fn derive_message(input: TokenStream) -> TokenStream {
-    let item = parse_macro_input!(input as ItemEnum);
-    let item_name = item.ident;
-    let event_prefix = item_name
-        .to_string()
-        .strip_suffix("Event")
-        .unwrap()
-        .to_owned();
-
-    let match_cases = item.variants.iter().fold(quote! {}, |acc, variant| {
-        let event_type = &variant.ident;
-        let event_name = format!("{}{}", event_prefix, event_type);
-
-        quote! {
-            #acc
-            #item_name::#event_type { .. } => #event_name,
-        }
-    });
-
-    let result = quote! {
-        impl eventually::message::Message for #item_name {
-            fn name(&self) -> &'static str {
-                match self {
-                    #match_cases
-                }
-            }
-        }
-    };
-
-    result.into()
-}
-
-/// Implements a newtype to use the [eventually::aggregate::Root] instance with
-/// user-defined [eventually::aggregate::Aggregate] types.
+/// Implements a newtype to use the [`eventually::aggregate::Root`] instance with
+/// user-defined [`eventually::aggregate::Aggregate`] types.
 ///
 /// # Context
 ///
-/// The eventually API uses `aggregate::Root<T>` to manage the versioning and
-/// list of events to commit for an `Aggregate` instance. Domain commands
-/// are to be implemented on the `aggregate::Root<T>` instance, as it gives
+/// The eventually API uses [`aggregate::Root`][eventually::aggregate::Root]
+/// to manage the versioning and list of events to commit for an `Aggregate` instance.
+/// Domain commands are to be implemented on the `aggregate::Root<T>` instance, as it gives
 /// access to use `Root<T>.record_that` or `Root<T>.record_new` to record Domain Events.
 ///
 /// However, it's not possible to use `impl aggregate::Root<MyAggregateType>` (`MyAggregateType`
@@ -58,7 +24,11 @@ pub fn derive_message(input: TokenStream) -> TokenStream {
 ///
 /// This attribute macro makes the implementation of a newtype easy, as it Implements
 /// conversion traits from and to `aggregate::Root<T>` and implements automatic deref
-/// through [std::ops::Deref] and [std::ops::DerefMut].
+/// through [`std::ops::Deref`] and [`std::ops::DerefMut`].
+///
+/// # Panics
+///
+/// This method will panic if the Aggregate Root type is not provided as a macro parameter.
 #[proc_macro_attribute]
 pub fn aggregate_root(args: TokenStream, item: TokenStream) -> TokenStream {
     let args = parse_macro_input!(args as AttributeArgs);

eventually-postgres/Cargo.toml

@@ -12,26 +12,27 @@ categories = ["web-programming", "asynchronous"]
 keywords = ["postgres", "postgresql", "database", "ddd", "event-sourcing"]
 
 [dependencies]
-async-trait = "0.1.74"
-chrono = "0.4.31"
+anyhow = "1.0.80"
+async-trait = "0.1.77"
+chrono = "0.4.34"
 eventually = { path = "../eventually", version = "0.5.0", features = [
     "serde-json",
 ] }
-futures = "0.3.29"
+futures = "0.3.30"
 lazy_static = "1.4.0"
-regex = "1.10.2"
-sqlx = { version = "0.7.2", features = [
+regex = "1.10.3"
+sqlx = { version = "0.7.3", features = [
     "runtime-tokio-rustls",
     "postgres",
     "migrate",
 ] }
-thiserror = "1.0.50"
+thiserror = "1.0.57"
 
 [dev-dependencies]
-tokio = { version = "1.34.0", features = ["macros", "rt"] }
+tokio = { version = "1.36.0", features = ["macros", "rt"] }
 eventually = { path = "../eventually", version = "0.5.0", features = [
     "serde-json",
 ] }
 eventually-macros = { path = "../eventually-macros", version = "0.1.0" }
-serde = { version = "1.0.192", features = ["derive"] }
+serde = { version = "1.0.197", features = ["derive"] }
 rand = "0.8.5"