Describe API for fundamental entities of reSolve

docs/api/command-handler.md → 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:
@@ -18,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
+## 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).

docs/api/aggregate/projection.md

@@ -0,0 +1,32 @@
+---
+id: projection
+title: Projection
+---
+
+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) => ...
+  ...
+}
+```
+
+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.

docs/api/command.md

@@ -0,0 +1,20 @@
+---
+id: command
+title: Command
+---
+
+A command is an object of the following structure:
+
+<!-- prettier-ignore-start -->
+
+```js
+{
+  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)
+}
+```
+
+<!-- prettier-ignore-end -->

docs/api/event.md

@@ -0,0 +1,20 @@
+---
+id: event
+title: Event
+---
+
+An event is an object of the following structure:
+
+<!-- prettier-ignore-start -->
+
+```js
+{
+  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)
+}
+```
+
+<!-- prettier-ignore-end -->

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.                                |

docs/api/read-model-connector.md → 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.
 ---
 

docs/api/read-model/projection.md

@@ -0,0 +1,37 @@
+---
+id: projection
+title: Projection
+---
+
+A read model projection is an object of the following structure:
+
+```js
+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) -> { ... }
+}
+```
+
+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.                             |
+
+## context
+
+The `context` argument is an object with the following fields:
+
+| 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).

docs/api/read-model-resolver.md → 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.
 ---
 
@@ -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).

docs/api/read-model-store.md → 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                                        |
 | --------------------------- | -------------------------------------------------- |

docs/api/view-model/projection.md

@@ -0,0 +1,44 @@
+---
+id: projection
+title: Projection
+---
+
+A view model projection is an object of the following structure:
+
+```js
+const projection = {
+  // 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
+  // and returns the updated state.
+  [EVENT_TYPE]: (state, event) => {
+    ...
+    return newState
+  }
+  [EVENT_TYPE2]: (state, event) => ...
+  [EVENT_TYPE3]: (state, event) => ...
+  ...
+}
+```
+
+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.
+
+## 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. |