Class Procedure<Input, Output>

A simple abstraction of a procedure (the P in RPC). Allows you to turn a function or callback into a procedure, which can be called via the transport specified.

See

TypedEmitter

Type Parameters

Input = undefined

Type of input parameter the procedure accepts. Defaults to undefined.
Output = undefined

Type of output value the procedure returns. Defaults to undefined.

Hierarchy

TypedEventEmitter<ProcedureEvents<Input>, this>
- Procedure

Implements

ProcedureDefinitionOptions

Constructors

constructor

new Procedure<Input, Output>(callback: ((input: Input) => Output), options??: Partial<ProcedureDefinitionOptions>): Procedure<Input, Output>
Initializes a new Procedure.
Type Parameters
- Input = undefined
  
  Type of input parameter the procedure accepts. Defaults to undefined.
- Output = undefined
  
  Type of output value the procedure returns. Defaults to undefined.
Parameters
- callback: ((input: Input) => Output)
  
  The underlying callback function powering the procedure itself. The callback may be asynchronous.
  - - (input: Input): Output
    - Parameters
      
      input: Input
      
      Returns Output
- Optional options: Partial<ProcedureDefinitionOptions> = {}
  
  Options for a Procedure. Defaults to {}.
Returns Procedure<Input, Output>
Overrides (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; })<Input>.constructor
- Defined in src/index.ts:135

Properties

`Private` `Optional` #endpoint

#endpoint?: string

`Private` `Optional` #uuid

#uuid?: string

`Protected` callback

callback: ((input: Input) => Output)

Type declaration

- (input: Input): Output
- The underlying callback function powering the procedure itself. The callback may be asynchronous.
  Parameters
  - input: Input
  Returns Output

`Protected` options

options: ProcedureDefinitionOptions

The options in use by the Procedure, including defaults.

`Protected` sockets

sockets: Socket[] = []

The underlying nanomsg sockets used for data transmission.

Accessors

endpoint

get endpoint(): undefined | string
The endpoint at which the Procedure, when bound, can be called.

Returns undefined | string
- Defined in src/index.ts:47
set endpoint(value: undefined | string): void
Parameters
- value: undefined | string
Returns void
- Defined in src/index.ts:50

extensionCodec

get extensionCodec(): undefined | ExtensionCodec<undefined>
An optional msgpack ExtensionCodec to use for encoding and decoding messages.

Returns undefined | ExtensionCodec<undefined>
Implementation of ProcedureDefinitionOptions.extensionCodec
- Defined in src/index.ts:101
set extensionCodec(value: undefined | ExtensionCodec<undefined>): void
An optional msgpack ExtensionCodec to use for encoding and decoding messages.
Parameters
- value: undefined | ExtensionCodec<undefined>
Returns void
Implementation of ProcedureDefinitionOptions.extensionCodec
- Defined in src/index.ts:104

ignoreUndefinedProperties

get ignoreUndefinedProperties(): boolean
Whether or not to ignore undefined properties of objects passed to or from a Procedure. Defaults to true. When true on a Procedure, only affects properties of input parameters. When true on a call, only affects properties of the return value.

Remarks
The procedure.js library uses the msgpack serialization format for encoding JavaScript objects and values for transmission to and from remote procedures. The JavaScript implementation of msgpack maps undefined to null. This means that when passing objects in or out of a Procedure (i.e. as a parameter or return value), any properties defined as undefined will evaluate to null on receipt. ignoreUndefinedProperties aims to alleviate this by signalling msgpack to ignore undefined properties from objects before they are encoded, allowing undefined to be evaluated as undefined and null to be evaluated as null. This operation incurs some overhead, and means that code relying on the presence of a property to infer meaning may not operate as expected.

See
null and undefined properties

Returns boolean
Implementation of ProcedureDefinitionOptions.ignoreUndefinedProperties
- Defined in src/index.ts:121
set ignoreUndefinedProperties(value: boolean): void
Whether or not to ignore undefined properties of objects passed to or from a Procedure. Defaults to true. When true on a Procedure, only affects properties of input parameters. When true on a call, only affects properties of the return value.

