search-gold 0.9.0

package/README.md

@@ -0,0 +1,111 @@
+# search-gold
+
+## Overview
+
+Your page displays a list columnar information, based on the ubiquitous data stucture:
+
+`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
+
+```bash
+$ npm i search-gold
+```
+OR
+```bash
+$ bun i search-gold
+```
+
+## Usage
+
+The following should provide enough to get things up and running.
+
+`my-data-list-component.ts`
+```javascript
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// 1. Import the two types and methods.
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+import {
+  ConfigParams,
+  ItemRecord,
+  searchHandler,
+  searchSetConfig,
+} from 'search-gold'
+
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// 2. Create a method to set search configuration.
+//
+// The configuration will be custom for your data.
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+const initSearchConfig = () => {
+  const config: ConfigParams = {
+    // required: items must reference an array of
+    // objects.
+    //
+    // 'search-gold' package only reads this data.
+    // 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,
+  },
+
+  searchSetConfig(config)
+
+  // Passing an empty string effectively returns
+  // the unfiltered set, 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 module is initialized and your data is ready.
+//
+// Also, it should be called whenever your data
+// changes via record create, edit, or delete.
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+initSearchConfig()
+
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// 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.
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+const searchMyData = (query: string) => {
+  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.
+
+I tried to keep the Usage code examples framework
+neutral.
+
+# Credits
+
+G. Gold
+
+October 2025
+
+Have fun!

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "search-gold",
+  "private": false,
+  "version": "0.9.0",
+  "description": "speedy search engine targeting an array of objects",
+  "author": "gold",
+  "main": "./src/search.ts",
+  "type": "module",
+  "files": [
+    "./src/search.ts"
+  ],
+  "scripts": {
+    "lint": "npx oxlint ./src/search.ts && npx eslint ."
+  },
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/gold/search-gold.git"
+  },
+  "keywords": [
+    "data search",
+    "search",
+    "data filter",
+    "simple search",
+    "fast search"
+  ],
+  "license": "MIT",
+  "homepage": "https://codeberg.org/gold/search-gold"
+}

package/src/search.ts

@@ -0,0 +1,66 @@
+export type ItemRecord = Record<string, any>
+
+export interface ConfigParams {
+  items: ItemRecord[]
+  keys: string[]
+  caseSensitive?: boolean
+}
+
+interface Config {
+  Items: ItemRecord[]
+  Keys: string[]
+  CaseSensitive: boolean
+  RegexFlag: 'i' | undefined
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
+//
+// RegExp.escape() is a relatively new addition to JS, thus for now
+// we continue to use the following tried and true functionality.
+const escapeRegExp = (str: string): string => {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+const Conf: Config = {
+  Items: [],
+  Keys: [],
+  CaseSensitive: false,
+  RegexFlag: 'i',
+}
+export const searchSetConfig = (params: ConfigParams): void => {
+  const { items, keys, caseSensitive = false } = params
+  Conf.Items = items
+  Conf.Keys = keys
+  Conf.CaseSensitive = caseSensitive
+  Conf.RegexFlag = caseSensitive ? undefined : 'i'
+}
+
+// Since (if no debounce) every search input keystroke calls this
+// method, performance has been optimized: there is no run-time type
+// guarding and no try-catch blocks; regex escaping is still necessary
+// though and has been encapsulated in this module.
+//
+// For a better run-time UX -- no errors and speedy execution -- we feel
+// 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[] = []
+  const qTrimmed = escapeRegExp(query.trim())
+
+  if (qTrimmed === '') {
+    return Conf.Items
+  }
+
+  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)
+    }
+  }
+
+  return results
+}