@bluelibs/runner 1.1.0 → 1.3.0

package/README.md

@@ -6,9 +6,9 @@
 <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.
@@ -89,7 +89,7 @@ Resources are more like services, they are singletons, they are meant to be used
 
 ### 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 have a `dispose()` method that can be used for cleanups. 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.
 
 ```ts
 import { task, run, resource } from "@bluelibs/runner";
@@ -99,24 +99,26 @@ 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.
+If you want to call dispose, you have to do it through the global resource called `store`, as everything is encapsulated.
 
 ```ts
-import { task, run, resource, global } from "@bluelibs/runner";
+import { task, run, resource, globals } from "@bluelibs/runner";
 
 const app = resource({
   id: "app",
   register: [dbResource],
   dependencies: {
-    store: global.resources.store,
+    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 +130,43 @@ const value = await run(app);
 await value.dispose();
 ```
 
-## Encapsulation
+### Resource with()
+
+Resources can be configured with a configuration object. This is useful when you want to pass in configuration to them. For example, you're building a library and you're initialising a mailer service, you can pass in the SMTP credentials as a configuration.
+
+```ts
+import { task, run, resource } from "@bluelibs/runner";
+
+type Config = { smtpUrl: string; defaultFrom: string };
+const emailerResource = resource({
+  async init(config: Config) {
+    // run config checks
+    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: "" }),
+  ],
+});
+```
 
-We want to make sure that our tasks are not dependent on the outside world. This is why we have the `dependencies` object.
+If by any chance your main `app` has configs then they will be passed via the second argument of `run`, like this:
 
-You cannot call on an task outside from dependencies. And not only that, it has to be explicitly registered to the container.
+```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";
@@ -150,7 +180,7 @@ const helloWorld = task({
 
 const app = resource({
   id: "app",
-  register: [helloWorld],
+  register: [helloWorld, logMiddleware],
   dependencies: {
     helloWorld,
   },
@@ -194,7 +224,7 @@ const root = resource({
 
 There are only 2 ways to listen to events:
 
-#### `on` property
+### `on` property
 
 ```ts
 import { task, run, event } from "@bluelibs/runner";
@@ -211,24 +241,24 @@ const helloTask = task({
   },
 });
 
-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
 
-This is only for resources
+This can only be applied to a `resource()`.
 
 ```ts
-import { task, resource, run, event } from "@bluelibs/runner";
+import { task, resource, run, event, global } from "@bluelibs/runner";
 
 const afterRegisterEvent = event<{ userId: string }>({
   id: "app.user.registered",
@@ -237,14 +267,12 @@ const afterRegisterEvent = event<{ userId: string }>({
 const root = resource({
   id: "app",
   register: [afterRegisterEvent],
-  dependencies: {
-    // ...
-  }
+  dependencies: {},
   hooks: [
     {
-      event: afterRegisterEvent,
+      event: global.events.afterInit,
       async run(event, deps) {
-        // the dependencies from init() also arrive inside the hooks()
+        // both dependencies and event are properly infered through typescript
         console.log("User has been registered!");
       },
     },
@@ -255,12 +283,55 @@ const root = resource({
 });
 ```
 
+### hooks wildcard
+
+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" });
+  },
+});
+```
+
+When using hooks, inside resource() you benefit of autocompletion, in order to keep things clean, if your hooks become large and long consider switching to tasks and `on`. This is a more explicit way to listen to events, and your resource registers them.
+
+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.
+
 ## 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 is a way to intercept the execution of tasks or initialization of resources. It's a powerful way to add additional functionality. First middleware that gets registered is the first that runs, giving it a form of priority, the last middleware that runs is 'closest' to the task, most likely the last element inside `middleware` array at task level.
 
 ```ts
-import { task, run, event } from "@bluelibs/runner";
+import { task, resource, run, event } from "@bluelibs/runner";
 
 const logMiddleware = middleware({
   id: "app.middleware.log",
@@ -268,11 +339,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;
   },
@@ -287,34 +365,14 @@ const helloTask = task({
 });
 ```
 
-You can use middleware creators (function that returns) for configurable middlewares such as:
-
-```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:
+However, 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({
@@ -325,20 +383,9 @@ 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.
-
 ## 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";
@@ -361,7 +408,9 @@ const app = resource({
   },
 });
 
-run(app);
+run(app).catch((err) => {
+  console.error(err);
+});
 ```
 
 You can listen to errors via events:
@@ -370,8 +419,11 @@ You can listen to errors via events:
 const helloWorld = task({
   id: "app.onError",
   on: helloWorld.events.onError,
-  run({ error, input }, deps) {
+  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();
   },
 });
 ```
@@ -396,7 +448,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.
 
 The interfaces look like this:
 
@@ -494,7 +546,7 @@ 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 world examples
 
 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.
 
@@ -569,47 +621,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
 
@@ -649,15 +661,19 @@ const app = resource({
 run(app);
 ```
 
-## Resource level
+### Business Config
 
 ```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
   },
 });
 
@@ -689,10 +705,12 @@ const app = resource({
 run(app);
 ```
 
-## Moving further
+### Moving further
 
 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
@@ -742,7 +760,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.
 
@@ -804,6 +822,7 @@ const securityResource = resource({
     securityConfigurationPhaseEvent,
   },
   async init(config: SecurityOptions) {
+    // Give the ability to other listeners to modify the configuration
     securityConfigurationPhaseEvent(config);
 
     return {
@@ -827,11 +846,187 @@ const app = resource({
 });
 ```
 
-## Support
+## Overrides
+
+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.
+
+```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],
+});
+```
+
+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.
+
+## Logging
+
+We expose through globals a logger that you can use to log things.
+
+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.
+
+```ts
+import { task, run, event, globals } from "@bluelibs/runner";
+
+const helloWorld = task({
+  id: "app.helloWorld",
+  dependencies: {
+    logger: globals.resources.logger,
+  },
+  run: async (_, { logger }) => {
+    await logger.info("Hello World!");
+    // or logger.log(level, data);
+  },
+});
+```
+
+### Logs Summary Table
+
+| 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." |
+
+### Print logs
+
+Logs don't get printed by default in this system.
+
+```ts
+import { task, run, event, globals, resource } from "@bluelibs/runner";
+
+const printLog = task({
+  id: "app.task.printLog",
+  on: globals.events.log,
+  dependencies: {
+    logger: globals.resources.logger,
+  },
+  run: async (event, { logger }) => {
+    logger.print(event);
+  },
+});
 
-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/bluelibs).
+const app = resource({
+  id: "root",
+  register: [printLog],
+});
+
+// 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.
+
+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`
+
+## Testing
+
+### Unit Testing
+
+You can easily test your 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.
+
+```ts
+import { task, resource } from "@bluelibs/runner";
+
+const helloWorld = task({
+  id: "app.helloWorld",
+  run: async () => {
+    return "Hello World!";
+  },
+});
+
+const helloWorldResource = resource({
+  id: "app.helloWorldResource",
+  init: async () => {
+    return "Hello World!";
+  },
+});
+
+// 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!");
+  });
+});
+
+// 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!");
+  });
+});
+```
+
+### 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.
+
+```ts
+import { task, resource, run, global } from "@bluelibs/runner";
+
+const task = task({
+  id: "app.myTask",
+  run: async () => {
+    return "Hello World!";
+  },
+});
+
+const app = resource({
+  id: "app",
+  register: [myTask],
+});
+```
+
+Then your tests can now be cleaner:
+
+```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
+      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);
+  });
+});
+```
+
+## Support
 
-For feedback or suggestions, please use our [feedback form](https://forms.gle/DTMg5Urgqey9QqLFA).
+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).
 
 ## License
 

package/dist/DependencyProcessor.d.ts

@@ -29,13 +29,13 @@ export declare class DependencyProcessor {
      * Processes all hooks, should run before emission of any event.
      * @returns
      */
-    processHooks(): void;
+    attachHooks(): void;
     /**
      * Processes the hooks for resources
      * @param hooks
      * @param deps
      */
-    processHooksForResource(resourceStoreElement: ResourceStoreElementType<any, any, {}>): void;
+    attachHooksToResource(resourceStoreElement: ResourceStoreElementType<any, any, {}>): void;
     extractDependencies<T extends DependencyMapType>(map: T): Promise<DependencyValuesType<T>>;
     extractDependency(object: any): Promise<any>;
     /**

package/dist/DependencyProcessor.js

@@ -76,11 +76,11 @@ class DependencyProcessor {
      * Processes all hooks, should run before emission of any event.
      * @returns
      */
-    processHooks() {
+    attachHooks() {
         // iterate through resources and send them to processHooks
         for (const resource of this.store.resources.values()) {
             if (resource.resource.hooks) {
-                this.processHooksForResource(resource);
+                this.attachHooksToResource(resource);
             }
         }
     }
@@ -89,7 +89,7 @@ class DependencyProcessor {
      * @param hooks
      * @param deps
      */
-    processHooksForResource(resourceStoreElement) {
+    attachHooksToResource(resourceStoreElement) {
         let hooks = resourceStoreElement.resource.hooks;
         if (typeof hooks === "function") {
             hooks = hooks(resourceStoreElement.config);