@plugjs/expect5 0.4.5 → 0.4.7

package/dist/expectation/matchers.d.ts

@@ -1,46 +1,59 @@
-import { Expectations, type AssertedType, type AssertionFunction, type InferMatchers } from './expectations';
+import { Expectations, type AssertedType, type AssertionFunction, type ExpectationsParent, type InferMatcher, type InferToEqual } from './expectations';
 import { type Constructor, type TypeMappings, type TypeName } from './types';
-type Matcher = (expectations: Expectations) => Expectations;
-export declare class Matchers<T = unknown> {
+type PositiveMatcherFunction = (expectations: Expectations) => Expectations;
+export declare class Matcher<T = unknown> {
     private readonly _matchers;
     readonly not: NegativeMatchers<T>;
     constructor();
-    expect(value: unknown): T;
+    expect(value: unknown, parent?: ExpectationsParent): T;
     private _push;
     /**
-     * Expects the value to be of the specified _extended_ {@link TypeName type},
-     * and (if specified) further asserts it with an {@link AssertionFunction}.
+     * Expects the value to be of the specified _extended_ {@link TypeName type}.
      *
-     * Negation: {@link NegativeMatchers.toBeA `not.toBeA(...)`}
+     * Negation: {@link NegativeExpectations.toBeA `not.toBeA(...)`}
      */
-    toBeA<Name extends TypeName, Mapped extends TypeMappings[Name], Assert extends AssertionFunction<Mapped>>(type: Name, assertion?: Assert): Matchers<AssertedType<Mapped, Assert>>;
+    toBeA<Name extends TypeName>(type: Name): Matcher<TypeMappings[Name]>;
+    /**
+      * Expects the value to be of the specified _extended_ {@link TypeName type},
+      * and further validates it with a {@link Matcher}.
+      *
+      * Negation: {@link NegativeExpectations.toBeA `not.toBeA(...)`}
+      */
+    toBeA<Name extends TypeName, Mapped extends TypeMappings[Name], Match extends Matcher>(type: Name, matcher: Match): Matcher<InferMatcher<Mapped, Match>>;
+    /**
+      * Expects the value to be of the specified _extended_ {@link TypeName type},
+      * and further asserts it with an {@link AssertionFunction}.
+      *
+      * Negation: {@link NegativeExpectations.toBeA `not.toBeA(...)`}
+      */
+    toBeA<Name extends TypeName, Mapped extends TypeMappings[Name], Assert extends AssertionFunction<Mapped>>(type: Name, assertion: Assert): Matcher<AssertedType<Mapped, Assert>>;
     /**
      * Expects the value to be a `number` within a given +/- _delta_ range of the
      * specified expected value.
      *
      * Negation: {@link NegativeMatchers.toBeCloseTo `not.toBeCloseTo(...)`}
      */
-    toBeCloseTo(value: number, delta: number): Matchers<number>;
+    toBeCloseTo(value: number, delta: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` within a given +/- _delta_ range of the
      * specified expected value.
      *
      * Negation: {@link NegativeMatchers.toBeCloseTo `not.toBeCloseTo(...)`}
      */
-    toBeCloseTo(value: bigint, delta: bigint): Matchers<bigint>;
+    toBeCloseTo(value: bigint, delta: bigint): Matcher<bigint>;
     /**
      * Expects the value to be neither `null` nor `undefined`.
      *
      * Negation: {@link NegativeMatchers.toBeDefined `not.toBeDefined()`}
      */
-    toBeDefined(): Matchers<T>;
+    toBeDefined(): Matcher<T>;
     /**
      * Expect the value to be an instance of {@link Error}.
      *
      * If specified, the {@link Error}'s own message will be further expected to
      * either match the specified {@link RegExp}, or equal the specified `string`.
      */
-    toBeError(message?: string | RegExp): Matchers<Error>;
+    toBeError(message?: string | RegExp): Matcher<Error>;
     /**
      * Expect the value to be an instance of {@link Error} and further asserts
      * it to be an instance of the specifed {@link Error} {@link Constructor}.
@@ -48,130 +61,160 @@ export declare class Matchers<T = unknown> {
      * If specified, the {@link Error}'s own message will be further expected to
      * either match the specified {@link RegExp}, or equal the specified `string`.
      */
-    toBeError<Class extends Constructor<Error>>(constructor: Class, message?: string | RegExp): Matchers<InstanceType<Class>>;
+    toBeError<Class extends Constructor<Error>>(constructor: Class, message?: string | RegExp): Matcher<InstanceType<Class>>;
     /** Expects the value strictly equal to `false`. */
-    toBeFalse(): Matchers<false>;
+    toBeFalse(): Matcher<false>;
     /**
      * Expects the value to be _falsy_ (zero, empty string, `false`, ...).
      *
-     * Negation: {@link Matchers.toBeTruthy `toBeTruthy()`}
+     * Negation: {@link Matcher.toBeTruthy `toBeTruthy()`}
      */
-    toBeFalsy(): Matchers<T>;
+    toBeFalsy(): Matcher<T>;
     /**
      * Expects the value to be a `number` greater than the specified* expected
      * value.
      *
-     * Negation: {@link Matchers.toBeLessThanOrEqual `toBeLessThanOrEqual(...)`}
+     * Negation: {@link Matcher.toBeLessThanOrEqual `toBeLessThanOrEqual(...)`}
      */
-    toBeGreaterThan(value: number): Matchers<number>;
+    toBeGreaterThan(value: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` greater than the specified expected
      * value.
      *
-     * Negation: {@link Matchers.toBeLessThanOrEqual `toBeLessThanOrEqual(...)`}
+     * Negation: {@link Matcher.toBeLessThanOrEqual `toBeLessThanOrEqual(...)`}
      */
-    toBeGreaterThan(value: bigint): Matchers<bigint>;
+    toBeGreaterThan(value: bigint): Matcher<bigint>;
     /**
      * Expects the value to be a `number` greater than or equal to the specified
      * expected value.
      *
-     * Negation: {@link Matchers.toBeLessThan `toBeLessThan(...)`}
+     * Negation: {@link Matcher.toBeLessThan `toBeLessThan(...)`}
      */
-    toBeGreaterThanOrEqual(value: number): Matchers<number>;
+    toBeGreaterThanOrEqual(value: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` greater than or equal to the specified
      * expected value.
      *
-     * Negation: {@link Matchers.toBeLessThan `toBeLessThan(...)`}
+     * Negation: {@link Matcher.toBeLessThan `toBeLessThan(...)`}
+     */
+    toBeGreaterThanOrEqual(value: bigint): Matcher<bigint>;
+    /**
+     * Expects the value to be an instance of the specified {@link Constructor}.
+     *
+     * Negation: {@link NegativeMatchers.toBeInstanceOf `not.toInstanceOf(...)`}
      */
-    toBeGreaterThanOrEqual(value: bigint): Matchers<bigint>;
+    toBeInstanceOf<Class extends Constructor>(constructor: Class): Matcher<InstanceType<Class>>;
     /**
      * Expects the value to be an instance of the specified {@link Constructor},
-     * and (if specified) further asserts it with an {@link AssertionFunction}.
+     * and further validates it with a {@link Matcher}.
      *
      * Negation: {@link NegativeMatchers.toBeInstanceOf `not.toInstanceOf(...)`}
      */
-    toBeInstanceOf<Class extends Constructor, Assert extends AssertionFunction<InstanceType<Class>>>(constructor: Class, assertion?: Assert): Matchers<AssertedType<InstanceType<Class>, Assert>>;
+    toBeInstanceOf<Class extends Constructor, Match extends Matcher>(constructor: Class, matcher: Match): Matcher<InferMatcher<InstanceType<Class>, Match>>;
+    /**
+     * Expects the value to be an instance of the specified {@link Constructor},
+     * and further asserts it with an {@link AssertionFunction}.
+     *
+     * Negation: {@link NegativeMatchers.toBeInstanceOf `not.toInstanceOf(...)`}
+     */
+    toBeInstanceOf<Class extends Constructor, Assert extends AssertionFunction<InstanceType<Class>>>(constructor: Class, assertion: Assert): Matcher<AssertedType<InstanceType<Class>, Assert>>;
     /**
      * Expects the value to be a `number` less than the specified expected value.
      *
-     * Negation: {@link Matchers.toBeGreaterThanOrEqual `toBeGreaterThanOrEqual(...)`}
+     * Negation: {@link Matcher.toBeGreaterThanOrEqual `toBeGreaterThanOrEqual(...)`}
      */
-    toBeLessThan(value: number): Matchers<number>;
+    toBeLessThan(value: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` less than the specified expected value.
      *
-     * Negation: {@link Matchers.toBeGreaterThanOrEqual `toBeGreaterThanOrEqual(...)`}
+     * Negation: {@link Matcher.toBeGreaterThanOrEqual `toBeGreaterThanOrEqual(...)`}
      */
-    toBeLessThan(value: bigint): Matchers<bigint>;
+    toBeLessThan(value: bigint): Matcher<bigint>;
     /**
      * Expects the value to be a `number` less than or equal to* the specified
      * expected value.
      *
-     * Negation: {@link Matchers.toBeGreaterThan `toBeGreaterThan(...)`}
+     * Negation: {@link Matcher.toBeGreaterThan `toBeGreaterThan(...)`}
      */
-    toBeLessThanOrEqual(value: number): Matchers<number>;
+    toBeLessThanOrEqual(value: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` less than or equal to the specified
      * expected value.
      *
-     * Negation: {@link Matchers.toBeGreaterThan `toBeGreaterThan(...)`}
+     * Negation: {@link Matcher.toBeGreaterThan `toBeGreaterThan(...)`}
      */
-    toBeLessThanOrEqual(value: bigint): Matchers<bigint>;
+    toBeLessThanOrEqual(value: bigint): Matcher<bigint>;
     /**
      * Expects the value to be `NaN`.
      *
      * Negation: {@link NegativeMatchers.toBeNaN `not.toBeNaN()`}
      */
-    toBeNaN(): Matchers<number>;
+    toBeNaN(): Matcher<number>;
     /** Expects the value to strictly equal `null`. */
-    toBeNull(): Matchers<null>;
+    toBeNull(): Matcher<null>;
     /** Expects the value to strictly equal `true`. */
-    toBeTrue(): Matchers<true>;
+    toBeTrue(): Matcher<true>;
     /**
      * Expects the value to be _falsy_ (non-zero, non-empty string, ...).
      *
-     * Negation: {@link Matchers.toBeFalsy `toBeFalsy()`}
+     * Negation: {@link Matcher.toBeFalsy `toBeFalsy()`}
      */
-    toBeTruthy(): Matchers<T>;
+    toBeTruthy(): Matcher<T>;
     /** Expects the value to strictly equal `undefined`. */
-    toBeUndefined(): Matchers<undefined>;
+    toBeUndefined(): Matcher<undefined>;
     /**
      * Expects the value to be a `number` within the specified range where the
      * minimum and maximum values are inclusive.
      *
      * Negation: {@link NegativeMatchers.toBeWithinRange `not.toBeWithinRange(...)`}
      */
-    toBeWithinRange(min: number, max: number): Matchers<number>;
+    toBeWithinRange(min: number, max: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` within the specified range where the
      * minimum and maximum values are inclusive.
      *
      * Negation: {@link NegativeMatchers.toBeWithinRange `not.toBeWithinRange(...)`}
      */
-    toBeWithinRange(min: bigint, max: bigint): Matchers<bigint>;
+    toBeWithinRange(min: bigint, max: bigint): Matcher<bigint>;
     /**
      * Expects the value to be _deep equal to_ the specified expected one.
      *
      * Negation: {@link NegativeMatchers.toEqual `not.toEqual(...)`}
      */
-    toEqual<Type>(expected: Type): Matchers<InferMatchers<Type>>;
+    toEqual<Type>(expected: Type): Matcher<InferToEqual<Type>>;
     /**
      * Expects the value to have a `number` _property_ `length` with the specified
      * expected value.
      *
      * Negation: {@link NegativeMatchers.toHaveLength `not.toHaveLength(...)`}
      */
-    toHaveLength(length: number): Matchers<T & {
+    toHaveLength(length: number): Matcher<T & {
         length: number;
     }>;
     /**
-     * Expects the value to have the specified _property_ and (if specified)
-     * further asserts its value with an {@link AssertionFunction}.
+     * Expects the value to have the specified _property_.
+     *
+     * Negation: {@link NegativeExpectations.toHaveProperty `not.toHaveProperty(...)`}
+     */
+    toHaveProperty<Prop extends string | number | symbol>(property: Prop): Matcher<T & {
+        [keyt in Prop]: unknown;
+    }>;
+    /**
+     * Expects the value to have the specified _property_ and validates its value
+     * with a {@link Matcher}.
+     *
+     * Negation: {@link NegativeExpectations.toHaveProperty `not.toHaveProperty(...)`}
+     */
+    toHaveProperty<Prop extends string | number | symbol, Match extends Matcher>(property: Prop, matcher: Match): Matcher<T & {
+        [keyt in Prop]: InferMatcher<unknown, Match>;
+    }>;
+    /**
+     * Expects the value to have the specified _property_ and further asserts
+     * its value with an {@link AssertionFunction}.
      *
      * Negation: {@link NegativeMatchers.toHaveProperty `not.toHaveProperty(...)`}
      */
-    toHaveProperty<Prop extends string | number | symbol, Assert extends AssertionFunction>(property: Prop, assertion?: Assert): Matchers<T & {
+    toHaveProperty<Prop extends string | number | symbol, Assert extends AssertionFunction>(property: Prop, assertion: Assert): Matcher<T & {
         [keyt in Prop]: AssertedType<unknown, Assert>;
     }>;
     /**
@@ -180,7 +223,7 @@ export declare class Matchers<T = unknown> {
      *
      * Negation: {@link NegativeMatchers.toHaveSize `not.toHaveSize(...)`}
      */
-    toHaveSize(size: number): Matchers<T & {
+    toHaveSize(size: number): Matcher<T & {
         size: number;
     }>;
     /**
@@ -191,139 +234,139 @@ export declare class Matchers<T = unknown> {
      *
      * Negation: {@link NegativeMatchers.toInclude `not.toInclude(...)`}
      */
-    toInclude<P extends Record<string, any>>(properties: P): Matchers<T>;
+    toInclude<P extends Record<string, any>>(properties: P): Matcher<T>;
     /**
      * Expect the value to include _all_ mappings from the specified {@link Map}.
      *
      * Negation: {@link NegativeMatchers.toInclude `not.toInclude(...)`}
      */
-    toInclude(mappings: Map<any, any>): Matchers<T>;
+    toInclude(mappings: Map<any, any>): Matcher<T>;
     /**
      * Expect the value to be an {@link Iterable} object includind _all_ values
      * from the specified {@link Set}, in any order.
      *
      * Negation: {@link NegativeMatchers.toInclude `not.toInclude(...)`}
      */
-    toInclude(entries: Set<any>): Matchers<T>;
+    toInclude(entries: Set<any>): Matcher<T>;
     /**
      * Expect the value to be an {@link Iterable} object includind _all_ values
      * from the specified _array_, in any order.
      *
      * Negation: {@link NegativeMatchers.toInclude `not.toInclude(...)`}
      */
-    toInclude(values: any[]): Matchers<T>;
+    toInclude(values: any[]): Matcher<T>;
     /**
      * Expects the value to be a `string` _matching_ the specified sub-`string`
      * or {@link RegExp}.
      *
      * Negation: {@link NegativeMatchers.toMatch `not.toMatch(...)`}
      */
-    toMatch<Matcher extends string | RegExp>(matcher: Matcher): Matchers<string>;
+    toMatch<Match extends string | RegExp>(matcher: Match): Matcher<string>;
     /**
      * Expect the value to be an {@link Iterable} object includind _all_ values
      * (and only those values) from the specified _array_, in any order.
      */
-    toMatchContents(contents: any[]): Matchers<T>;
+    toMatchContents(contents: any[]): Matcher<T>;
     /**
      * Expect the value to be an {@link Iterable} object includind _all_ values
      * (and only those values) from the specified {@link Set}, in any order.
      */
-    toMatchContents(contents: Set<any>): Matchers<T>;
+    toMatchContents(contents: Set<any>): Matcher<T>;
     /**
      * Expects the value to be _strictly equal to_ the specified expected one.
      *
      * Negation: {@link NegativeMatchers.toStrictlyEqual `not.toStrictlyEqual(...)`}
      */
-    toStrictlyEqual<Type>(expected: Type): Matchers<Type>;
+    toStrictlyEqual<Type>(expected: Type): Matcher<Type>;
 }
 export declare class NegativeMatchers<T = unknown> {
     private readonly _instance;
     private readonly _matchers;
-    constructor(_instance: Matchers<T>, _matchers: Matcher[]);
+    constructor(_instance: Matcher<T>, _matchers: PositiveMatcherFunction[]);
     private _push;
     /**
      * Expects the value _**NOT**_ to be of the specified _extended_
      * {@link TypeName type}.
      *
-     * Negates: {@link Matchers.toBeA `toBeA(...)`}
+     * Negates: {@link Matcher.toBeA `toBeA(...)`}
      */
-    toBeA(type: TypeName): Matchers<T>;
+    toBeA(type: TypeName): Matcher<T>;
     /**
      * Expects the value to be a `number` _**OUTSIDE**_ of the given +/- _delta_
      * range of the specified expected value.
      *
-     * Negates: {@link Matchers.toBeCloseTo `toBeCloseTo(...)`}
+     * Negates: {@link Matcher.toBeCloseTo `toBeCloseTo(...)`}
      */
-    toBeCloseTo(value: number, delta: number): Matchers<number>;
+    toBeCloseTo(value: number, delta: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` _**OUTSIDE**_ of the given +/- _delta_
      * range of the specified expected value.
      *
-     * Negates: {@link Matchers.toBeCloseTo `toBeCloseTo(...)`}
+     * Negates: {@link Matcher.toBeCloseTo `toBeCloseTo(...)`}
      */
-    toBeCloseTo(value: bigint, delta: bigint): Matchers<bigint>;
+    toBeCloseTo(value: bigint, delta: bigint): Matcher<bigint>;
     /**
      * Expects the value to be either `null` or `undefined`.
      *
-     * Negates: {@link Matchers.toBeDefined `toBeDefined()`}
+     * Negates: {@link Matcher.toBeDefined `toBeDefined()`}
      */
-    toBeDefined(): Matchers<null | undefined>;
+    toBeDefined(): Matcher<null | undefined>;
     /**
      * Expects the value _**NOT**_ to be an instance of the specified
      * {@link Constructor}.
      *
-     * Negates: {@link Matchers.toBeInstanceOf `toBeInstanceOf(...)`}
+     * Negates: {@link Matcher.toBeInstanceOf `toBeInstanceOf(...)`}
      */
-    toBeInstanceOf(constructor: Constructor): Matchers<T>;
+    toBeInstanceOf(constructor: Constructor): Matcher<T>;
     /**
      * Expects the value _**NOT**_ to be `NaN`.
      *
-     * Negates: {@link Matchers.toBeNaN `toBeNaN()`}
+     * Negates: {@link Matcher.toBeNaN `toBeNaN()`}
      */
-    toBeNaN(): Matchers<number>;
+    toBeNaN(): Matcher<number>;
     /**
      * Expects the value to be a `number` _**OUTSIDE**_ of the specified range
      * where minimum and maximum values are inclusive.
      *
-     * Negates: {@link Matchers.toBeWithinRange `toBeWithinRange(...)`}
+     * Negates: {@link Matcher.toBeWithinRange `toBeWithinRange(...)`}
      */
-    toBeWithinRange(min: number, max: number): Matchers<number>;
+    toBeWithinRange(min: number, max: number): Matcher<number>;
     /**
      * Expects the value to be a `bigint` _**OUTSIDE**_ of the specified range
      * where minimum and maximum values are inclusive.
      *
-     * Negates: {@link Matchers.toBeWithinRange `toBeWithinRange(...)`}
+     * Negates: {@link Matcher.toBeWithinRange `toBeWithinRange(...)`}
      */
-    toBeWithinRange(min: bigint, max: bigint): Matchers<bigint>;
+    toBeWithinRange(min: bigint, max: bigint): Matcher<bigint>;
     /**
      * Expects the value _**NOT**_ to be _deep equal to_ the specified expected
      * one.
      *
-     * Negates: {@link Matchers.toEqual `toEqual(...)`}
+     * Negates: {@link Matcher.toEqual `toEqual(...)`}
      */
-    toEqual(expected: any): Matchers<T>;
+    toEqual(expected: any): Matcher<T>;
     /**
      * Expects the value to have a `number` _property_ `length` _different_ from
      * the specified expected value.
      *
-     * Negates: {@link Matchers.toHaveLength `toHaveLength(...)`}
+     * Negates: {@link Matcher.toHaveLength `toHaveLength(...)`}
      */
-    toHaveLength(length: number): Matchers<T & {
+    toHaveLength(length: number): Matcher<T & {
         length: number;
     }>;
     /**
      * Expects the value _**NOT**_ to have the specified _property_.
      *
-     * Negates: {@link Matchers.toHaveProperty `toHaveProperty(...)`}
+     * Negates: {@link Matcher.toHaveProperty `toHaveProperty(...)`}
      */
-    toHaveProperty(property: string | number | symbol): Matchers<T>;
+    toHaveProperty(property: string | number | symbol): Matcher<T>;
     /**
      * Expects the value to have a `number` _property_ `size` _different_ from
      * the specified expected value.
      *
-     * Negates: {@link Matchers.toHaveSize `toHaveSize(...)`}
+     * Negates: {@link Matcher.toHaveSize `toHaveSize(...)`}
      */
-    toHaveSize(size: number): Matchers<T & {
+    toHaveSize(size: number): Matcher<T & {
         size: number;
     }>;
     /**
@@ -333,43 +376,43 @@ export declare class NegativeMatchers<T = unknown> {
      * If the object being expected is a {@link Map}, the properties specified
      * here will be treated as _mappings_ for said {@link Map}.
      *
-     * Negates: {@link Matchers.toInclude `toInclude(...)`}
+     * Negates: {@link Matcher.toInclude `toInclude(...)`}
      */
-    toInclude<P extends Record<string, any>>(properties: P): Matchers<T>;
+    toInclude<P extends Record<string, any>>(properties: P): Matcher<T>;
     /**
      * Expect the value to include _none_ of the mappings from the specified
      * {@link Map}.
      *
-     * Negates: {@link Matchers.toInclude `toInclude(...)`}
+     * Negates: {@link Matcher.toInclude `toInclude(...)`}
      */
-    toInclude(mappings: Map<any, any>): Matchers<T>;
+    toInclude(mappings: Map<any, any>): Matcher<T>;
     /**
      * Expect the value to be an {@link Iterable} object includind _none_ of the
      * values from the specified {@link Set}.
      *
-     * Negates: {@link Matchers.toInclude `toInclude(...)`}
+     * Negates: {@link Matcher.toInclude `toInclude(...)`}
      */
-    toInclude(entries: Set<any>): Matchers<T>;
+    toInclude(entries: Set<any>): Matcher<T>;
     /**
      * Expect the value to be an {@link Iterable} object includind _none_ of the
      * values from the specified _array_.
      *
-     * Negates: {@link Matchers.toInclude `toInclude(...)`}
+     * Negates: {@link Matcher.toInclude `toInclude(...)`}
      */
-    toInclude(values: any[]): Matchers<T>;
+    toInclude(values: any[]): Matcher<T>;
     /**
      * Expects the value to be a `string` _**NOT MATCHING**_ the specified
      * sub-`string` or {@link RegExp}.
      *
-     * Negates: {@link Matchers.toMatch `toMatch(...)`}
+     * Negates: {@link Matcher.toMatch `toMatch(...)`}
      */
-    toMatch(matcher: string | RegExp): Matchers<string>;
+    toMatch(matcher: string | RegExp): Matcher<string>;
     /**
      * Expects the value _**NOT**_ to be _strictly equal to_ the specified
      * expected one.
      *
-     * Negates: {@link Matchers.toStrictlyEqual `toStrictlyEqual(...)`}
+     * Negates: {@link Matcher.toStrictlyEqual `toStrictlyEqual(...)`}
      */
-    toStrictlyEqual(expected: any): Matchers<T>;
+    toStrictlyEqual(expected: any): Matcher<T>;
 }
 export {};