npm package: @silyze/background-runner-execute-instantly
Description: Local and instant execution transport for @silyze/background-runner
Author: Mihail Mojsoski
Latest version: 1.0.0

# Background Runner – Execute Instantly

> **A zero‑overhead, in‑process transport for [`@silyze/background-runner`](https://npmjs.com/package/@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

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

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

---

## Quick start

```ts
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)_

```ts
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.