Background Runner – Execute Instantly

A zero‑overhead, in‑process transport for @silyze/background-runner.

Run your jobs synchronously – perfect for unit tests, CLI tools, or any scenario where you don’t need queues, IPC, or brokers.

Why?

• Instant execution – tasks run immediately in the same call‑stack.
• 100 % type‑safe – preserves the compile‑time guarantees of Background Runner.
• Drop‑in – swap transports later (RabbitMQ, Redis, WebSocket…) with no changes to call‑sites.
• Zero dependencies – tiny footprint, uses the built‑in structuredClone() and a small assertNonNull() helper.

Installation

npm install @silyze/background-runner-execute-instantly

Peer dependency: @silyze/background-runner ≥ 1.0.0.

Quick start

import { BackgroundRunner, handler, registry } from "@silyze/background-runner";
import ExecuteInstantly from "@silyze/background-runner-execute-instantly";

/**
 * 1) Define some jobs
 */
const consoleRegistry = registry(
  handler("log", async (msg: string) => console.log(msg)),
  handler("warn", async (msg: string) => console.warn(msg)),
  handler("error", async (msg: string) => console.error(msg))
);

/**
 * 2) Create a runner bound to the *instant* transport
 */
const consoleRunner = new BackgroundRunner(consoleRegistry, ExecuteInstantly);

/**
 * 3) Fire‑and‑forget (well… almost – they run right now!)
 */
consoleRunner.run("log", "Hello immediate world");
consoleRunner.run("warn", "Heads‑up");
consoleRunner.run("error", "Something broke");

Tip: Because the transport deep‑clones parameters via structuredClone, your handler gets its own copy – no unintended mutation leaks.

API

ExecuteInstantly(getJobHandler) (default export)

default function ExecuteInstantly<
  R extends JobHandler<string, any>[],
  N extends RegistryName<R>
>(
  getJobHandler: <F extends N>(name: F) => MaybeRegistryJobHandler<F, R>
): JobTransport<R, N>;

| Param | Type | Description | | --------------- | ----------------------------------- | ---------------------------------------------------------------------- | | getJobHandler | (name) => MaybeRegistryJobHandler | Provided by BackgroundRunner; resolves a handler by name at runtime. |

Returns a JobTransport whose handleJob(name, params) simply:

1. Looks up the handler via getJobHandler.
2. assertNonNull (throws if job not found – should never happen with a typed registry).
3. Invokes handler(...structuredClone(params)) synchronously.

🏗 When not to use this transport

• Heavy CPU work – it will block the event loop; use a worker thread or queue instead.
• Horizontal scaling – for multi‑process / multi‑machine setups, pick a message broker transport.

Treat Execute Instantly as a baseline: develop locally, unit‑test easily, then graduate to distributed transports without rewriting your business code.