@silyze/background-runner v1.0.0

Background Runner

Background Runner is a tiny, type‑safe framework for executing tasks off the main call‑site – whether that means a local queue, a TCP worker, or a fully remote job system.

It gives you three primitives:

Everything is inferred so you can only call jobs that exist, with the right parameter shapes – no schema files or codegen needed.

Features

• End‑to‑end type‑safety – Job names and parameter tuples are checked at compile time.
• Pluggable transport – Swap ExecuteInstantly for a queue, WebSocket, or message broker without touching caller code.
• Zero dependencies – Ships as pure TypeScript typings + ~1 kB runtime.
• Structured clone example shows deep‑copy to keep workers pure.

Installation

npm install @silyze/background-runner

Requires TypeScript 5.2+ and Node 18+ (tested on 20 LTS).

Quick start

import {
  handler,
  registry,
  BackgroundRunner,
  JobHandler,
  RegistryName,
  MaybeRegistryJobHandler,
  JobTransport,
} from "@silyze/background-runner";

/**
 * A naïve transport that just calls the handler immediately.
 * Replace this with a RabbitMQ or Redis implementation later.
 */
function ExecuteInstantly<
  R extends JobHandler<string, any>[],
  N extends RegistryName<R>
>(
  getJobHandler: <F extends N>(name: F) => MaybeRegistryJobHandler<F, R>
): JobTransport<R, N> {
  return {
    handleJob(name, params) {
      const jobHandler = getJobHandler(name);
      // optional: network hop, retry logic, etc.
      // @ts-ignore – deep copy keeps job code pure
      jobHandler?.handler(...structuredClone(params));
    },
  };
}

/** Job definitions */
const consoleRegistry = registry(
  handler("log", async (msg: string) => console.log(msg)),
  handler("error", async (msg: string) => console.error(msg)),
  handler("warn", async (msg: string) => console.warn(msg))
);

/** Runner bound to our transport */
const consoleRunner = new BackgroundRunner(consoleRegistry, ExecuteInstantly);

/** Fire‑and‑forget jobs */
consoleRunner.run("log", "Hello background world!");
consoleRunner.run("error", "Something went wrong…");
consoleRunner.run("warn", "Heads‑up!");

API Reference

Types & Helpers

handler(name, fn)

Create a job handler.

const sendEmail = handler("send-email", async (to: string, body: string) => {
  /* … */
});

registry(...handlers)

Bundle handlers so they can share a runner.

const mailRegistry = registry(
  sendEmail,
  handler("ping", () => {})
);

JobTransport

Interface a transport must fulfil:

interface JobTransport<Registry, Name> {
  handleJob(name: Name, params: ParamsTuple): void;
}

Implementations typically serialize & enqueue the call, then a worker dequeues and executes.

BackgroundRunner

new BackgroundRunner(registry, transportFactory);

• registry – Output of registry(...).
• transportFactory(getJobHandler) – Function that returns a JobTransport. You receive a safe getJobHandler helper for worker‑side lookup.

The runner exposes:

run(name, ...params): void

Type checking guarantees name exists and params match the handler signature.

Building custom transports

Because BackgroundRunner provides a registry‑aware getJobHandler, your transport doesn’t need reflection. A minimal queue example:

function ViaInMemoryQueue<
  R extends JobHandler<string, any>[],
  N extends RegistryName<R>
>(
  getJobHandler: <F extends N>(name: F) => MaybeRegistryJobHandler<F, R>
): JobTransport<R, N> {
  const queue: { name: N; params: SerializableValue[] }[] = [];

  return {
    handleJob(name, params) {
      queue.push({ name, params });
    },
  };

  // somewhere else (worker loop)
  setInterval(() => {
    const job = queue.shift();
    if (!job) return;
    getJobHandler(job.name)?.handler(...job.params);
  }, 100);
}