search-gold 1.0.2 → 1.1.0

package/README.md

@@ -2,20 +2,28 @@
 
 ## Overview
 
-Your web page displays a list of columnar information, based on the common data structure:
+Your web page displays a list of columnar information, most often coming from one of the following two common data structures:
 
-`array of objects`
+```javascript
+// 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, you want to add a search field so the user can filter the displayed records.
+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` package is easy to set up and use!
+The `search-gold` search engine is easy to set up and use!
 
 ## Installation
 
 ```bash
 $ npm i search-gold
 ```
+
 OR
+
 ```bash
 $ bun i search-gold
 ```
@@ -26,11 +34,16 @@ The following should provide enough to get local search up and running and keep
 
 Provide the following in your component, e.g., `my-data-list-component.ts`.
 
-### 1. Import the two types and methods.
+### 1. Import applicable types and methods.
+
 ```javascript
 import {
+  // types
   ConfigParams,
   ItemRecord,
+  MapRecords,
+
+  // methods 
   searchHandler,
   searchSetConfig,
 } from 'search-gold'
@@ -40,30 +53,32 @@ import {
 
 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)
+- 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.
 
 ```javascript
 const initSearchConfig = () => {
   const config: ConfigParams = {
-    // required: items must reference an array of
-    // objects.
+    // 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 this data.
-    // Search results are returned in a separate array.
+    // 'search-gold' package only reads the original data,
+    // leaving it unchanged.
     items: MyData,
 
-    // required: keys are the object properties you
+    // 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
+    // Optional: default is false
     caseSensitive: true,
 
-    // optional: default is true
+    // Optional: default is true
     //
     // You should only ever consider disabling
     // memoization if you observe browser memory
@@ -72,7 +87,7 @@ const initSearchConfig = () => {
   }
 
   // Call the imported method with config arg.
-  searchSetConfig(config)
+  searchSetConfig(config),
 
   // After setting the config, you can call searchHandler()
   // as many times as necessary without having to set the
@@ -86,23 +101,27 @@ const initSearchConfig = () => {
   //
   // Passing an empty string effectively returns the
   // the unfiltered set of records, the same as MyData.
-  myFilteredData = <ItemRecord[]>searchHandler('')
+  myFilteredData = <ItemRecord[]>searchHandler(''),
+
+  // OR
+
+  myFilteredData = <MapRecords>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.
+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 whenever your
+Also, this `initSearchConfig()` method should be called again whenever your
 data changes after a record has been created, edited, or deleted.
 
 ```javascript
 // 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.
 
@@ -110,9 +129,13 @@ Presumably, a method is binded to the UI's search field (in this example it's ca
 `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.
+
 ```javascript
 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)
 }
 ```
@@ -125,10 +148,11 @@ 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
+February 2026
 
 Have fun!

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "search-gold",
   "private": false,
-  "version": "1.0.2",
-  "description": "speedy search engine targeting an array of objects",
+  "version": "1.1.0",
+  "description": "fast search engine targeting array of objects or Map",
   "author": "gold",
   "main": "./src/search.ts",
   "type": "module",
@@ -14,14 +14,14 @@
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.34.0",
-    "@typescript-eslint/parser": "^8.34.0",
-    "eslint": "9.33.0",
-    "eslint-plugin-oxlint": "1.12.0",
-    "globals": "^16.2.0",
-    "oxlint": "1.12.0",
-    "prettier": "^3.5.3",
-    "tslib": "^2.8.1",
-    "typescript-eslint": "8.39.1"
+    "@typescript-eslint/parser": "8.56.0",
+    "eslint": "9.39.2",
+    "eslint-plugin-oxlint": "1.49.0",
+    "globals": "17.3.0",
+    "oxfmt": "0.34.0",
+    "oxlint": "1.49.0",
+    "tslib": "2.8.1",
+    "typescript-eslint": "8.56.0"
   },
   "repository": {
     "type": "git",

package/src/search.ts

@@ -1,14 +1,15 @@
 export type ItemRecord = Record<string, any>
+export type MapRecords = Map<string, ItemRecord>
 
 export interface ConfigParams {
-  items: ItemRecord[]
+  items: ItemRecord[] | MapRecords
   keys: string[]
   caseSensitive?: boolean
   enableMemoize?: boolean
 }
 
 interface Config {
-  Items: ItemRecord[]
+  Items: ItemRecord[] | MapRecords
   Keys: string[]
   RegexFlag: 'i' | undefined
   EnableMemoize: boolean
@@ -25,6 +26,8 @@ const escapeRegExp = (str: string): string => {
 const cache = new Map()
 
 const Conf: Config = {
+  // Items could be either an array or a map.
+  // run-time will handle detection and applicable syntax.
   Items: [],
   Keys: [],
   RegexFlag: 'i',
@@ -49,25 +52,36 @@ export const searchSetConfig = (params: ConfigParams): void => {
 // that it behooves the caller to this method be responsible for
 // correctly setting the config for this module and to check that the
 // search's query argument is a string.
-export const searchHandler = (query: string): ItemRecord[] => {
-  const results: ItemRecord[] = []
+export const searchHandler = (query: string): ItemRecord[] | MapRecords => {
   const qTrimmed = escapeRegExp(query.trim())
 
   if (qTrimmed === '') {
     return Conf.Items
   }
 
+  let results: ItemRecord[] | MapRecords
+
   if (Conf.EnableMemoize && cache.has(qTrimmed)) {
     return cache.get(qTrimmed)
   }
 
   const rx = new RegExp(qTrimmed, Conf.RegexFlag)
 
-  // All the dirty work is done here...
-  for (const item of Conf.Items) {
-    const searchString = Conf.Keys.map((k) => item[k]).join('^')
-    if (rx.test(searchString)) {
-      results.push(item)
+  if (Conf.Items instanceof Map) {
+    results = <MapRecords>new Map()
+    for (const [key, item] of Conf.Items) {
+      const searchString = Conf.Keys.map((k) => item[k]).join('^')
+      if (rx.test(searchString)) {
+        results.set(key, item)
+      }
+    }
+  } else {
+    results = <ItemRecord[]>[]
+    for (const item of Conf.Items) {
+      const searchString = Conf.Keys.map((k) => item[k]).join('^')
+      if (rx.test(searchString)) {
+        results.push(item)
+      }
     }
   }