Skip to main content

Module: @divine/web-service

Enumerations​

Classes​

Interfaces​

Type aliases​

RPCClient​

Ζ¬ RPCClient<M>: { [K in keyof M]: Function }

The RPC client API. Used by clients to call an RPC method.

Type parameters​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).

Defined in​

web-service/src/rpc.ts:28


RPCClientProxy​

Ζ¬ RPCClientProxy<M>: (method: keyof M, options: Required<RPCEndpointOptions>, params: RPCParamsType) => Promise<RPCResultType>

Type parameters​

NameTypeDescription
Mextends 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​
NameTypeDescription
methodkeyof MThe name of the RPC method to invoke.
optionsRequired<RPCEndpointOptions>Contains the RPC method endpoint in the path property.
paramsRPCParamsTypeRPC method parameters to be POST'ed.
Returns​

Promise<RPCResultType>

The response as receieved from the RPC serivce.

Defined in​

web-service/src/rpc.ts:109


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​

NameTypeDescription
Mextends 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​

web-service/src/rpc.ts:68


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​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).
Kextends keyof M-

Defined in​

web-service/src/rpc.ts:14


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​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).
Kextends keyof M-

Defined in​

web-service/src/rpc.ts:21


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​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).

Defined in​

web-service/src/rpc.ts:37


RPCSeviceProxy​

Ζ¬ RPCSeviceProxy<M>: (method: keyof M, options: Required<RPCEndpointOptions>, args: WebArguments, fn: (params: RPCParamsType) => Promise<RPCResultType>) => Promise<RPCResultType>

Type parameters​

NameTypeDescription
Mextends 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​
NameTypeDescription
methodkeyof MThe name of the RPC method that should be invoked.
optionsRequired<RPCEndpointOptions>Contains the configured options for the RPC endpoint.
argsWebArgumentsIncoming 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​

web-service/src/rpc.ts:136


WebErrorHandler​

Ζ¬ WebErrorHandler<Context>: (err: Error, context: Context) => Promise<WebResponse>

Type parameters​

NameDescription
ContextThe type of the WebService context.

Type declaration​

β–Έ (err, context): Promise<WebResponse>

A custom error handler.

Parameters​
NameTypeDescription
errErrorThe error that caused the handler to be invoked.
contextContextThe 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​

web-service/src/rpc.ts:42


RPC_DISABLE_KEEPALIVE​

β€’ Const RPC_DISABLE_KEEPALIVE: null

The value to specify if keep-alive for event streams should be disabled.

Defined in​

web-service/src/rpc.ts:45

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​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).

Parameters​

NameTypeDescription
configRPCEndpoints<M>RPC endpoint configuration to generate a client API for.
clientProxyRPCClientProxy<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​

web-service/src/rpc.ts:173


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​

NameTypeDescription
Mextends RPCMethods<M>The interface that defines all RPC method request and response types (as tuples).
ContextContextThe WebService context type.

Parameters​

NameTypeDescription
configRPCEndpoints<M>RPC endpoint configuration to generate a client API for.
implRPCServiceCtor<Context, M>An RPC service class. A new instance will be constructed for each incoming request.
serviceProxyRPCSeviceProxy<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​

web-service/src/rpc.ts:220

β–Έ 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​

NameType
Mextends RPCMethods<M>

Parameters​

NameTypeDescription
configRPCEndpoints<M>RPC endpoint configuration to generate a client API for.
implRPCService<M>An RPC service instance (which may be stateful). Its methods will be invoked directly.
serviceProxyRPCSeviceProxy<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.

Defined in​

web-service/src/rpc.ts:256