API reference

Exports

Kind	Export	Description
Ttype alias	Cadence	One cron cadence in one IANA time zone.
Ttype alias	ScheduleState	Whether a schedule can fire, is paused, or has settled.
Ttype alias	ScheduleCore	The fields every schedule has; hosts add their own target fields.
Ttype alias	Refusal	A refused occurrence: the schedule’s new state and when to retry it.
Ttype alias	RetryPolicy	Initial and maximum delays for exponential retries.
Ttype alias	BackoffDelay	Pure retry-delay port shared by schedule and delivery owners.
Ttype alias	CadenceError	Why the next occurrence could not be computed.
constconstant	backoffDelay	Bounded exponential delay shared by schedule and delivery owners.
constconstant	defaultRetryPolicy	Default backoff: 30 s doubling to at most an hour.
fnfunction	nextOccurrence()	The first occurrence strictly after after. Hosts pass the current time after a firing, so occurrences missed while down or paused coalesce into the next one: a schedule never replays a backlog.
fnfunction	occurrenceKey()	The idempotency key of the schedule’s current occurrence. A retried or re-fired admission of the same occurrence carries the same key, so the host’s action runs at most once per occurrence.
fnfunction	isDue()	Whether the host should fire now; a paused or settled schedule never does.
fnfunction	settled()	Whether a schedule is cancelled or finished.
fnfunction	afterAdmitted()	The occurrence was admitted. A one-shot finishes; a recurring schedule moves to its next occurrence after now, or pauses with the reason if its cadence has none.
fnfunction	afterRefused()	The occurrence was refused. The schedule records why and retries the same occurrence (same key) after a bounded backoff; one failing schedule never delays another.
fnfunction	paused()	Pause admission while preserving the occurrence and any failure reason.
fnfunction	resumed()	Resume is the human retry: it clears the failure and skips recurring occurrences missed while paused.
fnfunction	cancelled()	Cancel an unsettled schedule, leaving an already settled record unchanged.

CadenceTtype alias

Signature

type Cadence = Readonly<{
  expression: string;
  timeZone: string;
}>;

One cron cadence in one IANA time zone.

---

ScheduleStateTtype alias

Signature

type ScheduleState = "active" | "paused" | "cancelled" | "finished";

Whether a schedule can fire, is paused, or has settled.

---

ScheduleCoreTtype alias

Signature

type ScheduleCore = Readonly<{
  id: string;
  cron: Cadence | null;
  nextDueAt: number;
  state: ScheduleState;
  lastError: string | null;
  attempt: number;
}>;

The fields every schedule has; hosts add their own target fields.

---

RefusalTtype alias

Signature

type Refusal<S> = Readonly<{
  schedule: S;
  retryAt: number;
}>;

A refused occurrence: the schedule’s new state and when to retry it.

Type Parameters

Type Parameter
S extends ScheduleCore

---

RetryPolicyTtype alias

Signature

type RetryPolicy = Readonly<{
  baseMs: number;
  maxMs: number;
}>;

Initial and maximum delays for exponential retries.

---

BackoffDelayTtype alias

Signature

type BackoffDelay = (attempt, policy) => number;

Pure retry-delay port shared by schedule and delivery owners.

Attempt one uses baseMs, capped by maxMs; zero and negative attempts retain that same first-delay convention. Later attempts double up to the cap. The owner supplies its policy; this port reads no clock or durable state.

Parameters

Parameter	Type
attempt	number
policy	RetryPolicy

Returns

number

---

CadenceErrorTtype alias

Signature

type CadenceError = Readonly<{
  kind: "invalid" | "exhausted";
  message: string;
}>;

Why the next occurrence could not be computed.

backoffDelayconstconstant

Signature

const backoffDelay: BackoffDelay;

Bounded exponential delay shared by schedule and delivery owners.

---

defaultRetryPolicyconstconstant

Signature

const defaultRetryPolicy: RetryPolicy;

Default backoff: 30 s doubling to at most an hour.

nextOccurrence()fnfunction

