@bluelibs/runner 1.2.0 → 1.4.0

package/README.md

@@ -6,14 +6,14 @@
 <a href="https://bluelibs.github.io/runner/" target="_blank"><img src="https://img.shields.io/badge/read-typedocs-blue" alt="Docs" /></a>
 </p>
 
-These are the building blocks to create amazing applications. It's a more functional approach to building small and large-scale applications.
+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.
 
-These are the building blocks:
+## 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. They can be used to add additional functionality to your tasks. Middleware can be global or task-specific.
+- **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.
 
 These are the concepts and philosophy:
 
@@ -23,11 +23,11 @@ These are the concepts and philosophy:
 - **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.
 
-Resources return through `async init()` their value to the container which can be used throughout the application. Resources might not have a value, they can just register things, like tasks, events, or middleware.
+Resources return their value to the container using the async `init()` function, making them available throughout the application.
 
-Tasks return through `async run()` function and the value from run, can be used throughout the application.
+Tasks provide their output through the async `run()` function, allowing the results to be used across the application.
 
-All tasks, resources, events, and middleware have to be explicitly registered to be used. Registration can only be done in resources.
+All tasks, resources, events, and middleware must be explicitly registered to be used. Registration can only be done within resources.
 
 ## Installation
 
@@ -38,7 +38,7 @@ npm install @bluelibs/runner
 ## Basic Usage
 
 ```typescript
-import { task, run, resource } from "@bluelibs/runner";
+import { run, resource } from "@bluelibs/runner";
 
 const minimal = resource({
   async init() {
@@ -53,16 +53,16 @@ run(minimal).then((result) => {
 
 ## Resources and Tasks
 
-Resources are singletons. They can be constants, services, functions, etc. They can depend on other resources, tasks, and event emitters.
+Resources are singletons and can include constants, services, functions, and more. They can depend on other resources, tasks, and event emitters.
 
-On the other hand, tasks are designed to be trackable units of logic. Like things that handle a specific route on your HTTP server, or any kind of action that is needed from various places. This will allow you to easily track what is happening in your application.
+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.
 
 ```ts
 import { task, run, resource } from "@bluelibs/runner";
 
 const helloTask = task({
   id: "app.hello",
-  run: async () => console.log("Hello World!"),
+  run: async () => "Hello World!",
 });
 
 const app = resource({
@@ -72,24 +72,26 @@ const app = resource({
     hello: helloTask,
   },
   async init(_, deps) {
-    await deps.hello();
+    return await deps.hello();
   },
 });
+
+const result = await run(app); // "Hello World!"
 ```
 
 ### When to use each?
 
-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 an action, for example:
+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:
 
 - "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
+- "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
 
 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.
 
 ### Resource dispose()
 
-Resources can have a `dispose()` method that can be used to clean up resources. This is useful for cleaning up resources like closing database connections, etc. You typically want to use this when you have opened pending connections or you need to do some cleanup or a graceful shutdown.
+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.
 
 ```ts
 import { task, run, resource } from "@bluelibs/runner";
@@ -99,13 +101,14 @@ const dbResource = resource({
     const db = await connectToDatabase();
     return db;
   },
+  // the value returned from init() will be passed to dispose()
   async dispose(db, config, deps) {
     return db.close();
   },
 });
 ```
 
-If you want to call dispose, you have to do it through the global store.
+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.
 
 ```ts
 import { task, run, resource, globals } from "@bluelibs/runner";
