API reference › @evolu/nodejs › runMain

Call Signature

function runMain<T>(main: Task<T>, options?: RunMainOptions): Promise<void>;

Defined in: packages/nodejs/src/Task.ts:106

Runs the main Task as the Node.js program lifecycle.

Creates one root Run and aborts it on:

  • SIGINT: Ctrl-C on all platforms.
  • SIGTERM: OS, service, Docker, or Kubernetes termination on Unix.
  • SIGBREAK: Ctrl-Break on Windows.

The first signal logs shutdown progress, aborts the root Run, and waits for the main Task and structured cleanup to finish. A subsequent signal exits immediately with its conventional signal status, abandoning cleanup. A signal received during final cleanup still applies signal shutdown behavior.

A main Task returning Resource keeps the program running until a termination signal and is disposed during shutdown. A main Task returning void completes the program immediately. A Resource result transfers ownership of a live resource that must remain valid after its creating Task settles.

Service mode treats graceful signal shutdown as successful. Command mode preserves conventional signal exit statuses. Every defect reported through reportDefect, including an observer defect that does not abort the Run, sets process.exitCode to 1. The default reporter logs to the configured Evolu console.

Escaped uncaught exceptions and unhandled rejections remain under Node.js native reporting and termination.

Service Example

const deps = { ...createRelayDeps(), console: createConsole() };

await runMain(deps)(createRelay({ port: 4000 }));

A Task returning void can keep a service alive explicitly when no Resource owns its lifetime:

await runMain(deps)(async (run) => {
  void run(processMessages);
  return await run(waitForAbort);
});

Command Example

await runMain(command, { mode: "command" });

Call Signature

function runMain<D>(
  deps: RunCustomDeps<D>,
  options?: RunMainOptions,
): <T>(main: Task<T, never, D>) => Promise<void>;

Defined in: packages/nodejs/src/Task.ts:111

With custom dependencies.

Markdown for LLMs