atomic-di 1.0.0-rc.2 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ This library implements lifetimes, scopes and mocking for pure dependency inject
         - [Scoped](#Scoped)
     - [Resolution context](#Resolution-context)
     - [Mocking](#Mocking)
-    - [Scopes](#Scopes)
+    - [Scoping](#Scoping)
     - [Bulk resolutions](#Bulk-resolutions)
         - [List resolution](#List-resolution)
         - [Map resolution](#Map-resolution)
@@ -36,7 +36,7 @@ This library implements lifetimes, scopes and mocking for pure dependency inject
 
 Before reading, it's highly recommended that you familiarize yourself with the concepts of inversion of control (IoC) and dependency injection (DI), as well as DI techniques.
 
-If you need a container to build your application, or you are satisfied with pure dependency injection, you should definitely consider other solutions, or not use the framework at all.
+If you need a container to build your application, or you are satisfied with pure dependency injection, you should definitely consider other solutions, or not use a framework at all.
 
 This library is an attempt to provide full-featured dependency injection **without containers**.
 
@@ -44,21 +44,21 @@ This library is an attempt to provide full-featured dependency injection **witho
 
 ### Lifetimes
 
-We can implement lifetime using static initializations together with factory functions that create instances on demand. However, this can introduce inconsistency into the composition code.
+We can implement lifetime using static initializations together with factory functions that create instances on demand. However, this can introduce inconsistency into a composition code.
 
 This library solves this problem by allowing to resolve instances once using the same factory technique.
 
 ### Scopes
 
-Often in your application you may need to resolve instances separately for different "scopes" of the program, be it a request, a transaction or a worker thread. This behavior can be achieved by correctly distributing transient resolutions, but at scale the complexity of this approach will only increase.
+Often in your application you may need to resolve instances separately for different "scopes" of a program, be it a request, a transaction or a worker thread. This behavior can be achieved by correctly distributing transient resolutions, but at scale the complexity of this approach will only increase.
 
-This library solves this problem by introducing into factories (hereinafter referred to as providers) the ability to work with a map of providers to their instances, which serves as a scope.
+This library solves this problem by introducing into factories (hereinafter referred to as providers) an ability to work with a map of providers to their instances, which serves as a scope.
 
-### Mocking
+### Testing
 
 Testability is an important part of every application. IoC handles this very well, but to perform a unit test we still need to resolve modules. To ensure testing without side effects, developers often use mocking - replacing implementations with others with the same behavior. We can rebuild modules manually for each unit test or group of unit tests, but at scale this approach can introduce a lot of extra manual work without any significant benefit.
 
-This library solves this problem by allowing you to use factories that have been defined for the main application build. It's enough to create a map of mock providers to providers with the same interface, and pass it to the provider call to replace the implementations in its dependencies.
+This library solves this problem by allowing you to use factories that have been defined for a main application build. It's enough to create a map of mock providers to providers with the same interface, and pass it to a provider call to replace implementations in its dependencies.
 
 # Installation
 
@@ -80,7 +80,7 @@ npx jsr add @ensi/di
     - [Scoped](#Scoped)
 - [Resolution context](#Resolution-context)
 - [Mocking](#Mocking)
-- [Scopes](#Scopes)
+- [Scoping](#Scoping)
 - [Bulk resolutions](#Bulk-resolutions)
     - [List resolution](#List-resolution)
     - [Map resolution](#Map-resolution)
@@ -91,54 +91,54 @@ The library provides functions that create providers with behavior typical of si
 
 ### Transient
 
-Transient providers are created using the `transient` function:
+Transient providers are created using `transient` function:
 ```ts
 const getThing = transient(() => createThing())
 ```
 
-Transient providers are no different from regular factories except for additional logic required for scopes and mocks to work correctly. This logic is also present in the other two functions, you can read about it [here](#Resolution-context).
+Transient providers are no different from regular factories except for additional logic required for scopes and mocks to work correctly. This logic is also present in other two functions, you can read about it [here](#Resolution-context).
 
 ### Singleton
 
-Singleton providers are created using the `singleton` function:
+Singleton providers are created using `singleton` function:
 ```ts
 const getA = singleton(() => createA())
 const getB = transient((c) => createB(getA(c)))
 ```
 
-In this case, calling `getA` will always result in the same instance, and the passed factory will only be called once:
+In this case, calling `getA` will always result in a same instance, and a passed factory will only be called once:
 ```ts
 getA() === getA() == getB().A === getB().A
 ```
 
-You may have noticed that the `getB` provider factory uses a certain `c` argument. This is a context that can optionally be passed when calling the provider, you can read about it [here](#Resolution-context).
+You may have noticed that the `getB` provider factory uses a certain `c` argument. This is a context that can optionally be passed when calling a provider, you can read about it [here](#Resolution-context).
 
 ### Scoped
 
-Scoped providers are created using the `scoped` function:
+Scoped providers are created using `scoped` function:
 ```ts
 const getThing = scoped(() => createThing())
 ```
 
-When calling this provider without passing a scope to the resolution context, it will create a new unique instance:
+When calling this provider without passing a scope to a resolution context, it will act as a singleton, resulting in a same instance:
 ```ts
-getThing() !== getThing()
+getThing() === getThing()
 ```
 
-To get resolutions within a scope, we need to pass it to the provider call in the resolution context object:
+To get resolutions within a scope, we need to pass it to a provider call in a resolution context object:
 ```ts
 const scope = createScope()
 
 getThing({ scope }) === getThing({ scope })
 ```
 
-You can read more about scopes [here](#Scopes).
+You can read more about scopes [here](#Scoping).
 
 ## Resolution context
 
-Each provider can accept a resolution context object. This is an object with optional `scope` and `mocks` fields that defines how the instance will be resolved.
+Each provider can accept a resolution context object. This is an object with optional `scope` and `mocks` fields that defines how an instance will be resolved.
 
-In all provider factories that have dependencies, this context **must** be passed into all calls to other providers to ensure it is propagated up the call chain.
+In all provider factories that have dependencies, this context **must** be passed into all calls to other providers to ensure it is propagated up a call chain.
 
 #### Incorrect
 ```ts
@@ -147,7 +147,7 @@ const getB = scoped(() => createB(getA()))
 const getC = scoped(() => createC(getB()))
 ```
 
-In this case, the context will not propagate beyond `getC` and other providers will not know about the current scope and mocks, and `getB` will return an instance that is not related to any scopes.
+In this case, a context will not propagate beyond `getC` and other providers will not know about a current scope and mocks, and `getB` will return an instance that is not related to any scopes.
 
 #### Correct
 ```ts
@@ -156,23 +156,23 @@ const getB = scoped((c) => createB(getA(c)))
 const getC = scoped((c) => createC(getB(c)))
 ```
 
-In this case, `getC` will propagate the context, and `getB` and `getA` will be aware of the current mocks and scopes, resolving instances correctly.
+In this case, `getC` will propagate a context, and `getB` and `getA` will be aware of a current mocks and scopes, resolving instances correctly.
 
-More details on how the provider behaves depending on the passed context can be found in the sections on [mocking](#Mocking) and [scopes](#Scopes).
+More details on how provider behaves depending on a passed context can be found in sections about [mocking](#Mocking) and [scoping](#Scoping).
 
 ## Mocking
 
-To replace implementations inside factories, we can use a mock map. To create one, we can use the `createMockMap` function:
+To replace implementations inside factories, we can use a mock map. To create one, we can use `createMockMap` function:
 ```ts
 const mockMap = createMockMap()
 ```
 
-To register a mock, you need to `set` an entry with the original provider in the key and its mock in the value:
+To register a mock, you need to `set` an entry with an original provider in a key and its mock in a value:
 ```ts
 mockMap.set(getDatabase, getMockDatabase)
 ```
 
-Once all mocks have been registered, this map can be passed to the provider call. If the provider finds a mock in the resolution context, it checks whether it is among the keys, and in that case returns the mock call instead of itself.
+Once all mocks have been registered, this map can be passed to a provider call. If a provider finds a mock in a resolution context, it checks whether it is among the keys, and in that case returns a mock call instead of itself.
 
 #### Direct replacement
 ```ts
@@ -203,16 +203,16 @@ const mocks = createMockMap().set(getC, getSea)
 getC({ mocks }) === "2sea"
 ```
 
-## Scopes
+## Scoping
 
-In this library, a scope is a map of providers to their resolutions. To create one, you can use the `createScope` function:
+In this library, a scope is a map of providers to their resolutions. To create one, you can use `createScope` function:
 ```ts
 const scope = createScope()
 ```
 
-It is passed to the scoped provider call or to the call of a provider that has the scoped provider among its transitive dependencies.
-- If the scoped provider finds a scope in the resolution context, it first tries to get its own resolution from it. If there is none, it creates a new resolution and places it in the scope below itself.
-- If a scope is not passed to the resolution context when calling the scoped provider, the provider will create a new instance, i.e. it will behave as a transient provider.
+It is passed to a scoped provider call or to a call of a provider that has the scoped provider among its transitive dependencies.
+- If a scoped provider finds a scope in a resolution context, it first tries to get its own resolution from it. If there is none, it creates a new resolution and places it in the scope below itself.
+- If a scope is not passed to a resolution context when calling a scoped provider, the provider will always result in a same instance, and a passed factory will only be called once, i.e. it will behave as a singleton provider.
 
 #### Direct scoped provider call
 ```ts
@@ -222,13 +222,14 @@ const getThing = scoped(() => createThing())
 const thing1 = getThing()
 const thing2 = getThing()
 
-thing1 !== thing2
+thing1 === thing2
 ```
 ```ts
 const thing1 = getThing({ scope })
 const thing2 = getThing({ scope })
+const thingFallback = getThing()
 
-thing1 === thing2
+thing1 === thing2 !== thingFallback
 ```
 
 #### Scoped provider as direct/transitive dependency
@@ -242,22 +243,23 @@ const getThing = transitive((c) =>
 const thing1 = getThing()
 const thing2 = getThing()
 
-thing1.scopedDependency !== thing2.scopedDependency
+thing1.scopedDependency === thing2.scopedDependency
 ```
 ```ts
 const thing1 = getThing({ scope })
 const thing2 = getThing({ scope })
+const thingWithFallback = getThing()
 
-thing1.scopedDependency === thing2.scopedDependency
+thing1.scopedDependency === thing2.scopedDependency !== thingWithFallback
 ```
 
 ## Bulk resolutions
 
-It often happens that you need to resolve instances of a large number of entities, in our case providers, with the same context. Fortunately, the library provides functions for this.
+It often happens that you need to resolve instances of a large number of entities, in our case providers, with a same context. Fortunately, the library provides functions for this.
 
 ### List resolution
 
-To resolve instances of a list of providers, you can use the `resolveList` function, which takes a list of providers and a common resolution context. If at least one provider in the passed list of providers returns a `Promise`, the function will return a `Promise` of the list of **awaited** resolutions.
+To resolve instances of a list of providers, you can use `resolveList` function, which takes a list of providers and a common resolution context. If at least one provider in the passed list of providers returns a `Promise`, the function will return a `Promise` of a list of **awaited** resolutions.
 
 #### Only sync providers
 ```ts
@@ -301,7 +303,7 @@ resolutions == [
 
 ### Map resolution
 
-To resolve instances of a provider map, or an object with string keys and providers in the values, you can use the `resolveMap` function, which takes a provider map and a common resolution context. If at least one provider in the values of the passed provider map returns a `Promise`, the function will return a `Promise` of a map of **awaited** resolutions.
+To resolve instances of a provider map, or an object with string keys and providers in a values, you can use `resolveMap` function, which takes a provider map and a common resolution context. If at least one provider in the values of the passed provider map returns a `Promise`, the function will return a `Promise` of a map of **awaited** resolutions.
 
 #### Only sync providers
 ```ts
@@ -394,19 +396,19 @@ function scoped<T>(resolver: Resolver<T>): Provider<T>
 ```
 - `resolver`: A function that returns a value of a particular type with a resolution context being passed to it.
 
-Creates a scoped provider that will take its resolution from a passed scope or create a new one and save it if there is none. If no scope is passed, it will create a new instance on each call.
+Creates a scoped provider that will take its resolution from a passed scope or create a new one and save it if there is none. If no scope is passed, it will act as a singleton
 
 #### Example 1
 ```ts
 const getThing = scoped(() => createThing())
-getThing() !== getThing()
+getThing() === getThing()
 ```
 
 #### Example 2
 ```ts
 const getThing = scoped(() => createThing())
 const scope = createScope()
-getThing({ scope }) === getThing({ scope })
+getThing({ scope }) === getThing({ scope }) !== getThing()
 ```
 
 ### `createMockMap`

package/dist/index.d.mts

@@ -114,19 +114,19 @@ declare const singleton: <T>(resolver: Resolver<T>) => Provider<T>;
 /**
  * Creates a scoped provider that will take its resolution from a passed scope
  * or create a new one and save it if there is none.
- * If no scope is passed, it will create a new instance on each call.
+ * If no scope is passed, it will act as a singleton.
  *
  * @example
  * ```ts
  * const getThing = scoped(() => createThing())
- * getThing() !== getThing()
+ * getThing() === getThing()
  * ```
  *
  * @example
  * ```ts
  * const getThing = scoped(() => createThing())
  * const scope = createScope()
- * getThing({ scope }) === getThing({ scope })
+ * getThing({ scope }) === getThing({ scope }) !== getThing()
  * ```
  *
  * @param resolver

package/dist/index.d.ts

@@ -114,19 +114,19 @@ declare const singleton: <T>(resolver: Resolver<T>) => Provider<T>;
 /**
  * Creates a scoped provider that will take its resolution from a passed scope
  * or create a new one and save it if there is none.
- * If no scope is passed, it will create a new instance on each call.
+ * If no scope is passed, it will act as a singleton.
  *
  * @example
  * ```ts
  * const getThing = scoped(() => createThing())
- * getThing() !== getThing()
+ * getThing() === getThing()
  * ```
  *
  * @example
  * ```ts
  * const getThing = scoped(() => createThing())
  * const scope = createScope()
- * getThing({ scope }) === getThing({ scope })
+ * getThing({ scope }) === getThing({ scope }) !== getThing()
  * ```
  *
  * @param resolver

package/dist/index.js

@@ -54,11 +54,12 @@ var singleton = (resolver) => {
   return instance;
 };
 var scoped = (resolver) => {
+  const singletonFallback = singleton(resolver);
   const instance = (context) => {
     var _a;
     const maybeMock = (_a = context == null ? void 0 : context.mocks) == null ? void 0 : _a.get(instance);
     if (maybeMock) return maybeMock(context);
-    if (!(context == null ? void 0 : context.scope)) return resolver(context);
+    if (!(context == null ? void 0 : context.scope)) return singletonFallback(context);
     const resolution = context.scope.has(resolver) ? context.scope.get(resolver) : resolver(context);
     context.scope.set(resolver, resolution);
     return resolution;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/provider.ts","../src/scope.ts","../src/mock-map.ts","../src/collection-resolution.ts"],"sourcesContent":["export * from \"./provider\";\nexport * from \"./scope\";\nexport * from \"./mock-map\";\nexport * from \"./collection-resolution\";\n","import { MockMap } from \"./mock-map\";\nimport { Scope } from \"./scope\";\n\n/**\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n */\nexport type Resolver<T> = (context?: ResolutionContext) => T;\n\n/**\n * A function that resolves an instance or a `Promise` of a particular type\n * based on a resolution context passed to it.\n */\nexport type Provider<T> = Resolver<T>;\n\n/**\n * A context used by providers to resolve instances\n * based on current scope and mocks.\n */\nexport type ResolutionContext = {\n    scope?: Scope;\n    mocks?: MockMap;\n};\n\n/**\n * Creates a transient provider that will resolve a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = transient(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The transient provider.\n */\nexport const transient = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        return resolver(context);\n    };\n\n    return instance;\n};\n\n/**\n * Creates a singleton provider that will resolve an instance once\n * and return it on every call.\n *\n * @example\n * ```ts\n * const getThing = singleton(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The singleton provider.\n */\nexport const singleton = <T>(resolver: Resolver<T>): Provider<T> => {\n    let resolved = false;\n    let resolution: T | undefined;\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (resolved) return resolution!;\n\n        resolution = resolver(context);\n        resolved = true;\n\n        return resolution;\n    };\n\n    return instance;\n};\n\n/**\n * Creates a scoped provider that will take its resolution from a passed scope\n * or create a new one and save it if there is none.\n * If no scope is passed, it will create a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * const scope = createScope()\n * getThing({ scope }) === getThing({ scope })\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The scoped provider.\n */\nexport const scoped = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (!context?.scope) return resolver(context);\n\n        const resolution = context.scope.has(resolver)\n            ? context.scope.get(resolver)\n            : resolver(context);\n        context.scope.set(resolver, resolution);\n\n        return resolution;\n    };\n\n    return instance;\n};\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n */\nexport type Scope = Map<Resolver<any>, any>;\n\n/**\n * Creates a `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n *\n * @example\n * ```ts\n * const requestScope = createScope()\n *\n * app.use(() => {\n *     const db = getDb({ scope: requestScope })\n *     // ...\n * })\n * ```\n *\n * @returns The map instance.\n */\nexport const createScope = (): Scope => new Map();\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n */\nexport type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, \"set\" | \"get\"> & {\n    /**\n     * Sets a mock for a provider.\n     *\n     * @param provider - The original provider.\n     * @param mock - The mock provider.\n     */\n    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;\n    /**\n     * Retrieves a mock of a provider. Returns undefined if there's none.\n     *\n     * @param provider - The provider.\n     */\n    get<T>(provider: Resolver<T>): Resolver<T> | undefined;\n};\n\n/**\n * Creates a `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n *\n * @example\n * ```ts\n * const mocks = createMockMap()\n *     .set(getConfig, getTestConfig)\n *\n * getThing({ mocks })\n * ```\n *\n * @returns The map instance.\n */\nexport const createMockMap = (): MockMap => new Map();\n","import { Provider, ResolutionContext } from \"./provider\";\n\ntype ProviderList = Provider<any>[];\ntype ProviderRecord = Record<string, Provider<any>>;\n\ntype InferProviderCollectionResolutions<\n    Providers extends ProviderList | ProviderRecord,\n> = {\n    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;\n};\n\n/**\n * Awaits all promises and wraps the collection in a promise\n * if there'ss at least one `Promise` in the collection,\n * otherwise returns an untouched type.\n */\ntype AwaitValuesInCollection<T extends any[] | Record<any, any>> =\n    Promise<any> extends T[keyof T]\n        ? Promise<{\n              [I in keyof T]: T[I] extends Promise<infer T> ? T : T[I];\n          }>\n        : T;\n\n/**\n * Calls every provider in a list with a provided resolution context\n * and returns a list of resolutions. Returns a `Promise` of a list\n * of awaited resolutions if there's at least one `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     await getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @param providers - The list of providers.\n * @param context - The resolution context.\n *\n * @returns The list of resolutions.\n */\nexport const resolveList = <const Providers extends ProviderList>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutions = providers.map((provider) => provider(context));\n\n    const hasPromises = resolutions.some(\n        (resolution) => resolution instanceof Promise,\n    );\n\n    return (hasPromises ? Promise.all(resolutions) : resolutions) as any;\n};\n\n/**\n * Calls every provider in a map with a provided resolution context\n * and returns a map with identical keys but with resolutions in values instead.\n * Returns a `Promise` of a map of awaited resolutions if there's at least one\n * `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = await resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: await getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @param providers - The map of providers.\n * @param context - The resolution context.\n *\n * @returns The map of resolutions.\n */\nexport const resolveMap = <const Providers extends ProviderRecord>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutionMapEntries = Object.entries(providers).map(\n        ([key, provider]) => [key, provider(context)],\n    );\n\n    const hasPromises = resolutionMapEntries.some(\n        ([, resolution]) => resolution instanceof Promise,\n    );\n\n    if (hasPromises) {\n        return (async () => {\n            const awaitedEntries = await Promise.all(\n                resolutionMapEntries.map(async ([key, resolution]) => [\n                    key,\n                    await resolution,\n                ]),\n            );\n            return Object.fromEntries(awaitedEntries);\n        })() as any;\n    }\n\n    return Object.fromEntries(resolutionMapEntries);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACuCO,IAAM,YAAY,CAAI,aAAuC;AAChE,QAAM,WAAwB,CAAC,YAAY;AAxC/C;AAyCQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,WAAO,SAAS,OAAO;AAAA,EAC3B;AAEA,SAAO;AACX;AAkBO,IAAM,YAAY,CAAI,aAAuC;AAChE,MAAI,WAAW;AACf,MAAI;AAEJ,QAAM,WAAwB,CAAC,YAAY;AAtE/C;AAuEQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,SAAU,QAAO;AAErB,iBAAa,SAAS,OAAO;AAC7B,eAAW;AAEX,WAAO;AAAA,EACX;AAEA,SAAO;AACX;AA0BO,IAAM,SAAS,CAAI,aAAuC;AAC7D,QAAM,WAAwB,CAAC,YAAY;AA9G/C;AA+GQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,EAAC,mCAAS,OAAO,QAAO,SAAS,OAAO;AAE5C,UAAM,aAAa,QAAQ,MAAM,IAAI,QAAQ,IACvC,QAAQ,MAAM,IAAI,QAAQ,IAC1B,SAAS,OAAO;AACtB,YAAQ,MAAM,IAAI,UAAU,UAAU;AAEtC,WAAO;AAAA,EACX;AAEA,SAAO;AACX;;;ACnGO,IAAM,cAAc,MAAa,oBAAI,IAAI;;;ACYzC,IAAM,gBAAgB,MAAe,oBAAI,IAAI;;;ACmC7C,IAAM,cAAc,CACvB,WACA,YAGC;AACD,QAAM,cAAc,UAAU,IAAI,CAAC,aAAa,SAAS,OAAO,CAAC;AAEjE,QAAM,cAAc,YAAY;AAAA,IAC5B,CAAC,eAAe,sBAAsB;AAAA,EAC1C;AAEA,SAAQ,cAAc,QAAQ,IAAI,WAAW,IAAI;AACrD;AAqDO,IAAM,aAAa,CACtB,WACA,YAGC;AACD,QAAM,uBAAuB,OAAO,QAAQ,SAAS,EAAE;AAAA,IACnD,CAAC,CAAC,KAAK,QAAQ,MAAM,CAAC,KAAK,SAAS,OAAO,CAAC;AAAA,EAChD;AAEA,QAAM,cAAc,qBAAqB;AAAA,IACrC,CAAC,CAAC,EAAE,UAAU,MAAM,sBAAsB;AAAA,EAC9C;AAEA,MAAI,aAAa;AACb,YAAQ,YAAY;AAChB,YAAM,iBAAiB,MAAM,QAAQ;AAAA,QACjC,qBAAqB,IAAI,OAAO,CAAC,KAAK,UAAU,MAAM;AAAA,UAClD;AAAA,UACA,MAAM;AAAA,QACV,CAAC;AAAA,MACL;AACA,aAAO,OAAO,YAAY,cAAc;AAAA,IAC5C,GAAG;AAAA,EACP;AAEA,SAAO,OAAO,YAAY,oBAAoB;AAClD;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/provider.ts","../src/scope.ts","../src/mock-map.ts","../src/collection-resolution.ts"],"sourcesContent":["export * from \"./provider\";\nexport * from \"./scope\";\nexport * from \"./mock-map\";\nexport * from \"./collection-resolution\";\n","import { MockMap } from \"./mock-map\";\nimport { Scope } from \"./scope\";\n\n/**\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n */\nexport type Resolver<T> = (context?: ResolutionContext) => T;\n\n/**\n * A function that resolves an instance or a `Promise` of a particular type\n * based on a resolution context passed to it.\n */\nexport type Provider<T> = Resolver<T>;\n\n/**\n * A context used by providers to resolve instances\n * based on current scope and mocks.\n */\nexport type ResolutionContext = {\n    scope?: Scope;\n    mocks?: MockMap;\n};\n\n/**\n * Creates a transient provider that will resolve a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = transient(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The transient provider.\n */\nexport const transient = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        return resolver(context);\n    };\n\n    return instance;\n};\n\n/**\n * Creates a singleton provider that will resolve an instance once\n * and return it on every call.\n *\n * @example\n * ```ts\n * const getThing = singleton(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The singleton provider.\n */\nexport const singleton = <T>(resolver: Resolver<T>): Provider<T> => {\n    let resolved = false;\n    let resolution: T | undefined;\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (resolved) return resolution!;\n\n        resolution = resolver(context);\n        resolved = true;\n\n        return resolution;\n    };\n\n    return instance;\n};\n\n/**\n * Creates a scoped provider that will take its resolution from a passed scope\n * or create a new one and save it if there is none.\n * If no scope is passed, it will act as a singleton.\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * const scope = createScope()\n * getThing({ scope }) === getThing({ scope }) !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The scoped provider.\n */\nexport const scoped = <T>(resolver: Resolver<T>): Provider<T> => {\n    const singletonFallback = singleton(resolver);\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (!context?.scope) return singletonFallback(context);\n\n        const resolution = context.scope.has(resolver)\n            ? context.scope.get(resolver)\n            : resolver(context);\n        context.scope.set(resolver, resolution);\n\n        return resolution;\n    };\n\n    return instance;\n};\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n */\nexport type Scope = Map<Resolver<any>, any>;\n\n/**\n * Creates a `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n *\n * @example\n * ```ts\n * const requestScope = createScope()\n *\n * app.use(() => {\n *     const db = getDb({ scope: requestScope })\n *     // ...\n * })\n * ```\n *\n * @returns The map instance.\n */\nexport const createScope = (): Scope => new Map();\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n */\nexport type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, \"set\" | \"get\"> & {\n    /**\n     * Sets a mock for a provider.\n     *\n     * @param provider - The original provider.\n     * @param mock - The mock provider.\n     */\n    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;\n    /**\n     * Retrieves a mock of a provider. Returns undefined if there's none.\n     *\n     * @param provider - The provider.\n     */\n    get<T>(provider: Resolver<T>): Resolver<T> | undefined;\n};\n\n/**\n * Creates a `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n *\n * @example\n * ```ts\n * const mocks = createMockMap()\n *     .set(getConfig, getTestConfig)\n *\n * getThing({ mocks })\n * ```\n *\n * @returns The map instance.\n */\nexport const createMockMap = (): MockMap => new Map();\n","import { Provider, ResolutionContext } from \"./provider\";\n\ntype ProviderList = Provider<any>[];\ntype ProviderRecord = Record<string, Provider<any>>;\n\ntype InferProviderCollectionResolutions<\n    Providers extends ProviderList | ProviderRecord,\n> = {\n    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;\n};\n\n/**\n * Awaits all promises and wraps the collection in a promise\n * if there'ss at least one `Promise` in the collection,\n * otherwise returns an untouched type.\n */\ntype AwaitValuesInCollection<T extends any[] | Record<any, any>> =\n    Promise<any> extends T[keyof T]\n        ? Promise<{\n              [I in keyof T]: T[I] extends Promise<infer T> ? T : T[I];\n          }>\n        : T;\n\n/**\n * Calls every provider in a list with a provided resolution context\n * and returns a list of resolutions. Returns a `Promise` of a list\n * of awaited resolutions if there's at least one `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     await getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @param providers - The list of providers.\n * @param context - The resolution context.\n *\n * @returns The list of resolutions.\n */\nexport const resolveList = <const Providers extends ProviderList>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutions = providers.map((provider) => provider(context));\n\n    const hasPromises = resolutions.some(\n        (resolution) => resolution instanceof Promise,\n    );\n\n    return (hasPromises ? Promise.all(resolutions) : resolutions) as any;\n};\n\n/**\n * Calls every provider in a map with a provided resolution context\n * and returns a map with identical keys but with resolutions in values instead.\n * Returns a `Promise` of a map of awaited resolutions if there's at least one\n * `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = await resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: await getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @param providers - The map of providers.\n * @param context - The resolution context.\n *\n * @returns The map of resolutions.\n */\nexport const resolveMap = <const Providers extends ProviderRecord>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutionMapEntries = Object.entries(providers).map(\n        ([key, provider]) => [key, provider(context)],\n    );\n\n    const hasPromises = resolutionMapEntries.some(\n        ([, resolution]) => resolution instanceof Promise,\n    );\n\n    if (hasPromises) {\n        return (async () => {\n            const awaitedEntries = await Promise.all(\n                resolutionMapEntries.map(async ([key, resolution]) => [\n                    key,\n                    await resolution,\n                ]),\n            );\n            return Object.fromEntries(awaitedEntries);\n        })() as any;\n    }\n\n    return Object.fromEntries(resolutionMapEntries);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACuCO,IAAM,YAAY,CAAI,aAAuC;AAChE,QAAM,WAAwB,CAAC,YAAY;AAxC/C;AAyCQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,WAAO,SAAS,OAAO;AAAA,EAC3B;AAEA,SAAO;AACX;AAkBO,IAAM,YAAY,CAAI,aAAuC;AAChE,MAAI,WAAW;AACf,MAAI;AAEJ,QAAM,WAAwB,CAAC,YAAY;AAtE/C;AAuEQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,SAAU,QAAO;AAErB,iBAAa,SAAS,OAAO;AAC7B,eAAW;AAEX,WAAO;AAAA,EACX;AAEA,SAAO;AACX;AA0BO,IAAM,SAAS,CAAI,aAAuC;AAC7D,QAAM,oBAAoB,UAAU,QAAQ;AAE5C,QAAM,WAAwB,CAAC,YAAY;AAhH/C;AAiHQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,EAAC,mCAAS,OAAO,QAAO,kBAAkB,OAAO;AAErD,UAAM,aAAa,QAAQ,MAAM,IAAI,QAAQ,IACvC,QAAQ,MAAM,IAAI,QAAQ,IAC1B,SAAS,OAAO;AACtB,YAAQ,MAAM,IAAI,UAAU,UAAU;AAEtC,WAAO;AAAA,EACX;AAEA,SAAO;AACX;;;ACrGO,IAAM,cAAc,MAAa,oBAAI,IAAI;;;ACYzC,IAAM,gBAAgB,MAAe,oBAAI,IAAI;;;ACmC7C,IAAM,cAAc,CACvB,WACA,YAGC;AACD,QAAM,cAAc,UAAU,IAAI,CAAC,aAAa,SAAS,OAAO,CAAC;AAEjE,QAAM,cAAc,YAAY;AAAA,IAC5B,CAAC,eAAe,sBAAsB;AAAA,EAC1C;AAEA,SAAQ,cAAc,QAAQ,IAAI,WAAW,IAAI;AACrD;AAqDO,IAAM,aAAa,CACtB,WACA,YAGC;AACD,QAAM,uBAAuB,OAAO,QAAQ,SAAS,EAAE;AAAA,IACnD,CAAC,CAAC,KAAK,QAAQ,MAAM,CAAC,KAAK,SAAS,OAAO,CAAC;AAAA,EAChD;AAEA,QAAM,cAAc,qBAAqB;AAAA,IACrC,CAAC,CAAC,EAAE,UAAU,MAAM,sBAAsB;AAAA,EAC9C;AAEA,MAAI,aAAa;AACb,YAAQ,YAAY;AAChB,YAAM,iBAAiB,MAAM,QAAQ;AAAA,QACjC,qBAAqB,IAAI,OAAO,CAAC,KAAK,UAAU,MAAM;AAAA,UAClD;AAAA,UACA,MAAM;AAAA,QACV,CAAC;AAAA,MACL;AACA,aAAO,OAAO,YAAY,cAAc;AAAA,IAC5C,GAAG;AAAA,EACP;AAEA,SAAO,OAAO,YAAY,oBAAoB;AAClD;","names":[]}

package/dist/index.mjs

@@ -23,11 +23,12 @@ var singleton = (resolver) => {
   return instance;
 };
 var scoped = (resolver) => {
+  const singletonFallback = singleton(resolver);
   const instance = (context) => {
     var _a;
     const maybeMock = (_a = context == null ? void 0 : context.mocks) == null ? void 0 : _a.get(instance);
     if (maybeMock) return maybeMock(context);
-    if (!(context == null ? void 0 : context.scope)) return resolver(context);
+    if (!(context == null ? void 0 : context.scope)) return singletonFallback(context);
     const resolution = context.scope.has(resolver) ? context.scope.get(resolver) : resolver(context);
     context.scope.set(resolver, resolution);
     return resolution;

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider.ts","../src/scope.ts","../src/mock-map.ts","../src/collection-resolution.ts"],"sourcesContent":["import { MockMap } from \"./mock-map\";\nimport { Scope } from \"./scope\";\n\n/**\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n */\nexport type Resolver<T> = (context?: ResolutionContext) => T;\n\n/**\n * A function that resolves an instance or a `Promise` of a particular type\n * based on a resolution context passed to it.\n */\nexport type Provider<T> = Resolver<T>;\n\n/**\n * A context used by providers to resolve instances\n * based on current scope and mocks.\n */\nexport type ResolutionContext = {\n    scope?: Scope;\n    mocks?: MockMap;\n};\n\n/**\n * Creates a transient provider that will resolve a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = transient(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The transient provider.\n */\nexport const transient = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        return resolver(context);\n    };\n\n    return instance;\n};\n\n/**\n * Creates a singleton provider that will resolve an instance once\n * and return it on every call.\n *\n * @example\n * ```ts\n * const getThing = singleton(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The singleton provider.\n */\nexport const singleton = <T>(resolver: Resolver<T>): Provider<T> => {\n    let resolved = false;\n    let resolution: T | undefined;\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (resolved) return resolution!;\n\n        resolution = resolver(context);\n        resolved = true;\n\n        return resolution;\n    };\n\n    return instance;\n};\n\n/**\n * Creates a scoped provider that will take its resolution from a passed scope\n * or create a new one and save it if there is none.\n * If no scope is passed, it will create a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * const scope = createScope()\n * getThing({ scope }) === getThing({ scope })\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The scoped provider.\n */\nexport const scoped = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (!context?.scope) return resolver(context);\n\n        const resolution = context.scope.has(resolver)\n            ? context.scope.get(resolver)\n            : resolver(context);\n        context.scope.set(resolver, resolution);\n\n        return resolution;\n    };\n\n    return instance;\n};\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n */\nexport type Scope = Map<Resolver<any>, any>;\n\n/**\n * Creates a `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n *\n * @example\n * ```ts\n * const requestScope = createScope()\n *\n * app.use(() => {\n *     const db = getDb({ scope: requestScope })\n *     // ...\n * })\n * ```\n *\n * @returns The map instance.\n */\nexport const createScope = (): Scope => new Map();\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n */\nexport type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, \"set\" | \"get\"> & {\n    /**\n     * Sets a mock for a provider.\n     *\n     * @param provider - The original provider.\n     * @param mock - The mock provider.\n     */\n    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;\n    /**\n     * Retrieves a mock of a provider. Returns undefined if there's none.\n     *\n     * @param provider - The provider.\n     */\n    get<T>(provider: Resolver<T>): Resolver<T> | undefined;\n};\n\n/**\n * Creates a `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n *\n * @example\n * ```ts\n * const mocks = createMockMap()\n *     .set(getConfig, getTestConfig)\n *\n * getThing({ mocks })\n * ```\n *\n * @returns The map instance.\n */\nexport const createMockMap = (): MockMap => new Map();\n","import { Provider, ResolutionContext } from \"./provider\";\n\ntype ProviderList = Provider<any>[];\ntype ProviderRecord = Record<string, Provider<any>>;\n\ntype InferProviderCollectionResolutions<\n    Providers extends ProviderList | ProviderRecord,\n> = {\n    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;\n};\n\n/**\n * Awaits all promises and wraps the collection in a promise\n * if there'ss at least one `Promise` in the collection,\n * otherwise returns an untouched type.\n */\ntype AwaitValuesInCollection<T extends any[] | Record<any, any>> =\n    Promise<any> extends T[keyof T]\n        ? Promise<{\n              [I in keyof T]: T[I] extends Promise<infer T> ? T : T[I];\n          }>\n        : T;\n\n/**\n * Calls every provider in a list with a provided resolution context\n * and returns a list of resolutions. Returns a `Promise` of a list\n * of awaited resolutions if there's at least one `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     await getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @param providers - The list of providers.\n * @param context - The resolution context.\n *\n * @returns The list of resolutions.\n */\nexport const resolveList = <const Providers extends ProviderList>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutions = providers.map((provider) => provider(context));\n\n    const hasPromises = resolutions.some(\n        (resolution) => resolution instanceof Promise,\n    );\n\n    return (hasPromises ? Promise.all(resolutions) : resolutions) as any;\n};\n\n/**\n * Calls every provider in a map with a provided resolution context\n * and returns a map with identical keys but with resolutions in values instead.\n * Returns a `Promise` of a map of awaited resolutions if there's at least one\n * `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = await resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: await getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @param providers - The map of providers.\n * @param context - The resolution context.\n *\n * @returns The map of resolutions.\n */\nexport const resolveMap = <const Providers extends ProviderRecord>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutionMapEntries = Object.entries(providers).map(\n        ([key, provider]) => [key, provider(context)],\n    );\n\n    const hasPromises = resolutionMapEntries.some(\n        ([, resolution]) => resolution instanceof Promise,\n    );\n\n    if (hasPromises) {\n        return (async () => {\n            const awaitedEntries = await Promise.all(\n                resolutionMapEntries.map(async ([key, resolution]) => [\n                    key,\n                    await resolution,\n                ]),\n            );\n            return Object.fromEntries(awaitedEntries);\n        })() as any;\n    }\n\n    return Object.fromEntries(resolutionMapEntries);\n};\n"],"mappings":";AAuCO,IAAM,YAAY,CAAI,aAAuC;AAChE,QAAM,WAAwB,CAAC,YAAY;AAxC/C;AAyCQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,WAAO,SAAS,OAAO;AAAA,EAC3B;AAEA,SAAO;AACX;AAkBO,IAAM,YAAY,CAAI,aAAuC;AAChE,MAAI,WAAW;AACf,MAAI;AAEJ,QAAM,WAAwB,CAAC,YAAY;AAtE/C;AAuEQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,SAAU,QAAO;AAErB,iBAAa,SAAS,OAAO;AAC7B,eAAW;AAEX,WAAO;AAAA,EACX;AAEA,SAAO;AACX;AA0BO,IAAM,SAAS,CAAI,aAAuC;AAC7D,QAAM,WAAwB,CAAC,YAAY;AA9G/C;AA+GQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,EAAC,mCAAS,OAAO,QAAO,SAAS,OAAO;AAE5C,UAAM,aAAa,QAAQ,MAAM,IAAI,QAAQ,IACvC,QAAQ,MAAM,IAAI,QAAQ,IAC1B,SAAS,OAAO;AACtB,YAAQ,MAAM,IAAI,UAAU,UAAU;AAEtC,WAAO;AAAA,EACX;AAEA,SAAO;AACX;;;ACnGO,IAAM,cAAc,MAAa,oBAAI,IAAI;;;ACYzC,IAAM,gBAAgB,MAAe,oBAAI,IAAI;;;ACmC7C,IAAM,cAAc,CACvB,WACA,YAGC;AACD,QAAM,cAAc,UAAU,IAAI,CAAC,aAAa,SAAS,OAAO,CAAC;AAEjE,QAAM,cAAc,YAAY;AAAA,IAC5B,CAAC,eAAe,sBAAsB;AAAA,EAC1C;AAEA,SAAQ,cAAc,QAAQ,IAAI,WAAW,IAAI;AACrD;AAqDO,IAAM,aAAa,CACtB,WACA,YAGC;AACD,QAAM,uBAAuB,OAAO,QAAQ,SAAS,EAAE;AAAA,IACnD,CAAC,CAAC,KAAK,QAAQ,MAAM,CAAC,KAAK,SAAS,OAAO,CAAC;AAAA,EAChD;AAEA,QAAM,cAAc,qBAAqB;AAAA,IACrC,CAAC,CAAC,EAAE,UAAU,MAAM,sBAAsB;AAAA,EAC9C;AAEA,MAAI,aAAa;AACb,YAAQ,YAAY;AAChB,YAAM,iBAAiB,MAAM,QAAQ;AAAA,QACjC,qBAAqB,IAAI,OAAO,CAAC,KAAK,UAAU,MAAM;AAAA,UAClD;AAAA,UACA,MAAM;AAAA,QACV,CAAC;AAAA,MACL;AACA,aAAO,OAAO,YAAY,cAAc;AAAA,IAC5C,GAAG;AAAA,EACP;AAEA,SAAO,OAAO,YAAY,oBAAoB;AAClD;","names":[]}
+{"version":3,"sources":["../src/provider.ts","../src/scope.ts","../src/mock-map.ts","../src/collection-resolution.ts"],"sourcesContent":["import { MockMap } from \"./mock-map\";\nimport { Scope } from \"./scope\";\n\n/**\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n */\nexport type Resolver<T> = (context?: ResolutionContext) => T;\n\n/**\n * A function that resolves an instance or a `Promise` of a particular type\n * based on a resolution context passed to it.\n */\nexport type Provider<T> = Resolver<T>;\n\n/**\n * A context used by providers to resolve instances\n * based on current scope and mocks.\n */\nexport type ResolutionContext = {\n    scope?: Scope;\n    mocks?: MockMap;\n};\n\n/**\n * Creates a transient provider that will resolve a new instance on each call.\n *\n * @example\n * ```ts\n * const getThing = transient(() => createThing())\n * getThing() !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The transient provider.\n */\nexport const transient = <T>(resolver: Resolver<T>): Provider<T> => {\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        return resolver(context);\n    };\n\n    return instance;\n};\n\n/**\n * Creates a singleton provider that will resolve an instance once\n * and return it on every call.\n *\n * @example\n * ```ts\n * const getThing = singleton(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The singleton provider.\n */\nexport const singleton = <T>(resolver: Resolver<T>): Provider<T> => {\n    let resolved = false;\n    let resolution: T | undefined;\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (resolved) return resolution!;\n\n        resolution = resolver(context);\n        resolved = true;\n\n        return resolution;\n    };\n\n    return instance;\n};\n\n/**\n * Creates a scoped provider that will take its resolution from a passed scope\n * or create a new one and save it if there is none.\n * If no scope is passed, it will act as a singleton.\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * getThing() === getThing()\n * ```\n *\n * @example\n * ```ts\n * const getThing = scoped(() => createThing())\n * const scope = createScope()\n * getThing({ scope }) === getThing({ scope }) !== getThing()\n * ```\n *\n * @param resolver\n * A function that returns a value of a particular type\n * with a resolution context being passed to it.\n *\n * @returns The scoped provider.\n */\nexport const scoped = <T>(resolver: Resolver<T>): Provider<T> => {\n    const singletonFallback = singleton(resolver);\n\n    const instance: Resolver<T> = (context) => {\n        const maybeMock = context?.mocks?.get(instance);\n        if (maybeMock) return maybeMock(context);\n\n        if (!context?.scope) return singletonFallback(context);\n\n        const resolution = context.scope.has(resolver)\n            ? context.scope.get(resolver)\n            : resolver(context);\n        context.scope.set(resolver, resolution);\n\n        return resolution;\n    };\n\n    return instance;\n};\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n */\nexport type Scope = Map<Resolver<any>, any>;\n\n/**\n * Creates a `Map` of providers to their instances\n * that is then passed to a provider call in a resolution context object\n * to resolve instances of scoped providers within it.\n *\n * @example\n * ```ts\n * const requestScope = createScope()\n *\n * app.use(() => {\n *     const db = getDb({ scope: requestScope })\n *     // ...\n * })\n * ```\n *\n * @returns The map instance.\n */\nexport const createScope = (): Scope => new Map();\n","import { Resolver } from \"./provider\";\n\n/**\n * A `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n */\nexport type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, \"set\" | \"get\"> & {\n    /**\n     * Sets a mock for a provider.\n     *\n     * @param provider - The original provider.\n     * @param mock - The mock provider.\n     */\n    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;\n    /**\n     * Retrieves a mock of a provider. Returns undefined if there's none.\n     *\n     * @param provider - The provider.\n     */\n    get<T>(provider: Resolver<T>): Resolver<T> | undefined;\n};\n\n/**\n * Creates a `Map` of providers to providers of the same type\n * which is then passed to a provider call in a resolution context object\n * in order to replace providers with their mocks.\n *\n * @example\n * ```ts\n * const mocks = createMockMap()\n *     .set(getConfig, getTestConfig)\n *\n * getThing({ mocks })\n * ```\n *\n * @returns The map instance.\n */\nexport const createMockMap = (): MockMap => new Map();\n","import { Provider, ResolutionContext } from \"./provider\";\n\ntype ProviderList = Provider<any>[];\ntype ProviderRecord = Record<string, Provider<any>>;\n\ntype InferProviderCollectionResolutions<\n    Providers extends ProviderList | ProviderRecord,\n> = {\n    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;\n};\n\n/**\n * Awaits all promises and wraps the collection in a promise\n * if there'ss at least one `Promise` in the collection,\n * otherwise returns an untouched type.\n */\ntype AwaitValuesInCollection<T extends any[] | Record<any, any>> =\n    Promise<any> extends T[keyof T]\n        ? Promise<{\n              [I in keyof T]: T[I] extends Promise<infer T> ? T : T[I];\n          }>\n        : T;\n\n/**\n * Calls every provider in a list with a provided resolution context\n * and returns a list of resolutions. Returns a `Promise` of a list\n * of awaited resolutions if there's at least one `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveList(\n *     [getA, getB, getC],\n *     { scope }\n * )\n *\n * resolutions == [\n *     getA({ scope }),\n *     await getB({ scope }),\n *     getC({ scope })\n * ]\n * ```\n *\n * @param providers - The list of providers.\n * @param context - The resolution context.\n *\n * @returns The list of resolutions.\n */\nexport const resolveList = <const Providers extends ProviderList>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutions = providers.map((provider) => provider(context));\n\n    const hasPromises = resolutions.some(\n        (resolution) => resolution instanceof Promise,\n    );\n\n    return (hasPromises ? Promise.all(resolutions) : resolutions) as any;\n};\n\n/**\n * Calls every provider in a map with a provided resolution context\n * and returns a map with identical keys but with resolutions in values instead.\n * Returns a `Promise` of a map of awaited resolutions if there's at least one\n * `Promise` in the resolutions.\n *\n * @example\n * Only sync providers:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(() => createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @example\n * Some provider is async:\n * ```ts\n * const getA = scoped(() => createA())\n * const getB = scoped(async () => await createB())\n * const getC = scoped(() => createC())\n *\n * const scope = createScope()\n * const resolutions = await resolveMap(\n *     { a: getA, b: getB, c: getC },\n *     { scope }\n * )\n *\n * resolutions == {\n *     a: getA({ scope }),\n *     b: await getB({ scope }),\n *     c: getC({ scope })\n * }\n * ```\n *\n * @param providers - The map of providers.\n * @param context - The resolution context.\n *\n * @returns The map of resolutions.\n */\nexport const resolveMap = <const Providers extends ProviderRecord>(\n    providers: Providers,\n    context?: ResolutionContext,\n): AwaitValuesInCollection<\n    InferProviderCollectionResolutions<Providers>\n> => {\n    const resolutionMapEntries = Object.entries(providers).map(\n        ([key, provider]) => [key, provider(context)],\n    );\n\n    const hasPromises = resolutionMapEntries.some(\n        ([, resolution]) => resolution instanceof Promise,\n    );\n\n    if (hasPromises) {\n        return (async () => {\n            const awaitedEntries = await Promise.all(\n                resolutionMapEntries.map(async ([key, resolution]) => [\n                    key,\n                    await resolution,\n                ]),\n            );\n            return Object.fromEntries(awaitedEntries);\n        })() as any;\n    }\n\n    return Object.fromEntries(resolutionMapEntries);\n};\n"],"mappings":";AAuCO,IAAM,YAAY,CAAI,aAAuC;AAChE,QAAM,WAAwB,CAAC,YAAY;AAxC/C;AAyCQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,WAAO,SAAS,OAAO;AAAA,EAC3B;AAEA,SAAO;AACX;AAkBO,IAAM,YAAY,CAAI,aAAuC;AAChE,MAAI,WAAW;AACf,MAAI;AAEJ,QAAM,WAAwB,CAAC,YAAY;AAtE/C;AAuEQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,SAAU,QAAO;AAErB,iBAAa,SAAS,OAAO;AAC7B,eAAW;AAEX,WAAO;AAAA,EACX;AAEA,SAAO;AACX;AA0BO,IAAM,SAAS,CAAI,aAAuC;AAC7D,QAAM,oBAAoB,UAAU,QAAQ;AAE5C,QAAM,WAAwB,CAAC,YAAY;AAhH/C;AAiHQ,UAAM,aAAY,wCAAS,UAAT,mBAAgB,IAAI;AACtC,QAAI,UAAW,QAAO,UAAU,OAAO;AAEvC,QAAI,EAAC,mCAAS,OAAO,QAAO,kBAAkB,OAAO;AAErD,UAAM,aAAa,QAAQ,MAAM,IAAI,QAAQ,IACvC,QAAQ,MAAM,IAAI,QAAQ,IAC1B,SAAS,OAAO;AACtB,YAAQ,MAAM,IAAI,UAAU,UAAU;AAEtC,WAAO;AAAA,EACX;AAEA,SAAO;AACX;;;ACrGO,IAAM,cAAc,MAAa,oBAAI,IAAI;;;ACYzC,IAAM,gBAAgB,MAAe,oBAAI,IAAI;;;ACmC7C,IAAM,cAAc,CACvB,WACA,YAGC;AACD,QAAM,cAAc,UAAU,IAAI,CAAC,aAAa,SAAS,OAAO,CAAC;AAEjE,QAAM,cAAc,YAAY;AAAA,IAC5B,CAAC,eAAe,sBAAsB;AAAA,EAC1C;AAEA,SAAQ,cAAc,QAAQ,IAAI,WAAW,IAAI;AACrD;AAqDO,IAAM,aAAa,CACtB,WACA,YAGC;AACD,QAAM,uBAAuB,OAAO,QAAQ,SAAS,EAAE;AAAA,IACnD,CAAC,CAAC,KAAK,QAAQ,MAAM,CAAC,KAAK,SAAS,OAAO,CAAC;AAAA,EAChD;AAEA,QAAM,cAAc,qBAAqB;AAAA,IACrC,CAAC,CAAC,EAAE,UAAU,MAAM,sBAAsB;AAAA,EAC9C;AAEA,MAAI,aAAa;AACb,YAAQ,YAAY;AAChB,YAAM,iBAAiB,MAAM,QAAQ;AAAA,QACjC,qBAAqB,IAAI,OAAO,CAAC,KAAK,UAAU,MAAM;AAAA,UAClD;AAAA,UACA,MAAM;AAAA,QACV,CAAC;AAAA,MACL;AACA,aAAO,OAAO,YAAY,cAAc;AAAA,IAC5C,GAAG;AAAA,EACP;AAEA,SAAO,OAAO,YAAY,oBAAoB;AAClD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atomic-di",
-  "version": "1.0.0-rc.2",
+  "version": "1.1.0",
   "description": "This library implements lifetimes, scopes and mocking for pure dependency injection.",
   "repository": "https://github.com/ncor/atomic-di",
   "bugs": "https://github.com/ncor/atomic-di/issues",