mesh-ioc 1.3.0 → 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
@@ -57,25 +57,6 @@ class User {
 
 const user = mesh.connect(new User());  // now user.db will also be resolved by Mesh
 
-// Scopes:
-
-// Declare scoped bindings
-mesh.scope('request')
-    .service(UsersRouter)
-    .service(OrdersRouter);
-
-// Create and use scope
-const request = mesh.createScope('request')
-    // Bind scope-specific data
-    .constant(Request, req)
-    .constant(Response, res);
-
-// Scoped services can use scope-specific data
-class UsersRouter {
-    @dep() req!: Request;
-    @dep() res!: Response;
-}
-
 // Middleware:
 mesh.use(instance => {
     // Allows modifying instances as they are created or connected
@@ -161,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`.
 
@@ -186,110 +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 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!
+**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 all components are loosely coupled, dependencies are easy to reason about and are not mixed with the actual data arguments.
-
-1. Identify the layers of your application. Oftentimes different components have different lifespans or, as we tend to refer to it, scopes:
-
-  - **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)
-
-2. Build the mesh hierarchy, starting from application scope, descending into more granular scopes.
-
-    ```ts
-    // app.ts
-    export class App {
-        // You can either inherit from Mesh or store it as a field.
-        // Name parameter is optional, but can be useful for debugging.
-        mesh: Mesh;
-
-        constructor() {
-            this.mesh = new Mesh('App')
-                // Define your application-scoped services
-                .constant(App, this)
-                .service(Logger, GlobalLogger);
-                .service(MyDatabase);
-                .service(MyServer);
-                // Define your session-scoped services
-                .scope('session')
-                .service(Logger, SessionLogger)
-                .service(SessionScopedService);
-        }
-
-        start() {
-            // Define logic for application startup
-            // (e.g. connect to databases, start listening to servers, etc)
-            this.mesh.resolve(MyServer).listen();
-        }
-
-        startSession(req: Request, res: Response) {
-            // Bind session-specific data (e.g. request, response, client web socket, session id, etc)
-            const sessionMesh = this.mesh.createScope('session')
-                // Session-specific data can be bound by session-scoped services
-                .constant(Request, req)
-                .constant(Response, res);
-            // Define logic for session initialisation
-            sessionMesh.resolve(SessionScopedService).doStuff();
-        }
+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);
+        // ...
     }
-    ```
 
-3. Create an application entrypoint (advice: never mix modules that export classes with entrypoint modules!):
+    async start() {
+        // Define logic for application startup, e.g.
+        await this.mesh.resolve(MyDatabase).connect();
+        await this.mesh.resolve(MyHttpServer).listen();
+        // ...
+    }
 
-    ```ts
-    // bin/run.ts
+    async stop() {
+        // Define logic for application shutdown, e.g.
+        await this.mesh.resolve(MyHttpServer).close();
+        await this.mesh.resolve(MyDatabase).close();
+        // ...
+    }
 
-    const app = new App();
-    app.start();
-    ```
+}
+```
 
-4. Identify the proper component for session entrypoint:
+The entrypoint would be an actual "main" function that instantiates the `App` class and calls its `start` method:
 
-    ```ts
-    export class MyServer {
-        @dep() app!: App;
+```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';
 
-        // The actual server (e.g. http server or web socket server)
-        server: Server;
+let app: TestApp;
 
-        constructor() {
-            this.server = new Server((req, res) => {
-                // This is the actual entrypoint of Session
-                app.startSession(req, res);
-            });
-        }
+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.
 
-5. Use `@dep()` to transparently inject dependencies in your services:
+### Creating request/response scopes
 
-    ```ts
-    export class SessionScopedService {
+Mesh IoC opts for maximum simplicity by following a straighforward model: each mesh instance is a scope.
 
-        @dep() database!: Database;
-        @dep() req!: Request;
-        @dep() res!: Response;
+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.
+
+```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());
     }
-    ```
 
-6. Come up with conventions and document them, for example:
+    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;
+    }
 
-  - create different directories for services with different scopes
-  - separate entrypoints from the rest of the modules
-    - entrypoints only import, instantiate and invoke methods (think "runnable from CLI")
-    - all other modules only export stuff
+}
+```
+
+Then in `MyServer`:
 
