feat(jest): unit reference overload methods for identifier metadata

AInclude additional methods in the unit reference to utilize identifier metadata.

packages/testbeds/jest/src/index.ts

@@ -1,6 +1,8 @@
 /// <reference types="jest" />
 
 import { Type } from '@automock/types';
+import { IdentifierMetadata } from '@automock/common';
+
 export * from './testbed-factory';
 
 declare module '@automock/core' {
@@ -19,7 +21,8 @@ declare module '@automock/core' {
    */
   export interface UnitReference {
     /**
-     * Retrieves a reference to the mocked object of a dependency corresponding to its type identifier.
+     * Retrieves a reference to the mocked object of a dependency corresponding to its type
+     * identifier.
      *
      * @template TDependency The type of the dependency being retrieved.
      * @param type The type representing the dependency.
@@ -28,35 +31,93 @@ declare module '@automock/core' {
     get<TDependency>(type: Type<TDependency>): jest.Mocked<TDependency>;
 
     /**
-     * Retrieves a reference to the mocked object of a dependency corresponding to a string-based token.
+     * Retrieves a reference to the mocked object of a dependency corresponding to its
+     * type identifier and the identifier metadata.
+     *
+     * @since 2.1.0
+     * @template TDependency The type of the dependency being retrieved.
+     * @param type The type representing the dependency
+     * @param identifierMetadata An accompanying metadata object for the token identifier.
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * type identifier and identifier metadata.
+     */
+    get<TDependency>(
+      type: Type<TDependency>,
+      identifierMetadata: IdentifierMetadata
+    ): jest.Mocked<TDependency>;
+
+    /**
+     * Retrieves a reference to the mocked object of a dependency corresponding to a string-based
+     * token.
      *
      * @template TDependency The type of the dependency being retrieved.
      * @param token The string-based token representing the dependency.
-     * @returns The mocked object corresponding to the provided string-based token.
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * string-based token.
      */
     get<TDependency>(token: string): jest.Mocked<TDependency>;
 
     /**
-     * Retrieves a reference to the mocked object of a dependency corresponding to a symbol-based token.
+     * Retrieves a reference to the mocked object of a dependency corresponding to its
+     * string-based identifier and the identifier metadata.
+     *
+     * @since 2.1.0
+     * @template TDependency The type of the dependency being retrieved.
+     * @param token The string-based token representing the dependency.
+     * @param identifierMetadata An accompanying metadata object for the token identifier.
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * string-based token and identifier metadata.
+     */
+    get<TDependency>(
+      token: string,
+      identifierMetadata: IdentifierMetadata
+    ): jest.Mocked<TDependency>;
+
+    /**
+     * Retrieves a reference to the mocked object of a dependency corresponding to a symbol-based
+     * token.
      *
      * @since 2.0.0
      * @template TDependency The type of the dependency being retrieved.
      * @param token The symbol-based token representing the dependency.
-     * @returns The mocked object corresponding to the provided symbol-based token.
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * symbol-based token.
      */
     get<TDependency>(token: symbol): jest.Mocked<TDependency>;
 
     /**
-     * Retrieves a mocked object or a constant value of a dependency using its type, string, or symbol token.
+     * Retrieves a reference to the mocked object of a dependency corresponding to its
+     * symbol-based identifier and the identifier metadata.
      *
-     * This method provides flexibility in retrieving dependencies by allowing various identifier types.
-     * Depending on the identifier and the setup, it can return either a mocked object or a constant value.
+     * @since 2.1.0
+     * @template TDependency The type of the dependency being retrieved.
+     * @param token The symbol-based token representing the dependency.
+     * @param identifierMetadata An accompanying metadata object for the token identifier.
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * symbol-based token and identifier metadata.
+     */
+    get<TDependency>(
+      token: symbol,
+      identifierMetadata: IdentifierMetadata
+    ): jest.Mocked<TDependency>;
+
+    /**
+     * Retrieves a reference to the mocked object of a dependency corresponding to its
+     * type, string-based or symbol-based identifier and the identifier metadata if present.
      *
-     * @since 2.0.0
+     * This method provides flexibility in retrieving dependencies by allowing various identifier
+     * types.
+     *
+     * @since 2.1.0
      * @template TDependency The type of the dependency being retrieved.
      * @param identifier The type or token that the dependency corresponds to.
-     * @returns The mocked object corresponding to the provided identifier.
+     * @param identifierMetadata
+     * @returns jest.Mocked<TDependency> The mocked object corresponding to the provided
+     * identifier, along with any available identifier metadata.
      */
-    get<TDependency>(identifier: Type<TDependency> | string | symbol): jest.Mocked<TDependency>;
+    get<TDependency>(
+      identifier: Type<TDependency> | string | symbol,
+      identifierMetadata?: IdentifierMetadata
+    ): jest.Mocked<TDependency>;
   }
 }