Interface: ClientOptions<SingleConnection>

client.ClientOptions

Type parameters

Properties

abortControllerImpl

• Optional abortControllerImpl: unknown

The AbortController implementation to use.

For NodeJS environments before v15 consider using node-abort-controller (opens in a new tab).

Default

global.AbortController

Defined in

src/client.ts:161 (opens in a new tab)

credentials

• Optional credentials: "omit" | "same-origin" | "include"

Indicates whether the user agent should send cookies from the other domain in the case of cross-origin requests.

Possible options are:

• omit: Never send or receive cookies.
• same-origin: Send user credentials (cookies, basic http auth, etc..) if the URL is on the same origin as the calling script.
• include: Always send user credentials (cookies, basic http auth, etc..), even for cross-origin calls.

Default

same-origin

Defined in

src/client.ts:101 (opens in a new tab)

fetchFn

• Optional fetchFn: unknown

The Fetch function to use.

For NodeJS environments consider using node-fetch (opens in a new tab).

Default

global.fetch

Defined in

src/client.ts:153 (opens in a new tab)

generateID

• Optional generateID: () => string

Type declaration

▸ (): string

A custom ID generator for identifying subscriptions.

The default generates a v4 UUID to be used as the ID using Math as the random number generator. Supply your own generator in case you need more uniqueness.

Reference: https://gist.github.com/jed/982883 (opens in a new tab)

Returns

string

Defined in

src/client.ts:171 (opens in a new tab)

headers

• Optional headers: Record<string, string> | () => Record<string, string> | Promise<Record<string, string>>

HTTP headers to pass along the request.

If the option is a function, it will be called on each connection attempt. Returning a Promise is supported too and the connection phase will stall until it resolves with the headers.

A good use-case for having a function is when using the headers for authentication, where subsequent reconnects (due to auth) may have a refreshed identity token in the header.

Defined in

src/client.ts:143 (opens in a new tab)

lazy

• Optional lazy: SingleConnection extends true ? boolean : never

Controls when should the connection be established while using the client in "single connection mode" (see singleConnection option).

• false: Establish a connection immediately.
• true: Establish a connection on first subscribe and close on last unsubscribe.

Note that the lazy option has NO EFFECT when using the client in "distinct connection mode" (singleConnection = false).

Default

true

Defined in

src/client.ts:51 (opens in a new tab)

lazyCloseTimeout

• Optional lazyCloseTimeout: SingleConnection extends true ? number : never

How long should the client wait before closing the connection after the last oparation has completed. You might want to have a calmdown time before actually closing the connection.

Meant to be used in combination with lazy.

Note that the lazy option has NO EFFECT when using the client in "distinct connection mode" (singleConnection = false).

Default

0

Defined in

src/client.ts:63 (opens in a new tab)

onMessage

• Optional onMessage: (message: StreamMessage<SingleConnection, StreamEvent>) => void

Type declaration

▸ (message): void

Browsers show stream messages in the DevTools only if they're received through the native EventSource (opens in a new tab), and because graphql-sse implements a custom SSE parser - received messages will not appear in browser's DevTools.

Use this function if you want to inspect valid messages received through the active SSE connection.

Parameters

Returns

void

Defined in

src/client.ts:194 (opens in a new tab)

onNonLazyError

• Optional onNonLazyError: SingleConnection extends true ? (error: unknown) => void : never

Used ONLY when the client is in non-lazy mode (lazy = false). When using this mode, errors might have no sinks to report to; however, to avoid swallowing errors, onNonLazyError will be called when either:

• An unrecoverable error/close event occurs
• Silent retry attempts have been exceeded

After a client has errored out, it will NOT perform any automatic actions.

Default

console.error

Defined in

src/client.ts:75 (opens in a new tab)

referrer

• Optional referrer: string

A string specifying the referrer of the request. This can be a same-origin URL, about:client, or an empty string.

Default

undefined

Defined in

src/client.ts:107 (opens in a new tab)

referrerPolicy

• Optional referrerPolicy: "same-origin" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url"

Specifies the referrer policy to use for the request.

Possible options are:

• no-referrer: Does not send referrer information along with requests to any origin.
• no-referrer-when-downgrade: Sends full referrerURL for requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL.
• same-origin: Sends full referrerURL as referrer information when making same-origin-referrer requests.
• origin: Sends only the ASCII serialization of the request’s referrerURL when making both same-origin-referrer requests and cross-origin-referrer requests.
• strict-origin: Sends the ASCII serialization of the origin of the referrerURL for requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL
• origin-when-cross-origin: Sends full referrerURL when making same-origin-referrer requests, and only the ASCII serialization of the origin of the request’s referrerURL is sent when making cross-origin-referrer requests
• strict-origin-when-cross-origin: Sends full referrerURL when making same-origin-referrer requests, and only the ASCII serialization of the origin of the request’s referrerURL when making cross-origin-referrer requests: whose referrerURL and current URL are both potentially trustworthy URLs, or whose referrerURL is a non-potentially trustworthy URL.
• unsafe-url: Sends full referrerURL along for both same-origin-referrer requests and cross-origin-referrer requests.

Default

undefined

Defined in

src/client.ts:123 (opens in a new tab)

retry

• Optional retry: (retries: number) => Promise<void>

Type declaration

▸ (retries): Promise<void>

Control the wait time between retries. You may implement your own strategy by timing the resolution of the returned promise with the retries count.

retries argument counts actual reconnection attempts, so it will begin with 0 after the first retryable disconnect.

Default

'Randomised exponential backoff, 5 times'

Parameters

Returns

Promise<void>

Defined in

src/client.ts:187 (opens in a new tab)

retryAttempts

• Optional retryAttempts: number

How many times should the client try to reconnect before it errors out?

Default

5

Defined in

src/client.ts:177 (opens in a new tab)

singleConnection

• Optional singleConnection: SingleConnection

Reuses a single SSE connection for all GraphQL operations.

When instantiating with false (default), the client will run in a "distinct connections mode" mode. Meaning, a new SSE connection will be established on each subscribe.

On the other hand, when instantiating with true, the client will run in a "single connection mode" mode. Meaning, a single SSE connection will be used to transmit all operation results while separate HTTP requests will be issued to dictate the behaviour.

Default

false

Defined in

src/client.ts:38 (opens in a new tab)

url

• url: string | () => string | Promise<string>

URL of the GraphQL over SSE server to connect.

If the option is a function, it will be called on each connection attempt. Returning a Promise is supported too and the connection phase will stall until it resolves with the URL.

A good use-case for having a function is when using the URL for authentication, where subsequent reconnects (due to auth) may have a refreshed identity token in the URL.

Defined in

src/client.ts:89 (opens in a new tab)