Skip to main content

Writing actions

Actions are the foundation of tools built with Interval. Actions are just async functions which means anything you can do within a JavaScript function is possible within an action. And by extension, if you know how to write JavaScript functions, you know how to write Interval actions.

But actions have access to special functionality that other functions don't, namely they can:

Defining actions​

Actions are identified by slugs that are defined in your code and are unique to your organization.

The simplest and most common way to define actions is by loading them from the filesystem using the routesDirectory property.

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

const interval = new Interval({
  apiKey: "<YOUR API KEY>",
  routesDirectory: path.resolve(__dirname, "routes"),
});

interval.listen();
src/routes/hello_world.ts
import { Action, io } from "@interval/sdk";

export default new Action(async () => {
  const name = await io.input.text("Your name");
  return `Hello, ${name}`;
});

When routesDirectory is defined, Interval will recursively walk directories and detect files with default exports of Actions or Pages and create slugs for them based on their files' paths.

tip

Relative path resolution is based on your Node.js process's current working directory. In order to load starting from a path relative to the Interval constructor, be sure to provide an explicit path, for instance by using the __dirname variable and path.resolve.

Learn more about pages ›

Defining routes inline

If necessary, can also be defined inline using the routes property on the Interval or Page constructors:

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

const interval = new Interval({
  apiKey: "<YOUR API KEY>",
  routes: {
    hello_world: async () => {
      const name = await io.input.text("Your name");
      return `Hello, ${name}`;
    },
  },
});

interval.listen();

Dynamically adding and removing routes​

Routes can also be defined dynamically after calling listen() by using the interval.routes.add() method:

interval.listen();

interval.routes.add("export_data", async () => {
  // action logic here
});

Routes can be dynamically removed as well, such as to make an action unavailable in response to some event. You can do so with the interval.routes.remove() method:

interval.listen();

interval.routes.remove("export_data");

Rendering UIs​

Inside of Interval actions, you can use I/O methods to collect input and display output. Interval handles the heavy lifting of rendering the appropriate UIs.

I/O methods can be awaited just like any other JavaScript promise. The execution of your action handler function will be suspended until the person running the action provides the requested input or acknowledges the data you've displayed.

In practice, this means you can collect input and display output as easily as calling any other function. You can focus on your business logic instead of the complexities of UI programming, like managing state, reactivity, etc.

Type safety and validation​

Interval's I/O methods are type safe by design. For example, a call to io.input.number will return a primitive JavaScript number that is statically typed by TypeScript.

In addition to basic type safety, Interval will also enforce validation where logical. For example, a call to io.input.email will return a JavaScript string that is guaranteed by Interval to be a valid email address.

A simple example​

Imagine you need to collect an email address from the person running your action. In Interval, this can be accomplished with a single line of code.

// email is a string containing an email address
const email = await io.input.email("Enter an email");

Note that I/O methods can only be used inside actions. Here's the above line in context of an Interval action:

import { Action, io } from "@interval/sdk";

export default new Action(async () => {
  const email = await io.input.email("Enter an email");
});

Requesting an optional value​

By default, when you request input with an I/O method, the person running your action must supply a valid value before continuing. In some cases, you may want to allow the person running you action to skip a field.

This can be done simply by chaining your I/O method call with .optional().

For example:

// maybeEmail is a string containing an email address *or* undefined
const maybeEmail = await io.input.email("Enter an email").optional();

// or to conditionally mark as optional
const maybeEmail = await io.input
  .email("Enter an email")
  .optional(user.email !== null);

I/O groups​

When writing actions, you'll often want to call multiple I/O methods at the same time. For example, for a tool to create a user account, you may want to collect an email, name, and age. To do this in Interval, you can use the io.group method. If you've used Promise.all before, Interval's group method works effectively identically:

const [name, email, age] = await io.group([
  io.input.text("Name"),
  io.input.email("Email"),
  io.input.number("Age"),
]);

See io.group for more information.

Was this section useful?
On this page