@remotex-labs/xjet 1.2.2 → 1.3.0

package/dist/index.d.ts

@@ -6,7 +6,6 @@
  import type { xExpect } from '@remotex-labs/xjet-expect';
 import type { FunctionLikeType, FunctionType } from '@remotex-labs/xjet-expect';
 import type { FunctionType } from '@remotex-labs/xjet-expect';
-import type { FunctionType, RejectedValueType, ResolvedValueType } from '@remotex-labs/xjet-expect';
 import type { ContextType } from '@remotex-labs/xjet-expect';
 import type { FunctionLikeType } from '@remotex-labs/xjet-expect';
 import type { ContextType, FunctionType } from '@remotex-labs/xjet-expect';
@@ -54,8 +53,11 @@ declare global {
         const runAllTimers: typeof FakeTimer.runAllTimers;
         const useFakeTimers: typeof FakeTimer.useFakeTimers;
         const useRealTimers: typeof FakeTimer.useRealTimers;
+        const clearAllTimers: typeof FakeTimer.clearAllTimers;
+        const runAllTimersAsync: typeof FakeTimer.runAllTimersAsync;
         const advanceTimersByTime: typeof FakeTimer.advanceTimersByTime;
         const runOnlyPendingTimers: typeof FakeTimer.runOnlyPendingTimers;
+        const runOnlyPendingTimersAsync: typeof FakeTimer.runOnlyPendingTimersAsync;
     }
     const it: TestDirectiveInterface;
     const test: TestDirectiveInterface;
@@ -178,7 +180,7 @@ declare function fnImplementation<ReturnType, Args extends Array<unknown>, Conte
  *
  * @since 1.2.2
  */
-declare function mockImplementation<F extends abstract new (...args: any) => any>(method: F, implementation?: (...args: ConstructorParameters<F>) => Partial<InstanceType<F>>): MockState<(...args: ConstructorParameters<F>) => Partial<InstanceType<F>>>;
+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.
  *
@@ -213,7 +215,7 @@ declare function mockImplementation<F extends abstract new (...args: any) => any
  *
  * @since 1.2.2
  */
-declare function mockImplementation<F extends FunctionType>(method: F, implementation?: (...args: Parameters<F>) => Partial<ReturnType<F>>): MockState<(this: ThisParameterType<F>, ...args: Parameters<F>) => Partial<ReturnType<F>>>;
+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.
  *
@@ -292,6 +294,35 @@ interface MockableFunctionInterface<F extends FunctionType> extends MockState<F>
      */
     (this: ThisParameterType<F>, ...args: Parameters<F>): ReturnType<F>;
 }
+/**
+ * Makes properties of a type or its resolved promise value optional.
+ * Converts `never` to `void` to avoid unassignable types.
+ *
+ * @template T - The type to transform
+ *
+ * @remarks
+ * If `T` is a `PromiseLike` type, this utility unwraps it and makes the resolved value's
+ * properties optional.
+ * If `T` is `never`, it is converted to `void`.
+ * Otherwise, it directly makes `T`'s properties optional.
+ *
+ * @example
+ * ```ts
+ * // Makes properties of User optional
+ * type MaybeUser = PartialResolvedType<User>;
+ *
+ * // Makes properties of resolved User optional
+ * type MaybeAsyncUser = PartialResolvedType<Promise<User>>;
+ *
+ * // Never becomes void
+ * type MaybeNever = PartialResolvedType<never>; // void
+ * ```
+ *
+ * @since 1.2.2
+ */
+type PartialResolvedType<T> = [
+    T
+] extends [never] ? void : T extends PromiseLike<infer U> ? Promise<Partial<U>> : Partial<T>;
 
 /**
  * Import will remove at compile time
@@ -813,7 +844,7 @@ export declare class MockState<F extends FunctionType = FunctionType> extends Fu
      *
      * @since 1.0.0
      */
-    mockResolvedValue(value: ResolvedValueType<ReturnType<F>>): this;
+    mockResolvedValue(value: PromiseValueType<ReturnType<F>>): this;
     /**
      * Adds a one-time resolved Promise return value for this mock function.
      *
@@ -847,7 +878,7 @@ export declare class MockState<F extends FunctionType = FunctionType> extends Fu
      *
      * @since 1.0.0
      */
-    mockResolvedValueOnce(value: ResolvedValueType<ReturnType<F>>): this;
+    mockResolvedValueOnce(value: PromiseValueType<ReturnType<F>>): this;
     /**
      * Sets a rejected Promise return value for this mock function.
      *
@@ -884,7 +915,7 @@ export declare class MockState<F extends FunctionType = FunctionType> extends Fu
      *
      * @since 1.0.0
      */
