Schedules

Named schedules trigger Flows on a calendar cron or a fixed duration. Declare with clock / helpers, set the zone once on the app, then bind with on(clockDecl, flow).

For developers running daily digests, health pings, and per-tenant billing loops on okengine.

Smallest Example

import { clock } from "okengine";

export const dailyReportClock = clock.daily("reports.daily", { at: "06:00" });

import { on, flow } from "okengine";
import { dailyReportClock } from "@/clocks/reports";

export const runDailyReport = on(
  dailyReportClock,
  flow("reports.runDaily", {
    plane: "operator",
    do: async (_, fx) => {
      await fx.call(buildDailyReport, { at: fx.clock.now() });
    },
  }),
);

import { oke } from "okengine";

export const app = oke({
  name: "notes",
  clock: { timezone: "Asia/Riyadh" },
});

Progressive Patterns

From helpers and intervals to per-tenant rows and Console-tunable schedules:

import { clock } from "okengine";

export const daily = clock.daily("reports.daily", { at: "06:00" });
export const rollup = clock.hourly("metrics.rollup", { minute: 0 });
export const digest = clock.weekly("notes.digest", {
  on: ["mon", "fri"],
  at: "09:00",
});
export const close = clock.monthly("billing.close", { on: [1, 15], at: "00:00" });
export const ping = clock.every("health.ping", "30s");

Helper Reference

At least one of cron or every is required on the callable form. Empty options throw clock("name"): require cron or every. Invalid cron throws at declare (invalid cron …).

An empty clock.cron field bag throws cron fields: require at least one of at, minute, hour, dayOfMonth, month, dayOfWeek.

Timezone Resolution

Cron math needs an IANA zone. Resolve it once; override only when a schedule must differ.

import { oke } from "okengine";
import { clock } from "okengine";

export const app = oke({
  name: "notes",
  clock: { timezone: "Asia/Riyadh" },
});

// Inherits Asia/Riyadh
export const digest = clock.daily("notes.digest", { at: "08:00" });

// Explicit UTC wins over the app default
export const utcRollup = clock.hourly("metrics.utc", {
  minute: 0,
  timezone: "UTC",
});

{ tz: "…" } is not an option — it is ignored. Intervals (every) are duration-based and do not consult the zone for tick spacing; the zone still lands on the Store row.

Binding & Input

Bind with on(clockDecl, flow("name", { do })). One Flow can write clock.every inside on() — Clock · Inline or named export. do has no payload; read time through fx.clock:

import { clock } from "okengine";

export const cleanupClock = clock.every("metrics.cleanup", "1h");

import { on, flow } from "okengine";
import { lt } from "drizzle-orm";
import { cleanupClock } from "@/clocks/metrics";
import { db, metricLogs } from "@/schema";

export const cleanup = on(
  cleanupClock,
  flow("metrics.cleanup", {
    plane: "operator",
    do: async (_, fx) => {
      await fx
        .store(db)
        .delete(metricLogs)
        .where(lt(metricLogs.timestamp, fx.clock.ago("7d")));
      return { at: new Date(fx.clock.now()).toISOString() };
    },
  }),
);

Options Reference

Shared options on clock(name, options) and helpers:

Duration units (every)

Per-tenant Schedules

clock.perTenant expands one Store row per tenant ({name}#{tenantId}). The bare template name never ticks — runNow("invoices") returns false.

Tenant ids come from reconcile (tenantIds). New tenants get rows; deleted tenants mark those rows orphaned.

Consequence: ten tenants → ten leases. Catch-up is "one" per row, so downtime does not replay a burst of missed hours for each tenant.

Leader Lock

Multi-instance deploys need a shared clock driver — otherwise every pod fires the same tick. Dev/prod default is postgres (test is frozen). A short lease (default 30s) means only one instance runs each fire.

Consequence: three pods calling runNow still execute the Flow once. After the lease expires, another instance may take the next tick.

Catch-up Policy

Catch-up is "one": after 5 hours down on an hourly clock, the next tick fires once. Missed slots are visible as missedRuns — they are not replayed as a burst.

Consequence: a digest that missed the night still runs once at boot, not 24 times.

Console health on each row exposes driftMs, overdue, missedRuns, and catchUp: "one". Flow retry is separate — it retries a failed fire, not missed calendar slots.

Store Lifecycle & Console

Named clocks reconcile into the Store at boot. The scheduler reads effective state from the Store, never the source declaration directly.

Declared  (Manifest / code)     ← truth for names and defaults
Override  (Store, overridable)  ← operational drift
Effective = declared + override ← what actually runs

Reconcile upserts still-declared clocks as active (preserving lease / lastRunAt / overrides when overridable). Removed declarations become orphaned.

Consequence: without overridable: true, change the schedule in source and redeploy — Console edits are refused. Redeploying a still-overridable clock preserves overrides.

DST gap / fall-back overlap attaches a Store warning (gap / overlap); UTC never warns; the scheduler still ticks. Detection covers simple M H * * * / M H * * DOW forms; on overlap days crontab fires once (first occurrence).

Troubleshooting

Learn more

• Clock overview — fx.clock helpers and drivers
• Clock · Inline or named export — one Flow vs shared schedule
• Durable Sleep — fx.clock.sleep(label, duration)
• Consumers · Clock Jobs — bind with on(clockDecl, flow)
• fx — fx.clock.now / ago / fromNow / duration
• Errors — ScheduleNotOverridableError · ClockResourceNotFoundError · OKE1072

Next