mesh-ioc 2.0.1 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Powerful and lightweight alternative to Dependency Injection (DI) solutions like [Inversify](https://inversify.io/).
 
-Mesh IoC solves the problem of dependency management of application services. It wires together application services (i.e. singletons instantiated once and scoped to an entire application) and contextual services (e.g. services scoped to a particular HTTP request, WebSocket connection, etc.)
+Mesh IoC solves the problem of dependency management of application services. It wires application services togethert (i.e. singletons instantiated once and scoped to an entire application) and contextual services (e.g. services scoped to a particular HTTP request, WebSocket connection, etc.)
 
 ## Key features
 
@@ -13,7 +13,7 @@ Mesh IoC solves the problem of dependency management of application services. It
 - 🐓 🥚 Tolerates circular dependencies
 - 🕵️‍♀️ Provides APIs for dependency analysis
 
-## Quick API Cheatsheet
+## API Cheatsheet
 
 ```ts
 // Mesh is an IoC container that stores service bindings and instantiated objects
@@ -142,16 +142,20 @@ class Redis {
 
 // app.ts
 
-class AppMesh extends Mesh {
-    // List all services so that mesh connects them together
-    this.service(Redis);
-    this.service(Logger, ConsoleLogger);
+class App {
+    mesh = new Mesh('App'); // Optional string identifier helps with debugging resolution problems
+
+    constructor() {
+        // List all services so that mesh connects them together
+        this.mesh.service(Redis);
+        this.mesh.service(Logger, ConsoleLogger);
+    }
 }
 ```
 
 There are several aspects that differentiate Mesh IoC from the rest of the DI libraries.
 
-  - Mesh is used only for services, so service instances are cached in mesh. If you only have a single mesh instance, the services will effectively be singletons. However, if multiple mesh instances are created, then each mesh will track its own service instances.
+  - Service instances are cached in mesh. If you only have a single mesh instance, the services will effectively be singletons. However, if multiple mesh instances are created, then each mesh will track its own service instances.
 
     - If you're familiar with Inversify, this effectively makes all bindings `inSingletonScope`.
 
@@ -167,11 +171,176 @@ There are several aspects that differentiate Mesh IoC from the rest of the DI li
 
   - Mesh can handle circular dependencies, all thanks to on-demand resolution. However, due to how Node.js module loading works, `@dep` will be unable to infer _one_ of the service keys (depending on which module happened to load first). It's a good practice to use explicit service keys on both sides of circular dependencies.
 
-  - Constant values can be bound to mesh. Those could be instances of other classes.
+  - Constant values can be bound to mesh. Those could be instances of other classes or just arbitrary values bound by string keys.
+
+**Important!** Mesh should be used to track _services_. We define services as classes with **zero-argument constructors** (this is also enforced by TypeScript). However, there are multiple patterns to support constructor arguments, read on!
+
+## Application Architecture Guide
+
+This short guide briefly explains the basic concepts of a good application architecture where the components are loosely coupled, dependencies are easy to reason about and are not mixed with the actual data arguments.
+
+### Scopes
+
+Oftentimes different application components have different lifespans or scopes.
+
+For example:
+
+- **Application scope**: things like database connection pools, servers and other global components are scoped to entire application; their instances are effectively singletons (i.e. you don't want to establish a new database connection each time you query it).
+
+- **Request/session scope**: things like traditional HTTP routers will depend on request and response objects; the same reasoning can be applied to other scenarios, for example, web socket server may need functionality per each connected client — such components will depend on client socket.
+
+- **Short-lived per-instance scope**: if you use "fat" classes (e.g. Active Record pattern) then each entity instances should be conceptually "connected" to the rest of the application (e.g. `instance.save()` should somehow know about the database).
+
+In the following sections we'll explore the best practices to organise the application components and to achieve a clear demarcation of scopes.
+
+### Composition Root and Entrypoint
+
+The term "app" is often very ambiguous when it comes to module organisation. For example, most http backend frameworks consider an "app" to be component responsible for routing and listening to HTTP requests, whereas most frontend frameworks would consider an "app" to be the root component with some setup.
+
+It is also a common practice to mix the "app" with the actual entrypoint, i.e. the app module would be an equivalent of the "main" function that gets executed as soon as the script is parsed. This later results in problems with unit testing (i.e. the test runtime cannot use the "app" part separately from the "entrypoint" which typically results in the decisions like "unit test applications by sending HTTP requests to them").
+
+With IoC the "app" term gets a well-defined meaning: `App` is a composition root, a "centralized registry" of application-scoped components.
+
+For application scope one must make sure that only a single `mesh` instance is maintained throughout a lifecycle:
+
+```ts
+// src/main/app.ts
+export class App {
+    mesh = new Mesh('App');
+
+    constuctor() {
+        // Add application-scoped (singleton) bindings, e.g.
+        this.mesh.service(Logger, GlobalLogger);
+        this.mesh.service(MyDatabase);
+        this.mesh.service(MyHttpServer);
+        // ...
+    }
+
+    async start() {
+        // Define logic for application startup, e.g.
+        await this.mesh.resolve(MyDatabase).connect();
+        await this.mesh.resolve(MyHttpServer).listen();
+        // ...
+    }
+
+    async stop() {
+        // Define logic for application shutdown, e.g.
+        await this.mesh.resolve(MyHttpServer).close();
+        await this.mesh.resolve(MyDatabase).close();
+        // ...
+    }
+
+}
+```
+
+The entrypoint would be an actual "main" function that instantiates the `App` class and calls its `start` method:
+
+```ts
+// src/bin/serve.ts
+import { App } from '../main/app.js';
+
+const app = new App();
+app.start()
+    .catch(err => {
+        // Setup app initialization error handling
+        process.exit(1);
+    });
+```
+
+### Test runtime setup
+
+Test runtime can create a fresh `App` instance on every test case, e.g.:
+
+```ts
+// src/test/runtime.ts
+import { App } from '../main/app.js';
+
+let app: TestApp;
+
+beforeEach(() => {
+    app = new TestApp();
+});
+
+export class TestApp extends App {
+
+    constructor() {
+        super();
+        // Setup test application
+        // e.g. one can substitute real components with mocks
+        this.mesh.service(ThirdPartyServiceMock);
+        this.mesh.alias(ThirdPartyService, ThirdPartyServiceMock);
+        // ...
+    }
+}
+```
+
+Each test would then be able to access `app` and re-bind any of the dependencies without affecting other test cases.
+
+### Creating request/response scopes
+
+Mesh IoC opts for maximum simplicity by following a straighforward model: each mesh instance is a scope.
+
+Therefore, to create a scope, say, per HTTP request we need to simply create a mesh instance inside the HTTP handler. It's also a good idea to keep the logic of creating HTTP-scoped mesh inside the composition root, so that it can be overridden in tests.
 
-**Important!** Mesh should be used to track _services_. We defined services as classes with **zero-argument constructors** (this is also enforced by TypeScript). However, there are multiple patterns to support constructor arguments, read on!
+```ts
+// src/main/app.ts
+
+export class App {
+    mesh = new Mesh('App');
+
+    constructor() {
+        // ...
+        this.mesh.service(MyServer);
+        // Bind the function that creates a scoped mesh, so that the server could use it.
+        this.mesh.constant('createRequestScope', (req: Request, res: Response) => this.createRequestScope());
+    }
 
-## Advanced
+    protected createRequestScope(req: Request, res: Response) {
+        const mesh = new Mesh('Request');
+        // Allow request-scoped classes to also resolve app-scoped dependencies
+        mesh.parent = this.mesh;
+        // Scoped variables (req, res) can be bound as constants
+        mesh.constant(Request, req);
+        mesh.constant(Response, res);
+        // Create request-scoped bindings
+        mesh.service(Router, MyRouter);
+        // ...
+        return mesh;
+    }
+
+}
+```
+
+Then in `MyServer`:
+
+```ts
+export class MyServer {
+
+    @dep({ key: 'createRequestScope' }) createRequestScope!: (req: Request, res: Response) => Mesh;
+
+    handleRequest(req: Request, res: Response) {
+        // This is an "entrypoint" of request scope
+        const mesh = this.createRequestScope(req, res);
+        // For example, let's delegate request handling to the Router
+        const router = mesh.resolve(Router);
+        router.handle();
+    }
+}
+```
+
+In our example, `Router` is a request-scoped class and thus can access `req` and `res`:
+
+```ts
+export class MyRouter extends Router {
+
+    @dep() req!: Request;
+    @dep() res!: Response;
+
+    async handle() {
+        // ...
+    }
+}
+```
 
 ### Connecting "guest" instances
 
@@ -212,6 +381,14 @@ class UserService {
 
 Note: the important limitation of this approach is that `@dep` are not available in entity constructors (e.g. `database` cannot be resolved in `User` constructor, because by the time the instance is instantiated it's not yet connected to the mesh).
 
+## Tips and tricks
+
+- Use classes as service keys whenever possible, this adds an additional compile-time type check to ensure that the implementation matches the declaration.
+
+- TypeScript `interface` cannot be a service key, because it does not exist at runtime. Use `abstract class` instead.
+
+- Don't be too dogmatic about interface/implementation split. For example, if all class methods are its public interface, there is no point in splitting it into an "interface" and its single implementation (e.g. ` abstract Config` and `ConfigImpl`) — this provides close to zero practical value and contributes towards people disliking the OOP paradigm for its verbosity and cargo culting. Instead just bind the concrete class to itself.
+
 ## License
 
 [ISC](https://en.wikipedia.org/wiki/ISC_license) © Boris Okunskiy

package/out/main/mesh.d.ts

@@ -24,8 +24,8 @@ export declare class Mesh {
     service<T>(key: AbstractClass<T> | string, impl: ServiceConstructor<T>): this;
     constant<T>(key: ServiceKey<T>, value: T): this;
     alias<T>(key: AbstractClass<T> | string, referenceKey: AbstractClass<T> | string): this;
-    resolve<T>(key: ServiceKey<T>): T;
-    tryResolve<T>(key: ServiceKey<T>): T | undefined;
+    resolve<T>(key: ServiceKey<T>, recursive?: boolean): T;
+    tryResolve<T>(key: ServiceKey<T>, recursive?: boolean): T | undefined;
     connect<T>(value: T): T;
     use(fn: Middleware): this;
     protected instantiate<T>(binding: Binding<T>): T;

package/out/main/mesh.js

@@ -56,15 +56,15 @@ class Mesh {
         this.bindings.set(k, { type: 'alias', key: refK });
         return this;
     }
-    resolve(key) {
-        const instance = this.tryResolve(key);
+    resolve(key, recursive = true) {
+        const instance = this.tryResolve(key, recursive);
         if (instance === undefined) {
             const k = util_1.keyToString(key);
             throw new errors_1.MeshBindingNotFound(this.name, k);
         }
         return instance;
     }
-    tryResolve(key) {
+    tryResolve(key, recursive = true) {
         const k = util_1.keyToString(key);
         let instance = this.instances.get(k);
         if (instance) {
@@ -77,7 +77,7 @@ class Mesh {
             this.instances.set(k, instance);
             return instance;
         }
-        if (this.parent) {
+        if (recursive && this.parent) {
             return this.parent.tryResolve(key);
         }
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mesh-ioc",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "description": "Mesh: Powerful and Lightweight IoC Library",
     "main": "out/main/index.js",
     "types": "out/main/index.d.ts",