-    mockRejectedValue(value: RejectedValueType<ReturnType<F>>): this;
+    mockRejectedValue(value: PromiseValueType<ReturnType<F>>): this;
     /**
      * Adds a one-time rejected Promise return value for this mock function.
      *
@@ -920,7 +951,7 @@ export declare class MockState<F extends FunctionType = FunctionType> extends Fu
      *
      * @since 1.0.0
      */
-    mockRejectedValueOnce(value: RejectedValueType<ReturnType<F>>): this;
+    mockRejectedValueOnce(value: PromiseValueType<ReturnType<F>>): this;
     /**
      * Initializes the internal state object for the mock function.
      *
@@ -1017,26 +1048,6 @@ export declare class MockState<F extends FunctionType = FunctionType> extends Fu
     private invokeFunction;
 }
 
-/**
- * Represents an interface for defining bound context and arguments.
- *
- * @template Context - The type of the bound `this` context, which can be an object, null, or undefined.
- * @template Args - The type of the array representing bound arguments.
- *
- * @remarks
- * This interface is designed to store binding metadata, specifically a reference to the bound `this` context
- * and any arguments that are pre-applied during function binding. It is often used in scenarios involving
- * dynamic contexts or partial application of functions.
- *
- * @see ContextType
- *
- * @since 1.0.0
- */
-interface BoundInterface<Context = unknown | null | undefined, Args = Array<unknown>> {
-    __boundThis?: Context;
-    __boundArgs?: Args;
-}
-
 /**
  * Import will remove at compile time
  */
@@ -1143,6 +1154,29 @@ interface MocksStateInterface<F extends FunctionType> {
      */
     results: Array<MockInvocationResultInterface<ReturnType<F>>>;
 }
+/**
+ * Extracts the resolved value type from a `PromiseLike` type.
+ *
+ * @template T The input type to inspect.
+ *
+ * @remarks
+ * If `T` extends `PromiseLike<infer U>`, the resulting type is `U | T`, meaning it includes both
+ * the resolved value type and the original `PromiseLike` type.
+ *
+ * If `T` is not a `PromiseLike`, the resulting type is simply `T`.
+ *
+ * This utility type is useful when you want to support both synchronous and asynchronous values
+ * transparently — for example, when a function may return either a raw value or a promise.
+ *
+ * @example
+ * ```ts
+ * type A = PromiseValueType<Promise<number>>; // number | Promise<number>
+ * type B = PromiseValueType<string>;          // string
+ * ```
+ *
+ * @since 1.0.0
+ */
+type PromiseValueType<T> = T | (T extends PromiseLike<infer U> ? U | T : never);
 /**
  * A utility type that extracts the signature of a function and allows it to be reused in an implementation.
  *
@@ -1173,7 +1207,27 @@ interface MocksStateInterface<F extends FunctionType> {
  *
  * @since 1.2.2
  */
-type ImplementationType<F extends FunctionType> = FunctionLikeType<ReturnType<F>, Parameters<F>, ThisParameterType<F>>;
+type ImplementationType<F extends FunctionType> = FunctionLikeType<PromiseValueType<ReturnType<F>>, Parameters<F>, ThisParameterType<F>>;
+
+/**
+ * Represents an interface for defining bound context and arguments.
+ *
+ * @template Context - The type of the bound `this` context, which can be an object, null, or undefined.
+ * @template Args - The type of the array representing bound arguments.
+ *
+ * @remarks
+ * This interface is designed to store binding metadata, specifically a reference to the bound `this` context
+ * and any arguments that are pre-applied during function binding. It is often used in scenarios involving
+ * dynamic contexts or partial application of functions.
+ *
+ * @see ContextType
+ *
+ * @since 1.0.0
+ */
+interface BoundInterface<Context = unknown | null | undefined, Args = Array<unknown>> {
+    __boundThis?: Context;
+    __boundArgs?: Args;
+}
 
 /**
  * A base error class that extends the standard Error class with enhanced JSON serialization and location tracking
@@ -1299,7 +1353,7 @@ declare class ExecutionError extends Error {
  * @see DeepSearchInterface
  * @since 1.0.0
  */
-declare function deepSearchObject(target: Record<string | symbol, unknown>, element: unknown, key?: string, maxDepth?: number): DeepSearchInterface | null;
+declare function deepSearchObject(target: Record<string | symbol, unknown>, element: unknown, key?: string | symbol, maxDepth?: number): DeepSearchInterface | null;
 /**
  * Resolves property references that may be affected by ESBuild's `__toESM` transformation.
  *
@@ -1560,7 +1614,7 @@ declare function spyOnProxyGet<T extends Record<string | symbol, unknown>, K ext
  *
  * @since 1.0.0
  */
-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]>) => ReturnType<T[K]>> : MockState<() => T[K]>;
+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]>;
 
 /**
  * Interface representing the internal state of a mock proxy.
@@ -1720,6 +1774,26 @@ declare class TimerService {
      * @since 1.1.0
      */
     useRealTimers(): void;
