vitest 1.6.0 → 2.0.0-beta.2

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { TaskPopulated, File, TaskResultPack, CancelReason } from '@vitest/runner';
 export { Custom, DoneCallback, ExtendedContext, File, HookCleanupCallback, HookListener, OnTestFailedHandler, RunMode, RuntimeContext, SequenceHooks, SequenceSetupFiles, Suite, SuiteAPI, SuiteCollector, SuiteFactory, SuiteHooks, Task, TaskBase, TaskContext, TaskCustomOptions, TaskMeta, TaskResult, TaskResultPack, TaskState, Test, TestAPI, TestContext, TestFunction, TestOptions, afterAll, afterEach, beforeAll, beforeEach, describe, it, onTestFailed, onTestFinished, suite, test } from '@vitest/runner';
-export { b as bench } from './suite-IbNSsUWN.js';
+export { b as bench } from './suite-C_sqQjdz.js';
 import { ExpectStatic } from '@vitest/expect';
 export { Assertion, AsymmetricMatchersContaining, ExpectStatic, JestAssertion } from '@vitest/expect';
-import { F as FakeTimerInstallOpts, M as MockFactoryWithHelper, s as RuntimeConfig, P as ProvidedContext, A as AfterSuiteRunMeta, t as UserConsoleLog, R as ResolvedConfig, u as ModuleGraphData, v as Reporter } from './reporters-yx5ZTtEV.js';
-export { Q as ApiConfig, aa as ArgumentsType, a9 as Arrayable, a7 as Awaitable, B as BaseCoverageOptions, ap as BenchFunction, an as Benchmark, aq as BenchmarkAPI, ao as BenchmarkResult, am as BenchmarkUserOptions, a0 as BrowserConfigOptions, r as BrowserScript, L as BuiltinEnvironment, O as CSSModuleScopeStrategy, y as CollectLineNumbers, z as CollectLines, ac as Constructable, G as Context, f as ContextRPC, a3 as ContextTestEnvironment, aj as CoverageIstanbulOptions, C as CoverageOptions, b as CoverageProvider, c as CoverageProviderModule, ai as CoverageReporter, ak as CoverageV8Options, al as CustomProviderOptions, X as DepsOptimizationOptions, E as Environment, S as EnvironmentOptions, ae as EnvironmentReturn, K as HappyDOMOptions, Z as InlineConfig, J as JSDOMOptions, ad as ModuleCache, ab as MutableArray, a8 as Nullable, ag as OnServerRestartHandler, H as Pool, I as PoolOptions, $ as ProjectConfig, w as RawErrsMap, ah as ReportContext, a5 as ResolveIdFunction, a as ResolvedCoverageOptions, a4 as ResolvedTestEnvironment, D as RootAndTarget, a2 as RunnerRPC, e as RuntimeRPC, Y as TransformModePatterns, x as TscErrorInfo, _ as TypecheckConfig, U as UserConfig, a1 as UserWorkspaceConfig, i as Vitest, N as VitestEnvironment, V as VitestRunMode, af as VmEnvironmentReturn, g as WorkerContext, W as WorkerGlobalState, a6 as WorkerRPC } from './reporters-yx5ZTtEV.js';
+import { F as FakeTimerInstallOpts, M as MockFactoryWithHelper, s as RuntimeConfig, P as ProvidedContext, A as AfterSuiteRunMeta, t as UserConsoleLog, R as ResolvedConfig, u as ModuleGraphData, v as Reporter } from './reporters-DFgqsvtL.js';
+export { Q as ApiConfig, aa as ArgumentsType, a9 as Arrayable, a7 as Awaitable, B as BaseCoverageOptions, ap as BenchFunction, an as Benchmark, aq as BenchmarkAPI, ao as BenchmarkResult, am as BenchmarkUserOptions, a0 as BrowserConfigOptions, r as BrowserScript, L as BuiltinEnvironment, O as CSSModuleScopeStrategy, y as CollectLineNumbers, z as CollectLines, ac as Constructable, G as Context, f as ContextRPC, a3 as ContextTestEnvironment, aj as CoverageIstanbulOptions, C as CoverageOptions, b as CoverageProvider, c as CoverageProviderModule, ai as CoverageReporter, ak as CoverageV8Options, al as CustomProviderOptions, X as DepsOptimizationOptions, E as Environment, S as EnvironmentOptions, ae as EnvironmentReturn, K as HappyDOMOptions, Z as InlineConfig, J as JSDOMOptions, ad as ModuleCache, ab as MutableArray, a8 as Nullable, ag as OnServerRestartHandler, H as Pool, I as PoolOptions, $ as ProjectConfig, w as RawErrsMap, ah as ReportContext, a5 as ResolveIdFunction, a as ResolvedCoverageOptions, a4 as ResolvedTestEnvironment, D as RootAndTarget, a2 as RunnerRPC, e as RuntimeRPC, Y as TransformModePatterns, x as TscErrorInfo, _ as TypecheckConfig, U as UserConfig, a1 as UserWorkspaceConfig, i as Vitest, N as VitestEnvironment, V as VitestRunMode, af as VmEnvironmentReturn, g as WorkerContext, W as WorkerGlobalState, a6 as WorkerRPC } from './reporters-DFgqsvtL.js';
 import { spyOn, fn, MaybeMockedDeep, MaybeMocked, MaybePartiallyMocked, MaybePartiallyMockedDeep, MockInstance } from '@vitest/spy';
 export { Mock, MockContext, MockInstance, Mocked, MockedClass, MockedFunction, MockedObject, SpyInstance } from '@vitest/spy';
 export { SnapshotEnvironment } from '@vitest/snapshot/environment';
