Describe the reSolve context object and related API

docs/api/api-handler/api-handler.md

@@ -0,0 +1,46 @@
+---
+id: api-handler
+title: API Handler
+description: This document describes API used by API handlers.
+---
+
+An API handler function has the following structure:
+
+```js
+export default async (req, res) => {
+  // ...
+}
+```
+
+The handler receives a request and response objects. See the sections below for the information on the API exposed through these objects.
+
+### Request
+
+The request objects exposes the following fields:
+
+| Field     | Description                                                                                        |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| `resolve` | The [reSolve context](resolve-context.md) object that provides access to reSolve API and metadata. |
+| `method`  | The request's HTTP method.                                                                         |
+| `path`    | The request URL's path part.                                                                       |
+| `body`    | The request body.                                                                                  |
+| `cookies` | An object that contains cookies as key-value pairs.                                                |
+| `headers` | An object that contains the request's HTTP headers as key-value pairs.                             |
+| `query`   | An object that contains the request's query string parameters as key-value pairs.                  |
+
+### Response
+
+The request objects exposes the following functions:
+
+| Function                               | Description                                 |
+| -------------------------------------- | ------------------------------------------- |
+| `status(code)`                         | Specifiers the response status code.        |
+| `getHeader(key)`                       | Get a response header by key.               |
+| `setHeader(key, value)`                | Sets a response header.                     |
+| `text([content] [, encoding])`         | Specifies content for a text-type response  |
+| `json([content])`                      | Specifies content for a JSON-type response. |
+| `end([content] [, encoding])`          | Ends the response process.                  |
+| `file(content, filename [, encoding])` | Specifies a file to write to response.      |
+| `redirect([status,] path)`             | Specifies the redirect path.                |
+| `cookie(name, value [, options])`      | Specifies cookies to send to the client.    |
+| `clearCookie(name [, options])`        | Clears a cookie from the response.          |

docs/api/api-handler/resolve-context.md

