BlueLibs Runner

Explicit TypeScript Dependency Injection Toolkit

Build apps from tasks and resources with explicit dependencies, predictable lifecycle, and first-class testing

Runner is a TypeScript-first toolkit for building an app out of small, typed building blocks. You can find more details and a visual overview at runner.bluelibs.com.

• Tasks: async functions with explicit dependencies, middleware, and input/output validation
• Resources: singletons with init/dispose lifecycle (databases, clients, servers, caches)
• Reliability Middleware: built-in retry, timeout, circuitBreaker, cache, and rateLimit
• HTTP Tunnels: cross-process execution (the "Distributed Monolith") with zero call-site changes
• Durable Workflows: persistent, crash-recoverable async logic for Node.js
• Events & hooks: typed signals and subscribers for decoupling
• Runtime control: run, observe, test, and dispose your app predictably

The goal is simple: keep dependencies explicit, keep lifecycle predictable, and make your runtime easy to control in production and in tests.

import { r, run, globals } from "@bluelibs/runner";
import { z } from "zod";

// resources are singletons with lifecycle management and async construction
const db = r
  .resource("app.db")
  .init(async () => {
    const conn = await postgres.connect(process.env.DB_URL);
    return conn;
  })
  .build();

const mailer = r
  .resource("app.mailer")
  .init(async () => ({
    sendWelcome: async (email: string) => {
      console.log(`Sending welcome email to ${email}`);
    },
  }))
  .build();

// Define a task with dependencies, middleware, and zod validation
const createUser = r
  .task("users.create")
  .dependencies({ db, mailer })
  .middleware([globals.middleware.task.retry.with({ retries: 3 })])
  .inputSchema(z.object({ name: z.string(), email: z.string().email() }))
  .run(async (input, { db, mailer }) => {
    const user = await db.users.insert(input);
    await mailer.sendWelcome(user.email);
    return user;
  })
  .build();

// Compose resources and run your application
const app = r
  .resource("app") // top-level app resource
  .register([db, mailer, createUser]) // register all elements
  .build();

const runtime = await run(app);
await runtime.runTask(createUser, { name: "Ada", email: "[email protected]" });
// await runtime.dispose() when you are done.

| Resource | Type | Description | | ------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------- | | Official Website & Documentation | Website | Overview and features | | GitHub Repository | GitHub | Source code, issues, and releases | | Runner Dev Tools | GitHub | Development CLI and tooling | | API Documentation | Docs | TypeDoc-generated reference | | AI-Friendly Docs | Docs | Compact summary (<5000 tokens) | | Full Guide | Docs | Complete documentation (composed) | | Support & Release Policy | Docs | Support windows and deprecation | | Design Documents | Docs | Architecture notes and deep dives | | Example: Express + OpenAPI + SQLite | Example | REST API with OpenAPI specification | | Example: Fastify + MikroORM + PostgreSQL | Example | Full-stack application with ORM |

Community & Policies

• Code of Conduct
• Contributing
• Security

Choose Your Path

• New to Runner: Start with Your First 5 Minutes
• Prefer an end-to-end example: Jump to Quick Start or the Real-World Example
• Need Node-only capabilities: See Durable Workflows
• Need remote execution: See HTTP Tunnels (expose from Node.js, call from any fetch runtime)
• Care about portability: Read Multi-Platform Architecture
• Planning upgrades: See Support & Release Policy
• Want the complete guide: Read FULL_GUIDE.md
• Want the short version: Read AI.md

Platform Support (Quick Summary)

| Capability | Node.js | Browser | Edge | Notes | | ------------------------------------------------------ | ------- | ------- | ---- | ------------------------------------------ | | Core runtime (tasks/resources/middleware/events/hooks) | Full | Full | Full | Platform adapters hide runtime differences | | Async Context (r.asyncContext) | Full | None | None | Requires Node.js AsyncLocalStorage | | Durable workflows (@bluelibs/runner/node) | Full | None | None | Node-only module | | Tunnels client (createHttpClient) | Full | Full | Full | Requires fetch | | Tunnels server (@bluelibs/runner/node) | Full | None | None | Exposes tasks/events over HTTP |

Prerequisites

Use these minimums before starting:

| Requirement | Minimum | Notes | | --------------- | ----------------------- | ----------------------------------------------------------------------- | | Node.js | 18.x | Enforced by package.json#engines.node | | TypeScript | 5.6+ (recommended) | Required for typed DX and examples in this repository | | Package manager | npm / pnpm / yarn / bun | Examples use npm, but any modern package manager works | | fetch runtime | Built-in or polyfilled | Required for tunnel clients (createHttpClient, universal HTTP client) |

If you use the Node-only package (@bluelibs/runner/node) for durable workflows or exposure, stay on a supported Node LTS line.

Your First 5 Minutes

New to Runner? Here's the absolute minimum you need to know:

1. Tasks are your business logic functions (with dependencies and middleware)
2. Resources are shared services (database, config, clients) with lifecycle (init / dispose)
3. You compose everything under an app resource with .register([...])
4. You run it with run(app) which gives you runTask() and dispose()

That's it. Now let's get you to a first successful run.

Quick Start

This is the fastest way to run the TypeScript example at the top of this README:

0. Confirm prerequisites from Prerequisites (Node 18+, TypeScript 5.6+ recommended)

1. Install dependencies:

npm i @bluelibs/runner zod
npm i -D typescript tsx

2. Copy the example into index.ts
3. Run it:

npx tsx index.ts

That's it! You now have a working Runtime and you can execute tasks with runtime.runTask(...).

Tip: If you prefer an end-to-end example with HTTP, OpenAPI, and persistence, jump to the examples below.

Runner Dev Tools Quick Start

@bluelibs/runner-dev gives you CLI scaffolding and runtime introspection.

1. Install (or run without install):

npm install -g @bluelibs/runner-dev
# or
npx @bluelibs/runner-dev --help

2. Three common commands:

# Scaffold a new Runner project
runner-dev new my-app --install

# Query tasks from a local TypeScript entry file (dry-run mode)
runner-dev query 'query { tasks { id } }' --entry-file ./src/main.ts

# Inspect a running app via GraphQL endpoint
ENDPOINT=http://localhost:1337/graphql runner-dev overview --details 10

For full CLI and Dev UI docs, see Runner Dev Tools.

Real-World Examples

• Express + OpenAPI + SQLite
• Fastify + MikroORM + PostgreSQL

Where To Go Next

• Complete guide: Read FULL_GUIDE.md (the full reference, composed from guide-units/)
• Popular guide sections:
  • Tasks
  • Resources
  • Middleware
  • Testing
  • Troubleshooting
• API reference: Browse the TypeDoc documentation
• Token-friendly overview: Read AI.md
• Node-only features:
  • Durable Workflows
  • HTTP Tunnels
• Releases and upgrades:
  • GitHub Releases
  • Support & Release Policy
• Operational baseline:
  • Production Readiness Checklist
• Multi-platform architecture: Read MULTI_PLATFORM.md

License

This project is licensed under the MIT License - see LICENSE.md.