run()

Overview

The run() function is the entry point for starting your Runner application. It initializes a resource (and all its dependencies), manages the lifecycle, and returns a runtime instance for executing tasks and emitting events.

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

const app = r.resource("app")
  .register([myTask, myService])
  .build();

const runtime = await run(app);
await runtime.runTask(myTask, { name: "Ada" });
await runtime.dispose();

Signature

async function run<C, V extends Promise<any>>(
  resourceOrResourceWithConfig:
    | IResourceWithConfig<C, V>
    | IResource<void, V, any, any>
    | IResource<{ [K in any]?: any }, V, any, any>,
  options?: RunOptions
): Promise<RunResult<V extends Promise<infer U> ? U : V>>

Parameters

resourceOrResourceWithConfig

IResource | IResourceWithConfig

required

The resource to run, optionally with configuration.Pass without config:

const runtime = await run(app);

Pass with config:

const runtime = await run(app.with({ port: 3000 }));

options

RunOptions

Configuration options for the runtime.

Show RunOptions properties

debug

DebugFriendlyConfig

Enable debug mode with logging to console.

logs

object

Configure logging settings.

Show logs properties

printThreshold

LogLevels | null

default:"info"

Minimum log level to print. Use null to disable logging. In test environment (NODE_ENV=test), defaults to null.

printStrategy

'pretty' | 'json'

default:"pretty"

Format for log output.

bufferLogs

boolean

default:"false"

Buffer logs until root resource is ready.

errorBoundary

boolean

default:"true"

Install a central error boundary to catch uncaught process-level errors.

shutdownHooks

boolean

default:"true"

Install SIGINT/SIGTERM handlers for graceful shutdown.

onUnhandledError

OnUnhandledError

Custom handler for unhandled errors. Defaults to logging via the created logger.

dryRun

boolean

default:"false"

Validate setup without initializing resources or emitting events. Useful for testing.

runtimeEventCycleDetection

boolean

default:"true"

Enable runtime cycle detection for event emissions. Disable to improve performance if you’re certain there are no cycles.

lazy

boolean

default:"false"

Skip initializing unused resources at startup. Load them on-demand via getLazyResourceValue().

initMode

'sequential' | 'parallel'

default:"sequential"

Control how resources are initialized during startup.

sequential: Initialize resources one at a time (safer, deterministic)
parallel: Initialize resources concurrently (faster)

mode

'dev' | 'prod' | 'test'

Specify the runtime mode. Automatically detected from NODE_ENV if not provided.

Returns

runtime

RunResult<V>

A runtime instance providing access to:

Task execution via runTask()
Event emission via emitEvent()
Resource access via getResourceValue() / getLazyResourceValue()
Root access via getRootValue(), getRootConfig(), getRootId()
Lifecycle management via dispose()

See Runtime API for details.

Examples

Basic Usage

const app = r.resource("app")
  .register([greetTask])
  .build();

const runtime = await run(app);
const greeting = await runtime.runTask(greetTask, { name: "World" });
console.log(greeting); // "Hello, World!"
await runtime.dispose();

With Configuration

const server = r.resource("server")
  .configSchema<{ port: number }>({ parse: (v) => v })
  .init(({ config }) => {
    return startServer(config.port);
  })
  .build();

const runtime = await run(server.with({ port: 3000 }));

With Options

const runtime = await run(app, {
  logs: {
    printThreshold: "debug",
    printStrategy: "json",
  },
  lazy: true,
  initMode: "parallel",
});

Dry Run (Testing)

// Validate setup without running
const runtime = await run(app, { dryRun: true });
// No resources initialized, no events emitted
await runtime.dispose();

Custom Error Handling

const runtime = await run(app, {
  onUnhandledError: async (error, context) => {
    await reportToSentry(error);
    console.error("Unhandled error:", error);
  },
});

Lifecycle

When you call run(), the following happens:

Registration Phase: All resources, tasks, events, hooks, and middleware are registered
Validation Phase: Dependency graph and event emission graph are validated
Override Processing: Any overrides are applied
Listener Attachment: Event hooks are attached to their events
Dependency Computation: Dependency injection is resolved
Resource Initialization: Resources are initialized (sequentially or in parallel)
Ready Event: globals.events.ready is emitted
Runtime Active: The runtime is now ready to execute tasks and emit events

Error Handling

If initialization fails, run() will:

Throw the error
Automatically dispose all already-initialized resources
Unhook process-level safety nets

try {
  const runtime = await run(app);
} catch (error) {
  console.error("Failed to start:", error);
  // Resources already cleaned up automatically
}

Runtime API - Working with the runtime instance
Resource Builder - Creating resources
RunResult - Runtime instance methods

Core API

Builders

Runtime

Overview

Signature

Parameters

Returns

Examples

Basic Usage

With Configuration

With Options

Dry Run (Testing)

Custom Error Handling

Lifecycle

Error Handling

Build docs developers (and LLMs) love

Core API

Builders

Runtime

​Overview

​Signature

​Parameters

​Returns

​Examples

​Basic Usage

​With Configuration

​With Options

​Dry Run (Testing)

​Custom Error Handling

​Lifecycle

​Error Handling

​Related

Build docs developers (and LLMs) love

Overview

Signature

Parameters

Returns

Examples

Basic Usage

With Configuration

With Options

Dry Run (Testing)

Custom Error Handling

Lifecycle

Error Handling

Related