atomic-di 1.2.0 → 2.0.1

package/dist/index.d.mts

@@ -1,50 +1,75 @@
+type PromiseAwarePartial<T> = T extends Promise<infer U> ? Promise<Partial<U>> : Partial<T>;
+type Mock<T> = {
+    isPartial: false;
+    resolver: Resolver<T>;
+} | {
+    isPartial: true;
+    resolver: Resolver<PromiseAwarePartial<T>>;
+};
 /**
- * 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.
+ * Immutable map that registers and provides mocks.
+ * Is passed in a resolution context and used by resolvers
+ * to replace or partially replace themselves with a mock if one is defined.
  */
-type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, "set" | "get"> & {
+type MockMap = {
+    /**
+     * Registers a mock for a resolver,
+     * creating a new `MockMap` with this registration.
+     *
+     * @param original - The original resolver.
+     * @param mock - The mock resolver.
+     */
+    mock<T>(original: Resolver<T>, mock: Resolver<T>): MockMap;
     /**
-     * Sets a mock for a provider.
+     * Registers a partial mock for a resolver,
+     * creating a new `MockMap` with this registration.
+     * In this case, the mock resolver's resolution object will be
+     * merged with the original resolver's resolution object,
+     * overwriting certain fields.
      *
-     * @param provider - The original provider.
-     * @param mock - The mock provider.
+     * @param original - The original resolver.
+     * @param mock - The mock resolver.
      */
-    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;
+    mockPartially<T extends object>(original: Resolver<T>, mock: Resolver<PromiseAwarePartial<T>>): MockMap;
     /**
-     * Retrieves a mock of a provider. Returns undefined if there's none.
+     * Returns a mock of a resolver
+     * or `undefined` if one is not registered.
      *
-     * @param provider - The provider.
+     * @param original - The original resolver.
      */
-    get<T>(provider: Resolver<T>): Resolver<T> | undefined;
+    get<T>(original: Resolver<T>): Mock<T> | undefined;
 };
 /**
- * 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.
+ * Creates a mock map, an immutable map that registers and provides mocks.
+ * Is passed in a resolution context and used by resolvers
+ * to replace or partially replace themselves with a mock if one is defined.
  *
  * @example
  * ```ts
  * const mocks = createMockMap()
- *     .set(getConfig, getTestConfig)
+ *     .mock(getDependency, getDependencyMock)
+ *     .mockPartially(
+ *         getOtherDepedency,
+ *         transient(() => ({ someField: "mock" }))
+ *     )
  *
- * getThing({ mocks })
+ * const entityWithMocks = getEntity({ mocks })
  * ```
  *
- * @returns The map instance.
+ * @returns The mock map.
  */
 declare const createMockMap: () => MockMap;
 
 /**
- * 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.
+ * A `Map` of resolvers to their resolutions.
+ * Is passed in a resolution context and used by scoped resolvers
+ * to retrieve or save resolution within it.
  */
 type Scope = Map<Resolver<any>, any>;
 /**
- * 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.
+ * Creates a `Map` of providers to their instances.
+ * Is passed in a resolution context and used by scoped resolvers
+ * to retrieve or save resolution within it.
  *
  * @example
  * ```ts
@@ -52,97 +77,95 @@ type Scope = Map<Resolver<any>, any>;
  *
  * app.use(() => {
  *     const db = getDb({ scope: requestScope })
- *     // ...
  * })
  * ```
  *
- * @returns The map instance.
+ * @returns The map.
  */
 declare const createScope: () => Scope;
 
 /**
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * A function that takes a resolution context
+ * and returns a value of some type.
  */
-type Resolver<T> = (context?: ResolutionContext) => T;
+type ResolverFn<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.
+ * A function that returns a value of some type
+ * based on a resolution context.
  */
-type Provider<T> = Resolver<T> & {
-    __brand: "provider";
-};
+type Resolver<T> = ResolverFn<T>;
 /**
- * A context used by providers to resolve instances
- * based on current scope and mocks.
+ * A context used by resolvers that defines the behaviour of the resolver
+ * with the passed mocks and scope.
  */
 type ResolutionContext = {
     scope?: Scope;
     mocks?: MockMap;
 };
 /**
- * Creates a transient provider that will resolve a new instance on each call.
+ * Creates a resolver that creates a new resolution on each call.
  *
  * @example
  * ```ts
- * const getThing = transient(() => createThing())
- * getThing() !== getThing()
+ * const getEntity = transient(() => createEntity())
+ * getEntity() !== getEntity()
  * ```
  *
  * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The transient provider.
+ * @returns The transient resolver.
  */
-declare const transient: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const transient: <T>(fn: ResolverFn<T>) => Resolver<T>;
 /**
- * Creates a singleton provider that will resolve an instance once
- * and return it on every call.
+ * Creates a resolver that creates
+ * a resolution once and return it on each call.
  *
  * @example
  * ```ts
- * const getThing = singleton(() => createThing())
- * getThing() === getThing()
+ * const getEntity = singleton(() => createEntity())
+ * getEntity() === getEntity()
  * ```
  *
- * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * @param fn
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The singleton provider.
+ * @returns The singleton resolver.
  */
-declare const singleton: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const singleton: <T>(fn: ResolverFn<T>) => Resolver<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 act as a singleton.
+ * Creates a resolver that takes its resolution
+ * from a scope or create a new one and save it if there is none.
+ * If no scope was passed in a resolution context,
+ * it will act as a singleton.
  *
  * @example
  * ```ts
- * const getThing = scoped(() => createThing())
- * getThing() === getThing()
+ * const getEntity = scoped(() => createEntity())
+ * getEntity() === getEntity()
  * ```
  *
  * @example
  * ```ts
- * const getThing = scoped(() => createThing())
+ * const getEntity = scoped(() => createEntity())
  * const scope = createScope()
- * getThing({ scope }) === getThing({ scope }) !== getThing()
+ * getEntity({ scope }) === getEntity({ scope }) !== getEntity()
  * ```
  *
- * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * @param fn
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The scoped provider.
+ * @returns The scoped resolver.
  */
-declare const scoped: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const scoped: <T>(fn: ResolverFn<T>) => Resolver<T>;
 
-type ProviderList = Provider<any>[];
-type ProviderRecord = Record<string, Provider<any>>;
-type InferProviderCollectionResolutions<Providers extends ProviderList | ProviderRecord> = {
-    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;
+type ResolverList = Resolver<any>[];
+type ResolverRecord = Record<string, Resolver<any>>;
+type InferResolverCollectionResolutions<Resolvers extends ResolverList | ResolverRecord> = {
+    [K in keyof Resolvers]: Resolvers[K] extends Resolver<infer T> ? T : never;
 };
 /**
  * Awaits all promises and wraps the collection in a promise
@@ -153,12 +176,12 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
     [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
+ * Calls every resolver 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
- * Only sync providers:
+ * Only sync resolvers:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(() => createB())
@@ -178,7 +201,7 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
  * ```
  *
  * @example
- * Some provider is async:
+ * Some resolver is async:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(async () => await createB())
@@ -197,20 +220,20 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
  * ]
  * ```
  *
- * @param providers - The list of providers.
+ * @param resolvers - The list of resolvers.
  * @param context - The resolution context.
  *
  * @returns The list of resolutions.
  */
-declare const resolveList: <const Providers extends ProviderList>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveList: <const Resolvers extends ResolverList>(resolvers: Resolvers, context?: ResolutionContext) => AwaitValuesInCollection<InferResolverCollectionResolutions<Resolvers>>;
 /**
- * Calls every provider in a map with a provided resolution context
+ * Calls every resolver 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
- * Only sync providers:
+ * Only sync resolvers:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(() => createB())
@@ -230,7 +253,7 @@ declare const resolveList: <const Providers extends ProviderList>(providers: Pro
  * ```
  *
  * @example
- * Some provider is async:
+ * Some resolver is async:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(async () => await createB())
@@ -249,11 +272,11 @@ declare const resolveList: <const Providers extends ProviderList>(providers: Pro
  * }
  * ```
  *
- * @param providers - The map of providers.
+ * @param resolvers - The map of resolvers.
  * @param context - The resolution context.
  *
  * @returns The map of resolutions.
  */
-declare const resolveMap: <const Providers extends ProviderRecord>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveMap: <const Resolvers extends ResolverRecord>(resolvers: Resolvers, context?: ResolutionContext) => AwaitValuesInCollection<InferResolverCollectionResolutions<Resolvers>>;
 
-export { type MockMap, type Provider, type ResolutionContext, type Resolver, type Scope, createMockMap, createScope, resolveList, resolveMap, scoped, singleton, transient };
+export { type MockMap, type ResolutionContext, type Resolver, type ResolverFn, type Scope, createMockMap, createScope, resolveList, resolveMap, scoped, singleton, transient };

package/dist/index.d.ts

@@ -1,50 +1,75 @@
+type PromiseAwarePartial<T> = T extends Promise<infer U> ? Promise<Partial<U>> : Partial<T>;
+type Mock<T> = {
+    isPartial: false;
+    resolver: Resolver<T>;
+} | {
+    isPartial: true;
+    resolver: Resolver<PromiseAwarePartial<T>>;
+};
 /**
- * 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.
+ * Immutable map that registers and provides mocks.
+ * Is passed in a resolution context and used by resolvers
+ * to replace or partially replace themselves with a mock if one is defined.
  */
-type MockMap = Omit<Map<Resolver<any>, Resolver<any>>, "set" | "get"> & {
+type MockMap = {
+    /**
+     * Registers a mock for a resolver,
+     * creating a new `MockMap` with this registration.
+     *
+     * @param original - The original resolver.
+     * @param mock - The mock resolver.
+     */
+    mock<T>(original: Resolver<T>, mock: Resolver<T>): MockMap;
     /**
-     * Sets a mock for a provider.
+     * Registers a partial mock for a resolver,
+     * creating a new `MockMap` with this registration.
+     * In this case, the mock resolver's resolution object will be
+     * merged with the original resolver's resolution object,
+     * overwriting certain fields.
      *
-     * @param provider - The original provider.
-     * @param mock - The mock provider.
+     * @param original - The original resolver.
+     * @param mock - The mock resolver.
      */
-    set<T>(provider: Resolver<T>, mock: Resolver<T>): MockMap;
+    mockPartially<T extends object>(original: Resolver<T>, mock: Resolver<PromiseAwarePartial<T>>): MockMap;
     /**
-     * Retrieves a mock of a provider. Returns undefined if there's none.
+     * Returns a mock of a resolver
+     * or `undefined` if one is not registered.
      *
-     * @param provider - The provider.
+     * @param original - The original resolver.
      */
-    get<T>(provider: Resolver<T>): Resolver<T> | undefined;
+    get<T>(original: Resolver<T>): Mock<T> | undefined;
 };
 /**
- * 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.
+ * Creates a mock map, an immutable map that registers and provides mocks.
+ * Is passed in a resolution context and used by resolvers
+ * to replace or partially replace themselves with a mock if one is defined.
  *
  * @example
  * ```ts
  * const mocks = createMockMap()
- *     .set(getConfig, getTestConfig)
+ *     .mock(getDependency, getDependencyMock)
+ *     .mockPartially(
+ *         getOtherDepedency,
+ *         transient(() => ({ someField: "mock" }))
+ *     )
  *
- * getThing({ mocks })
+ * const entityWithMocks = getEntity({ mocks })
  * ```
  *
- * @returns The map instance.
+ * @returns The mock map.
  */
 declare const createMockMap: () => MockMap;
 
 /**
- * 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.
+ * A `Map` of resolvers to their resolutions.
+ * Is passed in a resolution context and used by scoped resolvers
+ * to retrieve or save resolution within it.
  */
 type Scope = Map<Resolver<any>, any>;
 /**
- * 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.
+ * Creates a `Map` of providers to their instances.
+ * Is passed in a resolution context and used by scoped resolvers
+ * to retrieve or save resolution within it.
  *
  * @example
  * ```ts
@@ -52,97 +77,95 @@ type Scope = Map<Resolver<any>, any>;
  *
  * app.use(() => {
  *     const db = getDb({ scope: requestScope })
- *     // ...
  * })
  * ```
  *
- * @returns The map instance.
+ * @returns The map.
  */
 declare const createScope: () => Scope;
 
 /**
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * A function that takes a resolution context
+ * and returns a value of some type.
  */
-type Resolver<T> = (context?: ResolutionContext) => T;
+type ResolverFn<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.
+ * A function that returns a value of some type
+ * based on a resolution context.
  */
-type Provider<T> = Resolver<T> & {
-    __brand: "provider";
-};
+type Resolver<T> = ResolverFn<T>;
 /**
- * A context used by providers to resolve instances
- * based on current scope and mocks.
+ * A context used by resolvers that defines the behaviour of the resolver
+ * with the passed mocks and scope.
  */
 type ResolutionContext = {
     scope?: Scope;
     mocks?: MockMap;
 };
 /**
- * Creates a transient provider that will resolve a new instance on each call.
+ * Creates a resolver that creates a new resolution on each call.
  *
  * @example
  * ```ts
- * const getThing = transient(() => createThing())
- * getThing() !== getThing()
+ * const getEntity = transient(() => createEntity())
+ * getEntity() !== getEntity()
  * ```
  *
  * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The transient provider.
+ * @returns The transient resolver.
  */
-declare const transient: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const transient: <T>(fn: ResolverFn<T>) => Resolver<T>;
 /**
- * Creates a singleton provider that will resolve an instance once
- * and return it on every call.
+ * Creates a resolver that creates
+ * a resolution once and return it on each call.
  *
  * @example
  * ```ts
- * const getThing = singleton(() => createThing())
- * getThing() === getThing()
+ * const getEntity = singleton(() => createEntity())
+ * getEntity() === getEntity()
  * ```
  *
- * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * @param fn
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The singleton provider.
+ * @returns The singleton resolver.
  */
-declare const singleton: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const singleton: <T>(fn: ResolverFn<T>) => Resolver<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 act as a singleton.
+ * Creates a resolver that takes its resolution
+ * from a scope or create a new one and save it if there is none.
+ * If no scope was passed in a resolution context,
+ * it will act as a singleton.
  *
  * @example
  * ```ts
- * const getThing = scoped(() => createThing())
- * getThing() === getThing()
+ * const getEntity = scoped(() => createEntity())
+ * getEntity() === getEntity()
  * ```
  *
  * @example
  * ```ts
- * const getThing = scoped(() => createThing())
+ * const getEntity = scoped(() => createEntity())
  * const scope = createScope()
- * getThing({ scope }) === getThing({ scope }) !== getThing()
+ * getEntity({ scope }) === getEntity({ scope }) !== getEntity()
  * ```
  *
- * @param resolver
- * A function that returns a value of a particular type
- * with a resolution context being passed to it.
+ * @param fn
+ * A function that takes a resolution context
+ * and returns a value of some type.
  *
- * @returns The scoped provider.
+ * @returns The scoped resolver.
  */
-declare const scoped: <T>(resolver: Resolver<T>) => Provider<T>;
+declare const scoped: <T>(fn: ResolverFn<T>) => Resolver<T>;
 
-type ProviderList = Provider<any>[];
-type ProviderRecord = Record<string, Provider<any>>;
-type InferProviderCollectionResolutions<Providers extends ProviderList | ProviderRecord> = {
-    [K in keyof Providers]: Providers[K] extends Provider<infer T> ? T : never;
+type ResolverList = Resolver<any>[];
+type ResolverRecord = Record<string, Resolver<any>>;
+type InferResolverCollectionResolutions<Resolvers extends ResolverList | ResolverRecord> = {
+    [K in keyof Resolvers]: Resolvers[K] extends Resolver<infer T> ? T : never;
 };
 /**
  * Awaits all promises and wraps the collection in a promise
@@ -153,12 +176,12 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
     [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
+ * Calls every resolver 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
- * Only sync providers:
+ * Only sync resolvers:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(() => createB())
@@ -178,7 +201,7 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
  * ```
  *
  * @example
- * Some provider is async:
+ * Some resolver is async:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(async () => await createB())
@@ -197,20 +220,20 @@ type AwaitValuesInCollection<T extends any[] | Record<any, any>> = Promise<any>
  * ]
  * ```
  *
- * @param providers - The list of providers.
+ * @param resolvers - The list of resolvers.
  * @param context - The resolution context.
  *
  * @returns The list of resolutions.
  */
-declare const resolveList: <const Providers extends ProviderList>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveList: <const Resolvers extends ResolverList>(resolvers: Resolvers, context?: ResolutionContext) => AwaitValuesInCollection<InferResolverCollectionResolutions<Resolvers>>;
 /**
- * Calls every provider in a map with a provided resolution context
+ * Calls every resolver 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
- * Only sync providers:
+ * Only sync resolvers:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(() => createB())
@@ -230,7 +253,7 @@ declare const resolveList: <const Providers extends ProviderList>(providers: Pro
  * ```
  *
  * @example
- * Some provider is async:
+ * Some resolver is async:
  * ```ts
  * const getA = scoped(() => createA())
  * const getB = scoped(async () => await createB())
@@ -249,11 +272,11 @@ declare const resolveList: <const Providers extends ProviderList>(providers: Pro
  * }
  * ```
  *
- * @param providers - The map of providers.
+ * @param resolvers - The map of resolvers.
  * @param context - The resolution context.
  *
  * @returns The map of resolutions.
  */
-declare const resolveMap: <const Providers extends ProviderRecord>(providers: Providers, context?: ResolutionContext) => AwaitValuesInCollection<InferProviderCollectionResolutions<Providers>>;
+declare const resolveMap: <const Resolvers extends ResolverRecord>(resolvers: Resolvers, context?: ResolutionContext) => AwaitValuesInCollection<InferResolverCollectionResolutions<Resolvers>>;
 
-export { type MockMap, type Provider, type ResolutionContext, type Resolver, type Scope, createMockMap, createScope, resolveList, resolveMap, scoped, singleton, transient };
+export { type MockMap, type ResolutionContext, type Resolver, type ResolverFn, type Scope, createMockMap, createScope, resolveList, resolveMap, scoped, singleton, transient };