Writing actions
- TypeScript
- JavaScript
- Python Experimental
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.
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.
Actions are the foundation of tools built with Interval. Actions are just async coroutines which means anything you can do within a coroutine function is possible within an action. And by extension, if you know how to write coroutine functions, you know how to write Interval actions.
But actions have access to special functionality that other functions don't, namely they can:
- collect input and display output through I/O methods,
- be run by a member of your organization from the Interval dashboard,
- and send push notifications to members of your organization.
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.
The simplest and most common way to define actions is by loading them from
the filesystem using the routesDirectory
property.
The simplest and most common way to define actions is to add the @interval.action
decorator to an async coroutine. If you want to set additional metadata for the action, you can pass options to the decorator specifying metadata properties:
- TypeScript
- JavaScript
- Python Experimental
import { Interval } from "@interval/sdk";
import path from "path";
const interval = new Interval({
apiKey: "<YOUR API KEY>",
routesDirectory: path.resolve(__dirname, "routes"),
});
interval.listen();
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
.
import { Interval } from "@interval/sdk";
import path from "path";
const interval = new Interval({
apiKey: "<YOUR API KEY>",
routesDirectory: path.resolve(__dirname, "routes"),
});
interval.listen();
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
.
from interval_sdk import Interval, IO
@interval.action
async def refund_user(io: IO):
# action logic here
pass
@interval.action(name="Import data", description="Imports data.", backgroundable=True)
async def import_data(io: IO):
# action logic here
pass
@interval.action(name="Edit user", description="Only accessible via direct link with user ID parameters", unlisted=True)
async def edit_user(io: IO):
# action logic here
pass
interval.listen()
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();
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:
- TypeScript
- JavaScript
- Python Experimental
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");
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");
interval.listen()
async def export_data(io: IO):
# action logic here
pass
interval.routes.add("export_data", export_data)
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
- TypeScript
- JavaScript
- Python Experimental
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.
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.
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 async coroutine. 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.
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.
Interval's I/O methods are type safe by design. For example, a call to io.input.number will return an int
or float
type from the Python standard library, or a call to io.input.date will return a date object.
In addition to basic type safety, Interval will also enforce validation where logical. For example, a call to io.input.email will return a str
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.
- TypeScript
- JavaScript
- Python Experimental
// 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");
});
// 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");
});
// email is a string containing an email address
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 a complete Interval app:
import os
from interval_sdk import Interval, IO
interval = Interval(
os.environ["INTERVAL_API_KEY"],
)
@interval.action
async def collect_email(io: IO):
email = await io.input.text("Enter an email")
interval.listen()
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:
- TypeScript
- JavaScript
- Python Experimental
// 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);
// 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);
# maybe_email is a string containing an email address *or* None
maybe_email = await io.input.email("Enter an email").optional()
# or to conditionally mark as optional
maybe_email = await io.input
.email("Enter an email")
.optional(user.email is not None)
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:
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:
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.
- TypeScript
- JavaScript
- Python Experimental
const [name, email, age] = await io.group([
io.input.text("Name"),
io.input.email("Email"),
io.input.number("Age"),
]);
const [name, email, age] = await io.group([
io.input.text("Name"),
io.input.email("Email"),
io.input.number("Age"),
]);
name, email, age = await io.group(
io.input.text("Name"),
io.input.email("Email"),
io.input.number("Age"),
);
See io.group for more information.