Skip to main content
Big news! Interval has been acquired by Meter. Learn more →

Interval

The Interval class is the entrypoint for defining actions and pages.

Usage​

import path from "path";
import { Interval } from "@interval/sdk";

const interval = new Interval({
  endpoint: "wss://<YOUR INTERVAL SERVER URL>/websocket",
  apiKey: "<YOUR API KEY>", // get an API key from the Keys page in your Interval dashboard
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

Props​

apiKey

Required

string

Your API key. Get yours from the Keys page in your Interval dashboard.

endpoint

Required

string

The endpoint URL for your Interval Server instance.

routesDirectory

Optional

string

The path to the directory of route definitions when using file-based routing.

routes

Optional

Record<string, Action | Page>

An object mapping string route slugs to Actions or Pages when defining routes inline.

logLevel

Optional

"quiet" | "info" | "debug"

Controls the type of logs emitted by Interval in the console's standard out and standard error. Defaults to 'info', set to 'quiet' to reduce output to only fatal errors, and 'debug' to include low-level internal debugging information.

sendTimeoutMs

Optional

number

How long to wait in milliseconds before timing out the initial call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 5000 (5 seconds).

retryIntervalMs

Optional

number

How long to wait in milliseconds before retrying the initial failed call to Interval, increasing linearly for each subsequent retry attempt. Defaults to 3000 (3 seconds).

maxResendAttempts

Optional

number

The number of resend attempts that will be made before abandoning a call to Interval. Defaults to 10.

pingIntervalMs

Optional

number

How often in milliseconds Interval is pinged to ensure a consistent connection. Defaults to 30000 (30 seconds).

pingTimeoutMs

Optional

number

How long to wait in milliseconds for an attempted ping to Interval before assuming it fails and trying again. Defaults to 5000 (5 seconds).

closeUnresponsiveTimeoutMs

Optional

number

How long to wait in milliseconds after receiving the last successful ping response before closing the connection and attempting to reconnect. Defaults to 180000 (3 minutes).

reinitializeBatchTimeoutMs

Optional

number

How long to wait in milliseconds before updating Interval with any programmatic changes made to defined routes. Defaults to 200.

onError

Optional

(props: IntervalErrorProps) => void

A global error callback, typically used for logging or reporting to error services.
(props: {
    error: Error | unknown
    route: string
    routeDefinition: Action | Page | undefined
    params: Record<string, string | number | boolean | null | undefined | Date | bigint>
    environment: 'production' | 'development' | string
    user: {
        email: string
        firstName: string | null
        lastName: string | null
    }
    organization: {
        name: string
        slug: string
    }
}) => void

Methods​

listen()

Establish the persistent connection to Interval.

async ping()

Ping Interval to manually ensure an active connection, useful for health chceks. Will return `true` if successful, throw a `NotConnectedError` if there is no active connection, or throw a `TimeoutError` if a response is not received within `pingTimeoutMs`.

async safelyClose()

Safely close the connection to Interval, preventing new actions from being launched and closing the persistent connection afterward. Resolves when the connection is successfully safely closed.

immediatelyClose()

Immediately terminate the connection to interval, terminating any actions currently in progress.

async enqueue(slug, { assignee, params })

Enqueue an action to be completed, with an optional `assignee` email to assign the action to, and optional `params` which will be passed to the action as `ctx.params`. Assigned actions will be displayed in users' dashboards as a task list. See Queued actions for more information.
async (
  slug: string,
  options?: {
    assignee?: string,
    params?: Record<string, string | number | boolean | Date | null | undefined>
  }
) => Promise<{
  id: string;
  assignee?: string;
  params?: Record<string, string | number | boolean | Date | null | undefined>;
}>

async dequeue(queuedActionId)

Dequeue a previously enqueued action which was created with `interval.enqueue()`. See Queued actions for more information.
async (
  queuedActionId: string
) => Promise<void>

async notify(config)

Sends a custom notification to Interval users via email or Slack. To send Slack notifications, you'll need to connect your Slack workspace to the Interval app in your organization settings. See Notifications for more information.
async ({
  message: string,
  title?: string,
  delivery?: {
    to: string;
    method?: 'SLACK' | 'EMAIL';
  }[],
  transactionId?: string,
  idempotencyKey?: string,
}) => Promise<void>

Examples​

Safely shutting down a live deployment (blue-green deploys)​

Leverage the safelyClose method to ensure there are no service interruptions, lost progress, or malformed data when shutting down a previous version of a live deployment.

src/interval.ts
import path from "path";
import { Interval } from "@interval/sdk";

const interval = new Interval({
  endpoint: "wss://<YOUR INTERVAL SERVER URL>/websocket",
  apiKey: "<YOUR API KEY>", // get an API key from the Keys page in your Interval dashboard
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();

process.on("SIGINT", () => {
  interval
    .safelyClose()
    .then(() => {
      console.log("Safely shut down successfully.");
      process.exit(0);
    })
    .catch(err => {
      console.error(
        "Failed shutting down safely, forcibly closing connection."
      );
      interval.immediatelyClose();
      process.exit(0);
    });
});
Was this section useful?
On this page