search-gold

Overview

Your web page displays a list of columnar information, based on the common data structure:

array of objects

For an improved UX, you want to add a search field so the user can filter the displayed records.

The search-gold package is easy to set up and use!

Installation

$ npm i search-gold

OR

$ bun i search-gold

Usage

The following should provide enough to get local search up and running and keep your users in a happy place!

Provide the following in your component, e.g., my-data-list-component.ts.

1. Import the two types and methods.

import {
  ConfigParams,
  ItemRecord,
  searchHandler,
  searchSetConfig,
} from 'search-gold'

2. Create a method to set search configuration.

This wrapper method only needs to be called in the following two cases:

• when component is initialized and when data is ready
• when data changes (record has been created, edited, deleted)

You can name this wrapper method anything you want.

const initSearchConfig = () => {
  const config: ConfigParams = {
    // required: items must reference an array of
    // objects.
    //
    // 'search-gold' package only reads this data.
    // Search results are returned in a separate array.
    items: MyData,

    // required: keys are the object properties you
    // want to expose to search queries. List only
    // the fields which make sense to you.
    keys: ['productName', 'model', 'status'],

    // optional: default is false
    caseSensitive: true,

    // optional: default is true
    //
    // You should only ever consider disabling
    // memoization if you observe browser memory
    // limitations with cached search results.
    enableMemoize: false,
  }

  // Call the imported method with config arg.
  searchSetConfig(config)

  // After setting the config, you can call searchHandler()
  // as many times as necessary without having to set the
  // config again.
  //
  // Your template would be iterating over myFilteredData
  // in this example.
  //
  // How you set up your component to display the filtered
  // data is up to you and how your component is structured.
  //
  // Passing an empty string effectively returns the
  // the unfiltered set of records, the same as MyData.
  myFilteredData = <ItemRecord[]>searchHandler('')
}

3. Initialize the search engine.

This method (from Step 2.) should be called when your component has been initialized and your data is ready.

Also, this initSearchConfig() method should be called whenever your data changes after a record has been created, edited, or deleted.

// For this example we chose this method name; you
// can name this wrapper method anything you want.
initSearchConfig()

4. Execute search queries and get results.

Presumably, a method is binded to the UI's search field (in this example it's called searchMyData) and is called on every keystroke, debounced keystrokes, or an explicit and separate submit event. Ultimately, the UX behavior is left up to the front end engineer / design team.

const searchMyData = (query: string) => {
  // Call the imported method and get results.
  myFilteredData = searchHandler(query)
}

Author's Development

During development of the search-gold package, I integrated it into several apps I had previously created with Vue using its Composition API.

In this documentation I tried to keep the Usage code snippets framework neutral.

search-gold itself is framework neutral and should work in any TS codebase.

Credits

G. Gold

October 2025

Have fun!