search-gold 0.9.0 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Your page displays a list columnar information, based on the ubiquitous data stucture:
+Your web page displays a list of columnar information, based on the common data stucture:
 
 `array of objects`
 
@@ -22,25 +22,30 @@ $ bun i search-gold
 
 ## Usage
 
-The following should provide enough to get things up and running.
+The following should provide enough to get local search up and running and keep your users in a happy place!
 
-`my-data-list-component.ts`
+Provide the following in your component, e.g., `my-data-list-component.ts`.
+
+### 1. Import the two types and methods.
 ```javascript
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// 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)
 
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// 2. Create a method to set search configuration.
-//
-// The configuration will be custom for your data.
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can name this wrapper method anything you want.
+
+```javascript
 const initSearchConfig = () => {
   const config: ConfigParams = {
     // required: items must reference an array of
@@ -57,50 +62,63 @@ const initSearchConfig = () => {
 
     // 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)
 
-  // Passing an empty string effectively returns
-  // the unfiltered set, the same as MyData.
+  // After setting the config, you can call searchHandler()
+  // as many times as necessary without having to set the
+  // config again.
   //
-  // How you set up your component to display
-  // the filtered data is up to you and how
-  // your component is structured. This is just
-  // an example.
+  // Passing an empty string effectively returns the
+  // the unfiltered set of records, the same as MyData.
+  //
+  // How you set up your component to display the filtered
+  // data is up to you and how your component is structured.
+  // This is just an example.
   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.
 
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// 3. Initialize the search engine.
-//
-// This method (from step 2.) should be called when
-// your module is initialized and your data is ready.
-//
-// Also, it should be called whenever your data
-// changes via record create, edit, or delete.
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```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.
 
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-// 4. Perform search queries (finally!)
-//
-// Presumably, a method is binded to the UI's
-// search field (in this example it's called
-// 'searchMyData') and is called on every keystroke.
-//
-// You can optionally add a debounce in your component.
-// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 is left up to the front end developer.
+```javascript
 const searchMyData = (query: string) => {
+  // Call the imported method and get results.
   myFilteredData = searchHandler(query)
 }
 ```
 
-During development, I integrated this `search-gold` package
-in a couple of apps I had built using Vue and its Composition API.
+## Author's Development
+
+During development of the `search-gold` package, I integrated it
+into a several  apps I had built with Vue using its Composition API.
 
-I tried to keep the Usage code examples framework
-neutral.
+In this documentation I tried to keep the Usage code snippets framework neutral.
 
 # Credits
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "search-gold",
   "private": false,
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "speedy search engine targeting an array of objects",
   "author": "gold",
   "main": "./src/search.ts",
@@ -30,6 +30,9 @@
   "keywords": [
     "data search",
     "search",
+    "local search",
+    "search for gold",
+    "search for 金",
     "data filter",
     "simple search",
     "fast search"

package/src/search.ts

@@ -4,13 +4,14 @@ export interface ConfigParams {
   items: ItemRecord[]
   keys: string[]
   caseSensitive?: boolean
+  enableMemoize?: boolean
 }
 
 interface Config {
   Items: ItemRecord[]
   Keys: string[]
-  CaseSensitive: boolean
   RegexFlag: 'i' | undefined
+  EnableMemoize: boolean
 }
 
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
@@ -21,18 +22,22 @@ const escapeRegExp = (str: string): string => {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+const cache = new Map()
+
 const Conf: Config = {
   Items: [],
   Keys: [],
-  CaseSensitive: false,
   RegexFlag: 'i',
+  EnableMemoize: true,
 }
 export const searchSetConfig = (params: ConfigParams): void => {
-  const { items, keys, caseSensitive = false } = params
+  const { items, keys, caseSensitive = false, enableMemoize = true } = params
   Conf.Items = items
   Conf.Keys = keys
-  Conf.CaseSensitive = caseSensitive
   Conf.RegexFlag = caseSensitive ? undefined : 'i'
+  Conf.EnableMemoize = enableMemoize
+
+  cache.clear()
 }
 
 // Since (if no debounce) every search input keystroke calls this
@@ -52,6 +57,10 @@ export const searchHandler = (query: string): ItemRecord[] => {
     return Conf.Items
   }
 
+  if (Conf.EnableMemoize && cache.has(qTrimmed)) {
+    return cache.get(qTrimmed)
+  }
+
   const rx = new RegExp(qTrimmed, Conf.RegexFlag)
 
   // All the dirty work is done here...
@@ -62,5 +71,9 @@ export const searchHandler = (query: string): ItemRecord[] => {
     }
   }
 
+  if (Conf.EnableMemoize && qTrimmed.length >= 3) {
+    cache.set(qTrimmed, results)
+  }
+
   return results
 }