mesh-ioc 0.1.2 → 1.0.0

package/README.md

@@ -13,6 +13,78 @@ Mesh IoC solves the problem of dependency management of application services. It
 - 🐓 🥚 Tolerates circular dependencies
 - 🕵️‍♀️ Provides APIs for dependency analysis
 
+## Quick API Cheatsheet
+
+```ts
+// Mesh is an IoC container that stores service bindings and instantiated objects
+const mesh = new Mesh('someName');
+
+// Bindings:
+
+// 1. Service (zero-arg constructor) to itself
+mesh.service(SomeDatabase);
+// 2. Abstract class to service implementation
+mesh.service(Logger, SomeLogger);
+// 3. String key to service (👎 because of limited type support)
+mesh.service('Something', Something);
+// 4. Service to instance
+mesh.constant(SomeService, someServiceInstance);
+// 5. String key to arbitrary constant
+mesh.constant('SessionId', 42);
+// 6. Alias (key to another key)
+mesh.alias('DB', SomeDatabase);
+
+// Methods can also be chained
+mesh.service(MyFoo)
+    .alias(Foo, MyFoo)
+    .constant('Secret', 'supersecret');
+
+// Declarative bindings in services:
+
+class SomeDatabase {
+    @dep() logger!: Logger; // auto-resolved by Mesh
+}
+
+// Manual resolution:
+
+const db = mesh.resolve(SomeDatabase);
+
+// Connect instances:
+
+class User {
+    @dep() db!: MyDatabase;
+}
+
+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
+    // (useful for logging, stats or replacing instances with proxies)
+    console.log('Instantiated', instance);
+    return instance;
+});
+```
+
 ## IoC Recap
 
 [IoC](https://en.wikipedia.org/wiki/Inversion_of_control) when applied to class dependency management states that each component should not resolve their dependencies — instead the dependencies should be provided to each component.
@@ -80,15 +152,19 @@ class Redis {
 
     constructor() {
         this.redis = new RedisClient(/* ... */);
-        this.redis.on('connect', () => this.logger.log('Connected to Redis'));
+        this.redis.on('connect', () => {
+            // Logger can now be used by this class transparently
+            this.logger.log('Connected to Redis');
+        });
     }
 }
 
 // app.ts
 
 class AppMesh extends Mesh {
-    this.bind(Logger, ConsoleLogger);
-    this.bind(Redis);
+    // List all services so that mesh connects them together
+    this.service(Redis);
+    this.service(Logger, ConsoleLogger);
 }
 ```
 
@@ -111,3 +187,149 @@ 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.
+
+**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!
+
+## 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();
+        }
+    }
+    ```
+
+3. Create an application entrypoint (advice: never mix modules that export classes with entrypoint modules!):
+
+    ```ts
+    // bin/run.ts
+
+    const app = new App();
+    app.start();
+    ```
+
+4. Identify the proper component for session entrypoint:
+
+    ```ts
+    export class MyServer {
+        @dep() app!: App;
+
+        // The actual server (e.g. http server or web socket server)
+        server: Server;
+
+        constructor() {
+            this.server = new Server((req, res) => {
+                // This is the actual entrypoint of Session
+                app.startSession(req, res);
+            });
+        }
+    }
+    ```
+
+5. Use `@dep()` to transparently inject dependencies in your services:
+
+    ```ts
+    export class SessionScopedService {
+
+        @dep() database!: Database;
+        @dep() req!: Request;
+        @dep() res!: Response;
+
+        // ...
+    }
+    ```
+
+6. Come up with conventions and document them, for example:
+
+  - 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
+
+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.
+
+## Advanced
+
+### Connecting "guest" instances
+
+Mesh IoC allows connecting an arbitrary instance to the mesh, so that the `@dep` can be used in it.
+
+For example:
+
+```ts
+// This entity class is not managed by Mesh directly, instead it's instantiated by UserService
+class User {
+    @dep() database!: Database;
+
+    // Note: constructor can have arbitrary arguments in this case,
+    // because the instantiation isn't controlled by Mesh
+    constructor(
+        public firstName = '',
+        public lastName = '',
+        public email = '',
+        // ...
+    ) {}
+
+    async save() {
+        await this.database.save(this);
+    }
+}
+
+class UserService {
+    // Note: Mesh is automatically available in all connected services
+    @dep() mesh!: Mesh;
+
+    createUser(firstName = '', lastName = '', email = '', /*...*/) {
+        const user = new User();
+        // Now connect it to mesh, so that User can access its services via `@dep`
+        return this.mesh.connect(user);
+    }
+}
+```
+
+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).
+
+## License
+
+[ISC](https://en.wikipedia.org/wiki/ISC_license) © Boris Okunskiy

package/out/main/bindings.d.ts

@@ -1,24 +1,14 @@
-import { Mesh } from './mesh';
 import { ServiceConstructor } from './types';
-export declare abstract class Binding<T> {
-    readonly mesh: Mesh;
-    readonly key: string;
-    constructor(mesh: Mesh, key: string);
-    abstract get(): T;
-}
-export declare class ConstantBinding<T> extends Binding<T> {
+export declare type Binding<T> = ConstantBinding<T> | ServiceBinding<T> | AliasBinding;
+export declare type ConstantBinding<T> = {
+    type: 'constant';
     value: T;
-    constructor(mesh: Mesh, key: string, value: T);
-    get(): T;
-}
-export declare class ServiceBinding<T> extends Binding<T> {
-    readonly ctor: ServiceConstructor<T>;
-    instance: T | undefined;
-    constructor(mesh: Mesh, key: string, ctor: ServiceConstructor<T>);
-    get(): T;
-}
-export declare class ProxyBinding<T> extends Binding<T> {
-    readonly alias: string;
-    constructor(mesh: Mesh, key: string, alias: string);
-    get(): T;
-}
+};
+export declare type ServiceBinding<T> = {
+    type: 'service';
+    class: ServiceConstructor<T>;
+};
+export declare type AliasBinding = {
+    type: 'alias';
+    key: string;
+};

package/out/main/bindings.js

@@ -1,45 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProxyBinding = exports.ServiceBinding = exports.ConstantBinding = exports.Binding = void 0;
-class Binding {
-    constructor(mesh, key) {
-        this.mesh = mesh;
-        this.key = key;
-    }
-}
-exports.Binding = Binding;
-class ConstantBinding extends Binding {
-    constructor(mesh, key, value) {
-        super(mesh, key);
-        this.value = value;
-        this.mesh.connect(this.value);
-    }
-    get() {
-        return this.value;
-    }
-}
-exports.ConstantBinding = ConstantBinding;
-class ServiceBinding extends Binding {
-    constructor(mesh, key, ctor) {
-        super(mesh, key);
-        this.ctor = ctor;
-    }
-    get() {
-        if (!this.instance) {
-            this.instance = new this.ctor();
-            this.mesh.connect(this.instance);
-        }
-        return this.instance;
-    }
-}
-exports.ServiceBinding = ServiceBinding;
-class ProxyBinding extends Binding {
-    constructor(mesh, key, alias) {
-        super(mesh, key);
-        this.alias = alias;
-    }
-    get() {
-        return this.mesh.resolve(this.alias);
-    }
-}
-exports.ProxyBinding = ProxyBinding;

package/out/main/errors.d.ts

@@ -11,10 +11,10 @@ export declare class DepInstanceNotConnected extends BaseError {
     propertyName: string;
     constructor(className: string, propertyName: string);
 }
-export declare class MeshServiceNotFound extends BaseError {
+export declare class MeshBindingNotFound extends BaseError {
     constructor(meshName: string, serviceKey: string);
 }
-export declare class MeshInvalidServiceBinding extends BaseError {
+export declare class MeshInvalidBinding extends BaseError {
     constructor(key: string);
 }
 export {};

package/out/main/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MeshInvalidServiceBinding = exports.MeshServiceNotFound = exports.DepInstanceNotConnected = exports.DepKeyNotInferred = void 0;
+exports.MeshInvalidBinding = exports.MeshBindingNotFound = exports.DepInstanceNotConnected = exports.DepKeyNotInferred = void 0;
 class BaseError extends Error {
     constructor() {
         super(...arguments);
@@ -26,18 +26,18 @@ class DepInstanceNotConnected extends BaseError {
     }
 }
 exports.DepInstanceNotConnected = DepInstanceNotConnected;
-class MeshServiceNotFound extends BaseError {
+class MeshBindingNotFound extends BaseError {
     constructor(meshName, serviceKey) {
-        super(`Service "${serviceKey}" not found in Mesh "${meshName}"`);
+        super(`"${serviceKey}" not found in Mesh "${meshName}"`);
     }
 }
-exports.MeshServiceNotFound = MeshServiceNotFound;
-class MeshInvalidServiceBinding extends BaseError {
+exports.MeshBindingNotFound = MeshBindingNotFound;
+class MeshInvalidBinding extends BaseError {
     constructor(key) {
-        super(`Invalid service binding "${key}". Valid bindings are: ` +
+        super(`Invalid binding "${key}". Valid bindings are: ` +
             `string to constructor e.g. ("MyService", MyService) or ` +
             `abstract class to constructor e.g. (MyService, MyServiceImpl) or` +
             `constructor to self e.g. (MyService)`);
     }
 }
-exports.MeshInvalidServiceBinding = MeshInvalidServiceBinding;
+exports.MeshInvalidBinding = MeshInvalidBinding;

package/out/main/mesh.d.ts

@@ -1,19 +1,25 @@
 import { Binding } from './bindings';
-import { AbstractService, ServiceConstructor } from './types';
+import { Scope } from './scope';
+import { AbstractClass, Middleware, ServiceConstructor, ServiceKey } from './types';
 export declare const MESH_REF: unique symbol;
-export declare type ServiceKey<T> = ServiceConstructor<T> | AbstractService<T> | string;
 export declare class Mesh {
     name: string;
     parent: Mesh | undefined;
-    bindings: Map<string, Binding<any>>;
+    currentScope: Scope;
+    childScopes: Map<string, Scope>;
+    instances: Map<string, any>;
+    middlewares: Middleware[];
     constructor(name?: string, parent?: Mesh | undefined);
-    bind<T>(impl: ServiceConstructor<T>): Binding<T>;
-    bind<T>(key: AbstractService<T> | string, impl: ServiceConstructor<T>): Binding<T>;
-    constant<T>(key: ServiceKey<T>, value: T): Binding<T>;
-    alias<T>(key: AbstractService<T> | string, referenceKey: AbstractService<T> | string): Binding<T>;
+    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;
-    connect(value: any): void;
-    protected _bindService<T>(key: string, impl: ServiceConstructor<T>): Binding<T>;
-    protected _add<T>(binding: Binding<any>): Binding<T>;
-    protected _addMeshRef(value: any): void;
+    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

@@ -1,58 +1,103 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Mesh = exports.MESH_REF = void 0;
-const bindings_1 = require("./bindings");
 const errors_1 = require("./errors");
+const scope_1 = require("./scope");
+const util_1 = require("./util");
 exports.MESH_REF = Symbol.for('MESH_REF');
 class Mesh {
     constructor(name = 'default', parent = undefined) {
         this.name = name;
         this.parent = parent;
-        this.bindings = new Map();
-        this.constant('Mesh', this);
+        this.childScopes = new Map();
+        this.instances = new Map();
+        this.middlewares = [];
+        this.currentScope = new scope_1.Scope(name);
+        this.currentScope.constant('Mesh', this);
     }
-    bind(key, impl) {
-        const k = keyToString(key);
-        if (typeof impl === 'function') {
-            return this._bindService(k, impl);
-        }
-        else if (typeof key === 'function') {
-            return this._bindService(k, key);
-        }
-        throw new errors_1.MeshInvalidServiceBinding(String(key));
+    service(key, impl) {
+        this.currentScope.service(key, impl);
+        return this;
     }
     constant(key, value) {
-        const k = keyToString(key);
-        return this._add(new bindings_1.ConstantBinding(this, k, value));
+        this.currentScope.constant(key, value);
+        return this;
     }
     alias(key, referenceKey) {
-        const k = keyToString(key);
-        const refK = typeof referenceKey === 'string' ? referenceKey : referenceKey.name;
-        return this._add(new bindings_1.ProxyBinding(this, k, refK));
+        this.currentScope.alias(key, referenceKey);
+        return this;
     }
     resolve(key) {
-        const k = keyToString(key);
-        const binding = this.bindings.get(k);
+        const k = util_1.keyToString(key);
+        let instance = this.instances.get(k);
+        if (instance) {
+            return instance;
+        }
+        const binding = this.currentScope.bindings.get(k);
         if (binding) {
-            return binding.get();
+            instance = this.instantiate(binding);
+            instance = this.connect(instance);
+            this.instances.set(k, instance);
+            return instance;
         }
         if (this.parent) {
             return this.parent.resolve(key);
         }
-        throw new errors_1.MeshServiceNotFound(this.name, k);
+        throw new errors_1.MeshBindingNotFound(this.name, k);
     }
     connect(value) {
-        // TODO apply middlewares
-        this._addMeshRef(value);
+        const res = this.applyMiddleware(value);
+        this.injectRef(res);
+        return res;
+    }
+    use(fn) {
+        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;
     }
-    _bindService(key, impl) {
-        return this._add(new bindings_1.ServiceBinding(this, key, impl));
+    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);
+        mesh.currentScope = newScope;
+        return mesh;
     }
-    _add(binding) {
-        this.bindings.set(binding.key, binding);
-        return new bindings_1.ProxyBinding(this, binding.key, binding.key);
+    instantiate(binding) {
+        switch (binding.type) {
+            case 'alias':
+                return this.resolve(binding.key);
+            case 'service': {
+                // A fake derived class is created with Mesh attached to its prototype.
+                // This allows accessing deps in constructor whilst preserving instanceof.
+                const ctor = binding.class;
+                const derived = class extends ctor {
+                };
+                Object.defineProperty(derived, 'name', { value: ctor.name });
+                this.injectRef(derived.prototype);
+                return new derived();
+            }
+            case 'constant':
+                return binding.value;
+        }
+    }
+    applyMiddleware(value) {
+        let res = value;
+        for (const middleware of this.middlewares) {
+            res = middleware(res);
+        }
+        if (this.parent) {
+            res = this.parent.applyMiddleware(res);
+        }
+        return res;
     }
-    _addMeshRef(value) {
+    injectRef(value) {
         if (typeof value !== 'object') {
             return;
         }
@@ -64,6 +109,3 @@ class Mesh {
     }
 }
 exports.Mesh = Mesh;
-function keyToString(key) {
-    return typeof key === 'string' ? key : key.name;
-}

package/out/main/scope.d.ts

@@ -0,0 +1,13 @@
+import { Binding } from './bindings';
+import { AbstractClass, ServiceConstructor, ServiceKey } from './types';
+export declare const MESH_REF: unique symbol;
+export declare class Scope {
+    readonly name: string;
+    bindings: Map<string, Binding<any>>;
+    constructor(name: string, bindings?: Iterable<[string, Binding<any>]>);
+    [Symbol.iterator](): Generator<[string, Binding<any>], void, undefined>;
+    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;
+}

package/out/main/scope.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scope = exports.MESH_REF = void 0;
+const errors_1 = require("./errors");
+const util_1 = require("./util");
+exports.MESH_REF = Symbol.for('MESH_REF');
+class Scope {
+    constructor(name, bindings = []) {
+        this.name = name;
+        this.bindings = new Map();
+        for (const [k, v] of bindings) {
+            this.bindings.set(k, v);
+        }
+    }
+    *[Symbol.iterator]() {
+        yield* this.bindings.entries();
+    }
+    service(key, impl) {
+        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) {
+        const k = util_1.keyToString(key);
+        this.bindings.set(k, { type: 'constant', value });
+        return this;
+    }
+    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;
+    }
+}
+exports.Scope = Scope;

package/out/main/types.d.ts

@@ -4,7 +4,9 @@ export declare type Constructor<T> = {
 export declare type ServiceConstructor<T> = {
     new (): T;
 };
-export declare type AbstractService<T> = {
+export declare type AbstractClass<T> = {
     name: string;
     prototype: T;
 };
+export declare type ServiceKey<T> = ServiceConstructor<T> | AbstractClass<T> | string;
+export declare type Middleware = (instance: any) => any;

package/out/main/util.d.ts

@@ -0,0 +1,2 @@
+import { ServiceKey } from './types';
+export declare function keyToString<T>(key: ServiceKey<T>): string;

package/out/main/util.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyToString = void 0;
+function keyToString(key) {
+    return typeof key === 'string' ? key : key.name;
+}
+exports.keyToString = keyToString;

package/package.json

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