proxydi 0.0.5 → 0.0.6

package/README.md

@@ -1,16 +1,16 @@
 # ProxyDi
 
-[![Coverage Status](https://coveralls.io/repos/github/proxy-di/proxydi/badge.svg?branch=main)](https://coveralls.io/github/proxy-di/proxydi?branch=main&v=0.0.5)
+[![Coverage Status](https://coveralls.io/repos/github/proxy-di/proxydi/badge.png)](https://coveralls.io/github/proxy-di/proxydi)
 
 A typed hierarchical DI container that resolves circular dependencies via Proxy.
 
 Core features:
 
-- Uses Stage 3 decorators (supported in TypeScript 5.x and babel-plugin-proposal-decorators)
-- Automatically resolves circular dependencies
+- Uses Stage 3 decorators, supported in TypeScript 5.x ([examples repository](https://github.com/proxy-di/node-ts-examples)) and Babel via babel-plugin-proposal-decorators ([examples repository](https://github.com/proxy-di/node-babel-examples))
+- Automatically resolves circular dependencies with no persormance impact
 - Resolves dependencies in the context of a particular container
-- Matches services by unique identifiers, class, or property names
-- Currently in active development, API may change until version 0.1.0
+- Matches dependencies by unique identifiers or automatically using class names and property names
+- Currently under active development, the API may change until version 0.1.0
 
 # Quick start
 
@@ -20,6 +20,8 @@ Install the `proxydi` package in your JavaScript or TypeScript project:
 npm i proxydi
 ```
 
+## TypeScript set up
+
 If you are using TypeScript, ensure that `experimentalDecorators` is set to `false` in your `tsconfig.json`. This enables support for Stage 3 decorators:
 
 ```jsonc
@@ -28,11 +30,31 @@ If you are using TypeScript, ensure that `experimentalDecorators` is set to `fal
     "compilerOptions": {
         // ...
         "experimentalDecorators": false,
+        "strictPropertyInitialization": false,
     },
     //...
 }
 ```
 
+Changing `strictPropertyInitialization` is not necessary, but if you leave it at the default value, you will need to slightly modify the examples. More about this later.
+
+## Babel set up
+
+For Babel projects, ensure that @babel/plugin-proposal-decorators is configured exactly as follows:
+
+```jsonc
+// .babelrc
+{
+    // ...
+    "plugins": [
+        // other plugins
+        ["@babel/plugin-proposal-decorators", { "version": "2023-11" }],
+    ],
+}
+```
+
+## Usage
+
 The process of using ProxyDi consists of 3 stages:
 
 1. Use the @inject decorator to define the dependencies to be resolved by the ProxyDi container. In this example, we define an interface for characters and ask ProxyDi to resolve the `Role` dependency for actors.
@@ -65,7 +87,7 @@ container.newDependency(Actor, 'Actor');
 
 ```typescript
 const actor = container.resolve<Actor>('Actor');
-console.log(actor.greet());
+console.log(actor.play());
 ```
 
 And the result is:
@@ -95,11 +117,11 @@ console.log(actor.play());
 > 007, I have a new mission for you
 ```
 
-In this example, we changed the behavior of the actor by changing the role dependency in the ProxyDi container. This is the goal of the [Dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle) in SOLID. Continuing our metaphor, the actor can play any role, but it is not he who decides what role he will play. This is a film director's decision, and here we just cosplay him by setting up our containers.
+In this example, we changed the behavior of the actor by changing the role dependency in the ProxyDi container. This is the goal of the [Dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle) in SOLID. Continuing our metaphor, the actor can play any role, but he is not the one who decides which role he will play. This is a film director's decision, and here we just cosplay him by setting up our containers.
 
-So, ProxyDi is a just tool to link dependencies. And nothing more. But we
+So, ProxyDi is just a tool to link dependencies. And nothing more.
 
-# Сircular dependencies
+# Circular dependencies
 
 There are several rough edges in traditional DI container implementations that ProxyDi addresses. The first of these is circular dependencies.
 
@@ -121,7 +143,7 @@ class Actor {
 
     play() {
         const line = this.role.greet();
-        // Here actor asks director how to perform the line
+        // Here, the actor asks the director how to perform the line.
         return this.director.direct(line);
     }
 
@@ -143,4 +165,40 @@ console.log(actor.play());
 > Bond... James Bond!
 ```
 
-In traditional DI containers, this scene would be tricky to shoot - the Director calls Actor's methods while Actor simultaneously needs Director's guidance. But ProxyDi handles it elegantly using JavaScript Proxies without any worries from you.
+In traditional DI containers, this scene would be tricky to shoot - the Director calls Actor's methods while Actor simultaneously needs Director's guidance. But ProxyDi handles it elegantly using JavaScript Proxies, without any worries on your part.
+
+# Rewriting dependencies
+
+By default, ProxyDi doesn't allow rewriting dependencies in the container. After a dependency becomes known to the container, any attempt to register a new dependency with the same dependency ID will throw an Error:
+
+```typescript
+const container = new ProxyDiContainer();
+container.newDependency(Actor, 'Actor');
+container.newDependency(Actor, 'Actor'); // !!! Error here
+```
+
+However, there is an option that allows you to do these kinds of things:
+
+```typescript
+const container = new ProxyDiContainer({ allowRewriteDependencies: true });
+container.newDependency(Actor, 'Actor');
+
+const actor = container.resolve<Actor>('Actor');
+const wrapper = new ActorWrapper(actor);
+
+container.registerDependency(wrapper, 'Actor'); // No error is thrown here now
+```
+
+## Injection proxy performance
+
+As mentioned before, ProxyDi uses `Proxy` for each field marked by the @inject() decorator. This makes it possible to resolve circular dependencies. By default, these proxies are replaced by the actual dependency instances from the container during their first use, so the performance impact on your application is minimal.
+
+However, if you allow rewriting dependencies in the container, these proxies remain in use to keep injections updated. As a result, every time you access a dependency field, there is a significant performance impact. In our tests, property access via Proxy is up to 100 times slower. For this reason, we recommend not allowing rewriting dependencies in production and keeping the container’s default behavior.
+
+## Baking injections
+
+There is a container method `bakeInjections()` that bakes all injections and freezes the current container’s dependencies. After calling this method, the container will deny any attempts to rewrite dependencies. It also bakes the dependencies in all its children.
+
+After the container has been baked, the performance impact becomes zero. Therefore, you should use this method even for containers with default settings, ensuring that your application don't have to wait for the first use of each injection before they are baked.
+
+To be continued...

package/dist/Proxy.utils.d.ts

@@ -1,5 +1,5 @@
 import { ContainerizedDependency, Injection, IProxyDiContainer } from './types';
-export declare const makeInjectionProxy: <T>(inject: Injection, injectionOwner: ContainerizedDependency, container: IProxyDiContainer) => T;
+export declare const makeInjectionProxy: <T>(injection: Injection, injectionOwner: ContainerizedDependency, container: IProxyDiContainer) => T;
 export declare function makeDependencyProxy(dependency: any): any;
 export declare function isInjectionProxy(value: any): boolean;
 export declare function isInstanceProxy(value: any): boolean;

package/dist/ProxyDiContainer.d.ts

@@ -10,7 +10,7 @@ export declare class ProxyDiContainer implements IProxyDiContainer {
      */
     private dependencies;
     private parentDependencyProxies;
-    private settings;
+    readonly settings: Required<ContainerSettings>;
     constructor(settings?: ContainerSettings, parent?: ProxyDiContainer);
     registerDependency<T>(dependency: Instanced<T>, dependencyId: DependencyId): void;
     newDependency<T>(DependencyClass: DependencyClass<T>, dependencyId: DependencyId): void;
@@ -19,6 +19,7 @@ export declare class ProxyDiContainer implements IProxyDiContainer {
     resolveAutoInjectable<T extends new () => any>(SomeClass: T): InstanceType<T>;
     resolve<T>(dependencyId: DependencyId): T & ContainerizedDependency;
     injectDependenciesTo(injectionsOwner: any): void;
+    bakeInjections(): void;
     createChildContainer(): ProxyDiContainer;
     removeDependency(dependencyOrId: DependencyId | ContainerizedDependency): void;
     destroy(): void;

package/dist/index.cjs

@@ -47,13 +47,17 @@ class InjectionProxy {
     }
 }
 _a = IS_INJECTION_PROXY;
-const makeInjectionProxy = (inject, injectionOwner, container) => {
+const makeInjectionProxy = (injection, injectionOwner, container) => {
     function getDependency() {
-        if (container.isKnown(inject.dependencyId)) {
-            return container.resolve(inject.dependencyId);
+        if (container.isKnown(injection.dependencyId)) {
+            const dependency = container.resolve(injection.dependencyId);
+            if (!container.settings.allowRewriteDependencies) {
+                injection.set(injectionOwner, dependency);
+            }
+            return dependency;
         }
         else {
-            throw new Error(`Unknown dependency: ${String(inject.dependencyId)}`);
+            throw new Error(`Unknown dependency: ${String(injection.dependencyId)}`);
         }
     }
     return new Proxy(new InjectionProxy(injectionOwner, container), {
@@ -114,10 +118,13 @@ class ProxyDiContainer {
                 throw new Error(`ProxyDi already has dependency for ${String(dependencyId)}`);
             }
         }
-        if (!(typeof dependency === 'object') &&
-            !this.settings.allowRegisterAnything) {
+        const isObject = typeof dependency === 'object';
+        if (!isObject && !this.settings.allowRegisterAnything) {
             throw new Error(`Can't register as dependency (allowRegisterAnything is off for this contatiner): ${dependency}`);
         }
+        if (isObject) {
+            dependency[PROXYDY_CONTAINER] = this;
+        }
         this.registerDependencyImpl(dependencyId, dependency);
     }
     newDependency(DependencyClass, dependencyId) {
@@ -127,6 +134,7 @@ class ProxyDiContainer {
             }
         }
         const dependency = new DependencyClass();
+        dependency[PROXYDY_CONTAINER] = this;
         this.registerDependencyImpl(dependencyId, dependency);
     }
     registerDependencyImpl(dependencyId, dependency) {
@@ -177,11 +185,24 @@ class ProxyDiContainer {
     }
     injectDependenciesTo(injectionsOwner) {
         const dependencyInjects = injectionsOwner[INJECTIONS] || {};
-        Object.values(dependencyInjects).forEach((inject) => {
-            const dependencyProxy = makeInjectionProxy(inject, injectionsOwner, this);
-            inject.set(injectionsOwner, dependencyProxy);
+        Object.values(dependencyInjects).forEach((injection) => {
+            const dependencyProxy = makeInjectionProxy(injection, injectionsOwner, this);
+            injection.set(injectionsOwner, dependencyProxy);
         });
     }
+    bakeInjections() {
+        for (const dependency of Object.values(this.dependencies)) {
+            const dependencyInjects = dependency[INJECTIONS] || {};
+            Object.values(dependencyInjects).forEach((inject) => {
+                const value = this.resolve(inject.dependencyId);
+                inject.set(dependency, value);
+            });
+        }
+        this.settings.allowRewriteDependencies = false;
+        for (const child of Object.values(this.children)) {
+            child.bakeInjections();
+        }
+    }
     createChildContainer() {
         return new ProxyDiContainer(this.settings, this);
     }

package/dist/index.js

@@ -45,13 +45,17 @@ class InjectionProxy {
     }
 }
 _a = IS_INJECTION_PROXY;
-const makeInjectionProxy = (inject, injectionOwner, container) => {
+const makeInjectionProxy = (injection, injectionOwner, container) => {
     function getDependency() {
-        if (container.isKnown(inject.dependencyId)) {
-            return container.resolve(inject.dependencyId);
+        if (container.isKnown(injection.dependencyId)) {
+            const dependency = container.resolve(injection.dependencyId);
+            if (!container.settings.allowRewriteDependencies) {
+                injection.set(injectionOwner, dependency);
+            }
+            return dependency;
         }
         else {
-            throw new Error(`Unknown dependency: ${String(inject.dependencyId)}`);
+            throw new Error(`Unknown dependency: ${String(injection.dependencyId)}`);
         }
     }
     return new Proxy(new InjectionProxy(injectionOwner, container), {
@@ -112,10 +116,13 @@ class ProxyDiContainer {
                 throw new Error(`ProxyDi already has dependency for ${String(dependencyId)}`);
             }
         }
-        if (!(typeof dependency === 'object') &&
-            !this.settings.allowRegisterAnything) {
+        const isObject = typeof dependency === 'object';
+        if (!isObject && !this.settings.allowRegisterAnything) {
             throw new Error(`Can't register as dependency (allowRegisterAnything is off for this contatiner): ${dependency}`);
         }
+        if (isObject) {
+            dependency[PROXYDY_CONTAINER] = this;
+        }
         this.registerDependencyImpl(dependencyId, dependency);
     }
     newDependency(DependencyClass, dependencyId) {
@@ -125,6 +132,7 @@ class ProxyDiContainer {
             }
         }
         const dependency = new DependencyClass();
+        dependency[PROXYDY_CONTAINER] = this;
         this.registerDependencyImpl(dependencyId, dependency);
     }
     registerDependencyImpl(dependencyId, dependency) {
@@ -175,11 +183,24 @@ class ProxyDiContainer {
     }
     injectDependenciesTo(injectionsOwner) {
         const dependencyInjects = injectionsOwner[INJECTIONS] || {};
-        Object.values(dependencyInjects).forEach((inject) => {
-            const dependencyProxy = makeInjectionProxy(inject, injectionsOwner, this);
-            inject.set(injectionsOwner, dependencyProxy);
+        Object.values(dependencyInjects).forEach((injection) => {
+            const dependencyProxy = makeInjectionProxy(injection, injectionsOwner, this);
+            injection.set(injectionsOwner, dependencyProxy);
         });
     }
+    bakeInjections() {
+        for (const dependency of Object.values(this.dependencies)) {
+            const dependencyInjects = dependency[INJECTIONS] || {};
+            Object.values(dependencyInjects).forEach((inject) => {
+                const value = this.resolve(inject.dependencyId);
+                inject.set(dependency, value);
+            });
+        }
+        this.settings.allowRewriteDependencies = false;
+        for (const child of Object.values(this.children)) {
+            child.bakeInjections();
+        }
+    }
     createChildContainer() {
         return new ProxyDiContainer(this.settings, this);
     }

package/dist/index.umd.js

@@ -51,13 +51,17 @@
         }
     }
     _a = IS_INJECTION_PROXY;
-    const makeInjectionProxy = (inject, injectionOwner, container) => {
+    const makeInjectionProxy = (injection, injectionOwner, container) => {
         function getDependency() {
-            if (container.isKnown(inject.dependencyId)) {
-                return container.resolve(inject.dependencyId);
+            if (container.isKnown(injection.dependencyId)) {
+                const dependency = container.resolve(injection.dependencyId);
+                if (!container.settings.allowRewriteDependencies) {
+                    injection.set(injectionOwner, dependency);
+                }
+                return dependency;
             }
             else {
-                throw new Error(`Unknown dependency: ${String(inject.dependencyId)}`);
+                throw new Error(`Unknown dependency: ${String(injection.dependencyId)}`);
             }
         }
         return new Proxy(new InjectionProxy(injectionOwner, container), {
@@ -118,10 +122,13 @@
                     throw new Error(`ProxyDi already has dependency for ${String(dependencyId)}`);
                 }
             }
-            if (!(typeof dependency === 'object') &&
-                !this.settings.allowRegisterAnything) {
+            const isObject = typeof dependency === 'object';
+            if (!isObject && !this.settings.allowRegisterAnything) {
                 throw new Error(`Can't register as dependency (allowRegisterAnything is off for this contatiner): ${dependency}`);
             }
+            if (isObject) {
+                dependency[PROXYDY_CONTAINER] = this;
+            }
             this.registerDependencyImpl(dependencyId, dependency);
         }
         newDependency(DependencyClass, dependencyId) {
@@ -131,6 +138,7 @@
                 }
             }
             const dependency = new DependencyClass();
+            dependency[PROXYDY_CONTAINER] = this;
             this.registerDependencyImpl(dependencyId, dependency);
         }
         registerDependencyImpl(dependencyId, dependency) {
@@ -181,11 +189,24 @@
         }
         injectDependenciesTo(injectionsOwner) {
             const dependencyInjects = injectionsOwner[INJECTIONS] || {};
-            Object.values(dependencyInjects).forEach((inject) => {
-                const dependencyProxy = makeInjectionProxy(inject, injectionsOwner, this);
-                inject.set(injectionsOwner, dependencyProxy);
+            Object.values(dependencyInjects).forEach((injection) => {
+                const dependencyProxy = makeInjectionProxy(injection, injectionsOwner, this);
+                injection.set(injectionsOwner, dependencyProxy);
             });
         }
+        bakeInjections() {
+            for (const dependency of Object.values(this.dependencies)) {
+                const dependencyInjects = dependency[INJECTIONS] || {};
+                Object.values(dependencyInjects).forEach((inject) => {
+                    const value = this.resolve(inject.dependencyId);
+                    inject.set(dependency, value);
+                });
+            }
+            this.settings.allowRewriteDependencies = false;
+            for (const child of Object.values(this.children)) {
+                child.bakeInjections();
+            }
+        }
         createChildContainer() {
             return new ProxyDiContainer(this.settings, this);
         }

package/dist/types.d.ts

@@ -12,6 +12,7 @@ export type Injection = {
 };
 export type IProxyDiContainer = {
     id: number;
+    settings: Required<ContainerSettings>;
     isKnown: (dependencyId: DependencyId) => boolean;
     injectDependenciesTo: (dependency: any) => void;
     registerDependency: <T>(instance: T extends {
@@ -21,6 +22,7 @@ export type IProxyDiContainer = {
     resolve: <T>(serviceId: DependencyId) => T & ContainerizedDependency;
     createChildContainer: () => IProxyDiContainer;
     removeDependency: (serviceId: DependencyId | ContainerizedDependency) => void;
+    bakeInjections(): void;
     destroy: () => void;
 };
 export declare const INJECTIONS: unique symbol;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "proxydi",
-    "version": "0.0.5",
+    "version": "0.0.6",
     "description": "A typed hierarchical DI container that resolves circular dependencies via Proxy",
     "type": "module",
     "main": "./dist/index.cjs",