ditox 1.4.0 → 2.1.0

package/docs/classes/{resolvererror.md → ResolverError.md}

@@ -8,25 +8,25 @@ ResolverError is thrown by the resolver when a token is not found in a container
 
 - `Error`
 
-  ↳ **ResolverError**
+  ↳ **`ResolverError`**
 
 ## Table of contents
 
 ### Constructors
 
-- [constructor](resolvererror.md#constructor)
+- [constructor](ResolverError.md#constructor)
 
 ### Properties
 
-- [message](resolvererror.md#message)
-- [name](resolvererror.md#name)
-- [stack](resolvererror.md#stack)
-- [prepareStackTrace](resolvererror.md#preparestacktrace)
-- [stackTraceLimit](resolvererror.md#stacktracelimit)
+- [message](ResolverError.md#message)
+- [name](ResolverError.md#name)
+- [stack](ResolverError.md#stack)
+- [prepareStackTrace](ResolverError.md#preparestacktrace)
+- [stackTraceLimit](ResolverError.md#stacktracelimit)
 
 ### Methods
 
-- [captureStackTrace](resolvererror.md#capturestacktrace)
+- [captureStackTrace](ResolverError.md#capturestacktrace)
 
 ## Constructors
 
@@ -46,7 +46,7 @@ Error.constructor
 
 #### Defined in
 
-[packages/ditox/src/ditox.ts:60](https://github.com/mnasyrov/ditox/blob/8ebabbb/packages/ditox/src/ditox.ts#L60)
+[packages/ditox/src/ditox.ts:61](https://github.com/mnasyrov/ditox/blob/aea7a8f/packages/ditox/src/ditox.ts#L61)
 
 ## Properties
 
@@ -60,7 +60,7 @@ Error.message
 
 #### Defined in
 
-node_modules/typescript/lib/lib.es5.d.ts:974
+node_modules/typescript/lib/lib.es5.d.ts:1023
 
 ___
 
@@ -74,7 +74,7 @@ Error.name
 
 #### Defined in
 
-node_modules/typescript/lib/lib.es5.d.ts:973
+node_modules/typescript/lib/lib.es5.d.ts:1022
 
 ___
 
@@ -88,7 +88,7 @@ Error.stack
 
 #### Defined in
 
-node_modules/typescript/lib/lib.es5.d.ts:975
+node_modules/typescript/lib/lib.es5.d.ts:1024
 
 ___
 
@@ -102,6 +102,8 @@ ___
 
 Optional override for formatting stack traces
 
+**`see`** https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
 ##### Parameters
 
 | Name | Type |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ditox",
-  "version": "1.4.0",
-  "description": "Detoxed dependency injection for JS, Typescript and Flow.",
+  "version": "2.1.0",
+  "description": "Powerful dependency injection container for building modular apps.",
   "license": "MIT",
   "author": "Mikhail Nasyrov <mikhail@mnasyrov.com> (https://github.com/mnasyrov)",
   "homepage": "https://github.com/mnasyrov/ditox",
@@ -22,31 +22,30 @@
   "engines": {
     "node": ">=12"
   },
-  "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.module.js",
-  "jsnext:main": "dist/index.module.js",
-  "unpkg": "dist/index.umd.js",
-  "umd:main": "dist/index.umd.js",
-  "browser": "dist/index.browser.js",
-  "react-native": "dist/index.browser.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "jsnext:main": "dist/esm/index.js",
+  "unpkg": "dist/umd/index.js",
+  "umd:main": "dist/umd/index.js",
+  "browser": "dist/browser/index.js",
+  "react-native": "dist/browser/index.js",
+  "types": "dist/esm/index.d.ts",
   "source": "src/index.ts",
   "sideEffects": false,
   "files": [
     "dist",
     "docs",
-    "lib",
     "src",
     "LICENSE",
-    "mod.ts",
     "README.md"
   ],
   "scripts": {
     "clean": "shx rm -rf dist lib",
-    "test-deno": "deno test test-deno",
-    "build": "rollup -c",
-    "watch": "rollup -c --watch"
+    "test-deno": "npm run build:rollup && deno test test-deno",
+    "build": "npm run build:cjs && npm run build:esm && npm run build:rollup",
+    "build:cjs": "tsc -p tsconfig.build.json --outDir dist/cjs --module commonjs",
+    "build:esm": "tsc -p tsconfig.build.json --outDir dist/esm --module es2015",
+    "build:rollup": "rollup -c"
   },
-  "gitHead": "6ec3ece072ebc17fab4e8372f3afe008bb9068a6"
+  "gitHead": "8e8e4d79b6aaf3fa8662e51ecce0511f53e10ea8"
 }

package/src/ditox.test.ts

@@ -508,7 +508,16 @@ describe('Container', () => {
 
     it('should throw ResolverError in case a value is not provided', () => {
       const container = createContainer();
-      expect(() => container.resolve(NUMBER)).toThrowError(ResolverError);
+      expect(() => container.resolve(token('test'))).toThrowError(
+        new ResolverError(`Token "test" is not provided`),
+      );
+    });
+
+    it('should throw ResolverError with an empty name in case a token is not resolved', () => {
+      const container = createContainer();
+      expect(() => container.resolve(token())).toThrowError(
+        new ResolverError(`Token "" is not provided`),
+      );
     });
 
     it('should resolve a value from the parent container', () => {

package/src/index.ts

@@ -1,33 +1,40 @@
-export {
+export {token, optional, ResolverError, createContainer} from './ditox';
+export type {
   RequiredToken,
   OptionalToken,
   Token,
-  token,
-  optional,
-  ResolverError,
   FactoryScope,
   FactoryOptions,
   Container,
-  createContainer,
 } from './ditox';
 
 export {
+  isToken,
   bindMultiValue,
-  getValues,
+  tryResolveValue,
+  tryResolveValues,
+  resolveValue,
   resolveValues,
   injectable,
+  injectableClass,
+} from './utils';
+
+export {
+  getValues,
   getProps,
   resolveProps,
   injectableProps,
-} from './utils';
+} from './utils-deprecated';
 
 export {
-  Module,
-  ModuleDeclaration,
-  BindModuleOptions,
-  ModuleBindingEntry,
   bindModule,
   bindModules,
   declareModule,
   declareModuleBindings,
 } from './modules';
+export type {
+  Module,
+  ModuleDeclaration,
+  BindModuleOptions,
+  ModuleBindingEntry,
+} from './modules';

package/src/modules.test.ts

@@ -7,6 +7,7 @@ import {
   Module,
   ModuleDeclaration,
 } from './modules';
+import {injectable} from './utils';
 
 describe('bindModule()', () => {
   type TestQueries = {getValue: () => number};
@@ -196,6 +197,35 @@ describe('bindModule()', () => {
     expect(container.get(MODULE1_TOKEN)?.value).toBe(1);
     expect(container.get(MODULE2_TOKEN)?.value).toBe(22);
   });
+
+  it('should call beforeBinding() before importing modules from "imports"', () => {
+    const ARG_TOKEN = token<string>('arg');
+    const RESULT_TOKEN = token<string>('result');
+
+    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},
+    });
+
+    const container = createContainer();
+    bindModule(
+      container,
+      declareModule({
+        factory: () => ({}),
+        beforeBinding: (container) => {
+          container.bindValue(ARG_TOKEN, '1');
+        },
+        imports: [MODULE1],
+      }),
+    );
+
+    expect(container.resolve(ARG_TOKEN)).toBe('12');
+    expect(container.resolve(RESULT_TOKEN)).toBe('123');
+  });
 });
 
 describe('bindModules()', () => {
@@ -289,5 +319,7 @@ describe('declareModuleBindings()', () => {
     bindModule(container, MODULE_BINDINGS);
     expect(container.get(VALUE1_TOKEN)).toBe(1);
     expect(container.get(VALUE2_TOKEN)).toBe(2);
+
+    expect(container.get(MODULE_BINDINGS.token)).toEqual({});
   });
 });

package/src/modules.ts

@@ -113,14 +113,14 @@ export function bindModule<T extends Module<AnyObject>>(
 
   const scope = options?.scope;
 
-  if (imports) {
-    bindModules(container, imports);
-  }
-
   if (beforeBinding) {
     beforeBinding(container);
   }
 
+  if (imports) {
+    bindModules(container, imports);
+  }
+
   const exportedValueTokens = new Set<Token<unknown>>();
 
   if (exports) {

package/src/utils-deprecated.test.ts

@@ -0,0 +1,286 @@
+import {createContainer, optional, ResolverError, token} from './ditox';
+import {bindMultiValue, injectable, resolveValues} from './utils';
+import {
+  getProps,
+  getValues,
+  injectableProps,
+  resolveProps,
+} from './utils-deprecated';
+
+const NUMBER = token<number>('number');
+const STRING = token<string>('string');
+
+describe('bindMultiValue', () => {
+  const NUMBERS = token<Array<number>>('numbers');
+
+  it('should append a value to an array declared by a token', () => {
+    const container = createContainer();
+
+    bindMultiValue(container, NUMBERS, 1);
+    bindMultiValue(container, NUMBERS, 2);
+
+    const values: Array<number> = container.resolve(NUMBERS);
+    expect(values).toEqual([1, 2]);
+  });
+
+  it('should append new values to an array declared by a token', () => {
+    const container = createContainer();
+
+    bindMultiValue(container, NUMBERS, 1);
+    bindMultiValue(container, NUMBERS, 2);
+    expect(container.resolve(NUMBERS)).toEqual([1, 2]);
+
+    bindMultiValue(container, NUMBERS, 3);
+    bindMultiValue(container, NUMBERS, 4);
+    expect(container.resolve(NUMBERS)).toEqual([1, 2, 3, 4]);
+  });
+
+  it('should add new values to a copy of array from the parent container', () => {
+    const parent = createContainer();
+    parent.bindValue(NUMBERS, [1, 2]);
+    const container = createContainer(parent);
+
+    bindMultiValue(container, NUMBERS, 3);
+    bindMultiValue(container, NUMBERS, 4);
+    expect(parent.resolve(NUMBERS)).toEqual([1, 2]);
+    expect(container.resolve(NUMBERS)).toEqual([1, 2, 3, 4]);
+
+    container.remove(NUMBERS);
+    expect(parent.resolve(NUMBERS)).toEqual([1, 2]);
+    expect(container.resolve(NUMBERS)).toEqual([1, 2]);
+  });
+});
+
+describe('getValues', () => {
+  it('should return values for the tokens', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, 'abc');
+
+    const values: [number, string] = getValues(container, NUMBER, STRING);
+    expect(values).toEqual([1, 'abc']);
+  });
+
+  it('should return "undefined" item in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const values = getValues(container, NUMBER, STRING);
+    expect(values).toEqual([1, undefined]);
+  });
+
+  it('should return values of optional tokens in case they are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const OPTIONAL_STRING = optional(STRING, 'value');
+
+    const values = getValues(container, NUMBER, STRING, OPTIONAL_STRING);
+    expect(values).toEqual([1, undefined, 'value']);
+  });
+
+  it('should works with a big arity', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const values = getValues(
+      container,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+      NUMBER,
+    );
+    expect(values).toEqual([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
+  });
+});
+
+describe('resolveValues', () => {
+  it('should resolve tokens from the container', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, 'abc');
+
+    const values: [number, string] = resolveValues(container, NUMBER, STRING);
+    expect(values).toEqual([1, 'abc']);
+  });
+
+  it('should throw an error in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    expect(() => {
+      resolveValues(container, NUMBER, STRING);
+    }).toThrowError(
+      new ResolverError(`Token "${STRING.symbol.description}" is not provided`),
+    );
+  });
+
+  it('should resolve values of optional tokens in case they are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const values = getValues(container, NUMBER, optional(STRING, 'value'));
+    expect(values).toEqual([1, 'value']);
+  });
+});
+
+describe('injectable()', () => {
+  it('should inject values from Container as arguments of the factory', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, '2');
+
+    const decoratedFactory = injectable(
+      (a: number, b: string) => a + b,
+      NUMBER,
+      STRING,
+    );
+
+    expect(decoratedFactory(container)).toBe('12');
+  });
+
+  it('should throw ResolverError error in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const decoratedFactory = injectable(
+      (a: number, b: string) => a + b,
+      NUMBER,
+      STRING,
+    );
+
+    expect(() => decoratedFactory(container)).toThrowError(
+      new ResolverError(`Token "${STRING.symbol.description}" is not provided`),
+    );
+  });
+
+  it('should inject values of optional tokens in case values are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const decoratedFactory = injectable(
+      (a, b) => a + b,
+      NUMBER,
+      optional(STRING, 'value'),
+    );
+
+    expect(decoratedFactory(container)).toBe('1value');
+  });
+});
+
+describe('getProps', () => {
+  it('should return an object with values by the tokens', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, 'abc');
+
+    const props: {a?: number; b?: string} = getProps(container, {
+      a: NUMBER,
+      b: STRING,
+    });
+    expect(props).toEqual({a: 1, b: 'abc'});
+  });
+
+  it('should return "undefined" item in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const props = getProps(container, {a: NUMBER, b: STRING});
+    expect(props).toEqual({a: 1, b: undefined});
+  });
+
+  it('should return values of optional tokens in case they are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const OPTIONAL_STRING = optional(STRING, 'value');
+
+    const props = getProps(container, {
+      a: NUMBER,
+      b: STRING,
+      c: OPTIONAL_STRING,
+    });
+    expect(props).toEqual({a: 1, b: undefined, c: 'value'});
+  });
+});
+
+describe('resolveProps', () => {
+  it('should an object with resolved values from the container for the specified token props', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, 'abc');
+
+    const props: {a: number; b: string} = resolveProps(container, {
+      a: NUMBER,
+      b: STRING,
+    });
+    expect(props).toEqual({a: 1, b: 'abc'});
+  });
+
+  it('should throw an error in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    expect(() => {
+      resolveProps(container, {a: NUMBER, b: STRING});
+    }).toThrowError(
+      new ResolverError(`Token "${STRING.symbol.description}" is not provided`),
+    );
+  });
+
+  it('should resolve values of optional tokens in case they are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const props = resolveProps(container, {
+      a: NUMBER,
+      b: optional(STRING, 'value'),
+    });
+    expect(props).toEqual({a: 1, b: 'value'});
+  });
+});
+
+describe('injectableProps()', () => {
+  function join({a, b}: {a: number; b: string}): string {
+    return `${a}/${b}`;
+  }
+
+  it('should inject values from Container as an object for the first argument of the factory', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+    container.bindValue(STRING, '2');
+
+    const decoratedFactory = injectableProps(join, {a: NUMBER, b: STRING});
+
+    expect(decoratedFactory(container)).toBe('1/2');
+  });
+
+  it('should throw ResolverError error in case a value is not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const decoratedFactory = injectableProps(join, {a: NUMBER, b: STRING});
+
+    expect(() => decoratedFactory(container)).toThrowError(
+      new ResolverError(`Token "${STRING.symbol.description}" is not provided`),
+    );
+  });
+
+  it('should inject values of optional tokens in case values are not provided', () => {
+    const container = createContainer();
+    container.bindValue(NUMBER, 1);
+
+    const decoratedFactory = injectableProps(join, {
+      a: NUMBER,
+      b: optional(STRING, 'value'),
+    });
+
+    expect(decoratedFactory(container)).toBe('1/value');
+  });
+});

