strong-mock 8.0.1 → 9.0.0-beta.0

package/dist/matchers/matcher.d.ts

@@ -0,0 +1,92 @@
+export declare const MATCHER_SYMBOL: unique symbol;
+export type MatcherOptions = {
+    /**
+     * Will be called when printing the diff between an expectation and the
+     * (mismatching) received arguments.
+     *
+     * With this function you can pretty print the `actual` and `expected` values
+     * according to your matcher's logic.
+     *
+     * @param actual The actual value received by this matcher, same as the one
+     *   in `matches`.
+     *
+     * @example
+     * const neverMatcher = It.matches(() => false, {
+     *   getDiff: (actual) => ({ actual, expected: 'never' })
+     * });
+     *
+     * when(() => fn(neverMatcher)).thenReturn(42);
+     *
+     * fn(42);
+     * // - Expected
+     * // + Received
+     * //
+     * //   - 'never'
+     * //   + 42
+     */
+    getDiff: (actual: any) => {
+        actual: any;
+        expected: any;
+    };
+    /**
+     * Will be called when printing arguments for an unexpected or unmet expectation.
+     *
+     * @example
+     * const neverMatcher = It.matches(() => false, {
+     *   toString: () => 'never'
+     * });
+     * when(() => fn(neverMatcher)).thenReturn(42);
+     *
+     * fn(42);
+     * // Unmet expectations:
+     * // when(() => fn(never)).thenReturn(42)
+     */
+    toString: () => string;
+};
+/**
+ * You MUST use {@link It.matches} to create this branded type.
+ */
+export interface Matcher extends MatcherOptions {
+    [MATCHER_SYMBOL]: boolean;
+    /**
+     * Will be called with the received value and should return whether it matches
+     * the expectation.
+     */
+    matches: (actual: any) => boolean;
+}
+/**
+ * This takes the shape of T to satisfy call sites, but strong-mock will only
+ * care about the matcher type.
+ */
+export type TypeMatcher<T> = T & Matcher;
+/**
+ * Used to test if an expectation is an argument is a custom matcher.
+ */
+export declare function isMatcher(f: unknown): f is Matcher;
+export declare const getMatcherDiffs: (matchers: Matcher[], args: unknown[]) => {
+    actual: unknown[];
+    expected: unknown[];
+};
+/**
+ * Create a custom matcher.
+ *
+ * @param predicate Will receive the actual value and return whether it matches the expectation.
+ * @param options
+ * @param options.toString An optional function that should return a string that will be
+ *   used when the matcher needs to be printed in an error message. By default,
+ *   it stringifies `predicate`.
+ * @param options.getDiff An optional function that will be called when printing the
+ *   diff for a failed expectation. It will only be called if there's a mismatch
+ *   between the expected and received values i.e. `predicate(actual)` fails.
+ *   By default, the `toString` method will be used to format the expected value,
+ *   while the received value will be returned as-is.
+ *
+ * @example
+ * // Create a matcher for positive numbers.
+ * const fn = mock<(x: number) => number>();
+ * when(() => fn(It.matches(x => x >= 0))).thenReturn(42);
+ *
+ * fn(2) === 42
+ * fn(-1) // throws
+ */
+export declare const matches: <T>(predicate: (actual: T) => boolean, options?: Partial<MatcherOptions>) => TypeMatcher<T>;

package/dist/matchers/will-capture.d.ts

@@ -0,0 +1,21 @@
+import type { Matcher, TypeMatcher } from './matcher';
+/**
+ * Matches anything and stores the received value.
+ *
+ * This should not be needed for most cases, but can be useful if you need
+ * access to a complex argument outside the expectation e.g. to test a
+ * callback.
+ *
+ * @param name If given, this name will be printed in error messages.
+ *
+ * @example
+ * const fn = mock<(cb: (value: number) => number) => void>();
+ * const matcher = It.willCapture();
+ * when(() => fn(matcher)).thenReturn();
+ *
+ * fn(x => x + 1);
+ * matcher.value?.(3) === 4
+ */
+export declare const willCapture: <T = unknown>(name?: string) => T & Matcher & {
+    value: T | undefined;
+};

package/dist/mock/defaults.d.ts

