Overview

Signal is how your backend moves data when the producer should not wait. An email job, a cache bust across instances, and a browser status feed share one handle shape — only the helper changes: signal.once, signal.broadcast, or signal.live.

For developers wiring async work on okengine — declare the physics, emit with fx.emit, bind workers with on(handle, flow("name", { do })).

Smallest Example

Declare

import { signal } from "okengine";
import { z } from "zod";

export const orderPlaced = signal.once("orders.placed", {
  schema: z.object({
    orderId: z.string(),
    amount: z.number(),
    userId: z.string(),
  }),
  retries: 5,
  deadLetter: true,
});

Bind a worker

import { on, flow } from "okengine";
import { orderPlaced } from "@/signals/orders";

export const fulfill = on(
  orderPlaced,
  flow("orders.fulfill", {
    do: async ({ orderId }, fx) => {
      await fx.call(chargeAndShip, { orderId });
    },
  }),
);

Emit

// Inside any Flow — need not live next to the worker:
await fx.emit(orderPlaced, {
  orderId: "ord_99",
  amount: 150,
  userId: "usr_1",
});

The compiler records emits: ["orders.placed"] on the producer. The HTTP request does not wait for the worker.

A string fx.emit("name", payload) still runs (runtime schema still applies) but does not type-check. Import the exported const.

Progressive Patterns

Same helpers + fx.emit from a queue job to a fan-out and a browser feed:

import { signal } from "okengine";
import { z } from "zod";

export const emailTask = signal.once("tasks.email", {
  schema: z.object({ to: z.string().email(), body: z.string() }),
  retries: 3,
  deadLetter: true,
});

import { on, flow } from "okengine";
import { emailTask } from "@/signals/email";
import { rawEmail } from "@/channels/email";

export const processEmail = on(
  emailTask,
  flow("workers.email", {
    do: async ({ to, body }, fx) => {
      await fx.send(rawEmail, { to, body });
    },
  }),
);

Delivery Physics

Competing consumers (once vs broadcast)

This is the most common mix-up. signal.once is a work queue: exactly one worker claims each message. It is not fan-out.

Three differently-named Flows bound to the same once signal, then one emit:

import { on, flow } from "okengine";
import { orderPlaced } from "@/signals/orders";

export const charge = on(
  orderPlaced,
  flow("orders.charge", {
    do: async ({ orderId }, fx) => {
      await fx.call(chargeOrder, { orderId });
    },
  }),
);
export const ship = on(
  orderPlaced,
  flow("orders.ship", {
    do: async ({ orderId }, fx) => {
      await fx.call(shipOrder, { orderId });
    },
  }),
);
export const notify = on(
  orderPlaced,
  flow("orders.notify", {
    do: async ({ orderId }, fx) => {
      await fx.call(notifyOrder, { orderId });
    },
  }),
);

await fx.emit(orderPlaced, { orderId: "ord_99", amount: 150, userId: "usr_1" });

Consequence: if every bound Flow should independently receive its own copy, that is signal.broadcast — switch the declaration. That is the correct fix for this exact mistake.

Two or more different Flow definitions on the same once signal fail OKE1071.

Cause: Once signal "{signal}" is bound to more than one Flow ({flows}).

Load-balancing competing consumers is the same Flow on many process replicas — still one on() in source.

Fix: Use signal.broadcast if each flow should independently receive this event, or bind only one flow if these should compete for the same work.

The Capabilities of Signal

Options Reference

Optional second argument to signal.once / signal.broadcast / signal.live. Delivery is the helper name — not an option.

Consequence: deadLetter is a boolean flag, not a queue name string.

Emit through fx

Invalid schema payloads fail at emit with OKE1250 ("{resource}": {detail}) before any consumer runs. Cross-signal fx.deadLetters / fx.live without a declared read throws OKE1001.

await fx.emit(orderPlaced, { orderId: "ord_1", userId: "usr_1" }, { key: "usr_1" });

Omit key for a pure competing pool with no ordering.

Per-environment drivers

Protocol ids: memory · redis · postgres · nats. Defaults (when oke.config.ts omits drivers.signal):

export default defineConfig({
  drivers: {
    signal: { test: "memory", prod: "redis" },
  },
});

postgres and nats fail loud at boot until a native bind ships — never silently fall back to memory. Prefer memory for tests; pin redis when Compose provides Redis.

Troubleshooting

Learn more

• Once — leases, retries, partition keys, DLQ
• Broadcast — ephemeral fan-out
• Live — SSE tapes and retention
• Consumers — on(signal) workers next to Clock / CDC
• HTTP · Live Streams — http.live exposure
• fx — fx.emit, fx.deadLetters, fx.live
• Client — api.live for browsers
• Errors — OKE1070 · OKE1071 · OKE1072 · OKE1240 · OKE1250 · OKE1210

Next