Skip to content

State timeouts and schedules

A state timeout runs one of an actor’s commands when the actor stays in a state too long. A cron schedule runs a command at each due time of a cron expression. Both are declared in the contract and run their command as Akter.System.

Expire a state and run hourly work⁠

  1. Declare timeouts and schedules on the contract in hold.contract.ts. Each binding names a command that lists Akter.System in callers and takes Schema.Void.
hold.contract.ts
import { Cron, Duration, Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"

export const Shopper = Akter.caller("user", Schema.Struct({ id: Akter.PrincipalId }))

export const Held = Schema.TaggedStruct("Held", { checks: Schema.Int })

export const Released = Schema.TaggedStruct("Released", { checks: Schema.Int })

export const Hold = Akter.make("Hold", {
  callers: [Shopper, Akter.System],
  commands: {
    check: Akter.command({
      callers: [Akter.System],
      errors: [],
      from: [Held, Released],
      input: Schema.Void,
      output: Schema.Void,
      to: [Held, Released],
    }),
    release: Akter.command({
      callers: [Akter.System],
      errors: [],
      from: [Held],
      input: Schema.Void,
      output: Schema.Void,
      to: [Released],
    }),
  },
  initial: { input: Schema.Struct({}), to: Held },
  key: Schema.String,
  parent: Akter.Root,
  queries: {
    status: Akter.query({
      callers: [Shopper],
      errors: [],
      input: Schema.Void,
      output: Schema.String,
      states: [Held, Released],
    }),
  },
  schedules: [Akter.schedule({ command: "check", cron: Cron.parseUnsafe("0 * * * *") })],
  states: [Held, Released],
  tables: [],
  timeouts: [Akter.timeout({ after: Duration.minutes(15), command: "release", state: Held })],
})
  1. Implement the bound commands in hold.actor.ts like any other command.
hold.actor.ts
import { Effect } from "effect"
import { Held, Hold, Released } from "./hold.contract.ts"

export const HoldLive = Hold.toLayer({
  commands: {
    check: (hold) => {
      const checks = hold.checks + 1
      return Effect.succeed({ next: hold._tag === "Held" ? Held.make({ checks }) : Released.make({ checks }) })
    },
    release: (held) => Effect.succeed({ next: Released.make({ checks: held.checks }) }),
  },
  initial: () => ({ next: Held.make({ checks: 0 }) }),
  queries: {
    status: (hold) => Effect.succeed(`${hold._tag} after ${hold.checks} checks`),
  },
})
  1. Advance the clock with story.advance in hold.story.ts. The timeout fires 15 minutes after the actor enters Held, and the schedule fires at the start of each hour.
hold.story.ts
import { Effect } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { Story } from "@akterjs/effect/testing"
import { Hold, Shopper } from "./hold.contract.ts"
import { HoldLive } from "./hold.actor.ts"

const as = { caller: Shopper, principal: { id: Akter.PrincipalId.make("ada") } }

const program = Story.run(HoldLive, function* (story) {
  yield* story.create(Hold, "cart", { as, input: {} })

  const hold = yield* story.actor(Hold, "cart", { as })
  yield* story.advance("14 minutes")
  console.log(yield* hold.status())

  yield* story.advance("1 minute")
  console.log(yield* hold.status())

  yield* story.advance("1 hour")
  console.log(yield* hold.status())
})

Effect.runPromise(program)
Text
Held after 0 checks
Released after 0 checks
Released after 1 checks

Why timeouts and schedules live in the contract⁠

A state timeout belongs to a state rather than to a command. Declaring it in the contract lets the host arm and cancel it with the state change, so no handler has to remember to cancel it. A cron schedule has no caller of its own, so it runs as Akter.System. Clients can never send a command that lists only Akter.System.

akter verify reads each timeout as an edge from its state to the to states of its command (verify).

What you can rely on⁠

  • State timeouts end with their state. The host arms a state’s timeouts when the actor enters that state. It cancels them in the commit that leaves the state, and re-entering the state starts a new timeout.
  • A fired timeout runs once. The in-memory test host runs a timeout’s command one time. A commit, a declared error, a defect, or a refusal all spend the timeout. A failed run rolls back and is not retried. The state gets a new timeout only when the actor leaves it and enters it again.
  • Schedules run as the system caller. The host runs each schedules command at every due time of its cron expression, as Akter.System.
  • Schedules run in UTC. The host reads every cron expression in UTC, whatever the time zone of the machine. Akter.schedule throws InvalidScheduleError for a Cron that carries a time zone.
  • Schedules fire. Akter.schedule throws InvalidScheduleError for a cron with no future fire time, such as 0 0 30 2 *.
  • Timeouts wait whole milliseconds. Akter.timeout throws InvalidTimeoutError when after is infinite, negative, zero, a fraction of a millisecond, or above Number.MAX_SAFE_INTEGER milliseconds.
  • Bound commands. The type checker rejects a timeout or schedule command that does not list Akter.System, or that takes input. It also rejects a timeout whose command does not list the timeout’s state in from.
  • No inline handlers. The akter/declarative-bindings lint rule rejects a function or a computed name in timeouts and schedules.