From 1ca3a0578115723fc7df6de5006c8e67bad6ddcf Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 13 Jan 2022 14:16:53 +0300 Subject: [PATCH 01/19] Document structure --- docs/api/resolve-context.md | 4 ++++ website/sidebars.json | 1 + 2 files changed, 5 insertions(+) create mode 100644 docs/api/resolve-context.md diff --git a/docs/api/resolve-context.md b/docs/api/resolve-context.md new file mode 100644 index 000000000..f6a20c3a4 --- /dev/null +++ b/docs/api/resolve-context.md @@ -0,0 +1,4 @@ +--- +id: resolve-context +title: ReSolve Context +--- diff --git a/website/sidebars.json b/website/sidebars.json index 14315e5f0..3c2ef2877 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -65,6 +65,7 @@ "api/view-model/resolver" ] }, + "api/resolve-context", "api/saga", "api/command", "api/event", From a6b1aee27d8cdae7cae1515ef3c8af60280d9209 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 13 Jan 2022 15:41:30 +0300 Subject: [PATCH 02/19] Draft content --- docs/api/resolve-context.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/api/resolve-context.md b/docs/api/resolve-context.md index f6a20c3a4..6ad8c13c0 100644 --- a/docs/api/resolve-context.md +++ b/docs/api/resolve-context.md @@ -2,3 +2,36 @@ id: resolve-context title: ReSolve Context --- + +The `resolve` context object is available to an API handler through the request (`req`) object. This object exposes the following API. + +**Objects:** + +| Field Name | Description | +| ------------------- | ----------- | +| `uploader` | | +| `eventstoreAdapter` | | +| `performanceTracer` | | + + +**Methods:** + +| Function Name | Description | +| ---------------- | ----------- | +| `executeCommand` | | +| `executeQuery` | | +| `executeSaga` | | +| `seedClientEnvs` | | +| `broadcastEvent` | | + +**Constants:** + +| Constant Name | Description | +| ----------------- | ----------- | +| `applicationName` | | +| `distDir` | | +| `jwtCookie` | | +| `rootPath` | | +| `staticDir` | | +| `staticPath` | | +| `staticRoutes?` | | From 6a44d36c5a973f8340dde521fa3e1043cc780e48 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 13 Jan 2022 16:55:49 +0300 Subject: [PATCH 03/19] Add `monitoring` to API table --- docs/api/resolve-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/resolve-context.md b/docs/api/resolve-context.md index 6ad8c13c0..32c1c8b9f 100644 --- a/docs/api/resolve-context.md +++ b/docs/api/resolve-context.md @@ -12,7 +12,7 @@ The `resolve` context object is available to an API handler through the request | `uploader` | | | `eventstoreAdapter` | | | `performanceTracer` | | - +| `monitoring` | | **Methods:** From 6df565715ccf16f19355d86fb150e91582f7b07a Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 24 Jan 2022 13:45:32 +0300 Subject: [PATCH 04/19] Intro, navigaton --- docs/api/api-handler.md | 47 ------------------------- docs/api/api-handler/api-handler.md | 47 +++++++++++++++++++++++++ docs/api/api-handler/resolve-context.md | 37 +++++++++++++++++++ website/sidebars.json | 9 ++++- 4 files changed, 92 insertions(+), 48 deletions(-) delete mode 100644 docs/api/api-handler.md create mode 100644 docs/api/api-handler/api-handler.md create mode 100644 docs/api/api-handler/resolve-context.md diff --git a/docs/api/api-handler.md b/docs/api/api-handler.md deleted file mode 100644 index 414bdb22c..000000000 --- a/docs/api/api-handler.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -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 object that provides access to reSolve API and metadata. | -| adapter | The name of the adapter used to handle the request (`"express"` or `"awslambda"`). | -| 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. | diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md new file mode 100644 index 000000000..70f9eee8d --- /dev/null +++ b/docs/api/api-handler/api-handler.md @@ -0,0 +1,47 @@ +--- +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. | +| `adapter` | The name of the adapter used to handle the request (`"express"` or `"awslambda"`). | +| `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. | diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md new file mode 100644 index 000000000..994d4e568 --- /dev/null +++ b/docs/api/api-handler/resolve-context.md @@ -0,0 +1,37 @@ +--- +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` | | +| `eventstoreAdapter` | | +| `performanceTracer` | | +| `monitoring` | | + +## Methods + +| Function Name | Description | +| ---------------- | ----------- | +| `executeCommand` | | +| `executeQuery` | | +| `executeSaga` | | + +## Constants + +| Constant Name | Description | +| ----------------- | ----------- | +| `applicationName` | | +| `distDir` | | +| `jwtCookie` | | +| `rootPath` | | +| `staticDir` | | +| `staticPath` | | +| `staticRoutes?` | | diff --git a/website/sidebars.json b/website/sidebars.json index 34983f924..ec73c1fbb 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -65,12 +65,19 @@ "api/view-model/resolver" ] }, + { + "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", From 2f4216e01c022e67dceb973c43187058230fb9e9 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 24 Jan 2022 17:14:34 +0300 Subject: [PATCH 05/19] Populate API tables --- docs/api/api-handler/resolve-context.md | 40 ++++++++++++------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index 994d4e568..ce049a97a 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -9,29 +9,29 @@ The `resolve` context object exposes the following API: ## Objects -| Field Name | Description | -| ------------------- | ----------- | -| `uploader` | | -| `eventstoreAdapter` | | -| `performanceTracer` | | -| `monitoring` | | +| 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` | | -| `executeQuery` | | -| `executeSaga` | | +| Function Name | Description | +| ---------------- | --------------------- | +| `executeCommand` | Emits a command. | +| `executeQuery` | Queries a read model. | +| `executeSaga` | | ## Constants -| Constant Name | Description | -| ----------------- | ----------- | -| `applicationName` | | -| `distDir` | | -| `jwtCookie` | | -| `rootPath` | | -| `staticDir` | | -| `staticPath` | | -| `staticRoutes?` | | +| 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. | +| `staticRoutes?` | `string[]` or `null` | | From e090e59b99eff91b2bd4c2b5dba0b7767aeba57c Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 25 Jan 2022 11:24:58 +0300 Subject: [PATCH 06/19] Remove req.adapter field description --- docs/api/api-handler/api-handler.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index 70f9eee8d..9d9971c52 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -21,7 +21,6 @@ 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. | -| `adapter` | The name of the adapter used to handle the request (`"express"` or `"awslambda"`). | | `method` | The request's HTTP method. | | `path` | The request URL's path part. | | `body` | The request body. | From 37cff9b45b7edcb9bf86808bc9fdacb75e5580b3 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 25 Jan 2022 11:35:32 +0300 Subject: [PATCH 07/19] Object result description --- docs/api/command.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/api/command.md b/docs/api/command.md index c8dfc764f..c57634984 100644 --- a/docs/api/command.md +++ b/docs/api/command.md @@ -3,6 +3,8 @@ id: command title: Command --- +## Command Object + A command is an object of the following structure: @@ -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) } ``` + +## Command Result Object + +A command result object has the following structure: + + + +```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) +} +``` + + From 8b9293e2ec115f20f6be7fc05a1827ae8c6d6209 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Tue, 25 Jan 2022 11:37:33 +0300 Subject: [PATCH 08/19] Extended descriptions and code samples --- docs/api/api-handler/resolve-context.md | 88 +++++++++++++++++++++---- 1 file changed, 74 insertions(+), 14 deletions(-) diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index ce049a97a..d9863d82d 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -18,20 +18,80 @@ The `resolve` context object exposes the following API: ## Methods -| Function Name | Description | -| ---------------- | --------------------- | -| `executeCommand` | Emits a command. | -| `executeQuery` | Queries a read model. | -| `executeSaga` | | +| 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 or view model query object. | Describes a query to execute. | + +#### Result + +A `promise` that resolves to a read model query result or view model query result 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. | -| `staticRoutes?` | `string[]` or `null` | | +| 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. | From dc20b584f2f1369ab5e0a49bcd739da2c2526a7b Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Wed, 26 Jan 2022 14:27:52 +0300 Subject: [PATCH 09/19] resolve context - comands queries and results reference --- docs/api/api-handler/resolve-context.md | 8 +++--- docs/api/read-model/query.md | 34 +++++++++++++++++++++++++ docs/api/view-model/query.md | 23 +++++++++++++++++ website/sidebars.json | 6 +++-- 4 files changed, 65 insertions(+), 6 deletions(-) create mode 100644 docs/api/read-model/query.md create mode 100644 docs/api/view-model/query.md diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index d9863d82d..f764ecb72 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -77,13 +77,13 @@ const myApiHandler = async (req, res) => { #### Arguments -| Argument Name | Type | Description | -| ------------- | ---------------------------------------------- | ----------------------------- | -| `query ` | A read model query or view model query object. | Describes a query to execute. | +| 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 or view model query result depending on the query object's type. +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 diff --git a/docs/api/read-model/query.md b/docs/api/read-model/query.md new file mode 100644 index 000000000..65c895898 --- /dev/null +++ b/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: + + + +```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. +} +``` + + + +## 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 +``` diff --git a/docs/api/view-model/query.md b/docs/api/view-model/query.md new file mode 100644 index 000000000..394a10aeb --- /dev/null +++ b/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: + + + +```js +{ + modelName, // (string) The name of a view model. + aggregateIds, // (string[] or '*') A list of aggregate IDs for which to process events. +} +``` + + + +## 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. diff --git a/website/sidebars.json b/website/sidebars.json index ec73c1fbb..f127f5220 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -54,7 +54,8 @@ "api/read-model/projection", "api/read-model/resolver", "api/read-model/store", - "api/read-model/connector" + "api/read-model/connector", + "api/read-model/query" ] }, { @@ -62,7 +63,8 @@ "label": "View Model", "items": [ "api/view-model/projection", - "api/view-model/resolver" + "api/view-model/resolver", + "api/view-model/query" ] }, { From 7be834f56864bcd81f2a14cb5a2c42c05d51116a Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 31 Jan 2022 15:37:54 +0300 Subject: [PATCH 10/19] Remove redundant draft file. --- docs/api/resolve-context.md | 37 ------------------------------------- 1 file changed, 37 deletions(-) delete mode 100644 docs/api/resolve-context.md diff --git a/docs/api/resolve-context.md b/docs/api/resolve-context.md deleted file mode 100644 index 32c1c8b9f..000000000 --- a/docs/api/resolve-context.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -id: resolve-context -title: ReSolve Context ---- - -The `resolve` context object is available to an API handler through the request (`req`) object. This object exposes the following API. - -**Objects:** - -| Field Name | Description | -| ------------------- | ----------- | -| `uploader` | | -| `eventstoreAdapter` | | -| `performanceTracer` | | -| `monitoring` | | - -**Methods:** - -| Function Name | Description | -| ---------------- | ----------- | -| `executeCommand` | | -| `executeQuery` | | -| `executeSaga` | | -| `seedClientEnvs` | | -| `broadcastEvent` | | - -**Constants:** - -| Constant Name | Description | -| ----------------- | ----------- | -| `applicationName` | | -| `distDir` | | -| `jwtCookie` | | -| `rootPath` | | -| `staticDir` | | -| `staticPath` | | -| `staticRoutes?` | | From 746d069e0bd69eca354f9f7dfeff5799b6502726 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Mon, 31 Jan 2022 15:40:06 +0300 Subject: [PATCH 11/19] Minor adjustments in code samples --- docs/api/api-handler/resolve-context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index f764ecb72..a139b04be 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -39,10 +39,10 @@ const myApiHandler = async (req, res) => { aggregateId: uuid(), payload: { name: itemName }, }) + ... } catch (e) { ... } - ... } ``` @@ -68,10 +68,10 @@ const myApiHandler = async (req, res) => { modelName: 'MyList', resolverName: 'all', }) + ... } catch (e) { ... } - ... } ``` From acaa3771820b24851061a662a9f7e5243a81feb9 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 3 Feb 2022 13:46:24 +0300 Subject: [PATCH 12/19] Missing document short descriptions. --- docs/api/api-handler/api-handler.md | 2 +- docs/api/api-handler/resolve-context.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index 9d9971c52..d82e4b714 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -1,7 +1,7 @@ --- id: api-handler title: API Handler -description: This document describes API used by API handlers. +description: This article describes the structure of an API handler function and its arguments. --- An API handler function has the following structure: diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index a139b04be..08981c68f 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -1,9 +1,10 @@ --- id: resolve-context title: ReSolve Context +description: The resolve context object is available to an API handler function through its request (req) argument. This object implements a communication layer between an API handler and the reSolve framework. --- -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 is available to an [API handler](api-handler.md) function through its [request (`req`)](api-handler.md#request) argument. This object implements a communication layer between an API handler and the reSolve framework. The `resolve` context object exposes the following API: From e49d14265e6af78e6762136b27b7539fe0a619b3 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 3 Feb 2022 13:58:29 +0300 Subject: [PATCH 13/19] Style and grammar --- docs/api/api-handler/api-handler.md | 8 ++++---- docs/api/api-handler/resolve-context.md | 2 +- docs/api/view-model/query.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index d82e4b714..00fba4d6f 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -16,21 +16,21 @@ The handler receives a request and response objects. See the sections below for ### Request -The request objects exposes the following fields: +The request object 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. | +| `path` | The request URL path. | | `body` | The request body. | -| `cookies` | An object that contains cookies as key-value pairs. | +| `cookies` | An object that contains the attached 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: +The request object exposes the following functions: | Function | Description | | -------------------------------------- | ------------------------------------------- | diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index 08981c68f..919d45d56 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -21,7 +21,7 @@ The `resolve` context object exposes the following API: | Function Name | Description | | ----------------------------------- | ----------------------------------- | -| [`executeCommand`](#executecommand) | Emits a command. | +| [`executeCommand`](#executecommand) | Emits a command on the server side. | | [`executeQuery`](#executequery) | Queries a read model or view model. | ### `executeCommand` diff --git a/docs/api/view-model/query.md b/docs/api/view-model/query.md index 394a10aeb..7d525e9ac 100644 --- a/docs/api/view-model/query.md +++ b/docs/api/view-model/query.md @@ -20,4 +20,4 @@ A view model query object has the following structure: ## 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. +A view model query result is a serializable value, whose type and internal structure depends on the [view model projection](projection.md)'s implementation. From 997e1f38a0d8c3729119530f43b8b500112d88cf Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Thu, 3 Feb 2022 14:02:01 +0300 Subject: [PATCH 14/19] Minor stylistic fix. --- docs/api/api-handler/api-handler.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index 00fba4d6f..609172f31 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -18,15 +18,15 @@ The handler receives a request and response objects. See the sections below for The request object 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 path. | -| `body` | The request body. | -| `cookies` | An object that contains the attached 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. | +| Field | Description | +| --------- | ---------------------------------------------------------------------------------------- | +| `resolve` | The [reSolve context](resolve-context.md) object that contains reSolve API and metadata. | +| `method` | The request's HTTP method. | +| `path` | The request URL path. | +| `body` | The request body. | +| `cookies` | An object that contains the attached 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 From ac44a0972d2fe2f69db79d2adc245df8203ed207 Mon Sep 17 00:00:00 2001 From: Eugeniy Burmistrov <37070809+EugeniyBurmistrov@users.noreply.github.com> Date: Fri, 4 Feb 2022 09:54:17 +0300 Subject: [PATCH 15/19] Apply suggestions from code review Co-authored-by: Albert Totten <49917542+albertov05@users.noreply.github.com> --- docs/api/api-handler/api-handler.md | 8 ++++---- docs/api/api-handler/resolve-context.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index 609172f31..b8b28ea52 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -12,7 +12,7 @@ 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. +The handler receives a request and response objects. See the sections below for information on the API exposed through these objects. ### Request @@ -34,10 +34,10 @@ The request object exposes the following functions: | Function | Description | | -------------------------------------- | ------------------------------------------- | -| `status(code)` | Specifiers the response status code. | -| `getHeader(key)` | Get a response header by key. | +| `status(code)` | Specifies the response status code. | +| `getHeader(key)` | Gets a response header by key. | | `setHeader(key, value)` | Sets a response header. | -| `text([content] [, encoding])` | Specifies content for a text-type response | +| `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. | diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index 919d45d56..c3bd58ce5 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -92,7 +92,7 @@ A `promise` that resolves to a [read model query result](../read-model/query.md# | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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). | +| `jwtCookie` | `object` | An object that contains [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. | From 490388f151f5951b88ac14c2590348bfa13c12ab Mon Sep 17 00:00:00 2001 From: Eugeniy Burmistrov <37070809+EugeniyBurmistrov@users.noreply.github.com> Date: Fri, 4 Feb 2022 10:26:37 +0300 Subject: [PATCH 16/19] Update docs/api/view-model/query.md Co-authored-by: Albert Totten <49917542+albertov05@users.noreply.github.com> --- docs/api/view-model/query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/view-model/query.md b/docs/api/view-model/query.md index 7d525e9ac..be1813773 100644 --- a/docs/api/view-model/query.md +++ b/docs/api/view-model/query.md @@ -20,4 +20,4 @@ A view model query object has the following structure: ## Result Object -A view model query result is a serializable value, whose type and internal structure depends on the [view model projection](projection.md)'s implementation. +A view model query result is a serializable value, whose type and internal structure depend on the [view model projection](projection.md)'s implementation. From 404318d4d687713d8465c5924cab6279f33bd831 Mon Sep 17 00:00:00 2001 From: Eugeniy Burmistrov <37070809+EugeniyBurmistrov@users.noreply.github.com> Date: Fri, 4 Feb 2022 10:50:25 +0300 Subject: [PATCH 17/19] Update docs/api/view-model/query.md Co-authored-by: Albert Totten <49917542+albertov05@users.noreply.github.com> --- docs/api/view-model/query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/view-model/query.md b/docs/api/view-model/query.md index be1813773..f03927573 100644 --- a/docs/api/view-model/query.md +++ b/docs/api/view-model/query.md @@ -11,7 +11,7 @@ A view model query object has the following structure: ```js { - modelName, // (string) The name of a view model. + modelName, // (string) The name of the view model. aggregateIds, // (string[] or '*') A list of aggregate IDs for which to process events. } ``` From f61a9ecb712f622f950b96b8167bec9079452f34 Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 4 Feb 2022 10:50:52 +0300 Subject: [PATCH 18/19] Apply suggestions to command.md --- docs/api/command.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/command.md b/docs/api/command.md index c57634984..59aadbd9e 100644 --- a/docs/api/command.md +++ b/docs/api/command.md @@ -15,7 +15,7 @@ A command is an object of the following structure: 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. - jwt // A JSON Web Token attached to the web request used to send the command. (optional) + jwt // Optional. A JSON Web Token attached to the web request used to send the command. } ``` @@ -30,10 +30,10 @@ A command result object has the following structure: ```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) + payload, // Optional. An object of arbitrary structure that contains data attached to the command. + timestamp?, // Optional. A number type field that stores the point in time when the command was received. + aggregateId, // Optional. A string that uniquely identifies an aggregate instance. + aggregateVersion, // Optional. A number that is incremented for each subsequent event with the current aggregateId. } ``` From a72779bfc5d97c1445e0320177041b27526f1d8e Mon Sep 17 00:00:00 2001 From: EugeniyBurmistrov Date: Fri, 4 Feb 2022 12:11:33 +0300 Subject: [PATCH 19/19] Apply editor's suggestions --- docs/api/api-handler/api-handler.md | 8 +++---- docs/api/api-handler/resolve-context.md | 32 ++++++++++++------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/api/api-handler/api-handler.md b/docs/api/api-handler/api-handler.md index b8b28ea52..d90ab7e25 100644 --- a/docs/api/api-handler/api-handler.md +++ b/docs/api/api-handler/api-handler.md @@ -34,13 +34,13 @@ The request object exposes the following functions: | Function | Description | | -------------------------------------- | ------------------------------------------- | -| `status(code)` | Specifies the response status code. | -| `getHeader(key)` | Gets a response header by key. | +| `status(code)` | Specifies the response status code. | +| `getHeader(key)` | Gets a response header by key. | | `setHeader(key, value)` | Sets a response header. | -| `text([content] [, encoding])` | Specifies content for a text-type response. | +| `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. | +| `file(content, filename [, encoding])` | Specifies a file to send as a 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. | diff --git a/docs/api/api-handler/resolve-context.md b/docs/api/api-handler/resolve-context.md index c3bd58ce5..4a75ffd60 100644 --- a/docs/api/api-handler/resolve-context.md +++ b/docs/api/api-handler/resolve-context.md @@ -1,7 +1,7 @@ --- id: resolve-context title: ReSolve Context -description: The resolve context object is available to an API handler function through its request (req) argument. This object implements a communication layer between an API handler and the reSolve framework. +description: The 'resolve' context object is available to an API handler function through its request (req) argument. This object implements a communication layer between an API handler and the reSolve framework. --- The `resolve` context object is available to an [API handler](api-handler.md) function through its [request (`req`)](api-handler.md#request) argument. This object implements a communication layer between an API handler and the reSolve framework. @@ -19,14 +19,14 @@ The `resolve` context object exposes the following API: ## Methods -| Function Name | Description | -| ----------------------------------- | ----------------------------------- | -| [`executeCommand`](#executecommand) | Emits a command on the server side. | -| [`executeQuery`](#executequery) | Queries a read model or view model. | +| Function Name | Description | +| ----------------------------------- | -------------------------------------- | +| [`executeCommand`](#executecommand) | Executes a command on the server side. | +| [`executeQuery`](#executequery) | Queries a read model or view model. | ### `executeCommand` -Emits a command on the server side. +Executes a command on the server side. #### Example @@ -49,9 +49,9 @@ const myApiHandler = async (req, res) => { #### Arguments -| Argument Name | Type | Description | -| ------------- | ------------------------------------------------- | ---------------------------- | -| `command` | A [command](../command.md#command-object) object. | Describes a command to emit. | +| Argument Name | Type | Description | +| ------------- | ------------------------------------------------- | ------------------------------- | +| `command` | A [command](../command.md#command-object) object. | Describes a command to execute. | #### Result @@ -88,11 +88,11 @@ A `promise` that resolves to a [read model query result](../read-model/query.md# ## 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. | +| 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 contains [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. | +| `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. |