@@ -1,11 +1,11 @@
-import type { MockOptions } from './options';
-export type StrongMockDefaults = Required<MockOptions>;
-export declare let currentDefaults: StrongMockDefaults;
-/**
- * Override strong-mock's defaults.
- *
- * @param newDefaults These will be applied to the library defaults. Multiple
- *   calls don't stack e.g. calling this with `{}` will clear any previously
- *   applied defaults.
- */
-export declare const setDefaults: (newDefaults: MockOptions) => void;
+import type { MockOptions } from './options';
+export type StrongMockDefaults = Required<MockOptions>;
+export declare let currentDefaults: StrongMockDefaults;
+/**
+ * Override strong-mock's defaults.
+ *
+ * @param newDefaults These will be applied to the library defaults. Multiple
+ *   calls don't stack e.g. calling this with `{}` will clear any previously
+ *   applied defaults.
+ */
+export declare const setDefaults: (newDefaults: MockOptions) => void;

package/dist/mock/map.d.ts

@@ -1,16 +1,16 @@
-import type { ExpectationRepository } from '../expectation/repository/expectation-repository';
-import type { PendingExpectation } from '../when/pending-expectation';
-import type { StrongMockDefaults } from './defaults';
-import type { Mock } from './mock';
-export declare const setActiveMock: (mock: Mock<any>) => void;
-export declare const clearActiveMock: () => void;
-export declare const getActiveMock: () => Mock<any>;
-type MockState = {
-    repository: ExpectationRepository;
-    pendingExpectation: PendingExpectation;
-    options: StrongMockDefaults;
-};
-export declare const getMockState: (mock: Mock<any>) => MockState;
-export declare const setMockState: (mock: Mock<any>, state: MockState) => void;
-export declare const getAllMocks: () => [Mock<any>, MockState][];
-export {};
+import type { ExpectationRepository } from '../expectation/repository/expectation-repository';
+import type { ExpectationBuilder } from '../when/expectation-builder';
+import type { StrongMockDefaults } from './defaults';
+import type { Mock } from './mock';
+export declare const setActiveMock: (mock: Mock<any>) => void;
+export declare const clearActiveMock: () => void;
+export declare const getActiveMock: () => Mock<any>;
+type MockState = {
+    repository: ExpectationRepository;
+    builder: ExpectationBuilder;
+    options: StrongMockDefaults;
+};
+export declare const getMockState: (mock: Mock<any>) => MockState;
+export declare const setMockState: (mock: Mock<any>, state: MockState) => void;
+export declare const getAllMocks: () => [Mock<any>, MockState][];
+export {};

package/dist/mock/mock.d.ts

@@ -1,29 +1,29 @@
-import type { MockOptions } from './options';
-export type Mock<T> = T;
-export declare enum Mode {
-    EXPECT = 0,
-    CALL = 1
-}
-export declare const setMode: (mode: Mode) => void;
-/**
- * Create a type safe mock.
- *
- * @see {@link when} Set expectations on the mock using `when`.
- *
- * @param options Configure the options for this specific mock, overriding any
- *   defaults that were set with {@link setDefaults}.
- * @param options.unexpectedProperty Controls what happens when an unexpected
- *   property is accessed.
- * @param options.concreteMatcher The matcher that will be used when one isn't
- *   specified explicitly.
- * @param options.exactParams Controls whether the number of received arguments
- *   has to match the expectation.
- *
- * @example
- * const fn = mock<() => number>();
- *
- * when(() => fn()).thenReturn(23);
- *
- * fn() === 23;
- */
-export declare const mock: <T>({ unexpectedProperty, concreteMatcher, exactParams, }?: MockOptions) => T;
+import type { MockOptions } from './options';
+export type Mock<T> = T;
+export declare enum Mode {
+    EXPECT = 0,
+    CALL = 1
+}
+export declare const setMode: (mode: Mode) => void;
+/**
+ * Create a type safe mock.
+ *
+ * @see {@link when} Set expectations on the mock using `when`.
+ *
+ * @param options Configure the options for this specific mock, overriding any
+ *   defaults that were set with {@link setDefaults}.
+ * @param options.unexpectedProperty Controls what happens when an unexpected
+ *   property is accessed.
+ * @param options.concreteMatcher The matcher that will be used when one isn't
+ *   specified explicitly.
+ * @param options.exactParams Controls whether the number of received arguments
+ *   has to match the expectation.
+ *
+ * @example
+ * const fn = mock<() => number>();
+ *
+ * when(() => fn()).thenReturn(23);
+ *
+ * fn() === 23;
+ */
+export declare const mock: <T>({ unexpectedProperty, concreteMatcher, exactParams, }?: MockOptions) => T;

package/dist/mock/options.d.ts

