proxydi 0.0.8 → 0.0.9

package/README.md

@@ -9,8 +9,9 @@ A typed hierarchical DI container that resolves circular dependencies via Proxy.
 Core features:
 
 - 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
+- Automatically resolves circular dependencies with no performance impact
 - Resolves dependencies in the context of a particular container
+- Supports hierarchical containers with the ability to resolve dependencies in both directions
 - 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
 
@@ -78,7 +79,7 @@ class Actor {
 ```
 
 2. Next, create the [ProxyDiContainer](https://proxy-di.github.io/proxydi/classes/ProxyDiContainer.html)
-   and fill it with dependencies using [register()](https://proxy-di.github.io/proxydi/classes/ProxyDiContainer.html#register) metod. For example, let's define an agent 007 role and prepare our first container:
+   and fill it with dependencies using [register()](https://proxy-di.github.io/proxydi/classes/ProxyDiContainer.html#register) method. For example, let's define an agent 007 role and prepare our first container:
 
 ```typescript
 class Agent007 implements Character {
@@ -124,7 +125,7 @@ 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 exactly the goal of the [Dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle) in SOLID approach to design software. 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.
+In this example, we changed the behavior of the actor by changing the role dependency in the ProxyDi container. This is exactly the goal of the [Dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle) in the SOLID approach to software design. 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 just a tool to link dependencies, allowing them to freely communicate with each other without worrying about which specific dependency they're dealing with. And nothing more.
 
@@ -174,7 +175,7 @@ console.log(actor.play());
 
 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 take a look, our approach is still the same - we just link dependencies by @inject and use them freely without any worries. ProxyDi handles this tricky issue as elegantly as is even possible. It does this using JavaScript Proxies, more about Proxies and theirs impact on perfomance [later](#injection-proxy-performance).
+But take a look, our approach is still the same - we just link dependencies with @inject and use them freely without any worries. ProxyDi handles this tricky issue as elegantly as possible. It does this using JavaScript Proxies, more about Proxies and their impact on performance [later](#injection-proxy-performance).
 
 ## Hierarchy of containers
 
@@ -182,7 +183,7 @@ Another tricky part of DI containers is the ability to create multiple instances
 
 Instead, it suggests you to use a hierarchy of containers by using [createChildContainer()](https://proxy-di.github.io/proxydi/classes/ProxyDiContainer.html#createchildcontainer) method. Child container inherits all parent settings and can resolve exactly the same dependencies as their parent (but parent container does not have access to dependencies registered in its children).
 
-For example, imagine you are working on a game level, there are many characters on this level, each character could have many perks.
+For example, imagine you are working on a game level, there are many characters on this level, and each character could have many perks.
 
 With ProxyDi we can present all these stuff in a hierarchy of containers. The most top container holds information about game level, the most bottom ones hold information about perks:
 
@@ -199,7 +200,9 @@ const perk = perksContainer.register(new UnderwaterShield(10), 'perk');
 
 This is not how I propose to design games, ECS pattern does it better, but the goal was to demonstrate that with this approach instead of creating bunches of instances to represent your project entities, you can create bunches of containers each of them containing instances related to each other.
 
-As a bonus, each bottom level dependency is free to use any dependency from the top:
+### Resolving dependencies from parents
+
+As a bonus, each bottom level dependency is free to use any dependency from the top just as if they were registered in its own container:
 
 ```typescript
 class UnderwaterShield {
@@ -208,15 +211,38 @@ class UnderwaterShield {
 
     constructor(private amount: number) {}
 
-    initialize() {
-        this.character.on('hit', this.act);
-    }
-
-    act = () =>
+    activate = () =>
         this.level.isUnderwater && (this.character.health += this.amount);
 }
 ```
 
+In this example, the shield perk increases character health if it is underwater. The perk receives both level and character using the @inject() decorator, the same way as we have seen so far.
+
+## Resolving dependencies from children
+
+Backward bonus of containers hierarchy, each top level dependency is free to use all dependency from the bottom:
+
+```typescript
+class Character {
+    public health = 100;
+
+    hit(abount: number) {
+        this.health -= abount;
+
+        const perks = resolveAll<Perk>(this, 'perk');
+        perks.forEach((perk) => perk.activate());
+    }
+}
+```
+
+In this example, the character activates all its perks, which are registered in all children containers. The way it do this job need a little bit more explanation.
+
+### Reference to the container
+
+Here you should be wondering, how [resolveAll()](https://proxy-di.github.io/proxydi/functions/resolveAll.html.html) function knows about the container, to which character belongs. The answer - each time when dependency is registered in the ProxyDiContainer, it saves a reference to itself in this dependency instance. So, when you call resolveAll() function, it just takes this reference from the instance and then recursively resolves all asked dependencies from this container and all its children and children of children and so on.
+
+Despite this explanation is a little bit complicated, the example is still simple, the character just activates all its perks.
+
 ## 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:
@@ -253,10 +279,18 @@ Therefore, after the container has been baked, the performance impact becomes ze
 
 To be continued...
 
-## License
+## Motivation
 
-This project is licensed under the terms of the MIT License. See the [LICENSE](./LICENSE) file for details.
+The world and software changes, they become more complex over time. But the main imperative in software development stays the same - managing the complexity. Despite the tendency that software is written more often by artificial intelligence than humans, complexity stays complexity. The less complex conceptions any kind of intelligence should operate, the more efficient it will be.
+
+The main goal of ProxyDi is to decrease complexity in the very small field of connecting different entities of software code between each other, no matter by whom this code was written. This is my attempt to make the linking of dependencies as transparent and simple as possible for developers.
+
+Also, I'm tired of moving this-like code from one project to another. I hope that ProxyDi will be a good enough solution for this problem not only for me. To be honest, this is the 4th attempt to create an "ideal" DI container and my 1st that uses Stage 3 decorators. I hope, this one will be the last one. With your help :) For TS/JS technology stack, of course!
 
 ## Contributing
 
-Contribution documentation is not ready yet but is planned. Feel free to contribute even now though! :)
+Any reviews, comments, ideas, issues, and pull requests are welcome. Contribution documentation is not ready yet but is planned. Feel free to contribute even now though! :)
+
+## License
+
+This project is licensed under the terms of the MIT License. See the [LICENSE](./LICENSE) file for details.

package/dist/ProxyDiContainer.d.ts

@@ -44,8 +44,8 @@ export declare class ProxyDiContainer implements IProxyDiContainer {
      * @throws Error if dependency is already registered and rewriting is not allowed or if invalid dependency (not object) is provided and this it now allowed.
      * @returns Dependency instance, registered in container
      */
-    register<T>(DependencyClass: DependencyClass<T>, dependencyId: DependencyId): T;
-    register<T>(dependency: T, dependencyId: DependencyId): T;
+    register<T>(DependencyClass: DependencyClass<T>, dependencyId: DependencyId): T & ContainerizedDependency;
+    register<T>(dependency: T extends new (...args: any[]) => any ? never : T, dependencyId: DependencyId): T & ContainerizedDependency;
     /**
      * Internal method that implements registeration of dependency and prepare it for injection.
      * @param dependencyId The unique identifier of the dependency.
@@ -65,7 +65,7 @@ export declare class ProxyDiContainer implements IProxyDiContainer {
      * @throws Error if the dependency cannot be found or is not auto injectable.
      */
     resolve<T>(dependencyId: DependencyId): T & ContainerizedDependency;
-    resolve<T extends new (...args: any[]) => any>(SomeClass: T): InstanceType<T>;
+    resolve<T extends new (...args: any[]) => any>(SomeClass: T): InstanceType<T> & ContainerizedDependency;
     /**
      * Injects dependencies to the given object based on its defined injections metadata. Does not affect the container.
      * @param injectionsOwner The object to inject dependencies into.

package/dist/index.cjs

@@ -231,9 +231,7 @@ class ProxyDiContainer {
         }
         const AutoInjectableClass = autoInjectableClasses[param];
         const autoDependency = new AutoInjectableClass();
-        this.registerImpl(autoDependency, param);
-        this.dependencies[param] = autoDependency;
-        return autoDependency;
+        return this.register(autoDependency, param);
     }
     /**
      * Injects dependencies to the given object based on its defined injections metadata. Does not affect the container.
@@ -376,8 +374,35 @@ function isDependency(dependencyOrId) {
         !!dependencyOrId[DEPENDENCY_ID]);
 }
 
+function resolveAll(instance, dependencyId) {
+    if (typeof dependencyId === 'function') {
+        for (const [id, DependencyClass] of Object.entries(autoInjectableClasses)) {
+            if (DependencyClass === dependencyId) {
+                return resolveAll(instance, id);
+            }
+        }
+        throw new Error(`Class is not auto injectable: ${dependencyId.name}`);
+    }
+    const container = instance[PROXYDY_CONTAINER];
+    if (!container) {
+        throw new Error('Instance is not registered in any container');
+    }
+    return recursiveResolveAll(container, dependencyId);
+}
+function recursiveResolveAll(container, dependencyId) {
+    let all = container.isKnown(dependencyId)
+        ? [container.resolve(dependencyId)]
+        : [];
+    for (const child of container.children) {
+        const allChild = recursiveResolveAll(child, dependencyId);
+        all = all.concat(allChild);
+    }
+    return all;
+}
+
 exports.DEPENDENCY_ID = DEPENDENCY_ID;
 exports.PROXYDY_CONTAINER = PROXYDY_CONTAINER;
 exports.ProxyDiContainer = ProxyDiContainer;
 exports.autoInjectable = autoInjectable;
 exports.inject = inject;
+exports.resolveAll = resolveAll;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { inject } from './inject';
 export { ProxyDiContainer } from './ProxyDiContainer';
 export { autoInjectable } from './autoInjectable';
-export { Injection, DependencyId, DependencyClass, ContainerSettings as ProxyDiSettings, PROXYDY_CONTAINER, DEPENDENCY_ID, } from './types';
+export { Injection, DependencyId, DependencyClass, ContainerSettings, PROXYDY_CONTAINER, DEPENDENCY_ID, } from './types';
+export { resolveAll } from './resolveAll';

package/dist/index.js

@@ -229,9 +229,7 @@ class ProxyDiContainer {
         }
         const AutoInjectableClass = autoInjectableClasses[param];
         const autoDependency = new AutoInjectableClass();
-        this.registerImpl(autoDependency, param);
-        this.dependencies[param] = autoDependency;
-        return autoDependency;
+        return this.register(autoDependency, param);
     }
     /**
      * Injects dependencies to the given object based on its defined injections metadata. Does not affect the container.
@@ -374,4 +372,30 @@ function isDependency(dependencyOrId) {
         !!dependencyOrId[DEPENDENCY_ID]);
 }
 
-export { DEPENDENCY_ID, PROXYDY_CONTAINER, ProxyDiContainer, autoInjectable, inject };
+function resolveAll(instance, dependencyId) {
+    if (typeof dependencyId === 'function') {
+        for (const [id, DependencyClass] of Object.entries(autoInjectableClasses)) {
+            if (DependencyClass === dependencyId) {
+                return resolveAll(instance, id);
+            }
+        }
+        throw new Error(`Class is not auto injectable: ${dependencyId.name}`);
+    }
+    const container = instance[PROXYDY_CONTAINER];
+    if (!container) {
+        throw new Error('Instance is not registered in any container');
+    }
+    return recursiveResolveAll(container, dependencyId);
+}
+function recursiveResolveAll(container, dependencyId) {
+    let all = container.isKnown(dependencyId)
+        ? [container.resolve(dependencyId)]
+        : [];
+    for (const child of container.children) {
+        const allChild = recursiveResolveAll(child, dependencyId);
+        all = all.concat(allChild);
+    }
+    return all;
+}
+
+export { DEPENDENCY_ID, PROXYDY_CONTAINER, ProxyDiContainer, autoInjectable, inject, resolveAll };

package/dist/index.umd.js

@@ -235,9 +235,7 @@
             }
             const AutoInjectableClass = autoInjectableClasses[param];
             const autoDependency = new AutoInjectableClass();
-            this.registerImpl(autoDependency, param);
-            this.dependencies[param] = autoDependency;
-            return autoDependency;
+            return this.register(autoDependency, param);
         }
         /**
          * Injects dependencies to the given object based on its defined injections metadata. Does not affect the container.
@@ -380,10 +378,37 @@
             !!dependencyOrId[DEPENDENCY_ID]);
     }
 
+    function resolveAll(instance, dependencyId) {
+        if (typeof dependencyId === 'function') {
+            for (const [id, DependencyClass] of Object.entries(autoInjectableClasses)) {
+                if (DependencyClass === dependencyId) {
+                    return resolveAll(instance, id);
+                }
+            }
+            throw new Error(`Class is not auto injectable: ${dependencyId.name}`);
+        }
+        const container = instance[PROXYDY_CONTAINER];
+        if (!container) {
+            throw new Error('Instance is not registered in any container');
+        }
+        return recursiveResolveAll(container, dependencyId);
+    }
+    function recursiveResolveAll(container, dependencyId) {
+        let all = container.isKnown(dependencyId)
+            ? [container.resolve(dependencyId)]
+            : [];
+        for (const child of container.children) {
+            const allChild = recursiveResolveAll(child, dependencyId);
+            all = all.concat(allChild);
+        }
+        return all;
+    }
+
     exports.DEPENDENCY_ID = DEPENDENCY_ID;
     exports.PROXYDY_CONTAINER = PROXYDY_CONTAINER;
     exports.ProxyDiContainer = ProxyDiContainer;
     exports.autoInjectable = autoInjectable;
     exports.inject = inject;
+    exports.resolveAll = resolveAll;
 
 }));

package/dist/resolveAll.d.ts

@@ -0,0 +1,8 @@
+import { ContainerizedDependency, DependencyId } from './types';
+/**
+ * Resolves all dependencies from this container and it's children either by its dependency ID or through a class constructor for auto-injectable classes.
+ * @param param The dependency ID or class constructor.
+ * @returns Array with all founded dependence instances, could be empty
+ */
+export declare function resolveAll<T>(instance: any, dependencyId: DependencyId): (T & ContainerizedDependency)[];
+export declare function resolveAll<T extends new (...args: any[]) => any>(instance: any, SomeClass: T): (InstanceType<T> & ContainerizedDependency)[];

package/dist/types.d.ts

@@ -14,6 +14,8 @@ export type IProxyDiContainer = {
     register: (dependency: any, dependencyId: DependencyId) => any;
     resolve: <T>(dependencyId: DependencyId) => T & ContainerizedDependency;
     createChildContainer: () => IProxyDiContainer;
+    children: IProxyDiContainer[];
+    getChild(id: number): IProxyDiContainer;
     remove: (dependencyId: DependencyId | ContainerizedDependency) => void;
     bakeInjections(): void;
     destroy: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "proxydi",
-    "version": "0.0.8",
+    "version": "0.0.9",
     "description": "A typed hierarchical DI container that resolves circular dependencies via Proxy",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -57,4 +57,4 @@
         "typescript": "^5.7.3",
         "vitest": "^3.0.4"
     }
-}
+}