Remarks
The procedure.js library uses the msgpack serialization format for encoding JavaScript objects and values for transmission to and from remote procedures. The JavaScript implementation of msgpack maps undefined to null. This means that when passing objects in or out of a Procedure (i.e. as a parameter or return value), any properties defined as undefined will evaluate to null on receipt. ignoreUndefinedProperties aims to alleviate this by signalling msgpack to ignore undefined properties from objects before they are encoded, allowing undefined to be evaluated as undefined and null to be evaluated as null. This operation incurs some overhead, and means that code relying on the presence of a property to infer meaning may not operate as expected.

See
null and undefined properties
Parameters
- value: boolean
Returns void
Implementation of ProcedureDefinitionOptions.ignoreUndefinedProperties
- Defined in src/index.ts:124

optionalParameterSupport

get optionalParameterSupport(): boolean
Whether or not to enable optional parameter support. Defaults to true. When true on a Procedure, a null input parameter will be coerced to undefined. When true for a call, a null return value will be coerced to undefined.

Remarks
The procedure.js library uses the msgpack serialization format for encoding JavaScript objects and values for transmission to and from remote procedures. The JavaScript implementation of msgpack maps undefined to null. For procedures which accept optional parameters, this is problematic. It could also be an issue if you depend on the return value of a procedure to conditionally be undefined, for the convenience of passing the return value into an optional parameter of another function call. optionalParameterSupport aims to alleviate these issues by mapping null to undefined for the input and output of your Procedure calls.

See
- ignoreUndefinedProperties
- Optional parameter support
Returns boolean
Implementation of ProcedureDefinitionOptions.optionalParameterSupport
- Defined in src/index.ts:111
set optionalParameterSupport(value: boolean): void
Whether or not to enable optional parameter support. Defaults to true. When true on a Procedure, a null input parameter will be coerced to undefined. When true for a call, a null return value will be coerced to undefined.

Remarks
The procedure.js library uses the msgpack serialization format for encoding JavaScript objects and values for transmission to and from remote procedures. The JavaScript implementation of msgpack maps undefined to null. For procedures which accept optional parameters, this is problematic. It could also be an issue if you depend on the return value of a procedure to conditionally be undefined, for the convenience of passing the return value into an optional parameter of another function call. optionalParameterSupport aims to alleviate these issues by mapping null to undefined for the input and output of your Procedure calls.

See
- ignoreUndefinedProperties
- Optional parameter support
Parameters
- value: boolean
Returns void
Implementation of ProcedureDefinitionOptions.optionalParameterSupport
- Defined in src/index.ts:114

`Protected` uuid

get uuid(): undefined | string
A v5 uuid generated from endpoint, used to identify ping requests.

Returns undefined | string
- Defined in src/index.ts:58
set uuid(value: undefined | string): void
Parameters
- value: undefined | string
Returns void
- Defined in src/index.ts:61

verbose

get verbose(): boolean
Whether or not to output errors and events to the console. Defaults to false.

Returns boolean
Implementation of ProcedureDefinitionOptions.verbose
- Defined in src/index.ts:78
set verbose(value: boolean): void
Whether or not to output errors and events to the console. Defaults to false.
Parameters
- value: boolean
Returns void
Implementation of ProcedureDefinitionOptions.verbose
- Defined in src/index.ts:81

workers

get workers(): number
The number of workers to spin up for the Procedure. Useful for procedures which may take a long time to complete. Will be clamped between 1 and Number.MAX_SAFE_INTEGER inclusive. Defaults to 1.

Returns number
Implementation of ProcedureDefinitionOptions.workers
- Defined in src/index.ts:88
set workers(value: number): void
The number of workers to spin up for the Procedure. Useful for procedures which may take a long time to complete. Will be clamped between 1 and Number.MAX_SAFE_INTEGER inclusive. Defaults to 1.
Parameters
- value: number
Returns void
Implementation of ProcedureDefinitionOptions.workers
- Defined in src/index.ts:91

Methods

`Private` #emitAndLogData

#emitAndLogData(data: Input): void
Emits and optionally logs given input data.
Parameters
- data: Input
  
  The input data to emit and log.
Returns void
- Defined in src/index.ts:391

`Private` #emitAndLogError

#emitAndLogError(message: string, error?: ProcedureError): void
Emits and optionally logs a given error.
Parameters
- message: string
  
  A custom error message describing the cause of the error. The message will be concatenated with the Procedure's endpoint.
- Optional error: ProcedureError
  
  The error.
Returns void
- Defined in src/index.ts:420

