datocms-listen

A lightweight, TypeScript-ready package that offers utilities to work with DatoCMS Real-time Updates API inside a browser.

Installation

npm install datocms-listen

Example

Import subscribeToQuery from datocms-listen and use it inside your components like this:

import { subscribeToQuery } from "datocms-listen";

const unsubscribe = await subscribeToQuery({
  query: `
    query BlogPosts($first: IntType!) {
      allBlogPosts(first: $first) {
        title
        nonExistingField
      }
    }
  `,
  variables: { first: 10 },
  token: "YOUR_TOKEN",
  preview: true,
  onUpdate: (update) => {
    // response is the GraphQL response
    console.log(update.response.data);
  },
  onStatusChange: (status) => {
    // status can be "connected", "connecting" or "closed"
    console.log(status);
  },
  onChannelError: (error) => {
    // error will be something like:
    // {
    //   code: "INVALID_QUERY",
    //   message: "The query returned an erroneous response. Please consult the response details to understand the cause.",
    //   response: {
    //     errors: [
    //       {
    //         fields: ["query", "allBlogPosts", "nonExistingField"],
    //         locations: [{ column: 67, line: 1 }],
    //         message: "Field 'nonExistingField' doesn't exist on type 'BlogPostRecord'",
    //       },
    //     ],
    //   },
    // }
    console.error(error);
  },
  onError: (error) => {
    // error will be
    // {
    //   message: "ERROR MESSAGE"
    // }
    console.log(error.message);
  },
  onEvent: (event) => {
    // event will be
    // {
    //   status: "connected|connected|closed",
    //   channelUrl: "...",
    //   message: "MESSAGE",
    // }
  },
});

Initialization options

prop	type	required	description	default
query	string | TypedDocumentNode	✅	The GraphQL query to subscribe
token	string	✅	DatoCMS API token to use
onUpdate	function	✅	Callback function to receive query update events
onChannelError	function	❌	Callback function to receive channelError events
onStatusChange	function	❌	Callback function to receive status change events
onError	function	❌	Callback function to receive error events
onEvent	function	❌	Callback function to receive other events
variables	Object	❌	GraphQL variables for the query
preview	boolean	❌	If true, the Content Delivery API with draft content will be used	false
environment	string	❌	The name of the DatoCMS environment where to perform the query	defaults to primary environment
reconnectionPeriod	number	❌	In case of network errors, the period (in ms) to wait to reconnect	1000
fetcher	a fetch-like function	❌	The fetch function to use to perform the registration query	window.fetch
eventSourceClass	an EventSource-like class	❌	The EventSource class to use to open up the SSE connection	window.EventSource
baseUrl	string	❌	The base URL to use to perform the query	https://graphql-listen.datocms.com

Events

onUpdate(update: UpdateData<QueryResult>)

This function will be called everytime the channel sends an updated query result. The updateData argument has the following properties:

prop	type	description
response	Object	The GraphQL updated response

onStatusChange(status: ConnectionStatus)

The status argument represents the state of the server-sent events connection. It can be one of the following:

• connecting: the subscription channel is trying to connect
• connected: the channel is open, we're receiving live updates
• closed: the channel has been permanently closed due to a fatal error (ie. an invalid query)

onChannelError(errorData: ChannelErrorData)

The errorData argument has the following properties:

prop	type	description
code	string	The code of the error (ie. INVALID_QUERY)
message	string	An human friendly message explaining the error
response	Object	The raw response returned by the endpoint, if available

onError(error: ErrorData)

This function is called when connection errors occur.

The error argument has the following properties:

prop	type	description
message	string	An human friendly message explaining the error

onEvent(event: EventData)

This function is called then other events occur.

The event argument has the following properties:

prop	type	description
status	string	The current connection status (see above)
channelUrl	string	The current channel URL
message	string	An human friendly message explaining the event

Return value

The function returns a Promise<() => void>. You can call the function to gracefully close the SSE channel.