@remotex-labs/xjet 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -77,21 +77,73 @@ export {};
  * Imports
  */
 /**
- * Retrieves the parent object of the specified function if it exists within the global context.
+ * Finds the parent object and name of a given function or value in the global scope.
  *
- * @template FunctionLikeType - The type representing the input function.
+ * @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
  *
- * @param fn - The function whose parent object is to be retrieved.
- * @returns The parent object containing the function, or `undefined` if no such object is 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.
+ *
+ * @template T - The type of the target object containing the property to mock
+ *
+ * @param target - The object containing the property to mock
+ * @param key - The name of the property to mock
+ * @returns A {@link MockState} instance that tracks interactions with the property
  *
  * @remarks
- * This method searches for the parent object of a given function within the global context
- * by checking if the function name exists as a key of an object in the global scope.
- * If the function exists directly in the global scope, the global object itself is returned.
+ * The `mockDescriptorProperty` function replaces a property on a target object with a getter/setter
+ * that intercepts access to that property. This allows for monitoring and controlling property
+ * access during tests. The original property can be restored later through the mock's
+ * restore capability.
+ *
+ * Responsibilities:
+ * - Intercepting property access via custom property descriptors
+ * - Capturing the original property value and descriptor
+ * - Creating a {@link MockState} instance to track interactions
+ * - Supporting property restoration through the {@link MockState.mockRestore} method
+ * - Maintaining references in the global {@link MockState.mocks} registry
  *
- * @since 1.0.0
+ * @example
+ * ```ts
+ * // Mock a property on an object
+ * const obj = { value: 42 };
+ * const mockValue = mockDescriptorProperty(obj, 'value');
+ * ```
+ *
+ * @see MockState
+ * @since 1.2.0
  */
-declare function getParentObject(fn: FunctionLikeType): Record<string, unknown> | undefined;
+declare function mockDescriptorProperty<T extends object>(target: T, key: string | number | symbol): MockState;
 /**
  * Creates a mock function interface with the specified implementation and optional restore function.
  *
@@ -104,9 +156,14 @@ declare function getParentObject(fn: FunctionLikeType): Record<string, unknown>
  * @returns A mocked function interface with the specified behaviors.
  *
  * @remarks
- * This function creates a mock function handler, typically used in testing scenarios.
- * You can provide an implementation for the mock behavior or specify a restore
- * handler for resetting the mock's state.
+ * The `fnImplementation` function creates a mock function handler, typically used in testing scenarios.
+ * It transforms regular functions into mockable objects that can be monitored and controlled.
+ *
+ * Responsibilities:
+ * - Creating mock functions with custom implementations
+ * - Supporting restore functionality for resetting mocks
+ * - Providing type-safe mock interfaces via {@link FnMockInterface}
+ * - Integrating with the {@link MockState} system
  *
  * @example
  * ```ts
@@ -115,60 +172,114 @@ declare function getParentObject(fn: FunctionLikeType): Record<string, unknown>
  * console.log(mock(5)); // 10
  *
  * // Creating a mock with a restore function
- * const mockWithRestore = xJet.fnImplementation(undefined, () => { console.log('Restored!'); });
+ * const mockWithRestore = xJet.fn(undefined, () => { console.log('Restored!'); });
  * mockWithRestore.restore(); // "Restored!"
  * ```
  *
  * @see MockState
+ * @see FnMockInterface
+ * @see FunctionLikeType
  *
- * @since 1.0.0
+ * @since 1.2.0
  */
