Overview
Runner provides a set of global components that are automatically available in your application. These include core services, events, middleware, and utility resources.
import { globals, run } from "@bluelibs/runner";
Global Resources
Access built-in resources via the globals namespace:
const myTask = r.task("app.task")
.dependencies(() => ({
logger: globals.resources.logger,
store: globals.resources.store,
}))
.run(async ({ deps }) => {
await deps.logger.info("Task started");
})
.build();
globals.resources
Central store containing all registered tasks, events, resources, and metadata.dependencies(() => ({ store: globals.resources.store }))
Framework logger for diagnostics and debugging..run(async ({ deps }) => {
await deps.logger.info("Message");
await deps.logger.error("Error", { context: "details" });
})
Access to the runtime instance (RunResult) from within tasks/resources..run(async ({ deps }) => {
const value = deps.runtime.getResourceValue(someResource);
await deps.runtime.emitEvent(myEvent, payload);
})
Event manager for emitting events and managing hooks.
Task runner that executes tasks with middleware pipeline.
Manager for task and resource middleware.
Serializer for converting objects to/from JSON (used in durable workflows).
Cache state resource (used by cache middleware).
Queue resource for managing task queues.
Cron scheduling resource for periodic tasks.
Rate limiting state resource (used by rate limit middleware).
Circuit breaker state resource (used by circuit breaker middleware).
Temporal state resource for debounce/throttle middleware.
Concurrency control resource (used by concurrency middleware).
Factory for creating HTTP clients.
Debug configuration resource.
Global Events
Access built-in events via globals.events:
globals.events.ready
Emitted when the system is fully initialized and ready for work.
const startupHook = r.hook("app.hooks.startup")
.on(globals.events.ready)
.run(async () => {
console.log("System is ready!");
})
.build();
void
When emitted: Right before run() returns the runtime instance, after all resources have been initialized.
Global Middleware
Runner provides built-in middleware for common patterns:
import { globals } from "@bluelibs/runner";
const myTask = r.task("app.task")
.middleware([
globals.middleware.task.retry.with({ maxAttempts: 3 }),
globals.middleware.task.timeout.with({ ms: 5000 }),
])
.build();
Task Middleware
globals.middleware.task.retry
Retry failed task executions..middleware([globals.middleware.task.retry.with({ maxAttempts: 3, delayMs: 1000 })])
globals.middleware.task.timeout
Abort task execution after a timeout..middleware([globals.middleware.task.timeout.with({ ms: 5000 })])
globals.middleware.task.cache
Cache task results based on input..middleware([globals.middleware.task.cache.with({ ttl: 60000 })])
globals.middleware.task.circuitBreaker
Prevent cascading failures with circuit breaker pattern..middleware([globals.middleware.task.circuitBreaker.with({
failureThreshold: 5,
resetTimeoutMs: 30000
})])
globals.middleware.task.rateLimit
Limit task execution rate..middleware([globals.middleware.task.rateLimit.with({
maxCalls: 10,
windowMs: 60000
})])
globals.middleware.task.concurrency
Limit concurrent task executions..middleware([globals.middleware.task.concurrency.with({ maxConcurrent: 5 })])
globals.middleware.task.fallback
Provide fallback logic on task failure..middleware([globals.middleware.task.fallback.with({
fallback: async () => "default value"
})])
globals.middleware.task.debounce
Debounce task execution..middleware([globals.middleware.task.debounce.with({ delayMs: 500 })])
globals.middleware.task.throttle
Throttle task execution..middleware([globals.middleware.task.throttle.with({ intervalMs: 1000 })])
globals.middleware.task.requireContext
Require an async context to be present..middleware([globals.middleware.task.requireContext.with({ context: requestContext })])
Resource Middleware
globals.middleware.resource.retry
Retry failed resource initialization..middleware([globals.middleware.resource.retry.with({ maxAttempts: 3 })])
globals.middleware.resource.timeout
Abort resource initialization after a timeout..middleware([globals.middleware.resource.timeout.with({ ms: 10000 })])
globals.tags:
import { globals } from "@bluelibs/runner";
const myTask = r.task("app.task")
.tags([globals.tags.debug])
.build();
Tunnels
Access tunnel functionality (Node.js only):
import { globals } from "@bluelibs/runner";
// Access tunnel resources
globals.tunnels
Debug
Access debug utilities:
import { globals } from "@bluelibs/runner";
const runtime = await run(app, {
debug: globals.debug.simple(),
});
export const globals: {
events: {
ready: IEvent<void>;
};
resources: {
store: IResource;
logger: IResource;
runtime: IResource;
eventManager: IResource;
taskRunner: IResource;
middlewareManager: IResource;
serializer: IResource;
cache: IResource;
queue: IResource;
cron: IResource;
rateLimit: IResource;
circuitBreaker: IResource;
temporal: IResource;
concurrency: IResource;
httpClientFactory: IResource;
debug: IResource;
};
middleware: {
task: { /* task middleware */ };
resource: { /* resource middleware */ };
};
middlewares: typeof middleware; // Alias
tags: { /* built-in tags */ };
tunnels: { /* tunnel utilities */ };
debug: { /* debug utilities */ };
};