@remotex-labs/xjet 1.2.1 → 1.2.3

package/dist/shared.d.ts

@@ -3,7 +3,8 @@
  * This file was automatically generated by xBuild.
  * DO NOT EDIT MANUALLY.
  */
- import type { FunctionLikeType, RejectedValueType, ResolvedValueType } from '@remotex-labs/xjet-expect';
+ import type { FunctionType, RejectedValueType, ResolvedValueType } from '@remotex-labs/xjet-expect';
+import type { FunctionLikeType, FunctionType } from '@remotex-labs/xjet-expect';
 import type { ContextType, FunctionType } from '@remotex-labs/xjet-expect';
 import { type ContextType, type FunctionLikeType, type FunctionType } from '@remotex-labs/xjet-expect';
 import type { ContextType } from '@remotex-labs/xjet-expect';
@@ -11,36 +12,62 @@ import type { FunctionLikeType } from '@remotex-labs/xjet-expect';
 import type { FunctionType } from '@remotex-labs/xjet-expect';
 import type { Struct } from '@remotex-labs/xstruct';
 import { Struct } from '@remotex-labs/xstruct';
-import type { ConstructorLikeType, FunctionType } from '@remotex-labs/xjet-expect';
-import type { ConstructorType } from '@remotex-labs/xjet-expect';
-import type { ConstructorLikeType, FunctionLikeType } from '@remotex-labs/xjet-expect';
 
 /**
  * Imports
  */
+import '@components/require.component';
+
+/**
+ * Import will remove at compile time
+ */
 export {};
 
 /**
  * Import will remove at compile time
  */
 /**
- * A class representing the mock state for tracking and managing the behavior of mocked functions or classes.
+ * A powerful mock state manager for simulating functions and classes in tests.
  *
- * @template ReturnType - The type of value returned by the mock function.
- * @template Context - The type representing the context (`this` value) used in the mock function.
- * @template Args - The types of arguments for the mocked function.
+ * @template F - The function signature being mocked, defaults to any function
  *
  * @remarks
- * This class provides mechanisms to customize and manage the behavior of mocked functions or constructors.
- * It tracks invocation details, allows for behavior customization, and enables resetting or restoring the mock to its original state.
+ * MockState provides a complete mocking solution. It tracks
+ * all invocations, including arguments, return values, and contexts, while also allowing
+ * customization of behavior through various methods like `mockImplementation` and
+ * `mockReturnValue`.
+ *
+ * Key features:
+ * - Tracks call arguments, return values, and execution contexts
+ * - Supports one-time implementations and return values
+ * - Manages Promise resolutions and rejections
+ * - Provides methods for resetting or restoring mock state
+ * - Preserves the interface of the original function
  *
- * @since v1.0.0
+ * @example
+ * ```ts
+ * // Create a basic mock
+ * const mockFn = new MockState();
+ *
+ * // Configure return values
+ * mockFn.mockReturnValue('default');
+ * mockFn.mockReturnValueOnce('first call');
+ *
+ * // Use the mock
+ * console.log(mockFn()); // 'first call'
+ * console.log(mockFn()); // 'default'
+ *
+ * // Inspect calls
+ * console.log(mockFn.mock.calls); // [[], []]
+ * ```
+ *
+ * @since 1.0.0
  */
