ditox 3.1.0 → 3.3.0

package/src/container.test.ts

@@ -1,11 +1,12 @@
+import { describe, expect, it, test, vi } from 'vitest';
 import {
   CONTAINER,
   createContainer,
   PARENT_CONTAINERS,
   ResolverError,
 } from './container';
-import {optional, token} from './tokens';
-import {injectable} from './utils';
+import { optional, token } from './tokens';
+import { injectable } from './utils';
 
 const NUMBER = token<number>('number');
 const STRING = token<string>('string');
@@ -28,7 +29,7 @@ describe('Container', () => {
     it('should bind a result of a factory and prevent invoking it', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 1);
+      const factory = vi.fn(() => 1);
       container.bindFactory(NUMBER, factory);
       container.bindValue(NUMBER, 2);
 
@@ -54,7 +55,7 @@ describe('Container', () => {
       const container = createContainer();
 
       let containerArg;
-      const factory = jest.fn((arg) => {
+      const factory = vi.fn((arg) => {
         containerArg = arg;
         return 1;
       });
@@ -68,8 +69,8 @@ describe('Container', () => {
     it('should rebind a factory in case it was bound', () => {
       const container = createContainer();
 
-      const factory1 = jest.fn(() => 1);
-      const factory2 = jest.fn(() => 2);
+      const factory1 = vi.fn(() => 1);
+      const factory2 = vi.fn(() => 2);
       container.bindFactory(NUMBER, factory1);
       container.bindFactory(NUMBER, factory2);
 
@@ -87,7 +88,7 @@ describe('Container', () => {
       container.bindValue(START, 20);
 
       let counter = 0;
-      const factory = jest.fn((start) => start + ++counter);
+      const factory = vi.fn((start) => start + ++counter);
       parent.bindFactory(NUMBER, injectable(factory, START), {
         scope: 'singleton',
       });
@@ -113,7 +114,7 @@ describe('Container', () => {
       container.bindValue(START, 20);
 
       let counter = 0;
-      const factory = jest.fn((start) => start + ++counter);
+      const factory = vi.fn((start) => start + ++counter);
       parent.bindFactory(NUMBER, injectable(factory, START), {
         scope: 'scoped',
       });
@@ -129,7 +130,7 @@ describe('Container', () => {
     it('should inherit a factory with "scoped" scope', async () => {
       const parentParent = createContainer();
       let counter = 0;
-      const factory = jest.fn(() => ++counter);
+      const factory = vi.fn(() => ++counter);
 
       parentParent.bindFactory(NUMBER, factory);
 
@@ -163,7 +164,7 @@ describe('Container', () => {
       container.bindValue(START, 20);
 
       let counter = 0;
-      const factory = jest.fn((start) => start + ++counter);
+      const factory = vi.fn((start) => start + ++counter);
       parent.bindFactory(NUMBER, injectable(factory, START));
 
       expect(container.get(NUMBER)).toBe(11);
@@ -190,7 +191,7 @@ describe('Container', () => {
       container3.bindValue(START, 30);
 
       let counter = 0;
-      const factory = jest.fn((start) => start + ++counter);
+      const factory = vi.fn((start) => start + ++counter);
       parent.bindFactory(NUMBER, injectable(factory, START), {
         scope: 'scoped',
       });
@@ -235,7 +236,7 @@ describe('Container', () => {
       container.bindValue(START, 20);
 
       let counter = 0;
-      const factory = jest.fn((start) => start + ++counter);
+      const factory = vi.fn((start) => start + ++counter);
       parent.bindFactory(NUMBER, injectable(factory, START), {
         scope: 'transient',
       });
@@ -251,9 +252,9 @@ describe('Container', () => {
     it('should bind a factory with "onRemoved" callback', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 1);
-      const callback = jest.fn();
-      container.bindFactory(NUMBER, factory, {onRemoved: callback});
+      const factory = vi.fn(() => 1);
+      const callback = vi.fn();
+      container.bindFactory(NUMBER, factory, { onRemoved: callback });
 
       expect(container.get(NUMBER)).toBe(1);
       container.remove(NUMBER);
@@ -284,9 +285,9 @@ describe('Container', () => {
     it('should remove "singleton" factory silently in case its value has never been resolved', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 1);
-      const onRemoved = jest.fn();
-      container.bindFactory(NUMBER, factory, {scope: 'singleton', onRemoved});
+      const factory = vi.fn(() => 1);
+      const onRemoved = vi.fn();
+      container.bindFactory(NUMBER, factory, { scope: 'singleton', onRemoved });
       container.remove(NUMBER);
 
       expect(container.get(NUMBER)).toBeUndefined();
@@ -297,9 +298,9 @@ describe('Container', () => {
     it('should remove "singleton" factory with calling "onRemoved" in case its value has been resolved', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 100);
-      const onRemoved = jest.fn();
-      container.bindFactory(NUMBER, factory, {scope: 'singleton', onRemoved});
+      const factory = vi.fn(() => 100);
+      const onRemoved = vi.fn();
+      container.bindFactory(NUMBER, factory, { scope: 'singleton', onRemoved });
 
       expect(container.get(NUMBER)).toBe(100);
       container.remove(NUMBER);
@@ -315,9 +316,9 @@ describe('Container', () => {
       const container = createContainer(parent);
 
       let count = 1;
-      const factory = jest.fn(() => count++);
-      const onRemoved = jest.fn();
-      parent.bindFactory(NUMBER, factory, {scope: 'scoped', onRemoved});
+      const factory = vi.fn(() => count++);
+      const onRemoved = vi.fn();
+      parent.bindFactory(NUMBER, factory, { scope: 'scoped', onRemoved });
 
       expect(parent.get(NUMBER)).toBe(1);
       expect(container.get(NUMBER)).toBe(1);
@@ -332,8 +333,8 @@ describe('Container', () => {
     it('should remove "transient" factory in case its value has never been resolved', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 1);
-      container.bindFactory(NUMBER, factory, {scope: 'transient'});
+      const factory = vi.fn(() => 1);
+      container.bindFactory(NUMBER, factory, { scope: 'transient' });
       container.remove(NUMBER);
 
       expect(container.get(NUMBER)).toBeUndefined();
@@ -343,8 +344,8 @@ describe('Container', () => {
     it('should remove "transient" factory in case its value has been resolved', () => {
       const container = createContainer();
 
-      const factory = jest.fn(() => 1);
-      container.bindFactory(NUMBER, factory, {scope: 'transient'});
+      const factory = vi.fn(() => 1);
+      container.bindFactory(NUMBER, factory, { scope: 'transient' });
       expect(container.get(NUMBER)).toBe(1);
 
       container.remove(NUMBER);
@@ -382,8 +383,8 @@ describe('Container', () => {
       const F1 = token('f1');
       const F2 = token('f2');
 
-      const unbind1 = jest.fn();
-      const unbind2 = jest.fn();
+      const unbind1 = vi.fn();
+      const unbind2 = vi.fn();
 
       const container = createContainer();
       container.bindFactory(F1, () => 10, {
@@ -419,7 +420,7 @@ describe('Container', () => {
 
   describe('hasToken()', () => {
     it('should check if a container hierarchy has the token', () => {
-      const factory = jest.fn();
+      const factory = vi.fn();
 
       const token1 = token();
       const token2 = token();
@@ -621,8 +622,8 @@ describe('Container', () => {
 
     it('should resolve a value by shared tokens', () => {
       const key = 'token-' + Date.now();
-      const t1 = token({key});
-      const t2 = token({key});
+      const t1 = token({ key });
+      const t2 = token({ key });
       expect(t1).not.toBe(t2);
 
       const container = createContainer();

package/src/container.ts

@@ -1,4 +1,4 @@
-import {Token, token} from './tokens';
+import { Token, token } from './tokens';
 
 /**
  * ResolverError is thrown by the resolver when a token is not found in a container.
@@ -79,6 +79,12 @@ export type Container = {
   removeAll(): void;
 };
 
+/**
+ * A subset of Container interface that provides read-only access to dependency resolution.
+ * This type is used for parent containers to allow token resolution without exposing mutation methods.
+ */
+export type ContainerResolver = Pick<Container, 'hasToken' | 'get' | 'resolve'>;
+
 /** @internal */
 export const CONTAINER: Token<Container> = token('ditox.Container');
 /** @internal */
@@ -143,9 +149,9 @@ function isInternalToken<T>(token: Token<T>): boolean {
  * @param parentArg - Optional parent container or an array of containers.
  */
 export function createContainer(
-  parentArg?: Container | ReadonlyArray<Container>,
+  parentArg?: ContainerResolver | ReadonlyArray<ContainerResolver>,
 ): Container {
-  const parents: ReadonlyArray<Container> | undefined = parentArg
+  const parents: ReadonlyArray<ContainerResolver> | undefined = parentArg
     ? Array.isArray(parentArg)
       ? [...parentArg]
       : [parentArg]
@@ -172,7 +178,7 @@ export function createContainer(
         return;
       }
 
-      factories.set(token.symbol, {factory, options});
+      factories.set(token.symbol, { factory, options });
     },
 
     remove<T>(token: Token<T>): void {
@@ -324,7 +330,7 @@ export function createContainer(
 }
 
 function parentContainersHaveToken<T>(
-  parents: ReadonlyArray<Container> | undefined,
+  parents: ReadonlyArray<ContainerResolver> | undefined,
   token: Token<T>,
 ): boolean {
   if (!parents) return false;
@@ -339,7 +345,7 @@ function parentContainersHaveToken<T>(
 }
 
 function parentContainersResolveToken<T>(
-  parents: ReadonlyArray<Container>,
+  parents: ReadonlyArray<ContainerResolver>,
   token: Token<T>,
   origin: Container,
 ): T | typeof NOT_FOUND {

package/src/index.ts

@@ -1,29 +1,32 @@
-export {token, optional} from './tokens';
-export type {RequiredToken, OptionalToken, Token} from './tokens';
-
-export {ResolverError, createContainer} from './container';
-export type {FactoryScope, FactoryOptions, Container} from './container';
-
-export {
-  isToken,
-  bindMultiValue,
-  tryResolveValue,
-  tryResolveValues,
-  resolveValue,
-  resolveValues,
-  injectable,
-  injectableClass,
-} from './utils';
-
+export type {
+  Container,
+  ContainerResolver,
+  FactoryOptions,
+  FactoryScope,
+} from './container';
+export { createContainer, ResolverError } from './container';
+export type {
+  AnyModuleDeclaration,
+  BindModuleOptions,
+  Module,
+  ModuleBindingEntry,
+  ModuleDeclaration,
+} from './modules';
 export {
   bindModule,
   bindModules,
   declareModule,
   declareModuleBindings,
 } from './modules';
-export type {
-  Module,
-  ModuleDeclaration,
-  BindModuleOptions,
-  ModuleBindingEntry,
-} from './modules';
+export type { OptionalToken, RequiredToken, Token } from './tokens';
+export { optional, token } from './tokens';
+export {
+  bindMultiValue,
+  injectable,
+  injectableClass,
+  isToken,
+  resolveValue,
+  resolveValues,
+  tryResolveValue,
+  tryResolveValues,
+} from './utils';

package/src/modules.test.ts

@@ -1,18 +1,20 @@
-import {createContainer} from './container';
+import { describe, expect, it, vi } from 'vitest';
+import { createContainer } from './container';
 import {
   bindModule,
   bindModules,
   declareModule,
   declareModuleBindings,
   Module,
+  ModuleBindingEntry,
   ModuleDeclaration,
 } from './modules';
-import {token} from './tokens';
-import {injectable} from './utils';
+import { token } from './tokens';
+import { injectable } from './utils';
 
 describe('bindModule()', () => {
-  type TestQueries = {getValue: () => number};
-  type TestModule = Module<{queries: TestQueries}>;
+  type TestQueries = { getValue: () => number };
+  type TestModule = Module<{ queries: TestQueries }>;
 
   const MODULE_TOKEN = token<TestModule>();
   const QUERIES_TOKEN = token<TestQueries>();
@@ -39,7 +41,7 @@ describe('bindModule()', () => {
   });
 
   it('should destroy the module on removing the module token and remove tokens of its exported props', () => {
-    const destroy = jest.fn();
+    const destroy = vi.fn();
     const container = createContainer();
 
     bindModule(container, {
@@ -65,10 +67,10 @@ describe('bindModule()', () => {
     const token1 = token();
     const token2 = token();
 
-    const beforeBinding = jest.fn((container) =>
+    const beforeBinding = vi.fn((container) =>
       container.bindValue(token1, 'foo'),
     );
-    const afterBinding = jest.fn((container) => {
+    const afterBinding = vi.fn((container) => {
       const value = container.resolve(QUERIES_TOKEN).getValue();
       container.bindValue(token2, value * 10);
     });
@@ -86,6 +88,139 @@ describe('bindModule()', () => {
     expect(container.resolve(token2)).toBe(10);
   });
 
+  it('should support "eager" strategy', () => {
+    const container = createContainer();
+    const factory = vi.fn(() => ({}));
+
+    const MODULE = declareModule({
+      factory,
+      strategy: 'eager',
+    });
+
+    bindModule(container, MODULE);
+    expect(factory).toBeCalledTimes(1);
+  });
+
+  it('should support "lazy" strategy by default', () => {
+    const container = createContainer();
+    const factory = vi.fn(() => ({}));
+
+    const MODULE = declareModule({
+      factory,
+    });
+
+    bindModule(container, MODULE);
+    expect(factory).toBeCalledTimes(0);
+
+    container.resolve(MODULE.token);
+    expect(factory).toBeCalledTimes(1);
+  });
+
+  it('should support "eager" strategy in imports', () => {
+    const container = createContainer();
+    const factory1 = vi.fn(() => ({}));
+    const factory2 = vi.fn(() => ({}));
+
+    const MODULE1 = declareModule({
+      factory: factory1,
+      strategy: 'eager',
+    });
+
+    const MODULE2 = declareModule({
+      factory: factory2,
+      imports: [MODULE1],
+    });
+
+    bindModule(container, MODULE2);
+    expect(factory1).toBeCalledTimes(1);
+    expect(factory2).toBeCalledTimes(0);
+  });
+
+  it('should throw an error during binding if "eager" factory fails', () => {
+    const container = createContainer();
+    const error = new Error('Eager factory failed');
+    const factory = vi.fn(() => {
+      throw error;
+    });
+
+    const MODULE = declareModule({
+      factory,
+      strategy: 'eager',
+    });
+
+    expect(() => bindModule(container, MODULE)).toThrow(error);
+  });
+
+  it('should throw an error during binding if imported "eager" factory fails', () => {
+    const container = createContainer();
+    const error = new Error('Eager factory failed');
+    const factory1 = vi.fn(() => {
+      throw error;
+    });
+
+    const MODULE1 = declareModule({
+      factory: factory1,
+      strategy: 'eager',
+    });
+
+    const MODULE2 = declareModule({
+      factory: () => ({}),
+      imports: [MODULE1],
+    });
+
+    expect(() => bindModule(container, MODULE2)).toThrow(error);
+  });
+
+  it('should execute "eager" factories in reverse BFS order', () => {
+    const route: string[] = [];
+
+    const declareEagerModule = (id: string, imports?: ModuleBindingEntry[]) =>
+      declareModule({
+        imports,
+        strategy: 'eager',
+        factory: () => {
+          route.push(id);
+          return {};
+        },
+      });
+
+    /**
+     * Structure:
+     *       m1
+     *     / | \
+     *   m2 m3 m4
+     *
+     * BFS order: m1, m2, m3, m4
+     * Expected execution order (reverse): m4, m3, m2, m1
+     */
+    const m4 = declareEagerModule('m4');
+    const m3 = declareEagerModule('m3');
+    const m2 = declareEagerModule('m2');
+    const m1 = declareEagerModule('m1', [m2, m3, m4]);
+
+    const container = createContainer();
+    bindModule(container, m1);
+
+    expect(route).toEqual(['m4', 'm3', 'm2', 'm1']);
+  });
+
+  it('should throw an error during resolution if "lazy" factory fails', () => {
+    const container = createContainer();
+    const error = new Error('Lazy factory failed');
+    const factory = vi.fn(() => {
+      throw error;
+    });
+
+    const MODULE = declareModule({
+      factory,
+    });
+
+    bindModule(container, MODULE);
+    expect(factory).toBeCalledTimes(0);
+
+    expect(() => container.resolve(MODULE.token)).toThrow(error);
+  });
+
   it('should bind the module as singleton by default', () => {
     const parent = createContainer();
     const container = createContainer(parent);
@@ -98,7 +233,7 @@ describe('bindModule()', () => {
     const parent = createContainer();
     const container = createContainer(parent);
 
-    bindModule(parent, MODULE, {scope: 'singleton'});
+    bindModule(parent, MODULE, { scope: 'singleton' });
     expect(parent.get(MODULE_TOKEN)).toBe(container.get(MODULE_TOKEN));
   });
 
@@ -106,7 +241,7 @@ describe('bindModule()', () => {
     const parent = createContainer();
     const container = createContainer(parent);
 
-    bindModule(parent, MODULE, {scope: 'scoped'});
+    bindModule(parent, MODULE, { scope: 'scoped' });
     expect(parent.get(MODULE_TOKEN)).toBe(container.get(MODULE_TOKEN));
     expect(parent.get(QUERIES_TOKEN)).toBe(container.get(QUERIES_TOKEN));
   });
@@ -115,10 +250,10 @@ describe('bindModule()', () => {
     const parent = createContainer();
     const container = createContainer(parent);
 
-    const destroy = jest.fn();
+    const destroy = vi.fn();
     bindModule(parent, {
       token: MODULE_TOKEN,
-      factory: (container) => ({...MODULE.factory(container), destroy}),
+      factory: (container) => ({ ...MODULE.factory(container), destroy }),
     });
 
     parent.resolve(MODULE_TOKEN);
@@ -134,12 +269,12 @@ describe('bindModule()', () => {
     const parent = createContainer();
     const container = createContainer(parent);
 
-    const destroy = jest.fn();
+    const destroy = vi.fn();
     bindModule(
       parent,
       {
         token: MODULE_TOKEN,
-        factory: (container) => ({...MODULE.factory(container), destroy}),
+        factory: (container) => ({ ...MODULE.factory(container), destroy }),
       },
       {
         scope: 'scoped',
@@ -159,23 +294,23 @@ describe('bindModule()', () => {
   });
 
   it('should bind modules and binding entries from "imports" to the container', () => {
-    type TestModule = Module<{value: number}>;
+    type TestModule = Module<{ value: number }>;
 
     const MODULE1_TOKEN = token<TestModule>();
     const MODULE1: ModuleDeclaration<TestModule> = {
       token: MODULE1_TOKEN,
-      factory: () => ({value: 1}),
+      factory: () => ({ value: 1 }),
     };
 
     const MODULE2_TOKEN = token<TestModule>();
     const MODULE2: ModuleDeclaration<TestModule> = {
       token: MODULE2_TOKEN,
-      factory: () => ({value: 2}),
+      factory: () => ({ value: 2 }),
     };
 
     const MODULE2_ALTERED: ModuleDeclaration<TestModule> = {
       token: MODULE2_TOKEN,
-      factory: () => ({value: 22}),
+      factory: () => ({ value: 22 }),
     };
 
     const parent = createContainer();
@@ -188,7 +323,7 @@ describe('bindModule()', () => {
         factory: () => ({}),
         imports: [
           MODULE1,
-          {module: MODULE2_ALTERED, options: {scope: 'scoped'}},
+          { module: MODULE2_ALTERED, options: { scope: 'scoped' } },
         ],
       }),
     );
@@ -204,13 +339,13 @@ describe('bindModule()', () => {
     const ARG_TOKEN = token<string>('arg');
     const RESULT_TOKEN = token<string>('result');
 
-    type TestModule = Module<{value: string}>;
+    type TestModule = Module<{ value: string }>;
 
     const MODULE1: ModuleDeclaration<TestModule> = declareModule({
       beforeBinding: (container) =>
         container.bindValue(ARG_TOKEN, container.resolve(ARG_TOKEN) + '2'),
-      factory: injectable((arg) => ({value: arg + '3'}), ARG_TOKEN),
-      exports: {value: RESULT_TOKEN},
+      factory: injectable((arg) => ({ value: arg + '3' }), ARG_TOKEN),
+      exports: { value: RESULT_TOKEN },
     });
 
     const container = createContainer();
@@ -293,23 +428,23 @@ describe('bindModule()', () => {
 });
 
 describe('bindModules()', () => {
-  type TestModule = Module<{value: number}>;
+  type TestModule = Module<{ value: number }>;
 
   const MODULE1_TOKEN = token<TestModule>();
   const MODULE1: ModuleDeclaration<TestModule> = {
     token: MODULE1_TOKEN,
-    factory: () => ({value: 1}),
+    factory: () => ({ value: 1 }),
   };
 
   const MODULE2_TOKEN = token<TestModule>();
   const MODULE2: ModuleDeclaration<TestModule> = {
     token: MODULE2_TOKEN,
-    factory: () => ({value: 2}),
+    factory: () => ({ value: 2 }),
   };
 
   const MODULE2_ALTERED: ModuleDeclaration<TestModule> = {
     token: MODULE2_TOKEN,
-    factory: () => ({value: 22}),
+    factory: () => ({ value: 22 }),
   };
 
   it('should bind modules and binding entries to the container', () => {
@@ -320,7 +455,7 @@ describe('bindModules()', () => {
 
     bindModules(container, [
       MODULE1,
-      {module: MODULE2_ALTERED, options: {scope: 'scoped'}},
+      { module: MODULE2_ALTERED, options: { scope: 'scoped' } },
     ]);
 
     expect(parent.get(MODULE1_TOKEN)).toBeUndefined();
@@ -336,16 +471,16 @@ describe('declareModule()', () => {
     const container = createContainer();
 
     const VALUE_TOKEN = token<number>();
-    const MODULE_TOKEN = token<Module<{value: number}>>();
+    const MODULE_TOKEN = token<Module<{ value: number }>>();
     const MODULE = declareModule({
       token: MODULE_TOKEN,
-      factory: () => ({value: 1}),
-      exports: {value: VALUE_TOKEN},
+      factory: () => ({ value: 1 }),
+      exports: { value: VALUE_TOKEN },
     });
 
     bindModule(container, MODULE);
     expect(container.get(VALUE_TOKEN)).toBe(1);
-    expect(container.get(MODULE_TOKEN)).toEqual({value: 1});
+    expect(container.get(MODULE_TOKEN)).toEqual({ value: 1 });
   });
 
   it('should declare a binding for the anonymous module', () => {
@@ -353,8 +488,8 @@ describe('declareModule()', () => {
 
     const VALUE_TOKEN = token<number>();
     const MODULE = declareModule({
-      factory: () => ({value: 1}),
-      exports: {value: VALUE_TOKEN},
+      factory: () => ({ value: 1 }),
+      exports: { value: VALUE_TOKEN },
     });
 
     bindModule(container, MODULE);
@@ -368,14 +503,14 @@ describe('declareModuleBindings()', () => {
 
     const VALUE1_TOKEN = token<number>();
     const MODULE1 = declareModule({
-      factory: () => ({value: 1}),
-      exports: {value: VALUE1_TOKEN},
+      factory: () => ({ value: 1 }),
+      exports: { value: VALUE1_TOKEN },
     });
 
     const VALUE2_TOKEN = token<number>();
     const MODULE2 = declareModule({
-      factory: () => ({value: 2}),
-      exports: {value: VALUE2_TOKEN},
+      factory: () => ({ value: 2 }),
+      exports: { value: VALUE2_TOKEN },
     });
 
     const MODULE_BINDINGS = declareModuleBindings([MODULE1, MODULE2]);