ditox 2.4.1 → 3.1.0

package/src/container.test.ts

@@ -1,13 +1,11 @@
 import {
   CONTAINER,
   createContainer,
-  FACTORIES_MAP,
-  FAKE_FACTORY,
-  PARENT_CONTAINER,
+  PARENT_CONTAINERS,
   ResolverError,
 } from './container';
-import {injectable} from './utils';
 import {optional, token} from './tokens';
+import {injectable} from './utils';
 
 const NUMBER = token<number>('number');
 const STRING = token<string>('string');
@@ -44,10 +42,10 @@ describe('Container', () => {
 
       const custom = createContainer();
       container.bindValue(CONTAINER, custom);
-      container.bindValue(PARENT_CONTAINER, custom);
+      container.bindValue(PARENT_CONTAINERS, [custom]);
 
       expect(container.get(CONTAINER)).toBe(container);
-      expect(container.get(PARENT_CONTAINER)).toBe(parent);
+      expect(container.get(PARENT_CONTAINERS)).toEqual([parent]);
     });
   });
 
@@ -120,24 +118,40 @@ describe('Container', () => {
         scope: 'scoped',
       });
 
-      expect(container.get(NUMBER)).toBe(21);
-      expect(container.get(NUMBER)).toBe(21);
-      expect(parent.get(NUMBER)).toBe(12);
-      expect(container.get(NUMBER)).toBe(21);
+      expect(container.get(NUMBER)).toBe(11);
+      expect(container.get(NUMBER)).toBe(11);
+      expect(parent.get(NUMBER)).toBe(11);
+      expect(container.get(NUMBER)).toBe(11);
+
+      expect(factory).toBeCalledTimes(1);
+    });
+
+    it('should inherit a factory with "scoped" scope', async () => {
+      const parentParent = createContainer();
+      let counter = 0;
+      const factory = jest.fn(() => ++counter);
+
+      parentParent.bindFactory(NUMBER, factory);
+
+      expect(parentParent.get(NUMBER)).toBe(1);
+
+      const parent = createContainer(parentParent);
+
+      parent.bindFactory(NUMBER, injectable(factory), {
+        scope: 'scoped',
+      });
+
+      expect(parent.get(NUMBER)).toBe(2);
+
+      const container = createContainer(parent);
+
+      expect(container.get(NUMBER)).toBe(2);
+      expect(parent.get(NUMBER)).toBe(2);
 
       expect(factory).toBeCalledTimes(2);
 
-      // Check for using the internal FAKE_FACTORY
-      const internalFactories = container.resolve(FACTORIES_MAP);
-      const fakeContext = internalFactories.get(NUMBER.symbol);
-      expect(fakeContext?.factory).toBe(FAKE_FACTORY);
-      expect(() => fakeContext?.factory?.(container)).toThrowError(
-        'FAKE_FACTORY',
-      );
-      const internalOnRemoved =
-        fakeContext?.options?.scope === 'scoped' &&
-        fakeContext?.options?.onRemoved;
-      expect(internalOnRemoved).toBeUndefined();
+      container.removeAll();
+      expect(parent.get(NUMBER)).toBe(2);
     });
 
     it('should bind a factory with "singleton" scope by default', () => {
@@ -165,6 +179,9 @@ describe('Container', () => {
       const container1 = createContainer(parent);
       const container2 = createContainer(parent);
       const container3 = createContainer(parent);
+      const childContainer1 = createContainer(container1);
+      const childContainer2 = createContainer(container2);
+      const childContainer3 = createContainer(container3);
 
       const START = token<number>();
       parent.bindValue(START, 0);
@@ -178,13 +195,33 @@ describe('Container', () => {
         scope: 'scoped',
       });
 
-      expect(container1.get(NUMBER)).toBe(11);
+      container1.bindFactory(NUMBER, injectable(factory, START), {
+        scope: 'scoped',
+      });
+
+      container2.bindFactory(NUMBER, injectable(factory, START), {
+        scope: 'scoped',
+      });
+
+      container3.bindFactory(NUMBER, injectable(factory, START), {
+        scope: 'scoped',
+      });
+
+      childContainer1.bindValue(START, 1);
+      childContainer2.bindValue(START, 2);
+      childContainer3.bindValue(START, 3);
+
       expect(container1.get(NUMBER)).toBe(11);
       expect(container2.get(NUMBER)).toBe(22);
-      expect(parent.get(NUMBER)).toBe(3);
+      expect(container3.get(NUMBER)).toBe(33);
+      expect(parent.get(NUMBER)).toBe(4);
       expect(container1.get(NUMBER)).toBe(11);
       expect(container2.get(NUMBER)).toBe(22);
-      expect(container3.get(NUMBER)).toBe(34);
+      expect(container3.get(NUMBER)).toBe(33);
+
+      expect(childContainer1.get(NUMBER)).toBe(11);
+      expect(childContainer2.get(NUMBER)).toBe(22);
+      expect(childContainer3.get(NUMBER)).toBe(33);
 
       expect(factory).toBeCalledTimes(4);
     });
@@ -228,12 +265,11 @@ describe('Container', () => {
       const parent = createContainer();
       const container = createContainer(parent);
 
-      const factory = () => createContainer();
-      container.bindFactory(CONTAINER, factory);
-      container.bindFactory(PARENT_CONTAINER, factory);
+      container.bindFactory(CONTAINER, () => createContainer());
+      container.bindFactory(PARENT_CONTAINERS, () => [createContainer()]);
 
       expect(container.get(CONTAINER)).toBe(container);
-      expect(container.get(PARENT_CONTAINER)).toBe(parent);
+      expect(container.get(PARENT_CONTAINERS)).toEqual([parent]);
     });
   });
 