package/src/utils-deprecated.ts

@@ -0,0 +1,87 @@
+import type {Container, Token} from './ditox';
+import {
+  injectable,
+  resolveValue,
+  tryResolveValue,
+  tryResolveValues,
+} from './utils';
+
+type ValuesProps = {[key: string]: unknown};
+type TokenProps<Props extends ValuesProps> = {
+  [K in keyof Props]: Token<Props[K]>;
+};
+
+/**
+ * Returns an array of resolved values by the specified token.
+ * If a token is not found, then `undefined` value is used.
+ *
+ * @deprecated Use `tryResolveValues()` function.
+ */
+export function getValues<
+  Tokens extends Token<unknown>[],
+  Values extends {
+    [K in keyof Tokens]: Tokens[K] extends Token<infer V> ? V : never;
+  },
+>(container: Container, ...tokens: Tokens): Values {
+  return tryResolveValues(container, ...tokens);
+}
+
+/**
+ * Returns an object with resolved properties which are specified by token properties.
+ * If a token is not found, then `undefined` value is used.
+ *
+ * @deprecated Use `tryResolveValue()` function.
+ *
+ * @example
+ * ```ts
+ * const props = getProps(container, {a: tokenA, b: tokenB});
+ * console.log(props); // {a: 1, b: 2}
+ * ```
+ */
+export function getProps<Props extends ValuesProps>(
+  container: Container,
+  tokens: TokenProps<Props>,
+): Partial<Props> {
+  return tryResolveValue(container, tokens) as Partial<Props>;
+}
+
+/**
+ * Returns an object with resolved properties which are specified by token properties.
+ * If a token is not found, then `ResolverError` is thrown.
+ *
+ * @deprecated Use `resolveValue()` function.
+ *
+ * @example
+ * ```ts
+ * const props = resolveProps(container, {a: tokenA, b: tokenB});
+ * console.log(props); // {a: 1, b: 2}
+ * ```
+ */
+export function resolveProps<Props extends ValuesProps>(
+  container: Container,
+  tokens: TokenProps<Props>,
+): Props {
+  return resolveValue(container, tokens) as Props;
+}
+
+/**
+ * Decorates a factory by passing a resolved object with tokens as the first argument.
+ * @param factory - A factory.
+ * @param tokens - Object with tokens.
+ * @return Decorated factory which takes a dependency container as a single argument.
+ *
+ * @deprecated Use `injectable()` function.
+ *
+ * @example
+ * ```ts
+ * const factory = ({a, b}: {a: number, b: number}) => a + b;
+ * const decoratedFactory = injectableProps(factory, {a: tokenA, b: tokenB});
+ * const result = decoratedFactory(container);
+ * ```
+ */
+export function injectableProps<Props extends ValuesProps, Result>(
+  factory: (props: Props) => Result,
+  tokens: TokenProps<Props>,
+): (container: Container) => Result {
+  return injectable(factory as any, tokens);
+}