Value Validation

/**
 * Validate that matcher doesn't receive an expected argument
 * @param expected - Expected value to check
 * @param matcherName - Name of the matcher
 * @param options - Formatting options
 * @throws Error if expected is not undefined
 */
function ensureNoExpected(
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions
): void;

import { ensureNoExpected } from "jest-matcher-utils";

// Validate that matcher takes no expected argument
function toBeEmpty(received: unknown, expected: unknown) {
  // This matcher should not receive an expected argument
  ensureNoExpected(expected, 'toBeEmpty');
  
  // Continue with matcher logic...
}

// With custom options
function toHaveBeenCalled(received: unknown, expected: unknown) {
  ensureNoExpected(expected, 'toHaveBeenCalled', {
    isDirectExpectCall: true
  });
}

// Throws descriptive error if expected is provided:
// Error: expect(received).toBeEmpty()
//        
//        Matcher error: this matcher must not have an expected argument
//        
//        Expected has type: number
//        Expected has value: 42

/**
 * Validate that actual value is a number or bigint
 * @param actual - Actual value to validate
 * @param matcherName - Name of the matcher
 * @param options - Formatting options
 * @throws Error if actual is not number or bigint
 */
function ensureActualIsNumber(
  actual: unknown,
  matcherName: string,
  options?: MatcherHintOptions
): void;

import { ensureActualIsNumber } from "jest-matcher-utils";

// Validate received value is numeric
function toBeGreaterThan(received: unknown, expected: number) {
  ensureActualIsNumber(received, 'toBeGreaterThan');
  
  // Now safe to use received as number
  return (received as number) > expected;
}

// Works with bigint too
function toBeLessThan(received: unknown, expected: bigint) {
  ensureActualIsNumber(received, 'toBeLessThan');
  // received is validated as number | bigint
}

// With options for negated matchers
function toBePositive(received: unknown) {
  ensureActualIsNumber(received, 'toBePositive', { isNot: false });
}

// Throws descriptive error for invalid types:
// Error: expect(received).toBeGreaterThan(expected)
//        
//        Matcher error: received value must be a number or bigint
//        
//        Received has type: string
//        Received has value: "not a number"

/**
 * Validate that expected value is a number or bigint
 * @param expected - Expected value to validate
 * @param matcherName - Name of the matcher
 * @param options - Formatting options
 * @throws Error if expected is not number or bigint
 */
function ensureExpectedIsNumber(
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions
): void;

import { ensureExpectedIsNumber } from "jest-matcher-utils";

// Validate expected value is numeric
function toBeCloseTo(received: number, expected: unknown, precision = 2) {
  ensureExpectedIsNumber(expected, 'toBeCloseTo');
  
  // Now safe to use expected as number
  const diff = Math.abs(received - (expected as number));
  return diff < Math.pow(10, -precision);
}

// Custom validation messages
function toBeWithinRange(received: number, min: unknown, max: number) {
  ensureExpectedIsNumber(min, 'toBeWithinRange', {
    secondArgument: 'min'
  });
}

// Throws error for invalid expected types:
// Error: expect(received).toBeCloseTo(expected)
//        
//        Matcher error: expected value must be a number or bigint
//        
//        Expected has type: string
//        Expected has value: "42"

/**
 * Validate that both actual and expected values are numbers or bigints
 * @param actual - Actual value to validate
 * @param expected - Expected value to validate
 * @param matcherName - Name of the matcher
 * @param options - Formatting options
 * @throws Error if either value is not number or bigint
 */
function ensureNumbers(
  actual: unknown,
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions
): void;

import { ensureNumbers } from "jest-matcher-utils";

// Validate both values are numeric
function toBeGreaterThan(received: unknown, expected: unknown) {
  ensureNumbers(received, expected, 'toBeGreaterThan');
  
  // Both values are now validated as number | bigint
  return (received as number) > (expected as number);
}

// Common pattern for arithmetic matchers
function toBeCloseTo(received: unknown, expected: unknown, precision = 2) {
  ensureNumbers(received, expected, 'toBeCloseTo');
  
  const diff = Math.abs((received as number) - (expected as number));
  return diff < Math.pow(10, -precision);
}

// Validates both and throws for first invalid value found

/**
 * Validate that expected value is a non-negative integer
 * @param expected - Expected value to validate
 * @param matcherName - Name of the matcher
 * @param options - Formatting options
 * @throws Error if expected is not a non-negative integer
 */
function ensureExpectedIsNonNegativeInteger(
  expected: unknown,
  matcherName: string,
  options?: MatcherHintOptions
): void;

import { ensureExpectedIsNonNegativeInteger } from "jest-matcher-utils";

// Validate expected is a valid array length/index
function toHaveLength(received: unknown[], expected: unknown) {
  ensureExpectedIsNonNegativeInteger(expected, 'toHaveLength');
  
  // expected is now validated as non-negative integer
  return received.length === expected;
}

// For precision arguments
function toBeCloseTo(received: number, expected: number, precision: unknown = 2) {
  ensureExpectedIsNonNegativeInteger(precision, 'toBeCloseTo', {
    secondArgument: 'precision'
  });
}

// Validation rules:
// - Must be a number (not bigint)
// - Must be a safe integer (Number.isSafeInteger)
// - Must be >= 0

// Valid values: 0, 1, 2, 100, Number.MAX_SAFE_INTEGER
// Invalid values: -1, 1.5, NaN, Infinity, "5", null

// Throws error for invalid values:
// Error: expect(received).toHaveLength(expected)
//        
//        Matcher error: expected value must be a non-negative integer
//        
//        Expected has type: number
//        Expected has value: -1