Module: @divine/web-service
Enumerationsβ
Classesβ
- CORSFilter
- EventStreamResponse
- WebArguments
- WebError
- WebFilterBase
- WebRequest
- WebResourceBase
- WebResponse
- WebServer
- WebService
Interfacesβ
- CORSFilterParams
- EventAttributes
- RPCEndpointOptions
- RPCServiceCtor
- StartOptions
- UserAgent
- WebFilter
- WebFilterCtor
- WebResource
- WebResourceCtor
- WebResponseHeaders
- WebServiceConfig
Type aliasesβ
RPCClientβ
Ζ¬ RPCClient<M>: { [K in keyof M]: Function }
The RPC client API. Used by clients to call an RPC method.
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Defined inβ
RPCClientProxyβ
Ζ¬ RPCClientProxy<M>: (method: keyof M, options: Required<RPCEndpointOptions>, params: RPCParamsType) => Promise<RPCResultType>
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Type declarationβ
βΈ (method, options, params): Promise<RPCResultType>
This function is should issue an HTTP POST request to the remote server and return the response.
A minimal implementation using @divine/uri could look like this:
interface MyAPI {
hello: [ { who?: string }, { greeting: string } ];
}
const clientProxy: RPCClientProxy<MyAPI> = (method, options, params) =>
new URI(options.path, 'http://api.example.com/my-api/').append(params);
Parametersβ
| Name | Type | Description |
|---|---|---|
method | keyof M | The name of the RPC method to invoke. |
options | Required<RPCEndpointOptions> | Contains the RPC method endpoint in the path property. |
params | RPCParamsType | RPC method parameters to be POST'ed. |
Returnsβ
Promise<RPCResultType>
The response as receieved from the RPC serivce.
Defined inβ
RPCEndpointsβ
Ζ¬ RPCEndpoints<M>: Record<keyof M, RPCEndpointOptions | null>
RPC endpoint configuration. For each RPC method (the key) this interface contains either an RPCEndpointOptions
object or null for defaults.
This object is the run-time (JavaScript) view of the RPC service API. It's important that every RPC method is present
in this object, even if its configuration is null, becasue this is the only source of method names for JavaScript.
Both createRPCClient and createRPCService use this object as input when creating the RPC client or service
proxy.
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). This is the compile-time (TypeScript) view of the RPC service API. |
Defined inβ
RPCParamsβ
Ζ¬ RPCParams<M, K>: M[K] extends [infer A, infer _B] ? A : never
Given the compile-time RPC service API interface and a method name, extracs the request parameters.
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
K | extends keyof M | - |
Defined inβ
RPCResultβ
Ζ¬ RPCResult<M, K>: M[K] extends [infer _A, infer B] ? B : never
Given the compile-time RPC service API interface and a method name, extracs the result/response type.
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
K | extends keyof M | - |
Defined inβ
RPCServiceβ
Ζ¬ RPCService<M>: { [K in keyof M]: Function }
The RPC service API. The server should implement this API to handle incoming RPC method calls.
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Defined inβ
RPCSeviceProxyβ
Ζ¬ RPCSeviceProxy<M>: (method: keyof M, options: Required<RPCEndpointOptions>, args: WebArguments, fn: (params: RPCParamsType) => Promise<RPCResultType>) => Promise<RPCResultType>
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Type declarationβ
βΈ (method, options, args, fn): Promise<RPCResultType>
This function should load the request parameters from WebArguments.body and invoke the callback function.
This is a great place to perform input validation (perhaps using a schema), authenticate the client somehow or add
custom response headers. If an AsyncIterable is returned, it will automatically be wrapped in an EventStreamResponse,
but otherwise, you free to constuct the response as you wish.
A minimal implementation could look like this:
interface MyAPI {
hello: [ { who?: string }, { greeting: string } ];
}
const serviceProxy: RPCSeviceProxy<MyAPI> = async (method, options, args, fn) =>
fn(await args.body());
Parametersβ
| Name | Type | Description |
|---|---|---|
method | keyof M | The name of the RPC method that should be invoked. |
options | Required<RPCEndpointOptions> | Contains the configured options for the RPC endpoint. |
args | WebArguments | Incoming HTTP request arguments. You should at least load the body from it. |
fn | (params: RPCParamsType) => Promise<RPCResultType> | The RPC service method that should be invoked with the request parameters. |
Returnsβ
Promise<RPCResultType>
The return value of the fn service method, either directly or wrapped in a WebResponse.
Defined inβ
WebErrorHandlerβ
Ζ¬ WebErrorHandler<Context>: (err: Error, context: Context) => Promise<WebResponse>
Type parametersβ
| Name | Description |
|---|---|
Context | The type of the WebService context. |
Type declarationβ
βΈ (err, context): Promise<WebResponse>
A custom error handler.
Parametersβ
| Name | Type | Description |
|---|---|---|
err | Error | The error that caused the handler to be invoked. |
context | Context | The WebService context. |
Returnsβ
Promise<WebResponse>
A response that should be sent back to the client.
Defined inβ
web-service/src/resource.ts:15
WebResponsesβ
Ζ¬ WebResponses: null | WebResponse | NodeJS.ReadableStream | Buffer | string | number | bigint | boolean | Date | object
A union of all types a WebResource method may return.
Defined inβ
web-service/src/response.ts:336
Variablesβ
EVENT_IDβ
β’ Const EVENT_ID: typeof EVENT_ID
A symbol in EventAttributes representing the event's id field
Defined inβ
web-service/src/helpers.ts:151
EVENT_RETRYβ
β’ Const EVENT_RETRY: typeof EVENT_RETRY
A symbol in EventAttributes representing the event's retry field
Defined inβ
web-service/src/helpers.ts:157
EVENT_TYPEβ
β’ Const EVENT_TYPE: typeof EVENT_TYPE
A symbol in EventAttributes representing the event's event field
Defined inβ
web-service/src/helpers.ts:154
RPC_DEFAULT_KEEPALIVEβ
β’ Const RPC_DEFAULT_KEEPALIVE: 10000
The default keep-alive time for event streams, in milliseconds (10 s).
Defined inβ
RPC_DISABLE_KEEPALIVEβ
β’ Const RPC_DISABLE_KEEPALIVE: null
The value to specify if keep-alive for event streams should be disabled.
Defined inβ
Functionsβ
createRPCClientβ
βΈ createRPCClient<M>(config, clientProxy): RPCClient<M>
Enumerates all keys in the RPCEndpoints object and generates an RPCClient.
Example usage:
interface MyAPI {
hello: [ { who?: string; }, { greeting: string } ];
}
const MyAPI: RPCEndpoints<MyAPI> = {
hello: null,
}
const myAPI = createRPCClient(MyAPI, async (method, options, params) =>
new URI(options.path, 'http://api.example.com/my-api/').append(params));
const { greeting } = await myAPI.hello({ who: 'beautiful' });
console.log(greeting);
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Parametersβ
| Name | Type | Description |
|---|---|---|
config | RPCEndpoints<M> | RPC endpoint configuration to generate a client API for. |
clientProxy | RPCClientProxy<M> | Utility function that makes the actual HTTP request. |
Returnsβ
RPCClient<M>
A class that implements the client-side view of the RPC service API.
Defined inβ
createRPCServiceβ
βΈ createRPCService<M, Context>(config, impl, serviceProxy): WebResourceCtor<Context>[]
Enumerates all keys in the RPCEndpoints object and generates an array of WebResource classes which will invoke the RPC service methods provided.
Example usage:
interface MyAPI {
hello: [ { who?: string; }, { greeting: string } ];
}
const MyAPI: RPCEndpoints<MyAPI> = {
hello: null,
}
class MyAPIService implements RPCService<MyAPI> {
async hello({ who }: RPCParams<MyAPI, 'hello'>): Promise<RPCResult<MyAPI, 'hello'>> {
return { greeting: `Hello, ${who ?? 'World'}!` };
}
}
const ws = new WebService(null)
.addResources(createRPCService(MyAPI, MyAPIService,
async (method, options, args, fn) => fn(await args.body())));
Type parametersβ
| Name | Type | Description |
|---|---|---|
M | extends RPCMethods<M> | The interface that defines all RPC method request and response types (as tuples). |
Context | Context | The WebService context type. |
Parametersβ
| Name | Type | Description |
|---|---|---|
config | RPCEndpoints<M> | RPC endpoint configuration to generate a client API for. |
impl | RPCServiceCtor<Context, M> | An RPC service class. A new instance will be constructed for each incoming request. |
serviceProxy | RPCSeviceProxy<M> | A function that extracts the request parameters, calls the RPC service method and retuns the result. |
Returnsβ
WebResourceCtor<Context>[]
An array of WebResource classes that should be registered to a WebService via WebService.addResources.
Defined inβ
βΈ createRPCService<M>(config, impl, serviceProxy): WebResourceCtor<unknown>[]
Enumerates all keys in the RPCEndpoints object and generates an array of WebResource classes which will invoke the RPC service methods provided.
Example usage:
interface MyAPI {
hello: [ { who?: string; }, { greeting: string } ];
}
const MyAPI: RPCEndpoints<MyAPI> = {
hello: null,
}
const myAPIService = new class implements RPCService<MyAPI> {
async hello({ who }: RPCParams<MyAPI, 'hello'>): Promise<RPCResult<MyAPI, 'hello'>> {
return { greeting: `Hello, ${who ?? 'World'}!` };
}
}
const ws = new WebService(null)
.addResources(createRPCService(MyAPI, myAPIService,
async (method, options, args, fn) => fn(await args.body())));
- @template M The interface that defines all RPC method request and response types (as tuples).
Type parametersβ
| Name | Type |
|---|---|
M | extends RPCMethods<M> |
Parametersβ
| Name | Type | Description |
|---|---|---|
config | RPCEndpoints<M> | RPC endpoint configuration to generate a client API for. |
impl | RPCService<M> | An RPC service instance (which may be stateful). Its methods will be invoked directly. |
serviceProxy | RPCSeviceProxy<M> | A function that extracts the request parameters, calls the RPC service method and retuns the result. |
Returnsβ
WebResourceCtor<unknown>[]
An array of WebResource classes that should be registered to a WebService via WebService.addResources.