mesh-ioc 1.2.0 → 2.0.0

package/README.md

@@ -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
@@ -190,105 +171,6 @@ There are several aspects that differentiate Mesh IoC from the rest of the DI li
 
 **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

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,23 +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);
+    [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;
     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,38 +2,74 @@
 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) {
         this.name = name;
         this.parent = parent;
-        this.childScopes = new Map();
+        this.bindings = new Map();
         this.instances = new Map();
         this.middlewares = [];
-        this.currentScope = new scope_1.Scope(name);
-        this.currentScope.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);
+        if (instance === undefined) {
+            const k = util_1.keyToString(key);
+            throw new errors_1.MeshBindingNotFound(this.name, k);
+        }
+        return instance;
+    }
+    tryResolve(key) {
         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);
@@ -41,9 +77,9 @@ class Mesh {
             return instance;
         }
         if (this.parent) {
-            return this.parent.resolve(key);
+            return this.parent.tryResolve(key);
         }
-        throw new errors_1.MeshBindingNotFound(this.name, k);
+        return undefined;
     }
     connect(value) {
         const res = this.applyMiddleware(value);
@@ -54,21 +90,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);
-        mesh.currentScope = newScope;
-        return mesh;
-    }
     instantiate(binding) {
         switch (binding.type) {
             case 'alias':

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mesh-ioc",
-    "version": "1.2.0",
+    "version": "2.0.0",
     "description": "Mesh: Powerful and Lightweight IoC Library",
     "main": "out/main/index.js",
     "types": "out/main/index.d.ts",
@@ -15,7 +15,7 @@
         "test": "NODE_ENV=test mocha",
         "preversion": "npm run lint",
         "version": "npm run compile",
-        "postversion": "npm publish --access=public"
+        "postversion": "npm publish --access=public && git push origin main --tags"
     },
     "pre-commit": [
         "lint"

package/out/main/bindings.d.ts

@@ -1,14 +0,0 @@
-import { ServiceConstructor } from './types';
-export declare type Binding<T> = ConstantBinding<T> | ServiceBinding<T> | AliasBinding;
-export declare type ConstantBinding<T> = {
-    type: 'constant';
-    value: 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,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

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;

package/out/main/decorators.d.ts

@@ -1,5 +0,0 @@
-import 'reflect-metadata';
-export declare function dep(options?: DepOptions): (target: any, propertyName: string) => void;
-export interface DepOptions {
-    key?: string;
-}

package/out/main/decorators.js

@@ -1,34 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.dep = void 0;
-require("reflect-metadata");
-const errors_1 = require("./errors");
-const mesh_1 = require("./mesh");
-const metadata_1 = require("./metadata");
-function dep(options = {}) {
-    return function (target, propertyName) {
-        var _a;
-        const className = target.constructor.name;
-        const designType = Reflect.getMetadata('design:type', target, propertyName);
-        const key = (_a = options.key) !== null && _a !== void 0 ? _a : designType === null || designType === void 0 ? void 0 : designType.name;
-        if (!key) {
-            throw new errors_1.DepKeyNotInferred(className, propertyName);
-        }
-        metadata_1.depMetadata.push({
-            className,
-            propertyName,
-            designTypeName: designType.name,
-            key,
-        });
-        Object.defineProperty(target, propertyName, {
-            get() {
-                const mesh = this[mesh_1.MESH_REF];
-                if (!mesh) {
-                    throw new errors_1.DepInstanceNotConnected(className, propertyName);
-                }
-                return mesh.resolve(key);
-            }
-        });
-    };
-}
-exports.dep = dep;

package/out/main/metadata.d.ts

@@ -1,7 +0,0 @@
-export declare const depMetadata: DepMetadata[];
-export interface DepMetadata {
-    className: string;
-    propertyName: string;
-    designTypeName: string;
-    key: string;
-}

package/out/main/metadata.js

@@ -1,4 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.depMetadata = void 0;
-exports.depMetadata = [];