@bluelibs/runner 2.2.4 → 3.0.0

package/README.md

@@ -1,4 +1,6 @@
-# BlueLibs Runner
+# BlueLibs Runner: The Framework That Actually Makes Sense
+
+_Or: How I Learned to Stop Worrying and Love Dependency Injection_
 
 <p align="center">
 <a href="https://github.com/bluelibs/runner/actions/workflows/ci.yml"><img src="https://github.com/bluelibs/runner/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build Status" /></a>
@@ -7,1336 +9,1707 @@
 <a href="https://github.com/bluelibs/runner" target="_blank"><img src="https://img.shields.io/badge/github-blue" alt="GitHub" /></a>
 </p>
 
-- [View the documentation page here](https://bluelibs.github.io/runner/).
-- [Google Notebook LM Podcast](https://notebooklm.google.com/notebook/59bd49fa-346b-4cfb-bb4b-b59857c3b9b4/audio)
-- [Continue GPT Conversation](https://chatgpt.com/share/670392f8-7188-800b-9b4b-e49b437d77f7)
-
-BlueLibs Runner is a framework that provides a functional approach to building applications, whether small or large-scale. Its core concepts include Tasks, Resources, Events, and Middleware. Tasks represent the units of logic, while resources are singletons that provide shared services across the application. Events facilitate communication between different parts of the system, and Middleware allows interception and modification of task execution. The framework emphasizes an async-first philosophy, ensuring that all operations are executed asynchronously for smoother application flow.
-
-## Building Blocks
-
-- **Tasks**: Core units of logic that encapsulate specific tasks. They can depend on resources, other tasks, and event emitters.
-- **Resources**: Singleton objects providing shared functionality. They can be constants, services, functions. They can depend on other resources, tasks, and event emitters.
-- **Events**: Facilitate asynchronous communication between different parts of your application. All tasks and resources emit events, allowing you to easily hook. Events can be listened to by tasks, resources, and middleware.
-- **Middleware**: Intercept and modify the execution of tasks or initialisation of your resources. They can be used to add additional functionality to your tasks. Middleware can be global or task-specific.
+- [View the documentation page here](https://bluelibs.github.io/runner/)
 
-These are the concepts and philosophy:
+Welcome to BlueLibs Runner, where we've taken the chaos of modern application architecture and turned it into something that won't make you question your life choices at 3am. This isn't just another framework – it's your new best friend who actually understands that code should be readable, testable, and not require a PhD in abstract nonsense to maintain.
 
-- **Async**: Everything is async, no more sync code for this framework. Sync-code can be done via resource services or within tasks, but the high-level flow needs to run async.
-- **Type safety**: Built with TypeScript for enhanced developer experience and type-safety everywhere, no more type mistakes.
-- **Functional**: We use functions and objects instead of classes for DI. This is a functional approach to building applications.
-- **Explicit Registration**: All tasks, resources, events, and middleware have to be explicitly registered to be used.
-- **Dependencies**: Tasks, resources, and middleware can have access to each other by depending on one another and event emitters. This is a powerful way to explicitly declare the dependencies.
+## What Is This Thing?
 
-Resources return their value to the container using the async `init()` function, making them available throughout the application.
+BlueLibs Runner is a TypeScript-first framework that embraces functional programming principles while keeping dependency injection simple enough that you won't need a flowchart to understand your own code. Think of it as the anti-framework framework – it gets out of your way and lets you build stuff that actually works.
 
-Tasks provide their output through the async `run()` function, allowing the results to be used across the application.
+### The Core Philosophy (AKA Why We Built This)
 
-All tasks, resources, events, and middleware must be explicitly registered to be used. Registration can only be done within resources.
+- **Tasks are functions** - Not classes with 47 methods you'll never use
+- **Resources are singletons** - Database connections, configs, services - the usual suspects
+- **Events are just events** - Revolutionary concept, we know
+- **Everything is async** - Because it's 2025 and blocking code is so 2005
+- **Explicit beats implicit** - No magic, no surprises, no "how the hell does this work?"
 
-## Installation
+## Quick Start (The "Just Show Me Code" Section)
 
 ```bash
 npm install @bluelibs/runner
 ```
 
-## Basic Usage
+Here's a complete Express server in less lines than most frameworks need for their "Hello World":
 
 ```typescript
-import { run, resource } from "@bluelibs/runner";
+import express from "express";
+import { resource, task, run } from "@bluelibs/runner";
 
-const minimal = resource({
-  async init() {
-    return "Hello world!";
+// A resource is anything you want to share across your app
+const server = resource({
+  id: "app.server",
+  init: async (config: { port: number }) => {
+    const app = express();
+    const server = app.listen(config.port);
+    console.log(`Server running on port ${config.port}`);
+    return { app, server };
   },
+  dispose: async ({ server }) => server.close(),
 });
 
-run(minimal).then((result) => {
-  expect(result).toBe("Hello world!");
+// Tasks are your business logic - pure-ish, easily testable functions
+const createUser = task({
+  id: "app.tasks.createUser",
+  dependencies: { server },
+  run: async (userData: { name: string }, { server }) => {
+    // Your actual business logic here
+    return { id: "user-123", ...userData };
+  },
 });
-```
 
-## Resources and Tasks
+// Wire everything together
+const app = resource({
+  id: "app",
+  // Here you make the system aware of resources, tasks, middleware, and events.
+  register: [server, createUser],
+  dependencies: { server, createUser },
+  init: async (_, { server, createUser }) => {
+    server.app.post("/users", async (req, res) => {
+      const user = await createUser(req.body);
+      res.json(user);
+    });
+  },
+});
 
-Resources are singletons and can include constants, services, functions, and more. They can depend on other resources, tasks, and event emitters.
+// That's it. No webpack configs, no decorators, no XML.
+const { dispose } = await run(app, { port: 3000 });
+```
 
-Tasks are designed to be trackable units of logic, such as handling specific routes on your HTTP server or performing actions needed by different parts of the application. This makes it easy to monitor what’s happening in your application.
+## The Big Four: Your New Building Blocks
 
-```ts
-import { task, run, resource } from "@bluelibs/runner";
+### 1. Tasks: The Heart of Your Business Logic
 
-const helloTask = task({
-  id: "app.hello",
-  run: async () => "Hello World!",
-});
+Tasks are functions with superpowers. They're pure-ish, testable, and composable. Unlike classes that accumulate methods like a hoarder accumulates stuff, tasks do one thing well.
 
-const app = resource({
-  id: "app",
-  register: [helloTask],
-  dependencies: {
-    hello: helloTask,
-  },
-  async init(_, deps) {
-    return await deps.hello();
+```typescript
+const sendEmail = task({
+  id: "app.tasks.sendEmail",
+  dependencies: { emailService, logger },
+  run: async ({ to, subject, body }: EmailData, { emailService, logger }) => {
+    await logger.info(`Sending email to ${to}`);
+    return await emailService.send({ to, subject, body });
   },
 });
 
-const result = await run(app); // "Hello World!"
+// Test it like a normal function (because it basically is)
+const result = await sendEmail.run(
+  { to: "user@example.com", subject: "Hi", body: "Hello!" },
+  { emailService: mockEmailService, logger: mockLogger }
+);
 ```
 
-### When to use each?
+#### When to Task and When Not to Task
 
-It is unrealistic to create a task for everything you're doing in your system, not only it will be tedious for the developer, but it will affect performance unnecessarily. The idea is to think of a task of something that you want trackable as a higher-level action, for example:
+Look, we get it. You could turn every function into a task, but that's like using a sledgehammer to crack nuts. Here's the deal:
 
-- "app.user.register" - this is a task, registers the user, returns a token
-- "app.user.createComment" - this is a task, creates a comment, returns the comment maybe
-- "app.user.updateFriendList" - this task can be re-used from many other tasks or resources as necessary
+**Make it a task when:**
 
-Resources are more like services, they are singletons, they are meant to be used as a shared functionality across your application. They can be constants, services, functions, etc.
+- It's a high-level business action: `"app.user.register"`, `"app.order.process"`
+- You want it trackable and observable
+- Multiple parts of your app need it
+- It's complex enough to benefit from dependency injection
 
-### Resource dispose()
+**Don't make it a task when:**
 
-Resources can include a `dispose()` method for cleanup tasks. This is useful for actions like closing database connections. You should use `dispose()` when you have open connections or need to perform cleanup during a graceful shutdown.
+- It's a simple utility function
+- It's used in only one place or to help other tasks
+- It's performance-critical and doesn't need DI overhead
 
-```ts
-import { task, run, resource } from "@bluelibs/runner";
+Think of tasks as the "main characters" in your application story, not every single line of dialogue.
 
-const dbResource = resource({
-  async init(config, deps) {
-    const db = await connectToDatabase();
-    return db;
-  },
-  // the value returned from init() will be passed to dispose()
-  async dispose(db, config, deps) {
-    return db.close();
-  },
-});
-```
+### 2. Resources: Your Singletons That Don't Suck
 
-To call dispose(), you need to use the global resource called store, since everything is encapsulated. This allows you to access the internal parts of the system to start the disposal process.
+Resources are the services, configs, and connections that live throughout your app's lifecycle. They initialize once and stick around until cleanup time. They have to be registered (via `register: []`) only once before they can be used.
 
-```ts
-import { task, run, resource, globals } from "@bluelibs/runner";
+```typescript
+const database = resource({
+  id: "app.db",
+  init: async () => {
+    const client = new MongoClient(process.env.DATABASE_URL as string);
+    await client.connect();
 
-const app = resource({
-  id: "app",
-  register: [dbResource],
-  dependencies: {
-    store: globals.resources.store,
-  },
-  async init(_, deps) {
-    // We use the fact that we can reuse the value we got from here
-    return {
-      dispose: async () => deps.store.dispose(),
-    };
+    return client;
   },
+  dispose: async (client) => await client.close(),
 });
 
-const value = await run(app);
-// To begin the disposal process.
-await value.dispose();
+const userService = resource({
+  id: "app.services.user",
+  dependencies: { database },
+  init: async (_, { database }) => ({
+    async createUser(userData: UserData) {
+      return database.collection("users").insertOne(userData);
+    },
+    async getUser(id: string) {
+      return database.collection("users").findOne({ _id: id });
+    },
+  }),
+});
 ```
 
-### Resource configuration
-
-Resources can be set up with a configuration object, which is helpful for passing in specific settings. For example, if you’re building a library and initializing a mailer service, you can provide the SMTP credentials through this configuration.
+#### Resource Configuration: Because Hardcoding Is for Amateurs
 
-```ts
-import { task, run, resource } from "@bluelibs/runner";
+Resources can be configured with type-safe options. No more "config object of unknown shape" nonsense.
 
-type Config = { smtpUrl: string; defaultFrom: string };
+```typescript
+type SMTPConfig = {
+  smtpUrl: string;
+  from: string;
+};
 
-const emailerResource = resource({
-  // automatic type inference.
-  async init(config: Config) {
-    // todo: perform config checks with a library like zod
-    return {
-      sendEmail: async (to: string, subject: string, body: string) => {
-        // send *email*
-      },
-    };
-  },
+const emailer = resource({
+  id: "app.emailer",
+  init: async (config: SMTPConfig) => ({
+    send: async (to: string, subject: string, body: string) => {
+      // Use config.smtpUrl and config.from
+    },
+  }),
 });
 
+// Register with specific config
 const app = resource({
   id: "app",
   register: [
-    // proper autocompletion is present
-    emailerResource.with({ smtpUrl: "smtp://localhost", defaultFrom: "" }),
+    emailer.with({
+      smtpUrl: "smtp://localhost",
+      from: "noreply@myapp.com",
+    }),
+    // using emailer without with() will throw a type-error ;)
   ],
 });
 ```
 
-If by any chance your main `app` has configs then they will be passed via the second argument of `run`, like this:
+#### Shared Context Between Init and Dispose
 
-```ts
-run(app, config);
+For cases where you need to share variables between `init()` and `dispose()` methods (because sometimes cleanup is complicated), use the enhanced context pattern:
+
+```typescript
+const dbResource = resource({
+  id: "db.service",
+  context: () => ({
+    connections: new Map(),
+    pools: [],
+  }),
+  async init(config, deps, ctx) {
+    const db = await connectToDatabase();
+    ctx.connections.set("main", db);
+    ctx.pools.push(createPool(db));
+    return db;
+  },
+  async dispose(db, config, deps, ctx) {
+    // Same context available - no more "how do I access that thing I created?"
+    for (const pool of ctx.pools) {
+      await pool.drain();
+    }
+    for (const [name, conn] of ctx.connections) {
+      await conn.close();
+    }
+  },
+});
 ```
 
-## Dependencies
+### 3. Events: Async Communication That Actually Works
+
+Events let different parts of your app talk to each other without tight coupling. It's like having a really good office messenger who never forgets anything.
 
-You can depend on `tasks`, `resources`, `events` and (indirectly) on `middleware`.
+```typescript
+const userRegistered = event<{ userId: string; email: string }>({
+  id: "app.events.userRegistered",
+});
 
-```ts
-import { task, resource, run, event } from "@bluelibs/runner";
+const registerUser = task({
+  id: "app.tasks.registerUser",
+  dependencies: { userService, userRegistered },
+  run: async (userData, { userService, userRegistered }) => {
+    const user = await userService.createUser(userData);
 
-const helloWorld = task({
-  middleware: [logMiddleware],
-  dependencies: {
-    userRegisteredEvent,
-  },
-  async run(_, deps) {
-    await deps.userRegisteredEvent();
-    return "Hello World!";
+    // Tell the world about it
+    await userRegistered({ userId: user.id, email: user.email });
+    return user;
   },
 });
 
-const app = resource({
-  id: "app",
-  // You have to register everything you use.
-  register: [helloWorld, logMiddleware],
-  dependencies: {
-    helloWorld,
-  },
-  async init(_, deps) {
-    await deps.helloWorld();
+// Someone else handles the welcome email
+const sendWelcomeEmail = task({
+  id: "app.tasks.sendWelcomeEmail",
+  on: userRegistered, // Listen to the event, notice the "on"
+  run: async (eventData) => {
+    // Everything is type-safe, automatically inferred from the 'on' property
+    console.log(`Welcome email sent to ${eventData.data.email}`);
   },
 });
-
-run(app);
 ```
 
-We have a circular dependency checker to ensure consistency. If a circular dependency is found, an error will be thrown, showing the exact paths involved.
-
-Tasks, however, are not bound by this restriction; they can freely depend on each other as needed.
-
-The dependencies get injected as follows:
-
-| Component    | Injection Description                                     |
-| ------------ | --------------------------------------------------------- |
-| `tasks`      | Injected as functions with their input argument           |
-| `resources`  | Injected as their return value                            |
-| `events`     | Injected as functions with their payload argument         |
-| `middleware` | Not typically injected; used via a `middleware: []` array |
+#### Wildcard Events: For When You Want to Know Everything
 
-### Circular dependencies
+Sometimes you need to be the nosy neighbor of your application:
 
-There are situations in which you can, with a resource ("A"), register a resource or task ("B"), which in turn depends on resource ("A"). The system permits this, because "A" does not depend on "B" for initialization. But TypeScript will break due to infinite type recursion guessing. Instead of manually specifying the types, just defer registration into a separate statement.
-
-```ts
-import { task, run, resource } from "@bluelibs/runner";
-
-const resourceB = defineResource({
-  id: "task",
-  init: async (_, deps) => {
-    deps.resource;
-    return "";
+```typescript
+const logAllEventsTask = task({
+  id: "app.tasks.logAllEvents",
+  on: "*", // Listen to EVERYTHING
+  run(event) {
+    console.log("Event detected", event.id, event.data);
+    // Note: Be careful with dependencies here since some events fire before initialization
   },
-  dependencies: () => ({
-    resource,
-  }),
 });
+```
 
-const resourceA = defineResource({
-  id: "resource",
-});
+#### Tasks and Resources built-in events
 
-// Important: store, the registration separately, otherwise TypeScript will break
-resourceA.register = [resourceB];
+Tasks and resources have their own lifecycle events that you can hook into:
+
+```typescript
+const myTask = task({ ... });
+const myResource = resource({ ... });
 ```
 
-## Events
+- `myTask.events.beforeRun` - Fires before the task runs
+- `myTask.events.afterRun` - Fires after the task completes
+- `myTask.events.onError` - Fires when the task fails
+- `myResource.events.beforeInit` - Fires before the resource initializes
+- `myResource.events.afterInit` - Fires after the resource initializes
+- `myResource.events.onError` - Fires when the resource initialization fails
 
-Events are triggered when specific actions occur in your app, like a user registration or a new comment. When you catch these events, you also receive the emitted data along with the source of the event. Knowing the source of the event without explicitly specifying it can be very helpful in large applications.
+Each event has its own utilities and functions.
 
-You can listen for these events using tasks and resources, and similarly, emit them from tasks and resources through dependencies.
+#### Global Events: The System's Built-in Gossip Network
 
-```ts
-import { task, run, event } from "@bluelibs/runner";
+The framework comes with its own set of events that fire during the lifecycle. Think of them as the system's way of keeping you informed:
 
-const afterRegisterEvent = event<{ userId: string }>({
-  id: "app.user.afterRegister",
-});
+- `globals.tasks.beforeRun` - "Hey, I'm about to run this task"
+- `globals.tasks.afterRun` - "Task completed, here's what happened"
+- `globals.tasks.onError` - "Oops, something went wrong"
+- `globals.resources.beforeInit` - "Initializing a resource"
+- `globals.resources.afterInit` - "Resource is ready"
+- `globals.resources.onError` - "Resource initialization failed"
 
-const root = resource({
-  id: "app",
-  register: [afterRegisterEvent],
-  dependencies: {
-    afterRegisterEvent,
-  },
-  async init(_, deps) {
-    // the event becomes a function that you run with the propper payload
-    await deps.afterRegisterEvent({ userId: string });
+```typescript
+const taskLogger = task({
+  id: "app.logging.taskLogger",
+  on: globalEvents.tasks.beforeRun,
+  run(event) {
+    console.log(`Running task: ${event.source} with input:`, event.data.input);
   },
 });
 ```
 
-To listen to events you have to create a task.
-
-### `task.on` property
-
-```ts
-import { task, run, event } from "@bluelibs/runner";
+### 4. Middleware: The Interceptor Pattern Done Right
 
-const afterRegisterEvent = event<{ userId: string }>({
-  id: "app.user.afterRegister",
-});
+Middleware wraps around your tasks and resources, adding cross-cutting concerns without polluting your business logic.
 
-const helloTask = task({
-  id: "app.hello",
-  on: afterRegisterEvent,
-  listenerPriority: 0, // this is the order in which the task will be executed when `on` is present
-  run(event) {
-    event.source; // id which middleware, task, resource triggered it
-    console.log("User has been registered!");
+```typescript
+// This is a middleware that accepts a config
+const authMiddleware = middleware({
+  id: "app.middleware.auth",
+  // You can also add dependencies, no problem.
+  run: async (
+    { task, next },
+    dependencies,
+    config: { requiredRole: string }
+  ) => {
+    const user = task.input.user;
+    if (!user || user.role !== config.requiredRole) {
+      throw new Error("Unauthorized");
+    }
+    return next(task.input);
   },
 });
 
-const app = resource({
-  id: "app",
-  register: [afterRegisterEvent, helloTask],
-  dependencies: {
-    afterRegisterEvent,
-  },
-  async init(_, deps) {
-    await deps.afterRegisterEvent({ userId: "XXX" });
+const adminTask = task({
+  id: "app.tasks.adminOnly",
+  // If the configuration accepts {} or is empty, .with() becomes optional, otherwise it becomes enforced.
+  middleware: [authMiddleware.with({ requiredRole: "admin" })],
+  run: async (input: { user: User }) => {
+    return "Secret admin data";
   },
 });
 ```
 
-### wildcard events
+#### Global Middleware: Apply Everywhere, Configure Once
 
-You can listen to all events by using the wildcard `*`. However you need to **manually check** if your dependencies have been computed. For example we dispatch events like 'global.beforeInit' before anything is initialized.
+Want to add logging to everything? Authentication to all tasks? Global middleware has your back:
 
-```ts
-import { task, resource, run, event, global } from "@bluelibs/runner";
-
-const afterRegisterEvent = event<{ userId: string }>({
-  id: "app.user.registered",
-});
-
-const logAllEventsTask = task({
-  id: "app.tasks.logAllEvents",
-  on: "*",
-  run(event) {
-    console.log("Event detected", event.id, event.data);
+```typescript
+const logMiddleware = middleware({
+  id: "app.middleware.log",
+  run: async ({ task, next }) => {
+    console.log(`Executing: ${task.definition.id}`);
+    const result = await next(task.input);
+    console.log(`Completed: ${task.definition.id}`);
+    return result;
   },
 });
 
-const root = resource({
+const app = resource({
   id: "app",
-  register: [afterRegisterEvent, logAllEventsTask],
-  dependencies: {},
-  async init(_, deps) {
-    deps.afterRegisterEvent({ userId: "XXX" });
-  },
+  register: [
+    logMiddleware.everywhere({ tasks: true, resources: false }), // Only tasks get logged
+  ],
 });
 ```
 
-## Middleware
-
-Middleware intercepts the execution of tasks or the initialization of resources, providing a powerful means to enhance functionality. The order in which middleware is registered dictates its execution priority: the first middleware registered is the first to run, while the last middleware in the middleware array at the task level is the closest to the task itself, executing just before the task completes. (Imagine an onion if you will, with the task at the core.)
+## Context: Request-Scoped Data That Doesn't Drive You Insane
 
-```ts
-import { task, resource, run, event } from "@bluelibs/runner";
+Ever tried to pass user data through 15 function calls? Yeah, we've been there. Context fixes that without turning your code into a game of telephone.
 
-const logMiddleware = middleware({
-  id: "app.middleware.log",
-  dependencies: {
-    // inject tasks, resources, eventCallers here.
-  },
-  async run(data, deps) {
-    const { taskDefinition, resourceDefinition, config, next, input } = data;
-
-    // The middleware can be for a task or a resource, depending on which you get the right elements.
-    if (taskDefinition) {
-      console.log("Before task", taskDefinition.id);
-      const result = await next(input); // pass the input to the next middleware or task
-      console.log("After task", taskDefinition.id);
-    } else {
-      console.log("Before resource", resourceDefinition.id);
-      const result = await next(config); // pass the input to the next middleware or task
-      console.log("After resource", resourceDefinition.id);
-    }
+```typescript
+const UserContext = createContext<{ userId: string; role: string }>(
+  "app.userContext"
+);
 
-    return result;
+const getUserData = task({
+  id: "app.tasks.getUserData",
+  middleware: [UserContext.require()], // This is a middleware that ensures the context is available before task runs, throws if not.
+  run: async () => {
+    const user = UserContext.use(); // Available anywhere in the async chain
+    return `Current user: ${user.userId} (${user.role})`;
   },
 });
 
-const helloTask = task({
-  id: "app.hello",
-  middleware: [logMiddleware],
-  run(event) {
-    console.log("User has been registered!");
+// Provide context at the entry point
+const handleRequest = resource({
+  id: "app.requestHandler",
+  init: async () => {
+    return UserContext.provide({ userId: "123", role: "admin" }, async () => {
+      // All tasks called within this scope have access to UserContext
+      return await getUserData();
+    });
   },
 });
 ```
 
-### Global
-
-If you want to register a middleware for all tasks and resources, here's how you can do it:
+### Context with Middleware: The Power Couple
 
-```ts
-import { run, resource } from "@bluelibs/runner";
+Context shines when combined with middleware for request-scoped data:
 
-const logMiddleware = middleware({
-  id: "app.middleware.log",
-  // ... rest
+```typescript
+const RequestContext = createContext<{
+  requestId: string;
+  startTime: number;
+  userAgent?: string;
+}>("app.requestContext");
+
+const requestMiddleware = middleware({
+  id: "app.middleware.request",
+  run: async ({ task, next }) => {
+    // This works even in express middleware if needed.
+    return RequestContext.provide(
+      {
+        requestId: crypto.randomUUID(),
+        startTime: Date.now(),
+        userAgent: "MyApp/1.0",
+      },
+      async () => {
+        return next(task.input);
+      }
+    );
+  },
 });
 
-const root = resource({
-  id: "app",
-  register: [logMiddleware.global() /* this will apply to all tasks */],
+const handleRequest = task({
+  id: "app.handleRequest",
+  middleware: [requestMiddleware],
+  run: async (input: { path: string }) => {
+    const request = RequestContext.use();
+    console.log(`Processing ${input.path} (Request ID: ${request.requestId})`);
+    return { success: true, requestId: request.requestId };
+  },
 });
 ```
 
-The middleware can only be registered once. This means that if you register a middleware as global, you cannot specify it as a task middleware. This is to avoid confusion and to keep the system clean.
+## Dependency Management: The Index Pattern
 
-## Errors
+When your app grows beyond "hello world", you'll want to group related dependencies. The `index()` helper is your friend - it's basically a 3-in-1 resource that registers, depends on, and returns everything you give it.
 
-If an error is thrown in a task, the error will be propagated up to the top runner.
-
-```ts
-import { task, run, event } from "@bluelibs/runner";
-
-const helloWorld = task({
-  id: "app.helloWorld",
-  run() {
-    throw new Error("Something went wrong");
-  },
+```typescript
+// This registers all services, depends on them, and returns them as one clean interface
+const services = index({
+  userService,
+  emailService,
+  paymentService,
+  notificationService,
 });
 
 const app = resource({
   id: "app",
-  register: [helloWorld],
-  dependencies: {
-    helloWorld,
+  register: [services],
+  dependencies: { services },
+  init: async (_, { services }) => {
+    // Access everything through one clean interface
+    const user = await services.userService.createUser(userData);
+    await services.emailService.sendWelcome(user.email);
   },
-  async init() {
-    await helloWorld();
-  },
-});
-
-run(app).catch((err) => {
-  console.error(err);
 });
 ```
 
-You can listen to errors via events:
+## Error Handling: Graceful Failures
 
-```ts
-const helloWorld = task({
-  id: "app.tasks.helloWorld.onError",
-  on: helloWorld.events.onError,
-  run({ error, input, suppress }, deps) {
-    // this will be called when an error happens
+Errors happen. When they do, you can listen for them and decide what to do. No more unhandled promise rejections ruining your day.
 
-    // if you handled the error, and you don't want it propagated to the top, supress the propagation.
-    suppress();
+```typescript
+const riskyTask = task({
+  id: "app.tasks.risky",
+  run: async () => {
+    throw new Error("Something went wrong");
   },
+  // Behind the scenes when you create a task() we create these 3 events for you (onError, beforeRun, afterRun)
 });
-```
 
-```ts
-const helloWorld = resource({
-  id: "app.resources.helloWorld.onError",
-  on: helloWorld.events.onError,
-  init({ error, input, suppress }, deps) {
-    // this will be called when an error happens
+const errorHandler = task({
+  id: "app.tasks.errorHandler",
+  on: riskyTask.events.onError,
+  run: async (event) => {
+    console.error("Task failed:", event.data.error);
 
-    // if you handled the error, and you don't want it propagated to the top, supress the propagation.
-    suppress();
+    // Don't let the error bubble up - this makes the task return undefined
+    event.data.suppress();
   },
 });
 ```
 
-## Meta
-
-You can attach metadata to tasks, resources, events, and middleware.
+## Caching: Built-in Performance
 
-```ts
-import { task, run, event } from "@bluelibs/runner";
+Because nobody likes waiting for the same expensive operation twice:
 
-const helloWorld = task({
-  id: "app.helloWorld",
-  meta: {
-    title: "Hello World",
-    description: "This is a hello world task",
-    tags: ["api"],
-  },
-  run() {
-    return "Hello World!";
+```typescript
+import { globals } from "@bluelibs/runner";
+
+const expensiveTask = task({
+  id: "app.tasks.expensive",
+  middleware: [
+    globals.middleware.cache.with({
+      // lru-cache options by default
+      ttl: 60 * 1000, // Cache for 1 minute
+      keyBuilder: (taskId, input) => `${taskId}-${input.userId}`, // optional key builder
+    }),
+  ],
+  run: async ({ userId }) => {
+    // This expensive operation will be cached
+    return await doExpensiveCalculation(userId);
   },
 });
+
+// Global cache configuration
+const app = resource({
+  id: "app.cache",
+  register: [
+    // You have to register it, cache resource is not enabled by default.
+    globals.resources.cache.with({
+      defaultOptions: {
+        max: 1000, // Maximum items in cache
+        ttl: 30 * 1000, // Default TTL
+      },
+      async: false, // in-memory is sync by default
+      // When using redis or others mark this as true to await response.
+    }),
+  ],
+});
 ```
 
-This is particularly helpful to use in conjunction with global middlewares, or global events, they can read some meta tag definition and act accordingly, decorate them or log them.
+Want Redis instead of the default LRU cache? No problem, just override the cache factory task:
 
-The interfaces look like this:
+```typescript
+import { task } from "@bluelibs/runner";
 
-```ts
-export interface IMeta {
-  title?: string;
-  description?: string;
-  tags: string[];
-}
+const redisCacheFactory = task({
+  id: "globals.tasks.cacheFactory", // Same ID as the default task
+  run: async (options: any) => {
+    return new RedisCache(options); // Make sure to turn async on in the cacher.
+  },
+});
 
-export interface ITaskMeta extends IMeta {}
-export interface IResourceMeta extends IMeta {}
-export interface IEventMeta extends IMeta {}
-export interface IMiddlewareMeta extends IMeta {}
+const app = resource({
+  id: "app",
+  register: [
+    // Your other stuff
+  ],
+  overrides: [redisCacheFactory], // Override the default cache factory
+});
 ```
 
-Which means you can extend them in your system to add more keys to better describe your actions.
-
-## Internal Services
+## Logging: Because Console.log Isn't Professional
 
-We expose direct access to the following internal services:
+_The structured logging system that actually makes debugging enjoyable_
 
-- Store (contains Map()s for events, tasks, resources, middleware configurations)
-- TaskRunner (can run tasks definitions directly and within D.I. context)
-- EventManager (can emit and listen to events)
+BlueLibs Runner comes with a built-in logging system that's event-driven, structured, and doesn't make you hate your life when you're trying to debug at 2 AM. It emits events for everything, so you can handle logs however you want - ship them to your favorite log warehouse, pretty-print them to console, or ignore them entirely (we won't judge).
 
-Attention, we do not encourage you to use these services directly, unless you really have to, they are exposed for advanced use-case scenarios.
+### Quick Start: Basic Logging
 
-```ts
-import { task, run, event, globals } from "@bluelibs/runner";
+```typescript
+import { globals } from "@bluelibs/runner";
 
-const helloWorld = task({
-  id: "app.helloWorld",
-  dependencies: {
-    store: globals.resources.store,
-    taskRunner: globals.resources.taskRunner,
-    eventManager: globals.resources.eventManager,
-  }
-  run(_, deps) {
-    // you benefit of full autocompletion here
+const businessTask = task({
+  id: "app.tasks.business",
+  dependencies: { logger: globals.resources.logger },
+  run: async (_, { logger }) => {
+    logger.info("Starting business process");
+    logger.warn("This might take a while");
+    logger.error("Oops, something went wrong", {
+      error: new Error("Database connection failed"),
+    });
+    logger.critical("System is on fire", {
+      data: { temperature: "9000°C" },
+    });
   },
 });
 ```
 
-## Namespacing
-
-Domain usually is "app", but as your application grows or you plan on building external libraries the naming convention should be: "companyName.packageName".
+### Log Levels: From Whispers to Screams
 
-| Type           | Format                                    |
-| -------------- | ----------------------------------------- |
-| Tasks          | `{domain}.tasks.{taskName}`               |
-| Listener Tasks | `{domain}.tasks.{taskName}.on{EventName}` |
-| Resources      | `{domain}.resources.{resourceName}`       |
-| Events         | `{domain}.events.{eventName}`             |
-| Middleware     | `{domain}.middleware.{middlewareName}`    |
+The logger supports six log levels with increasing severity:
 
-You can always create helpers for you as you're creating your tasks, resources, middleware:
+| Level      | Severity | When to Use                                 | Color   |
+| ---------- | -------- | ------------------------------------------- | ------- |
+| `trace`    | 0        | Ultra-detailed debugging info               | Gray    |
+| `debug`    | 1        | Development and debugging information       | Cyan    |
+| `info`     | 2        | General information about normal operations | Green   |
+| `warn`     | 3        | Something's not right, but still working    | Yellow  |
+| `error`    | 4        | Errors that need attention                  | Red     |
+| `critical` | 5        | System-threatening issues                   | Magenta |
 
-```ts
-function namespaced(id) {
-  return `bluelibs.core.${id}`;
-}
+```typescript
+// All log levels are available as methods
+logger.trace("Ultra-detailed debugging info");
+logger.debug("Development debugging");
+logger.info("Normal operation");
+logger.warn("Something's fishy");
+logger.error("Houston, we have a problem");
+logger.critical("DEFCON 1: Everything is broken");
 ```
 
-We need to import all the tasks, resources, events, and middlewares, a convention for their naming is to export them like this
-
-```ts
-import { userCreatedEvent } from "./events";
-export const events = {
-  userCreated: userCreatedEvent,
-  // ...
-};
-
-export const tasks = {
-  doSomething: doSomethingTask,
-};
-
-export const resources = {
-  root: rootResource,
-  user: userResource,
-};
-```
+### Structured Logging: More Than Just Strings
 
-Often the root will register all needed items, so you don't have to register anything but the root.
+The logger accepts rich, structured data that makes debugging actually useful:
 
-```ts
-import { resource } from "@bluelibs/runner";
-import * as packageName from "package-name";
+```typescript
+const userTask = task({
+  id: "app.tasks.user.create",
+  dependencies: { logger: globals.resources.logger },
+  run: async (userData, { logger }) => {
+    // Basic message
+    logger.info("Creating new user");
+
+    // With structured data
+    logger.info("User creation attempt", {
+      data: {
+        email: userData.email,
+        registrationSource: "web",
+        timestamp: new Date().toISOString(),
+      },
+    });
 
-const app = resource({
-  id: "app",
-  register: [packageName.resources.root],
+    // With error information
+    try {
+      const user = await createUser(userData);
+      logger.info("User created successfully", {
+        data: { userId: user.id, email: user.email },
+      });
+    } catch (error) {
+      logger.error("User creation failed", {
+        error,
+        data: {
+          attemptedEmail: userData.email,
+          validationErrors: error.validationErrors,
+        },
+      });
+    }
+  },
 });
-
-run(app);
 ```
 
-Now you can freely use any of the tasks, resources, events, and middlewares from the `packageName` namespace.
-
-This approach is very powerful when you have multiple packages and you want to compose them together.
-
-## Real life
-
-Or is it just fantasy?
+### Context-Aware Logging: The with() Method
 
-Typically, an application consists of an Express server (to handle HTTP requests), a database, and various services. You can conveniently define all of these components within a single file and execute them together.
+Create logger instances with bound context for consistent metadata across related operations:
 
-```ts
-import { task, resource, run, event } from "@bluelibs/runner";
-import express from "express";
+```typescript
+const RequestContext = createContext<{ requestId: string; userId: string }>(
+  "app.requestContext"
+);
+
+const requestHandler = task({
+  id: "app.tasks.handleRequest",
+  dependencies: { logger: globals.resources.logger },
+  run: async (requestData, { logger }) => {
+    const request = RequestContext.use();
+
+    // Create a contextual logger with bound metadata
+    const requestLogger = logger.with({
+      requestId: request.requestId,
+      userId: request.userId,
+      source: "api.handler",
+    });
 
-const expressServer = resource({
-  id: "app.express",
-  async init() {
-    const app = express();
-    app.listen(3000).then(() => {
-      console.log("Server is running on port 3000");
+    // All logs from this logger will include the bound context
+    requestLogger.info("Processing request", {
+      data: { endpoint: requestData.path },
     });
 
-    // because we return it you can now access it via dependencies
-    return app;
-  },
-});
+    requestLogger.debug("Validating input", {
+      data: { inputSize: JSON.stringify(requestData).length },
+    });
 
-const setupRoutes = resource({
-  id: "app.routes",
-  dependencies: {
-    expressServer,
-  },
-  async init(_, deps) {
-    deps.expressServer.use("/api", (req, res) => {
-      res.json({ hello: "world" });
+    // Context is automatically included in all log events
+    requestLogger.error("Request processing failed", {
+      error: new Error("Invalid input"),
+      data: { stage: "validation" },
     });
   },
 });
-
-// Just run them, init() will be called everywhere.
-const app = resource({
-  id: "app",
-  register: [expressServer, setupRoutes],
-});
-
-run();
 ```
 
-The system intelligently determines the order in which init() functions should be called, ensuring that all dependencies are initialized first. In the case of circular dependencies, it will throw an error, providing the exact paths to help identify the issue.
+### Print Threshold: Control What Shows Up
 
-### Business config
+By default, logs are just events - they don't print to console unless you tell them to. Set a print threshold to automatically output logs at or above a certain level:
 
-Or just simple config, you can do it for your business logic, environment variables, etc.
-
-```ts
-import { resource, run } from "@bluelibs/runner";
+```typescript
+// Set up log printing (they don't print by default)
+const setupLogging = task({
+  id: "app.logging.setup",
+  on: globals.resources.logger.events.afterInit,
+  run: async (event) => {
+    const logger = event.data.value;
 
-// we keep it as const because we will also benefit of type-safety
-const businessData = {
-  pricePerSubscription: 9.99,
-};
+    // Print info level and above (info, warn, error, critical)
+    logger.setPrintThreshold("info");
 
-const businessConfig = resource({
-  id: "app.config",
-  async init() {
-    return businessData;
-  },
-});
+    // Print only errors and critical issues
+    logger.setPrintThreshold("error");
 
-const app = resource({
-  id: "app",
-  register: [businessConfig],
-  dependencies: { businessConfig },
-  async init(_, deps) {
-    console.log(deps.businessConfig.pricePerSubscription);
+    // Disable auto-printing entirely
+    logger.setPrintThreshold(null);
   },
 });
-
-run();
 ```
 
-## Global Events
+### Event-Driven Log Handling: Ship Logs Anywhere
 
-You can listen to all events by using the wildcard `*`. However, keep in mind that to avoid infinite recursion, all the events coming from the same source will be ignored.
+Every log generates an event that you can listen to. This is where the real power comes in:
 
-At the same time, if a task is listening to all events such as `beforeRun`, since it's a task, triggering `beforeRun` will lead to infinite recursion, this is why we ignore emitting the same event from the same source.
+```typescript
+// Ship logs to your favorite log warehouse
+const logShipper = task({
+  id: "app.logging.shipper", // or pretty printer, or winston, pino bridge, etc.
+  on: globals.events.log,
+  run: async (event) => {
+    const log = event.data;
+
+    // Ship critical errors to PagerDuty
+    if (log.level === "critical") {
+      await pagerDuty.alert({
+        message: log.message,
+        details: log.data,
+        source: log.source,
+      });
+    }
+
+    // Ship all errors to error tracking
+    if (log.level === "error" || log.level === "critical") {
+      await sentry.captureException(log.error || new Error(log.message), {
+        tags: { source: log.source },
+        extra: log.data,
+        level: log.level,
+      });
+    }
 
-This guide outlines the key global events that can be used throughout your application to hook into resource and task lifecycle moments. These events help monitor initialization, execution, and errors, making your system more resilient and traceable.
+    // Ship everything to your log warehouse
+    await logWarehouse.ship({
+      timestamp: log.timestamp,
+      level: log.level,
+      message: log.message,
+      source: log.source,
+      data: log.data,
+      context: log.context,
+    });
+  },
+});
 
-### Overview
+// Filter logs by source
+const databaseLogHandler = task({
+  id: "app.logging.database",
+  on: globals.events.log,
+  run: async (event) => {
+    const log = event.data;
 
-Global events are categorized into:
+    // Only handle database-related logs
+    if (log.source?.includes("database")) {
+      await databaseMonitoring.recordMetric({
+        operation: log.data?.operation,
+        duration: log.data?.duration,
+        level: log.level,
+      });
+    }
+  },
+});
+```
 
-- **Initialization events**: Before and after a resource or task is initialized.
-- **Execution events**: Before and after a task runs.
-- **Error events**: Handling errors for both tasks and resources.
+### Integration with Winston: Best of Both Worlds
 
-### Events in Tasks
+Want to use Winston as your transport? No problem - integrate it seamlessly:
 
-#### `global.tasks.beforeRun`
+```typescript
+import winston from "winston";
+
+// Create Winston logger, put it in a resource if used from various places.
+const winstonLogger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.File({ filename: "error.log", level: "error" }),
+    new winston.transports.File({ filename: "combined.log" }),
+    new winston.transports.Console({
+      format: winston.format.simple(),
+    }),
+  ],
+});
 
-This event is triggered just before a task is executed. It allows you to inspect or modify the input to the task.
+// Bridge BlueLibs logs to Winston
+const winstonBridge = task({
+  id: "app.logging.winston",
+  on: globals.events.log,
+  run: async (event) => {
+    const log = event.data;
+
+    // Convert BlueLibs log to Winston format
+    const winstonMeta = {
+      source: log.source,
+      timestamp: log.timestamp,
+      data: log.data,
+      context: log.context,
+      ...(log.error && { error: log.error }),
+    };
 
-##### Example:
+    // Map log levels (BlueLibs -> Winston)
+    const levelMapping = {
+      trace: "silly",
+      debug: "debug",
+      info: "info",
+      warn: "warn",
+      error: "error",
+      critical: "error", // Winston doesn't have critical, use error
+    };
 
-```ts
-task({
-  id: "logBeforeRun",
-  on: globalEvents.tasks.beforeRun, // Listening to the beforeRun event
-  run(event) {
-    console.log("Task is about to run with input:", event.data.input);
+    const winstonLevel = levelMapping[log.level] || "info";
+    winstonLogger.log(winstonLevel, log.message, winstonMeta);
   },
 });
 ```
 
-**Use Case**: You can use this event to log input data or modify it before the task execution.
-
-#### `global.tasks.afterRun`
-
-This event fires immediately after a task finishes. It provides access to both the task input and the result (output).
+### Advanced: Custom Log Formatters
 
-##### Example:
+Want to customize how logs are printed? You can override the print behavior:
 
-```ts
-task({
-  id: "logAfterRun",
-  on: globalEvents.tasks.afterRun, // Listening to the afterRun event
-  run(event) {
+```typescript
+// Custom logger with JSON output
+class JSONLogger extends Logger {
+  print(log: ILog) {
     console.log(
-      "Task completed. Input:",
-      event.data.input,
-      "Output:",
-      event.data.output
+      JSON.stringify(
+        {
+          timestamp: log.timestamp.toISOString(),
+          level: log.level.toUpperCase(),
+          source: log.source,
+          message: log.message,
+          data: log.data,
+          context: log.context,
+          error: log.error,
+        },
+        null,
+        2
+      )
     );
+  }
+}
+
+// Custom logger resource
+const customLogger = resource({
+  id: "app.logger.custom",
+  dependencies: { eventManager: globals.resources.eventManager },
+  init: async (_, { eventManager }) => {
+    return new JSONLogger(eventManager);
   },
 });
-```
 
-**Use Case**: Useful for logging or post-processing based on the task's output.
-
-#### `global.tasks.onError`
+// Or you could simply add it as "globals.resources.logger" and override the default logger
+```
 
-If an error occurs during the execution of a task, this event is triggered. You can log or suppress the error.
+### Log Structure: What You Get
 
-##### Example:
+Every log event contains:
 
-```ts
-task({
-  id: "handleTaskError",
-  on: globalEvents.tasks.onError, // Listening to the onError event
-  run(event) {
-    console.error("Error occurred:", event.data.error);
-    event.data.suppress(); // Optionally suppress the error to prevent propagation
-  },
-});
+```typescript
+interface ILog {
+  level: string; // The log level (trace, debug, info, etc.)
+  source?: string; // Where the log came from
+  message: any; // The main log message (can be object or string)
+  timestamp: Date; // When the log was created
+  error?: {
+    // Structured error information
+    name: string;
+    message: string;
+    stack?: string;
+  };
+  data?: Record<string, any>; // Additional structured data, it's about the log itself
+  context?: Record<string, any>; // Bound context from logger.with(), it's about the context in which the log was created
+}
 ```
 
-**Use Case**: Error handling logic for specific tasks. For example, you may want to send alerts when a task fails.
+### Debugging Tips & Best Practices
 
-### Events in Resources
+#### 1. Use Structured Data Liberally
 
-#### `global.resources.beforeInit`
-
-This event is triggered before a resource starts its initialization. It allows inspection or modification of the configuration before the resource is fully initialized.
-
-##### Example:
+```typescript
+// Bad - hard to search and filter
+await logger.error(`Failed to process user ${userId} order ${orderId}`);
 
-```ts
-task({
-  id: "logBeforeResourceInit",
-  on: globalEvents.resources.beforeInit, // Listening to beforeInit event for resources
-  run(event) {
-    console.log("Initializing resource with config:", event.data.config);
+// Good - searchable and filterable
+await logger.error("Order processing failed", {
+  data: {
+    userId,
+    orderId,
+    step: "payment",
+    paymentMethod: "credit_card",
   },
 });
 ```
 
-**Use Case**: Logging or validating the resource's configuration before initialization.
+#### 2. Include Context in Errors
 
-#### `global.resources.afterInit`
-
-This event fires after a resource is initialized, giving access to the initialization result.
+```typescript
+// Include relevant context with errors
+try {
+  await processPayment(order);
+} catch (error) {
+  await logger.error("Payment processing failed", {
+    error,
+    data: {
+      orderId: order.id,
+      amount: order.total,
+      currency: order.currency,
+      paymentMethod: order.paymentMethod,
+      attemptNumber: order.paymentAttempts,
+    },
+  });
+}
+```
 
-##### Example:
+#### 3. Use Different Log Levels Appropriately
 
-```ts
-task({
-  id: "logAfterResourceInit",
-  on: globalEvents.resources.afterInit, // Listening to afterInit event
-  run(event) {
-    console.log("Resource initialized with value:", event.data.value);
-  },
+```typescript
+// Good level usage
+await logger.debug("Cache hit", { data: { key, ttl: remainingTTL } });
+await logger.info("User logged in", { data: { userId, loginMethod } });
+await logger.warn("Rate limit approaching", {
+  data: { current: 95, limit: 100 },
+});
+await logger.error("Database connection failed", {
+  error,
+  data: { attempt: 3 },
 });
+await logger.critical("System out of memory", { data: { available: "0MB" } });
 ```
 
-**Use Case**: Post-processing or logging resource initialization details.
+#### 4. Create Domain-Specific Loggers
 
-#### `global.resources.onError`
+```typescript
+// Create loggers with domain context
+const paymentLogger = logger.with({ source: "payment.processor" });
+const authLogger = logger.with({ source: "auth.service" });
+const emailLogger = logger.with({ source: "email.service" });
+
+// Use throughout your domain
+await paymentLogger.info("Processing payment", { data: paymentData });
+await authLogger.warn("Failed login attempt", { data: { email, ip } });
+```
 
-If an error occurs during resource initialization, this event is triggered. You can log or handle the error.
+### Common Pitfalls
 
-##### Example:
+1. **Logging sensitive data**: Never log passwords, tokens, or PII
+2. **Over-logging in hot paths**: Check print thresholds for expensive operations
+3. **Forgetting error objects**: Always include the original error when logging failures
+4. **Poor log levels**: Don't use `error` for expected conditions
+5. **Missing context**: Include relevant identifiers (user ID, request ID, etc.)
 
-```ts
-task({
-  id: "handleResourceError",
-  on: globalEvents.resources.onError, // Listening to resource onError event
-  run(event) {
-    console.error("Resource initialization error:", event.data.error);
-    event.data.suppress(); // Optionally suppress the error to prevent propagation
+The Logger system is designed to be fast, flexible, and non-intrusive. Use it liberally - good logging is the difference between debugging hell and debugging heaven.
+
+## Meta: Tagging Your Components
+
+Sometimes you want to attach metadata to your tasks and resources for documentation, filtering, or middleware logic:
+
+```typescript
+const apiTask = task({
+  id: "app.tasks.api.createUser",
+  meta: {
+    title: "Create User API",
+    description: "Creates a new user account",
+    tags: ["api", "user", "public"],
+  },
+  run: async (userData) => {
+    // Business logic
+  },
+});
+
+// Middleware that only applies to API tasks
+const apiMiddleware = middleware({
+  id: "app.middleware.api",
+  run: async ({ task, next }) => {
+    if (task.meta?.tags?.includes("api")) {
+      // Apply API-specific logic
+    }
+    return next(task.input);
   },
 });
 ```
 
-**Use Case**: Error handling for critical resources, allowing for fallback mechanisms or error logging.
+## Advanced Usage: When You Need More Power
 
-#### Common Usage Pattern
+### Overrides: Swapping Components at Runtime
 
-To make use of these events, you will typically define tasks that respond to these global events. These tasks can then be registered in your main application resource to handle events for resources and tasks alike.
+Sometimes you need to replace a component entirely. Maybe you're testing, maybe you're A/B testing, maybe you just changed your mind:
 
-#### Example of registering event-handling tasks:
+```typescript
+const productionEmailer = resource({
+  id: "app.emailer",
+  init: async () => new SMTPEmailer(),
+});
+
+const testEmailer = resource({
+  ...productionEmailer, // Copy everything else
+  init: async () => new MockEmailer(), // But use a different implementation
+});
 
-```ts
 const app = resource({
   id: "app",
-  register: [
-    logBeforeRun,
-    logAfterRun,
-    handleTaskError,
-    logBeforeResourceInit,
-    logAfterResourceInit,
-    handleResourceError,
-  ],
+  register: [productionEmailer],
+  overrides: [testEmailer], // This replaces the production version
 });
-
-run(app);
 ```
 
-This structure helps you create a centralized and modular approach to manage events and handle tasks and resource lifecycles in your system.
-
-### Available Global Events
+### Namespacing: Keeping Things Organized
 
-Here’s a summary of all the global events you can listen to:
+As your app grows, you'll want consistent naming. Here's the convention that won't drive you crazy:
 
-- `global.beforeInit`: Triggered before any resource is initialized.
-- `global.afterInit`: Triggered after any resource is initialized.
-- `global.log`: Used for logging across the system.
-- **Task-specific events**:
-  - `global.tasks.beforeRun`: Fired before a task begins execution.
-  - `global.tasks.afterRun`: Fired after a task completes.
-  - `global.tasks.onError`: Fired if a task encounters an error.
-- **Resource-specific events**:
-  - `global.resources.beforeInit`: Fired before a resource is initialized.
-  - `global.resources.afterInit`: Fired after a resource is initialized.
-  - `global.resources.onError`: Fired if an error occurs during resource initialization.
+| Type           | Format                                    |
+| -------------- | ----------------------------------------- |
+| Tasks          | `{domain}.tasks.{taskName}`               |
+| Listener Tasks | `{domain}.tasks.{taskName}.on{EventName}` |
+| Resources      | `{domain}.resources.{resourceName}`       |
+| Events         | `{domain}.events.{eventName}`             |
+| Middleware     | `{domain}.middleware.{middlewareName}`    |
 
-This modular event system helps in building more reactive and error-tolerant applications.
+```typescript
+// Helper function for consistency
+function namespaced(id: string) {
+  return `mycompany.myapp.${id}`;
+}
 
-### Individual Task level
+const userTask = task({
+  id: namespaced("tasks.user.create"),
+  // ...
+});
+```
 
-When creating tasks or resources we also create lifecycle events for them stored in `events` property.
+### Factory Pattern: For When You Need Instances
 
-```ts
-import { task, run, event } from "@bluelibs/runner";
+To keep things dead simple, we avoided poluting the D.I. with this concept. Therefore, we recommend using a resource with a factory function to create instances of your classes:
 
-// Define the task
-const helloWorld = task({
-  id: "app.helloWorld",
-  async run() {
-    // Task logic here
-    return "Hello World!";
+```typescript
+const myFactory = resource({
+  id: "app.factories.myFactory",
+  init: async (config: { someOption: string }) => {
+    return (input: any) => {
+      return new MyClass(input, config.someOption);
+    };
   },
 });
 
-// Define the tasks for beforeRun, afterRun, and onError using the `on` property
-const beforeHelloWorldTask = task({
-  id: "app.helloWorld.beforeRun",
-  on: helloWorld.events.beforeRun, // Listening to beforeRun event
-  async run(event) {
-    const input = event.data.input; // Handle the input before task runs
-    console.log("Before run:", input);
+const app = resource({
+  id: "app",
+  register: [myFactory],
+  dependencies: { myFactory },
+  init: async (_, { myFactory }) => {
+    const instance = myFactory({ someOption: "value" });
   },
 });
+```
 
-const afterHelloWorldTask = task({
-  id: "app.helloWorld.afterRun",
-  on: helloWorld.events.afterRun, // Listening to afterRun event
-  async run(event) {
-    const output = event.data.output; // Handle the output after task runs
-    console.log("After run:", output);
-  },
-});
+### Internal Services: For When You Need Direct Access
+
+We expose the internal services for advanced use cases (but try not to use them unless you really need to):
 
-const helloWorldErrorTask = task({
-  id: "app.helloWorld.onError",
-  on: helloWorld.events.onError, // Listening to onError event
-  async run(event) {
-    const error = event.data.error; // Handle errors during task execution
-    console.error("Error:", error);
+```typescript
+import { globals } from "@bluelibs/runner";
+
+const advancedTask = task({
+  id: "app.advanced",
+  dependencies: {
+    store: globals.resources.store,
+    taskRunner: globals.resources.taskRunner,
+    eventManager: globals.resources.eventManager,
+  },
+  run: async (_, { store, taskRunner, eventManager }) => {
+    // Direct access to the framework internals
+    // (Use with caution!)
   },
 });
+```
 
-// Register all tasks to the app
-const app = resource({
-  id: "app",
-  register: [
-    helloWorld,
-    beforeHelloWorldTask,
-    afterHelloWorldTask,
-    helloWorldErrorTask,
-  ],
+## Real-World Example: The Complete Package
+
+Here's a more realistic application structure that shows everything working together:
+
+```typescript
+import {
+  resource,
+  task,
+  event,
+  middleware,
+  index,
+  run,
+  createContext,
+} from "@bluelibs/runner";
+
+// Configuration
+const config = resource({
+  id: "app.config",
+  init: async () => ({
+    port: parseInt(process.env.PORT || "3000"),
+    databaseUrl: process.env.DATABASE_URL!,
+    jwtSecret: process.env.JWT_SECRET!,
+  }),
 });
 
-// Run the app
-run(app);
-```
+// Database
+const database = resource({
+  id: "app.database",
+  dependencies: { config },
+  init: async (_, { config }) => {
+    const client = new MongoClient(config.databaseUrl);
+    await client.connect();
+    return client;
+  },
+  dispose: async (client) => await client.close(),
+});
 
-### Resource level
+// Context for request data
+const RequestContext = createContext<{ userId?: string; role?: string }>(
+  "app.requestContext"
+);
 
-```ts
-import { task, run, event } from "@bluelibs/runner";
+// Events
+const userRegistered = event<{ userId: string; email: string }>({
+  id: "app.events.userRegistered",
+});
 
-// Define the resource
-const businessConfig = resource({
-  id: "app.businessConfig",
-  async init(config) {
-    // Business logic to initialize config
-    return { value: "Business Configuration Loaded" };
+// Middleware
+const authMiddleware = middleware<{ requiredRole?: string }>({
+  id: "app.middleware.auth",
+  run: async ({ task, next }, deps, config) => {
+    const context = RequestContext.use();
+    if (config?.requiredRole && context.role !== config.requiredRole) {
+      throw new Error("Insufficient permissions");
+    }
+    return next(task.input);
   },
 });
 
-// Define tasks for handling events beforeInit, afterInit, and onError
+// Services
+const userService = resource({
+  id: "app.services.user",
+  dependencies: { database },
+  init: async (_, { database }) => ({
+    async createUser(userData: { name: string; email: string }) {
+      const users = database.collection("users");
+      const result = await users.insertOne(userData);
+      return { id: result.insertedId.toString(), ...userData };
+    },
+  }),
+});
 
-const beforeInitTask = task({
-  id: "app.businessConfig.beforeInit",
-  on: businessConfig.events.beforeInit, // Listening to beforeInit event
-  async run(event) {
-    const config = event.data.config; // Handle the config input before resource initialization
-    console.log("Before init:", config);
+// Business Logic
+const registerUser = task({
+  id: "app.tasks.registerUser",
+  dependencies: { userService, userRegistered },
+  run: async (userData, { userService, userRegistered }) => {
+    const user = await userService.createUser(userData);
+    await userRegistered({ userId: user.id, email: user.email });
+    return user;
   },
 });
 
-const afterInitTask = task({
-  id: "app.businessConfig.afterInit",
-  on: businessConfig.events.afterInit, // Listening to afterInit event
-  async run(event) {
-    const value = event.data.value; // Handle the return value after resource initialization
-    console.log("After init:", value);
+const adminOnlyTask = task({
+  id: "app.tasks.adminOnly",
+  middleware: [authMiddleware.with({ requiredRole: "admin" })],
+  run: async () => {
+    return "Top secret admin data";
   },
 });
 
-const businessConfigErrorTask = task({
-  id: "app.businessConfig.onError",
-  on: businessConfig.events.onError, // Listening to onError event
-  async run(event) {
-    const error = event.data.error; // Handle errors during resource initialization
-    console.error("Error during initialization:", error);
+// Event Handlers
+const sendWelcomeEmail = task({
+  id: "app.tasks.sendWelcomeEmail",
+  on: userRegistered,
+  run: async (event) => {
+    console.log(`Sending welcome email to ${event.data.email}`);
+    // Email sending logic here
   },
 });
 
-// Register all tasks and the businessConfig resource to the app
-const app = resource({
-  id: "app",
-  register: [
-    businessConfig,
-    beforeInitTask,
-    afterInitTask,
-    businessConfigErrorTask,
-  ],
+// Group everything together
+const services = index({
+  userService,
+  registerUser,
+  adminOnlyTask,
 });
 
-// Run the app
-run(app);
-```
-
-## Advanced Usage
+// Express server
+const server = resource({
+  id: "app.server",
+  register: [config, database, services, sendWelcomeEmail],
+  dependencies: { config, services },
+  init: async (_, { config, services }) => {
+    const app = express();
+    app.use(express.json());
+
+    // Middleware to set up request context
+    app.use((req, res, next) => {
+      RequestContext.provide(
+        { userId: req.headers["user-id"], role: req.headers["user-role"] },
+        () => next()
+      );
+    });
 
-This is just a "language" of developing applications. It simplifies dependency injection to the barebones, it forces you to think more functional and use classes less.
+    app.post("/register", async (req, res) => {
+      try {
+        const user = await services.registerUser(req.body);
+        res.json({ success: true, user });
+      } catch (error) {
+        res.status(400).json({ error: error.message });
+      }
+    });
 
-This doesn't mean you shouldn't use classes, just not for hooking things up together.
+    app.get("/admin", async (req, res) => {
+      try {
+        const data = await services.adminOnlyTask();
+        res.json({ data });
+      } catch (error) {
+        res.status(403).json({ error: error.message });
+      }
+    });
 
-You can add many services or external things into the runner ecosystem with things like:
+    const server = app.listen(config.port);
+    console.log(`Server running on port ${config.port}`);
+    return server;
+  },
+  dispose: async (server) => server.close(),
+});
 
-```ts
-import { task, run, event } from "@bluelibs/runner";
+// Start the application
+const { dispose } = await run(server);
 
-// proxy declaration pattern
-const expressResource = resource({
-  id: "app.helloWorld",
-  run: async (app: express.Application) => app,
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("Shutting down gracefully...");
+  await dispose();
+  process.exit(0);
 });
+```
 
-const app = resource({
-  id: "app",
-  register: [expressResource.with(express())],
-  dependencies: {
-    express: expressResource,
-  },
-  init: async (_, { express }) => {
-    express.get("/", (req, res) => {
-      res.send("Hello World!");
+## Testing: Actually Enjoyable
+
+### Unit Testing: Mock Everything, Test Everything
+
+Unit testing is straightforward because everything is explicit:
+
+```typescript
+describe("registerUser task", () => {
+  it("should create a user and emit event", async () => {
+    const mockUserService = {
+      createUser: jest.fn().mockResolvedValue({ id: "123", name: "John" }),
+    };
+    const mockEvent = jest.fn();
+
+    const result = await registerUser.run(
+      { name: "John", email: "john@example.com" },
+      { userService: mockUserService, userRegistered: mockEvent }
+    );
+
+    expect(result.id).toBe("123");
+    expect(mockEvent).toHaveBeenCalledWith({
+      userId: "123",
+      email: "john@example.com",
     });
-  },
+  });
 });
-
-run(app);
 ```
 
-This demonstrates how effortlessly an external service can be encapsulated within the runner ecosystem. This ‘pattern’ of storing objects in this manner is quite unique, as it typically involves configurations with various options, rather than directly using an Express instance like this:
+### Integration Testing: The Real Deal
 
-```ts
-type Config = {
-  port: number;
-};
+Integration testing with overrides lets you test the whole system with controlled components:
 
-const expressResource = resource({
-  id: "app.helloWorld",
-  init: async (config: Config) => {
-    const app = express();
-    app.listen(config.port);
-    return app;
-  },
+```typescript
+const testDatabase = resource({
+  id: "app.database",
+  init: async () => new MemoryDatabase(), // In-memory test database
 });
 
-const app = resource({
-  id: "app",
-  register: [expressResource.with({ port: 3000 })],
-  dependencies: {
-    express: expressResource,
-  },
-  init: async (_, { express }) => {
-    // type is automagically infered.
-    express.get("/", (req, res) => {
-      res.send("Hello World!");
-    });
-  },
+const testApp = resource({
+  id: "test.app",
+  register: [productionApp],
+  overrides: [testDatabase], // Replace real database with test one
 });
 
-run(app);
+describe("Full application", () => {
+  it("should handle user registration flow", async () => {
+    const { dispose } = await run(testApp);
+
+    // Test your application end-to-end
+
+    await dispose(); // Clean up
+  });
+});
 ```
 
-### Inter-communication between resources
+## Semaphore
 
-When registering resources with specific configuration, the initialization order usually doesn’t matter. However, there are cases where it becomes crucial. For instance, consider a security service that allows the injection of a custom hashing function to transition from MD5 to SHA-256.
+Ever had too many database connections competing for resources? Your connection pool under pressure? The `Semaphore` is here to manage concurrent operations like a professional traffic controller.
 
-In such cases, your resource should provide a method for other resources to update it. A straightforward approach is to expose a configuration option that lets you set a custom hasher, like so:
+Think of it as a VIP rope at an exclusive venue. Only a limited number of operations can proceed at once. The rest wait in an orderly queue like well-behaved async functions.
 
-```ts
-type SecurityResourceConfig = {
-  hasher: (str: string) => string;
-};
+### Quick Start
 
-const securityResource = resource({
-  id: "app.security",
-  async init(config: SecurityResourceConfig) {
-    return {
-      hash: (input: string) => config.hasher(input),
-    };
-  },
-});
+```typescript
+import { Semaphore } from "@bluelibs/runner";
+
+// Create a semaphore that allows max 5 concurrent operations
+const dbSemaphore = new Semaphore(5);
+
+// Basic usage - acquire and release manually
+await dbSemaphore.acquire();
+try {
+  // Do your database magic here
+  const result = await db.query("SELECT * FROM users");
+  console.log(result);
+} finally {
+  dbSemaphore.release(); // Critical: always release to prevent bottlenecks
+}
+```
 
-const app = resource({
-  id: "app",
-  register: [securityResource.with({ hasher: (input) => md5(input) })],
+### The Elegant Approach: withPermit()
+
+Why manage permits manually when you can let the semaphore do the heavy lifting?
+
+```typescript
+// The elegant approach - automatic cleanup guaranteed!
+const users = await dbSemaphore.withPermit(async () => {
+  return await db.query("SELECT * FROM users WHERE active = true");
 });
 ```
 
-However, other resources might need to modify this dynamically as extensions. This is where events become valuable.
+### Timeout Support
 
-```ts
-import { resource, run, event } from "@bluelibs/runner";
+Prevent operations from hanging indefinitely with configurable timeouts:
 
-type SecurityOptions = {
-  hashFunction: (input: string) => string;
-};
+```typescript
+try {
+  // Wait max 5 seconds, then throw timeout error
+  await dbSemaphore.acquire({ timeout: 5000 });
+  // Your code here
+} catch (error) {
+  console.log("Operation timed out waiting for permit");
+}
 
-const securityResource = resource({
-  /* Same as above, but create a setHasher method */
-});
-const afterSecurityInitTask = task({
-  id: "app.security.afterInit",
-  on: securityResource.events.afterInit, // Listening to afterInit event
-  async run(event, deps) {
-    const { config, value } = event.data;
-    const security = value;
+// Or with withPermit
+const result = await dbSemaphore.withPermit(
+  async () => await slowDatabaseOperation(),
+  { timeout: 10000 } // 10 second timeout
+);
+```
 
-    // Custom hasher implementation
-    security.setHasher((input) => {
-      // Implement custom hashing logic here
-      console.log("Hashing input:", input);
-    });
-  },
-});
+### Cancellation Support
 
-// Register the security resource and the afterInit task in the app
-const app = resource({
-  id: "app",
-  register: [securityResource, afterSecurityInitTask],
-});
-```
+Operations can be cancelled using AbortSignal:
 
-Another approach is to create a new event that contains the configuration, providing the flexibility to update it as needed.
+```typescript
+const controller = new AbortController();
+
+// Start an operation
+const operationPromise = dbSemaphore.withPermit(
+  async () => await veryLongOperation(),
+  { signal: controller.signal }
+);
+
+// Cancel the operation after 3 seconds
+setTimeout(() => {
+  controller.abort();
+}, 3000);
+
+try {
+  await operationPromise;
+} catch (error) {
+  console.log("Operation was cancelled");
+}
+```
 
-```ts
-import { resource, run, event } from "@bluelibs/runner";
+### Monitoring: Metrics & Debugging
 
-const securityConfigurationPhaseEvent = event<SecurityOptions>({
-  id: "app.security.configurationPhase",
-});
+Want to know what's happening under the hood?
 
-const securityResource = resource({
-  id: "app.security",
-  dependencies: {
-    securityConfigurationPhaseEvent,
-  },
-  async init(config: SecurityOptions) {
-    // Give the ability to other listeners to modify the configuration
-    securityConfigurationPhaseEvent(config);
-    Objecte.freeze(config);
+```typescript
+// Get comprehensive metrics
+const metrics = dbSemaphore.getMetrics();
+console.log(`
+Semaphore Status Report:
+  Available permits: ${metrics.availablePermits}/${metrics.maxPermits}
+  Operations waiting: ${metrics.waitingCount}
+  Utilization: ${(metrics.utilization * 100).toFixed(1)}%
+  Disposed: ${metrics.disposed ? "Yes" : "No"}
+`);
+
+// Quick checks
+console.log(`Available permits: ${dbSemaphore.getAvailablePermits()}`);
+console.log(`Queue length: ${dbSemaphore.getWaitingCount()}`);
+console.log(`Is disposed: ${dbSemaphore.isDisposed()}`);
+```
 
-    return {
-      // ... based on config
-    };
-  },
-});
+### Resource Cleanup
 
-// Define securityResource and securityConfigurationPhaseEvent as needed
+Properly dispose of semaphores when finished:
 
-const securityConfigTask = task({
-  id: "app.security.config",
-  on: securityConfigurationPhaseEvent, // Listening to securityConfigurationPhaseEvent
-  async run(event, deps) {
-    const { config } = event.data; // config is SecurityOptions
-    config.setHasher(newHashFunction); // Apply the new hash function
-  },
-});
+```typescript
+// Reject all waiting operations and prevent new ones
+dbSemaphore.dispose();
 
-// Register the security resource and configuration task in the app
-const app = resource({
-  id: "app",
-  register: [securityResource, securityConfigTask],
-});
+// All waiting operations will be rejected with:
+// Error: "Semaphore has been disposed"
 ```
 
-### Overrides
+## Queue
 
-Previously, we discussed how to extend functionality using events. However, there are times when you need to replace an existing resource with a new one or swap out a task or middleware imported from another package that doesn’t support such changes.
+_The orderly guardian of chaos, the diplomatic bouncer of async operations._
 
-```ts
-import { resource, run, event } from "@bluelibs/runner";
+The `Queue` class is your friendly neighborhood task coordinator. Think of it as a very polite but firm British queue-master who ensures everyone waits their turn, prevents cutting in line, and gracefully handles when it's time to close shop.
 
-// This example is for resources but override works for tasks, events, and middleware as well.
-const securityResource = resource({
-  id: "app.security",
-  async init() {
-    // returns a security service
-  },
-});
+### **FIFO Ordering**
 
-const override = resource({
-  ...securityResource,
-  init: async () => {
-    // a new and custom service
-  },
-});
+Tasks execute one after another in first-in, first-out order. No cutting, no exceptions, no drama.
 
-const app = resource({
-  id: "app",
-  register: [securityResource], // this resource might be registered by any element in the dependency tree.
-  overrides: [override],
-});
-```
+### **Deadlock Detective**
 
-The new securityResource will replace the existing one, ensuring all future references point to the updated version.
+Using the clever `AsyncLocalStorage`, our Queue can detect when a task tries to queue another task (the async equivalent of "yo dawg, I heard you like queues..."). When caught red-handed, it politely but firmly rejects with a deadlock error.
 
-Overrides work if the resource being overridden is already registered. If multiple resources attempt to override the same one, no error will be thrown. This is a common scenario, where the root resource typically contains the most authoritative overrides. But it's also to be mindful about.
+### **Graceful Disposal & Cancellation**
 
-## Logging
+The Queue provides cooperative cancellation through the Web Standard `AbortController`:
 
-We expose through globals a `logger` that you can use to log things. Essentially what this service does it emits a `global.events.log` event with an `ILog` object.
+- **Patient mode** (default): Waits for all queued tasks to complete naturally
+- **Cancel mode**: Signals running tasks to abort via `AbortSignal`, enabling early termination
 
-```ts
-import { task, run, event, globals } from "@bluelibs/runner";
+### Basic Example
 
-const helloWorld = task({
-  id: "app.helloWorld",
-  dependencies: {
-    logger: globals.resources.logger,
-  },
-  run: async (_, { logger }) => {
-    await logger.info("Hello World!");
-    // or logger.log(level, data);
-  },
+```typescript
+import { Queue } from "@bluelibs/runner";
+
+const queue = new Queue();
+
+// Queue up some work
+const result = await queue.run(async (signal) => {
+  // Your async task here
+  return "Task completed";
 });
+
+// Graceful shutdown
+await queue.dispose();
 ```
 
-### Logs Summary Table
+### AbortController Integration
 
-| Log Level    | Description                               | Usage Example                          |
-| ------------ | ----------------------------------------- | -------------------------------------- |
-| **trace**    | Very detailed logs, usually for debugging | "Entering function X with params Y."   |
-| **debug**    | Detailed debug information                | "Fetching user data: userId=123."      |
-| **info**     | General application information           | "Service started on port 8080."        |
-| **warn**     | Indicates a potential issue               | "Disk space running low."              |
-| **error**    | Indicates a significant problem           | "Unable to connect to database."       |
-| **critical** | Serious problem causing a crash           | "System out of memory, shutting down." |
+The Queue provides each task with an `AbortSignal` for cooperative cancellation. Tasks should periodically check this signal to enable early termination.
 
-### Print logs
+#### Example: Long-running Task with Cancellation Support
 
-Logs don't get printed by default. You have to set the print threshold to a certain level. This is useful when you want to print only errors and critical logs in production, but you want to print all logs in development. Your codebase, your rules.
+```typescript
+const queue = new Queue();
 
-To showcase the versatility of the system, here are some ways you could do it:
+// Task that respects cancellation
+const processLargeDataset = queue.run(async (signal) => {
+  const items = await fetchLargeDataset();
 
-```ts
-import { task, run, event, globals, resource } from "@bluelibs/runner";
+  for (const item of items) {
+    // Check for cancellation before processing each item
+    if (signal.aborted) {
+      throw new Error("Operation was cancelled");
+    }
 
-const { logger } = globals.resources;
+    await processItem(item);
+  }
 
-const printLog = task({
-  id: "app.task.updatePrintThreshold",
-  on: logger.events.afterInit,
-  // Note: logger is
-  run: async (event, deps) => {
-    const logger = event.data.value;
-    logger.setPrintThreshold("trace"); // will print all logs
-    logger.setPrintThreshold("error"); // will print only "error" and "critical" logs
-  },
+  return "Dataset processed successfully";
 });
 
-const app = resource({
-  id: "root",
-  register: [printLog],
+// Cancel all running tasks
+await queue.dispose({ cancel: true });
+```
+
+#### Example: Network Request with Timeout
+
+```typescript
+const queue = new Queue();
+
+const fetchWithCancellation = queue.run(async (signal) => {
+  try {
+    // Pass the signal to fetch for automatic cancellation
+    const response = await fetch("https://api.example.com/data", { signal });
+    return await response.json();
+  } catch (error) {
+    if (error.name === "AbortError") {
+      console.log("Request was cancelled");
+      throw error;
+    }
+    throw error;
+  }
 });
 
-// Now your app will print all logs
+// This will cancel the fetch request if still pending
+await queue.dispose({ cancel: true });
 ```
 
-The logger’s log() function is asynchronous because it handles events. If you want to prevent your system from waiting for log operations to complete, simply omit the await when calling log(). This is useful if you have listeners that send logs to external log storage systems.
+#### Example: File Processing with Progress Tracking
 
-Additionally, there is a `global.events.log` event available. You can use this event both to emit log messages and to listen for all log activities.
+```typescript
+const queue = new Queue();
 
-```ts
-import { task, run, event, globals } from "@bluelibs/runner";
+const processFiles = queue.run(async (signal) => {
+  const files = await getFileList();
+  const results = [];
 
-const { logger } = globals.resources;
+  for (let i = 0; i < files.length; i++) {
+    // Respect cancellation
+    signal.throwIfAborted();
 
-const shipLogsToWarehouse = task({
-  id: "app.task.shipLogsToWarehouse",
-  on: logger.events.log,
-  dependencies: {
-    warehouseService: warehouseServiceResource,
-  },
-  run: async (event, deps) => {
-    const log = event.data; // ILog
-    if (log.level === "error" || log.level === "critical") {
-      // Ensure no extra log() calls are made here to prevent infinite loops
-      await deps.warehouseService.push(log);
-    }
-  },
+    const result = await processFile(files[i]);
+    results.push(result);
+
+    // Optional: Report progress
+    console.log(`Processed ${i + 1}/${files.length} files`);
+  }
+
+  return results;
 });
 ```
 
-And yes, this would also work:
+## The Magic Behind the Curtain
 
-```ts
-const task = task({
-  id: "app.task.logSomething",
-  dependencies: {
-    log: globals.events.log,
-  },
-  run: async (_, { log }) => {
-    await log({
-      level: "info",
-      data: { anything: "you want" };
-      timestamp: new Date();
-      context: "app.task.logSomething"; // optional
-    })
-  },
-});
+### Internal State
+
+- `tail`: The promise chain that maintains FIFO execution order
+- `disposed`: Boolean flag indicating whether the queue accepts new tasks
+- `abortController`: Centralized cancellation controller that provides `AbortSignal` to all tasks
+- `executionContext`: AsyncLocalStorage-based deadlock detection mechanism
+
+### Error Handling
+
+- **"Queue has been disposed"**: You tried to add work after closing time
+- **"Dead-lock detected"**: A task tried to queue another task (infinite recursion prevention)
+
+### Best Practices
+
+#### 1. Always Dispose Resources
+
+```typescript
+const queue = new Queue();
+try {
+  await queue.run(task);
+} finally {
+  await queue.dispose();
+}
 ```
 
-Fair Warning: If you plan to use the global.events.log event, ensure you avoid creating a circular dependency. This event is emitted by the logger itself. Additionally, some logs are sent before all resources are fully initialized. Therefore, it’s important to carefully review and verify your dependencies to prevent potential issues.
+#### 2. Implement Cooperative Cancellation
 
-## Testing
+Tasks should regularly check the `AbortSignal` and respond appropriately:
 
-Oh yes, testing is a breeze with this system. You can easily test your tasks, resources, and middleware by running them in a test environment. It's designed to be tested.
+```typescript
+// Preferred: Use signal.throwIfAborted() for immediate termination
+signal.throwIfAborted();
 
-### Unit Testing
+// Alternative: Check signal.aborted for custom handling
+if (signal.aborted) {
+  cleanup();
+  throw new Error("Operation cancelled");
+}
+```
 
-You can easily test your middleware, resources and tasks by running them in a test environment.
+#### 3. Integrate with Native APIs
 
-The only components you need to test are the run function and the init functions, along with their proper dependencies.
+Many Web APIs accept `AbortSignal`:
 
-```ts
-import { task, resource } from "@bluelibs/runner";
+- `fetch(url, { signal })`
+- `setTimeout(callback, delay, { signal })`
+- Custom async operations
 
-const helloWorld = task({
-  id: "app.helloWorld",
-  run: async () => {
-    return "Hello World!";
-  },
-});
+### 4. Avoid Nested Queuing
 
-const helloWorldResource = resource({
-  id: "app.helloWorldResource",
-  init: async () => {
-    return "Hello World!";
-  },
-});
+The Queue prevents deadlocks by rejecting attempts to queue tasks from within running tasks. Structure your code to avoid this pattern.
 
-// sample tests for the task
-describe("app.helloWorld", () => {
-  it("should return Hello World!", async () => {
-    const result = await helloWorld.run(input, dependencies); // pass in the arguments and the mocked dependencies.
-    expect(result).toBe("Hello World!");
-  });
-});
+### 5. Handle AbortError Gracefully
 
-// sample tests for the resource
-describe("app.helloWorldResource", () => {
-  it("should return Hello World!", async () => {
-    const result = await helloWorldResource.init(config, dependencies); // pass in the arguments and the mocked dependencies.
-    expect(result).toBe("Hello World!");
-  });
-});
+```typescript
+try {
+  await queue.run(task);
+} catch (error) {
+  if (error.name === "AbortError") {
+    // Expected cancellation, handle appropriately
+    return;
+  }
+  throw error; // Re-throw unexpected errors
+}
 ```
 
-### Integration
+---
 
-Unit testing becomes straightforward with mocks, as all dependencies are explicitly defined. However, if you wish to run an integration test, you can have a task tested within the full container environment.
+_Cooperative task scheduling with professional-grade cancellation support_
 
-```ts
-import { task, resource, run, global } from "@bluelibs/runner";
+## Real-World Examples
 
-const task = task({
-  id: "app.myTask",
-  run: async () => {
-    return "Hello World!";
-  },
-});
+### Database Connection Pool Manager
 
-const app = resource({
-  id: "app",
-  register: [myTask],
-});
+```typescript
+class DatabaseManager {
+  private semaphore = new Semaphore(10); // Max 10 concurrent queries
+
+  async query(sql: string, params?: any[]) {
+    return this.semaphore.withPermit(
+      async () => {
+        const connection = await this.pool.getConnection();
+        try {
+          return await connection.query(sql, params);
+        } finally {
+          connection.release();
+        }
+      },
+      { timeout: 30000 } // 30 second timeout
+    );
+  }
+
+  async shutdown() {
+    this.semaphore.dispose();
+    await this.pool.close();
+  }
+}
 ```
 
-Then your tests can now be cleaner, as you can use `overrides` and a wrapper resource to mock your task.
-
-```ts
-describe("app", () => {
-  it("an example to override a task or resource", async () => {
-    const testApp = resource({
-      id: "app.test",
-      register: [myApp], // wrap your existing app
-      overrides: [override], // apply the overrides for "app.myTask"
-      init: async (_, deps) => {
-        // you can now test a task simply by depending on it, and running it, then asserting the response of run()
+### Rate-Limited API Client
+
+```typescript
+class APIClient {
+  private rateLimiter = new Semaphore(5); // Max 5 concurrent requests
+
+  async fetchUser(id: string, signal?: AbortSignal) {
+    return this.rateLimiter.withPermit(
+      async () => {
+        const response = await fetch(`/api/users/${id}`, { signal });
+        return response.json();
       },
+      { signal, timeout: 10000 }
+    );
+  }
+}
+```
+
+### Batch Processing with Progress
+
+```typescript
+async function processBatch(items: any[]) {
+  const semaphore = new Semaphore(3); // Max 3 concurrent items
+  const results = [];
+
+  console.log("Starting batch processing...");
+
+  for (const [index, item] of items.entries()) {
+    const result = await semaphore.withPermit(async () => {
+      console.log(`Processing item ${index + 1}/${items.length}`);
+      return await processItem(item);
     });
 
-    await run(testApp);
-  });
-});
+    results.push(result);
+
+    // Show progress
+    const metrics = semaphore.getMetrics();
+    console.log(
+      `Active: ${metrics.maxPermits - metrics.availablePermits}, Waiting: ${
+        metrics.waitingCount
+      }`
+    );
+  }
+
+  semaphore.dispose();
+  console.log("Batch processing complete!");
+  return results;
+}
 ```
 
-## Support
+## Best Practices
+
+1. **Always dispose**: Clean up your semaphores when finished to prevent memory leaks
+2. **Use withPermit()**: It's cleaner and prevents resource leaks
+3. **Set timeouts**: Don't let operations hang forever
+4. **Monitor metrics**: Keep an eye on utilization to tune your permit count
+5. **Handle errors**: Timeouts and cancellations throw errors - catch them!
+
+## Common Pitfalls
+
+- **Forgetting to release**: Manual acquire/release is error-prone - prefer `withPermit()`
+- **No timeout**: Operations can hang forever without timeouts
+- **Ignoring disposal**: Always dispose semaphores to prevent memory leaks
+- **Wrong permit count**: Too few = slow, too many = defeats the purpose
+
+## Why Choose BlueLibs Runner?
+
+### What You Get
+
+- **Type Safety**: Full TypeScript support with intelligent inference
+- **Testability**: Everything is mockable and testable by design
+- **Flexibility**: Compose your app however you want
+- **Performance**: Built-in caching and optimization
+- **Clarity**: Explicit dependencies, no hidden magic
+- **Developer Experience**: Helpful error messages and clear patterns
+
+### What You Don't Get
+
+- Complex configuration files that require a PhD to understand
+- Decorator hell that makes your code look like a Christmas tree
+- Hidden dependencies that break when you least expect it
+- Framework lock-in that makes you feel trapped
+- Mysterious behavior at runtime that makes you question reality
+
+## The Migration Path
+
+Coming from Express? No problem. Coming from NestJS? We feel your pain. Coming from Spring Boot? Welcome to the light side.
+
+The beauty of BlueLibs Runner is that you can adopt it incrementally. Start with one task, one resource, and gradually refactor your existing code. No big bang rewrites required - your sanity will thank you.
+
+## Community & Support
+
+This is part of the [BlueLibs](https://www.bluelibs.com) ecosystem. We're not trying to reinvent everything – just the parts that were broken.
+
+- [GitHub Repository](https://github.com/bluelibs/runner) - ⭐ if you find this useful
+- [Documentation](https://bluelibs.github.io/runner/) - When you need the full details
+- [Issues](https://github.com/bluelibs/runner/issues) - When something breaks (or you want to make it better)
+
+## The Bottom Line
+
+BlueLibs Runner is what happens when you take all the good ideas from modern frameworks and leave out the parts that make you want to switch careers. It's TypeScript-first, test-friendly, and actually makes sense when you read it six months later.
+
+Give it a try. Your future self (and your team) will thank you.
 
-This package is part of the [BlueLibs](https://www.bluelibs.com) family. If you enjoy this work, please show your support by starring [the main repository](https://github.com/bluelibs/runner).
+_P.S. - Yes, we know there are 47 other JavaScript frameworks. This one's different. (No, really, it is.)_
 
 ## License