ditox 3.2.0 → 3.3.1

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]);
@@ -386,4 +521,22 @@ describe('declareModuleBindings()', () => {
 
     expect(container.get(MODULE_BINDINGS.token)).toEqual({});
   });
+
+  it('should ignore falsy tokens in exports', () => {
+    const container = createContainer();
+
+    const MODULE = declareModule({
+      factory: () => ({
+        valid: 1,
+        invalid: 2,
+      }),
+      exports: {
+        valid: token(),
+        invalid: undefined,
+      } as any,
+    });
+
+    bindModule(container, MODULE);
+    expect(container.get(MODULE.token)).toEqual({ valid: 1, invalid: 2 });
+  });
 });

package/src/modules.ts

@@ -1,6 +1,6 @@
-import {Container} from './container';
-import {Token, token} from './tokens';
-import {injectable} from './utils';
+import { Container } from './container';
+import { Token, token } from './tokens';
+import { injectable } from './utils';
 
 type AnyObject = Record<string, any>;
 type EmptyObject = Record<string, never>;
@@ -65,6 +65,13 @@ export type ModuleDeclaration<T extends Module<AnyObject>> = {
 
   /** Callback could be used to export complex dependencies from the module. It is called after binding the module.  */
   afterBinding?: (container: Container) => void;
+
+  /**
+   * Strategy for executing the factory:
+   *   - `lazy` - **This is the default**. The factory is called when the module is resolved.
+   *   - `eager` - The factory is called immediately after the module is bound to the container.
+   */
+  strategy?: 'eager' | 'lazy';
 };
 
 export type AnyModuleDeclaration = ModuleDeclaration<Module<AnyObject>>;
@@ -145,6 +152,14 @@ export function bindModule<T extends Module<AnyObject>>(
     const m = 'module' in entry ? entry.module : entry;
     m.afterBinding?.(container);
   }
+
+  for (let i = bfsQueue.length - 1; i >= 0; i--) {
+    const entry = bfsQueue[i];
+    const m = 'module' in entry ? entry.module : entry;
+    if (m.strategy === 'eager') {
+      container.resolve(m.token);
+    }
+  }
 }
 
 function bindModuleEntry(
@@ -176,7 +191,7 @@ function bindModuleEntry(
         container.bindFactory(
           valueToken,
           injectable((module) => module[valueKey], module.token),
-          {scope},
+          { scope },
         );
       }
     });
@@ -240,10 +255,12 @@ export function declareModule<T extends Module<AnyObject>>(
   declaration: Omit<ModuleDeclaration<T>, 'token'> &
     Partial<Pick<ModuleDeclaration<T>, 'token'>>,
 ): ModuleDeclaration<T> {
-  return {...declaration, token: declaration.token ?? token()};
+  return { ...declaration, token: declaration.token ?? token() };
 }
 
 /**
+ * @deprecated Use `declareModule` instead
+ *
  * Declares bindings of several modules
  *
  * @param modules - module declaration entries