@@ -0,0 +1,97 @@
+---
+id: resolve-context
+title: ReSolve Context
+---
+
+The `resolve` context object is available to an [API handler](api-handler.md) function through the [request (`req`)](api-handler.md#request) object. This object implements a communication layer between an API handler and the reSolve framework.
+
+The `resolve` context object exposes the following API:
+
+## Objects
+
+| Field Name          | Description                                                       |
+| ------------------- | ----------------------------------------------------------------- |
+| `uploader`          | Exposes the file upload API.                                      |
+| `eventstoreAdapter` | Exposes the [event store adapter API](../event-store-adapter.md). |
+| `performanceTracer` | Exposes the performance tracer API.                               |
+| `monitoring`        | Exposes the monitoring API.                                       |
+
+## Methods
+
+| Function Name                       | Description                         |
+| ----------------------------------- | ----------------------------------- |
+| [`executeCommand`](#executecommand) | Emits a command.                    |
+| [`executeQuery`](#executequery)     | Queries a read model or view model. |
+
+### `executeCommand`
+
+Emits a command on the server side.
+
+#### Example
+
+```js
+const myApiHandler = async (req, res) => {
+  const { resolve } = req
+  try {
+    const result = await resolve.executeCommand({
+      type: 'addItem',
+      aggregateName: 'MyItems',
+      aggregateId: uuid(),
+      payload: { name: itemName },
+    })
+    ...
+  } catch (e) {
+    ...
+  }
+}
+```
+
+#### Arguments
+
+| Argument Name | Type                                              | Description                  |
+| ------------- | ------------------------------------------------- | ---------------------------- |
+| `command`     | A [command](../command.md#command-object) object. | Describes a command to emit. |
+
+#### Result
+
+A `promise` that resolves to a [command result](../command.md#command-result-object) object.
+
+### `executeQuery`
+
+#### Example
+
+```js
+const myApiHandler = async (req, res) => {
+  const { resolve } = req
+  try {
+    const result = await resolve.executeQuery({
+      modelName: 'MyList',
+      resolverName: 'all',
+    })
+    ...
+  } catch (e) {
+    ...
+  }
+}
+```
+
+#### Arguments
+
+| Argument Name | Type                                                                                                                         | Description                   |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `query `      | A [read model query](../read-model/query.md#query-object) or [view model query](../view-model/query.md#query-object) object. | Describes a query to execute. |
+
+#### Result
+
+A `promise` that resolves to a [read model query result](../read-model/query.md#result-object) or [view model query result](../view-model/query.md#result-object) depending on the query object's type.
+
+## Constants
+
+| Constant Name     | Type     | Description                                                                                                                                                                     |
+| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `applicationName` | `string` | The reSolve application's name as specified in `package.json`.                                                                                                                  |
+| `distDir`         | `string` | The path to the WebPack `dist` directory within the application.                                                                                                                |
+| `jwtCookie`       | `object` | An object that contain [JWT cookie settings](../../application-configuration.md#jwtcookie) as specified in the [application configuration](../../application-configuration.md). |
+| `rootPath`        | `string` | The application's root URL path.                                                                                                                                                |
+| `staticDir`       | `string` | The path to a directory that contains static files.                                                                                                                             |
+| `staticPath`      | `string` | The base URL path for static file URLs.                                                                                                                                         |

docs/api/command.md

@@ -3,6 +3,8 @@ id: command
 title: Command
 ---
 
+## Command Object
+
 A command is an object of the following structure:
 
 <!-- prettier-ignore-start -->
@@ -12,9 +14,27 @@ A command is an object of the following structure:
   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)
+  payload, // An object of arbitrary structure that contains data attached to the command. 
   jwt // A JSON Web Token attached to the web request used to send the command. (optional)
 }
 ```
 
 <!-- prettier-ignore-end -->
+
+## Command Result Object
+
+A command result object has the following structure:
+
+<!-- prettier-ignore-start -->
+
+```js
+export type CommandResult = {
+  type, // A string that contains the command type name.
+  payload, // An object of arbitrary structure that contains data attached to the command. (optional)
+  timestamp?, // A number type field that stores the point in time when the command was received. (optional)
+  aggregateId, // A string that uniquely identifies an aggregate instance. (optional)
+  aggregateVersion, // A number that is incremented for each subsequent event with the current aggregateId. (optional)
+}
+```
+
+<!-- prettier-ignore-end -->

docs/api/read-model/query.md

@@ -0,0 +1,34 @@
+---
+id: query
+title: Query
+---
+
+## Query Object
+
+A read model query object has the following structure:
+
+<!-- prettier-ignore-start -->
+
+```js
+{
+  modelName, // (string) The name of a read model.
+  resolverName, // (string) The name of a read model resolver.
+  resolverArgs, // (object) Specifies resolver arguments as key-value pairs.
+  jwt, // (string, optional) A JSON Web Token used to authorize the query.
+}
+```
+
+<!-- prettier-ignore-end -->
+
+## Result Object
+
+A read model query result can be a value of any serializable type depending on the implementation of the queried read model resolver:
+
+```js title="common/read-models/shopping-lists.resolvers.js"
+const resolvers = {
+  all: async (store) => {
+    return await store.find('ShoppingLists', {}, null, { createdAt: 1 })
+  },
+}
+export default resolvers
+```

docs/api/view-model/query.md

@@ -0,0 +1,23 @@
+---
+id: query
+title: Query
+---
+
+## Query Object
+
+A view model query object has the following structure:
+
+<!-- prettier-ignore-start -->
+
+```js
+{
+  modelName, // (string) The name of a view model.
+  aggregateIds, // (string[] or '*') A list of aggregate IDs for which to process events.
+}
+```
+
+<!-- prettier-ignore-end -->
+
+## Result Object
+
+A view model query result is a serializable value, whose type and/or internal structure depends on the [view model projection](projection.md)'s implementation.

website/sidebars.json

@@ -54,23 +54,32 @@
               "api/read-model/projection",
               "api/read-model/resolver",
               "api/read-model/store",
-              "api/read-model/connector"
+              "api/read-model/connector",
+              "api/read-model/query"
             ]
           },
           {
             "type": "category",
             "label": "View Model",
             "items": [
               "api/view-model/projection",
-              "api/view-model/resolver"
+              "api/view-model/resolver",
+              "api/view-model/query"
+            ]
+          },
+          {
+            "type": "category",
+            "label": "API Handler",
+            "items": [
+              "api/api-handler/api-handler",
+              "api/api-handler/resolve-context"
             ]
           },
           "api/saga",
           "api/command",
           "api/event",
           "api/event-store-adapter",
           "api/middleware",
-          "api/api-handler",
           "api/resolve-scripts",
           {
             "type": "category",