From b1be2c585986ba8895d22a5736700f8d6bc70351 Mon Sep 17 00:00:00 2001 From: ThomasAribart Date: Tue, 14 Mar 2023 14:45:12 +0100 Subject: [PATCH] update documentation --- README.md | 9 ++++++--- docs/building-your-own-event-storage-adapter.md | 7 +++++-- docs/the-five-rules-of-event-sourcing.md | 2 +- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b24b3129..a5d8eb07 100644 --- a/README.md +++ b/README.md @@ -507,17 +507,20 @@ const userEventStore = new EventStore({ > }); > ``` > -> - listAggregateIds ((opt?: OptionsObj = {}) => Promise\): Retrieves the list of `aggregateId` of an event store, ordered by `timestamp` of their first event. Returns an empty array if no aggregate is found. +> - listAggregateIds ((opt?: OptionsObj = {}) => Promise\): Retrieves the list of `aggregateId` of an event store, ordered by the `timestamp` of their initial event. Returns an empty array if no aggregate is found. > > `OptionsObj` contains the following properties: > > - limit (?number): Maximum number of aggregate ids to retrieve +> - initialEventAfter (?string): To retrieve aggregate ids that appeared after a certain timestamp +> - initialEventBefore (?string): To retrieve aggregate ids that appeared before a certain timestamp +> - reverse (?boolean): To retrieve the aggregate ids in reverse order > - pageToken (?string): To retrieve a paginated result of aggregate ids > > `ResponseObj` contains the following properties: > > - aggregateIds (string[]): The list of aggregate ids -> - nextPageToken (?string): A token for the next page of aggregate ids if one exists +> - nextPageToken (?string): A token for the next page of aggregate ids if one exists. The nextPageToken carries the previously used options, so you do not have to provide them again (though you can still do it to override them). > > ```ts > const accAggregateIds: string = []; @@ -617,7 +620,7 @@ If the storage solution that you use is missing, feel free to create/upvote an i Modifying the state of your application (i.e. pushing new events to your event stores) is done by executing **commands**. They typically consist in: -- Fetching the required aggregates (if not the first event of a new aggregate) +- Fetching the required aggregates (if not the initial event of a new aggregate) - Validating that the modification is acceptable - Pushing new events with incremented versions diff --git a/docs/building-your-own-event-storage-adapter.md b/docs/building-your-own-event-storage-adapter.md index 03a31f8c..31b07cf8 100644 --- a/docs/building-your-own-event-storage-adapter.md +++ b/docs/building-your-own-event-storage-adapter.md @@ -108,17 +108,20 @@ class CustomEventAlreadyExistsError > This ensures that executed [`Commands`](../README.md#%EF%B8%8F-command) are not subject to [race conditions](https://en.wikipedia.org/wiki/Race_condition) and are accordingly retried. -- listAggregateIds ((opt?: OptionsObj = {}) => Promise\): Retrieves the list of `aggregateId` of an event store, ordered by `timestamp` of their first event. Returns an empty array if no aggregate is found. +- listAggregateIds ((opt?: OptionsObj = {}) => Promise\): Retrieves the list of `aggregateId` of an event store, ordered by `timestamp` of their initial event. Returns an empty array if no aggregate is found. `OptionsObj` contains the following attributes: - limit (?number): Maximum number of aggregate ids to retrieve - pageToken (?string): To retrieve a paginated result of aggregate ids + - initialEventAfter (?string): To retrieve aggregate ids that appeared after a certain timestamp + - initialEventBefore (?string): To retrieve aggregate ids that appeared before a certain timestamp + - reverse (?boolean): To retrieve the aggregate ids in reverse order `ResponseObj` contains the following attributes: - aggregateIds (string[]): The list of aggregate ids - - nextPageToken (?string): A token for the next page of aggregate ids if one exists + - nextPageToken (?string): A token for the next page of aggregate ids if one exists. The nextPageToken carries the previously used options, so you do not have to provide them again (though you can still do it to override them). ```ts const accAggregateIds: string = []; diff --git a/docs/the-five-rules-of-event-sourcing.md b/docs/the-five-rules-of-event-sourcing.md index 490dc1d4..1c55ea46 100644 --- a/docs/the-five-rules-of-event-sourcing.md +++ b/docs/the-five-rules-of-event-sourcing.md @@ -23,7 +23,7 @@ You should rather modify your `ORDER_CREATED` event to optionally contain a `att ## 4 - Write relations on all sides -In general, creating a relation in one way, say from an "order" to many "products", is easy to do: Simply write the "order" id on the "product" first event. However, in the context of a command (remember that you can't use read models, that can easily re-index), the other way around is tricky: Depending on your implementation (especially in NoSQL), there may not be an easy way to find all the "products" of an "order". +In general, creating a relation in one way, say from an "order" to many "products", is easy to do: Simply write the "order" id on the "product" initial event. However, in the context of a command (remember that you can't use read models, that can easily re-index), the other way around is tricky: Depending on your implementation (especially in NoSQL), there may not be an easy way to find all the "products" of an "order". The solution is to write an attachment event on the "order" at the same time that the "product" is created, containing only its order id. This way, you can easily find the order products ids in its aggregate. However, make sure to use transactions: Either all events are written, either none of them is written.