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

package/dist/index.d.mts

@@ -1,185 +1,139 @@
 /**
- * A map of providers to providers of the same type.
- * 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 object
+ * 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.
- * ```ts
- * const otherProvider =
- *     transitive(() => ...)
- * const otherProviderMock: typeof otherProvider =
- *     scoped(() => ...)
- *
- * const mocks = createMockMap()
- * mocks.set(otherProvider, otherProviderMock)
- *
- * provider({ mocks })
- * ```
  */
-type MockMap = Omit<Map<Provider<any>, Provider<any>>, "set" | "get"> & {
+type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, "set" | "get"> & {
     /**
      * Sets a mock for a provider.
      *
      * @param provider - The original provider.
      * @param mock - The mock provider.
      */
-    set<T>(provider: Provider<T>, mock: Provider<T>): MockMap;
+    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;
     /**
      * Retrieves a mock of a provider. Returns undefined if there's none.
      *
      * @param provider - The provider.
      */
-    get<T>(provider: Provider<T>): Provider<T> | undefined;
+    get<T>(provider: Resolver<T>): Resolver<T> | undefined;
 };
 /**
- * Creates a mock map instance,
- * a map of providers to providers of the same type.
- * 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 object
+ * Creates 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.
- * ```ts
- * const otherProvider =
- *     transitive(() => ...)
- * const otherProviderMock: typeof otherProvider =
- *     scoped(() => ...)
  *
+ * @example
+ * ```ts
  * const mocks = createMockMap()
- * mocks.set(otherProvider, otherProviderMock)
+ *     .set(getConfig, getTestConfig)
  *
- * provider({ mocks })
+ * getThing({ mocks })
  * ```
  *
- * @returns The mock map instance.
+ * @returns The map instance.
  */
 declare const createMockMap: () => MockMap;
 
 /**
- * A map of providers to their instances.
- *
- * Passed to a provider call in a resolution context object
+ * 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.
- * ```ts
- * const scope = createScope()
- * provider({ scope })
- * ```
  */
-type Scope = Map<Provider<any>, any>;
+type Scope = Map<Resolver<any>, any>;
 /**
- * Creates a scope instance.
- *
- * Scope is passed to a provider call in a resolution context object
+ * 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.
+ *
+ * @example
  * ```ts
- * const scope = createScope()
- * provider({ scope })
+ * const requestScope = createScope()
+ *
+ * app.use(() => {
+ *     const db = getDb({ scope: requestScope })
+ *     // ...
+ * })
  * ```
  *
- * @returns The scope instance.
+ * @returns The map instance.
  */
 declare const createScope: () => Scope;
 
 /**
- * A wrapper around the resolver(factory) for contextual dependency resolution.
- *
- * Resolves an instance by calling a resolver
- * with a resolution context that will be propagated
- * throughout a dependency tree.
- *
- * When passing a scope it will try to get an instance from it
- * or create a new one and put it there.
- *
- * When passing mocks, it will try to get its own mock version,
- * and if there is one, it will use it instead of itself.
- */
-type Provider<T> = (context?: ResolutionContext) => T;
-/**
- * A resolution lifetime.
- *
- * Passed when creating a provider to determine its behavior.
- *
- * `"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
- * 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.
+ * A function that returns a value of a particular type
+ * with a resolution context being passed to it.
  */
-type Lifetime = "transient" | "singleton" | "scoped";
+type Resolver<T> = (context?: ResolutionContext) => T;
 /**
- * A function that creates an instance using a resolution context.
+ * A function that resolves an instance or a `Promise` of a particular type
+ * based on a resolution context passed to it.
  */
-type Resolver<T> = (context?: ResolutionContext) => T;
+type Provider<T> = Resolver<T>;
 /**
- * An object that holds information about a scope and provider mocks.
- *
- * Passed to the provider call to resolve scope instances and mock providers.
+ * A context used by providers to resolve instances
+ * based on current scope and mocks.
  */
 type ResolutionContext = {
     scope?: Scope;
     mocks?: MockMap;
 };
 /**
- * Creates a provider instance,
- * a wrapper around a resolver(factory) for contextual dependency resolution.
- *
- * @param lifetime
- * A resolution lifetime.
- *
- * `"transient"` doesn't provide any modifications to a resolver behaviour,
- * so the resolver will create a new instance on each request.
+ * Creates a transient provider that will resolve a new instance on each call.
  *
- * `"singleton"` forces the resolver to create an instance once
- * and return it in subsequent requests.
- *
- * `"scoped"` forces the resolver to take its resolution from a provided 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.
- *
- * @param resolver
- * The function that creates an instance using a resolution context.
- *
- * @returns The provider instance.
- */
-declare const provide: <T>(lifetime: Lifetime, resolver: Resolver<T>) => Provider<T>;
-/**
- * Creates a transient provider instance,
- * a wrapper around a resolver(factory) for contextual dependency resolution
- * that will create a new instance on each request.
+ * @example
+ * ```ts
+ * const getThing = transient(() => createThing())
+ * getThing() !== getThing()
+ * ```
  *
  * @param resolver
- * The function that creates an instance using a resolution context.
+ * A function that returns a value of a particular type
+ * with a resolution context being passed to it.
  *
- * @returns The transient provider instance.
+ * @returns The transient provider.
  */
 declare const transient: <T>(resolver: Resolver<T>) => Provider<T>;
 /**
- * Creates a transient provider instance,
- * a wrapper around a resolver(factory) for contextual dependency resolution
- * that will create an instance once and return it in subsequent requests.
+ * Creates a singleton provider that will resolve an instance once
+ * and return it on every call.
+ *
+ * @example
+ * ```ts
+ * const getThing = singleton(() => createThing())
+ * getThing() === getThing()
+ * ```
  *
  * @param resolver
- * The function that creates an instance using a resolution context.
+ * A function that returns a value of a particular type
+ * with a resolution context being passed to it.
  *
- * @returns The singleton provider instance.
+ * @returns The singleton provider.
  */
 declare const singleton: <T>(resolver: Resolver<T>) => Provider<T>;
 /**
- * Creates a transient provider instance,
- * a wrapper around a resolver(factory) for contextual dependency resolution
- * that will take its resolution from a provided scope
+ * 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 request.
+ * If no scope is passed, it will create a new instance on each call.
+ *
+ * @example
+ * ```ts
+ * const getThing = scoped(() => createThing())
+ * getThing() !== getThing()
+ * ```
+ *
+ * @example
+ * ```ts
+ * const getThing = scoped(() => createThing())
+ * const scope = createScope()
+ * getThing({ scope }) === getThing({ scope })
+ * ```
  *
  * @param resolver
- * The function that creates an instance using a resolution context.
+ * A function that returns a value of a particular type
+ * with a resolution context being passed to it.
  *
- * @returns The scoped provider instance.
+ * @returns The scoped provider.
  */
 declare const scoped: <T>(resolver: Resolver<T>) => Provider<T>;
 
@@ -193,31 +147,111 @@ type InferProviderCollectionResolutions<Providers extends ProviderList | Provide
  * if there'ss at least one `Promise` in the collection,
  * otherwise returns an untouched type.
  */
-type AwaitAllValuesInCollection<T extends any[] | Record<any, any>> = Promise<any> extends T[keyof T] ? Promise<{
+type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any> extends T[keyof T] ? Promise<{
     [I in keyof T]: T[I] extends Promise<infer T> ? T : T[I];
 }> : T;
 /**
  * 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.
+ * 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
+ * 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 }
+ * )
+ *
+ * resolutions == [
+ *     getA({ scope }),
+ *     getB({ scope }),
+ *     getC({ scope })
+ * ]
+ * ```
+ *
+ * @example
+ * Some provider is async:
+ * ```ts
+ * const getA = scoped(() => createA())
+ * const getB = scoped(async () => await createB())
+ * const getC = scoped(() => createC())
+ *
+ * const scope = createScope()
+ * const resolutions = resolveList(
+ *     [getA, getB, getC],
+ *     { scope }
+ * )
+ *
+ * resolutions == [
+ *     getA({ scope }),
+ *     await getB({ scope }),
+ *     getC({ scope })
+ * ]
+ * ```
  *
  * @param providers - The list of providers.
  * @param context - The resolution context.
  *
  * @returns The list of resolutions.
  */
-declare const resolveList: <const Providers extends ProviderList>(providers: Providers, context?: ResolutionContext) => AwaitAllValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveList: <const Providers extends ProviderList>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
 /**
  * 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.
+ * Returns a `Promise` of a map of awaited resolutions if there's at least one
+ * `Promise` in the resolutions.
+ *
+ * @example
+ * 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 }
+ * )
+ *
+ * resolutions == {
+ *     a: getA({ scope }),
+ *     b: getB({ scope }),
+ *     c: getC({ scope })
+ * }
+ * ```
+ *
+ * @example
+ * 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 resolveMap(
+ *     { a: getA, b: getB, c: getC },
+ *     { scope }
+ * )
+ *
+ * resolutions == {
+ *     a: getA({ scope }),
+ *     b: await getB({ scope }),
+ *     c: getC({ scope })
+ * }
+ * ```
  *
  * @param providers - The map of providers.
  * @param context - The resolution context.
  *
  * @returns The map of resolutions.
  */
-declare const resolveMap: <const Providers extends ProviderRecord>(providers: Providers, context?: ResolutionContext) => AwaitAllValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveMap: <const Providers extends ProviderRecord>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
 
-export { type Lifetime, type MockMap, type Provider, type ResolutionContext, type Resolver, type Scope, createMockMap, createScope, provide, resolveList, resolveMap, scoped, singleton, transient };
+export { type MockMap, type Provider, type ResolutionContext, type Resolver, type Scope, createMockMap, createScope, resolveList, resolveMap, scoped, singleton, transient };