diff --git a/docs/api/api-handler.md b/docs/api/api-handler.md deleted file mode 100644 index 414bdb22cd..0000000000 --- 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 0000000000..d90ab7e25a --- /dev/null +++ b/docs/api/api-handler/api-handler.md @@ -0,0 +1,46 @@ +--- +id: api-handler +title: API Handler +description: This article describes the structure of an API handler function and its arguments. +--- + +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 information on the API exposed through these objects. + +### Request + +The request object exposes the following fields: + +| 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 + +The request object exposes the following functions: + +| Function | Description | +| -------------------------------------- | ------------------------------------------- | +| `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. | +| `json([content])` | Specifies content for a JSON-type response. | +| `end([content] [, encoding])` | Ends the response process. | +| `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 new file mode 100644 index 0000000000..4a75ffd606 --- /dev/null +++ b/docs/api/api-handler/resolve-context.md @@ -0,0 +1,98 @@ +--- +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 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: + +## 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) | Executes a command on the server side. | +| [`executeQuery`](#executequery) | Queries a read model or view model. | + +### `executeCommand` + +Executes 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 execute. | + +#### 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 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. | diff --git a/docs/api/command.md b/docs/api/command.md index c8dfc764f4..59aadbd9e0 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,8 +14,26 @@ 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) - jwt // A JSON Web Token attached to the web request used to send the command. (optional) + payload, // An object of arbitrary structure that contains data attached to the command. + jwt // Optional. A JSON Web Token attached to the web request used to send the command. +} +``` + + + +## 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, // 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. } ``` diff --git a/docs/api/read-model/query.md b/docs/api/read-model/query.md new file mode 100644 index 0000000000..65c8958984 --- /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 0000000000..f03927573f --- /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 the 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 internal structure depend on the [view model projection](projection.md)'s implementation. diff --git a/website/sidebars.json b/website/sidebars.json index 34983f9241..f127f52203 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,16 @@ "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", @@ -70,7 +80,6 @@ "api/event", "api/event-store-adapter", "api/middleware", - "api/api-handler", "api/resolve-scripts", { "type": "category",