Schedule a persistent task to run once,protectedschedule(delaySeconds,method,payload?,opts?):Promise<string>
delaySeconds from now.
A task names a method on your class: when the timer fires, the SDK calls
this[method](payload) — one argument, the payload. If no such method
exists, onTask fires instead. Tasks are persistent:
they survive crashes and restarts, riding the actor’s single alarm slot.
Delivery is at-least-once — write handlers to be idempotent. A task that
throws is retried with exponential backoff (starting around a second,
capped at 5 minutes) up to opts.maxRetries times after the first
delivery (default 5), then parked (dropped without firing again).
With a stable opts.id, scheduling is an upsert — the prior task with
that id is replaced and the timer re-armed. Payloads must be
storage-codec-safe or a CodecError is thrown.
A task handler may schedule and cancel tasks, its own id included — the
usual shape for a poller that books its next look, or a task that stops
itself. What the handler leaves behind stands: the run that is finishing
never removes or overwrites it. Retry accounting still applies, though, so
a handler that re-schedules its own task and then throws keeps the task it
wrote but not a clean slate — the failure counts toward maxRetries, and
the task fires no sooner than the backoff. (A handler that cancels its
own task and then throws stays cancelled.)
Parameters
Returns
Promise<string>
The task id (pass to
cancelSchedule).
ScheduleOptions
Options for schedule()/queue()/every(). Properties everyMs?Recurrence interval in ms. Set by every(); re-inserts the next fire.optionaleveryMs?:number
id?
Stable id. Re-scheduling with the same id replaces the prior task (dedup + re-arm). Omit for a random id. Must not contain a codec-unsafe value; keep it a plain string.optionalid?:string
maxRetries?
Retries AFTER the first delivery before the task is parked (dropped). Default 5, so a task runs up tooptionalmaxRetries?:number
maxRetries + 1 times total.