Signature

function nextOccurrence(
  cadence,
  after,
): Result<
  number,
  Readonly<{
    kind: "invalid" | "exhausted";
    message: string;
  }>
>;

The first occurrence strictly after after. Hosts pass the current time after a firing, so occurrences missed while down or paused coalesce into the next one: a schedule never replays a backlog.

Parameters

Parameter	Type
cadence	Cadence
after	number

Returns

Result<number, Readonly<{ kind: "invalid" | "exhausted"; message: string; }>>

---

occurrenceKey()fnfunction

Signature

function occurrenceKey(schedule): string;

The idempotency key of the schedule’s current occurrence. A retried or re-fired admission of the same occurrence carries the same key, so the host’s action runs at most once per occurrence.

Parameters

Parameter	Type
schedule	ScheduleCore

Returns

string

---

isDue()fnfunction

Signature

function isDue(schedule, now): boolean;

Whether the host should fire now; a paused or settled schedule never does.

Parameters

Parameter	Type
schedule	ScheduleCore
now	number

Returns

boolean

---

settled()fnfunction

Signature

function settled(schedule): boolean;

Whether a schedule is cancelled or finished.

Parameters

Parameter	Type
schedule	ScheduleCore

Returns

boolean

---

afterAdmitted()fnfunction

Signature

function afterAdmitted<S>(schedule, now): S;

The occurrence was admitted. A one-shot finishes; a recurring schedule moves to its next occurrence after now, or pauses with the reason if its cadence has none.

Type Parameters

Type Parameter
S extends Readonly<{ id: string; cron: | Readonly<{ expression: string; timeZone: string; }> | null; nextDueAt: number; state: ScheduleState; lastError: string | null; attempt: number; }>

Parameters

Parameter	Type
schedule	S
now	number

Returns

S

---

afterRefused()fnfunction

Signature

function afterRefused<S>(schedule, now, reason, policy?): Refusal<S>;

The occurrence was refused. The schedule records why and retries the same occurrence (same key) after a bounded backoff; one failing schedule never delays another.

Type Parameters

Type Parameter
S extends Readonly<{ id: string; cron: | Readonly<{ expression: string; timeZone: string; }> | null; nextDueAt: number; state: ScheduleState; lastError: string | null; attempt: number; }>

Parameters

Parameter	Type	Default value
schedule	S	undefined
now	number	undefined
reason	string	undefined
policy	RetryPolicy	defaultRetryPolicy

Returns

Refusal<S>

---

paused()fnfunction

Signature

function paused<S>(schedule): S;

Pause admission while preserving the occurrence and any failure reason.

Type Parameters

Type Parameter
S extends Readonly<{ id: string; cron: | Readonly<{ expression: string; timeZone: string; }> | null; nextDueAt: number; state: ScheduleState; lastError: string | null; attempt: number; }>

Parameters

Parameter	Type
schedule	S

Returns

S

---

resumed()fnfunction

Signature

function resumed<S>(
  schedule,
  now,
): Result<
  S,
  Readonly<{
    kind: "invalid" | "exhausted";
    message: string;
  }>
>;

Resume is the human retry: it clears the failure and skips recurring occurrences missed while paused.

Type Parameters

Type Parameter
S extends Readonly<{ id: string; cron: | Readonly<{ expression: string; timeZone: string; }> | null; nextDueAt: number; state: ScheduleState; lastError: string | null; attempt: number; }>

Parameters

Parameter	Type
schedule	S
now	number

Returns

Result<S, Readonly<{ kind: "invalid" | "exhausted"; message: string; }>>

---

cancelled()fnfunction

Signature

function cancelled<S>(schedule): S;

Cancel an unsettled schedule, leaving an already settled record unchanged.

Type Parameters

Type Parameter
S extends Readonly<{ id: string; cron: | Readonly<{ expression: string; timeZone: string; }> | null; nextDueAt: number; state: ScheduleState; lastError: string | null; attempt: number; }>

Parameters

Parameter	Type
schedule	S

Returns

S