@@ -26,20 +26,50 @@ import 'vite-node/server';
 import 'node:worker_threads';
 import 'node:fs';
 
+/**
+ * Negates a boolean type.
+ */
 declare type Not<T extends boolean> = T extends true ? false : true;
+/**
+ * Checks if all the boolean types in the {@linkcode Types} array are `true`.
+ */
 declare type And<Types extends boolean[]> = Types[number] extends true ? true : false;
+/**
+ * Represents an equality type that returns {@linkcode Right} if
+ * {@linkcode Left} is `true`,
+ * otherwise returns the negation of {@linkcode Right}.
+ */
 declare type Eq<Left extends boolean, Right extends boolean> = Left extends true ? Right : Not<Right>;
 declare const secret: unique symbol;
 declare type Secret = typeof secret;
+/**
+ * Checks if the given type is `never`.
+ */
 declare type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Checks if the given type is `any`.
+ */
 declare type IsAny<T> = [T] extends [Secret] ? Not<IsNever<T>> : false;
+/**
+ * Determines if the given type is `unknown`.
+ */
 declare type IsUnknown<T> = [unknown] extends [T] ? Not<IsAny<T>> : false;
+/**
+ * Determines the printable type representation for a given type.
+ */
 declare type PrintType<T> = IsUnknown<T> extends true ? 'unknown' : IsNever<T> extends true ? 'never' : IsAny<T> extends true ? never : boolean extends T ? 'boolean' : T extends boolean ? `literal boolean: ${T}` : string extends T ? 'string' : T extends string ? `literal string: ${T}` : number extends T ? 'number' : T extends number ? `literal number: ${T}` : T extends null ? 'null' : T extends undefined ? 'undefined' : T extends (...args: any[]) => any ? 'function' : '...';
