From 5dd839200203c4c341c3c4417cb5624c3cd386f4 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 26 Aug 2021 13:21:52 +0300 Subject: [PATCH 01/16] Add missing documents --- docs/api/aggregate-projection.md | 4 ++++ docs/api/view-model-projection.md | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 docs/api/aggregate-projection.md create mode 100644 docs/api/view-model-projection.md diff --git a/docs/api/aggregate-projection.md b/docs/api/aggregate-projection.md new file mode 100644 index 0000000000..927fcf1926 --- /dev/null +++ b/docs/api/aggregate-projection.md @@ -0,0 +1,4 @@ +--- +id: aggregate-projection +title: Aggregate Projection +--- diff --git a/docs/api/view-model-projection.md b/docs/api/view-model-projection.md new file mode 100644 index 0000000000..13b8328419 --- /dev/null +++ b/docs/api/view-model-projection.md @@ -0,0 +1,4 @@ +--- +id: view-model-projection +title: View Model Projection +--- From dae6ca459570096336c2a2e11dbf1926719ad384 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 26 Aug 2021 13:31:12 +0300 Subject: [PATCH 02/16] Draft --- docs/api/aggregate-projection.md | 8 ++++++++ docs/api/view-model-projection.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/api/aggregate-projection.md b/docs/api/aggregate-projection.md index 927fcf1926..4eeb2e7b9c 100644 --- a/docs/api/aggregate-projection.md +++ b/docs/api/aggregate-projection.md @@ -2,3 +2,11 @@ id: aggregate-projection title: Aggregate Projection --- + +An aggregate projection function has the following structure: + +```js + +``` + +A projection implementation receives the following arguments: diff --git a/docs/api/view-model-projection.md b/docs/api/view-model-projection.md index 13b8328419..a4f6c649ef 100644 --- a/docs/api/view-model-projection.md +++ b/docs/api/view-model-projection.md @@ -2,3 +2,11 @@ id: view-model-projection title: View Model Projection --- + +A view model projection function has the following structure: + +```js + +``` + +A projection implementation receives the following arguments: From 404ae0f8a19875ac13082491a4d7dcfe32fd45e6 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 27 Aug 2021 14:11:11 +0300 Subject: [PATCH 03/16] Adjust the documents' structure --- docs/api/aggregate-projection.md | 12 ------------ docs/api/aggregate.md | 17 +++++++++++++++++ docs/api/command.md | 16 ++++++++++++++++ docs/api/event.md | 10 ++++++++++ docs/api/view-model-projection.md | 12 ------------ 5 files changed, 43 insertions(+), 24 deletions(-) delete mode 100644 docs/api/aggregate-projection.md create mode 100644 docs/api/aggregate.md create mode 100644 docs/api/command.md create mode 100644 docs/api/event.md delete mode 100644 docs/api/view-model-projection.md diff --git a/docs/api/aggregate-projection.md b/docs/api/aggregate-projection.md deleted file mode 100644 index 4eeb2e7b9c..0000000000 --- a/docs/api/aggregate-projection.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: aggregate-projection -title: Aggregate Projection ---- - -An aggregate projection function has the following structure: - -```js - -``` - -A projection implementation receives the following arguments: diff --git a/docs/api/aggregate.md b/docs/api/aggregate.md new file mode 100644 index 0000000000..d02374eb4f --- /dev/null +++ b/docs/api/aggregate.md @@ -0,0 +1,17 @@ +--- +id: aggregate +title: Aggregate +--- + +An aggregate event handler function has the following structure: + +```js + +``` + +export type AggregateEventHandler = ( +state: AggregateState, +event: Event +) => AggregateState + +An event handler implementation receives the following arguments: diff --git a/docs/api/command.md b/docs/api/command.md new file mode 100644 index 0000000000..4ac09f1951 --- /dev/null +++ b/docs/api/command.md @@ -0,0 +1,16 @@ +--- +id: command +title: Command +--- + +A command is an object of the following structure: + +```js +{ + type, + aggregateId, + aggregateName, + payload, // (optional) + jwt // (optional) +} +``` diff --git a/docs/api/event.md b/docs/api/event.md new file mode 100644 index 0000000000..f3394698d3 --- /dev/null +++ b/docs/api/event.md @@ -0,0 +1,10 @@ +--- +id: event +title: Event +--- + +```js +{ + type, timestamp, aggregateId, aggregateVersion, payload // (optional) +} +``` diff --git a/docs/api/view-model-projection.md b/docs/api/view-model-projection.md deleted file mode 100644 index a4f6c649ef..0000000000 --- a/docs/api/view-model-projection.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: view-model-projection -title: View Model Projection ---- - -A view model projection function has the following structure: - -```js - -``` - -A projection implementation receives the following arguments: From 31f5ec35150250bcc2d8970e43faa9b0937024f7 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 27 Aug 2021 14:11:27 +0300 Subject: [PATCH 04/16] View Model API document --- docs/api/view-model.md | 46 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/api/view-model.md diff --git a/docs/api/view-model.md b/docs/api/view-model.md new file mode 100644 index 0000000000..0dca1e5a70 --- /dev/null +++ b/docs/api/view-model.md @@ -0,0 +1,46 @@ +--- +id: view-model +title: View Model +--- + +A view model projection is an object of the following structure: + +```js +const projection = { + // The *Init* function creates the view models initial state object. + Init: () => initialState, + // An event handler function is associated with an event type. + // It receives the view model's state and an incoming event + // and returns the updated state. + [EVENT_TYPE]: (state, event) => { + ... + return newState + } + [EVENT_TYPE2]: (state, event) => ... + [EVENT_TYPE3]: (state, event) => ... + ... +} +``` + +## Event Handler + +An event handler implementation receives the following arguments: + +| Argument Name | Description | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| state | The view model's state that is an object of arbitrary structure. | +| event | An [event](event.md) object. | +| args | Arguments attached to the request. | +| context | An object that contains functions and data related to the current operation (see the [Event Handler Context](#event-handler-context) section.) | + +An event handler should return a new state object. + +## Event Handler Context + +A view model event handler context is an object with the following fields: + +| Field Name | Description | +| ---------- | ------------------------------------------------------ | +| jwt | The JSON Web Token attached to the request. | +| encrypt | The user-defined [encrypt](../encryption.md) function. | +| decrypt | The user-defined [decrypt](../encryption.md) function. | From f248da19705735e38d1642448ce2a6efd4cd39e3 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 27 Aug 2021 14:21:41 +0300 Subject: [PATCH 05/16] Add section headings --- docs/api/view-model.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api/view-model.md b/docs/api/view-model.md index 0dca1e5a70..2556dfd52a 100644 --- a/docs/api/view-model.md +++ b/docs/api/view-model.md @@ -3,6 +3,8 @@ id: view-model title: View Model --- +## View Model Projection + A view model projection is an object of the following structure: ```js @@ -22,7 +24,7 @@ const projection = { } ``` -## Event Handler +### Event Handler An event handler implementation receives the following arguments: @@ -35,7 +37,7 @@ An event handler implementation receives the following arguments: An event handler should return a new state object. -## Event Handler Context +### Event Handler Context A view model event handler context is an object with the following fields: From 05edfdcc824bfe2e399b902cc3a1d63622a587ab Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 27 Aug 2021 14:28:51 +0300 Subject: [PATCH 06/16] Aggregate API --- docs/api/aggregate.md | 31 +++++++++++++++++++++++++------ docs/api/view-model.md | 2 +- 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/api/aggregate.md b/docs/api/aggregate.md index d02374eb4f..892d00328f 100644 --- a/docs/api/aggregate.md +++ b/docs/api/aggregate.md @@ -3,15 +3,34 @@ id: aggregate title: Aggregate --- -An aggregate event handler function has the following structure: +## Aggregate Projection -```js +An aggregate projection is an object of the following structure: +```js +const projection = { + // The *Init* function creates the initial aggregate state object. + Init: () => initialState, + // An event handler function is associated with an event type. + // It receives the aggregate state and an incoming event + // and returns the updated state. + [EVENT_TYPE]: (state, event) => { + ... + return newState + } + [EVENT_TYPE2]: (state, event) => ... + [EVENT_TYPE3]: (state, event) => ... + ... +} ``` -export type AggregateEventHandler = ( -state: AggregateState, -event: Event -) => AggregateState +### Event Handler An event handler implementation receives the following arguments: + +| Argument Name | Description | +| ------------- | ------------------------------------------------------------- | +| state | The aggregate state that is an object of arbitrary structure. | +| event | An [event](event.md) object. | + +An event handler should return a new state object. diff --git a/docs/api/view-model.md b/docs/api/view-model.md index 2556dfd52a..9460394b06 100644 --- a/docs/api/view-model.md +++ b/docs/api/view-model.md @@ -9,7 +9,7 @@ A view model projection is an object of the following structure: ```js const projection = { - // The *Init* function creates the view models initial state object. + // The *Init* function creates the view model's initial state object. Init: () => initialState, // An event handler function is associated with an event type. // It receives the view model's state and an incoming event From 6ae458069222b68cde7ca93f1df2bea7d9cc89b5 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 31 Aug 2021 14:11:10 +0300 Subject: [PATCH 07/16] Command and event API --- docs/api/command.md | 14 +++++++++----- docs/api/event.md | 12 +++++++++++- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/api/command.md b/docs/api/command.md index 4ac09f1951..c8dfc764f4 100644 --- a/docs/api/command.md +++ b/docs/api/command.md @@ -5,12 +5,16 @@ title: Command A command is an object of the following structure: + + ```js { - type, - aggregateId, - aggregateName, - payload, // (optional) - jwt // (optional) + type, // A string that contains the command type name. + aggregateId, // A string that uniquely identifies an aggregate instance. + aggregateName, // The name of an aggregate that the command targets. + payload, // An object of arbitrary structure that contains data attached to the command. (optional) + jwt // A JSON Web Token attached to the web request used to send the command. (optional) } ``` + + diff --git a/docs/api/event.md b/docs/api/event.md index f3394698d3..fca666d80f 100644 --- a/docs/api/event.md +++ b/docs/api/event.md @@ -3,8 +3,18 @@ id: event title: Event --- +An event is an object of the following structure: + + + ```js { - type, timestamp, aggregateId, aggregateVersion, payload // (optional) + type, // A string that contains the command type name. + timestamp, // A number type field that stores the point in time when the event was produced. + aggregateId, // A string that uniquely identifies an aggregate instance. + aggregateVersion, // A number that is incremented for each consequent event with the current aggregateId. + payload // An object of arbitrary structure that contains data attached to the event. (optional) } ``` + + From 2e458e4f1ed6244dbbb27a055a4aa3a427df5f56 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Wed, 1 Sep 2021 15:03:28 +0300 Subject: [PATCH 08/16] Hierarchy and sidebar --- docs/api/{ => aggregate}/command-handler.md | 3 +- .../{aggregate.md => aggregate/projection.md} | 8 ++--- .../connector.md} | 4 +-- .../projection.md} | 5 ++-- .../resolver.md} | 4 +-- .../store.md} | 6 ++-- .../projection.md} | 10 ++----- docs/api/view-model/resolver.md | 4 +++ website/sidebars.json | 30 +++++++++++++++---- 9 files changed, 44 insertions(+), 30 deletions(-) rename docs/api/{ => aggregate}/command-handler.md (94%) rename docs/api/{aggregate.md => aggregate/projection.md} (92%) rename docs/api/{read-model-connector.md => read-model/connector.md} (98%) rename docs/api/{read-model-event-handler.md => read-model/projection.md} (90%) rename docs/api/{read-model-resolver.md => read-model/resolver.md} (96%) rename docs/api/{read-model-store.md => read-model/store.md} (98%) rename docs/api/{view-model.md => view-model/projection.md} (95%) create mode 100644 docs/api/view-model/resolver.md diff --git a/docs/api/command-handler.md b/docs/api/aggregate/command-handler.md similarity index 94% rename from docs/api/command-handler.md rename to docs/api/aggregate/command-handler.md index e4b2631d43..6bc8368552 100644 --- a/docs/api/command-handler.md +++ b/docs/api/aggregate/command-handler.md @@ -1,7 +1,6 @@ --- id: command-handler title: Command Handler -description: Aggregate command handlers handle incoming commands and produce events. --- A command handler function has the following structure: @@ -24,7 +23,7 @@ A command handler implementation receives the following arguments: | command | An object that contains the incoming command's data. | | context | An object that contains data and functions related to the current operation. | -## context +## Context The `context` argument is an object with the following fields: diff --git a/docs/api/aggregate.md b/docs/api/aggregate/projection.md similarity index 92% rename from docs/api/aggregate.md rename to docs/api/aggregate/projection.md index 892d00328f..cc3ec21f13 100644 --- a/docs/api/aggregate.md +++ b/docs/api/aggregate/projection.md @@ -1,10 +1,8 @@ --- -id: aggregate -title: Aggregate +id: projection +title: Projection --- -## Aggregate Projection - An aggregate projection is an object of the following structure: ```js @@ -24,8 +22,6 @@ const projection = { } ``` -### Event Handler - An event handler implementation receives the following arguments: | Argument Name | Description | diff --git a/docs/api/read-model-connector.md b/docs/api/read-model/connector.md similarity index 98% rename from docs/api/read-model-connector.md rename to docs/api/read-model/connector.md index 1461ffa888..d087d0b4d0 100644 --- a/docs/api/read-model-connector.md +++ b/docs/api/read-model/connector.md @@ -1,6 +1,6 @@ --- -id: read-model-connector -title: Read Model Connector +id: connector +title: Connector description: This document describes the interface that a read model connector should expose. --- diff --git a/docs/api/read-model-event-handler.md b/docs/api/read-model/projection.md similarity index 90% rename from docs/api/read-model-event-handler.md rename to docs/api/read-model/projection.md index 334dd95a14..0385839376 100644 --- a/docs/api/read-model-event-handler.md +++ b/docs/api/read-model/projection.md @@ -1,7 +1,6 @@ --- -id: read-model-event-handler -title: Read Model Event Handler -description: Event handlers build a Read Model state based on incoming events. +id: projection +title: Projection --- A read model event handler function has the following structure: diff --git a/docs/api/read-model-resolver.md b/docs/api/read-model/resolver.md similarity index 96% rename from docs/api/read-model-resolver.md rename to docs/api/read-model/resolver.md index ceb3036653..25a20cb7d0 100644 --- a/docs/api/read-model-resolver.md +++ b/docs/api/read-model/resolver.md @@ -1,6 +1,6 @@ --- -id: read-model-resolver -title: Read Model Resolver +id: resolver +title: Resolver description: A resolver is the part of a Read Model that handles data requests. --- diff --git a/docs/api/read-model-store.md b/docs/api/read-model/store.md similarity index 98% rename from docs/api/read-model-store.md rename to docs/api/read-model/store.md index 58beb1690c..d841fc0a3f 100644 --- a/docs/api/read-model-store.md +++ b/docs/api/read-model/store.md @@ -1,10 +1,10 @@ --- -id: read-model-store -title: Read Model Store +id: store +title: Store description: This document describes functions that you can use to communicate with a Read Model store through a `store` object. --- -The table below lists functions that you can use to communicate with a Read Model store through a `store` object. +The table below lists functions that you can use to communicate with a read model store through a `store` object. | Function Name | Description | | --------------------------- | -------------------------------------------------- | diff --git a/docs/api/view-model.md b/docs/api/view-model/projection.md similarity index 95% rename from docs/api/view-model.md rename to docs/api/view-model/projection.md index 9460394b06..43b9a6266e 100644 --- a/docs/api/view-model.md +++ b/docs/api/view-model/projection.md @@ -1,10 +1,8 @@ --- -id: view-model -title: View Model +id: projection +title: Projection --- -## View Model Projection - A view model projection is an object of the following structure: ```js @@ -24,8 +22,6 @@ const projection = { } ``` -### Event Handler - An event handler implementation receives the following arguments: | Argument Name | Description | @@ -37,7 +33,7 @@ An event handler implementation receives the following arguments: An event handler should return a new state object. -### Event Handler Context +## Context A view model event handler context is an object with the following fields: diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md new file mode 100644 index 0000000000..54b88d18db --- /dev/null +++ b/docs/api/view-model/resolver.md @@ -0,0 +1,4 @@ +--- +id: resolver +title: Resolver +--- diff --git a/website/sidebars.json b/website/sidebars.json index b004176450..fcb4df0e72 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -39,11 +39,31 @@ "type": "category", "label": "API", "items": [ - "api/command-handler", - "api/read-model-event-handler", - "api/read-model-resolver", - "api/read-model-connector", - "api/read-model-store", + { + "type": "category", + "label": "Aggregate", + "items": [ + "api/aggregate/command-handler", + "api/aggregate/projection" + ] + }, + { + "type": "category", + "label": "Read Model", + "items": [ + "api/read-model/projection", + "api/read-model/resolver", + "api/read-model/store", + "api/read-model/connector" + ] + }, + { + "type": "category", + "label": "View Model", + "items": [ + "api/view-model/projection" + ] + }, "api/event-store-adapter", "api/middleware", "api/api-handler", From bc79e0c8e64b4bc5910f7f3333780b82a044ca0b Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Wed, 1 Sep 2021 15:59:34 +0300 Subject: [PATCH 09/16] Fix broken links --- docs/api/aggregate/command-handler.md | 24 +++++++++---------- docs/api/aggregate/projection.md | 2 +- docs/api/middleware.md | 34 +++++++++++++-------------- docs/api/read-model/projection.md | 20 ++++++++-------- docs/api/read-model/resolver.md | 20 ++++++++-------- docs/api/view-model/projection.md | 12 +++++----- docs/read-side.md | 2 +- docs/tutorial.md | 8 +++---- 8 files changed, 61 insertions(+), 61 deletions(-) diff --git a/docs/api/aggregate/command-handler.md b/docs/api/aggregate/command-handler.md index 6bc8368552..40dfe128de 100644 --- a/docs/api/aggregate/command-handler.md +++ b/docs/api/aggregate/command-handler.md @@ -17,21 +17,21 @@ A command handler function has the following structure: A command handler implementation receives the following arguments: -| Argument Name | Description | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| state | The state object built by the aggregate [projection](../write-side.md#aggregate-projection-function). | -| command | An object that contains the incoming command's data. | -| context | An object that contains data and functions related to the current operation. | +| Argument Name | Description | +| ------------- | -------------------------------------------------------------------------------------------------------- | +| state | The state object built by the aggregate [projection](../../write-side.md#aggregate-projection-function). | +| command | An object that contains the incoming command's data. | +| context | An object that contains data and functions related to the current operation. | ## Context The `context` argument is an object with the following fields: -| Field Name | Description | -| ---------------- | -------------------------------------------------------------------------- | -| jwt | The JSON Web Token attached to the request. | -| aggregateVersion | The aggregate version identifier. | -| encrypt | The user-defined [encrypt](../advanced-techniques.md#encryption) function. | -| decrypt | The user-defined [decrypt](../advanced-techniques.md#encryption) function. | +| Field Name | Description | +| ---------------- | --------------------------------------------------------- | +| jwt | The JSON Web Token attached to the request. | +| aggregateVersion | The aggregate version identifier. | +| encrypt | The user-defined [encrypt](../../encryption.md) function. | +| decrypt | The user-defined [decrypt](../../encryption.md) function. | -This object can also contain additional fields added by [middleware](middleware.md). +This object can also contain additional fields added by [middleware](../../middleware.md). diff --git a/docs/api/aggregate/projection.md b/docs/api/aggregate/projection.md index cc3ec21f13..7020100cfd 100644 --- a/docs/api/aggregate/projection.md +++ b/docs/api/aggregate/projection.md @@ -27,6 +27,6 @@ An event handler implementation receives the following arguments: | Argument Name | Description | | ------------- | ------------------------------------------------------------- | | state | The aggregate state that is an object of arbitrary structure. | -| event | An [event](event.md) object. | +| event | An [event](../event.md) object. | An event handler should return a new state object. diff --git a/docs/api/middleware.md b/docs/api/middleware.md index df250c27d5..26c27afbe1 100644 --- a/docs/api/middleware.md +++ b/docs/api/middleware.md @@ -28,16 +28,16 @@ The middleware handler function receives the following arguments: | middlewareContext | Contains data that describes the currently processed operation. | | state | The state object built by the aggregate [projection](../write-side.md#aggregate-projection-function). | | command | An object that contains data about the incoming command. | -| context | The command [context](command-handler.md#context) object. | +| context | The command [context](aggregate/command-handler.md#context) object. | ### middlewareContext A command middleware handler's `middlewareContext` argument is an object with the following fields: -| Field Name | Description | -| ---------- | --------------------------------------------------------------- | +| Field Name | Description | +| ---------- | ---------------------------------------------------------------- | | req | Stores data that describes the currently processed HTTP request. | -| res | Contains the function used to configure the server's response. | +| res | Contains the function used to configure the server's response. | Both `req` and `res` fields are included only if the client sends the command. If the command is generated on the server (for example, by a saga or API handler), these fields are omitted. @@ -62,19 +62,19 @@ The middleware handler function receives the following arguments: | Parameter Name | Description | | ----------------- | ----------------------------------------------------------------------------------------------------- | | middlewareContext | Contains data that describes the currently processed operation. | -| store | Exposes [API](read-model-store.md) used to communicate with the read model's persistent data storage. | +| store | Exposes [API](read-model/store.md) used to communicate with the read model's persistent data storage. | | event | The incoming event object. | -| context | The read model projection [context](read-model-event-handler.md#context) object. | +| context | The read model projection [context](read-model/projection.md#context) object. | ### middlewareContext A projection middleware handler's `middlewareContext` argument is an object with the following fields: -| Field Name | Description | -| ------------- | --------------------------------------------------------------- | +| Field Name | Description | +| ------------- | ---------------------------------------------------------------- | | req | Stores data that describes the currently processed HTTP request. | -| res | Contains the function used to configure the server's response. | -| readModelName | The name of the processed read model. | +| res | Contains the function used to configure the server's response. | +| readModelName | The name of the processed read model. | ## Read Model Resolver Middleware @@ -97,17 +97,17 @@ The middleware handler function receives the following arguments: | Parameter Name | Description | | ----------------- | ----------------------------------------------------------------------------------------------------- | | middlewareContext | Contains data that describes the currently processed operation. | -| store | Exposes [API](read-model-store.md) used to communicate with the read model's persistent data storage. | +| store | Exposes [API](read-model/store.md) used to communicate with the read model's persistent data storage. | | params | An object that contains the request parameters as key-value pairs. | -| context | The read model resolver [context](read-model-resolver.md#context) object. | +| context | The read model resolver [context](read-model/resolver.md#context) object. | ### middlewareContext A projection middleware handler's `middlewareContext` argument is an object with the following fields: -| Field Name | Description | -| ------------- | --------------------------------------------------------------- | +| Field Name | Description | +| ------------- | ---------------------------------------------------------------- | | req | Stores data that describes the currently processed HTTP request. | -| res | Contains the function used to configure the server's response. | -| readModelName | The name of the processed read model. | -| resolverName | The name of the queried resolver. | +| res | Contains the function used to configure the server's response. | +| readModelName | The name of the processed read model. | +| resolverName | The name of the queried resolver. | diff --git a/docs/api/read-model/projection.md b/docs/api/read-model/projection.md index 0385839376..e362aa300c 100644 --- a/docs/api/read-model/projection.md +++ b/docs/api/read-model/projection.md @@ -13,19 +13,19 @@ async (store, event, context) => { An event handler implementation receives the following arguments: -| Argument Name | Description | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| store | Exposes [API](read-model-store.md) used to communicate with the read model's persistent data storage. | -| event | An object that contains the incoming event's data. | -| context | An object that contains data and functions related to the current operation. | +| Argument Name | Description | +| ------------- | -------------------------------------------------------------------------------------------------------- | +| store | Exposes [API](../read-model/store.md) used to communicate with the read model's persistent data storage. | +| event | An object that contains the incoming event's data. | +| context | An object that contains data and functions related to the current operation. | ## context The `context` argument is an object with the following fields: -| Field Name | Description | -| ---------- | -------------------------------------------------------------------------- | -| encrypt | The user-defined [encrypt](../advanced-techniques.md#encryption) function. | -| decrypt | The user-defined [decrypt](../advanced-techniques.md#encryption) function. | +| Field Name | Description | +| ---------- | --------------------------------------------------------- | +| encrypt | The user-defined [encrypt](../../encryption.md) function. | +| decrypt | The user-defined [decrypt](../../encryption.md) function. | -This object can also contain additional fields added by [middleware](middleware.md). +This object can also contain additional fields added by [middleware](../../middleware.md). diff --git a/docs/api/read-model/resolver.md b/docs/api/read-model/resolver.md index 25a20cb7d0..99bbc3ca30 100644 --- a/docs/api/read-model/resolver.md +++ b/docs/api/read-model/resolver.md @@ -15,19 +15,19 @@ async (store, params, context) => { A projection implementation receives the following arguments: -| Argument Name | Description | -| ------------- | ----------------------------------------------------------------------------------------------------- | -| store | Exposes [API](read-model-store.md) used to communicate with the read model's persistent data storage. | -| params | An object that contains the request parameters as key-value pairs. | -| context | An object that contains data and functions related to the current operation. | +| Argument Name | Description | +| ------------- | -------------------------------------------------------------------------------------------------------- | +| store | Exposes [API](../read-model/store.md) used to communicate with the read model's persistent data storage. | +| params | An object that contains the request parameters as key-value pairs. | +| context | An object that contains data and functions related to the current operation. | ## context The `context` argument is an object with the following fields: -| Field Name | Description | -| -------------- | ------------------------------------------------------------------------------- | -| jwt | The JSON Web Token attached to the request. | -| secretsManager | The application's [secrets manager](../advanced-techniques.md#storing-secrets). | +| Field Name | Description | +| -------------- | ------------------------------------------------------------------------- | +| jwt | The JSON Web Token attached to the request. | +| secretsManager | The application's [secrets manager](../../encryption.md#storing-secrets). | -This object can also contain additional fields added by [middleware](middleware.md). +This object can also contain additional fields added by [middleware](../../middleware.md). diff --git a/docs/api/view-model/projection.md b/docs/api/view-model/projection.md index 43b9a6266e..298d20c721 100644 --- a/docs/api/view-model/projection.md +++ b/docs/api/view-model/projection.md @@ -27,7 +27,7 @@ An event handler implementation receives the following arguments: | Argument Name | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | state | The view model's state that is an object of arbitrary structure. | -| event | An [event](event.md) object. | +| event | An [event](../event.md) object. | | args | Arguments attached to the request. | | context | An object that contains functions and data related to the current operation (see the [Event Handler Context](#event-handler-context) section.) | @@ -37,8 +37,8 @@ An event handler should return a new state object. A view model event handler context is an object with the following fields: -| Field Name | Description | -| ---------- | ------------------------------------------------------ | -| jwt | The JSON Web Token attached to the request. | -| encrypt | The user-defined [encrypt](../encryption.md) function. | -| decrypt | The user-defined [decrypt](../encryption.md) function. | +| Field Name | Description | +| ---------- | --------------------------------------------------------- | +| jwt | The JSON Web Token attached to the request. | +| encrypt | The user-defined [encrypt](../../encryption.md) function. | +| decrypt | The user-defined [decrypt](../../encryption.md) function. | diff --git a/docs/read-side.md b/docs/read-side.md index 9695f1fd0c..b2823a233c 100644 --- a/docs/read-side.md +++ b/docs/read-side.md @@ -126,7 +126,7 @@ We recommend that you store Read Model data in a denormalized form so that your A projection function is used to accumulate the event data in a **Read Model storage**. Each projection function receives the storage object and event information. The event information includes the aggregateID, timestamp, and payload. -You can use the [standard API](api/read-model-store.md) to communicate with the store. The code sample below demonstrates a Read Model projection function's implementation: +You can use the [standard API](api/read-model/store.md) to communicate with the store. The code sample below demonstrates a Read Model projection function's implementation: ```js [STORY_COMMENTED]: async ( diff --git a/docs/tutorial.md b/docs/tutorial.md index 40eba06b9a..1ba5d14df2 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -382,9 +382,9 @@ export default { ##### Used API: -- [store](api/read-model-store.md#read-model-store-interface) -- [store.defineTable](api/read-model-store.md#definetable) -- [store.insert](api/read-model-store.md#insert) +- [store](api/read-model/store.md) +- [store.defineTable](api/read-model/store.md#definetable) +- [store.insert](api/read-model/store.md#insert) The type of the physical store used to save data is defined by a Read Model connector: @@ -438,7 +438,7 @@ export default { ##### Used API: -- [store.find](api/read-model-store.md#find) +- [store.find](api/read-model/store.md#find) Register the created Read Model in the application configuration file: From 693b33ae5b703eab8d9eab4d7c3a5843ad2219b0 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 6 Sep 2021 14:41:16 +0300 Subject: [PATCH 10/16] Update read model projecton description --- docs/api/read-model/projection.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/api/read-model/projection.md b/docs/api/read-model/projection.md index e362aa300c..65ba8bd98b 100644 --- a/docs/api/read-model/projection.md +++ b/docs/api/read-model/projection.md @@ -3,11 +3,17 @@ id: projection title: Projection --- -A read model event handler function has the following structure: +A read model projection is an object of the following structure: ```js -async (store, event, context) => { - ... +const projection = { + // The *Init* function initializes the read model's persistent store. + Init: async (store) => { ... } + // An event handler function is associated with an event type. + // It receives the read model store and an incoming event + // and updates the store based on the event's data + [EVENT_TYPE1]: async (store, event, context) -> { ... } + [EVENT_TYPE2]: async (store, event, context) -> { ... } } ``` From 10d41cf574458ab440a5c53caabadec921db8840 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 6 Sep 2021 16:30:51 +0300 Subject: [PATCH 11/16] View model resolver API --- docs/api/view-model/resolver.md | 28 ++++++++++++++++++++++++++++ website/sidebars.json | 3 ++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index 54b88d18db..4d3cff3e35 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -2,3 +2,31 @@ id: resolver title: Resolver --- + +A view model resolver function has the following structure: + +```js +async(api, query, context) => { + ... + return { + data, + meta + } +} +``` + +## API + +## Query + +## Context + +```js +{ + jwt, // Optional + viewModel: { + name, + eventTypes + } +} +``` diff --git a/website/sidebars.json b/website/sidebars.json index fcb4df0e72..b2042cdb75 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -61,7 +61,8 @@ "type": "category", "label": "View Model", "items": [ - "api/view-model/projection" + "api/view-model/projection", + "api/view-model/resolver" ] }, "api/event-store-adapter", From a395b9a2c8bd2d6aed0de331f2f15c87483669ae Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 7 Sep 2021 10:31:51 +0300 Subject: [PATCH 12/16] Add document content --- docs/api/view-model/resolver.md | 34 ++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index 4d3cff3e35..c88913502d 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -6,27 +6,51 @@ title: Resolver A view model resolver function has the following structure: ```js + async(api, query, context) => { ... return { - data, - meta + data, // Built view model data. + meta // Meta data about the resolver execution results (see below). } } ``` +The `meta` object returned by a resolver should have the following structure: + +```js +{ + cursor, // The data cursor used to traverse the events included into the query result set. + eventTypes, // The list of event types available to the client. + aggregateIds, // List of aggregate IDs available to th client. +} +``` + ## API +The `API` argument provides is an object that contains the following API: + +| Function Name | Description | +| -------------- | ---------------------------------- | +| buildViewModel | Runs projection for the view model | + ## Query +The `query` argument is an object of the following field: + +| Field Name | Description | +| ------------- | -------------------------------------------------------- | +| aggregateIds | An array of aggregate IDs. | +| aggregateArgs | An object that contains arguments attached to the query. | + ## Context ```js { - jwt, // Optional + jwt, // The JSON web token attacked to the request (Optional). viewModel: { - name, - eventTypes + name, // The name of the view model. + eventTypes // The event types available to the view model. } } ``` From 6c9bf8fda7fcbbf938f87b4c41bfd1dc3cf9f7e3 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 7 Sep 2021 11:04:10 +0300 Subject: [PATCH 13/16] Sidebar, minor fixes --- docs/api/view-model/resolver.md | 2 ++ website/sidebars.json | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index c88913502d..cd45fb4809 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -45,6 +45,8 @@ The `query` argument is an object of the following field: ## Context +The `context` argument is an object of the following structure: + ```js { jwt, // The JSON web token attacked to the request (Optional). diff --git a/website/sidebars.json b/website/sidebars.json index b2042cdb75..14315e5f09 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -65,10 +65,12 @@ "api/view-model/resolver" ] }, + "api/saga", + "api/command", + "api/event", "api/event-store-adapter", "api/middleware", "api/api-handler", - "api/saga", "api/resolve-scripts", { "type": "category", From 2268a67556207e579b0642f78b05ce19ab98ab9f Mon Sep 17 00:00:00 2001 From: Eugeniy Burmistrov <37070809+EugeniyBurmistrov@users.noreply.github.com> Date: Wed, 8 Sep 2021 16:13:12 +0300 Subject: [PATCH 14/16] Typo --- docs/api/view-model/resolver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index cd45fb4809..2fbf2e6758 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -49,7 +49,7 @@ The `context` argument is an object of the following structure: ```js { - jwt, // The JSON web token attacked to the request (Optional). + jwt, // The JSON web token attached to the request (Optional). viewModel: { name, // The name of the view model. eventTypes // The event types available to the view model. From 4755c2556539f152ec7b6d8238238f7481265e4b Mon Sep 17 00:00:00 2001 From: Eugeniy Burmistrov <37070809+EugeniyBurmistrov@users.noreply.github.com> Date: Wed, 8 Sep 2021 16:14:11 +0300 Subject: [PATCH 15/16] Update resolver.md --- docs/api/view-model/resolver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index 2fbf2e6758..0112020068 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -22,7 +22,7 @@ The `meta` object returned by a resolver should have the following structure: { cursor, // The data cursor used to traverse the events included into the query result set. eventTypes, // The list of event types available to the client. - aggregateIds, // List of aggregate IDs available to th client. + aggregateIds, // List of aggregate IDs available to the client. } ``` From cb1a6ce0c1bb31ba08394a10de0ac14f6871b530 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 9 Sep 2021 17:06:15 +0300 Subject: [PATCH 16/16] Apply corrections --- docs/api/aggregate/command-handler.md | 12 ++++++------ docs/api/read-model/resolver.md | 2 +- docs/api/view-model/resolver.md | 20 +++++++------------- 3 files changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/api/aggregate/command-handler.md b/docs/api/aggregate/command-handler.md index 40dfe128de..0b22c621ce 100644 --- a/docs/api/aggregate/command-handler.md +++ b/docs/api/aggregate/command-handler.md @@ -27,11 +27,11 @@ A command handler implementation receives the following arguments: The `context` argument is an object with the following fields: -| Field Name | Description | -| ---------------- | --------------------------------------------------------- | -| jwt | The JSON Web Token attached to the request. | -| aggregateVersion | The aggregate version identifier. | -| encrypt | The user-defined [encrypt](../../encryption.md) function. | -| decrypt | The user-defined [decrypt](../../encryption.md) function. | +| Field Name | Description | +| ---------------- | ---------------------------------------------------------------------------------------------------------- | +| jwt | The JSON Web Token attached to the request. | +| aggregateVersion | The aggregate version that is a number incremented for each consequent event with the current aggregateId. | +| encrypt | The user-defined [encrypt](../../encryption.md) function. | +| decrypt | The user-defined [decrypt](../../encryption.md) function. | This object can also contain additional fields added by [middleware](../../middleware.md). diff --git a/docs/api/read-model/resolver.md b/docs/api/read-model/resolver.md index 99bbc3ca30..5a3d9c642e 100644 --- a/docs/api/read-model/resolver.md +++ b/docs/api/read-model/resolver.md @@ -13,7 +13,7 @@ async (store, params, context) => { } ``` -A projection implementation receives the following arguments: +A resolver implementation receives the following arguments: | Argument Name | Description | | ------------- | -------------------------------------------------------------------------------------------------------- | diff --git a/docs/api/view-model/resolver.md b/docs/api/view-model/resolver.md index 0112020068..1d20444fc7 100644 --- a/docs/api/view-model/resolver.md +++ b/docs/api/view-model/resolver.md @@ -11,24 +11,18 @@ async(api, query, context) => { ... return { data, // Built view model data. - meta // Meta data about the resolver execution results (see below). + meta: { // Metadata about the resolver execution results. + cursor, // The data cursor used to traverse the events included into the query result set. + eventTypes, // The list of event types available to the client. + aggregateIds, // List of aggregate IDs available to the client. + } } } ``` -The `meta` object returned by a resolver should have the following structure: - -```js -{ - cursor, // The data cursor used to traverse the events included into the query result set. - eventTypes, // The list of event types available to the client. - aggregateIds, // List of aggregate IDs available to the client. -} -``` - ## API -The `API` argument provides is an object that contains the following API: +The `API` argument is an object that contains the following API: | Function Name | Description | | -------------- | ---------------------------------- | @@ -36,7 +30,7 @@ The `API` argument provides is an object that contains the following API: ## Query -The `query` argument is an object of the following field: +The `query` argument is an object with the following fields: | Field Name | Description | | ------------- | -------------------------------------------------------- |