`Private` #emitAndLogUnbind

#emitAndLogUnbind(): void
Emits and optionally logs the unbind event.

See
unbind

Returns void
- Defined in src/index.ts:406

`Private` #logSocketClose

#logSocketClose(): void
Optionally logs the close event of the Procedure's underlying sockets.

Returns void
- Defined in src/index.ts:437

`Private` #onRepSocketData

#onRepSocketData(data: Buffer, socket: Socket): Promise<void>
Asynchrously handles the socket's data event, representing requests to call the Procedure.
Parameters
- data: Buffer
  
  The encoded input Buffer.
- socket: Socket
  
  The socket the data was received on.
Returns Promise<void>
- Defined in src/index.ts:311

`Private` #onRepSocketError

#onRepSocketError(error: unknown): void
Handles the error event for the underlying sockets of the Procedure.
Parameters
- error: unknown
  
  The error data passed by the socket.
Returns void
- Defined in src/index.ts:380

`Private` #tryDecodeInput

#tryDecodeInput(buffer: Buffer): {
    error?: undefined;
    input: Input | Ping;
} | {
    error: ProcedureInternalServerError;
    input?: undefined;
}
Attempts to decode the given Buffer.

Returns
If successful, an object of shape { input: Input | Ping }, otherwise { error: unknown }.
Parameters
- buffer: Buffer
  
  The Buffer to decode.
Returns {
    error?: undefined;
    input: Input | Ping;
} | {
    error: ProcedureInternalServerError;
    input?: undefined;
}
- Defined in src/index.ts:203

`Private` #tryEncodeResponse

#tryEncodeResponse(response: Response<Output>): Buffer
Attempts to encode the given response for transmission back to the Procedure's caller.

Returns
A Buffer containing the encoded response.
Parameters
- response: Response<Output>
  
  The response to encode.
Returns Buffer
- Defined in src/index.ts:261

`Private` #tryGetCallbackResponse

#tryGetCallbackResponse(input: Input): Promise<Response<Output>>
Attempts to asynchronously call the Procedure's callback and return a response containing its output value.

Returns
A Promise which when resolved passes the response to the then handler(s).
Parameters
- input: Input
  
  An input parameter to pass to the callback.
Returns Promise<Response<Output>>
- Defined in src/index.ts:228

`Private` #tryHandlePing

#tryHandlePing(data: unknown, socket: Socket): data is Ping
Handles ping requests for a given socket.

Returns
true when the decoded data object was a valid Ping and handled, otherwise false.
Parameters
- data: unknown
  
  The decoded incoming data object.
- socket: Socket
  
  The socket the data was received on.
Returns data is Ping
- Defined in src/index.ts:353

`Private` #trySendBuffer

#trySendBuffer(buffer: Buffer, socket: Socket): boolean
Attempts to send the encoded buffer back to the Procedure's caller.

Returns
true when the encoded Buffer was successfully sent, otherwise false.
Parameters
- buffer: Buffer
  
  A Buffer containing the encoded response.
- socket: Socket
  
  The socket through which to send the response.
Returns boolean
- Defined in src/index.ts:293

addListener

addListener<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).addListener
- Defined in node_modules/typed-emitter/index.d.ts:22

bind

bind(endpoint: string, ipv6??: boolean): Procedure<Input, Output>
Binds the Procedure to an endpoint, making it available to be called.

Returns
The bound Procedure for method chaining.

See
unbind
Parameters
- endpoint: string
  
  The endpoint at which the procedure will be callable.
- Optional ipv6: boolean = false
  
  Whether the endpoint requires ipv6 support. Defaults to false.
Returns Procedure<Input, Output>
- Defined in src/index.ts:159

emit

emit<E>(event: E, ...args: Parameters<ProcedureEvents<Input>[E]>): boolean
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- Rest ...args: Parameters<ProcedureEvents<Input>[E]>
Returns boolean
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).emit
- Defined in node_modules/typed-emitter/index.d.ts:32

eventNames

eventNames(): (string | symbol)[]
Returns (string | symbol)[]
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).eventNames
- Defined in node_modules/typed-emitter/index.d.ts:34

getMaxListeners

getMaxListeners(): number
Returns number
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).getMaxListeners
- Defined in node_modules/typed-emitter/index.d.ts:39

listenerCount