-declare class MockState<ReturnType = unknown, Args extends Array<unknown> = unknown[], Context = unknown> extends Function {
+declare class MockState<F extends FunctionType = FunctionType> extends Function {
     /**
-     * List of all mocks that created
+     * List of all mocks that created as WeakRef
      */
-    static mocks: Array<MockState>;
+    static mocks: Set<WeakRef<MockState>>;
     /**
      * The `name` property represents the name of the mock function.
      */
@@ -50,555 +77,674 @@ declare class MockState<ReturnType = unknown, Args extends Array<unknown> = unkn
      */
     readonly xJetMock: boolean;
     /**
-     * The `state` property holds the detailed state of the mock invocations.
-     * It tracks information such as the arguments passed, the results returned, the context (`this` value) used,
-     * the instances created, and the order of invocations.
-     * This data is automatically updated after each call to the mock.
+     * Holds the current state of the mock, including all invocation records.
      *
-     * @template ReturnType - The type of value returned by the mock function.
-     * @template Context - The type representing the context (`this` value) used in the mock function.
-     * @template Args - The types of arguments for the mocked function.
+     * @remarks
+     * This property tracks the complete history of the mock's usage, storing
+     * information like call arguments, return values, execution contexts,
+     * instances, and the order of invocations.
      *
-     * @see MocksStateInterface
+     * It's initialized with empty arrays for tracking and gets updated with
+     * each invocation. This state is what powers the inspection capabilities
+     * accessible via the public `mock` getter.
      *
-     * @since v1.0.0
+     * @since 1.0.0
      */
     private state;
     /**
-     * A private function that restores the mock's original implementation.
+     * Stores one-time implementations to be used on successive invocations.
      *
      * @remarks
-     * The `restore` function is responsible for resetting the mock to its initial state.
-     * It works in conjunction with methods like `mockReset` and `mockRestore` to ensure
-     * proper restoration of the mock's behavior.
+     * This queue contains functions that will be consumed in FIFO order
+     * (first-in, first-out) when the mock is called. Each implementation
+     * is used exactly once and then removed from the queue.
      *
-     * Responsibilities:
-     * - Returning the original implementation when restoring the mock
-     * - Ensuring consistent reset behavior across mock operations
-     * - Supporting the {@link mockRestore} method's functionality
-     * - Maintaining mock state integrity during restoration
+     * When adding implementations with `mockImplementationOnce()` or similar
+     * methods, they are pushed to this queue. On invocation, the mock will
+     * check this queue first, using and removing the oldest implementation
+     * if available, or falling back to the default implementation.
      *
-     * @see MockState.mockRestore
-     * @see MockState.originalImplementation
-     *
-     * @since 1.2.0
+     * @since 1.0.0
      */
-    private readonly restore?;
+    private queuedImplementations;
     /**
-     * A private array that stores the implementations queued to be executed
-     * for future invocations of the mock.
-     * Each function in this array is invoked in sequence when the mock function is called,
-     * with the first queued implementation being used on the first call, the second on the second call, and so on.
+     * The current default implementation for this mock.
      *
-     * This property is used in conjunction with methods like `mockImplementationOnce`
-     * to specify different behaviors for consecutive calls to the mock.
+     * @remarks
+     * This property holds the function that will be executed when the mock is called,
+     * unless overridden by a queued one-time implementation. It can be set using
+     * the `mockImplementation()` method and retrieved with `getMockImplementation()`.
      *
-     * @since v1.0.0
-     */
-    private queuedImplementations;
-    /**
-     * A private property that holds the current implementation of the mock function.
-     * This function is executed whenever the mock is invoked and can be changed
-     * using methods like `mockImplementation` or `mockImplementationOnce`.
+     * If not explicitly set, it defaults to `undefined`, meaning the mock will
+     * return `undefined` when called (after any queued implementations are used).
      *
-     * The `implementation` allows for customizing the behavior of the mock,
-     * such as returning specific values, throwing errors, or performing actions.
+     * This implementation determines the behavior of the mock for all calls that
+     * don't have a specific one-time implementation in the queue.
      *
-     * @since v1.0.0
+     * @since 1.0.0
      */
     private implementation;
     /**
-     * A private property that holds the original implementation of the mock function.
-     * This is the initial function passed to the constructor that defines the mock's default behavior
-     * before any customization.
-     *
-     * @template ReturnType - The type of value returned by the original function.
-     * @template Args - The types of arguments for the original function.
-     * @template Context - The type representing the context (`this` value) used in the original function.
+     * Preserves the original implementation provided when creating the mock.
      *
      * @remarks
-     * This property stores the initial implementation provided when creating the mock.
-     * If no implementation is provided during construction, it defaults to a function
-     * that returns `undefined` cast to the appropriate return type.
-     * Unlike `implementation` which can be modified, this property maintains a reference
-     * to the original function for scenarios where the original behavior needs to be preserved
-     * or restored.
+     * This property stores the initial function passed to the constructor, allowing
+     * the mock to be restored to its original behavior later using `mockRestore()`.
      *
-     * @see FunctionLikeType
-     * @see MockState.original
+     * If no implementation was provided in the constructor, this will contain a
+     * function that returns `undefined` when called.
+     *
+     * The original implementation is immutable and serves as a reference point
+     * for resetting the mock to its initial state.
      *
      * @since 1.0.0
      */
     private readonly originalImplementation;
     /**
-     * Constructs a mock object that allows custom implementation, restore capability,
-     * and optional naming functionality. This mock is proxied to handle function invocation
-     * and class instantiation.
+     * Optional cleanup function to be called when the mock is restored.
+     *
+     * @remarks
+     * If provided, this function will be executed when `mockRestore()` is called,
+     * allowing for custom cleanup operations. This is particularly useful when
+     * creating mocks that replace methods or properties on existing objects.
      *
-     * @template ReturnType - The type of the value returned by the mock function.
-     * @template Context - The type of the context (`this`) for the mock function.
-     * @template Args - The type of arguments accepted by the mock function.
+     * The restore function should handle any necessary teardown, such as
+     * restoring original object properties, removing event listeners, or
+     * closing connections that were established during mock creation.
+     *
+     * @since 1.0.0
+     */
+    private readonly restore?;
+    /**
+     * Creates a new instance of a mock function.
      *
-     * @param implementation - Optional implementation for the mock function.
-     * @param restore - Optional function to restore the mock to its initial state. Defaults to resetting to the provided implementation.
-     * @param name - Optional name for the mock instance. Default to a predefined mock name if not provided.
+     * @template F - The function type being mocked. This generic type parameter allows
+     *               the mock to properly type-check parameters and return values to match
+     *               the function signature being mocked.
      *
-     * @returns A proxied mock object capable of behaving as a callable function or a constructible class.
+     * @param implementation - The initial function implementation to use. If not provided,
+     *                         the mock will return `undefined` when called.
+     * @param restore - Optional cleanup function that will be called when `mockRestore()` is invoked.
+     *                  Useful for restoring original behavior when mocking existing object methods.
+     * @param name - Optional name for the mock function, used in error messages and test output.
+     *               Defaults to "xJet.fn()" if not provided.
      *
      * @remarks
-     * The mock object can work as both a function and a class, using JavaScript's Proxy API. The restore functionality
-     * allows resetting to the original state or implementation. If no implementation is provided, the mock remains uninitialized
-     * but still functional.
+     * The constructor initializes the mock's state, implementation, and metadata.
+     * It returns a Proxy that allows the mock to be both a function and an object with properties.
+     *
+     * The Proxy intercepts:
+     * - Function calls (via `apply`)
+     * - Property access (via `get`)
+     * - Constructor calls with `new` (via `construct`)
+     *
+     * This enables the mock to track calls, return configured values, and provide
+     * helper methods for assertions and configuration.
      *
-     * @see FunctionLikeType
-     * @see VoidFunctionType
+     * @see ReturnType
+     * @see ImplementationType
      *
      * @since 1.0.0
      */
-    constructor(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: () => FunctionLikeType<ReturnType, Args, Context> | void, name?: string);
+    constructor(implementation?: F, restore?: () => F | void, name?: string);
     /**
-     * todo remove it
-     * only for jest expect will support this mock
-     */
-    getMockName(): string;
-    /**
-     * Retrieves the current state of the mock function.
+     * Gets a readonly snapshot of the current mocks state.
      *
-     * @remarks
-     * The `mock` getter provides read-only access to the complete state tracking information
-     * for the mock function. This includes all recorded invocations, return values, contexts,
-     * and other mock-related tracking data.
+     * @template F - The function type being mocked.
      *
-     * Responsibilities:
-     * - Providing access to recorded function calls via {@link MocksStateInterface.calls}
-     * - Tracking invocation results through {@link MocksStateInterface.results}
-     * - Maintaining context information in {@link MocksStateInterface.contexts}
-     * - Recording instance creation in {@link MocksStateInterface.instances}
-     * - Preserving invocation order via {@link MocksStateInterface.invocationCallOrder}
+     * @returns A frozen (immutable) copy of the mock state {@link MocksStateInterface}, containing information
+     *          about calls, return values, and other tracking data.
      *
-     * @returns A read-only view of the mock state tracking object.
+     * @remarks
+     * This property provides safe access to the mock's internal state for assertions and
+     * debugging purposes. The returned object is a deep copy with all properties frozen
+     * to prevent accidental modification of the mock's internal state.
      *
      * @see MocksStateInterface
+     *
      * @since 1.0.0
      */
-    get mock(): Readonly<MocksStateInterface<ReturnType, Args, Context>>;
+    get mock(): Readonly<MocksStateInterface<F>>;
     /**
-     * Returns the original implementation of the function that was instrumented
+     * Gets the original function implementation.
      *
-     * @returns The original function implementation that was wrapped or modified
+     * @template F - The function type being mocked.
+     *
+     * @returns The original function implementation that was provided when creating the mock
+     *          or a default implementation that returns undefined if none was provided.
      *
      * @remarks
-     * This getter provides access to the unmodified function that was originally passed
-     * to the instrumentation system. Useful for debugging, testing, or when you need
-     * to bypass the instrumented behavior temporarily.
+     * This property allows access to the original implementation that was stored
+     * when the mock was created. It's useful when you need to temporarily access
+     * or call the original behavior within test cases.
      *
      * @example
      * ```ts
-     * const mockFn = jest.fn(x => x * 2);
-     * // Later in test
-     * const originalImplementation = mockFn.original;
-     * expect(originalImplementation(5)).toBe(10);
-     * ```
+     * // Create a mock with an original implementation
+     * const originalFn = (x: number) => x * 2;
+     * const mockFn = xJet.fn(originalFn);
      *
-     * @see FunctionLikeType
+     * // Override the implementation for some tests
+     * mockFn.mockImplementation((x: number) => x * 3);
+     *
+     * // Call the original implementation directly when needed
+     * const result = mockFn.original(5); // Returns 10, not 15
+     * ```
      *
      * @since 1.0.0
      */
-    get original(): FunctionLikeType<ReturnType, Args, Context>;
+    get original(): F;
     /**
-     * Clears the `mock.calls`, `mock.results`, `mock.contexts`, `mock.instances`, and `mock.invocationCallOrder` properties.
+     * Clears all information stored in the mock's state {@link MocksStateInterface}.
      *
-     * @returns The current instance of the mock, allowing for method chaining.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method resets the state of the mock function, clearing all invocation data and results,
-     * ensuring that previous mock states do not affect the following tests.
-     * Equivalent to calling `.mockClear()` on every mocked function.
+     * This method resets all stored information such as tracked calls, return values,
+     * and other state information. It doesn't reset any custom implementations that
+     * were set using mockImplementation or similar methods.
+     *
+     * @example
+     * ```ts
+     * const mockFn = xJet.fn();
+     * mockFn('first call');
+     * mockFn('second call');
+     *
+     * expect(mockFn.mock.calls.length).toBe(2);
      *
-     * @see MockState.initState
+     * mockFn.mockClear();
+     *
+     * // All calls information has been cleared
+     * expect(mockFn.mock.calls.length).toBe(0);
+     * ```
      *
-     * @since v1.0.0
+     * @since 1.0.0
      */
     mockClear(): this;
     /**
-     * Resets the mock function to its initial state.
+     * Resets the mock by clearing all state and removing all queued implementations.
      *
-     * @returns The current instance of the mock, allowing for method chaining.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * The `mockReset` method clears all invocation data and results by calling `mockClear()` and also resets
-     * the queued implementations,
-     * removing any previously queued behavior set by methods like `mockImplementationOnce`.
-     * This ensures that the mock is in a clean state and ready for new invocations or configurations.
+     * This method performs a more complete reset than mockClear() {@link mockClear}.
+     * It clears all stored information about calls and additionally removes any queued implementations that were
+     * set using mockImplementationOnce(). The default implementation will be restored.
+     *
+     * @example
+     * ```ts
+     * const mockFn = xJet.fn(() => 'default');
+     * mockFn.mockImplementationOnce(() => 'first call');
+     * mockFn.mockImplementationOnce(() => 'second call');
      *
-     * @see MockState.mockClear
+     * console.log(mockFn()); // 'first call'
      *
-     * @since v1.0.0
+     * mockFn.mockReset();
+     *
+     * // All calls have been cleared, and queued implementations removed
+     * console.log(mockFn()); // 'default'
+     * ```
+     *
+     * @see mockClear
+     * @since 1.0.0
      */
     mockReset(): this;
     /**
-     * Restores the mock function to its original implementation and resets its state.
+     * Restores the original implementation of the mocked function.
      *
-     * @returns The current instance of the mock, allowing for method chaining.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * The `mockRestore` method does two things:
-     * 1. It restores the mock to its initial implementation, which was set during the mocks creation or
-     *    via the `mockImplementation` method.
-     * 2. It clears all tracking data, such as calls, results, contexts, instances, and invocation call order
-     *    by calling `mockReset()`, ensuring the mock is fully reset and ready for new invocations.
+     * This method performs the most complete reset operation. It first calls mockReset() {@link mockReset}
+     * to clear all state and queued implementations, then restores the original implementation
+     *  provided when the mock was created. If a custom restore function was provided,
+     * it will be used instead to determine the implementation to restore.
+     *
+     * @example
+     * ```ts
+     * // Create a mock with an original implementation
+     * const originalFn = (x: number) => x * 2;
+     * const mockFn = xJet.fn(originalFn);
+     *
+     * // Override the implementation
+     * mockFn.mockImplementation((x: number) => x * 3);
+     *
+     * console.log(mockFn(5)); // 15
+     *
+     * // Restore the original implementation
+     * mockFn.mockRestore();
      *
-     * This method is useful for ensuring that the mock is completely restored and cleared, making it behave as it did
-     * when it was first created or last restored.
+     * console.log(mockFn(5)); // 10
+     * ```
      *
-     * @see MockState.restore
-     * @see MockState.mockReset
+     * @see mockClear
+     * @see mockReset
      *
-     * @since v1.0.0
+     * @since 1.0.0
      */
     mockRestore(): this;
     /**
-     * Retrieves the mock implementation for a function, if available.
-     *
-     * @template ReturnType The type the return value of the function.
-     * @template Context The type of the `this` context for the function.
-     * @template Args The type the argument(s) of the function.
+     * Returns the current implementation of the mock function.
      *
-     * @return A function matching `FunctionLikeType` that represents the mock implementation,
-     * or `undefined` if no implementation is set.
+     * @returns The current mock implementation, or undefined if no implementation exists.
      *
      * @remarks
-     * This method returns the mock implementation associated with the instance.
-     * If no mock implementation exists, it returns `undefined`.
+     * This method returns the current implementation function used by the mock.
+     * This could be the default implementation, a custom implementation set via
+     * mockImplementation() {@link mockImplementation}, or the original implementation
+     * if mockRestore() {@link mockRestore} was called.
+     *
+     * @example
+     * ```ts
+     * const mockFn = xJet.fn(() => 'default');
+     *
+     * // Get the default implementation
+     * const impl = mockFn.getMockImplementation();
+     * console.log(impl()); // 'default'
+     *
+     * // Change the implementation
+     * mockFn.mockImplementation(() => 'new implementation');
+     *
+     * // Get the new implementation
+     * const newImpl = mockFn.getMockImplementation();
+     * console.log(newImpl()); // 'new implementation'
+     * ```
      *
      * @since 1.0.0
      */
-    getMockImplementation(): FunctionLikeType<ReturnType, Args, Context> | undefined;
+    getMockImplementation(): ImplementationType<F> | undefined;
     /**
-     * Retrieves the next implementation from the queued implementations or defaults to the current implementation.
+     * Returns the next implementation to be used when the mock is called.
      *
-     * @template ReturnType The return type of the function-like implementation.
-     * @template Context     The context in which the implementation executes.
-     * @template Args        The argument types expected by the implementation.
-     *
-     * @return The next implementation from the queue if available, or the current implementation.
-     * Returns are `undefined` if no implementation is found.
+     * @returns The next implementation from the queue, or the default implementation if the queue is empty.
      *
      * @remarks
-     * This method first checks if there are any queued implementations available.
-     * If a queued implementation exists, it will be removed from the queue and returned.
-     * If the queue is empty, the primary current implementation is returned.
-     * Returns are `undefined` if there is no implementation available.
+     * This method retrieves and removes the next implementation from the queue of implementations
+     * added via mockImplementationOnce() {@link mockImplementationOnce}. If the queue is empty,
+     * it returns the default implementation set via mockImplementation() {@link mockImplementation}
+     * or the original function.
+     *
+     * @example
+     * ```ts
+     * const mockFn = xJet.fn(() => 'default');
+     * mockFn.mockImplementationOnce(() => 'first call');
+     * mockFn.mockImplementationOnce(() => 'second call');
+     *
+     * const firstImpl = mockFn.getNextImplementation();
+     * console.log(firstImpl()); // 'first call'
+     *
+     * const secondImpl = mockFn.getNextImplementation();
+     * console.log(secondImpl()); // 'second call'
+     *
+     * const defaultImpl = mockFn.getNextImplementation();
+     * console.log(defaultImpl()); // 'default'
+     * ```
      *
      * @since 1.0.0
      */
-    getNextImplementation(): FunctionLikeType<ReturnType, Args, Context> | undefined;
+    getNextImplementation(): ImplementationType<F> | undefined;
     /**
-     * Replaces the default implementation of a mock function with the provided function.
+     * Sets a new implementation for this mock function.
+     *
+     * @param fn - The function to be used as the mock implementation.
+     * @returns The mock instance for method chaining.
      *
-     * @template ReturnType - The type of the value returned by the implementation function.
-     * @template Context - The context (`this`) expected by the implementation function.
-     * @template Args - The types of the arguments expected by the implementation function.
+     * @remarks
+     * This method sets a persistent implementation that will be used whenever the mock function is called,
+     * unless there are queued implementations from mockImplementationOnce() {@link mockImplementationOnce}.
+     * The implementation remains until it is replaced by another call to mockImplementation() or restored
+     * via mockRestore() {@link mockRestore}.
      *
-     * @param fn - The function to be used as the mock implementation. It defines
-     * the behavior of the mock when called.
+     * @example
+     * ```ts
+     * const mockFn = xJet.fn();
      *
-     * @return Returns the instance of the current object for method chaining.
+     * mockFn.mockImplementation((x: number) => x * 2);
      *
-     * @remarks
-     * This method is useful when you need to mock the behavior of a function
-     * dynamically during tests or in controlled scenarios.
+     * console.log(mockFn(5)); // 10
+     * console.log(mockFn(10)); // 20
+     *
+     * // Change the implementation
+     * mockFn.mockImplementation((x: number) => x * 3);
+     *
+     * console.log(mockFn(5)); // 15
+     * ```
+     *
+     * @see mockRestore
+     * @see mockImplementationOnce
      *
      * @since 1.0.0
      */
-    mockImplementation(fn: FunctionLikeType<ReturnType, Args, Context>): this;
+    mockImplementation(fn: ImplementationType<F>): this;
     /**
-     * Sets a mock implementation that will be used once for the next call to the mocked function.
+     * Adds a one-time implementation for this mock function.
      *
-     * @template ReturnType The type of the value that the mock function will return.
-     * @template Context The type of the `this` context for the mock function.
-     * @template Args The type of arguments that the mock function will receive.
-     *
-     * @param fn - The function to be used as the mock implementation for the next call.
-     * @returns The current instance, allowing for chaining of mock configurations.
+     * @param fn - The function to be used as the mock implementation for a single call.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * The provided mock implementation will only be executed once. Further calls will fall back
-     * to a different implementation, if provided, or the default behavior of the mock function.
+     * This method queues an implementation that will be used for a single call to the mock function.
+     * After being used once, it will be removed from the queue. Multiple implementations can be queued,
+     * and they will be used in the order they were added. Once all queued implementations are used,
+     * the mock will revert to using the implementation set by mockImplementation() {@link mockImplementation}.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState();
-     *
-     * // Set default implementation
-     * mockFn.mockImplementation(() => 'default');
+     * const mockFn = xJet.fn(() => 'default');
      *
-     * // Set one-time behavior for the next call
-     * mockFn.mockImplementationOnce(() => 'first call');
+     * mockFn.mockImplementationOnce(() => 'first call')
+     *       .mockImplementationOnce(() => 'second call');
      *
-     * console.log(mockFn()); // Output: 'first call' (from mockImplementationOnce)
-     * console.log(mockFn()); // Output: 'default' (from mockImplementation)
+     * console.log(mockFn()); // 'first call'
+     * console.log(mockFn()); // 'second call'
+     * console.log(mockFn()); // 'default'
      * ```
      *
-     * @see FunctionLikeType
+     * @see mockReset
+     * @see mockImplementation
      *
      * @since 1.0.0
      */
-    mockImplementationOnce(fn: FunctionLikeType<ReturnType, Args, Context>): this;
+    mockImplementationOnce(fn: ImplementationType<F>): this;
     /**
-     * Sets a mock implementation to always return a specified value when invoked.
-     *
-     * @template ReturnType The type of the value returned by the mock implementation.
+     * Sets a fixed return value for this mock function.
      *
-     * @param value - The value to always return when the mock function is called.
-     * @return The current instance for chaining.
+     * @param value - The value to be returned when the mock function is called.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method overrides any previous mock implementation configured for the function.
+     * This method is a convenience wrapper around mockImplementation() {@link mockImplementation}
+     * that creates an implementation which always returns the same value. It replaces any existing
+     * implementation with a function that simply returns the specified value.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState();
+     * const mockFn = xJet.fn();
+     *
+     * mockFn.mockReturnValue(42);
      *
-     * // Set mock to return 'Hello World' on each call
-     * mockFn.mockReturnValue('Hello World');
+     * console.log(mockFn()); // 42
+     * console.log(mockFn('anything')); // 42
+     * console.log(mockFn({}, [])); // 42
      *
-     * console.log(mockFn()); // Output: 'Hello World'
-     * console.log(mockFn()); // Output: 'Hello World'
+     * // Can be changed
+     * mockFn.mockReturnValue('new value');
+     * console.log(mockFn()); // 'new value'
      * ```
      *
+     * @see mockImplementation
+     * @see mockReturnValueOnce
+     *
      * @since 1.0.0
      */
-    mockReturnValue(value: ReturnType): this;
+    mockReturnValue(value: ReturnType<F>): this;
     /**
-     * Sets up a mock function to always resolve a promise with the specified value when called.
-     *
-     * @template ResolvedValueType - The type of the value to be resolved by the promise.
-     * @template ReturnType - The return type of the function, which should include a Promise of the specified resolved value type.
+     * Adds a one-time fixed return value for this mock function.
      *
-     * @param value - The value to be returned as the resolved value of the promise.
-     * @returns The mock function instance, enabling method chaining.
+     * @param value - The value to be returned for a single call to the mock function.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method is particularly useful for mocking asynchronous functions that return promises.
-     * It ensures that the mock function resolves with the provided value every time it is called.
+     * This method is a convenience wrapper around mockImplementationOnce() {@link mockImplementationOnce}
+     * that creates a one-time implementation which returns the specified value. Multiple return values
+     * can be queued, and they will be used in the order they were added. After all queued values are
+     * consumed, the mock will revert to its default implementation.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState<Promise<string>>();
+     * const mockFn = xJet.fn(() => 'default');
      *
-     * // Set mock to return a resolved promise with the value 'Success'
-     * mockFn.mockResolvedValue('Success');
+     * mockFn.mockReturnValueOnce(42)
+     *       .mockReturnValueOnce('string value')
+     *       .mockReturnValueOnce({ object: true });
      *
-     * mockFn().then((result: string) => {
-     *     console.log(result); // Output: 'Success'
-     * });
+     * console.log(mockFn()); // 42
+     * console.log(mockFn()); // 'string value'
+     * console.log(mockFn()); // { object: true }
+     * console.log(mockFn()); // 'default'
      * ```
      *
+     * @see mockReturnValue
+     * @see mockImplementationOnce
+     *
      * @since 1.0.0
      */
-    mockResolvedValue(value: ResolvedValueType<ReturnType>): this;
+    mockReturnValueOnce(value: ReturnType<F>): this;
     /**
-     * Sets a mock implementation for a single call that resolves to the specified value.
-     *
-     * @template ReturnType The type of the resolved value.
-     * @template ResolvedValueType The type of the input value to be resolved.
+     * Sets a resolved Promise return value for this mock function.
      *
-     * @param value - The value that the promise should resolve with when the mock is called once.
-     * @return The current mock object instance, enabling method chaining.
+     * @param value - The value that the Promise will resolve to.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method is useful for defining custom behavior for a specific invocation of a mocked function,
-     * returning a resolved promise with the provided value.
+     * This method is a convenience wrapper that creates an implementation which returns a
+     * Promise that resolves to the specified value. It's particularly useful for testing
+     * async functions that should return resolved Promises.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState(async () => {
-     *     return 'end';
-     * });
+     * const mockFn = xJet.fn();
      *
-     * // Set mock to return a resolved promise with the value 'Success'
-     * mockFn.mockResolvedValueOnce('Success');
+     * mockFn.mockResolvedValue('resolved value');
      *
-     * mockFn().then((result: string) => {
-     *     console.log(result); // Output: 'Success'
+     * // The mock now returns a Promise that resolves to 'resolved value'
+     * mockFn().then(result => {
+     *   console.log(result); // 'resolved value'
      * });
      *
-     * mockFn().then((result: string) => {
-     *     console.log(result); // Output: 'end'
-     * });
+     * // Can also be used with async/await
+     * const result = await mockFn();
+     * console.log(result); // 'resolved value'
      * ```
      *
+     * @see mockRejectedValue
+     * @see mockImplementation
+     * @see mockResolvedValueOnce
+     *
      * @since 1.0.0
      */
-    mockResolvedValueOnce(value: ResolvedValueType<ReturnType>): this;
+    mockResolvedValue(value: ResolvedValueType<ReturnType<F>>): this;
     /**
-     * Sets the return value of the mock function for a single call.
-     *
-     * @template ReturnType The type of the value to be returned.
+     * Adds a one-time resolved Promise return value for this mock function.
      *
-     * @param value - The value to be returned by the mock function for the next call.
-     * @return The mock function instance, allowing for method chaining.
+     * @param value - The value that the Promise will resolve to for a single call.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method only affects the return value for the next call to the mock function.
-     * All further calls will use the usual mock implementation or other specified behaviors.
+     * This method is a convenience wrapper that creates a one-time implementation which returns
+     * a Promise that resolves to the specified value. Multiple resolved values can be queued and
+     * will be used in the order they were added. After all queued values are consumed, the mock
+     * will revert to its default implementation.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState();
-     *
-     * // Set default return value
-     * mockFn.mockReturnValue('Default Value');
+     * const mockFn = xJet.fn(() => Promise.resolve('default'));
      *
-     * // Set a one-time return value for the next call
-     * mockFn.mockReturnValueOnce('First Call');
-     * mockFn.mockReturnValueOnce('Second Call');
+     * mockFn.mockResolvedValueOnce('first call')
+     *       .mockResolvedValueOnce('second call')
+     *       .mockResolvedValueOnce('third call');
      *
-     * console.log(mockFn()); // Output: 'First Call' (from mockReturnValueOnce)
-     * console.log(mockFn()); // Output: 'Second Call' (from mockReturnValueOnce)
-     * console.log(mockFn()); // Output: 'Default Value' (from mockReturnValue)
+     * // Each call returns a different Promise
+     * await expect(mockFn()).resolves.toEqual('first call');
+     * await expect(mockFn()).resolves.toEqual('second call');
+     * await expect(mockFn()).resolves.toEqual('third call');
+     * await expect(mockFn()).resolves.toEqual('default');
      * ```
      *
+     * @see mockResolvedValue
+     * @see mockRejectedValueOnce
+     * @see mockImplementationOnce
+     *
      * @since 1.0.0
      */
-    mockReturnValueOnce(value: ReturnType): this;
+    mockResolvedValueOnce(value: ResolvedValueType<ReturnType<F>>): this;
     /**
-     * Mocks the method to always return a rejected Promise with the specified value.
-     *
-     * @template ReturnType - The expected type of the return value for the mocked method.
-     * @template RejectedValueType - The type of the value used to reject the Promise.
+     * Sets a rejected Promise return value for this mock function.
      *
-     * @param value - The value with which the mocked Promise will be rejected.
-     *
-     * @return The current instance of the mock for chaining purposes.
+     * @param value - The error that the Promise will reject with.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method is useful for testing scenarios where the function being mocked
-     * is expected to reject with a specific value.
+     * This method is a convenience wrapper that creates an implementation which returns a
+     * Promise that rejects with the specified value. It's particularly useful for testing
+     * error handling in async functions.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState<Promise<string>>();
+     * const mockFn = xJet.fn();
      *
-     * // Set mock to return a rejected promise with the value 'Error'
-     * mockFn.mockRejectedValue('Error');
+     * mockFn.mockRejectedValue(new Error('Something went wrong'));
      *
+     * // The mock now returns a Promise that rejects with the error
      * mockFn().catch(error => {
-     *     console.log(error); // Output: 'Error'
+     *   console.error(error.message); // 'Something went wrong'
      * });
+     *
+     * // Can also be used with async/await and try/catch
+     * try {
+     *   await mockFn();
+     * } catch (error) {
+     *   console.error(error.message); // 'Something went wrong'
+     * }
      * ```
      *
+     * @see mockResolvedValue
+     * @see mockImplementation
+     * @see mockRejectedValueOnce
+     *
      * @since 1.0.0
      */
-    mockRejectedValue(value: RejectedValueType<ReturnType>): this;
+    mockRejectedValue(value: RejectedValueType<ReturnType<F>>): this;
     /**
-     * Adds a one-time rejection with the provided value to the mock function.
+     * Adds a one-time rejected Promise return value for this mock function.
      *
-     * @template ReturnType - The type of the value the mock function would return.
-     *
-     * @param value - The value to reject the promise with in the mock function.
-     * @return The current instance of the mock function, allowing for method chaining.
+     * @param value - The error that the Promise will reject with for a single call.
+     * @returns The mock instance for method chaining.
      *
      * @remarks
-     * This method configures a mock function to return a rejected promise with the
-     * specified value the next time it is called. After the rejection occurs, the
-     * mock function's behavior will revert to the next defined mock behavior, or
-     * to the default behavior if no behaviors are defined.
+     * This method is a convenience wrapper that creates a one-time implementation which returns
+     * a Promise that rejects with the specified value. Multiple rejected values can be queued and
+     * will be used in the order they were added. After all queued values are consumed, the mock
+     * will revert to its default implementation.
      *
      * @example
      * ```ts
-     * const mockFn = new MockState<Promise<string>>();
+     * const mockFn = xJet.fn(() => Promise.resolve('success'));
      *
-     * // Set default rejected value
-     * mockFn.mockRejectedValue('Default Error');
+     * mockFn.mockRejectedValueOnce(new Error('first error'))
+     *       .mockRejectedValueOnce(new Error('second error'));
      *
-     * // Set a one-time rejected value for the next call
-     * mockFn.mockRejectedValueOnce('First Call Error');
+     * // First call rejects with 'first error'
+     * await expect(mockFn()).rejects.toThrow('first error');
      *
-     * mockFn().catch(error => {
-     *     console.log(error); // Output: 'First Call Error' (from mockRejectedValueOnce)
-     * });
+     * // Second call rejects with 'second error'
+     * await expect(mockFn()).rejects.toThrow('second error');
      *
-     * mockFn().catch(error => {
-     *     console.log(error); // Output: 'Default Error' (from mockRejectedValue)
-     * });
+     * // Third call uses the default implementation and resolves
+     * await expect(mockFn()).resolves.toEqual('success');
      * ```
      *
+     * @see mockRejectedValue
+     * @see mockResolvedValueOnce
+     * @see mockImplementationOnce
+     *
      * @since 1.0.0
      */
-    mockRejectedValueOnce(value: RejectedValueType<ReturnType>): this;
+    mockRejectedValueOnce(value: RejectedValueType<ReturnType<F>>): this;
     /**
-     * Initializes and returns the state object for mock function tracking.
+     * Initializes the internal state object for the mock function.
      *
-     * @return An object containing the initialized mock function state.
+     * @returns A new mock state object with default empty values.
      *
      * @remarks
-     * The state object contains the structure necessary to keep track of
-     * calls, results, contexts, instances, and invocation orders of the function.
+     * This private method creates and returns a fresh state object used to track
+     * mock function invocations. The state includes:
+     * - calls: Arguments passed to the mock function
+     * - results: Return values or errors from each call
+     * - lastCall: Arguments from the most recent call
+     * - contexts: 'this' context values for each call
+     * - instances: Objects created when the mock is used as a constructor
+     * - invocationCallOrder: Tracking the sequence of calls across multiple mocks
      *
-     * @see MocksStateInterface
+     * This method is used internally when creating a new mock or when resetting
+     * an existing mocks state.
      *
-     * @since v1.0.0
+     * @since 1.0.0
      */
     private initState;
     /**
-     * Invokes the next implementation of a mock function with the provided context and arguments.
-     *
-     * @template Context The type of `this` context in which the function is invoked.
-     * @template Args The type of the arguments passed to the function.
-     * @template ReturnType The type of the return value, of the function being invoked.
-     *
-     * @param thisArg - The context (`this`) in which the function is executed.
-     * @param args - The arguments to be passed to the function.
+     * Invokes the mock function with the provided arguments and context.
      *
-     * @returns The result of the function invocation, which is either the return value, the thrown error, or undefined.
+     * @param thisArg - The 'this' context for the function call
+     * @param args - The arguments to pass to the function
+     * @returns The result of the mock implementation or undefined
      *
      * @remarks
-     * This method simulates the function call for a mocked implementation. It tracks all invocations,
-     * including the call order, the provided arguments, and the context. It handles binding, default
-     * arguments, and maintains a record of results (either successful returns or thrown errors).
+     * This private method handles the actual invocation of the mock function and manages all
+     * state trackings.
+     *
+     * This method is central to the mock's functionality, enabling call tracking,
+     * result recording, and the execution of custom implementations.
      *
      * @since 1.0.0
      */
     private invoke;
     /**
-     * Invokes a function within a specific context and with provided arguments.
-     *
-     * @template Context The type of the context in which the function is invoked.
-     * @template Args The type of the arguments passed to the function.
-     * @template ReturnType The type of the value that the invoked function returns.
+     * Handles property access for the mock function proxy.
      *
-     * @param target - The instance of the class containing the method to be invoked.
-     * @param thisArg - The context object that will be bound to the invoked function.
-     * @param argumentsList - The list of arguments to pass to the invoked function.
-     * @returns The result of the invoked function or `undefined` if no value is returned.
+     * @param target - The mock function instance
+     * @param property - The property name or symbol being accessed
+     * @returns The property value from either the mock or the original implementation
      *
      * @remarks
-     * This method modifies the state of the `target` instance by adding the `thisArg`
-     * to the `target.state.instances` array before invoking the function.
+     * This private method is used as the 'get' trap for the Proxy surrounding the mock function.
+     * It provides property access fallback behavior - first checking if the property exists
+     * on the mock itself, and if not, retrieving it from the original implementation.
+     *
+     * This enables the mock to maintain its own properties while still allowing access to
+     * properties from the original function, providing a more transparent mocking experience.
      *
      * @since 1.0.0
      */
-    private invokeFunction;
+    private invokeGet;
     /**
-     * Invokes a class method on the provided target with specified arguments and a new target.
-     *
-     * @template Args - The type of arguments to be passed to the invoked method.
+     * Handles constructor invocation when the mock is used with 'new'.
      *
-     * @param target - The object on which the class method is invoked.
-     * @param argArray - The array of arguments to pass to the invoked method.
-     * @param newTarget - The new object used as the invocation context.
-     * @returns The result of the invocation, typically an object. If the result is not an object,
-     *          the `newTarget` is returned instead.
+     * @param target - The mock function instance
+     * @param argArray - The arguments passed to the constructor
+     * @param newTarget - The constructor that was directly invoked
+     * @returns The constructed instance
      *
      * @remarks
-     * This method ensures that the result is stored in the `instances` array of the target's state
-     * if it is detected as a proper class instance. Otherwise, the `newTarget` is registered.
+     * This method is used as the 'construct' trap for the Proxy surrounding the mock function.
+     * It delegates to the `invoke` method to handle the actual function call, then tracks the
+     * resulting instance in the mock's state for later verification.
+     *
+     * The method handles both cases where the constructor returns an object (which becomes the
+     * instance) and where it doesn't (in which case the newTarget becomes the instance).
      *
      * @since 1.0.0
      */
     private invokeClass;
+    /**
+     * Handles function invocation when the mock is called.
+     *
+     * @param target - The mock function instance
+     * @param thisArg - The 'this' context for the function call
+     * @param argumentsList - The arguments passed to the function
+     * @returns The result of the function invocation
+     *
+     * @remarks
+     * This method is used as the 'apply' trap for the Proxy surrounding the mock function.
+     * It captures the calling context in the mock's state for later verification, then
+     * delegates to the `invoke` method to handle the actual function call logic.
+     *
+     * This method is called whenever the mock function is invoked as a regular function
+     * (not as a constructor).
+     *
+     * @since 1.0.0
+     */
+    private invokeFunction;
 }
 
 /**
@@ -621,6 +767,9 @@ interface BoundInterface<Context = unknown | null | undefined, Args = Array<unkn
     __boundArgs?: Args;
 }
 
+/**
+ * Import will remove at compile time
+ */
 /**
  * Represents the possible result types of a mock function invocation.
  *
@@ -680,35 +829,35 @@ interface MockInvocationResultInterface<T> {
  *
  * @since 1.0.0
  */
-interface MocksStateInterface<ReturnType, Args extends Array<unknown> = [], Context = unknown> {
+interface MocksStateInterface<F extends FunctionType> {
     /**
      * An array that holds the arguments for each invocation made to the mock.
      * Each entry corresponds to the arguments passed during a single call to the mock function.
      *
      * @since 1.0.0
      */
-    calls: Array<Args>;
+    calls: Array<Parameters<F>>;
     /**
      * The arguments passed to the mock during its most recent invocation.
      * Returns `undefined` if the mock has not been called yet.
      *
      * @since 1.0.0
      */
-    lastCall?: Args;
+    lastCall?: Parameters<F>;
     /**
      * An array of contexts (`this` values) for each invocation made to the mock.
      * Each entry corresponds to the context in which the mock was called.
      *
      * @since 1.0.0
      */
-    contexts: Array<Context>;
+    contexts: Array<ThisParameterType<F>>;
     /**
      * An array of all object instances created by the mock.
      * Each entry represents an instance was instantiated during the mocks invocations.
      *
      * @since 1.0.0
      */
-    instances: Array<Context>;
+    instances: Array<ThisParameterType<F>>;
     /**
      * An array of invocation order indices for the mock.
      * xJet assigns an index to each call, starting from 1, to track the order in which mocks are invoked within a test file.
@@ -722,8 +871,39 @@ interface MocksStateInterface<ReturnType, Args extends Array<unknown> = [], Cont
      *
      * @since 1.0.0
      */
-    results: Array<MockInvocationResultInterface<ReturnType>>;
+    results: Array<MockInvocationResultInterface<ReturnType<F>>>;
 }
+/**
+ * A utility type that extracts the signature of a function and allows it to be reused in an implementation.
+ *
+ * @remarks
+ * This type creates a representation of a function's signature based on its return type, parameters, and
+ * `this` context. It's particularly useful for creating mock implementations, decorators, or wrappers
+ * that need to maintain the same signature as the original function.
+ *
+ * By using this type, you can ensure type safety when implementing functions that need to match
+ * an existing function's signature exactly, including its return type, parameter types, and `this` binding.
+ *
+ * @typeParam F - The original function type to extract the signature from
+ *
+ * @example
+ * ```ts
+ * // Original function
+ * function greet(name: string): string {
+ *   return `Hello, ${name}!`;
+ * }
+ *
+ * // Implementation with the same signature
+ * const mockGreet: ImplementationType<typeof greet> = function(name) {
+ *   return `Mocked greeting for ${name}`;
+ * };
+ *
+ * // Both functions now have the exact same type signature
+ * ```
+ *
+ * @since 1.2.2
+ */
+type ImplementationType<F extends FunctionType> = FunctionLikeType<ReturnType<F>, Parameters<F>, ThisParameterType<F>>;
 
 /**
  * Import will remove at compile time
@@ -2905,10 +3085,6 @@ declare function getTrimmedStackString(position?: number): string;
 /**
  * Imports
  */
-declare const proxyRegistry: WeakMap<object, {
-    proxy: unknown;
-    spies: Map<PropertyKey, MockState>;
-}>;
 /**
  * Checks if a property on an object is provided via a proxy mechanism rather than directly defined.
  *
@@ -2950,269 +3126,247 @@ declare const proxyRegistry: WeakMap<object, {
  */
 declare function isProxyProperty<T extends object>(obj: T, key: keyof T): boolean;
 /**
- * Creates a spy on a property accessed via a proxy getter, allowing interception
- * and monitoring of property access operations.
+ * Determines if a value is a mock proxy created by the mocking system.
  *
- * @template T - The type of the target object containing the proxy
- * @template K - The type of property key being spied on
+ * @param value - The value to check
+ * @returns `true` if the value is a mock proxy, `false` otherwise
  *
- * @param target - The object containing the property to spy on
- * @param key - The property key to intercept access to
- * @param method - The method to execute when the property is accessed
- * @returns A {@link MockState} instance that tracks interactions with the property
+ * @remarks
+ * This function checks if an object has the internal `__isMockProxy__` symbol property
+ * which is added to all mock proxy objects created by the mocking framework.
  *
- * @throws Error - If the target is not part of any global object
+ * Mock proxies are specialized proxy objects that intercept property access
+ * and method calls while providing mocking capabilities.
  *
  * @example
  * ```ts
- * // Create an object with dynamic property access
- * const user = new Proxy({}, {
- *   get(target, prop) {
- *     if (prop === 'name') return 'John';
- *     return target[prop];
- *   }
- * });
- *
- * // Spy on the 'name' property
- * const nameSpy = spyOnProxyGet(user, 'name', () => 'Jane');
+ * const regularObject = { name: 'Test' };
+ * const mockObject = createMock({ name: 'Test' });
  *
- * // Now accessing user.name returns 'Jane' and the access is tracked
- * console.log(user.name); // 'Jane'
- * expect(nameSpy).toHaveBeenCalled();
- *
- * // Restore original behavior
- * nameSpy.mockRestore();
- * console.log(user.name); // 'John'
+ * isMockProxy(regularObject); // false
+ * isMockProxy(mockObject);    // true
  * ```
  *
- * @see MockState
- * @see getParentObject
- *
- * @since 1.2.0
+ * @since 1.2.2
  */
-declare function spyOnProxyGet<T extends object, K extends keyof T>(target: T, key: K, method: unknown): MockState;
+declare function isMockProxy(value: Record<symbol, unknown>): boolean;
 /**
- * Creates a spy on a specified static method or static property of a target class (not a class instance).
- * Useful for mocking behavior during testing.
+ * Creates a mock proxy that intercepts property access on an object.
  *
- * @template Target - The type of the target class.
- * @template Key - The static method or static property key on the target object to spy on.
+ * @template T - The type of the target object being proxied
+ * @param target - The object to be proxied
+ * @returns A MockProxyInterface that intercepts property access on the target
  *
- * @param target - The object on which to spy.
- * @param key - The key of the method or property of the target to spy on.
- * @returns If the spied-on property is a function, returns a `MockState` object for the function,
- * allowing tracking of calls and modifying the return value or behavior.
- * Otherwise, returns a `MockState` object for the property, enabling tracking and manipulation of its value.
+ * @remarks
+ * This function creates a proxy around an object that allows for interception
+ * and customization of property access. The proxy maintains an internal state
+ * that tracks mocked properties and provides mechanisms for customizing getter behavior.
  *
- * @throws Error Throws an error if the `target` is a primitive value.
- * @throws Error Throws an error if `key` is null or undefined.
- * @throws Error Throws an error if the specified property does not exist on the target object.
+ * The proxy implements special properties:
+ * - `__isMockProxy__`: Used to identify mock proxy objects
+ * - `__MockMap__`: Provides access to the internal state for managing mocks
  *
- * @remarks
- * This function is commonly used in testing environments to replace or monitor functionality without
- * altering the actual logic in the source code. It provides fine-grained control over target behavior.
+ * Property access behavior:
+ * 1. First checks if a custom getter is defined and uses it if available
+ * 2. Then checks if the property has a specific mock implementation
+ * 3. Falls back to the original property on the target object
  *
  * @example
  * ```ts
- * class ClassTest {
- *     static name: string = 'ClassTest';
- *
- *     static x(param: string) {
- *         console.log(`original static x ${ param }`);
- *     }
- * }
+ * const user = { name: 'John', getAge: () => 30 };
+ * const mockUser = createMockProxy(user);
  *
- * const spy1 = xJet.spyOn(ClassTest, 'name');
- * const spy2 = xJet.spyOn(ClassTest, 'x');
+ * // Access original property
+ * console.log(mockUser.name); // "John"
  *
- * spy1.mockReturnValueOnce('Mock name');
- * spy2.mockImplementationOnce((param: string) => {
- *     console.log(`Mock x ${ param }`);
- * });
+ * // Add a mock for a property
+ * const mockMap = mockUser.__MockMap__;
+ * mockMap.mocks.set('getAge', () => 25);
  *
- * console.log(ClassTest.name); // Mock name
- * console.log(ClassTest.name); // ClassTest
- *
- * ClassTest.x('test1'); // Mock x test1
- * ClassTest.x('test2'); // original static x test2
+ * // Now returns the mock implementation
+ * console.log(mockUser.getAge()); // 25
  * ```
  *
- * @see FunctionType
- * @see KeysExtendingConstructorType
- *
- * @since 1.0.0
+ * @since 1.2.2
  */
-declare function spyOnImplementation<Target, Key extends KeysExtendingConstructorType<Target>>(target: Target, key: Key): Target[Key] extends FunctionType ? MockState<ReturnType<Target[Key]>, Parameters<Target[Key]>, Target> : MockState<Target[Key], [], Target>;
+declare function createMockProxy<T extends object>(target: T): MockProxyInterface;
 /**
- * Creates a mock spy on the specified method or constructor of the target object.
- *
- * @template Target The type of the target object.
- * @template Key The type of the method or constructor key on the target object.
+ * Creates a spy on a property access for a proxied object.
  *
- * @param target - The object whose method or constructor needs to be spied on.
- * @param key - The property key of the method or constructor to spy on.
- * @return A mock state representing the spied method or constructor if the key corresponds to a constructor type;
- * otherwise, throws a type error.
+ * @template T - The type of the target object
+ * @template K - The key of the property to spy on
  *
- * @throws Error Throws an error if the `target` is a primitive value.
- * @throws Error Throws an error if `key` is null or undefined.
- * @throws Error Throws an error if the specified property does not exist on the target object.
+ * @param target - The proxy object containing the property to spy on
+ * @param prop - The name of the property to spy on
+ * @returns A MockState object wrapping the property access
  *
  * @remarks
- * This method is typically used for testing purposes to observe or manipulate calls to the method or constructor of an object.
- * The returned mock state may allow additional configuration, such as altering its behavior or tracking calls.
+ * This specialized spy function is designed to work with properties accessed through proxy objects.
+ * It handles the complexities of intercepting property access in proxied objects by:
+ *
+ * 1. Locating the proxy object in the global scope if needed
+ * 2. Converting a normal object to a mock proxy if it isn't already one
+ * 3. Setting up a spy on the property get operation
+ *
+ * The function ensures proper cleanup by providing a cleanup function that removes
+ * the spy from the proxy's internal mock map when the spy is restored.
+ *
+ * @throws Error - When the target object cannot be found in the global scope
  *
  * @example
  * ```ts
- * const coolObject = {
- *     ClassTest: class {
- *         constructor(param: number) {
- *             console.log('original Constructor');
- *         }
- *
- *         justAnFunction() {
- *             console.log('original justAnFunction');
- *         }
- *     }
- * };
+ * // With an existing proxy
+ * const proxyObj = createMockProxy({ getData: () => 'data' });
+ * const spy = spyOnProxyGet(proxyObj, 'getData');
  *
- * const spy = xJet.spyOn(coolObject, 'ClassTest');
- * spy.mockImplementationOnce((param: number) => {
- *     console.log(`mock Constructor with param: ${ param }`);
- *
- *     return <any> {
- *         justAnFunction() {
- *             console.log('mock justAnFunction');
- *         }
- *     };
- * });
+ * proxyObj.getData(); // Spy records this call
+ * spy.verify.called(); // Passes
  *
- * const instance = new coolObject.ClassTest(1); // mock Constructor with param: 1
- * instance.justAnFunction(); // mock justAnFunction
+ * // With a normal object (will be converted to proxy)
+ * const obj = { getValue: () => 42 };
+ * const valueSpy = spyOnProxyGet(obj, 'getValue');
  *
- * const instance2 = new coolObject.ClassTest(2); // original Constructor
- * instance2.justAnFunction(); // original justAnFunction
+ * obj.getValue(); // Spy records this call
+ * valueSpy.verify.called(); // Passes
  * ```
  *
- * @see ConstructorType
- * @see ConstructorKeysType
- *
- * @since 1.0.0
+ * @since 1.2.2
  */
-declare function spyOnImplementation<Target, Key extends ConstructorKeysType<Target>>(target: Target, key: Key): Target[Key] extends ConstructorLikeType ? MockState<InstanceType<Target[Key]>, ConstructorParameters<Target[Key]>, Target> : never;
+declare function spyOnProxyGet<T extends Record<string | symbol, unknown>, K extends keyof T>(target: T, prop: K): MockState;
 /**
- * Creates a spy on a specific method or property of the given target object.
+ * Creates a spy on a method or property of an object.
  *
- * @template Target - The type of the target object to spy on.
- * @template Key - The key of the property or method to spy on within the target object.
+ * @template T - The type of the target object
+ * @template K - The key of the property or method to spy on
  *
- * @param target - The target object containing the property or method to be spied upon.
- * @param key - The name of the property or method on the target object to spy on.
- * @returns If the spied target is a function, it returns a `MockState` object to observe calls and arguments of the function.
- *          Otherwise, it returns a `MockState` object to observe the value or state of the property.
+ * @param target - The object containing the method or property to spy on
+ * @param key - The name of the method or property to spy on
+ * @returns A MockState object wrapping the original method or property
  *
- * @throws Error Throws an error if the `target` is a primitive value.
- * @throws Error Throws an error if `key` is null or undefined.
- * @throws Error Throws an error if the specified property does not exist on the target object.
+ * @remarks
+ * This function creates a spy that wraps around an existing method or property on an object.
+ * The spy tracks all calls to the method or access to the property while still executing the original functionality.
  *
- * @remarks This method is commonly used in test environments to monitor and assert interactions with a specific property
- *          or method on an object. The returned `MockState` can be used to retrieve call history or observe mutations.
+ * - For methods: The spy preserves the original `this` context and passes all arguments to the original method
+ * - For properties: The spy intercepts property access and returns the original value
  *
  * @example
  * ```ts
- * const coolObject = {
- *     myMethod() {
- *         return 'Original myMethod';
- *     },
- *     coolString: 'Original coolString'
+ * // Spying on a method
+ * const user = {
+ *   getName: (prefix: string) => prefix + ' John'
  * };
+ * const spy = xJet.spyOn(user, 'getName');
  *
- * const spy = xJet.spyOn(coolObject, 'coolString');
- * const spy2 = xJet.spyOn(coolObject, 'myMethod');
- *
- * spy.mockImplementationOnce(() => 'mock coolString');
- * spy2.mockImplementationOnce(() => 'mock myMethod string');
- *
- * console.log(coolObject.coolString); // mock coolString
- * console.log(coolObject.coolString); // Original coolString
- * console.log(coolObject.myMethod()); // mock myMethod string
- * console.log(coolObject.myMethod()); // Original myMethod
+ * user.getName('Mr.'); // Returns "Mr. John"
  * ```
  *
- * @see FunctionType
- *
  * @since 1.0.0
  */
-declare function spyOnImplementation<Target, Key extends keyof Target>(target: Target, key: Key): Target[Key] extends FunctionType ? MockState<ReturnType<Target[Key]>, Parameters<Target[Key]>, ThisParameterType<Target[Key]>> : MockState<Target[Key] | void, [Target[Key]], ThisParameterType<Target[Key]>>;
+declare function spyOnImplementation<T extends object, K extends keyof T>(target: T, key: K): T[K] extends FunctionType ? MockState<(this: ThisParameterType<T[K]>, ...args: Parameters<T[K]>) => PartialResolvedType<ReturnType<T[K]>>> : MockState<() => T[K]>;
 
 /**
  * Import will remove at compile time
  */
 /**
- * A utility type that removes all index signatures (string and number keys) from the given type `T`.
- * This results in a new type that retains only explicitly defined properties.
+ * Represents a mockable function interface with a customizable return type, context,
+ * and argument list. This interface extends `MockState` to facilitate tracking
+ * and testing of function behaviors and states.
  *
- * @template T - The type from which index signatures are to be removed.
+ * @template F - The function / class type being mocked
  *
  * @remarks
- * This type is useful for filtering out index signatures from types, especially when working
- * with mapped or dynamic types where indexable properties are not desired.
- * When an object has an index signature (e.g., `[key: string]: any`), TypeScript assumes that all
- * possible string or number keys exist on the object. This utility type filters out such keys,
- * leaving only explicitly defined properties.
+ * This interface is useful for creating test doubles or mock implementations that simulate
+ * complex behaviors (allows for both `function-like` behavior and `constructor-like` behavior)
+ * while tracking interactions and state information.
  *
- * @see https://stackoverflow.com/a/66252656/4536543
+ * @see MockState
  *
  * @since 1.0.0
  */
-type RemoveIndexType<T> = {
-    [P in keyof T as string extends P ? never : number extends P ? never : P]: T[P];
-};
+interface MockableFunctionInterface<F extends FunctionType> extends MockState<F> {
+    /**
+     * Constructor signature when the mocked item is used with 'new'
+     */
+    new (...args: Parameters<F>): ReturnType<F>;
+    /**
+     * Function call signature preserving 'this' context and parameters
+     */
+    (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F>;
+}
 /**
- * A utility type that maps the keys of a given type `T` whose properties are constructor types.
+ * Makes properties of a type or its resolved promise value optional.
  *
- * This type iterates over the properties of `RemoveIndexType<T>`,
- * retaining only those keys where the value matches a constructor type.
- *
- * @template T - The target type from which constructor-like properties are to be extracted.
+ * @template T - The type to transform
  *
  * @remarks
- * This type is designed to filter out keys of a given type `T` to include only those that are associated with constructor functions.
- * It leverages mapped types along with conditional type checks to achieve this functionality.
+ * If T is a Promise-like type, this utility unwraps it and makes the resolved value's
+ * properties optional. Otherwise, it directly makes T's properties optional.
  *
- * @since 1.0.0
+ * @example
+ * ```ts
+ * // Makes properties of User optional
+ * type MaybeUser = PartialResolvedType<User>;
+ *
+ * // Makes properties of resolved User optional
+ * type MaybeAsyncUser = PartialResolvedType<Promise<User>>;
+ * ```
+ *
+ * @since 1.2.2
  */
-type PropertiesWithConstructorsType<T> = {
-    [Key in keyof RemoveIndexType<T> as RemoveIndexType<T>[Key] extends ConstructorType ? Key : never]: RemoveIndexType<T>[Key];
-};
+type PartialResolvedType<T> = T extends PromiseLike<infer U> ? Promise<Partial<U>> : Partial<T>;
+
 /**
- * A utility type that extracts the keys of the provided type `T` that correspond
- * to properties with constructor types, removing any index signatures.
- *
- * @template T - The object type from which constructor property keys are extracted.
+ * Interface representing the internal state of a mock proxy.
  *
  * @remarks
- * This type is useful for narrowing down a type to only the keys representing
- * properties with constructor functions (e.g., classes) while excluding index signatures.
+ * This interface defines the structure for storing and managing the internal state
+ * of mock proxies, including mock implementations and custom property access behavior.
  *
- * @since 1.0.0
+ * @since 1.2.2
  */
-type ConstructorKeysType<T> = RemoveIndexType<keyof PropertiesWithConstructorsType<T>>;
+interface MockProxyStateInterface {
+    /**
+     * Map storing mock implementations for specific properties.
+     * Keys are property names, values are the mock implementations.
+     *
+     * @since 1.2.2
+     */
+    mocks: Map<PropertyKey, unknown>;
+    /**
+     * Optional custom getter function that overrides default property access behavior.
+     * When provided, this function is called for all property access on the mock proxy.
+     *
+     * @since 1.2.2
+     */
+    customGetter: ((target: object, prop: PropertyKey, receiver: unknown) => unknown) | null;
+}
 /**
- * A utility type that extracts the keys of a type `T` if `T` extends a constructor type.
- * If `T` does not extend a constructor type, it resolves to `never`.
- *
- * @template T - The type to check and extract keys from.
- *
- * @param T - The generic type parameter which is evaluated against a constructor type.
+ * Interface representing a mock proxy object.
  *
  * @remarks
- * This type is particularly useful when working with class-like or constructor-based types.
- * It further applies `RemoveIndexType` to exclude index signatures from the resulting keys.
+ * A `MockProxyInterface` defines the structure of objects that have been
+ * wrapped by a mocking proxy system. These proxies intercept property access
+ * and allow for dynamic replacement or monitoring of object properties.
  *
- * @since 1.0.0
+ * @since 1.2.2
  */
-type KeysExtendingConstructorType<T> = T extends ConstructorType ? keyof RemoveIndexType<T> : never;
+interface MockProxyInterface extends Record<PropertyKey, unknown> {
+    /**
+     * A boolean flag that indicates this object is a mock proxy.
+     * Used for type checking and identification of mock objects.
+     *
+     * @since 1.2.2
+     */
+    readonly __isMockProxy__?: true;
+    /**
+     * Provides access to the internal state of the mock proxy,
+     * including mapped mock implementations and custom getter functions.
+     *
+     * @since 1.2.2
+     */
+    readonly __MockMap__?: MockProxyStateInterface;
+}
 
 /**
  * Import will remove at compile time
@@ -3220,41 +3374,6 @@ type KeysExtendingConstructorType<T> = T extends ConstructorType ? keyof RemoveI
 /**
  * Imports
  */
-/**
- * Finds the parent object and name of a given function or value in the global scope.
- *
- * @param fn - The function or value to find in the global scope
- * @returns An object containing the name and parent object of the function, or `undefined` if not found
- *
- * @remarks
- * The `getParentObject` function attempts to locate where a function or value is defined
- * within the global context (`globalThis`). It searches for the function's name in the
- * global scope and also within properties of global objects. This is useful for
- * determining the original location of a function or value in the global namespace.
- *
- * Responsibilities:
- * - Finding functions directly attached to `globalThis`
- * - Locating functions within objects in the global scope
- * - Identifying functions by reference equality with global properties
- * - Supporting both named and anonymous functions
- *
- * @example
- * ```ts
- * // Finding a global function
- * const result = getParentObject(setTimeout);
- * // Returns: { name: 'setTimeout', parent: globalThis }
- *
- * // Finding a method on a global object
- * const arrayResult = getParentObject(Array.prototype.map);
- * // Returns: { name: 'map', parent: Array.prototype }
- * ```
- *
- * @since 1.2.0
- */
-declare function getParentObject(fn: unknown): {
-    name: string;
-    object: Record<string, unknown>;
-} | undefined;
 /**
  * Creates a mock for an object property using property descriptors.
  *
@@ -3292,8 +3411,8 @@ declare function mockDescriptorProperty<T extends object>(target: T, key: string
  * Creates a mock function interface with the specified implementation and optional restore function.
  *
  * @template ReturnType - The return type of the mocked function.
- * @template Context - The context type that the mocked function binds to.
  * @template Args - The argument type of the mocked function. Defaults to an array of unknown values.
+ * @template Context - The context type that the mocked function binds to.
  *
  * @param implementation - An optional implementation of the mocked function.
  * @param restore - An optional restore function used to reset the mock.
@@ -3306,7 +3425,7 @@ declare function mockDescriptorProperty<T extends object>(target: T, key: string
  * Responsibilities:
  * - Creating mock functions with custom implementations
  * - Supporting restore functionality for resetting mocks
- * - Providing type-safe mock interfaces via {@link FnMockInterface}
+ * - Providing type-safe mock interfaces via {@link MockableFunctionInterface}
  * - Integrating with the {@link MockState} system
  *
  * @example
@@ -3321,61 +3440,80 @@ declare function mockDescriptorProperty<T extends object>(target: T, key: string
  * ```
  *
  * @see MockState
- * @see FnMockInterface
+ * @see MockableFunctionInterface
  * @see FunctionLikeType
  *
  * @since 1.2.0
  */
-declare function fnImplementation<ReturnType, Args extends Array<unknown>, Context>(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: () => FunctionLikeType<ReturnType, Args, Context> | void): FnMockInterface<ReturnType, Args, Context>;
+declare function fnImplementation<ReturnType, Args extends Array<unknown>, Context>(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: () => FunctionLikeType<ReturnType, Args, Context> | void): MockableFunctionInterface<FunctionLikeType<ReturnType, Args, Context>>;
 /**
- * Creates a mock function with an optional custom implementation.
+ * Creates a mock implementation of the provided class constructor.
+ *
+ * @param method - The class constructor to mock
+ * @param implementation - Optional custom implementation of the mocked constructor
+ * @returns The mock state associated with the mocked constructor
+ *
+ * @remarks
+ * This overload of the mockImplementation function is specifically designed for mocking class constructors.
+ * It allows for replacing a class implementation during testing while tracking instantiation.
+ *
+ * The implementation function can return a partial instance of the class, which will be used
+ * as the constructed object when the mock is called with 'new'.
+ *
+ * @example
+ * ```ts
+ * class User {
+ *   name: string;
+ *   age: number;
+ *   constructor (name: string, age: number) {
+ *     this.name = name;
+ *     this.age = age;
+ *   }
+ * }
+ *
+ * const MockUser = mockImplementation(User, (name, age) => ({ name, age: age + 1 }));
+ * const user = new MockUser('Alice', 30); // user.age === 31
+ * MockUser.verify.called(); // passes
+ * ```
  *
- * @template Method - The return type of the function being mocked
- * @template Args - The argument types for the function, defaulting to unknown array
- * @template Context - The context type (`this`) for the function, defaulting to unknown
+ * @since 1.2.2
+ */
+declare function mockImplementation<F extends abstract new (...args: any) => any>(method: F, implementation?: (...args: ConstructorParameters<F>) => PartialResolvedType<InstanceType<F>>): MockState<(...args: ConstructorParameters<F>) => PartialResolvedType<InstanceType<F>>>;
+/**
+ * Creates a mock implementation of the provided function.
  *
- * @param method - The original function to mock
- * @param implementation - Optional custom implementation to use instead of the original
- * @returns A {@link MockState} instance that wraps the original function
+ * @param method - The function to mock
+ * @param implementation - Optional custom implementation that returns a partial result
+ * @returns The mock state associated with the mocked function
  *
  * @remarks
- * The `mockImplementation` function creates a new {@link MockState} instance that wraps
- * around a provided function, allowing you to monitor calls to that function and optionally
- * override its implementation. This is particularly useful for testing components that
- * depend on external functions by providing controlled behavior during tests.
+ * This overload of the mockImplementation function allows for providing an implementation
+ * that returns a partial result object. This is particularly useful when mocking functions
+ * that return complex objects where only specific properties are relevant for testing.
  *
- * Responsibilities:
- * - Creating a trackable mock function from any original function
- * - Supporting custom implementation override capability
- * - Preserving the original function's signature and return type
- * - Enabling all mock functionality like call tracking and verification
- * - Maintaining type safety between the original and mocked functions
+ * The implementation preserves the 'this' context from the original function, allowing
+ * for proper method mocking on objects.
  *
  * @example
  * ```ts
- * // Mock a function with default implementation
- * const fetchData = async () => ({ id: 1, name: 'Test' });
- * const mockedFetch = xJet.mock(fetchData);
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
  *
- * // Mock with custom implementation
- * const mockedFetchCustom = xJet.mock(fetchData, async () => {
- *   return { id: 2, name: 'Custom Test' };
- * });
+ * function getUser(id: number): User {
+ *   // real implementation
+ *   return { id, name: 'Real User', email: 'user@example.com' };
+ * }
  *
- * test('uses mocked function', async () => {
- *   const result = await mockedFetchCustom();
- *   expect(result.name).toBe('Custom Test');
- *   expect(mockedFetchCustom).toHaveBeenCalled();
- * });
+ * const mockGetUser = mockImplementation(getUser, (id) => ({ id, name: 'Mock User' }));
+ * const user = mockGetUser(123); // { id: 123, name: 'Mock User' }
  * ```
  *
- * @see MockState
- * @see FunctionLikeType
- * @see ConstructorLikeType
- *
- * @since 1.2.0
+ * @since 1.2.2
  */
-declare function mockImplementation<Method, Args extends Array<unknown> = [], Context = unknown>(method: FunctionLikeType<Method, Args, Context> | ConstructorLikeType<Method, Args>, implementation?: FunctionLikeType<Method, Args, Context>): MockState<Method, Args, Context>;
+declare function mockImplementation<F extends FunctionType>(method: F, implementation?: (...args: Parameters<F>) => PartialResolvedType<ReturnType<F>>): MockState<(this: ThisParameterType<F>, ...args: Parameters<F>) => PartialResolvedType<ReturnType<F>>>;
 /**
  * Creates a mock for an element with an optional custom implementation.
  *
@@ -3423,32 +3561,128 @@ declare function mockImplementation<Method, Args extends Array<unknown> = [], Co
  *
  * @since 1.2.0
  */
-declare function mockImplementation<Element = unknown>(item: Element, implementation?: FunctionLikeType<Element>): MockState<Element>;
+declare function mockImplementation<Element = unknown>(item: Element, implementation?: () => Element): MockState<() => Element>;
 
 /**
  * Import will remove at compile time
  */
 /**
- * Represents a mockable function interface with a customizable return type, context,
- * and argument list. This interface extends `MockState` to facilitate tracking
- * and testing of function behaviors and states.
+ * Recursively searches for a specific element within an object or its nested properties.
  *
- * @template ReturnType - Specifies the return type of the function. Defaults to `unknown`.
- * @template Context - Defines the function's "this" context type. Defaults to `unknown`.
- * @template Args - Sets the argument type(s) for the function, represented as an array. Defaults to `unknown[]`.
+ * @param target - The object to search within.
+ * @param element - The value to find within the target object or its nested properties.
+ * @param key - Optional specific key to search for within the target object.
+ * @param maxDepth - Maximum recursion depth to prevent infinite loops, defaults to 3.
+ * @returns A {@link DeepSearchInterface} object containing parent and key if found, or null if not found.
  *
  * @remarks
- * This interface is useful for creating test doubles or mock implementations that simulate
- * complex behaviors (allows for both `function-like` behavior and `constructor-like` behavior)
- * while tracking interactions and state information.
+ * This utility performs a depth-first search through an object's properties to locate a specific value
+ * or a property with a specific key. It maintains a set of visited objects to prevent circular reference issues.
  *
- * @see MockState
+ * The search process:
+ * - Tracks visited objects to avoid circular references
+ * - Searches by exact reference equality for the element
+ * - Handles errors during property access
+ * - Limits search depth to prevent stack overflow
+ * - Can find elements by exact key name (when the `key` parameter is provided)
  *
+ * @example
+ * ```ts
+ * const obj = {
+ *   a: 1,
+ *   b: {
+ *     c: 'test',
+ *     d: [1, 2, { e: 'target' }]
+ *   }
+ * };
+ *
+ * // Find by value
+ * const result = deepSearchObject(obj, 'target');
+ * // result: { parent: { e: 'target' }, key: 'e' }
+ *
+ * // Find by key name
+ * const byKey = deepSearchObject(obj, null, 'c');
+ * // byKey: { parent: { c: 'test', d: [...] }, key: 'c' }
+ * ```
+ *
+ * @see DeepSearchInterface
  * @since 1.0.0
  */
-interface FnMockInterface<ReturnType = unknown, Args extends Array<unknown> = any, Context = any> extends MockState<ReturnType, Args, Context> {
-    new (...args: Args): ReturnType;
-    (this: Context, ...args: Args): ReturnType;
+declare function deepSearchObject(target: Record<string | symbol, unknown>, element: unknown, key?: string, maxDepth?: number): DeepSearchInterface | null;
+/**
+ * Resolves property references that may be affected by ESBuild's `__toESM` transformation.
+ *
+ * @remarks
+ * This function handles a specific issue with ESBuild's module transformation where Node.js
+ * built-in modules (like 'fs', 'http', etc.) are wrapped with getter descriptors that aren't
+ * configurable. This causes problems when trying to mock or modify these modules in testing.
+ *
+ * When ESBuild transforms CommonJS modules to ESM, it creates non-configurable getter properties
+ * on the module object. This function detects such cases and returns a reference to the original
+ * underlying object instead, making the property accessible for mocking or modification.
+ *
+ * @param parent - The object containing the property to resolve
+ * @param key - The property name or symbol to resolve
+ * @returns A {@link DeepSearchInterface} pointing to either the original object or the
+ *          underlying object in case of non-configurable ESBuild transformations
+ *
+ * @example
+ * ```ts
+ * // When working with an ESBuild transformed fs module
+ * import * as fs from 'fs';
+ *
+ * // Normal access would use a non-configurable getter
+ * // Making it impossible to mock
+ * const originalRef = { parent: fs, key: 'readFileSync' };
+ *
+ * // This function resolves to the underlying object
+ * const mockableRef = getOwnProperty(fs, 'readFileSync');
+ * // Now we can mock it: mockableRef.parent[mockableRef.key] = mockFn;
+ * ```
+ *
+ * @since 1.2.2
+ */
+declare function getOwnProperty(parent: Record<string | symbol, unknown>, key: string | symbol): DeepSearchInterface;
+
+/**
+ * Interface representing the result of a deep object search operation.
+ *
+ * @remarks
+ * This interface provides a structured way to return the results of an object traversal
+ * search, containing both the parent object and the specific key where a target value was found.
+ * It allows callers to not only determine if a value was found, but also access its
+ * containing object and property name.
+ *
+ * The interface is typically used in deep search algorithms that need to return both
+ * the location of a found item and provide access to its context.
+ *
+ * @example
+ * ```ts
+ * // Example result from a search operation
+ * const result: DeepSearchInterface = {
+ *   parent: { id: 123, name: 'example' },
+ *   key: 'name'
+ * };
+ *
+ * // Accessing the found value through the result
+ * const foundValue = result.parent[result.key]; // 'example'
+ * ```
+ *
+ * @since 1.2.2
+ */
+interface DeepSearchInterface {
+    /**
+     * The property key (name) where the searched element was found.
+     *
+     * @since 1.2.2
+     */
+    key: string | symbol;
+    /**
+     * The parent object containing the found element.
+     *
+     * @since 1.2.2
+     */
+    parent: Record<string | symbol, unknown>;
 }
 
 /**