-You can take those further and adapt to your own needs. Meshes are composable and the underlying mechanics are quite simple. Start using it and you'll get a better understanding of how to adapt it to the needs of your particular case.
+```ts
+export class MyServer {
 
-## Advanced
+    @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
 
@@ -330,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/index.d.ts

@@ -1,5 +1,4 @@
 export * from './decorators/dep';
 export * from './errors';
 export * from './mesh';
-export * from './scope';
 export * from './types';

package/out/main/index.js

@@ -13,5 +13,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./decorators/dep"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./mesh"), exports);
-__exportStar(require("./scope"), exports);
 __exportStar(require("./types"), exports);

package/out/main/mesh.d.ts

@@ -1,24 +1,33 @@
-import { Scope } from './scope';
 import { AbstractClass, Binding, Middleware, ServiceConstructor, ServiceKey } from './types';
 export declare const MESH_REF: unique symbol;
+/**
+ * An IoC container.
+ *
+ * Encapsulates bindings — a map that allows to associate a _service key_ with a way to obtain an instance.
+ *
+ * Three binding types are supported via corresponding methods:
+ *
+ * - `service` — a zero-arg constructor mapping; these will be instantiated on demand and cached in this mesh
+ * - `constant` — an instance of a class (can be bound by using class as service name) or an arbitrary value bound by a string key
+ * - `alias` — a "redirect" mapping, useful in tests
+ */
 export declare class Mesh {
     name: string;
     parent: Mesh | undefined;
-    currentScope: Scope;
-    childScopes: Map<string, Scope>;
+    bindings: Map<string, Binding<any>>;
     instances: Map<string, any>;
     middlewares: Middleware[];
-    constructor(name?: string, parent?: Mesh | undefined, scope?: Scope);
+    constructor(name?: string, parent?: Mesh | undefined);
+    [Symbol.iterator](): Generator<[string, Binding<any>], void, undefined>;
+    clone(): Mesh;
     service<T>(impl: ServiceConstructor<T>): this;
     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;
-    scope(scopeId: string): Scope;
-    createScope(scopeId: string, scopeName?: string): Mesh;
     protected instantiate<T>(binding: Binding<T>): T;
     protected applyMiddleware<T>(value: T): T;
     protected injectRef(value: any): void;

package/out/main/mesh.js

@@ -2,53 +2,82 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Mesh = exports.MESH_REF = void 0;
 const errors_1 = require("./errors");
-const scope_1 = require("./scope");
 const util_1 = require("./util");
 exports.MESH_REF = Symbol.for('MESH_REF');
+/**
+ * An IoC container.
+ *
+ * Encapsulates bindings — a map that allows to associate a _service key_ with a way to obtain an instance.
+ *
+ * Three binding types are supported via corresponding methods:
+ *
+ * - `service` — a zero-arg constructor mapping; these will be instantiated on demand and cached in this mesh
+ * - `constant` — an instance of a class (can be bound by using class as service name) or an arbitrary value bound by a string key
+ * - `alias` — a "redirect" mapping, useful in tests
+ */
 class Mesh {
-    constructor(name = 'default', parent = undefined, scope) {
+    constructor(name = 'default', parent = undefined) {
         this.name = name;
         this.parent = parent;
-        this.childScopes = new Map();
+        this.bindings = new Map();
         this.instances = new Map();
         this.middlewares = [];
-        this.currentScope = scope !== null && scope !== void 0 ? scope : new scope_1.Scope(name);
-        this.currentScope.constant('Mesh', this);
+        this.constant(Mesh, this);
+    }
+    *[Symbol.iterator]() {
+        yield* this.bindings.entries();
+    }
+    clone() {
+        const clone = new Mesh();
+        clone.parent = this.parent;
+        clone.bindings = new Map(this.bindings);
+        return clone;
     }
     service(key, impl) {
-        this.currentScope.service(key, impl);
-        return this;
+        const k = util_1.keyToString(key);
+        if (typeof impl === 'function') {
+            this.bindings.set(k, { type: 'service', class: impl });
+            return this;
+        }
+        else if (typeof key === 'function') {
+            this.bindings.set(k, { type: 'service', class: key });
+            return this;
+        }
+        throw new errors_1.MeshInvalidBinding(String(key));
     }
     constant(key, value) {
-        this.currentScope.constant(key, value);
+        const k = util_1.keyToString(key);
+        this.bindings.set(k, { type: 'constant', value });
         return this;
     }
     alias(key, referenceKey) {
-        this.currentScope.alias(key, referenceKey);
+        const k = util_1.keyToString(key);
+        const refK = util_1.keyToString(referenceKey);
+        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) {
             return instance;
         }
-        const binding = this.currentScope.bindings.get(k);
+        const binding = this.bindings.get(k);
         if (binding) {
             instance = this.instantiate(binding);
             instance = this.connect(instance);
             this.instances.set(k, instance);
             return instance;
         }
-        if (this.parent) {
+        if (recursive && this.parent) {
             return this.parent.tryResolve(key);
         }
         return undefined;
@@ -62,20 +91,6 @@ class Mesh {
         this.middlewares.push(fn);
         return this;
     }
-    scope(scopeId) {
-        let scope = this.childScopes.get(scopeId);
-        if (!scope) {
-            scope = new scope_1.Scope(scopeId);
-            this.childScopes.set(scopeId, scope);
-        }
-        return scope;
-    }
-    createScope(scopeId, scopeName = scopeId) {
-        const childScope = this.childScopes.get(scopeId);
-        const newScope = new scope_1.Scope(scopeName, childScope !== null && childScope !== void 0 ? childScope : []);
-        const mesh = new Mesh(scopeId, this, newScope);
-        return mesh;
-    }
     instantiate(binding) {
         switch (binding.type) {
             case 'alias':

package/package.json

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

package/out/main/decorators/service.d.ts

@@ -1,7 +0,0 @@
-import { ServiceMetadata } from '../types';
-export declare const serviceMetadata: ServiceMetadata[];
-export interface SvcOptions {
-    alias?: string;
-    metadata?: any;
-}
-export declare function service(options?: SvcOptions): (target: any) => void;

package/out/main/decorators/service.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.service = exports.serviceMetadata = void 0;
-exports.serviceMetadata = [];
-function service(options = {}) {
-    return function (target) {
-        exports.serviceMetadata.push(Object.assign({ class: target }, options));
-    };
-}
-exports.service = service;