@@ -284,25 +320,13 @@ describe('Container', () => {
       parent.bindFactory(NUMBER, factory, {scope: 'scoped', onRemoved});
 
       expect(parent.get(NUMBER)).toBe(1);
-      expect(container.get(NUMBER)).toBe(2);
-
-      // Check for using the internal FAKE_FACTORY
-      const internalFactories = container.resolve(FACTORIES_MAP);
-      const fakeContext = internalFactories.get(NUMBER.symbol);
-      expect(fakeContext?.factory).toBe(FAKE_FACTORY);
-      expect(() => fakeContext?.factory?.(container)).toThrowError(
-        'FAKE_FACTORY',
-      );
-      const internalOnRemoved =
-        fakeContext?.options?.scope === 'scoped' &&
-        fakeContext?.options?.onRemoved;
-      expect(internalOnRemoved).toBe(onRemoved);
+      expect(container.get(NUMBER)).toBe(1);
 
       // Continue the main test
       parent.remove(NUMBER);
       container.remove(NUMBER);
       expect(onRemoved).toHaveBeenNthCalledWith(1, 1);
-      expect(onRemoved).toHaveBeenNthCalledWith(2, 2);
+      expect(onRemoved).toHaveBeenCalledTimes(1);
     });
 
     it('should remove "transient" factory in case its value has never been resolved', () => {
@@ -333,10 +357,10 @@ describe('Container', () => {
       const container = createContainer(parent);
 
       container.remove(CONTAINER);
-      container.remove(PARENT_CONTAINER);
+      container.remove(PARENT_CONTAINERS);
 
       expect(container.get(CONTAINER)).toBe(container);
-      expect(container.get(PARENT_CONTAINER)).toBe(parent);
+      expect(container.get(PARENT_CONTAINERS)).toEqual([parent]);
     });
   });
 
@@ -389,7 +413,7 @@ describe('Container', () => {
       container.removeAll();
 
       expect(container.get(CONTAINER)).toBe(container);
-      expect(container.get(PARENT_CONTAINER)).toBe(parent);
+      expect(container.get(PARENT_CONTAINERS)).toEqual([parent]);
     });
   });
 
