search-gold

Overview

Your web page displays a list of columnar information, most often coming from one of the following two common data structures:

// an array of objects
Record<string, any>[]

// a Map in which the unique key's value is an object
Map<string, Record<string, any>>

For an improved UX in the front end, you can add a search field so the user can filter the displayed records.

The search-gold search engine 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 applicable types and methods.

import {
  // types
  ConfigParams,
  ItemRecord,
  MapRecords,

  // methods 
  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 or a Map<string, Record<string, any>>.
    //
    // Search results are returned in a separate array or Map.
    //
    // 'search-gold' package only reads the original data,
    // leaving it unchanged.
    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(''),

  // OR

  myFilteredData = <MapRecords>searchHandler(''),
}

3. Initialize the search engine.

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

Also, this initSearchConfig() method should be called again 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 is binded to the template for filtered display.
  // Use the variable name and appropriate syntax for your app.
  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

February 2026

Have fun!