listenerCount<E>(event: E): number
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
Returns number
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).listenerCount
- Defined in node_modules/typed-emitter/index.d.ts:37

listeners

listeners<E>(event: E): ProcedureEvents<Input>[E][]
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
Returns ProcedureEvents<Input>[E][]
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).listeners
- Defined in node_modules/typed-emitter/index.d.ts:36

off

off<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).off
- Defined in node_modules/typed-emitter/index.d.ts:28

on

on<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).on
- Defined in node_modules/typed-emitter/index.d.ts:23

once

once<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).once
- Defined in node_modules/typed-emitter/index.d.ts:24

prependListener

prependListener<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).prependListener
- Defined in node_modules/typed-emitter/index.d.ts:25

prependOnceListener

prependOnceListener<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).prependOnceListener
- Defined in node_modules/typed-emitter/index.d.ts:26

rawListeners

rawListeners<E>(event: E): ProcedureEvents<Input>[E][]
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
Returns ProcedureEvents<Input>[E][]
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).rawListeners
- Defined in node_modules/typed-emitter/index.d.ts:35

removeAllListeners

removeAllListeners<E>(event?: E): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- Optional event: E
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).removeAllListeners
- Defined in node_modules/typed-emitter/index.d.ts:29

removeListener

removeListener<E>(event: E, listener: ProcedureEvents<Input>[E]): Procedure<Input, Output>
Type Parameters
- E extends keyof ProcedureEvents<Input>
Parameters
- event: E
- listener: ProcedureEvents<Input>[E]
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).removeListener
- Defined in node_modules/typed-emitter/index.d.ts:30

setMaxListeners

setMaxListeners(maxListeners: number): Procedure<Input, Output>
Parameters
- maxListeners: number
Returns Procedure<Input, Output>
Inherited from (EventEmitter as { new <Input>(): TypedEmitter<ProcedureEvents<Input>>; }).setMaxListeners
- Defined in node_modules/typed-emitter/index.d.ts:40

unbind

unbind(): Procedure<Input, Output>
Releases the Procedure from its endpoint.

Returns
The unbound Procedure for method chaining.

See
bind

Returns Procedure<Input, Output>
- Defined in src/index.ts:185

Class Procedure<Input, Output>

See

Type Parameters

Input = undefined

Output = undefined

Hierarchy

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Input = undefined

Output = undefined

Parameters

callback: ((input: Input) => Output)

Parameters

input: Input

Returns Output

Optional options: Partial<ProcedureDefinitionOptions> = {}

Returns Procedure<Input, Output>

Properties

Private Optional #endpoint

Private Optional #uuid

Protected callback

Type declaration

Parameters

input: Input

Returns Output

Protected options

Protected sockets

Accessors

endpoint

Returns undefined | string

Parameters

value: undefined | string

Returns void

extensionCodec

Returns undefined | ExtensionCodec<undefined>

Parameters

value: undefined | ExtensionCodec<undefined>

Returns void

ignoreUndefinedProperties

Remarks

See

Returns boolean

Remarks

See

Parameters

value: boolean

Returns void

optionalParameterSupport

Remarks

See

Returns boolean

Remarks

See

Parameters

value: boolean

Returns void

Protected uuid

Returns undefined | string

Parameters

value: undefined | string

Returns void

verbose

Returns boolean

Parameters

value: boolean

Returns void

workers

Returns number

Parameters

value: number

Returns void

Methods

Private #emitAndLogData

`Optional` options: Partial<ProcedureDefinitionOptions> = {}

`Private` `Optional` #endpoint

`Private` `Optional` #uuid

`Protected` callback

`Protected` options

`Protected` sockets

`Protected` uuid

`Private` #emitAndLogData

`Private` #emitAndLogError

`Optional` error: ProcedureError

`Private` #emitAndLogUnbind

`Private` #logSocketClose

`Private` #onRepSocketData

`Private` #onRepSocketError

`Private` #tryDecodeInput

Returns {
error?: undefined;
input: Input | Ping;
} | {
error: ProcedureInternalServerError;
input?: undefined;
}

`Private` #tryEncodeResponse

`Private` #tryGetCallbackResponse

`Private` #tryHandlePing

`Private` #trySendBuffer

`Optional` ipv6: boolean = false

`Rest` ...args: Parameters<ProcedureEvents<Input>[E]>