Documentation Index
Fetch the complete documentation index at: https://mintlify.com/cloudflare/partykit/llms.txt
Use this file to discover all available pages before exploring further.
partywhen is a task-scheduling library built on Durable Object Alarms. It lets you schedule tasks by delay, cron expression, or specific date/time — all from a single Scheduler Durable Object. Each task carries a description, a JSON payload, and a callback that fires when the task runs.
Installation
Class: Scheduler
Scheduler is the Durable Object class that manages and fires tasks. Export it from your Worker and bind it in wrangler.jsonc:
import { Scheduler } from "partywhen";
export { Scheduler };
export default {
fetch(request: Request, env: Env, ctx: ExecutionContext) {
// access a named scheduler instance
const id = env.SCHEDULER.idFromName("my-scheduler");
const scheduler = env.SCHEDULER.get(id);
// now you can call scheduler.scheduleTask(...)
}
};
wrangler.jsonc Configuration
Declare Scheduler as a Durable Object with SQLite storage and add a migration tag:
{
"durable_objects": {
"bindings": [
{
"name": "SCHEDULER",
"class_name": "Scheduler"
}
]
},
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": ["Scheduler"]
}
]
}
Accessing a Scheduler Instance
Obtain a stub via the standard Durable Object API:
const id = env.SCHEDULER.idFromName("my-scheduler");
const scheduler = env.SCHEDULER.get(id);
Method: scheduler.scheduleTask(task)
Schedule a new task. The task runs according to its type and fires the specified callback.
scheduler.scheduleTask(task: RawTask): Promise<Task>
Task fields
An optional human-readable label for the task. Can be used to query or identify the task later.
An optional JSON-serializable object passed to the callback when the task fires.
type
"delayed" | "cron" | "scheduled" | "no-schedule"
required
Determines when the task runs:
"delayed" — run after a delay (requires delayInSeconds)"cron" — run on a cron schedule (requires cron)"scheduled" — run at a specific Date (requires time)"no-schedule" — never runs automatically; useful for tasks that must be manually removed
Required when type is "delayed". Number of seconds to wait before firing.
Required when type is "cron". A standard 5-field cron expression, e.g. "0 18 * * 5" (every Friday at 6 pm UTC).
Required when type is "scheduled". The exact Date at which to fire the task.
callback
WebhookCallback | DurableObjectCallback | ServiceCallback
What to invoke when the task fires. See callback types below.
Callback Types
Webhook callback
POST the payload to an HTTP URL.
callback: {
type: "webhook";
url: string; // the URL to POST to
}
Durable Object callback
Call a named function on a Durable Object instance.
callback: {
type: "durable-object";
namespace: string; // the binding name, e.g. "MYDURABLE"
name: string; // the DO instance name, e.g. "some-id"
function: string; // the method name to call on the DO
}
Service callback
Call a named function on a service binding.
callback: {
type: "service";
service: string; // the service binding name, e.g. "MYSERVICE"
function: string; // the function name to call on the service
}
Examples
Delayed task — webhook
Run a task 60 seconds from now and POST to a URL:
scheduler.scheduleTask({
description: "my-task",
type: "delayed",
delayInSeconds: 60,
payload: {
message: "Hello, world!"
},
callback: {
type: "webhook",
url: "https://example.com/webhook"
}
});
Cron task — Durable Object
Run every Friday at 6 pm UTC and call a method on a Durable Object:
scheduler.scheduleTask({
description: "my-task",
type: "cron",
cron: "0 18 * * 5",
payload: {
message: "Hello, world!"
},
callback: {
type: "durable-object",
namespace: "MYDURABLE",
name: "some-id",
function: "myFunction"
}
});
Scheduled task — service binding
Run at a specific date and time and invoke a service binding function:
scheduler.scheduleTask({
description: "my-task",
type: "scheduled",
time: new Date("2024-01-01T12:00:00Z"),
payload: {
message: "Hello, world!"
},
callback: {
type: "service",
service: "MYSERVICE",
function: "myFunction"
}
});
partywhen is particularly well-suited for LLM-agent workflows where tasks
can be described in natural language and converted to type: "scheduled" or
type: "cron" entries automatically.
