Skip to content

Latest commit

 

History

History
198 lines (156 loc) · 9.47 KB

migration.md

File metadata and controls

198 lines (156 loc) · 9.47 KB
Raw

NATS.js 2.0 API Changes

V2 is a complete re-write of the client using a shared underlying client engine. The new API is 100% compatible across all our supported JavaScript environments; Code written for Node will work on Browser or Deno.

The new library is also async / await, while still supporting callbacks for subscription handling if desired.

General Changes:

  • All API signatures are greatly simplified, with required arguments listed first. Optional arguments follow. In the case that the API takes two optional arguments, an empty value is required.
  • Subscriptions and notifications are async iterators, but subscriptions can specify a callback if desired.
  • Message payloads are always Uint8Arrays. Simple Codecs are provided to encode/decode strings, JSON, or custom data.

Changes to Connect

Previous versions of the connect(url, opts) function depended on notifications from an event listener, to know if the client connected, etc. The new version changes to connect(opts: ConnectionOptions): Promise<NatsConnection>.

If the connect resolves, you have a connection and you can use the client. Otherwise depending on the connection options, the connection will fail.

Similarly, to detect that the connection closed, you had to register a handler. The new API simplifies handling a closed connection by waiting for the promise from closed(): Promise<void|Error>.

Changes to publish

  • Previous publish signature was: publish(subject: string, msg?: any, reply?: string, callback?: Function):void

The new signature is: publish(subject: string, data?: Uint8Array, opts?: PublishOptions): void

The PublishOptions has the following interface: { reply?: string, headers?: MsgHdrs }

Changes to subscribe

  • Previous subscribe signature was: subscribe(subject: string, opts: SubscribeOptions, callback: Function): number

  • The new signature is subscribe(subject: string, opts?: SubscriptionOptions): Subscription

SubscriptionOptions has the following interface:

{
  queue?: string;
  max?: number;
  timeout?: number;
  callback?: (err: NatsError | null, msg: Msg) => void;
}

The returned Subscription is an object. Providing functionality to drain(), unsubscribe() and more:

{
  unsubscribe(max?: number): void;
  drain(): Promise<void>;
  isDraining(): boolean;
  isClosed(): boolean;
  getSubject(): string;
  getReceived(): number;
  getProcessed(): number;
  getPending(): number;
  getID(): number;
  getMax(): number | undefined;
}

Most importantly, subscriptions are AsyncIterable<Msg> - to process your messages:

for await(const m of sub) {
 // process the message. When the subscription completes the loop ends.
}

If you want to use callbacks you can specify them as a subscription option. The use of callbacks is discouraged.

Messages have the following interface:

{
  subject: string;
  sid: number;
  reply?: string;
  data: Uint8Array;
  headers?: MsgHdrs;
  respond(data?: Uint8Array, opts?: PublishOptions): boolean;
}

The respond method of the message returns true if the message had a reply subject.

Changes to request

  • The previous request signature was: request(subject: string, msg: any, options: RequestOptions, callback: Function): number;
  • The new signature is: request(subject: string, data?: Uint8Array, opts?: RequestOptions): Promise<Msg>

The RequestOptions interface has the following interface and defaults:

{
    timeout: number; // defaults to `1000`
    noMux: boolean; // defaults to `false`
    headers?: MsgHeaders;
    reply?: string
}

A request will either succeed and resolve to a message or fail with a timeout or some other error. If specifying the connection options headers and noResponder, requests sent to subjects that have no interest will immediately fail with a ErrorCode.NoResponders.

Error Codes

All error codes are now exported under ErrorCode.

Error Handling

Previous versions of NATS.js typically emitted errors and had numerous handlers you needed to specify. The new version provides an async iterator status(). You can iterate to pull the latest notification. The notifications have the interface: {type: string, data?: string|ServersChanged}. Available types are available under: Events, which has available properties for DISCONNECT, RECONNECT, UPDATE, LDM and ERROR.

The ERROR event will notify any runtime error returned by the server that could not properly be dispatched to your client in a more direct way. For example, if there's a problem publishing to a subject because the client doesn't have permissions.

Payloads

Previous versions of NATS.js created an encoded connection that required all messages to be either binary, strings, or JSON. Version 2 simplifies the API by making all payloads Uint8Arrays. User code that is interested in a different format, can simply encode/decode as necessary.

The StringCodec() and JSONCodec() functions return an encoder interface:

export interface Codec<T> {
  encode(d: T): Uint8Array;
  decode(a: Uint8Array): T;
}

For StringCodec, encode coverts a string to UintArray and decodes an UintArray into a string. JSONCodec does the same between objects and Uint8Arrays.

Changed Configuration Properties

Property Description
authenticator A function that deals with providing credentials
debug If set to true, client will output to the console the raw protocol interactions. Only useful for developing the client.
headers If set to true, client enables use of headers
maxPingOut Maximum number of pings that go unanswered before a connection is considered stale
maxReconnectAttempts maximum number of reconnect attempts before client closes
name A name identifying the client on the server for monitoring purposes
noEcho If true messages published by the client won't be visible to the client's subscriptions
noRandomize If true, servers are tried in the order specified
noResponders If true when making a request for which there are no reponders an error is returned. This functionality requires headers'
pass Password for a connection
pedantic If true server will emit pedantic responses. Only useful for developing the client
pingInterval Number of milliseconds between client pings
port Number of the port where the server is running
reconnect If false the client will not attempt reconnects
reconnectDelayHandler A function with the interface () => number returning the number of milliseconds to wait before the next connection attempt
reconnectJitter number of milliseconds to jitter a connection retry
reconnectJitterTLS number of milliseconds to jitter a TLS connection
reconnectTimeWait number of milliseconds between reconnect attempts
servers A string or array of strings with server hostports
timeout number milliseconds before a connection attempt is timed out
tls an object specifying a TlsOptions options. An empty object implies the client requires a TLS connection.
token A string to be used as an authentication token
user string specifying the user name
verbose If true the server will emit verbose responses. Only useful for developing the client
waitOnFirstConnect If true the client will keep attempting to connect if it has never connected
ignoreClusterUpdates If true the client will ignore any cluster updates provided by the server.