-/** Subjective "useful" keys from a type. For objects it's just `keyof` but for tuples/arrays it's the number keys
+/**
+ * Subjective "useful" keys from a type. For objects it's just `keyof` but for
+ * tuples/arrays it's the number keys.
+ *
  * @example
+ * ```ts
  * UsefulKeys<{a: 1; b: 2}> // 'a' | 'b'
+ *
  * UsefulKeys<['a', 'b']> // '0' | '1'
+ *
  * UsefulKeys<string[]> // number
+ * ```
  */
 declare type UsefulKeys<T> = T extends any[] ? {
     [K in keyof T]: K;
@@ -48,15 +78,20 @@ declare type MismatchInfo<Actual, Expected> = And<[Extends<PrintType<Actual>, '.
     [K in UsefulKeys<Actual> | UsefulKeys<Expected>]: MismatchInfo<K extends keyof Actual ? Actual[K] : never, K extends keyof Expected ? Expected[K] : never>;
 } : StrictEqualUsingBranding<Actual, Expected> extends true ? Actual : `Expected: ${PrintType<Expected>}, Actual: ${PrintType<Exclude<Actual, Expected>>}`;
 /**
- * Recursively walk a type and replace it with a branded type related to the original. This is useful for
- * equality-checking stricter than `A extends B ? B extends A ? true : false : false`, because it detects
- * the difference between a few edge-case types that vanilla typescript doesn't by default:
+ * Represents a deeply branded type.
+ *
+ * Recursively walk a type and replace it with a branded type related to the
+ * original. This is useful for equality-checking stricter than
+ * `A extends B ? B extends A ? true : false : false`, because it detects the
+ * difference between a few edge-case types that vanilla typescript
+ * doesn't by default:
  * - `any` vs `unknown`
  * - `{ readonly a: string }` vs `{ a: string }`
  * - `{ a?: string }` vs `{ a: string | undefined }`
  *
- * Note: not very performant for complex types - this should only be used when you know you need it. If doing
- * an equality check, it's almost always better to use `StrictEqualUsingTSInternalIdenticalToOperator`.
+ * __Note__: not very performant for complex types - this should only be used
+ * when you know you need it. If doing an equality check, it's almost always
+ * better to use {@linkcode StrictEqualUsingTSInternalIdenticalToOperator}.
  */
 declare type DeepBrand<T> = IsNever<T> extends true ? {
     type: 'never';
@@ -92,10 +127,19 @@ declare type DeepBrand<T> = IsNever<T> extends true ? {
     optional: OptionalKeys<T>;
     constructorParams: DeepBrand<ConstructorParams<T>>;
 };
+/**
+ * Extracts the keys from a type that are required (not optional).
+ */
 declare type RequiredKeys<T> = Extract<{
     [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
 }[keyof T], keyof T>;
+/**
+ * Gets the keys of an object type that are optional.
+ */
 declare type OptionalKeys<T> = Exclude<keyof T, RequiredKeys<T>>;
+/**
+ * Extracts the keys from a type that are not readonly.
+ */
 declare type ReadonlyKeys<T> = Extract<{
     [K in keyof T]-?: ReadonlyEquivalent<{
         [_K in K]: T[K];
@@ -103,27 +147,66 @@ declare type ReadonlyKeys<T> = Extract<{
         -readonly [_K in K]: T[K];
     }> extends true ? never : K;
 }[keyof T], keyof T>;
+/**
+ * Determines if two types, are equivalent in a `readonly` manner.
+ */
 declare type ReadonlyEquivalent<X, Y> = Extends<(<T>() => T extends X ? true : false), (<T>() => T extends Y ? true : false)>;
-/** Returns true if `L extends R`. Explicitly checks for `never` since that can give unexpected results. */
+/**
+ * Checks if one type extends another.
+ */
 declare type Extends<L, R> = IsNever<L> extends true ? IsNever<R> : [L] extends [R] ? true : false;
 declare type ExtendsUsingBranding<L, R> = Extends<DeepBrand<L>, DeepBrand<R>>;
 declare type ExtendsExcludingAnyOrNever<L, R> = IsAny<L> extends true ? IsAny<R> : Extends<L, R>;
+/**
+ * Checks if two types are strictly equal using
+ * the TypeScript internal identical-to operator.
+ *
+ * @see {@link https://github.com/microsoft/TypeScript/issues/55188#issuecomment-1656328122 much history}
+ */
 declare type StrictEqualUsingTSInternalIdenticalToOperator<L, R> = (<T>() => T extends (L & T) | T ? true : false) extends <T>() => T extends (R & T) | T ? true : false ? IsNever<L> extends IsNever<R> ? true : false : false;
+/**
+ * Checks if two types are strictly equal using branding.
+ */
 declare type StrictEqualUsingBranding<Left, Right> = And<[
     ExtendsUsingBranding<Left, Right>,
     ExtendsUsingBranding<Right, Left>
 ]>;
-declare type Params<Actual> = Actual extends (...args: infer P) => any ? P : never;
+/**
+ * Extracts the parameter types from a function type.
+ */
+declare type Params<Actual> = Actual extends (...args: infer ParameterTypes) => any ? ParameterTypes : never;
+/**
+ * Represents the constructor parameters of a class or constructor function.
+ * If the constructor takes no arguments, an empty array is returned.
+ */
 declare type ConstructorParams<Actual> = Actual extends new (...args: infer P) => any ? Actual extends new () => any ? P | [] : P : never;
 declare const mismatch: unique symbol;
 declare type Mismatch = {
     [mismatch]: 'mismatch';
 };
-/** A type which should match anything passed as a value but *doesn't* match `Mismatch` - helps TypeScript select the right overload for `toEqualTypeOf` and `toMatchTypeOf`. */
+/**
+ * A type which should match anything passed as a value but *doesn't*
+ * match {@linkcode Mismatch}. It helps TypeScript select the right overload
+ * for {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`} and
+ * {@linkcode PositiveExpectTypeOf.toMatchTypeOf `.toMatchTypeOf()`}.
+ */
 declare const avalue: unique symbol;
+/**
+ * Represents a value that can be of various types.
+ */
 declare type AValue = {
     [avalue]?: undefined;
 } | string | number | boolean | symbol | bigint | null | undefined | void;
+/**
+ * Represents the type of mismatched arguments between
+ * the actual result and the expected result.
+ *
+ * If {@linkcode ActualResult} and {@linkcode ExpectedResult} are equivalent,
+ * the type resolves to an empty tuple `[]`, indicating no mismatch.
+ * If they are not equivalent, it resolves to a tuple containing the element
+ * {@linkcode Mismatch}, signifying a discrepancy between
+ * the expected and actual results.
+ */
 declare type MismatchArgs<ActualResult extends boolean, ExpectedResult extends boolean> = Eq<ActualResult, ExpectedResult> extends true ? [] : [Mismatch];
 declare const inverted: unique symbol;
 declare type Inverted<T> = {
@@ -199,85 +282,746 @@ declare type ExpectNullable<T> = {
     [expectNullable]: T;
     result: Not<StrictEqualUsingBranding<T, NonNullable<T>>>;
 };
+/**
+ * Represents a scolder function that checks if the result of an expecter
+ * matches the specified options.
+ */
 declare type Scolder<Expecter extends {
     result: boolean;
 }, Options extends {
     positive: boolean;
 }> = Expecter['result'] extends Options['positive'] ? () => true : Options['positive'] extends true ? Expecter : Inverted<Expecter>;
+/**
+ * Represents the positive assertion methods available for type checking in the
+ * {@linkcode expectTypeOf()} utility.
+ */
 interface PositiveExpectTypeOf<Actual> extends BaseExpectTypeOf<Actual, {
     positive: true;
     branded: false;
 }> {
     toEqualTypeOf: {
+        /**
+         * Uses TypeScript's internal technique to check for type "identicalness".
+         *
+         * It will check if the types are fully equal to each other.
+         * It will not fail if two objects have different values, but the same type.
+         * It will fail however if an object is missing a property.
+         *
+         * **_Unexpected failure_**? For a more permissive but less performant
+         * check that accommodates for equivalent intersection types,
+         * use {@linkcode branded `.branded.toEqualTypeOf()`}.
+         * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
+         *
+         * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
+         *
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
+         * ```
+         *
+         * @param value - The value to compare against the expected type.
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected extends StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
         ...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, true>): true;
+        /**
+         * Uses TypeScript's internal technique to check for type "identicalness".
+         *
+         * It will check if the types are fully equal to each other.
+         * It will not fail if two objects have different values, but the same type.
+         * It will fail however if an object is missing a property.
+         *
+         * **_Unexpected failure_**? For a more permissive but less performant
+         * check that accommodates for equivalent intersection types,
+         * use {@linkcode branded `.branded.toEqualTypeOf()`}.
+         * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
+         *
+         * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
+         *
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
+         * ```
+         *
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected extends StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, true>): true;
     };
     toMatchTypeOf: {
+        /**
+         * A less strict version of {@linkcode toEqualTypeOf `.toEqualTypeOf()`}
+         * that allows for extra properties.
+         * This is roughly equivalent to an `extends` constraint
+         * in a function type argument.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
+         * ```
+         *
+         * @param value - The value to compare against the expected type.
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected extends Extends<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
         ...MISMATCH: MismatchArgs<Extends<Actual, Expected>, true>): true;
+        /**
+         * A less strict version of {@linkcode toEqualTypeOf `.toEqualTypeOf()`}
+         * that allows for extra properties.
+         * This is roughly equivalent to an `extends` constraint
+         * in a function type argument.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
+         * ```
+         *
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected extends Extends<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<Extends<Actual, Expected>, true>): true;
     };
-    toHaveProperty: <K extends keyof Actual>(key: K, ...MISMATCH: MismatchArgs<Extends<K, keyof Actual>, true>) => K extends keyof Actual ? PositiveExpectTypeOf<Actual[K]> : true;
+    /**
+     * Checks whether an object has a given property.
+     *
+     * @example
+     * <caption>check that properties exist</caption>
+     * ```ts
+     * const obj = {a: 1, b: ''}
+     *
+     * expectTypeOf(obj).toHaveProperty('a')
+     *
+     * expectTypeOf(obj).not.toHaveProperty('c')
+     * ```
+     *
+     * @param key - The property key to check for.
+     * @param MISMATCH - The mismatch arguments.
+     * @returns `true`.
+     */
+    toHaveProperty: <KeyType extends keyof Actual>(key: KeyType, ...MISMATCH: MismatchArgs<Extends<KeyType, keyof Actual>, true>) => KeyType extends keyof Actual ? PositiveExpectTypeOf<Actual[KeyType]> : true;
+    /**
+     * Inverts the result of the following assertions.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf({ a: 1 }).not.toMatchTypeOf({ b: 1 })
+     * ```
+     */
     not: NegativeExpectTypeOf<Actual>;
+    /**
+     * Intersection types can cause issues with
+     * {@linkcode toEqualTypeOf `.toEqualTypeOf()`}:
+     * ```ts
+     * // ❌ The following line doesn't compile, even though the types are arguably the same.
+     * expectTypeOf<{ a: 1 } & { b: 2 }>().toEqualTypeOf<{ a: 1; b: 2 }>()
+     * ```
+     * This helper works around this problem by using
+     * a more permissive but less performant check.
+     *
+     * __Note__: This comes at a performance cost, and can cause the compiler
+     * to 'give up' if used with excessively deep types, so use sparingly.
+     *
+     * @see {@link https://github.com/mmkal/expect-type/pull/21 Reference}
+     */
     branded: {
+        /**
+         * Uses TypeScript's internal technique to check for type "identicalness".
+         *
+         * It will check if the types are fully equal to each other.
+         * It will not fail if two objects have different values, but the same type.
+         * It will fail however if an object is missing a property.
+         *
+         * **_Unexpected failure_**? For a more permissive but less performant
+         * check that accommodates for equivalent intersection types,
+         * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
+         * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
+         *
+         * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
+         *
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
+         * ```
+         *
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         toEqualTypeOf: <Expected extends StrictEqualUsingBranding<Actual, Expected> extends true ? unknown : MismatchInfo<Actual, Expected>>(...MISMATCH: MismatchArgs<StrictEqualUsingBranding<Actual, Expected>, true>) => true;
     };
 }
+/**
+ * Represents the negative expectation type for the {@linkcode Actual} type.
+ */
 interface NegativeExpectTypeOf<Actual> extends BaseExpectTypeOf<Actual, {
     positive: false;
 }> {
     toEqualTypeOf: {
+        /**
+         * Uses TypeScript's internal technique to check for type "identicalness".
+         *
+         * It will check if the types are fully equal to each other.
+         * It will not fail if two objects have different values, but the same type.
+         * It will fail however if an object is missing a property.
+         *
+         * **_Unexpected failure_**? For a more permissive but less performant
+         * check that accommodates for equivalent intersection types,
+         * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
+         * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
+         *
+         * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
+         *
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
+         * ```
+         *
+         * @param value - The value to compare against the expected type.
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected>(value: Expected & AValue, ...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, false>): true;
+        /**
+         * Uses TypeScript's internal technique to check for type "identicalness".
+         *
+         * It will check if the types are fully equal to each other.
+         * It will not fail if two objects have different values, but the same type.
+         * It will fail however if an object is missing a property.
+         *
+         * **_Unexpected failure_**? For a more permissive but less performant
+         * check that accommodates for equivalent intersection types,
+         * use {@linkcode PositiveExpectTypeOf.branded `.branded.toEqualTypeOf()`}.
+         * @see {@link https://github.com/mmkal/expect-type#why-is-my-assertion-failing The documentation for details}.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: number }>()
+         *
+         * expectTypeOf({ a: 1, b: 1 }).not.toEqualTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 1 })
+         *
+         * expectTypeOf({ a: 1 }).toEqualTypeOf({ a: 2 })
+         * ```
+         *
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected>(...MISMATCH: MismatchArgs<StrictEqualUsingTSInternalIdenticalToOperator<Actual, Expected>, false>): true;
     };
     toMatchTypeOf: {
+        /**
+         * A less strict version of
+         * {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`}
+         * that allows for extra properties.
+         * This is roughly equivalent to an `extends` constraint
+         * in a function type argument.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
+         * ```
+         *
+         * @param value - The value to compare against the expected type.
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected>(value: Expected & AValue, // reason for `& AValue`: make sure this is only the selected overload when the end-user passes a value for an inferred typearg. The `Mismatch` type does match `AValue`.
         ...MISMATCH: MismatchArgs<Extends<Actual, Expected>, false>): true;
+        /**
+         * A less strict version of
+         * {@linkcode PositiveExpectTypeOf.toEqualTypeOf `.toEqualTypeOf()`}
+         * that allows for extra properties.
+         * This is roughly equivalent to an `extends` constraint
+         * in a function type argument.
+         *
+         * @example
+         * <caption>Using generic type argument syntax</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf<{ a: number }>()
+         * ```
+         *
+         * @example
+         * <caption>Using inferred type syntax by passing a value</caption>
+         * ```ts
+         * expectTypeOf({ a: 1, b: 1 }).toMatchTypeOf({ a: 2 })
+         * ```
+         *
+         * @param MISMATCH - The mismatch arguments.
+         * @returns `true`.
+         */
         <Expected>(...MISMATCH: MismatchArgs<Extends<Actual, Expected>, false>): true;
     };
-    toHaveProperty: <K extends string | number | symbol>(key: K, ...MISMATCH: MismatchArgs<Extends<K, keyof Actual>, false>) => true;
+    /**
+     * Checks whether an object has a given property.
+     *
+     * @example
+     * <caption>check that properties exist</caption>
+     * ```ts
+     * const obj = {a: 1, b: ''}
+     *
+     * expectTypeOf(obj).toHaveProperty('a')
+     *
+     * expectTypeOf(obj).not.toHaveProperty('c')
+     * ```
+     *
+     * @param key - The property key to check for.
+     * @param MISMATCH - The mismatch arguments.
+     * @returns `true`.
+     */
+    toHaveProperty: <KeyType extends string | number | symbol>(key: KeyType, ...MISMATCH: MismatchArgs<Extends<KeyType, keyof Actual>, false>) => true;
 }
+/**
+ * Represents a conditional type that selects either
+ * {@linkcode PositiveExpectTypeOf} or {@linkcode NegativeExpectTypeOf} based
+ * on the value of the `positive` property in the {@linkcode Options} type.
+ */
 declare type ExpectTypeOf<Actual, Options extends {
     positive: boolean;
 }> = Options['positive'] extends true ? PositiveExpectTypeOf<Actual> : NegativeExpectTypeOf<Actual>;
+/**
+ * Represents the base interface for the
+ * {@linkcode expectTypeOf()} function.
+ * Provides a set of assertion methods to perform type checks on a value.
+ */
 interface BaseExpectTypeOf<Actual, Options extends {
     positive: boolean;
 }> {
+    /**
+     * Checks whether the type of the value is `any`.
+     */
     toBeAny: Scolder<ExpectAny<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `unknown`.
+     */
     toBeUnknown: Scolder<ExpectUnknown<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `never`.
+     */
     toBeNever: Scolder<ExpectNever<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `function`.
+     */
     toBeFunction: Scolder<ExpectFunction<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `object`.
+     */
     toBeObject: Scolder<ExpectObject<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is an {@linkcode Array}.
+     */
     toBeArray: Scolder<ExpectArray<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `number`.
+     */
     toBeNumber: Scolder<ExpectNumber<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `string`.
+     */
     toBeString: Scolder<ExpectString<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `boolean`.
+     */
     toBeBoolean: Scolder<ExpectBoolean<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `void`.
+     */
     toBeVoid: Scolder<ExpectVoid<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `symbol`.
+     */
     toBeSymbol: Scolder<ExpectSymbol<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `null`.
+     */
     toBeNull: Scolder<ExpectNull<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `undefined`.
+     */
     toBeUndefined: Scolder<ExpectUndefined<Actual>, Options>;
+    /**
+     * Checks whether the type of the value is `null` or `undefined`.
+     */
     toBeNullable: Scolder<ExpectNullable<Actual>, Options>;
+    /**
+     * Checks whether a function is callable with the given parameters.
+     *
+     * __Note__: You cannot negate this assertion with
+     * {@linkcode PositiveExpectTypeOf.not `.not`} you need to use
+     * `ts-expect-error` instead.
+     *
+     * @example
+     * ```ts
+     * const f = (a: number) => [a, a]
+     *
+     * expectTypeOf(f).toBeCallableWith(1)
+     * ```
+     *
+     * __Known Limitation__: This assertion will likely fail if you try to use it
+     * with a generic function or an overload.
+     * @see {@link https://github.com/mmkal/expect-type/issues/50 This issue} for an example and a workaround.
+     *
+     * @param args - The arguments to check for callability.
+     * @returns `true`.
+     */
     toBeCallableWith: Options['positive'] extends true ? (...args: Params<Actual>) => true : never;
+    /**
+     * Checks whether a class is constructible with the given parameters.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf(Date).toBeConstructibleWith('1970')
+     *
+     * expectTypeOf(Date).toBeConstructibleWith(0)
+     *
+     * expectTypeOf(Date).toBeConstructibleWith(new Date())
+     *
+     * expectTypeOf(Date).toBeConstructibleWith()
+     * ```
+     *
+     * @param args - The arguments to check for constructibility.
+     * @returns `true`.
+     */
     toBeConstructibleWith: Options['positive'] extends true ? (...args: ConstructorParams<Actual>) => true : never;
+    /**
+     * Equivalent to the {@linkcode Extract} utility type.
+     * Helps narrow down complex union types.
+     *
+     * @example
+     * ```ts
+     * type ResponsiveProp<T> = T | T[] | { xs?: T; sm?: T; md?: T }
+     *
+     * interface CSSProperties {
+     *   margin?: string
+     *   padding?: string
+     * }
+     *
+     * function getResponsiveProp<T>(_props: T): ResponsiveProp<T> {
+     *   return {}
+     * }
+     *
+     * const cssProperties: CSSProperties = { margin: '1px', padding: '2px' }
+     *
+     * expectTypeOf(getResponsiveProp(cssProperties))
+     *   .extract<{ xs?: any }>() // extracts the last type from a union
+     *   .toEqualTypeOf<{
+     *     xs?: CSSProperties
+     *     sm?: CSSProperties
+     *     md?: CSSProperties
+     *   }>()
+     *
+     * expectTypeOf(getResponsiveProp(cssProperties))
+     *   .extract<unknown[]>() // extracts an array from a union
+     *   .toEqualTypeOf<CSSProperties[]>()
+     * ```
+     *
+     * __Note__: If no type is found in the union, it will return `never`.
+     *
+     * @param v - The type to extract from the union.
+     * @returns The type after extracting the type from the union.
+     */
     extract: <V>(v?: V) => ExpectTypeOf<Extract<Actual, V>, Options>;
+    /**
+     * Equivalent to the {@linkcode Exclude} utility type.
+     * Removes types from a union.
+     *
+     * @example
+     * ```ts
+     * type ResponsiveProp<T> = T | T[] | { xs?: T; sm?: T; md?: T }
+     *
+     * interface CSSProperties {
+     *   margin?: string
+     *   padding?: string
+     * }
+     *
+     * function getResponsiveProp<T>(_props: T): ResponsiveProp<T> {
+     *   return {}
+     * }
+     *
+     * const cssProperties: CSSProperties = { margin: '1px', padding: '2px' }
+     *
+     * expectTypeOf(getResponsiveProp(cssProperties))
+     *   .exclude<unknown[]>()
+     *   .exclude<{ xs?: unknown }>() // or just `.exclude<unknown[] | { xs?: unknown }>()`
+     *   .toEqualTypeOf<CSSProperties>()
+     * ```
+     */
     exclude: <V>(v?: V) => ExpectTypeOf<Exclude<Actual, V>, Options>;
-    parameter: <K extends keyof Params<Actual>>(number: K) => ExpectTypeOf<Params<Actual>[K], Options>;
+    /**
+     * Equivalent to the {@linkcode Pick} utility type.
+     * Helps select a subset of properties from an object type.
+     *
+     * @example
+     * ```ts
+     * interface Person {
+     *   name: string
+     *   age: number
+     * }
+     *
+     * expectTypeOf<Person>()
+     *   .pick<'name'>()
+     *   .toEqualTypeOf<{ name: string }>()
+     * ```
+     *
+     * @param keyToPick - The property key to pick.
+     * @returns The type after picking the property.
+     */
+    pick: <KeyToPick extends keyof Actual>(keyToPick?: KeyToPick) => ExpectTypeOf<Pick<Actual, KeyToPick>, Options>;
+    /**
+     * Equivalent to the {@linkcode Omit} utility type.
+     * Helps remove a subset of properties from an object type.
+     *
+     * @example
+     * ```ts
+     * interface Person {
+     *   name: string
+     *   age: number
+     * }
+     *
+     * expectTypeOf<Person>().omit<'name'>().toEqualTypeOf<{ age: number }>()
+     * ```
+     *
+     * @param keyToOmit - The property key to omit.
+     * @returns The type after omitting the property.
+     */
+    omit: <KeyToOmit extends keyof Actual | (PropertyKey & Record<never, never>)>(keyToOmit?: KeyToOmit) => ExpectTypeOf<Omit<Actual, KeyToOmit>, Options>;
+    /**
+     * Extracts a certain function argument with `.parameter(number)` call to
+     * perform other assertions on it.
+     *
+     * @example
+     * ```ts
+     * function foo(a: number, b: string) {
+     *   return [a, b]
+     * }
+     *
+     * expectTypeOf(foo).parameter(0).toBeNumber()
+     *
+     * expectTypeOf(foo).parameter(1).toBeString()
+     * ```
+     *
+     * @param index - The index of the parameter to extract.
+     * @returns The extracted parameter type.
+     */
+    parameter: <Index extends keyof Params<Actual>>(index: Index) => ExpectTypeOf<Params<Actual>[Index], Options>;
+    /**
+     * Equivalent to the {@linkcode Parameters} utility type.
+     * Extracts function parameters to perform assertions on its value.
+     * Parameters are returned as an array.
+     *
+     * @example
+     * ```ts
+     * function noParam() {}
+     *
+     * function hasParam(s: string) {}
+     *
+     * expectTypeOf(noParam).parameters.toEqualTypeOf<[]>()
+     *
+     * expectTypeOf(hasParam).parameters.toEqualTypeOf<[string]>()
+     * ```
+     */
     parameters: ExpectTypeOf<Params<Actual>, Options>;
+    /**
+     * Equivalent to the {@linkcode ConstructorParameters} utility type.
+     * Extracts constructor parameters as an array of values and
+     * perform assertions on them with this method.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf(Date).constructorParameters.toEqualTypeOf<
+     *   [] | [string | number | Date]
+     * >()
+     * ```
+     */
     constructorParameters: ExpectTypeOf<ConstructorParams<Actual>, Options>;
+    /**
+     * Equivalent to the {@linkcode ThisParameterType} utility type.
+     * Extracts the `this` parameter of a function to
+     * perform assertions on its value.
+     *
+     * @example
+     * ```ts
+     * function greet(this: { name: string }, message: string) {
+     *   return `Hello ${this.name}, here's your message: ${message}`
+     * }
+     *
+     * expectTypeOf(greet).thisParameter.toEqualTypeOf<{ name: string }>()
+     * ```
+     */
     thisParameter: ExpectTypeOf<ThisParameterType<Actual>, Options>;
+    /**
+     * Equivalent to the {@linkcode InstanceType} utility type.
+     * Extracts the instance type of a class to perform assertions on.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf(Date).instance.toHaveProperty('toISOString')
+     * ```
+     */
     instance: Actual extends new (...args: any[]) => infer I ? ExpectTypeOf<I, Options> : never;
+    /**
+     * Equivalent to the {@linkcode ReturnType} utility type.
+     * Extracts the return type of a function.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf(() => {}).returns.toBeVoid()
+     *
+     * expectTypeOf((a: number) => [a, a]).returns.toEqualTypeOf([1, 2])
+     * ```
+     */
     returns: Actual extends (...args: any[]) => infer R ? ExpectTypeOf<R, Options> : never;
-    resolves: Actual extends PromiseLike<infer R> ? ExpectTypeOf<R, Options> : never;
-    items: Actual extends ArrayLike<infer R> ? ExpectTypeOf<R, Options> : never;
+    /**
+     * Extracts resolved value of a Promise,
+     * so you can perform other assertions on it.
+     *
+     * @example
+     * ```ts
+     * async function asyncFunc() {
+     *   return 123
+     * }
+     *
+     * expectTypeOf(asyncFunc).returns.resolves.toBeNumber()
+     *
+     * expectTypeOf(Promise.resolve('string')).resolves.toBeString()
+     * ```
+     *
+     * Type Equivalent:
+     * ```ts
+     * type Resolves<PromiseType> = PromiseType extends PromiseLike<infer ResolvedType>
+     *   ? ResolvedType
+     *   : never
+     * ```
+     */
+    resolves: Actual extends PromiseLike<infer ResolvedType> ? ExpectTypeOf<ResolvedType, Options> : never;
+    /**
+     * Extracts array item type to perform assertions on.
+     *
+     * @example
+     * ```ts
+     * expectTypeOf([1, 2, 3]).items.toEqualTypeOf<number>()
+     *
+     * expectTypeOf([1, 2, 3]).items.not.toEqualTypeOf<string>()
+     * ```
+     *
+     * __Type Equivalent__:
+     * ```ts
+     * type Items<ArrayType> = ArrayType extends ArrayLike<infer ItemType>
+     *   ? ItemType
+     *   : never
+     * ```
+     */
+    items: Actual extends ArrayLike<infer ItemType> ? ExpectTypeOf<ItemType, Options> : never;
+    /**
+     * Extracts the type guarded by a function to perform assertions on.
+     *
+     * @example
+     * ```ts
+     * function isString(v: any): v is string {
+     *   return typeof v === 'string'
+     * }
+     *
+     * expectTypeOf(isString).guards.toBeString()
+     * ```
+     */
     guards: Actual extends (v: any, ...args: any[]) => v is infer T ? ExpectTypeOf<T, Options> : never;
+    /**
+     * Extracts the type asserted by a function to perform assertions on.
+     *
+     * @example
+     * ```ts
+     * function assertNumber(v: any): asserts v is number {
+     *   if (typeof v !== 'number')
+     *     throw new TypeError('Nope !')
+     * }
+     *
+     * expectTypeOf(assertNumber).asserts.toBeNumber()
+     * ```
+     */
     asserts: Actual extends (v: any, ...args: any[]) => asserts v is infer T ? unknown extends T ? never : ExpectTypeOf<T, Options> : never;
 }
+/**
+ * Represents a function that allows asserting the expected type of a value.
+ */
 declare type _ExpectTypeOf = {
+    /**
+     * Asserts the expected type of a value.
+     *
+     * @param actual - The actual value being asserted.
+     * @returns An object representing the expected type assertion.
+     */
     <Actual>(actual: Actual): ExpectTypeOf<Actual, {
         positive: true;
         branded: false;
     }>;
+    /**
+     * Asserts the expected type of a value without providing an actual value.
+     *
+     * @returns An object representing the expected type assertion.
+     */
     <Actual>(): ExpectTypeOf<Actual, {
         positive: true;
         branded: false;
@@ -519,14 +1263,16 @@ interface VitestUtils {
      * @param path Path to the module. Can be aliased, if your Vitest config supports it
      * @param factory Mocked module factory. The result of this function will be an exports object
      */
-    mock: (path: string, factory?: MockFactoryWithHelper) => void;
+    mock(path: string, factory?: MockFactoryWithHelper): void;
+    mock<T>(module: Promise<T>, factory?: MockFactoryWithHelper<T>): void;
     /**
      * Removes module from mocked registry. All calls to import will return the original module even if it was mocked before.
      *
      * This call is hoisted to the top of the file, so it will only unmock modules that were defined in `setupFiles`, for example.
      * @param path Path to the module. Can be aliased, if your Vitest config supports it
      */
-    unmock: (path: string) => void;
+    unmock(path: string): void;
+    unmock(module: Promise<unknown>): void;
     /**
      * Mocks every subsequent [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) call.
      *
@@ -536,14 +1282,16 @@ interface VitestUtils {
      * @param path Path to the module. Can be aliased, if your Vitest config supports it
      * @param factory Mocked module factory. The result of this function will be an exports object
      */
-    doMock: (path: string, factory?: MockFactoryWithHelper) => void;
+    doMock(path: string, factory?: MockFactoryWithHelper): void;
+    doMock<T>(module: Promise<T>, factory?: MockFactoryWithHelper<T>): void;
     /**
      * Removes module from mocked registry. All subsequent calls to import will return original module.
      *
      * Unlike [`vi.unmock`](https://vitest.dev/api/vi#vi-unmock), this method is not hoisted to the top of the file.
      * @param path Path to the module. Can be aliased, if your Vitest config supports it
      */
-    doUnmock: (path: string) => void;
+    doUnmock(path: string): void;
+    doUnmock(module: Promise<unknown>): void;
     /**
      * Imports module, bypassing all checks if it should be mocked.
      * Can be useful if you want to mock module partially.