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 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 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're 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: WebResponse | BasicTypes | Date | URI | NodeJS.ReadableStream | Buffer | AsyncIterable<BasicTypes | undefined>
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:152
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:158
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:155
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 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())));
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. |
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 addResources.