-declare function fnImplementation<ReturnType, Args extends Array<unknown>, Context>(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: FunctionLikeType<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): FnMockInterface<ReturnType, Args, Context>;
 /**
- * Creates a mock instance for the given method or constructor.
+ * Creates a mock function with an optional custom implementation.
  *
- * @template Method - The type of the method being mocked.
- * @template Context - The `this` context type of the method.
- * @template Args - The types of the arguments accepted by the method.
+ * @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
  *
- * @param method - The method or constructor to mock. This can either be a function-like type or a
- * constructor-like type.
- * @returns A `MockState` instance associated with the provided method, allowing for capturing
- * interactions and controlling behavior during testing.
+ * @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
  *
  * @remarks
- * This method identifies whether the provided method is a function or constructor and creates
- * a suitable mock state. If the method is already mocked, the existing mock state is returned.
- * Throws an error if the method does not belong to an object or if it has an invalid type.
+ * 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.
+ *
+ * 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
  *
  * @example
  * ```ts
- * // Mocking a regular method
- * function greet(name: string) {
- *     return `Hello, ${ name }`;
- * }
+ * // Mock a function with default implementation
+ * const fetchData = async () => ({ id: 1, name: 'Test' });
+ * const mockedFetch = xJet.mock(fetchData);
  *
- * const greetMock = xJet.mock(greet);
- * greetMock.mockImplementation(() => 'Hi!');
- * console.log(greet('World')); // "Hi!"
+ * // Mock with custom implementation
+ * const mockedFetchCustom = xJet.mock(fetchData, async () => {
+ *   return { id: 2, name: 'Custom Test' };
+ * });
  *
- * // Mocking a constructor
- * class Person {
- *     constructor(public name: string) {}
- * }
- * const personMock = xJet.mock(Person);
- * personMock.mockImplementation((name: string) => ({ name: `${name} (mocked)` }));
- * const person = new Person('Alice');
- * console.log(person.name); // "Alice (mocked)"
- *
- * // Restoring the original method
- * greetMock.mockRestore();
- * console.log(greet('World')); // "Hello, World"
+ * test('uses mocked function', async () => {
+ *   const result = await mockedFetchCustom();
+ *   expect(result.name).toBe('Custom Test');
+ *   expect(mockedFetchCustom).toHaveBeenCalled();
+ * });
  * ```
  *
- * @since 1.0.0
+ * @see MockState
+ * @see FunctionLikeType
+ * @see ConstructorLikeType
+ *
+ * @since 1.2.0
  */
-declare function mockImplementation<Method, Args extends Array<unknown>, Context>(method: FunctionLikeType<Method, Args, Context> | ConstructorLikeType<Method, Args>): MockState<Method, Args, Context>;
+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>;
+/**
+ * Creates a mock for an element with an optional custom implementation.
+ *
+ * @template Element - The type of the element being mocked
+ *
+ * @param item - The element to mock
+ * @param implementation - Optional custom implementation to replace the original element's behavior
+ * @returns A {@link MockState} instance that controls and tracks the mock
+ *
+ * @remarks
+ * The `mockImplementation` function creates a new {@link MockState} instance that wraps
+ * around the provided element, allowing you to observe interactions with it and optionally
+ * override its behavior. This is useful for isolating components during testing by
+ * replacing their dependencies with controlled mocks.
+ *
+ * Responsibilities:
+ * - Creating a trackable mock from any element
+ * - Supporting custom implementation substitution
+ * - Maintaining type safety between the original and mocked elements
+ * - Enabling interaction tracking and verification capabilities
+ * - Providing a fluent API for configuring mock behavior
+ *
+ * @example
+ * ```ts
+ * // Mock a simple value like export const testValue = 'original value'
+ * const mockValue = xJet.mock(testValue);
+ * mockValue.mockReturnValue("mocked value");
+ *
+ * // Mock a function
+ * const originalFn = (name: string) => `Hello, ${name}!`;
+ * const mockedFn = xJet.mock(originalFn);
+ *
+ * // Configure custom implementation
+ * mockedFn.mockImplementation((name: string) => `Hi, ${name}!`);
+ *
+ * test ('uses mocked function', () => {
+ *   const result = xJet.mock(testValue);
+ *   expect(result).toBe('Hi, World!');
+ *   expect(mockedFn).toHaveBeenCalledWith('World');
+ * });
+ * ```
+ *
+ * @see MockState
+ * @see FunctionLikeType
+ *
+ * @since 1.2.0
+ */
+declare function mockImplementation<Element = unknown>(item: Element, implementation?: FunctionLikeType<Element>): MockState<Element>;
 
 /**
  * Import will remove at compile time
@@ -241,16 +352,25 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
      */
     private state;
     /**
-     * A private function that restores the mocks original implementation.
-     * It resets the mock to its initial state, typically used when restoring
-     * the mock after a call to `mockReset` or `mockRestore`.
+     * A private function that restores the mock's original implementation.
      *
-     * This function is invoked internally to ensure that the mock behaves as
-     * originally defined before any changes were made to its behavior or implementation.
+     * @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.
      *
-     * @since v1.0.0
+     * 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
+     *
+     * @see MockState.mockRestore
+     * @see MockState.originalImplementation
+     *
+     * @since 1.2.0
      */
-    private readonly restore;
+    private readonly restore?;
     /**
      * A private array that stores the implementations queued to be executed
      * for future invocations of the mock.
@@ -265,7 +385,7 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
     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
+     * This function is executed whenever the mock is invoked and can be changed
      * using methods like `mockImplementation` or `mockImplementationOnce`.
      *
      * The `implementation` allows for customizing the behavior of the mock,
@@ -322,18 +442,30 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
      *
      * @since 1.0.0
      */
