Search

Searching through arrays, nested arrays, or objects for specific keywords can often be cumbersome, especially when dealing with deeply nested structures. This package simplifies that process by offering a lightweight, flexible search utility that delves into every key of an object or array elements to find matches. It utilizes ES6+ syntax, so if your codebase uses older standards, a transpiler might be required.

Demo

Explore the live demonstration available on CodeSandbox:

How it works?

Install the package using npm or pnpm:

npm install @smakss/search
# or
pnpm add @smakss/search

For CommonJS modules:

const { default: Search } = require('@smakss/search');

For ECMAScript modules:

import Search from '@smakss/search';

Then, to utilize the search function within your application:

The Search function accepts an options object with the following properties:

• searchText (String): The string to search for.
• searchItems (Array|Object): The items or structure to search within.
• keys (Array): An array of keys to include or exclude from the search.
• include (Boolean): Determines whether to include (true) or exclude (false) the keys specified. Defaults to true.
• exact (Boolean): Determines whether to perform an exact match search. Defaults to false.

searchText is treated as a literal string, including regular expression characters. This keeps user-provided search text from controlling a regular expression.

The search function can take a generic type to specify the type of the search items.

Examples of Usage

Lets suppose we have the following type:

type Person = { name: string; lastName: string };

Searching Within an Object

When the match is found in an object, the entire object is returned:

const obj: Person = { name: 'John', lastName: 'Doe' };

const results = Search<Person>({ searchText: 'john', searchItems: [obj] });
// Results: [{ name: 'John', lastName: 'Doe' }]

Searching Within an Array

const arr: Person[] = [
  { name: 'John', lastName: 'Doe' },
  { name: 'Joe', lastName: 'Doe' }
];

const results = Search<Person>({ searchText: 'john', searchItems: arr });
// Results: [{ name: 'John', lastName: 'Doe' }]

Searching Within a Nested Array

const nestedArr: (Person | Person[])[] = [
  { name: 'John', lastName: 'Doe' },
  { name: 'Joe', lastName: 'Doe' },
  [{ name: 'Jane', lastName: 'Doe' }]
];

const results = Search<Person | Person[]>({
  searchText: 'jane',
  searchItems: nestedArr
});
// Results: [{ name: 'Jane', lastName: 'Doe' }]

Including Specific Keys

const results = Search<Person>({
  searchText: 'jane',
  searchItems: nestedArr,
  keys: ['name']
});
// Results: [{ name: 'Jane', lastName: 'Doe' }]

Excluding Specific Keys

const results = Search<Person>({
  searchText: 'jane',
  searchItems: nestedArr,
  keys: ['lastName'],
  include: false
});
// Results: []

Note: The result is an empty array because 'lastName' is excluded from the search.

Performing an Exact Match Search

const results = Search<Person>({
  searchText: 'jane',
  searchItems: nestedArr,
  exact: true
});
// Results: [{ name: 'Jane', lastName: 'Doe' }]

Note: Only the exact term 'Jane' is matched, not 'Janet' or other partial matches.

Contributing

Interested in contributing to this project? Please refer to CONTRIBUTING.md for contribution guidelines.

Code of Conduct

Our community prioritizes the well-being and inclusivity of all contributors and users. Please review our Code of Conduct to help maintain a supportive environment for everyone.

Local playground

This repository includes a Vite playground linked to the package through the pnpm workspace. Try the current local build without publishing a package version:

pnpm install
pnpm run dev:playground

To build the playground app, run this from the package root:

pnpm run build:playground