@@ -1,99 +1,99 @@
-import type { Matcher } from '../expectation/matcher';
-export type ConcreteMatcher = <T>(expected: T) => Matcher;
-export declare enum UnexpectedProperty {
-    /**
-     * Throw an error immediately.
-     *
-     * @example
-     * // Will throw "Didn't expect foo to be accessed".
-     * const { foo } = service;
-     *
-     * // Will throw "Didn't expect foo to be accessed",
-     * // without printing the arguments.
-     * foo(42);
-     */
-    THROW = 0,
-    /**
-     * Return a function that will throw if called. This can be useful if your
-     * code destructures a function but never calls it.
-     *
-     * It will also improve error messages for unexpected calls because arguments
-     * will be captured instead of throwing immediately on the property access.
-     *
-     * The function will be returned even if the property is not supposed to be a
-     * function. This could cause weird behavior at runtime, when your code expects
-     * e.g. a number and gets a function instead.
-     *
-     * @example
-     * // This will NOT throw.
-     * const { foo } = service;
-     *
-     * // This will NOT throw, and might produce unexpected results.
-     * foo > 0
-     *
-     * // Will throw "Didn't expect foo(42) to be called".
-     * foo(42);
-     */
-    CALL_THROW = 1
-}
-export interface MockOptions {
-    /**
-     * Controls what should be returned for a property with no expectations.
-     *
-     * A property with no expectations is a property that has no `when`
-     * expectations set on it. It can also be a property that ran out of `when`
-     * expectations.
-     *
-     * The default is to return a function that will throw when called.
-     *
-     * @example
-     * const foo = mock<{ bar: () => number }>();
-     * foo.bar() // unexpected property access
-     *
-     * @example
-     * const foo = mock<{ bar: () => number }>();
-     * when(() => foo.bar()).thenReturn(42);
-     * foo.bar() === 42
-     * foo.bar() // unexpected property access
-     */
-    unexpectedProperty?: UnexpectedProperty;
-    /**
-     * If `true`, the number of received arguments in a function/method call has to
-     * match the number of arguments set in the expectation.
-     *
-     * If `false`, extra parameters are considered optional and checked by the
-     * TypeScript compiler instead.
-     *
-     * You may want to set this to `true` if you're not using TypeScript,
-     * or if you want to be extra strict.
-     *
-     * @example
-     * const fn = mock<(value?: number) => number>({ exactParams: true });
-     * when(() => fn()).thenReturn(42);
-     *
-     * fn(100) // throws with exactParams, returns 42 without
-     */
-    exactParams?: boolean;
-    /**
-     * The matcher that will be used when one isn't specified explicitly.
-     *
-     * The most common use case is replacing the default {@link It.deepEquals}
-     * matcher with {@link It.is}, but you can also use {@link It.matches} to
-     * create a custom matcher.
-     *
-     * @param expected The concrete expected value received from the
-     *   {@link when} expectation.
-     *
-     * @example
-     * const fn = mock<(value: number[]) => boolean>({
-     *   concreteMatcher: It.is
-     * });
-     *
-     * const expected = [1, 2, 3];
-     * when(() => fn(expected).thenReturn(true);
-     *
-     * fn([1, 2, 3]); // throws because different array instance
-     * fn(expected); // OK
-     */
-    concreteMatcher?: ConcreteMatcher;
-}
+import type { Matcher } from '../matchers/matcher';
+export type ConcreteMatcher = <T>(expected: T) => Matcher;
+export declare enum UnexpectedProperty {
+    /**
+     * Throw an error immediately.
+     *
+     * @example
+     * // Will throw "Didn't expect foo to be accessed".
+     * const { foo } = service;
+     *
+     * // Will throw "Didn't expect foo to be accessed",
+     * // without printing the arguments.
+     * foo(42);
+     */
+    THROW = 0,
+    /**
+     * Return a function that will throw if called. This can be useful if your
+     * code destructures a function but never calls it.
+     *
+     * It will also improve error messages for unexpected calls because arguments
+     * will be captured instead of throwing immediately on the property access.
+     *
+     * The function will be returned even if the property is not supposed to be a
+     * function. This could cause weird behavior at runtime, when your code expects
+     * e.g. a number and gets a function instead.
+     *
+     * @example
+     * // This will NOT throw.
+     * const { foo } = service;
+     *
+     * // This will NOT throw, and might produce unexpected results.
+     * foo > 0
+     *
+     * // Will throw "Didn't expect foo(42) to be called".
+     * foo(42);
+     */
+    CALL_THROW = 1
+}
+export interface MockOptions {
+    /**
+     * Controls what should be returned for a property with no expectations.
+     *
+     * A property with no expectations is a property that has no `when`
+     * expectations set on it. It can also be a property that ran out of `when`
+     * expectations.
+     *
+     * The default is to return a function that will throw when called.
+     *
+     * @example
+     * const foo = mock<{ bar: () => number }>();
+     * foo.bar() // unexpected property access
+     *
+     * @example
+     * const foo = mock<{ bar: () => number }>();
+     * when(() => foo.bar()).thenReturn(42);
+     * foo.bar() === 42
+     * foo.bar() // unexpected property access
+     */
+    unexpectedProperty?: UnexpectedProperty;
+    /**
+     * If `true`, the number of received arguments in a function/method call has to
+     * match the number of arguments set in the expectation.
+     *
+     * If `false`, extra parameters are considered optional and checked by the
+     * TypeScript compiler instead.
+     *
+     * You may want to set this to `true` if you're not using TypeScript,
+     * or if you want to be extra strict.
+     *
+     * @example
+     * const fn = mock<(value?: number) => number>({ exactParams: true });
+     * when(() => fn()).thenReturn(42);
+     *
+     * fn(100) // throws with exactParams, returns 42 without
+     */
+    exactParams?: boolean;
+    /**
+     * The matcher that will be used when one isn't specified explicitly.
+     *
+     * The most common use case is replacing the default {@link It.deepEquals}
+     * matcher with {@link It.is}, but you can also use {@link It.matches} to
+     * create a custom matcher.
+     *
+     * @param expected The concrete expected value received from the
+     *   {@link when} expectation.
+     *
+     * @example
+     * const fn = mock<(value: number[]) => boolean>({
+     *   concreteMatcher: It.is
+     * });
+     *
+     * const expected = [1, 2, 3];
+     * when(() => fn(expected).thenReturn(true);
+     *
+     * fn([1, 2, 3]); // throws because different array instance
+     * fn(expected); // OK
+     */
+    concreteMatcher?: ConcreteMatcher;
+}