+    /**
+     * Clears all active fake timers.
+     *
+     * @remarks
+     * This method removes every timer currently stored in {@link timers},
+     * effectively resetting the fake timer state without advancing time.
+     * It is useful for cleaning up between tests to ensure no lingering
+     * scheduled callbacks remain.
+     *
+     * @example
+     * ```ts
+     * useFakeTimers();
+     * setTimeout(() => console.log('A'), 100);
+     * clearAllTimers(); // removes all scheduled timers
+     * advanceTimersByTime(100); // nothing happens
+     * ```
+     *
+     * @since 1.3.0
+     */
+    clearAllTimers(): void;
     /**
      * Advances the simulated clock by a specific number of milliseconds and
      * executes all timers whose scheduled time has elapsed.
@@ -1790,6 +1864,51 @@ declare class TimerService {
      * @since 1.1.0
      */
     runOnlyPendingTimers(): void;
+    /**
+     * Asynchronous equivalent of {@link runAllTimers}.
+     *
+     * @remarks
+     * This method first yields to the event loop to allow any pending promises
+     * to resolve before executing all remaining fake timers.
+     * It ensures a deterministic sequence when timers and microtasks coexist.
+     *
+     * @example
+     * ```ts
+     * useFakeTimers();
+     * Promise.resolve().then(() => console.log('microtask'));
+     * setTimeout(() => console.log('timer'), 0);
+     * await timerService.runAllTimersAsync();
+     * // Logs:
+     * // microtask
+     * // timer
+     * ```
+     *
+     * @since 1.3.0
+     */
+    runAllTimersAsync(): Promise<void>;
+    /**
+     * Asynchronous equivalent of {@link runOnlyPendingTimers}.
+     *
+     * @remarks
+     * This method first yields to the event loop to allow any pending promises
+     * to resolve before executing only currently pending fake timers.
+     * Timers scheduled during execution will not run until explicitly advanced later.
+     *
+     * @example
+     * ```ts
+     * useFakeTimers();
+     * setTimeout(() => {
+     *   console.log('first');
+     *   setTimeout(() => console.log('second'), 100);
+     * }, 100);
+     * await timerService.runOnlyPendingTimersAsync();
+     * // Logs:
+     * // first
+     * ```
+     *
+     * @since 1.3.0
+     */
+    runOnlyPendingTimersAsync(): Promise<void>;
 }
 /**
  * Globally enables fake timers using the shared {@link TimerService}.
@@ -1853,6 +1972,31 @@ declare function useRealTimers(): void;
  * @since 1.1.0
  */
 declare function runAllTimers(): void;
+/**
+ * Removes all scheduled fake timers from the {@link TimerService}.
+ *
+ * @remarks
+ * This function clears all active timers registered in the shared timer service,
+ * effectively canceling any pending callbacks that would have run during
+ * timer advancement.
+ *
+ * It's useful for resetting the fake timer state between test cases to ensure
+ * no lingering timers affect further tests or for scenarios where you
+ * need to abort all pending operations.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => console.log('A'), 100);
+ * setTimeout(() => console.log('B'), 200);
+ *
+ * clearAllTimers(); // removes all scheduled timers
+ * advanceTimersByTime(1000); // nothing happens, not show any logs
+ * ```
+ *
+ * @since 1.3.0
+ */
+declare function clearAllTimers(): void;
 /**
  * Executes only the timers that are pending at the time of invocation.
  *
@@ -1900,6 +2044,48 @@ declare function runOnlyPendingTimers(): void;
  * @since 1.1.0
  */
 declare function advanceTimersByTime(ms?: number): void;
+/**
+ * Asynchronous equivalent of {@link runAllTimers}.
+ *
+ * @remarks
+ * Yields to the event loop before running all pending fake timers.
+ * Useful when working with both Promises and fake timers.
+ *
+ * @example
+ * ```ts
+ * xJet.useFakeTimers();
+ * Promise.resolve().then(() => console.log('promise done'));
+ * setTimeout(() => console.log('timeout done'), 0);
+ * await xJet.runAllTimersAsync();
+ * // Logs:
+ * // promise done
+ * // timeout done
+ * ```
+ *
+ * @since 1.3.0
+ */
+declare function runAllTimersAsync(): Promise<void>;
+/**
+ * Asynchronous equivalent of {@link runOnlyPendingTimers}.
+ *
+ * @remarks
+ * Yields to the event loop before running only timers that are currently pending.
+ * Any timers scheduled by those callbacks will not be executed until a later call.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => {
+ *   console.log('first');
+ *   setTimeout(() => console.log('second'), 100);
+ * }, 100);
+ * await runOnlyPendingTimersAsync();
+ * // Logs only "first"
+ * ```
+ *
+ * @since 1.3.0
+ */
+declare function runOnlyPendingTimersAsync(): Promise<void>;
 
 /**
  * Interface representing a single timer stored and executed by the {@link TimerService}.