@@ -477,13 +501,13 @@ describe('Container', () => {
     it('should return the parent container for PARENT_CONTAINER token', () => {
       const parent = createContainer();
       const container = createContainer(parent);
-      const result = container.get(PARENT_CONTAINER);
-      expect(result).toBe(parent);
+      const result = container.get(PARENT_CONTAINERS);
+      expect(result).toEqual([parent]);
     });
 
     it('should return "undefined" for PARENT_CONTAINER token in case there is no parent container', () => {
       const container = createContainer();
-      const result = container.get(PARENT_CONTAINER);
+      const result = container.get(PARENT_CONTAINERS);
       expect(result).toBeUndefined();
     });
 
@@ -572,15 +596,15 @@ describe('Container', () => {
     it('should resolve PARENT_CONTAINER as the parent container', () => {
       const parent = createContainer();
       const container = createContainer(parent);
-      const result = container.get(PARENT_CONTAINER);
-      expect(result).toBe(parent);
+      const result = container.get(PARENT_CONTAINERS);
+      expect(result).toEqual([parent]);
     });
 
     it('should throw ResolverError for PARENT_CONTAINER token in case there is no parent container', () => {
       const container = createContainer();
-      expect(() => container.resolve(PARENT_CONTAINER)).toThrowError(
+      expect(() => container.resolve(PARENT_CONTAINERS)).toThrowError(
         new ResolverError(
-          `Token "${PARENT_CONTAINER.symbol.description}" is not provided`,
+          `Token "${PARENT_CONTAINERS.symbol.description}" is not provided`,
         ),
       );
     });
@@ -608,4 +632,60 @@ describe('Container', () => {
       expect(container.resolve(t2)).toBe(1);
     });
   });
+
+  describe('multiple parent containers', () => {
+    it('should expose all parent containers in order via PARENT_CONTAINERS', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      const child = createContainer([p1, p2]);
+
+      expect(child.get(PARENT_CONTAINERS)).toEqual([p1, p2]);
+    });
+
+    it('get(): should return a value from the first parent that provides it', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      p1.bindValue(NUMBER, 1);
+      p2.bindValue(NUMBER, 2);
+
+      const child = createContainer([p1, p2]);
+      expect(child.get(NUMBER)).toBe(1);
+    });
+
+    it('get(): should return a value from the next parent when previous parents do not provide it', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      p2.bindValue(NUMBER, 2);
+
+      const child = createContainer([p1, p2]);
+      expect(child.get(NUMBER)).toBe(2);
+    });
+
+    it('resolve(): should resolve a value from the first parent that provides it', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      p1.bindValue(NUMBER, 1);
+      p2.bindValue(NUMBER, 2);
+
+      const child = createContainer([p1, p2]);
+      expect(child.resolve(NUMBER)).toBe(1);
+    });
+
+    it('resolve(): should resolve a value from the next parent when previous parents do not provide it', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      p2.bindValue(NUMBER, 2);
+
+      const child = createContainer([p1, p2]);
+      expect(child.resolve(NUMBER)).toBe(2);
+    });
+
+    it('resolve(): should throw if none of the parents provide the value', () => {
+      const p1 = createContainer();
+      const p2 = createContainer();
+      const child = createContainer([p1, p2]);
+
+      expect(() => child.resolve(NUMBER)).toThrow(ResolverError);
+    });
+  });
 });

package/src/container.ts

@@ -20,8 +20,8 @@ export type FactoryScope = 'scoped' | 'singleton' | 'transient';
  * Options for factory binding.
  *
  * `scope` types:
- *   - `singleton` - **This is the default**. The value is created and cached by the container which registered the factory.
- *   - `scoped` - The value is created and cached by the container which starts resolving.
+ *   - `singleton` - **This is the default**. The value is created and cached by the most distant parent container which owns the factory function.
+ *   - `scoped` - The value is created and cached by the nearest container which owns the factory function.
  *   - `transient` - The value is created every time it is resolved.
  *
  * `scoped` and `singleton` scopes can have `onRemoved` callback. It is called when a token is removed from the container.
