proxydi 0.0.4 → 0.0.5

package/README.md

@@ -1,25 +1,29 @@
-# ProxyDI
+# ProxyDi
 
-[![Coverage Status](https://coveralls.io/repos/github/proxy-di/proxydi/badge.svg?branch=main)](https://coveralls.io/github/proxy-di/proxydi?branch=main)
+[![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)
 
-A typed DI container that resolves circular dependencies via Proxy.
+A typed hierarchical DI container that resolves circular dependencies via Proxy.
 
-Core notes:
+Core features:
 
 - Uses Stage 3 decorators (supported in TypeScript 5.x and babel-plugin-proposal-decorators)
 - Automatically resolves circular dependencies
-- Matches services by unique identifiers, class or property names
-- Currently in active development
+- 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
 
 # Quick start
 
+Install the `proxydi` package in your JavaScript or TypeScript project:
+
 ```shell
 npm i proxydi
 ```
 
-If you are using TypeScript be sure that your tsconfig.json set exactly `false` value for `experimentalDecorators`. This could be not obvious, but this setup turns on support of Stage 3 decorators.
+If you are using TypeScript, ensure that `experimentalDecorators` is set to `false` in your `tsconfig.json`. This enables support for Stage 3 decorators:
 
 ```jsonc
+// tsconfig.json
 {
     "compilerOptions": {
         // ...
@@ -29,42 +33,114 @@ If you are using TypeScript be sure that your tsconfig.json set exactly `false`
 }
 ```
 
-1. @inject your dependencies
+The process of using ProxyDi consists of 3 stages:
 
-```typescript
-import { inject } from 'proxydi';
+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.
 
-interface Personality {
+```typescript
+interface Character {
     greet(): string;
 }
 
-class Agent {
-    @inject() personality: Personality;
+class Actor {
+    @inject('Role') role: Character;
+
+    play = () => this.role.greet();
 }
 ```
 
-2. Create, fill ProxyDI container
+2. Next, set up the ProxyDi container and fill it with dependencies. Let's define an agent 007 role and prepare our first container:
 
 ```typescript
-import { ProxyDI } from 'proxydi';
+class Agent007 implements Character {
+    greet = () => 'Bond... James Bond';
+}
+
+const container = new ProxyDiContainer();
+container.newDependency(Agent007, 'Role');
+container.newDependency(Actor, 'Actor');
+```
+
+3. At the last stage, take dependencies from the ProxyDi container and just use them. Let our actor play its role:
+
+```typescript
+const actor = container.resolve<Actor>('Actor');
+console.log(actor.greet());
+```
+
+And the result is:
+
+```shell
+> Bond... James Bond
+```
+
+# The Reason
+
+To illustrate why we should use a container for this simple purpose, let's create a container for another character and ask the actor to play the new role:
 
-class Jarvis implements Personality {
-    greet: () => 'Hello, sir!';
+```typescript
+class M implements Character {
+    greet = () => '007, I have a new mission for you';
 }
 
-const container = new ProxyDI();
-container.registerClass('personality', Jarvis);
+const container = new ProxyDiContainer();
+container.newDependency(M, 'Role');
+container.newDependency(Actor, 'Actor');
+
+const actor = container.resolve<Actor>('Actor');
+console.log(actor.play());
+```
+
+```shell
+> 007, I have a new mission for you
 ```
 
-3. Use dependencies
+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.
+
+So, ProxyDi is a just tool to link dependencies. And nothing more. But we
+
+# Сircular dependencies
+
+There are several rough edges in traditional DI container implementations that ProxyDi addresses. The first of these is circular dependencies.
+
+Let's illustrate this with a movie set metaphor. During filming, the actor and director work together in a continuous feedback loop:
 
 ```typescript
-const agent = container.resolve(Agent);
-console.log(agent.personality.greet());
+class Director {
+    @inject('Actor') private actor: Actor;
+    private passionLevel = 1;
+
+    direct(line: string) {
+        return this.actor.perform(line, this.passionLevel);
+    }
+}
+
+class Actor {
+    @inject('Role') private role: Character;
+    @inject('Director') private director: Director;
+
+    play() {
+        const line = this.role.greet();
+        // Here actor asks director how to perform the line
+        return this.director.direct(line);
+    }
+
+    perform(line: string, loudness: number = 0) {
+        return line + '!'.repeat(loudness);
+    }
+}
+
+const container = new ProxyDiContainer();
+container.newDependency(Actor, 'Actor');
+container.newDependency(Director, 'Director');
+container.newDependency(Agent007, 'Role');
+
+const actor = container.resolve<Actor>('Actor');
+console.log(actor.play());
 ```
 
 ```shell
-> Hello, sir!
+> Bond... James Bond!
 ```
 
-To be continued...
+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.

package/dist/Proxy.utils.d.ts

@@ -1,3 +1,5 @@
-import { ServiceId } from './types';
-export declare const makeProxy: <T>(serviceId: ServiceId, instance: any) => T;
-export declare function isProxy(value: any): boolean;
+import { ContainerizedDependency, Injection, IProxyDiContainer } from './types';
+export declare const makeInjectionProxy: <T>(inject: 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/ProxyDI.d.ts

@@ -1,27 +1,27 @@
-import { ProxyDI as IProxyDI, ProxydiedInstance } from './types';
-import { ProxyDISettings, ServiceClass, ServiceId } from './types';
-export declare class ProxyDI implements IProxyDI {
+import { IProxyDiContainer as IProxyDiContainer, ContainerizedServiceInstance, ServiceInstanced, ServiceClass } from './types';
+import { ProxyDiSettings, ServiceId } from './types';
+export declare class ProxyDiContainer implements IProxyDiContainer {
     private static idCounter;
     readonly id: number;
-    readonly parent?: ProxyDI;
+    readonly parent?: ProxyDiContainer;
     private children;
+    /**
+     * Holds instances of services registered in particular this container
+     */
     private serviceInstances;
-    private serviceClasses;
+    private parentInstanceProxies;
     private settings;
-    constructor(settings?: ProxyDISettings, parent?: ProxyDI);
-    registerInstance<T>(serviceId: ServiceId, instance: T extends {
-        new (...args: any[]): any;
-    } ? never : T): void;
-    registerClass<T>(serviceId: ServiceId, serviceClass: ServiceClass<T>): void;
+    constructor(settings?: ProxyDiSettings, parent?: ProxyDiContainer);
+    registerService<T>(serviceId: ServiceId, instance: ServiceInstanced<T>): void;
+    private registerInstanceImplementation;
+    createService<T>(serviceId: ServiceId, ServiceClass: ServiceClass<T>): void;
     isKnown(serviceId: ServiceId): boolean;
-    resolve<T>(serviceId: ServiceId): T;
-    injectDependencies(instance: any): void;
-    createChildContainer(): ProxyDI;
-    removeInstance(serviceId: ServiceId | ProxydiedInstance): void;
-    removeClass(serviceId: ServiceId): void;
+    resolve<T>(serviceId: ServiceId): T & ContainerizedServiceInstance;
+    injectDependencies(injectionsOwner: any): void;
+    createChildContainer(): ProxyDiContainer;
+    removeService(serviceId: ServiceId | ContainerizedServiceInstance): void;
     destroy(): void;
     private findInstance;
-    private findServiceClass;
     private addChild;
     private removeChild;
 }

package/dist/ProxyDiContainer.d.ts

@@ -0,0 +1,28 @@
+import { IProxyDiContainer as IProxyDiContainer, ContainerizedDependency as ContainerizedDependency, Instanced, DependencyClass } from './types';
+import { ContainerSettings as ContainerSettings, DependencyId } from './types';
+export declare class ProxyDiContainer implements IProxyDiContainer {
+    private static idCounter;
+    readonly id: number;
+    readonly parent?: ProxyDiContainer;
+    private children;
+    /**
+     * Holds dependencies of this particular container
+     */
+    private dependencies;
+    private parentDependencyProxies;
+    private settings;
+    constructor(settings?: ContainerSettings, parent?: ProxyDiContainer);
+    registerDependency<T>(dependency: Instanced<T>, dependencyId: DependencyId): void;
+    newDependency<T>(DependencyClass: DependencyClass<T>, dependencyId: DependencyId): void;
+    private registerDependencyImpl;
+    isKnown(dependencyId: DependencyId): boolean;
+    resolveAutoInjectable<T extends new () => any>(SomeClass: T): InstanceType<T>;
+    resolve<T>(dependencyId: DependencyId): T & ContainerizedDependency;
+    injectDependenciesTo(injectionsOwner: any): void;
+    createChildContainer(): ProxyDiContainer;
+    removeDependency(dependencyOrId: DependencyId | ContainerizedDependency): void;
+    destroy(): void;
+    private findDependency;
+    private addChild;
+    private removeChild;
+}

package/dist/autoInjectable.d.ts

@@ -0,0 +1,13 @@
+import { InstancedDependency, DependencyId } from './types';
+export declare const autoInjectableClasses: Record<DependencyId, InstancedDependency<any>>;
+/**
+ * Registers a class as an auto-injectable for dependency injection.
+ *
+ * @param dependencyId - Optional dependency identifier. If omitted, the class name is used.
+ * @returns A class decorator function.
+ *
+ * Note: During dependency resolution, any container that does not have an instance for the specified dependency identifier
+ * will create an instance of the decorated class. However, if a container already has an instance with that identifier
+ * prior to resolution, the decorated class will be ignored by that container.
+ */
+export declare const autoInjectable: (dependencyId?: DependencyId) => (value: InstancedDependency<any>, context: ClassDecoratorContext) => void;

package/dist/autoInjectableService.d.ts

@@ -0,0 +1,13 @@
+import { InstancedServiceClass, ServiceId } from './types';
+export declare const autoInjectableServices: Record<ServiceId, InstancedServiceClass<any>>;
+/**
+ * Decorator that registers a class as an auto-injectable service for dependency injection.
+ *
+ * @param serviceId - Optional service identifier. If omitted, the class name is used.
+ * @returns A class decorator function.
+ *
+ * Note: During dependency resolution, any container that does not have an instance for the specified service identifier
+ * will create an instance of the decorated class. However, if a container already has an instance with that identifier
+ * prior to resolution, the decorated class will be ignored by that container.
+ */
+export declare const autoInjectableService: (serviceId?: ServiceId) => (value: InstancedServiceClass<any>, context: ClassDecoratorContext) => void;