atomic-di 0.9.1-beta.3 → 1.0.0-rc.1

package/README.md

@@ -1,15 +1,64 @@
 # atomic-di
 
-> **This is not an IoC container or a service locator.**
+This library implements lifetimes, scopes and mocking for pure dependency injection.
 
-This library provides a set of tools that implement missing features such as lifetimes, scopes and mocking in a pure factory-based dependency injection.
+# Table of contents
 
-### Key features
+- [Intro](#Intro)
+- [Installation](#Installation)
+- [Usage](#Usage)
+    - [Providers](#Providers)
+        - [Transient](#Transient)
+        - [Singleton](#Singleton)
+        - [Scoped](#Scoped)
+    - [Resolution context](#Resolution-context)
+    - [Mocking](#Mocking)
+    - [Scopes](#Scopes)
+    - [Bulk resolutions](#Bulk-resolutions)
+        - [List resolution](#List-resolution)
+        - [Map resolution](#Map-resolution)
+- [Reference](#Reference)
+    - [Functions](#Functions)
+        - [transient](#transient)
+        - [singleton](#singleton)
+        - [scoped](#scoped)
+        - [createMockMap](#createMockMap)
+        - [createScope](#createScope)
+    - [Types](#Types)
+        - [Provider](#Provider)
+        - [ResolutionContext](#ResolutionContext)
+        - [MockMap](#MockMap)
+        - [Scope](#Scope)
 
--   **Small & fast.** The usage is based on the use of a thin, performant abstraction that wraps factories, adding a couple of operations needed for resolution in a dynamic context.
--   **Transparent.** All the logic for creating instances is written by the developer himself.
--   **Non-invasive.** Does not require adding decorators, registrations or any additional logic to the business logic of the application.
--   **Atomic.** There's no global container. The creation of instances occurs in factories that can be shared among themselves.
+# Intro
+
+## Prerequisites
+
+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.
+
+This library is an attempt to provide full-featured dependency injection **without containers**.
+
+## Problems and solutions
+
+### 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.
+
+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.
+
+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.
+
+### Mocking
+
+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.
 
 # Installation
 
@@ -18,223 +67,540 @@ You can use any package manager.
 ```bash
 npm add atomic-di
 ```
-
 ```bash
 npx jsr add @ensi/di
 ```
 
 # Usage
 
-Not written yet.
+#### Table of contents
+- [Providers](#Providers)
+    - [Transient](#Transient)
+    - [Singleton](#Singleton)
+    - [Scoped](#Scoped)
+- [Resolution context](#Resolution-context)
+- [Mocking](#Mocking)
+- [Scopes](#Scopes)
+- [Bulk resolutions](#Bulk-resolutions)
+    - [List resolution](#List-resolution)
+    - [Map resolution](#Map-resolution)
 
-# API
+## Providers
 
-## `Provider`
+The library provides functions that create providers with behavior typical of singletons, transients, and scopeds.
 
+### Transient
+
+Transient providers are created using the `transient` function:
 ```ts
-type Provider<T> = (context?: ResolutionContext) => T;
+const getThing = transient(() => createThing())
 ```
 
-A function wrapper around the [resolver](#Resolver)(factory) for contextual dependency resolution. Resolves an instance by calling a resolver with an **optional** [resolution context](#ResolutionContext) that will be propagated throughout a dependency tree. Can act as a transient, singleton or scoped, which is [determined by the lifetime](#Lifetime) at creation.
+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).
+
+### Singleton
 
+Singleton providers are created using the `singleton` function:
 ```ts
-provider({ scope, mocks });
+const getA = singleton(() => createA())
+const getB = transient((c) => createB(getA(c)))
 ```
 
-When passing a [scope](#Scope) it will try to get an instance from it or create a new one and put it there.
+In this case, calling `getA` will always result in the same instance, and the passed factory will only be called once:
+```ts
+getA() === getA() == getB().A === getB().A
+```
 
-When passing [mocks](#MockMap), it will try to get its own mock version and if there is one, it will use it instead of itself.
+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).
 
-### `provide`
+### Scoped
 
+Scoped providers are created using the `scoped` function:
 ```ts
-function provide<T>(lifetime: Lifetime, resolver: Resolver<T>): Provider<T>;
+const getThing = scoped(() => createThing())
 ```
 
-Creates a provider instance.
+When calling this provider without passing a scope to the resolution context, it will create a new unique instance:
+```ts
+getThing() !== getThing()
+```
+
+To get resolutions within a scope, we need to pass it to the provider call in the resolution context object:
+```ts
+const scope = createScope()
+
+getThing({ scope }) === getThing({ scope })
+```
 
--   `lifetime`: A resolution [lifetime](#Lifetime).
--   `resolver`: A function that creates an instance using a [resolution context](#ResolutionContext). If the function calls other providers, the context **must** be passed to their calls.
+You can read more about scopes [here](#Scopes).
 
+## 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.
+
+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.
+
+#### Incorrect
 ```ts
-const getInstance = provide("transient", (context) =>
-    createInstance(getOtherInstance(context)),
-);
+const getA = singleton(() => createA())
+const getB = scoped(() => createB(getA()))
+const getC = scoped(() => createC(getB()))
 ```
 
-### `transient`
+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.
 
+#### Correct
 ```ts
-function transient<T>(resolver: Resolver<T>): Provider<T>;
+const getA = singleton(() => createA())
+const getB = scoped((c) => createB(getA(c)))
+const getC = scoped((c) => createC(getB(c)))
 ```
 
-An alias for [provide](#provide) with `"transient"` lifetime. Creates a [transient](#Lifetime) provider instance.
+In this case, `getC` will propagate the context, and `getB` and `getA` will be aware of the 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).
 
+## Mocking
+
+To replace implementations inside factories, we can use a mock map. To create one, we can use the `createMockMap` function:
 ```ts
-const getInstance = transient((context) =>
-    createInstance(...)
-)
+const mockMap = createMockMap()
+```
 
-getInstance() !== getInstance()
+To register a mock, you need to `set` an entry with the original provider in the key and its mock in the value:
+```ts
+mockMap.set(getDatabase, getMockDatabase)
 ```
 
-### `singleton`
+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.
 
+#### Direct replacement
 ```ts
-function singleton<T>(resolver: Resolver<T>): Provider<T>;
+const getA = transient(() => 1)
+const getB = transient((c) => getA(c) + 1)
+
+getB() === 2
 ```
+```ts
+const getBee = transient((c) => getA(c) + "bee")
+const mocks = createMockMap().set(getB, getBee)
 
-An alias for [provide](#provide) with `"singleton"` lifetime. Creates a [singleton](#Lifetime) provider instance.
+getB({ mocks }) === "1bee"
+```
 
+#### Direct/transitive dependency replacement
 ```ts
-const getInstance = singleton((context) =>
-    createInstance(...)
-)
+const getA = transient(() => 1)
+const getB = transient((c) => getA(c) + 1)
+const getC = transient((c) => getB(c) + 1)
 
-getInstance() === getInstance()
+getC() === 3
 ```
+```ts
+const getSea = transient((c) => getB(c) + "sea")
+const mocks = createMockMap().set(getC, getSea)
 
-### `scoped`
+getC({ mocks }) === "2sea"
+```
 
+## Scopes
+
+In this library, a scope is a map of providers to their resolutions. To create one, you can use the `createScope` function:
 ```ts
-function scoped<T>(resolver: Resolver<T>): Provider<T>;
+const scope = createScope()
 ```
 
-An alias for [provide](#provide) with `"scoped"` lifetime. Creates a [scoped](#Lifetime) provider instance.
+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.
 
+#### Direct scoped provider call
 ```ts
-const getInstance = scoped((context) =>
-    createInstance(...)
-)
+const getThing = scoped(() => createThing())
+```
+```ts
+const thing1 = getThing()
+const thing2 = getThing()
 
-getInstance() !== getInstance()
-getInstance({ scope }) === getInstance({ scope })
+thing1 !== thing2
 ```
+```ts
+const thing1 = getThing({ scope })
+const thing2 = getThing({ scope })
 
-## `Resolver`
+thing1 === thing2
+```
 
+#### Scoped provider as direct/transitive dependency
 ```ts
-type Resolver<T> = (context?: ResolutionContext) => T;
+const getScopedDependency = scoped(() => ...)
+const getThing = transitive((c) =>
+    createThing(getScopedDependency(c))
+)
 ```
+```ts
+const thing1 = getThing()
+const thing2 = getThing()
+
+thing1.scopedDependency !== thing2.scopedDependency
+```
+```ts
+const thing1 = getThing({ scope })
+const thing2 = getThing({ scope })
+
+thing1.scopedDependency === thing2.scopedDependency
+```
+
+## 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.
 
-A function that creates an instance using a [resolution context](#ResolutionContext).
+### List resolution
 
-## `Lifetime`
+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.
 
+#### Only sync providers
 ```ts
-type Lifetime = "transient" | "singleton" | "scoped";
+const getA = scoped(() => createA())
+const getB = scoped(() => createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = resolveList(
+    [getA, getB, getC],
+    { scope }
+)
+```
+```ts
+resolutions == [
+    getA({ scope }),
+    getB({ scope }),
+    getC({ scope })
+]
 ```
 
-A resolution lifetime. Passed when [creating a provider](#provide) to determine its behaviour.
+#### Some provider is async
+```ts
+const getA = scoped(() => createA())
+const getB = scoped(async () => await createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = await resolveList(
+    [getA, getB, getC],
+    { scope }
+)
+```
+```ts
+resolutions == [
+    getA({ scope }),
+    await getB({ scope }),
+    getC({ scope })
+]
+```
 
--   `"transient"` doesn't provide any modifications to a resolver behaviour, so the resolver will create a new instance on each request.
--   `"singleton"` forces the resolver to create an instance once and return it in subsequent requests.
--   `"scoped"` forces the resolver to take its instance from a provided [scope](#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 request.
+### Map resolution
 
-## `ResolutionContext`
+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.
 
+#### Only sync providers
 ```ts
-type ResolutionContext = {
-    scope?: Scope;
-    mocks?: MockMap;
-};
+const getA = scoped(() => createA())
+const getB = scoped(() => createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = resolveMap(
+    { a: getA, b: getB, c: getC },
+    { scope }
+)
+```
+```ts
+resolutions == {
+    a: getA({ scope }),
+    b: getB({ scope }),
+    c: getC({ scope })
+}
 ```
 
-An object that holds information about a [scope](#Scope) and provider [mocks](#MockMap). Passed to the [provider call](#Provider) to resolve scope instances and mock providers.
+#### Some provider is async
+```ts
+const getA = scoped(() => createA())
+const getB = scoped(async () => await createB())
+const getC = scoped(() => createC())
 
-## `Scope`
+const scope = createScope()
+const resolutions = await resolveMap(
+    { a: getA, b: getB, c: getC },
+    { scope }
+)
+```
+```ts
+resolutions == {
+    a: getA({ scope }),
+    b: await getB({ scope }),
+    c: getC({ scope })
+}
+```
+
+# Reference
 
+#### Table of contents
+- [Functions](#Functions)
+    - [transient](#transient)
+    - [singleton](#singleton)
+    - [scoped](#scoped)
+    - [createMockMap](#createMockMap)
+    - [createScope](#createScope)
+- [Types](#Types)
+    - [Provider](#Provider)
+    - [ResolutionContext](#ResolutionContext)
+    - [MockMap](#MockMap)
+    - [Scope](#Scope)
+
+## Functions
+
+### `transient`
 ```ts
-type Scope = Map<Provider<any>, any>;
+function transient<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.
 
-A `Map` of [providers](#Provider) to their instances. Passed to a provider call in a resolution context object to resolve instances of scoped providers within it.
+Creates a transient provider that will resolve a new instance on each call.
 
+#### Example
 ```ts
-const scope = createScope();
-provider({ scope });
+const getThing = transient(() => createThing())
+getThing() !== getThing()
 ```
 
-### `createScope`
+### `singleton`
+```ts
+function singleton<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 singleton provider that will resolve an instance once and return it on every call.
 
+#### Example
 ```ts
-function createScope(): Scope;
+const getThing = singleton(() => createThing())
+getThing() === getThing()
 ```
 
-Creates a scope instance.
+### `scoped`
+```ts
+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.
 
-## `MockMap`
+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.
 
+#### Example 1
 ```ts
-type MockMap = Omit<Map<Provider<any>, Provider<any>>, "set" | "get"> & {
-    set<T>(provider: Provider<T>, mock: Provider<T>): MockMap;
-    get<T>(provider: Provider<T>): Provider<T> | undefined;
-};
+const getThing = scoped(() => createThing())
+getThing() !== getThing()
 ```
 
-A `Map` of [providers](#Provider) to providers of the same type. [Lifetime](#Lifetime) is not a part of `Provider` type, so you can use a different one if necessary. Passed to a provider call in a [resolution context](#ResolutionContext) object in order to replace providers with their mocks.
+#### Example 2
+```ts
+const getThing = scoped(() => createThing())
+const scope = createScope()
+getThing({ scope }) === getThing({ scope })
+```
 
+### `createMockMap`
 ```ts
-const otherProvider =
-    transitive(() => ...)
-const otherProviderMock: typeof otherProvider =
-    scoped(() => ...)
+function createMockMap(): MockMap
+```
+
+Creates a `Map` of providers to providers of the samep type which is then passed to a provider call in a resolution context object in order to replace providers with their mocks.
 
+#### Example
+```ts
 const mocks = createMockMap()
-mocks.set(otherProvider, otherProviderMock)
+    .set(getConfig, getTestConfig)
 
-provider({ mocks })
+getThing({ mocks })
 ```
 
-### `createMockMap`
-
+### `createScope`
 ```ts
-function createMockMap(): MockMap;
+function createScope(): Scope
 ```
 
-Creates a mock map instance.
+Creates a `Map` of providers to their instances that is then passed to a provider call in a resolution context object to resolve instances of scoped providers within it.
 
-## Bulk resolutions
+#### Example
+```ts
+const requestScope = createScope()
 
-### `resolveList`
+app.use(() => {
+    const db = getDb({ scope: requestScope })
+    // ...
+})
+```
 
+### `resolveList`
 ```ts
 function resolveList<const Providers extends ProviderList>(
     providers: Providers,
-    context?: ResolutionContext,
-): AwaitAllValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+    context?: ResolutionContext
+): AwaitValuesInCollection<
+    InferProviderCollectionResolutions<Provider>
+>
 ```
+- `providers`: A list of providers.
+- `context?`: A resolution context.
 
--   `providers`: A list of providers.
--   `context`: A resolution context.
+Calls every provider in a list with a provided resolution context and returns a list of resolutions. Returns a `Promise` of a list of awaited resolutions if there's at least one `Promise` in the resolution.
 
-Calls every provider in a list with a provided resolution context and returns a list of resolutions. Returns a promise of a list of awaited resolutions if there's at least one promise in the resolutions.
+#### Example 1
+Only sync providers:
+```ts
+const getA = scoped(() => createA())
+const getB = scoped(() => createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = resolveList(
+    [getA, getB, getC],
+    { scope }
+)
+```
+```ts
+resolutions == [
+    getA({ scope }),
+    getB({ scope }),
+    getC({ scope })
+]
+```
 
+#### Example 2
+Some provider is async:
+```ts
+const getA = scoped(() => createA())
+const getB = scoped(async () => await createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = await resolveList(
+    [getA, getB, getC],
+    { scope }
+)
+```
 ```ts
-const resolutions = resolveList([getA, getB, getC], { scope, mocks });
+resolutions == [
+    getA({ scope }),
+    await getB({ scope }),
+    getC({ scope })
+]
 ```
 
 ### `resolveMap`
-
 ```ts
 function resolveMap<const Providers extends ProviderRecord>(
     providers: Providers,
-    context?: ResolutionContext,
-): AwaitAllValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+    context?: ResolutionContext
+): AwaitValuesInCollection<
+    InferProviderCollectionResolutions<Provider>
+>
 ```
+- `providers`: A map of providers.
+- `context?`: A resolution context.
 
--   `providers`: A map of providers.
--   `context`: A resolution context.
+Calls every provider in a map with a provided resolution context and returns a map with identical keys but with resolutions in values instead. Returns a `Promise` of a map of awaited resolutions if there's at least one `Promise` in the resolutions.
 
-Calsl every provider in a map with a provided resolution context and returns a map with identical keys but with resolutions in values instead. Returns a promise of a map of awaited resolutions if there's at least one promise in the resolutions.
+#### Example 1
+Only sync providers:
+```ts
+const getA = scoped(() => createA())
+const getB = scoped(() => createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = resolveMap(
+    { a: getA, b: getB, c: getC },
+    { scope }
+)
+```
+```ts
+resolutions == {
+    a: getA({ scope }),
+    b: getB({ scope }),
+    c: getC({ scope })
+}
+```
 
+#### Example 2
+Some provider is async:
 ```ts
-const resolutionMap = resolveMap(
+const getA = scoped(() => createA())
+const getB = scoped(async () => await createB())
+const getC = scoped(() => createC())
+
+const scope = createScope()
+const resolutions = await resolveMap(
     { a: getA, b: getB, c: getC },
-    { scope, mocks },
-);
+    { scope }
+)
+```
+```ts
+resolutions == {
+    a: getA({ scope }),
+    b: await getB({ scope }),
+    c: getC({ scope })
+}
+```
+
+## Types
+
+### `Resolver`
+```ts
+type Resolver<T> = (context?: ResolutionContext) => T
+```
+
+A function that returns a value of a particular type with a resolution context being passed to it.
+
+### `Provider`
+```ts
+type Provider<T> = (context?: ResolutionContext) => T
+```
+
+A function that resolves an instance or a `Promise` of a particular type based on a resolution context passed to it.
+
+### `ResolutionContext`
+```ts
+type ResolutionContext = {
+    scope?: Scope;
+    mocks?: MockMap;
+}
 ```
 
+A context used by providers to resolve instances based on current scope and mocks.
+
+### `MockMap`
+```ts
+type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, "set" | "get"> & {
+    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;
+    get<T>(provider: Resolver<T>): Resolver<T> | undefined;
+};
+```
+- `set`: Sets a mock for a provider.
+    - `provider`: The original provider.
+    - `mock`: The mock provider.
+- `get`: Retrieves a mock of a provider. Returns undefined if there's none.
+    - `provider`: The provider.
+
+A `Map` of providers to providers of the same type which is then passed to a provider call in a resolution context object in order to replace providers with their mocks.
+
+### `Scope`
+```ts
+type Scope = Map<Resolver<any>, any>
+```
+
+A `Map` of providers to their instances that is then passed to a provider call in a resolution context object to resolve instances of scoped providers within it.
+
 # Contribution
 
 This is free and open source project licensed under the [MIT License](LICENSE). You could help its development by contributing via [pull requests](https://github.com/ncor/atomic-di/fork) or [submitting an issue](https://github.com/ncor/atomic-di/issues).