@@ -64,7 +64,7 @@ export type Container = {
   get<T>(token: Token<T>): T | undefined;
 
   /**
-   * Returns a resolved value by the token, or throws `ResolverError` in case the token is not found.
+   * Returns a resolved value by the token or throws `ResolverError` in case the token is not found.
    */
   resolve<T>(token: Token<T>): T;
 
@@ -82,7 +82,7 @@ export type Container = {
 /** @internal */
 export const CONTAINER: Token<Container> = token('ditox.Container');
 /** @internal */
-export const PARENT_CONTAINER: Token<Container> = token(
+export const PARENT_CONTAINERS: Token<ReadonlyArray<Container>> = token(
   'ditox.ParentContainer',
 );
 /** @internal */
@@ -91,11 +91,6 @@ export const RESOLVER: Token<Resolver> = token('ditox.Resolver');
 /** @internal */
 const NOT_FOUND = Symbol();
 
-/** @internal */
-export const FAKE_FACTORY = (): never => {
-  throw new Error('FAKE_FACTORY');
-};
-
 /** @internal */
 const DEFAULT_SCOPE: FactoryScope = 'singleton';
 
@@ -135,7 +130,7 @@ function getOnRemoved<T>(options: FactoryOptions<T>) {
 function isInternalToken<T>(token: Token<T>): boolean {
   return (
     token.symbol === CONTAINER.symbol ||
-    token.symbol === PARENT_CONTAINER.symbol ||
+    token.symbol === PARENT_CONTAINERS.symbol ||
     token.symbol === RESOLVER.symbol
   );
 }
@@ -145,9 +140,17 @@ function isInternalToken<T>(token: Token<T>): boolean {
  *
  * Container can have an optional parent to chain token resolution. The parent is used in case the current container does not have a registered token.
  *
- * @param parentContainer - Optional parent container.
+ * @param parentArg - Optional parent container or an array of containers.
  */
-export function createContainer(parentContainer?: Container): Container {
+export function createContainer(
+  parentArg?: Container | ReadonlyArray<Container>,
+): Container {
+  const parents: ReadonlyArray<Container> | undefined = parentArg
+    ? Array.isArray(parentArg)
+      ? [...parentArg]
+      : [parentArg]
+    : undefined;
+
   const values: ValuesMap = new Map<symbol, any>();
   const factories: FactoriesMap = new Map<symbol, FactoryContext<any>>();
 
@@ -202,7 +205,7 @@ export function createContainer(parentContainer?: Container): Container {
       return (
         values.has(token.symbol) ||
         factories.has(token.symbol) ||
-        (parentContainer?.hasToken(token) ?? false)
+        parentContainersHaveToken(parents, token)
       );
     },
 
@@ -247,14 +250,14 @@ export function createContainer(parentContainer?: Container): Container {
     }
 
     const factoryContext = factories.get(token.symbol);
-    if (factoryContext && factoryContext.factory !== FAKE_FACTORY) {
+    if (factoryContext) {
       const scope = getScope(factoryContext.options);
 
       switch (scope) {
         case 'singleton': {
           if (hasValue) {
             return value;
-          } else if (parentContainer?.hasToken(token)) {
+          } else if (parentContainersHaveToken(parents, token)) {
             break;
           } else {
             // Cache the value in the same container where the factory is registered.
@@ -265,16 +268,14 @@ export function createContainer(parentContainer?: Container): Container {
         }
 
         case 'scoped': {
-          // Create a value within the origin container and cache it.
-          const value = factoryContext.factory(origin);
-          origin.bindValue(token, value);
-
-          if (origin !== container) {
-            // Bind a fake factory with actual options to make onRemoved() works.
-            origin.bindFactory(token, FAKE_FACTORY, factoryContext.options);
+          if (hasValue) {
+            return value;
+          } else {
+            // Create a value within the factory's container and cache it.
+            const value = factoryContext.factory(container);
+            container.bindValue(token, value);
+            return value;
           }
-
-          return value;
         }
 
         case 'transient': {
@@ -288,9 +289,8 @@ export function createContainer(parentContainer?: Container): Container {
       return value;
     }
 
-    const parentResolver = parentContainer?.get(RESOLVER);
-    if (parentResolver) {
-      return parentResolver(token, origin);
+    if (parents) {
+      return parentContainersResolveToken(parents, token, origin);
     }
 
     return NOT_FOUND;
@@ -314,11 +314,44 @@ export function createContainer(parentContainer?: Container): Container {
     values.set(RESOLVER.symbol, resolver);
     values.set(FACTORIES_MAP.symbol, factories);
 
-    if (parentContainer) {
-      values.set(PARENT_CONTAINER.symbol, parentContainer);
+    if (parents) {
+      values.set(PARENT_CONTAINERS.symbol, parents);
     }
   }
 
   bindInternalTokens();
   return container;
 }
+
+function parentContainersHaveToken<T>(
+  parents: ReadonlyArray<Container> | undefined,
+  token: Token<T>,
+): boolean {
+  if (!parents) return false;
+
+  for (let i = 0; i < parents.length; i++) {
+    if (parents[i].hasToken(token)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function parentContainersResolveToken<T>(
+  parents: ReadonlyArray<Container>,
+  token: Token<T>,
+  origin: Container,
+): T | typeof NOT_FOUND {
+  for (const parentContainer of parents) {
+    const parentResolver = parentContainer.get(RESOLVER);
+    if (parentResolver) {
+      const resolved = parentResolver(token, origin);
+      if (resolved !== NOT_FOUND) {
+        return resolved;
+      }
+    }
+  }
+
+  return NOT_FOUND;
+}

package/src/modules.test.ts

@@ -7,8 +7,8 @@ import {
   Module,
   ModuleDeclaration,
 } from './modules';
-import {injectable} from './utils';
 import {token} from './tokens';
+import {injectable} from './utils';
 
 describe('bindModule()', () => {
   type TestQueries = {getValue: () => number};
@@ -107,8 +107,8 @@ describe('bindModule()', () => {
     const container = createContainer(parent);
 
     bindModule(parent, MODULE, {scope: 'scoped'});
-    expect(parent.get(MODULE_TOKEN)).not.toBe(container.get(MODULE_TOKEN));
-    expect(parent.get(QUERIES_TOKEN)).not.toBe(container.get(QUERIES_TOKEN));
+    expect(parent.get(MODULE_TOKEN)).toBe(container.get(MODULE_TOKEN));
+    expect(parent.get(QUERIES_TOKEN)).toBe(container.get(QUERIES_TOKEN));
   });
 
   it('should remove "singleton" module when a container is cleaning', () => {
@@ -149,11 +149,12 @@ describe('bindModule()', () => {
     parent.resolve(MODULE_TOKEN);
     container.resolve(MODULE_TOKEN);
 
-    parent.removeAll();
-    expect(destroy).toBeCalledTimes(1);
-
     destroy.mockClear();
     container.removeAll();
+    expect(destroy).toBeCalledTimes(0);
+
+    destroy.mockClear();
+    parent.removeAll();
     expect(destroy).toBeCalledTimes(1);
   });
 
@@ -227,6 +228,68 @@ describe('bindModule()', () => {
     expect(container.resolve(ARG_TOKEN)).toBe('12');
     expect(container.resolve(RESULT_TOKEN)).toBe('123');
   });
+
+  it('should call beforeBinding() and afterBinding() in deep-first order', () => {
+    const route: string[] = [];
+
+    const declareTestModule = (
+      id: string,
+      imports?: ModuleDeclaration<Record<string, any>>[],
+    ) =>
+      declareModule({
+        imports,
+        beforeBinding: () => route.push(`${id}:before`),
+        factory: (container) => {
+          imports?.forEach((m) => container.resolve(m.token));
+          route.push(`${id}:factory`);
+          return {};
+        },
+        afterBinding: () => route.push(`${id}:after`),
+      });
+
+    /**
+     *       m1
+     *     / | \
+     *   m2 m3 m4
+     *  / \  \ |
+     * m5 m6  m7
+     */
+    const m7 = declareTestModule('m7');
+    const m6 = declareTestModule('m6');
+    const m5 = declareTestModule('m5');
+    const m4 = declareTestModule('m4', [m7]);
+    const m3 = declareTestModule('m3', [m7]);
+    const m2 = declareTestModule('m2', [m5, m6]);
+    const m1 = declareTestModule('m1', [m2, m3, m4]);
+
+    const container = createContainer();
+    bindModule(container, m1);
+    container.resolve(m1.token);
+
+    expect(route).toEqual([
+      'm1:before',
+      'm2:before',
+      'm3:before',
+      'm4:before',
+      'm5:before',
+      'm6:before',
+      'm7:before',
+      'm7:after',
+      'm6:after',
+      'm5:after',
+      'm4:after',
+      'm3:after',
+      'm2:after',
+      'm1:after',
+      'm5:factory',
+      'm6:factory',
+      'm2:factory',
+      'm7:factory',
+      'm3:factory',
+      'm4:factory',
+      'm1:factory',
+    ]);
+  });
 });
 
 describe('bindModules()', () => {