@@ -117,6 +120,7 @@ const app = resource({
     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(),
     };
@@ -128,15 +132,45 @@ const value = await run(app);
 await value.dispose();
 ```
 
-## Encapsulation
+### Resource configuration
 
-We want to make sure that our tasks are not dependent on the outside world. This is why we have the `dependencies` object.
+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.
 
-You cannot call on an task outside from dependencies. And not only that, it has to be explicitly registered to the container.
+```ts
+import { task, run, resource } from "@bluelibs/runner";
+
+type Config = { smtpUrl: string; defaultFrom: 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 app = resource({
+  id: "app",
+  register: [
+    // proper autocompletion is present
+    emailerResource.with({ smtpUrl: "smtp://localhost", defaultFrom: "" }),
+  ],
+});
+```
+
+If by any chance your main `app` has configs then they will be passed via the second argument of `run`, like this:
+
+```ts
+run(app, config);
+```
 
 ## Dependencies
 
-You can depend on `tasks`, `resources`, `events` and `middleware`.
+You can depend on `tasks`, `resources`, `events` and (indirectly) on `middleware`.
 
 ```ts
 import { task, resource, run, event } from "@bluelibs/runner";
@@ -146,11 +180,16 @@ const helloWorld = task({
   dependencies: {
     userRegisteredEvent,
   },
+  async run(_, deps) {
+    await deps.userRegisteredEvent();
+    return "Hello World!";
+  },
 });
 
 const app = resource({
   id: "app",
-  register: [helloWorld],
+  // You have to register everything you use.
+  register: [helloWorld, logMiddleware],
   dependencies: {
     helloWorld,
   },
@@ -162,9 +201,18 @@ const app = resource({
 run(app);
 ```
 
-Resources can also depend on other resources and tasks. We have a circular dependency checker which ensures consistency. If a circular dependency is detected, an error will be thrown showing you the exact pathways.
+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:
 
-Tasks are not limited to this constraint, actions can use depend on each other freely.
+| 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 |
 
 ## Events
 
@@ -184,7 +232,6 @@ const root = resource({
   dependencies: {
     afterRegisterEvent,
   },
-
   async init(_, deps) {
     // the event becomes a function that you run with the propper payload
     await deps.afterRegisterEvent({ userId: string });
@@ -192,9 +239,9 @@ const root = resource({
 });
 ```
 
-There are only 2 ways to listen to events:
+There are only 2 recommended ways to listen to events:
 
-### `on` property
+### `task.on` property
 
 ```ts
 import { task, run, event } from "@bluelibs/runner";
@@ -206,24 +253,25 @@ const afterRegisterEvent = event<{ userId: string }>({
 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) {
     console.log("User has been registered!");
   },
 });
 
-const root = resource({
+const app = resource({
   id: "app",
   register: [afterRegisterEvent, helloTask],
   dependencies: {
     afterRegisterEvent,
   },
   async init(_, deps) {
-    deps.afterRegisterEvent({ userId: "XXX" });
+    await deps.afterRegisterEvent({ userId: "XXX" });
   },
 });
 ```
 
-### `hooks` property
+### `resource.hooks` property
 
 This can only be applied to a `resource()`.
 
@@ -241,11 +289,47 @@ const root = resource({
   hooks: [
     {
       event: global.events.afterInit,
+      order: -1000, // event priority, the lower the number, the sooner it will run.
       async run(event, deps) {
+        // both dependencies and event are properly infered through typescript
         console.log("User has been registered!");
       },
     },
   ],
+  async init(_, deps) {
+    await deps.afterRegisterEvent({ userId: "XXX" });
+  },
+});
+```
+
+#### wildcard events
+
+You can listen to all events by using the wildcard `*`.
+
+```ts
+import { task, resource, run, event, global } from "@bluelibs/runner";
+
+const afterRegisterEvent = event<{ userId: string }>({
+  id: "app.user.registered",
+});
+
+const root = resource({
+  id: "app",
+  register: [afterRegisterEvent],
+  dependencies: {},
+  hooks: [
+    {
+      event: "*",
+      async run(event, deps) {
+        console.log(
+          "Generic event detected",
+          event.id,
+          event.data,
+          event.timestamp
+        );
+      },
+    },
+  ],
   async init(_, deps) {
     deps.afterRegisterEvent({ userId: "XXX" });
   },
@@ -256,12 +340,17 @@ When using hooks, inside resource() you benefit of autocompletion, in order to k
 
 The hooks from a `resource` are mostly used for configuration, and blending in the system.
 
+### When to use either?
+
+- `hooks` are for resources to extend each other, compose functionalities, they are mostly used for configuration and blending in the system.
+- `on` is for when you want to perform a task when something happens, like send an email, begin processing something, etc.
+
 ## Middleware
 
-Middleware is a way to intercept the execution of tasks. It's a powerful way to add additional functionality to your tasks. First middleware that gets registered is the first that runs, the last middleware that runs is 'closest' to the task, most likely the last element inside `middleware` array at task level.
+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.)
 
 ```ts
-import { task, run, event } from "@bluelibs/runner";
+import { task, resource, run, event } from "@bluelibs/runner";
 
 const logMiddleware = middleware({
   id: "app.middleware.log",
@@ -269,11 +358,18 @@ const logMiddleware = middleware({
     // inject tasks, resources, eventCallers here.
   },
   async run(data, deps) {
-    const { taskDefinition, next, input } = data;
-
-    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);
+    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);
+    }
 
     return result;
   },
@@ -288,34 +384,16 @@ const helloTask = task({
 });
 ```
 
-You can use middleware creators (function that returns) for configurable middlewares such as:
+### Global
 
-```ts
-import { middleware } from "@bluelibs/runner";
-
-function createLogMiddleware(config) {
-  return middleware({
-    // your config-based middleware here.
-  });
-}
-```
-
-However, if you want to register a middleware for all tasks, here's how you can do it:
+If you want to register a middleware for all tasks and resources, here's how you can do it:
 
 ```ts
 import { run, resource } from "@bluelibs/runner";
 
 const logMiddleware = middleware({
   id: "app.middleware.log",
-  async run(data, deps) {
-    const { taskDefinition, next, input } = data;
-
-    console.log("Before task", task.id);
-    const result = await next(input);
-    console.log("After task", task.id);
-
-    return result;
-  },
+  // ... rest
 });
 
 const root = resource({
@@ -324,22 +402,11 @@ const root = resource({
 });
 ```
 
-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.
-
-### Middleware for resources
-
-Unfortunately, middleware for resources is not supported at the moment. The main reason for this is simplicity and the fact that resources are not meant to be executed, but rather to be initialized.
-
-You have access to the global events if you want to hook into the initialisation system.
-
-### When to use either?
-
-- `hooks` are for resources to extend each other, compose functionalities, they are mostly used for configuration and blending in the system.
-- `on` is for when you want to perform a task when something happens.
+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.
 
 ## Errors
 
-If an error is thrown in a task, the error will be propagated up.
+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";
@@ -362,22 +429,40 @@ const app = resource({
   },
 });
 
-run(app);
+run(app).catch((err) => {
+  console.error(err);
+});
 ```
 
 You can listen to errors via events:
 
 ```ts
 const helloWorld = task({
-  id: "app.onError",
+  id: "app.tasks.helloWorld.onError",
+  on: helloWorld.events.onError,
+  run({ error, input, suppress }, deps) {
+    // this will be called when an error happens
+
+    // if you handled the error, and you don't want it propagated to the top, supress the propagation.
+    suppress();
+  },
+});
+```
+
+```ts
+const helloWorld = resource({
+  id: "app.resources.helloWorld.onError",
   on: helloWorld.events.onError,
-  run({ error, input }, deps) {
+  init({ error, input, suppress }, deps) {
     // this will be called when an error happens
+
+    // if you handled the error, and you don't want it propagated to the top, supress the propagation.
+    suppress();
   },
 });
 ```
 
-## Metadata
+## Meta
 
 You can attach metadata to tasks, resources, events, and middleware.
 
@@ -397,7 +482,7 @@ const helloWorld = task({
 });
 ```
 
-This is particularly helpful to use in conjunction with global middlewares, or global events, etc.
+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.
 
 The interfaces look like this:
 
@@ -416,7 +501,7 @@ export interface IMiddlewareMeta extends IMeta {}
 
 Which means you can extend them in your system to add more keys to better describe your actions.
 
-## Global Services
+## Internal Services
 
 We expose direct access to the following internal services:
 
@@ -424,7 +509,7 @@ We expose direct access to the following internal services:
 - TaskRunner (can run tasks definitions directly and within D.I. context)
 - EventManager (can emit and listen to events)
 
-Attention, it is not recommended to use these services directly, but they are exposed for advanced use-cases, for when you do not have any other way.
+Attention, we do not encourage you to use these services directly, unless you really have to, they are exposed for advanced use-case scenarios.
 
 ```ts
 import { task, run, event, globals } from "@bluelibs/runner";
@@ -444,16 +529,20 @@ const helloWorld = task({
 
 ## Namespacing
 
-We typically namespace using `.` like `app.helloWorld`. This is a convention that we use to make sure that we can easily identify where the task belongs to.
-
-When creating special packages the convention is:
+Domain usually is "app", but as your application grows or you plan on building external libraries the naming convention should be: "companyName.packageName".
 
-- `{companyName}.{packageName}.{taskName}`
+| 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}`    |
 
 You can always create helpers for you as you're creating your tasks, resources, middleware:
 
 ```ts
-function getNamespace(id) {
+function namespaced(id) {
   return `bluelibs.core.${id}`;
 }
 ```
@@ -495,9 +584,11 @@ Now you can freely use any of the tasks, resources, events, and middlewares from
 
 This approach is very powerful when you have multiple packages and you want to compose them together.
 
-## Real world usage.
+## Real life
 
-Typically you have an express server (to handle HTTP requests), a database, and a bunch of services. You can define all of these in a single file and run them.
+Or is it just fantasy?
+
+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.
 
 ```ts
 import { task, resource, run, event } from "@bluelibs/runner";
@@ -537,11 +628,11 @@ const app = resource({
 run();
 ```
 
-The system is smart enough to know which `init()` to call first. Typically all dependencies are initialised first. If there are circular dependencies, an error will be thrown with the exact paths.
+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.
 
 ### Business config
 
-There's a resource for that! You can define a resource that holds your business configuration.
+Or just simple config, you can do it for your business logic, environment variables, etc.
 
 ```ts
 import { resource, run } from "@bluelibs/runner";
@@ -570,47 +661,7 @@ const app = resource({
 run();
 ```
 
-### Resources can receive configs
-
-Resources are super configurable.
-
-```ts
-import { resource, run } from "@bluelibs/runner";
-
-type EmailerOptions = {
-  smtpUrl: string;
-  defaultFrom: string;
-};
-
-const emailerResource = resource({
-  id: "app.config",
-  async init(config: EmailerOptions) {
-    return {
-      sendEmail: async (to: string, subject: string, body: string) => {
-        // send *email*
-      },
-    };
-    // or return some service that sends email
-  },
-});
-
-const app = resource({
-  id: "app",
-  register: [
-    // You can pass the config here
-    emailerResource.with({
-      smtpUrl: "smtp://localhost",
-      defaultFrom: "",
-    }),
-    // Leaving it simply emailerResource is similar to passing an empty object.
-    // We leave this for simplicity in some cases but we recommend using .with() for clarity.
-  ],
-});
-
-run(app);
-```
-
-## Useful events
+## Global Events
 
 ### Task level
 
@@ -650,15 +701,19 @@ const app = resource({
 run(app);
 ```
 
-## Resource level
+### Resource level
 
 ```ts
 import { task, run, event } from "@bluelibs/runner";
 
+const businessData = {
+  pricePerSubscription: 9.99,
+};
+
 const businessConfig = resource({
   id: "app.config",
   async init() {
-    return businessData;
+    return businessData; // if you use it as a const you will have full typesafety
   },
 });
 
@@ -690,24 +745,30 @@ const app = resource({
 run(app);
 ```
 
-## Moving further
+## Advanced Usage
 
 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.
 
+This doesn't mean you shouldn't use classes, just not for hooking things up together.
+
 You can add many services or external things into the runner ecosystem with things like:
 
 ```ts
 import { task, run, event } from "@bluelibs/runner";
 
-const expressResource = resource<express.Application>({
+// proxy declaration pattern
+const expressResource = resource({
   id: "app.helloWorld",
-  run: async (config) => config,
+  run: async (app: express.Application) => app,
 });
 
 const app = resource({
   id: "app",
   register: [expressResource.with(express())],
-  init: async (express) => {
+  dependencies: {
+    express: expressResource,
+  },
+  init: async (_, { express }) => {
     express.get("/", (req, res) => {
       res.send("Hello World!");
     });
@@ -717,12 +778,16 @@ const app = resource({
 run(app);
 ```
 
-This shows how easy you encapsulate an external service into the runner ecosystem. This 'pattern' of storing objects like this is not that common because usually they require a configuration with propper options and stuff, not an express instance(), like this:
+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:
 
 ```ts
+type Config = {
+  port: number;
+};
+
 const expressResource = resource({
   id: "app.helloWorld",
-  run: async (config) => {
+  init: async (config: Config) => {
     const app = express();
     app.listen(config.port);
     return app;
@@ -732,7 +797,10 @@ const expressResource = resource({
 const app = resource({
   id: "app",
   register: [expressResource.with({ port: 3000 })],
-  init: async (express) => {
+  dependencies: {
+    express: expressResource,
+  },
+  init: async (_, { express }) => {
     // type is automagically infered.
     express.get("/", (req, res) => {
       res.send("Hello World!");
@@ -743,7 +811,7 @@ const app = resource({
 run(app);
 ```
 
-## Inter-communication between resources
+### Inter-communication between resources
 
 By stating dependencies you often don't care about the initialisation order, but sometimes you really do, for example, let's imagine a security service that allows you to inject a custom hashing function let's say to shift from md5 to sha256.
 
@@ -776,6 +844,7 @@ const app = resource({
   register: [securityResource],
   hooks: [
     {
+      // careful when you listen on such events and need dependencies, you might not have them computed yet due to how early these events happen in the system.
       event: securityResource.events.afterInit,
       async run(event, deps) {
         const { config, value } = event.data;
@@ -790,7 +859,7 @@ const app = resource({
 });
 ```
 
-Another approach is to create a new event that holds the config and it allows it to be updated.
+Another approach is to create a new event that contains the configuration, providing the flexibility to update it as needed.
 
 ```ts
 import { resource, run, event } from "@bluelibs/runner";
@@ -807,6 +876,7 @@ const securityResource = resource({
   async init(config: SecurityOptions) {
     // Give the ability to other listeners to modify the configuration
     securityConfigurationPhaseEvent(config);
+    Objecte.freeze(config);
 
     return {
       // ... based on config
@@ -829,11 +899,42 @@ const app = resource({
 });
 ```
 
-## Logging
+### Overrides
+
+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.
+
+```ts
+import { resource, run, event } from "@bluelibs/runner";
+
+// 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
+  },
+});
+
+const override = resource({
+  ...securityResource,
+  init: async () => {
+    // a new and custom service
+  },
+});
+
+const app = resource({
+  id: "app",
+  register: [securityResource], // this resource might be registered by any element in the dependency tree.
+  overrides: [override],
+});
+```
 
-We expose through globals a logger that you can use to log things.
+The new securityResource will replace the existing one, ensuring all future references point to the updated version.
 
-By default logs are not printed unless a resource listens to the log event. This is by design, when something is logged an event is emitted. You can listen to this event and print the logs.
+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.
+
+## Logging
+
+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.
 
 ```ts
 import { task, run, event, globals } from "@bluelibs/runner";
@@ -863,19 +964,23 @@ const helloWorld = task({
 
 ### Print logs
 
-Logs don't get printed by default in this system.
+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.
+
+To showcase the versatility of the system, here are some ways you could do it:
 
 ```ts
 import { task, run, event, globals, resource } from "@bluelibs/runner";
 
+const { logger } = globals.resources;
+
 const printLog = task({
-  id: "app.task.printLog",
-  on: globals.events.log,
-  dependencies: {
-    logger: globals.resources.logger,
-  },
-  run: async (event, { logger }) => {
-    logger.print(event);
+  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
   },
 });
 
@@ -887,50 +992,79 @@ const app = resource({
 // Now your app will print all logs
 ```
 
-You can in theory do it in `hooks` as well, but as specified `hooks` are mostly used for configuration and blending in the system.
+You can also achieve this using hooks:
 
-The logger's `log()` function is async as it works with events. If you don't want your system hanging on logs, simply omit the `await`
+```ts
+resource({
+  id: "root",
+  hooks: [
+    {
+      // after logger gets initialised as a resource, I'm going to set the print threshold
+      event: logger.events.afterInit,
+      async run(event) {
+        const logger = event.data; // do not depend on the logger
+        logger.setPrintThreshold("trace");
+      },
+    },
+  ],
+});
+```
 
-## Overrides
+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.
 
-Previously, we explored how we can extend functionality through events. However, sometimes you want to override a resource with a new one or simply swap out a task or a middleware that you import from another package and they don't offer the ability.
+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.
 
 ```ts
-import { resource, run, event } from "@bluelibs/runner";
+import { task, run, event, globals } from "@bluelibs/runner";
 
-// 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
-  },
-});
+const { logger } = globals.resources;
 
-const override = resource({
-  ...securityResource,
-  init: async () => {
-    // a new and custom service
+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 app = resource({
-  id: "app",
-  register: [securityResource], // this resource might be registered by any element in the dependency tree.
-  overrides: [override],
+And yes, this would also work:
+
+```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
+    })
+  },
 });
 ```
 
-Now the `securityResource` will be overriden by the new one and whenever it's used it will use the new one.
-
-Overrides can only happen once and only if the overriden resource is registered. If two resources try to override the same resource, an error will be thrown.
+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.
 
 ## Testing
 
+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.
+
 ### Unit Testing
 
-You can easily test your resources and tasks by running them in a test environment.
+You can easily test your middleware, resources and tasks by running them in a test environment.
 
-The only bits that you need to test are the `run` function and the `init` functions with the propper dependencies.
+The only components you need to test are the run function and the init functions, along with their proper dependencies.
 
 ```ts
 import { task, resource } from "@bluelibs/runner";
@@ -968,7 +1102,7 @@ describe("app.helloWorldResource", () => {
 
 ### Integration
 
-Unit testing can be very simply with mocks, since all dependencies are explicit. However, if you would like to run an integration test, and have a task be tested and within the full container.
+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.
 
 ```ts
 import { task, resource, run, global } from "@bluelibs/runner";
@@ -986,7 +1120,7 @@ const app = resource({
 });
 ```
 
-Then your tests can now be cleaner:
+Then your tests can now be cleaner, as you can use `overrides` and a wrapper resource to mock your task.
 
 ```ts
 describe("app", () => {
@@ -994,14 +1128,12 @@ describe("app", () => {
     const testApp = resource({
       id: "app.test",
       register: [myApp], // wrap your existing app
-      overrides: [override], // apply the overrides
+      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()
       },
     });
 
-    // Same concept applies for resources as well.
-
     await run(testApp);
   });
 });