Timers

Schedule from a handler

import { createServer } from 'experimental-a2/server'
import { vercelQueues } from 'experimental-a2/scheduler-vercel'
import { orders } from '@/contracts'

export const scheduler = vercelQueues()

export const ordersServer = createServer({
  contract: orders,
  scheduler,
  handlers: {
    created: async ({ session }) => {
      await session.schedule(
        'expire-order',
        { delay: '5d' },
        { type: 'expired', payload: {} },
      )
    },
    expired: async ({ session }) => {
      const events = await session.history()
      if (events.some((event) => event.type === 'shop.started')) return
      // your expiry side effect goes here
    },
  },
})

Configure a scheduler, then call session.schedule(name, timing, ...events). The scheduler route that handles recovery delivers timers too; mount it once.

timing is { delay } (units ms, s, m, h, d, checked by the type) or { at: Date }. A delay must be a finite, unsigned base-10 decimal above zero with no leading zeros; A2 rejects 0s, signs, exponent notation, malformed strings, and invalid dates.

The call resolves once the provider accepts the task; nothing enters the log until delivery. The target is the earliest delivery time, not a deadline: adapters round to whole seconds, and an already-due target sends immediately.

Schedule from ordinary server code

import { z } from 'zod'
import { ordersServer } from '@/server/orders'

const scheduleTrial = z.object({
  orderId: z.string(),
  expiresAt: z.iso.datetime().transform((value) => new Date(value)),
})

export async function POST(request: Request) {
  const body = scheduleTrial.parse(await request.json())
  await ordersServer.session(body.orderId).schedule(
    'expire-order',
    { at: body.expiresAt },
    { type: 'expired', payload: {} },
  )
  return Response.json({ scheduled: true }, { status: 202 })
}

Root sessions have the same method. A root { delay: '30s' } counts from that call's clock, so a retry 10 seconds later delivers 10 seconds later too. Use { at } when a caller may retry. Inside a handler, a delay counts from the triggering event's durable createdAt, so retries keep the same target.

Identity and retries

name identifies one schedule: per contract and session at the root, plus the triggering event id in a handler. Different events can share a name like expire-order, while retries of one event converge.

Keep the same name, timing, and events on every retry. Omitted event ids are derived and stable, so duplicate deliveries append once per session lifetime, even after the provider's deduplication window. A clear frees those ids, so a root task redelivered after one appends again. Changed input under the same name conflicts at delivery when it produces a different validated event.

What arrives later

Payloads travel in the provider message as plain JSON: encode a Date as an ISO string and a class as plain data. A2 rejects undefined, functions, symbols, bigints, cycles, accessors, and non-plain prototypes, and shared references arrive as copies. At delivery, an ordinary top-level append with fixed ids validates the original input, so a schema transform runs on that input, not on an earlier output.

Scheduled events enter the log only when delivered, with cause: null. From there they behave like any server append: handlers, lanes, reducers, streams, and live clients see them normally, and their stable ids absorb at-least-once delivery.

If the receiving deployment changed or removed the event's schema, delivery can fail validation and then keeps retrying as a scheduler error. The Vercel adapter pins timers to their publishing deployment by default; with deploymentId: null or a stable URL like QStash's, keep schemas compatible. See Deploys and rollbacks.

Stale timers

The order shipped on day two; its expiry still arrives on day five. Use the guard from the first example: let the event land, read the session, and return when it no longer applies. The log still records that the timer fired.

A2 has no cancellation, reschedule, cron, or timer-listing API. name is an idempotency key, not a handle. For repeating work, have each occurrence's handler schedule the next one.

Provider limits

A2 does not split a longer delay into several tasks. Vercel Queues keeps messages for seven days, and A2 reserves the final day for delivery and retries. At a QStash maximum, leave at least one second of margin: its notBefore uses whole Unix seconds.