fx

fx is the second argument of every do — the single door to the world. This page is the whole surface; each entry notes the effect it records, which feeds the Manifest, caching, and capability checks.

Smallest Example

import { on, flow, http } from "okengine";
import { z } from "zod";
import { db, notes } from "@/schema";

export const create = on(
  http.post({
    in: z.object({ title: z.string().min(1) }),
  }),
  flow({
    do: async ({ title }, fx) => {
      const id = fx.id();
      await fx.store(db).insert(notes).values({ id, title });
      return fx.json.create({ id, title });
    },
  }),
);

import type { Fx } from "okengine";

async function loadNote(id: string, fx: Fx) {
  return fx.store(db).findById(notes, id);
}

What the effects ledger powers

Stores

See Store for the query-builder surface.

Signals

Runs (observability read)

Declare effects: { reads: ["runs"] }. Powers native SLO checkers (Clock + Channel) without a parallel metrics API.

const sloCheckClock = clock.every("ops.slo-check", "5m");

on(
  sloCheckClock,
  flow("ops.slo-check", {
    effects: { reads: ["runs"], sends: ["slo-alert"] },
    do: async (_, fx) => {
      const breaches = await fx.runs.checkSlo(
        "checkout.create",
        { availability: "99.9%", latency: { p95: "200ms" } },
        5 * 60_000,
      );
      if (breaches.length === 0) return;
      await fx.send(sloAlert, {
        to: "oncall@example.com",
        data: { flow: "checkout.create", count: breaches.length },
      });
    },
  }),
);

Flows

fx.call starts the callee with an empty fx.auth (fail-closed for authorization) and propagates fx.tenant.id. For audit/attribution only, read fx.principal — it propagates the originating identity without copying into fx.auth. Gates never consult fx.principal.

Concurrency and retry

Pass thunks to all / race — not already-started Promises — so each branch gets an abort scope before work begins.

const [user, stock] = await fx.all([
  () => fx.store(db).findById(users, input.userId),
  () => fx.store(db).findById(inventory, input.sku),
]);

const charge = await fx.step("charge", () =>
  fx.retry(() => fx.call(stripeCharge, { amount: input.total }), {
    retries: 3,
    delay: "100ms",
    backoff: 2,
    jitter: true,
  }),
);

fx.using(acquire, release, use) scopes a process-local resource to one attempt: release runs exactly once when use settles or when the ambient signal aborts (a sibling fx.race winner, a failing fx.all sibling). It is not journaled — do not hold handles across durable park/resume.

const rows = await fx.using(
  () => pool.acquire(),
  (conn) => conn.release(),
  (conn) => conn.query("select …"),
);

Consequence: put fx.retry inside fx.step on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is flow(name, { retry: { … } }) on the same journal session.

Channel

Omit locale opts and the send uses fx.locale. Dry runs record would have fired and never contact a provider. Channel bodies use {{field}} catalogs — not ICU (see Channel).

Outbound HTTP

Declare hosts in effects.fetches (e.g. ["api.stripe.com"]). Prefer fx.step; use fx.retry only when the remote API is safe to repeat. Dry runs never hit the network.

Use this for third-party REST outside Channel / AI / Store — not as a substitute for those elements.

AI

AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. tools are Flow refs — each model tool call goes through fx.call (same capability and Runs path).

Driver-reported EffectEntry.external marks cloud providers as third-party and self-hosted / provider: "local" as infrastructure (Console waterfall dashed egress + host tooltip).

Vault

get reads through the boot resolution chain. Everything else needs the encrypted-at-rest backend (drivers.vault = "vault") and throws without it.

Clock

Durations: "200ms" · "30s" · "2m" · "1h" · "7d". A "d" is 86_400_000 ms, not a calendar day. Unknown strings parse as 0.

Cache

Read-only flows cache automatically from inferred or ledgered reads — no fx.cache call and no cache: default on the flow. Writes invalidate those keys. Use cache: false to opt out, or cache: "30s" for a TTL.

fx.cache is the manual (tier-3) surface:

Responses

Returning a plain value instead answers 200 with { data: value, error: null } — the helpers exist for status and meta control. Pass fx.stream(...) into fx.json.stream to reach the HTTP client token-by-token.

Logging, i18n, ids

Catalogs, ICU syntax, and Register augmentation live on i18n. Id options: OKID. Localized fx.fail / OkeError catalogs: Errors.

Principals

Consequence: use fx.auth / gates for authorization; use fx.principal only when a callee must log who started the call chain. A key Bearer sets userId to the issuer and apiKeyId to the key — see Gate.

Not on fx

Troubleshooting

Learn more

• Flow — why fx is the only door
• Channel — fx.send, consent, locale chain, {{field}} catalogs
• i18n — fx.t, catalogs, locale matching
• Errors — what fx.fail produces
• Configuration — drivers and the i18n block
• OKID — fx.id() options

Next