contains

The contains utility checks if a specific value exists within an array. Unlike the native Array.prototype.includes(), contains uses deep equality, making it suitable for finding objects and arrays within a list.

Implementation

View Source Code

import { assert } from '../function/assert';
import { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';
import { isEqual } from '../typed/isEqual';

/**
 * Checks if a value is present in an array.
 *
 * @example
 * ```ts
 * const arr = [1, 2, 3, { a: 1 }, 'hello'];
 * const value = { a: 1 };
 * contains(arr, value) // true;
 * ```
 *
 * @param array - The array to check.
 * @param value - The value to search for.
 *
 * @returns true if the value is present in the array, else false.
 *
 * @throws {TypeError} If the first argument is not an array.
 */

// biome-ignore lint/suspicious/noExplicitAny: -
export function contains<T>(array: T[], value: any): boolean {
  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });

  return array.some((val) => isEqual(val, value));
}

contains.fp = true;

Features

• Isomorphic: Works in both Browser and Node.js.
• Deep Equality: Correctly identifies objects, arrays, and nested structures.
• Type-safe: Properly typed for all input values.

API

function contains<T>(array: T[], value: any): boolean;

Parameters

• array: The array to search.
• value: The value to search for. Uses deep comparison for complex types.

Returns

• true if the value is found in the array; otherwise, false.

Examples

Finding Primitives

import { contains } from '@vielzeug/toolkit';

const numbers = [1, 2, 3, 4];
contains(numbers, 3); // true
contains(numbers, 9); // false

Finding Objects (Deep Equality)

import { contains } from '@vielzeug/toolkit';

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];

// native includes() would return false here for a new object literal
contains(users, { id: 1, name: 'Alice' }); // true

Finding Nested Arrays

import { contains } from '@vielzeug/toolkit';

const nested = [
  [1, 2],
  [3, 4],
];
contains(nested, [1, 2]); // true

Implementation Notes

• Throws TypeError if the first argument is not an array.
• Uses the isEqual utility internally for comparisons.
• For performance-critical code with very large arrays of primitives, consider using native includes().

See Also

• isEqual: The deep equality helper used by contains.
• find: Get the matching element itself.
• some: Check if any element satisfies a custom predicate.