ScheduledEvent
Background
A ScheduledEvent
is the event type for scheduled requests to a Worker. It is the Object
passed through as the event
when a Worker is invoked by a Worker’s Cron Trigger. ScheduledEvent
is supported in Workers written with Service Worker syntax and Module Worker syntax.
Syntax: Module Worker
A ScheduledEvent
can be handled in Workers functions written using the Module Worker syntax by adding a scheduled
function to your module’s exported handlers:
export default { async scheduled(event, env, ctx) { ctx.waitUntil(doSomeTaskOnASchedule()); },
};
Properties
event.cron
string
- The value of the Cron Trigger that started the
ScheduledEvent
.
- The value of the Cron Trigger that started the
event.type
string
- The type of event. This will always return
"scheduled"
.
- The type of event. This will always return
event.scheduledTime
number
- The time the
ScheduledEvent
was scheduled to be executed in milliseconds since January 1, 1970, UTC. It can be parsed asnew Date(event.scheduledTime)
.
- The time the
env
object
- An object containing the bindings associated with your Module Worker, such as KV namespaces and Durable Objects.
ctx
object
- An object containing the context associated with your Module Worker. Currently, this object just contains the
waitUntil
function.
- An object containing the context associated with your Module Worker. Currently, this object just contains the
Methods
When a Workers script is invoked by a Cron Trigger, the Workers runtime starts a ScheduledEvent
which will be handled by the scheduled
function in your Workers Module class. The ctx
argument represents the context your function runs in, and contains the following methods to control what happens next:
ctx.waitUntil(promisePromise)
:void
- Use this method to notify the runtime to wait for asynchronous tasks (for example, logging, analytics to third-party services, streaming and caching). The first
ctx.waitUntil
to fail will be observed and recorded as the status in the Cron Trigger Past Events table. Otherwise, it will be reported as a success.
- Use this method to notify the runtime to wait for asynchronous tasks (for example, logging, analytics to third-party services, streaming and caching). The first
Syntax: Service Worker
A ScheduledEvent
can be handled in Workers functions written using the Service Worker syntax by attaching to the scheduled
event with addEventListener
:
addEventListener("scheduled", (event) => { event.waitUntil(handleScheduled(event));
});
Properties
event.cron
string
- The value of the Cron Trigger that started the
ScheduledEvent
.
- The value of the Cron Trigger that started the
event.type
string
- The type of event. This will always return
"scheduled"
.
- The type of event. This will always return
event.scheduledTime
number
- The time the
ScheduledEvent
was scheduled to be executed in milliseconds since January 1, 1970, UTC. It can be parsed asnew Date(event.scheduledTime)
- The time the
Methods
When a Workers script is invoked by a Cron Trigger, the Workers runtime starts a ScheduledEvent
which will be handled by the event listener registered for the type "scheduled"
. The event handler can invoke the following methods of the event
object to control what happens next:
event.waitUntil(promisePromise)
:void
- Use this method to notify the runtime to wait for asynchronous tasks (for example, logging, analytics to third-party services, streaming and caching). The first
event.waitUntil
to fail will be observed and recorded as the status in the Cron Trigger Past Events table. Otherwise, it will be reported as a Success.
- Use this method to notify the runtime to wait for asynchronous tasks (for example, logging, analytics to third-party services, streaming and caching). The first