package/dist/mock/stub.d.ts

@@ -1,5 +1,5 @@
-import type { ExpectationRepository } from '../expectation/repository/expectation-repository';
-import type { PendingExpectation } from '../when/pending-expectation';
-import type { Mock } from './mock';
-import { Mode } from './mock';
-export declare const createStub: <T>(repo: ExpectationRepository, pendingExpectation: PendingExpectation, getCurrentMode: () => Mode) => T;
+import type { ExpectationRepository } from '../expectation/repository/expectation-repository';
+import type { ExpectationBuilder } from '../when/expectation-builder';
+import type { Mock } from './mock';
+import { Mode } from './mock';
+export declare const createStub: <T>(repo: ExpectationRepository, builder: ExpectationBuilder, getCurrentMode: () => Mode) => T;

package/dist/print.d.ts

@@ -1,10 +1,10 @@
-import type { Expectation } from './expectation/expectation';
-import type { ReturnValue } from './expectation/repository/return-value';
-import type { Property } from './proxy';
-export declare const printProperty: (property: Property) => string;
-export declare const printArg: (arg: unknown) => string;
-export declare const printCall: (property: Property, args: any[]) => string;
-export declare const printReturns: ({ isError, isPromise, value }: ReturnValue, min: number, max: number) => string;
-export declare const printWhen: (property: Property, args: any[] | undefined) => string;
-export declare const printExpectation: (property: Property, args: any[] | undefined, returnValue: ReturnValue, min: number, max: number) => string;
-export declare const printRemainingExpectations: (expectations: Expectation[]) => string;
+import type { Expectation } from './expectation/expectation';
+import type { ReturnValue } from './expectation/repository/return-value';
+import type { Property } from './proxy';
+export declare const printProperty: (property: Property) => string;
+export declare const printValue: (arg: unknown) => string;
+export declare const printCall: (property: Property, args?: any[]) => string;
+export declare const printReturns: ({ isError, isPromise, value }: ReturnValue, min: number, max: number) => string;
+export declare const printWhen: (property: Property, args: any[] | undefined) => string;
+export declare const printExpectation: (property: Property, args: any[] | undefined, returnValue: ReturnValue, min: number, max: number) => string;
+export declare const printRemainingExpectations: (expectations: Expectation[]) => string;

package/dist/proxy.d.ts

