@jest/expect-utils

import { 
  equals, 
  isA, 
  isError,
  getPath, 
  getObjectKeys,
  pathAsArray,
  getObjectSubset, 
  subsetEquality,
  iterableEquality,
  typeEquality,
  arrayBufferEquality,
  sparseArrayEquality,
  partition,
  emptyObject,
  isOneline
} from "@jest/expect-utils";

const { 
  equals, 
  isA, 
  isError,
  getPath, 
  getObjectKeys,
  pathAsArray,
  getObjectSubset, 
  subsetEquality,
  iterableEquality,
  typeEquality,
  arrayBufferEquality,
  sparseArrayEquality,
  partition,
  emptyObject,
  isOneline
} = require("@jest/expect-utils");

import { equals, getPath, iterableEquality, subsetEquality } from "@jest/expect-utils";

// Deep equality comparison
const result = equals({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] });
// Result: true

// Safe property path traversal
const pathResult = getPath({ user: { name: "Alice" } }, "user.name");
// Result: { hasEndProp: true, value: "Alice", traversedPath: ["user", "name"] }

// Object subset comparison for partial matching
const isSubset = subsetEquality(
  { name: "Alice", age: 30, city: "NYC" },
  { name: "Alice", age: 30 }
);
// Result: true

/**
 * Deep equality comparison function with support for custom testers
 * @param a - First value to compare
 * @param b - Second value to compare
 * @param customTesters - Optional array of custom tester functions
 * @param strictCheck - Optional strict comparison mode
 * @returns boolean indicating equality
 */
function equals(
  a: unknown,
  b: unknown,
  customTesters?: Array<Tester>,
  strictCheck?: boolean
): boolean;

type EqualsFunction = (
  a: unknown,
  b: unknown,
  customTesters?: Array<Tester>,
  strictCheck?: boolean,
) => boolean;

/**
 * Type guard that checks if value matches given type name
 * @param typeName - String representation of type (e.g., "Array", "Object")
 * @param value - Value to check
 * @returns Type predicate indicating if value is of specified type
 */
function isA<T>(typeName: string, value: unknown): value is T;

/**
 * Type guard for Error objects including subclasses
 * @param value - Value to check
 * @returns Type predicate indicating if value is an Error
 */
function isError(value: unknown): value is Error;

/**
 * Safely traverses object property paths with detailed results
 * @param object - Object to traverse
 * @param propertyPath - Property path as string or array
 * @returns GetPath object with traversal information
 */
function getPath(
  object: Record<string, any>,
  propertyPath: string | Array<string>
): GetPath;

interface GetPath {
  hasEndProp?: boolean;
  endPropIsDefined?: boolean;
  lastTraversedObject: unknown | null;
  traversedPath: Array<string>;
  value?: unknown;
}

/**
 * Retrieves object's enumerable string and symbol keys
 * @param object - Object to get keys from
 * @returns Array of string and symbol keys
 */
function getObjectKeys(object: object): Array<string | symbol>;

/**
 * Converts dot-notation property path to array of property names
 * @param propertyPath - Property path string (e.g., "user.name")
 * @returns Array of property names
 */
function pathAsArray(propertyPath: string): Array<any>;

/**
 * Strips properties from object that are not present in the subset
 * @param object - Source object
 * @param subset - Subset pattern object
 * @param customTesters - Optional custom tester functions
 * @param seenReferences - Internal circular reference tracking
 * @returns Object containing only properties present in subset
 */
function getObjectSubset(
  object: any,
  subset: any,
  customTesters?: Array<Tester>,
  seenReferences?: WeakMap<object, boolean>
): any;

/**
 * Checks if object contains all properties from subset with matching values
 * @param object - Object to check
 * @param subset - Subset pattern to match
 * @param customTesters - Optional custom tester functions
 * @returns boolean or undefined if not applicable
 */
function subsetEquality(
  object: unknown,
  subset: unknown,
  customTesters?: Array<Tester>
): boolean | undefined;

/**
 * Compares iterables (Sets, Maps, iterators) with circular reference detection
 * @param a - First iterable
 * @param b - Second iterable
 * @param customTesters - Optional custom tester functions
 * @param aStack - Internal circular reference stack for a
 * @param bStack - Internal circular reference stack for b
 * @returns boolean or undefined if not applicable
 */
function iterableEquality(
  a: any,
  b: any,
  customTesters?: Array<Tester>,
  aStack?: Array<any>,
  bStack?: Array<any>
): boolean | undefined;

/**
 * Compares constructor types with special handling for arrays and null
 * @param a - First value
 * @param b - Second value
 * @returns boolean or undefined if not applicable
 */
function typeEquality(a: any, b: any): boolean | undefined;

/**
 * Compares ArrayBuffers and typed arrays byte-by-byte
 * @param a - First buffer
 * @param b - Second buffer
 * @returns boolean or undefined if not applicable
 */
function arrayBufferEquality(
  a: unknown,
  b: unknown
): boolean | undefined;

/**
 * Compares sparse arrays by checking both values and key patterns
 * @param a - First array
 * @param b - Second array
 * @param customTesters - Optional custom tester functions
 * @returns boolean or undefined if not applicable
 */
function sparseArrayEquality(
  a: unknown,
  b: unknown,
  customTesters?: Array<Tester>
): boolean | undefined;

/**
 * Splits array into two arrays based on predicate function
 * @param items - Array to partition
 * @param predicate - Function to determine which partition items belong to
 * @returns Tuple of [truthy items, falsy items]
 */
function partition<T>(
  items: Array<T>,
  predicate: (arg: T) => boolean
): [Array<T>, Array<T>];

/**
 * Checks if object is empty (has no own properties)
 * @param obj - Object to check
 * @returns boolean indicating if object is empty
 */
function emptyObject(obj: unknown): boolean;

/**
 * Checks if both values are strings without multiline content
 * @param expected - First string value
 * @param received - Second string value
 * @returns boolean indicating if both are single-line strings
 */
function isOneline(expected: unknown, received: unknown): boolean;

/**
 * Function type for custom equality testers used in equals() function
 */
type Tester = (
  this: TesterContext,
  a: any,
  b: any,
  customTesters: Array<Tester>,
) => boolean | undefined;

/**
 * Context object passed to custom testers
 */
interface TesterContext {
  equals: EqualsFunction;
}

/**
 * Type for the main equals function
 */
type EqualsFunction = (
  a: unknown,
  b: unknown,
  customTesters?: Array<Tester>,
  strictCheck?: boolean,
) => boolean;