-    constructor(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: FunctionLikeType<void>, name?: string);
+    constructor(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: () => FunctionLikeType<ReturnType, Args, Context> | void, name?: string);
     /**
      * todo remove it
      * only for jest expect will support this mock
      */
     getMockName(): string;
     /**
-     * Retrieves the current state of mocks.
+     * Retrieves the current state of the mock function.
      *
-     * @return The current state of the mocks.
-     * @see MocksStateInterface
+     * @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.
+     *
+     * 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 read-only view of the mock state tracking object.
      *
+     * @see MocksStateInterface
      * @since 1.0.0
      */
     get mock(): Readonly<MocksStateInterface<ReturnType, Args, Context>>;
@@ -381,7 +513,7 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
      * @returns The current instance of the mock, allowing for method chaining.
      *
      * @remarks
-     * The `mockReset` method clears all invocation data and results by calling `mockClear()`, and also resets
+     * 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.
@@ -415,9 +547,9 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
     /**
      * Retrieves the mock implementation for a function, if available.
      *
-     * @template ReturnType The type of the return value of the function.
+     * @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 of the argument(s) of the function.
+     * @template Args The type the argument(s) of the function.
      *
      * @return A function matching `FunctionLikeType` that represents the mock implementation,
      * or `undefined` if no implementation is set.
@@ -606,7 +738,7 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
      * // Set default return value
      * mockFn.mockReturnValue('Default Value');
      *
-     * // Set one-time return value for the next call
+     * // Set a one-time return value for the next call
      * mockFn.mockReturnValueOnce('First Call');
      * mockFn.mockReturnValueOnce('Second Call');
      *
@@ -668,7 +800,7 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
      * // Set default rejected value
      * mockFn.mockRejectedValue('Default Error');
      *
-     * // Set one-time rejected value for the next call
+     * // Set a one-time rejected value for the next call
      * mockFn.mockRejectedValueOnce('First Call Error');
      *
      * mockFn().catch(error => {
@@ -965,23 +1097,92 @@ declare class ExecutionError extends Error {
 /**
  * Imports
  */
+declare const proxyRegistry: WeakMap<object, {
+    proxy: unknown;
+    spies: Map<PropertyKey, MockState>;
+}>;
 /**
- * Intercepts and mocks the property descriptor of a specified property on a target object.
+ * Checks if a property on an object is provided via a proxy mechanism rather than directly defined.
  *
- * @template Target - The target object type.
- * @template Key - The key of the property to be mocked.
+ * @template T - The type of object being checked
  *
- * @param target - The object whose property descriptor is being intercepted and mocked.
- * @param key - The property key on the target object to spy on.
- * @return A `MockState` instance that provides control over the mocked property and its interactions.
+ * @param obj - The object to inspect
+ * @param key - The property key to check on the object
+ * @returns `true` if the property is provided by a proxy, `false` if directly defined
  *
  * @remarks
- * This function replaces the property's getter and setter to allow interception and testing of their behavior.
- * A `MockState` instance is returned to control and observes mocked behavior.
+ * This function determines whether a property on an object is being provided through
+ * a proxy mechanism (like a Proxy object or getter) rather than being directly defined
+ * on the object itself. It works by checking if the key doesn't exist in the object's
+ * own properties while still returning a non-undefined value when accessed.
  *
- * @since 1.0.0
+ * This is useful for:
+ * - Detecting dynamically created properties
+ * - Identifying properties provided via getters or proxies
+ * - Distinguishing between direct properties and inherited/proxied ones
+ *
+ * @example
+ * ```ts
+ * // Regular object with direct property
+ * const directObj = { name: 'Test' };
+ * console.log(isProxyProperty(directObj, 'name')); // false
+ *
+ * // Object with proxy property
+ * const handler = {
+ *   get(target, prop) {
+ *     if (prop === 'dynamic') return 'This is dynamic';
+ *     return target[prop];
+ *   }
+ * };
+ * const proxyObj = new Proxy({}, handler);
+ * console.log(isProxyProperty(proxyObj, 'dynamic')); // true
+ * ```
+ *
+ * @since 1.2.0
+ */
+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.
+ *
+ * @template T - The type of the target object containing the proxy
+ * @template K - The type of property key being spied on
+ *
+ * @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
+ *
+ * @throws Error - If the target is not part of any global object
+ *
+ * @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');
+ *
+ * // 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'
+ * ```
+ *
+ * @see MockState
+ * @see getParentObject
+ *
+ * @since 1.2.0
  */
-declare function spyOnDescriptorProperty<Target, Key extends keyof Target>(target: Target, key: Key): MockState<Target[Key], []>;
+declare function spyOnProxyGet<T extends object, K extends keyof T>(target: T, key: K, method: unknown): MockState;
 /**
  * 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.