@@ -1,48 +1,48 @@
-import type { Mock } from './mock/mock';
-export type Property = string | symbol;
-export interface ProxyTraps {
-    /**
-     * Called when accessing any property on an object, except for
-     * `.call`, `.apply` and `.bind`.
-     */
-    property: (property: Property) => unknown;
-    /**
-     * Called when calling a function.
-     *
-     * @example
-     * ```
-     * fn(...args)
-     * ```
-     *
-     * @example
-     * ```
-     * fn.call(this, ...args)
-     * ```
-     *
-     * @example
-     * ```
-     * fn.apply(this, [...args])
-     * ```
-     *
-     * @example
-     * ```
-     * Reflect.apply(fn, this, [...args])
-     * ```
-     */
-    apply: (args: any[]) => unknown;
-    /**
-     * Called when getting the proxy's own enumerable keys.
-     *
-     * @example
-     * ```
-     * Object.keys(proxy);
-     * ```
-     *
-     * @example
-     * ```
-     * const foo = { ...proxy };
-     * ```
-     */
-    ownKeys: () => Property[];
-}
-export declare const createProxy: <T>(traps: ProxyTraps) => T;
+import type { Mock } from './mock/mock';
+export type Property = string | symbol;
+export interface ProxyTraps {
+    /**
+     * Called when accessing any property on an object, except for
+     * `.call`, `.apply` and `.bind`.
+     */
+    property: (property: Property) => unknown;
+    /**
+     * Called when calling a function.
+     *
+     * @example
+     * ```
+     * fn(...args)
+     * ```
+     *
+     * @example
+     * ```
+     * fn.call(this, ...args)
+     * ```
+     *
+     * @example
+     * ```
+     * fn.apply(this, [...args])
+     * ```
+     *
+     * @example
+     * ```
+     * Reflect.apply(fn, this, [...args])
+     * ```
+     */
+    apply: (args: unknown[]) => unknown;
+    /**
+     * Called when getting the proxy's own enumerable keys.
+     *
+     * @example
+     * ```
+     * Object.keys(proxy);
+     * ```
+     *
+     * @example
+     * ```
+     * const foo = { ...proxy };
+     * ```
+     */
+    ownKeys: () => Property[];
+}
+export declare const createProxy: <T>(traps: ProxyTraps) => T;

package/dist/return/invocation-count.d.ts

@@ -1,44 +1,44 @@
-import type { Expectation } from '../expectation/expectation';
-export interface InvocationCount {
-    /**
-     * Expect a call to be made at least `min` times and at most `max` times.
-     */
-    between(min: number, max: number): void;
-    /**
-     * Expect a call to be made exactly `exact` times.
-     *
-     * Shortcut for `between(exact, exact)`.
-     */
-    times(exact: number): void;
-    /**
-     * Expect a call to be made any number of times, including never.
-     *
-     * Shortcut for `between(0, Infinity)`.
-     */
-    anyTimes(): void;
-    /**
-     * Expect a call to be made at least `min` times.
-     *
-     * Shortcut for `between(min, Infinity)`.
-     */
-    atLeast(min: number): void;
-    /**
-     * Expect a call to be made at most `max` times.
-     *
-     * Shortcut for `between(0, max)`.
-     */
-    atMost(max: number): void;
-    /**
-     * Expect a call to be made exactly once.
-     *
-     * Shortcut for `times(1)`.
-     */
-    once(): void;
-    /**
-     * Expect a call to be made exactly twice.
-     *
-     * Shortcut for `times(2)`.
-     */
-    twice(): void;
-}
-export declare const createInvocationCount: (expectation: Expectation) => InvocationCount;
+import type { Expectation } from '../expectation/expectation';
+export interface InvocationCount {
+    /**
+     * Expect a call to be made at least `min` times and at most `max` times.
+     */
+    between: (min: number, max: number) => void;
+    /**
+     * Expect a call to be made exactly `exact` times.
+     *
+     * Shortcut for `between(exact, exact)`.
+     */
+    times: (exact: number) => void;
+    /**
+     * Expect a call to be made any number of times, including never.
+     *
+     * Shortcut for `between(0, Infinity)`.
+     */
+    anyTimes: () => void;
+    /**
+     * Expect a call to be made at least `min` times.
+     *
+     * Shortcut for `between(min, Infinity)`.
+     */
+    atLeast: (min: number) => void;
+    /**
+     * Expect a call to be made at most `max` times.
+     *
+     * Shortcut for `between(0, max)`.
+     */
+    atMost: (max: number) => void;
+    /**
+     * Expect a call to be made exactly once.
+     *
+     * Shortcut for `times(1)`.
+     */
+    once: () => void;
+    /**
+     * Expect a call to be made exactly twice.
+     *
+     * Shortcut for `times(2)`.
+     */
+    twice: () => void;
+}
+export declare const createInvocationCount: (expectation: Expectation) => InvocationCount;