Skip to content

Latest commit

 

History

History
189 lines (144 loc) · 12 KB

README.md

File metadata and controls

189 lines (144 loc) · 12 KB
Raw

👉 Visit the DatoCMS homepage or see What is DatoCMS?

datocms-listen

MIT MIT Build Status

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",
  includeDrafts: 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
includeDrafts boolean ❌ If true, draft records will be returned
excludeInvalid boolean ❌ If true, invalid records will be filtered out
environment string ❌ The name of the DatoCMS environment where to perform the query (defaults to primary environment)
contentLink 'vercel-1' or undefined ❌ If true, embed metadata that enable Content Link
baseEditingUrl string ❌ The base URL of the DatoCMS project
cacheTags boolean ❌ If true, receive the Cache Tags associated with the query
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.

What is DatoCMS?

DatoCMS is the REST & GraphQL Headless CMS for the modern web.

Trusted by over 25,000 enterprise businesses, agency partners, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our developers, content editors and marketers!

Quick links:

Our featured repos:

Or see all our public repos