Calling Actions

Once a runtime is wired, calling an action looks the same on any side — client or server — and regardless of where it resolves (locally or over a carrier).

Run to output

The common case: run the action and get its output directly. Throws on a declared or transport error.

const output = await userDomain.action.getUser
  .request({ userId: "u_123" })
  .runToOutput();

console.log(output); // { id: "u_123", name: "Alice" }

Keep the running handle

When you want progress or abort control, keep the RunningAction and await the full result payload:

const running = await userDomain.runAction(
  userDomain.action.getUser.request({ userId: "u_123" }),
);

const result = await running.waitForResultPayload();
console.log(result.output);

Error handling at the call site

Actions declared with .throws(domain, ids?) surface typed errors. Use castNiceError and the domain’s guards to narrow:

import { castNiceError } from "@nice-code/error";

try {
  const output = await userDomain.action.getUser.request({ userId }).runToOutput();
} catch (e) {
  const error = castNiceError(e);
  if (err_user.isExact(error) && error.hasId("not_found")) {
    console.log("User not found:", error.getContext("not_found").userId);
  }
}

The same request(...).runToOutput() shape works whether the action resolves locally (a registered handler in this runtime) or remotely (over a carrier to a peer) — the runtime routes it for you.

Prefer a result over a throw

runToResult() returns a deterministic outcome instead of throwing — branch on expected (did this action declare the error?) rather than wrapping every call in try/catch:

const result = await userDomain.action.getUser.request({ userId }).runToResult();
if (result.ok) use(result.output);
else if (result.expected) handleDeclared(result.error);
else report(result.error); // undeclared NiceError or unhandled foreign throw

This is the recommended path — see Error Handling → for the full model (expected vs isUnhandled, the typed isExpectedError guard, and how it surfaces in devtools).

Next: Error Handling →