GitHub Homepage Legal Notice

@server-state/types

Install using 

npm install @server-state/types

Exported Members

You can access these members by importing the module:

import { member } from '@server-state/types';

JsonSerializable

type JsonSerializable

Alias for: | null | number | string | boolean | { [key: string]: JsonSerializable | undefined } | Array<JsonSerializable>

Type that only allows JSON serializable data, i.e., where the following holds true:

const orig: JsonSerializable = // [...]

const new: JsonSerializable = JSON.parse(JSON.stringify(orig));

// orig and new have the exact same values

@see:

JSON.parse

@see:

JSON.stringify

BaseConfig

type BaseConfig

Alias for: Record<string, JsonSerializable>

The base configuration type that every extension configuration has to extend.

ExtensionObject

interface ExtensionObject

The object returned by an Extension function.

Properties

name

Type: string

The extension's human-readable name. Should be unique (e.g., a package name)

typeDefs ?

Type: TypeSource

typeDefs for an optional GraphQL schema extension for the Server State schema.

Also requires ExtensionObject.resolvers

resolvers ?

Type: IResolvers

Resolvers for the schema extensions defined in ExtensionObject.schema.

Required if schema is set.

Methods

onRemove (...) ?

function onRemove ( ) : Promise<void>

Function that gets called when the extension gets unloaded.

Should clean up all remaining running code (e.g., subscriptions to the pub/sub bus)

@returns:

Promise that resolves when cleanup is finished

Extension

type Extension < T : BaseConfig >

Alias for: ( config: T, api: ExtensionApi ) => ExtensionObject | Promise<ExtensionObject>

A Server State extension function.

PubSubHandleFunction

type PubSubHandleFunction

Alias for: ( ...args: JsonSerializable[] ) => void | JsonSerializable | Promise<JsonSerializable | void>

A function that handles requests triggered by ExtensionApi.request in ExtensionApi.handle

@param:

args - the additional arguments passed to ExtensionApi.request.

@returns:

Synchronously (or asynchronously, with a Promise that resolves to the value) a JsonSerializable that gets returned to the ExtensionApi.request call, or void ("returning" undefined)

@example: 

// let api: ExtensionApi;

await api.handle('REQUEST_SOME_INFO', (arg1, arg2) => `${arg1};${arg2}`);

// handler is now registered and can be used

const info = await api.request('REQUEST_SOME_INFO', 'a', 2);

console.log(info); // "a;2"

ExtensionApi

interface ExtensionApi

The APIs passed to an Extension as api

Properties

Methods

request (...)

function request (
   channel : string ,
   ... args : JsonSerializable[]
) : Promise<JsonSerializable | void>

Calls a subroutine defined by the given channel name and returns a promise that resolves with its return value.

Handled by handle

@param:

channel - The channel name that defines the subroutine

@param:

args - The args that get passed to handle

@returns:

Promise that resolves to the handler's callback return/resolve value

@example: 

// let api: ExtensionApi;

await api.handle('REQUEST_SOME_INFO', (arg1, arg2) => `${arg1};${arg2}`);

// handler is now registered and can be used

const info = await api.request('REQUEST_SOME_INFO', 'a', 2);

console.log(info); // "a;2"

@see:

handle

handle (...)

function handle (
   channel : string ,
   callback : PubSubHandleFunction
) : Promise<void>

Handles a request triggered by request.

Only awaits "active subscription", not execution!

@param:

channel - The channel to listen to. The channel defines the event.

@param:

callback - The callback's return (/resolve) value gets passed back to request

@returns:

Promise that resolves to Observable once the subscription is active

@example: 

// let api: ExtensionApi;

await api.handle('REQUEST_SOME_INFO', (arg1, arg2) => `${arg1};${arg2}`);

// handler is now registered and can be used

const info = await api.request('REQUEST_SOME_INFO', 'a', 2);

console.log(info); // "a;2"

@see:

request

subscribe (...)

function subscribe (
   channel : string
) : Promise<Observable<JsonSerializable>>

Subscribes to a channel on the event bus.

Only awaits "active subscription", not execution!

@param:

channel - the channel to subscribe to

@returns:

Promise that resolves to Observable once the subscription is active

subscribe (...)

function subscribe (
   ... channels : string[]
) : Promise<Observable<readonly [message: JsonSerializable, channel: string]>>

Subscribes to channels on the event bus.

Only awaits "active subscription", not execution!

@param:

channels - the channels to subscribe to

@returns:

an RXJS Observable which contains the message and the channel name

@returns:

Promise that resolves to Observable that emits [message, channelName] once the subscription is active

pSubscribe (...)

function pSubscribe (
   ... patterns : string[]
) : Promise<Observable<readonly [message: JsonSerializable, channel: string]>>

Subscribes to channels on the event bus using patterns.

@param:

patterns - the pattern(s) of channel(s) to subscribe to

@returns:

Promise that resolves to Observable that emits [message, channelName] once the subscription is active

publish (...)

function publish (
   channel : string ,
   message : JsonSerializable
) : Promise<void>

Publishes a message to a channel on the event bus.

@param:

channel - the channel to publish to

@param:

message - the message to publish

@returns:

Promise which resolves when the message was successfully published