search

The search utility performs a fuzzy search across an array of objects. It checks all string properties of each object and returns a filtered list of items that match the query based on a similarity threshold (tone).

Implementation

View Source Code

import { assert } from '../function/assert';
import { seek } from '../object/seek';
import { IS_STRING_ERROR_MSG, isString } from '../typed/isString';
import { IS_WITHIN_ERROR_MSG, isWithin } from '../typed/isWithin';
import { filter } from './filter';

/**
 * Performs a search on an array of objects, checking all values for a match with the search string.
 *
 * @example
 * ```ts
 * const data = [{ name: 'John Doe', age: 25 }, { name: 'Jane Doe', age: 30 }];
 * search(data, 'doe', 0.5); // [{ name: 'John Doe', age: 25 }, { name: 'Jane Doe', age: 30 }]
 * ```
 *
 * @param array - The array of objects to search.
 * @param query - The string to search for.
 * @param [tone=0.25] - Degree of similarity between 0 and 1.
 *
 * @returns The filtered array of objects that match the search string.
 *
 * @throws {Error} If input values are invalid.
 */
export function search<T>(array: T[], query: string, tone = 0.25): T[] {
  assert(isString(query), IS_STRING_ERROR_MSG, { args: { query }, type: TypeError });
  assert(isWithin(tone, 0, 1), IS_WITHIN_ERROR_MSG, { args: { max: 1, min: 0, tone }, type: TypeError });

  if (!query) return [];

  const searchTerm = query.toLowerCase();

  return filter(array, (obj) => seek(obj, searchTerm, tone));
}

Features

• Isomorphic: Works in both Browser and Node.js.
• Fuzzy Matching: Finds results even with partial or slightly misspelled queries.
• Auto-Scanning: Automatically searches through all string properties of objects in the array.
• Configurable Sensitivity: Adjust the "tone" to control how strict or loose the matching should be.

API

function search<T>(array: T[], query: string, tone?: number): T[];

Parameters

• array: The array of objects to search through.
• query: The search string (case-insensitive).
• tone: Optional. A similarity threshold between 0 and 1 (defaults to 0.25). Higher values require a closer match.

Returns

• A new array containing only the objects that match the search query.

Examples

Basic String Search

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

const users = [
  { name: 'John Doe', city: 'New York' },
  { name: 'Jane Smith', city: 'London' },
  { name: 'Alice Jones', city: 'Paris' },
];

// Searches across both 'name' and 'city'
search(users, 'doe'); // [{ name: 'John Doe', ... }]
search(users, 'london'); // [{ name: 'Jane Smith', ... }]

Adjusting Similarity (Tone)

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

const products = [{ name: 'iPhone 15' }, { name: 'Pixel 8' }];

// Strict match
search(products, 'phone', 0.8); // []

// Loose match (default)
search(products, 'phone', 0.25); // [{ name: 'iPhone 15' }]

Implementation Notes

• Throws TypeError if the first argument is not an array or if query is not a string.
• Returns an empty array immediately if the query is an empty string.
• Internally leverages the similarity string utility to calculate match scores.
• Only considers properties that are currently of type string for matching.

See Also

• filter: Filter items based on exact conditions.
• similarity: The underlying string comparison helper.
• contains: Check for existence using deep equality.