prostub 1.1.0 → 1.2.0

package/index.d.ts

@@ -1,24 +1,19 @@
-interface Type<T extends object> {
-    new (...args: never[]): T;
-    prototype: T;
-}
-
 declare const mock$1: unique symbol;
 declare const stub$1: unique symbol;
 
-interface InvocationRecord<TArgs extends Array<unknown>, TReturn> {
+interface InteractionRecord {
+    time: bigint;
+}
+interface InvocationRecord<TArgs extends Array<unknown>, TReturn> extends InteractionRecord {
     args: TArgs;
     returnValue?: TReturn;
-    invocationTime: Date;
     exception?: unknown;
 }
-interface AssignmentRecord<TValue> {
+interface AssignmentRecord<TValue> extends InteractionRecord {
     newValue: TValue;
-    assignmentTime: Date;
 }
-interface ReadRecord<TValue> {
+interface ReadRecord<TValue> extends InteractionRecord {
     value: TValue;
-    readTime: Date;
 }
 interface FunctionStub<TThis extends object, TKey extends keyof TThis, TArgs extends Array<unknown>, TReturn> {
     [stub$1]: {
@@ -31,84 +26,221 @@ interface PropertyStubMetadata<TValue> {
     reads: Array<ReadRecord<TValue>>;
     assignments: Array<AssignmentRecord<TValue>>;
 }
-type FunctionStubMetadata<TArgs extends Array<unknown>, TReturn> = {
+interface FunctionStubMetadata<TArgs extends Array<unknown>, TReturn> {
     calls: Array<InvocationRecord<TArgs, TReturn>>;
-};
+}
 interface PropertyStub<TThis extends object, TKey extends keyof TThis> {
     [stub$1]: {
+        metadata: PropertyStubMetadata<TThis[TKey]>;
         type: "property";
         get(thisArg: TThis, propertyName: TKey): TThis[TKey];
         set(thisArg: TThis, propertyName: TKey, newValue: TThis[TKey]): void;
-        metadata: {
-            reads: Array<ReadRecord<TThis[TKey]>>;
-            assignments: Array<AssignmentRecord<TThis[TKey]>>;
-        };
     };
 }
 type Stubbable<T extends object> = {
     -readonly [K in keyof T]: Stub<T, K>;
 };
 type Stub<TThis extends object, TKey extends keyof TThis> = TThis[TKey] extends (...args: infer TArgs) => infer TReturn ? FunctionStub<TThis, TKey, TArgs, TReturn> : PropertyStub<TThis, TKey>;
-type Mock<T extends Object> = T & {
+type Mock<T extends object> = T & {
     [mock$1]: {
         stubs: {
-            -readonly [TKey in keyof T]?: Stub<T, TKey>;
+            -readonly [TKey in keyof T]: Stub<T, TKey>;
         };
     };
 };
 
-declare function mock<const TObject extends object>(clazz: Type<TObject>): TObject & {
-    [mock$1]: {
-        stubs: { -readonly [TKey in keyof TObject]?: Stub<TObject, TKey>; };
-    };
-} & {
-    [mock$1]: {
-        stubs: TObject & {
-            [mock$1]: {
-                stubs: { -readonly [TKey_1 in keyof TObject]?: Stub<TObject, TKey_1>; };
-            };
-        } extends infer T extends object ? { -readonly [TKey in keyof T]?: Stub<T, TKey> | undefined; } : never;
-    };
-};
+interface Type<T extends object> {
+    prototype: T;
+    new (...args: Array<never>): T;
+}
 
-declare function spy<const TObject extends object>(realObject: TObject): TObject & {
-    [mock$1]: {
-        stubs: {
-            -readonly [TKey in keyof TObject]?: Stub<TObject, TKey>;
-        };
-    };
-};
+/**
+ * Creates a mock instance of the given class.
+ * @param clazz The class to mock.
+ * @returns A mock instance of the class.
+ * @example
+ * ```ts
+ * class MyClass {
+ *     myMethod() {
+ *         return "real value";
+ *     }
+ * }
+ * const myClassMock = mock(MyClass);
+ * // Now you can stub methods and properties on myClassMock as needed.
+ * ```
+ *
+ * @see {@link stub} for stubbing methods and properties on the mock.
+ * @see {@link spy} for creating spies on real instances.
+ */
+declare function mock<const TObject extends object>(clazz: Type<TObject>): Mock<TObject>;
 
-declare function stub<const TObject extends object>(mockOrSpy: TObject & {
-    [mock$1]: {
-        stubs: {
-            -readonly [TKey in keyof TObject]?: Stub<TObject, TKey>;
-        };
-    };
-}): Stubbable<TObject>;
+/**
+ * Creates a spy for the given real object. A spy wraps the real object and allows you to stub methods and properties while still calling through to the real implementations by default.
+ * @returns A mock object that wraps the real object and allows stubbing.
+ * @example
+ * ```ts
+ * class MyClass {
+ *     myMethod() {
+ *         return "real value";
+ *     }
+ * }
+ * const myRealInstance = new MyClass();
+ * const mySpy = spy(myRealInstance);
+ * // Now you can stub methods and properties on mySpy as needed.
+ * ```
+ *
+ * @see {@link stub} for stubbing methods and properties on the spy.
+ * @see {@link mock} for creating mock instances of classes.
+ * @param realObject The real object to create a spy for.
+ */
+declare function spy<const TObject extends object>(realObject: TObject): Mock<TObject>;
+
+/**
+ * Creates a {@link Stubbable} for the given mock or spy. The returned object allows you to define stubs for methods and properties on the mock or spy.
+ * @returns A stubbable object for defining stubs on the mock or spy.
+ * @example
+ * ```ts
+ * const myMock = mock(MyClass);
+ * const myStubs = stub(myMock);
+ * myStubs.myMethod = returnFixed("stubbed value");
+ * myStubs.myProperty = fixedValue(42);
+ * ```
+ *
+ * @see {@link mock} for creating mock instances of classes.
+ * @see {@link spy} for creating spies on real instances.
+ * @param mockOrSpy The mock or spy to create stubs for. Must be created using the `mock` or `spy` functions.
+ */
+declare function stub<const TObject extends object>(mockOrSpy: Mock<TObject>): Stubbable<TObject>;
 
+/**
+ * Creates a function stub that uses the provided function to generate return values or throw exceptions when invoked.
+ * It also records each invocation's arguments, return values, exceptions, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @param answerFunction - The function to be used as the stub implementation.
+ * @returns A function stub that records invocations and uses the provided function for behavior.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = answer(function(this: MyObject, arg1: number, arg2: string): boolean {
+ *     if (arg1 > 0) {
+ *         return true;
+ *     } else {
+ *         throw new Error("arg1 must be positive");
+ *     }
+ * });
+ * ```
+ */
 declare function answer<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(answerFunction: (this: TObject, ...args: TArgs) => TReturn): FunctionStub<TObject, TKey, TArgs, TReturn>;
 
+/**
+ * Creates a function stub that calls through to the original implementation of the function when invoked.
+ * It also records each invocation's arguments, return values, exceptions, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @returns A function stub that records invocations and calls through to the original implementation.
+ * @example
+ * ```ts
+ * stub(mySpyObject).someMethod = callThrough();
+ * ```
+ */
 declare function callThrough<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(): FunctionStub<TObject, TKey, TArgs, TReturn>;
 
+/**
+ * Creates a function stub that delegates its implementation to the provided delegate function.
+ * It also records each invocation's arguments, return values, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @returns A function stub that records invocations and delegates to the provided function.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = delegateTo(function(this: MyObject, arg1: number, arg2: string): boolean {
+ *     return arg1 > 0 && arg2.length > 0;
+ * });
+ * ```
+ * @param delegateFunction - The function to which calls will be delegated.
+ */
 declare function delegateTo<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(delegateFunction: (this: TObject, ...args: TArgs) => TReturn): FunctionStub<TObject, TKey, TArgs, TReturn>;
 
+/**
+ * Creates a no-operation function stub that records each invocation's arguments and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @returns A no-operation function stub that records invocations.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = noop();
+ * ```
+ */
+declare function noop<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>>(): FunctionStub<TObject, TKey, TArgs, void>;
+
+/**
+ * Creates a function stub that always returns a fixed value when invoked.
+ * It also records each invocation's arguments, return values, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @returns A function stub that always returns the specified fixed value and records invocations.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = returnFixed(42);
+ * ```
+ * @param returnValue
+ */
 declare function returnFixed<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(returnValue: TReturn): FunctionStub<TObject, TKey, TArgs, TReturn>;
 
+/**
+ * Creates a function stub that returns a series of specified values in order when invoked.
+ * Once all values have been returned, further invocations will throw an error.
+ * It also records each invocation's arguments, return values, exceptions, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @returns A function stub that returns the specified values in order and records invocations.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = returnSerial(1, 2, 3);
+ * ```
+ * @param values
+ */
 declare function returnSerial<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(...values: Array<TReturn>): FunctionStub<TObject, TKey, TArgs, TReturn>;
 
-declare function noop<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>>(): FunctionStub<TObject, TKey, TArgs, void>;
-
+/**
+ * Creates a function stub that throws an error when invoked.
+ * It also records each invocation's arguments, exceptions, and timestamps.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @returns A function stub that throws an error on invocation and records invocations.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = throwOnCall(() => new Error("method was called"));
+ * ```
+ * @param errorFactory
+ */
 declare function throwOnCall<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>>(errorFactory: () => Error): FunctionStub<TObject, TKey, TArgs, never>;
 
 type ArgumentPredicate<TArgs extends Array<unknown>> = TArgs extends [infer TFirst, ...infer TRest] ? [
     ((arg: TFirst) => boolean),
     ...ArgumentPredicate<TRest>
-] : TArgs extends [infer TSingle] ? [
-    (arg: TSingle) => boolean
-] : TArgs extends [] ? [
-] : never;
+] : TArgs extends [infer TSingle] ? [(arg: TSingle) => boolean] : TArgs extends [] ? [] : never;
 
+/**
+ * Ongoing function stub that matches specific argument predicates.
+ * It allows chaining multiple stubs with different argument matching criteria.
+ * @typeParam TThis - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ */
 declare class OngoingFunctionStub<const TThis extends object, const TKey extends keyof TThis, const TArgs extends Array<unknown>, const TReturn> implements FunctionStub<TThis, TKey, TArgs, TReturn> {
     #private;
     get [stub$1](): {
@@ -116,9 +248,27 @@ declare class OngoingFunctionStub<const TThis extends object, const TKey extends
         type: "function";
         metadata: FunctionStubMetadata<TArgs, TReturn>;
     };
-    constructor(argumentPredicates: ArgumentPredicate<TArgs>, stub: FunctionStub<TThis, TKey, TArgs, TReturn>, parentStub?: OngoingFunctionStub<TThis, TKey, TArgs, TReturn>);
+    constructor(argumentPredicates: ArgumentPredicate<TArgs>, functionStub: FunctionStub<TThis, TKey, TArgs, TReturn>, parentStub?: OngoingFunctionStub<TThis, TKey, TArgs, TReturn>);
+    /**
+     * Begins the definition of an additional function stub that matches specific argument predicates.
+     * Use the returned builder to complete the stub definition with the `then` method.
+     * @returns An ongoing function stub builder for defining the stub behavior.
+     * @typeParam TThis - The type of the object containing the function.
+     * @typeParam TKey - The key of the function within the object.
+     * @typeParam TArgs - The types of the arguments the function accepts.
+     * @typeParam TReturn - The return type of the function.
+     * @param argumentPredicates - The predicates to match the function arguments.
+     */
     when(...argumentPredicates: ArgumentPredicate<TArgs>): OngoingFunctionStubBuilder<TThis, TKey, TArgs, TReturn>;
 }
+/**
+ * Builder for defining ongoing function stubs with argument matching.
+ * Use the `then` method to complete the stub definition.
+ * @typeParam TThis - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ */
 declare class OngoingFunctionStubBuilder<const TThis extends object, const TKey extends keyof TThis, const TArgs extends Array<unknown>, const TReturn> implements FunctionStub<TThis, TKey, TArgs, TReturn> {
     #private;
     get [stub$1](): {
@@ -129,83 +279,304 @@ declare class OngoingFunctionStubBuilder<const TThis extends object, const TKey
         };
     };
     constructor(argumentPredicates: ArgumentPredicate<TArgs>, parentStub?: OngoingFunctionStub<TThis, TKey, TArgs, TReturn>);
-    then(stub: FunctionStub<TThis, TKey, TArgs, TReturn>): OngoingFunctionStub<TThis, TKey, TArgs, TReturn>;
+    /**
+     * Completes the stub definition by specifying the function stub to use when the argument predicates match.
+     * @returns An ongoing function stub that can be further extended with additional argument matching.
+     * @typeParam TThis - The type of the object containing the function.
+     * @typeParam TKey - The key of the function within the object.
+     * @typeParam TArgs - The types of the arguments the function accepts.
+     * @typeParam TReturn - The return type of the function.
+     * @param nextStub - The function stub to use when the argument predicates match.
+     */
+    then(nextStub: FunctionStub<TThis, TKey, TArgs, TReturn>): OngoingFunctionStub<TThis, TKey, TArgs, TReturn>;
 }
+/**
+ * Begins the definition of a function stub that matches specific argument predicates.
+ * Use the returned builder to complete the stub definition with the `then` method.
+ * @typeParam TObject - The type of the object containing the function.
+ * @typeParam TKey - The key of the function within the object.
+ * @typeParam TArgs - The types of the arguments the function accepts.
+ * @typeParam TReturn - The return type of the function.
+ * @returns An ongoing function stub builder for defining the stub behavior.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someMethod = when(
+ *     arg1 => arg1 > 0,
+ *     arg2 => arg2 === "test"
+ * )
+ * .then(returnValue(42))
+ * .when(
+ *     arg1 => arg1 <= 0,
+ *     arg2 => arg2 === "test"
+ * )
+ * .then(throwError(new Error("arg1 must be positive")));
+ * ```
+ * @param argumentPredicates - The predicates to match the function arguments.
+ */
 declare function when<const TObject extends object, const TKey extends keyof TObject, const TArgs extends Array<unknown>, const TReturn>(...argumentPredicates: ArgumentPredicate<TArgs>): OngoingFunctionStubBuilder<TObject, TKey, TArgs, TReturn>;
 
+/**
+ * Creates a property stub that returns a default value.
+ *
+ * The property stub will track reads and assignments to the property.
+ * @typeParam TObject - The type of the object containing the property.
+ * @typeParam TKey - The key of the property within the object.
+ * @returns A property stub that returns the specified default value and tracks reads and assignments.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someProperty = defaultValue(10);
+ * ```
+ * @param value - The default value to be returned by the property stub.
+ */
 declare function defaultValue<const TObject extends object, const TKey extends keyof TObject>(value: TObject[TKey]): PropertyStub<TObject, TKey>;
 
+/**
+ * Creates a property stub that always returns a fixed value.
+ *
+ * The property stub will track reads and assignments to the property.
+ * Attempts to set a new value will result in an error.
+ * @typeParam TThis - The type of the object containing the property.
+ * @typeParam TKey - The key of the property within the object.
+ * @returns A property stub that always returns the specified fixed value and tracks reads and assignments.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someProperty = fixedValue(10);
+ * ```
+ * @param value - The fixed value to be returned by the property stub.
+ */
 declare function fixedValue<const TThis extends object, const TKey extends keyof TThis>(value: TThis[TKey]): PropertyStub<TThis, TKey>;
 
+/**
+ * Creates a property stub that tracks reads and assignments to the property.
+ * The property stub will return the current value of the property.
+ * @typeParam TObject - The type of the object containing the property.
+ * @typeParam TKey - The key of the property within the object.
+ * @returns A property stub that tracks reads and assignments to the property.
+ * @example
+ * ```ts
+ * stub(myStubbedObject).someProperty = trackValue();
+ * ```
+ */
 declare function trackValue<const TObject extends object, const TKey extends keyof TObject>(): PropertyStub<TObject, TKey>;
 
-declare class AssignmentVerification<const TValue> {
+/**
+ * Abstract base class for verifying interactions.
+ * @typeParam TRecord The type of interaction record.
+ */
+declare abstract class InteractionVerification<TRecord extends InteractionRecord> {
+    protected readonly interactionRecord: TRecord;
+    protected constructor(record: TRecord);
+    /**
+     * Checks if this interaction occurred before another interaction.
+     * @param otherInteractionVerification - The other interaction verification to compare against.
+     */
+    wasBefore(otherInteractionVerification: InteractionVerification<InteractionRecord>): void;
+    /**
+     * Checks if this interaction occurred before a specific point in time.
+     * @param date - The point in time to compare against.
+     */
+    wasBefore(date: Date): void;
+    /**
+     * Checks if this interaction occurred after another interaction.
+     * @param otherInteractionVerification - The other interaction verification to compare against.
+     */
+    wasAfter(otherInteractionVerification: InteractionVerification<InteractionRecord>): void;
+    /**
+     * Checks if this interaction occurred after a specific point in time.
+     * @param date - The point in time to compare against.
+     */
+    wasAfter(date: Date): void;
+}
+
+declare class InvocationVerification<const TArgs extends Array<unknown>, TReturn> extends InteractionVerification<InvocationRecord<TArgs, TReturn>> {
+    constructor(call: InvocationRecord<TArgs, TReturn>);
+    /**
+     * Checks the returned value against a provided validator function.
+     * @param validator - A function that validates the returned value.
+     */
+    returned(validator: (result: TReturn) => boolean): void;
+    /**
+     * Checks the thrown exception against a provided validator function.
+     * @param validator - A function that validates the thrown exception.
+     */
+    threw(validator: (error: unknown) => boolean): void;
+    /**
+     * Checks that the invocation did not throw an exception.
+     */
+    didNotThrow(): void;
+    /**
+     * Checks the invocation arguments against provided validators.
+     * @param validators - An array of functions that validate each argument.
+     */
+    hadArguments(...validators: ArgumentPredicate<TArgs>): void;
+}
+
+/**
+ * Provides verification methods for function invocations.
+ * @typeParam TArgs - The types of the function arguments.
+ * @typeParam TReturn - The return type of the function.
+ */
+declare class FunctionVerification<const TArgs extends Array<unknown>, const TReturn> {
     #private;
+    constructor(functionStubMetadata: FunctionStubMetadata<TArgs, TReturn>);
+    /**
+     * Checks if the function was called and verifies the invocation count against a provided predicate.
+     * @param invocationCountPredicate
+     */
+    wasCalled(invocationCountPredicate?: (n: number) => boolean): void;
+    /**
+     * Checks if the function was never called.
+     */
+    wasNotCalled(): void;
+    /**
+     * Checks the number of times the function was called against an expected count.
+     * @param expectedCallCount - The expected number of times the function should have been called.
+     */
+    wasCalledTimes(expectedCallCount: number): void;
+    /**
+     * Retrieves the verification for the nth invocation of the function.
+     * @param invocationIndex
+     */
+    nthInvocation(invocationIndex: number): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Retrieves the verification for the first invocation of the function.
+     */
+    firstInvocation(): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Retrieves the verification for the last invocation of the function.
+     */
+    lastInvocation(): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Finds the first invocation that matches the provided predicate.
+     * @param predicate - A function that tests the arguments of each invocation.
+     * @deprecated Use `firstInvocationMatching` instead. This is only kept for backward compatibility.
+     */
+    invocationMatching(predicate: (...args: TArgs) => boolean): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Finds the first invocation that matches the provided predicate.
+     * @param predicate - A function that tests the recorded information of each invocation
+     */
+    firstInvocationMatching(predicate: (invocationRecord: InvocationRecord<TArgs, TReturn>) => boolean): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Finds the last invocation that matches the provided predicate.
+     * @param predicate - A function that tests the recorded information of each invocation
+     */
+    lastInvocationMatching(predicate: (invocationRecord: InvocationRecord<TArgs, TReturn>) => boolean): InvocationVerification<TArgs, TReturn>;
+    /**
+     * Finds all invocations that match the provided predicate.
+     * @param predicate - A function that tests the recorded information of each invocation
+     */
+    allInvocationsMatching(predicate: (invocationRecord: InvocationRecord<TArgs, TReturn>) => boolean): Array<InvocationVerification<TArgs, TReturn>>;
+}
+
+/**
+ * Provides verification methods for assignment interactions.
+ * @typeParam TValue The type of the value being assigned.
+ */
+declare class AssignmentVerification<const TValue> extends InteractionVerification<AssignmentRecord<TValue>> {
     constructor(assignmentRecord: AssignmentRecord<TValue>);
-    wasBefore(otherAssignment: AssignmentVerification<TValue>): void;
-    wasAfter(otherAssignment: AssignmentVerification<TValue>): void;
+    /**
+     * Checks if the assigned value satisfies the provided validator function.
+     * @param validator - A function that validates the assigned value.
+     */
     hasValue(validator: (result: TValue) => boolean): void;
 }
 
-declare class ReadVerification<const TValue> {
-    #private;
+/**
+ * Verification class for read interactions.
+ * @typeParam TValue The type of the value being read.
+ */
+declare class ReadVerification<const TValue> extends InteractionVerification<ReadRecord<TValue>> {
     constructor(read: ReadRecord<TValue>);
-    wasBefore(otherRead: ReadVerification<TValue>): void;
-    wasAfter(otherRead: ReadVerification<TValue>): void;
+    /**
+     * Checks the read value against a provided validator function.
+     * @param validator
+     */
     hadValue(validator: (result: TValue) => boolean): void;
 }
 
+/**
+ * Provides verification methods for a spied or mocked property's interactions.
+ */
 declare class PropertyVerification<const TValue> {
     #private;
     constructor(propertyStubMetadata: PropertyStubMetadata<TValue>);
+    /**
+     * Checks the number of occurred reads against a fixed number.
+     * @param expectedGetCallCount How many reads are expected to have occurred
+     */
     wasReadNTimes(expectedGetCallCount?: number): void;
-    wasRead(): void;
+    /**
+     * Checks the number of occurred reads against a predicate function.
+     * @param readCountPredicate A predicate function that checks if the number of occurred reads matches the expectation
+     */
+    wasRead(readCountPredicate?: (n: number) => boolean): void;
+    /**
+     * Checks the number of occurred assignments against a predicate function.
+     * @param writeCountPredicate A predicate function that checks if the number of occurred assignments matches the expectation
+     */
+    wasAssigned(writeCountPredicate?: (n: number) => boolean): void;
+    /**
+     * Checks if the property has never been assigned.
+     */
     wasNotAssigned(): void;
+    /**
+     * Checks if the property has never been read.
+     */
     wasNotRead(): void;
+    /**
+     * Checks the number of occurred assignments against a fixed number.
+     * @param expectedSetCallCount How many assignments are expected to have occurred
+     */
     wasAssignedNTimes(expectedSetCallCount?: number): void;
-    wasAssigned(): void;
+    /**
+     * Gets the nth assignment verification.
+     * @param index The zero-based index of the assignment to retrieve
+     */
     nthAssignment(index: number): AssignmentVerification<TValue>;
+    /**
+     * Gets the first assignment verification.
+     */
     firstAssignment(): AssignmentVerification<TValue>;
+    /**
+     * Gets the last assignment verification.
+     */
     lastAssignment(): AssignmentVerification<TValue>;
+    /**
+     * Gets the first read verification.
+     */
     firstRead(): ReadVerification<TValue>;
+    /**
+     * Gets the last read verification.
+     */
     lastRead(): ReadVerification<TValue>;
+    /**
+     * Gets the nth read verification.
+     * @param index The zero-based index of the read to retrieve
+     */
     nthRead(index: number): ReadVerification<TValue>;
 }
 
-declare class InvocationVerification<const TArgs extends Array<unknown>, TReturn> {
-    #private;
-    constructor(call: InvocationRecord<TArgs, TReturn>);
-    wasBefore(otherInvocation: InvocationVerification<TArgs, TReturn>): void;
-    wasAfter(otherInvocation: InvocationVerification<TArgs, TReturn>): void;
-    returned(validator: (result: TReturn) => boolean): void;
-    threw(validator: (error: unknown) => boolean): void;
-    didNotThrow(): void;
-    hadArguments(...validators: ArgumentPredicate<TArgs>): void;
-}
-
-declare class FunctionVerification<const TArgs extends Array<unknown>, TReturn> {
-    #private;
-    constructor(functionStubMetadata: FunctionStubMetadata<TArgs, TReturn>);
-    wasCalled(): void;
-    wasNotCalled(): void;
-    wasCalledTimes(expectedCallCount: number): void;
-    nthInvocation(invocationIndex: number): InvocationVerification<TArgs, TReturn>;
-    firstInvocation(): InvocationVerification<TArgs, TReturn>;
-    lastInvocation(): InvocationVerification<TArgs, TReturn>;
-    invocationMatching(predicate: (...args: TArgs) => boolean): InvocationVerification<TArgs, TReturn>;
-}
-
-type Verifiable<T> = {
+type Verification<T> = {
     readonly [TKey in keyof T]: T[TKey] extends (...args: infer TArgs) => infer TReturn ? FunctionVerification<TArgs, TReturn> : PropertyVerification<T[TKey]>;
 };
 
-declare function verify<const TObject extends object>(mockOrSpy: TObject & {
-    [mock$1]: {
-        stubs: {
-            -readonly [TKey in keyof TObject]?: Stub<TObject, TKey>;
-        };
-    };
-}): Verifiable<TObject>;
+/**
+ * starts a stub verification. The Verification API always follows the pattern `verify(<mockOrSpy>).<member>.<verification>`.
+ * @param mockOrSpy
+ * @returns A proxy that provides access to the verification API for the specified mock or spy.
+ * @example
+ * ```ts
+ * verify(myMock).someMethod.firstInvocation().didNotThrow();
+ * ```
+ *
+ * @see {@link FunctionVerification} for function call verifications.
+ * @see {@link PropertyVerification} for property interaction verifications.
+ * @see {@link spy} for creating spies on real instances.
+ * @see {@link mock} for creating mock instances of classes.
+ * @see {@link stub} for stubbing methods and properties on the mock.
+ */
+declare function verify<const TObject extends object>(mockOrSpy: Mock<TObject>): Verification<TObject>;
 
 export { answer, callThrough, defaultValue, delegateTo, fixedValue, mock, noop, returnFixed, returnSerial, spy, stub, throwOnCall, trackValue, verify, when };
 export type { Mock };