{"id":17579035,"url":"https://github.com/mlms13/simplesearch","last_synced_at":"2026-02-23T15:31:33.733Z","repository":{"id":19747144,"uuid":"23003979","full_name":"mlms13/SimpleSearch","owner":"mlms13","description":"Powerful list searching in simple packaging.","archived":false,"fork":false,"pushed_at":"2016-01-25T15:46:04.000Z","size":252,"stargazers_count":3,"open_issues_count":7,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-22T18:18:26.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlms13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-15T21:46:42.000Z","updated_at":"2021-09-20T18:52:26.000Z","dependencies_parsed_at":"2022-07-12T15:17:25.906Z","dependency_job_id":null,"html_url":"https://github.com/mlms13/SimpleSearch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2FSimpleSearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2FSimpleSearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2FSimpleSearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlms13%2FSimpleSearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlms13","download_url":"https://codeload.github.com/mlms13/SimpleSearch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230575852,"owners_count":18247484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-22T00:43:23.741Z","updated_at":"2026-02-23T15:31:33.690Z","avatar_url":"https://github.com/mlms13.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleSearch\n\nSimpleSearch is becoming a powerful JavaScript tool to filter an array for matched (and approximately matched) strings.\n\n## Installation and Setup\n\nWe use UMD to maintain compatibility with several popular module systems.\n\n### CommonJS Setup (for environments like Node.js and Browserify)\n\nInstall SimpleSearch...\n\n```\nnpm install --save simplesearch\n```\n\n...and require it in your project\n\n```javascript\nvar SimpleSearch = require('simplesearch');\nSimpleSearch.filter(...);\n```\n\n### AMD Setup (for Require.JS)\n\n**Disclaimer:** it's been awhile since I've used Require.JS, and I'm no expert. This method is currently untested, but it should work.\n\nInstall SimpleSearch by downloading a [tagged release](https://github.com/mlms13/SimpleSearch/releases). Or you could install with npm and dig it out of the `node_modules` folder... I don't really know the preferred way to do package management in AMD environments.\n\nThen, start using it like this:\n\n```javascript\nrequire(['path/to/simplesearch.js'], function(SimpleSearch) {\n  SimpleSearch.filter(...);\n});\n```\n\n### No module loader? No problem.\n\nIf you're just looking to dump a script into your page, we can work with that. Start by [downloading the latest release](https://github.com/mlms13/SimpleSearch/releases).\n\n```html\n\u003cscript src=\"/path/to/simplesearch.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  window.SimpleSearch.filter(...);\n\u003c/script\u003e\n```\n\n## Usage\n\nThe SimpleSearch object defines two useful methods related to filtering and matching text.\n\n### SimpleSearch.matches(item, search)\n\nGiven an item to test against and a search string to look for, return true\nor false, depending on whether the match is found, according to our criteria:\n - The search string can leave out characters\n - Search string cannot get character order wrong\n - Ignore spaces in the search string\n - Ignore other non-alphanumeric characters in the search string\n - Word order of the target item doesn't matter\n\n**Parameters**\n\n- **item**: `string`, The string to be searched for matches\n\n- **search**: `string`, The string of characters we are searching for\n\n**Returns**: `Boolean`\n\n**Example**:\n```js\nSimpleSearch.matches('foobar', 'fbr'); // returns true\nSimpleSearch.matches('foobar', 'bf'); // returns false\nSimpleSearch.matches('foo', 'f oo!'); // returns true\nSimpleSearch.matches('bar (foo)', foobar); // returns true\n```\n\n\n### SimpleSearch.filter(data, search)\n\nGiven an array as the first paramater and a string of search text as the\nsecond, filter() will return a new array that is a subset of the original.\nThe results are filtered according to the criteria listed for matches().\n\n**Parameters**\n\n- **data**: `Array.\u0026lt;string\u0026gt;`, Array of strings that will be filtered\n\n- **search**: `string`, The string of characters we are searching for\n\n**Returns**: `Array.\u0026lt;string\u0026gt;`, - A new array, a subset of the original data\n\n**Example**:\n```js\nSimpleSearch.filter([\"foo\", \"bar\", \"baz\"], \"ba\"); // returns [\"bar\", \"baz\"]\n```\n\n\n## Roadmap\n\nThe `matches` function has some hard-coded rules about how spaces, special characters, text case, and word order work.  All of that will soon be configurable.\n\nFilter currently only handles arrays of strings. Filtering an array of objects is coming next.\n\n```javascript\n// data as an array of objects instead of strings\nvar data = [{\n  name: \"berry\",\n  alias: [\"strawberry\", \"acai\", \"blueberry\"]\n}, {\n  name: \"chickpea\",\n  alias: \"garbanzo bean\"\n}, {\n  name: \"apple, raw\"\n}];\n```\n\nInstead of passing an array and a search string to `filter`, you will be able to pass a big configuration object.\n\n```javascript\n// filter(obj)\nSimpleSearch.filter({\n  data: data,\n  fields: [\"name\", \"alias\"], // fields to be searched, ordered by preference.\n                             // we only search \"alias\" if \"name\" doesn't match\n  exactMatch: false, // if set to true, \"ba\" would not match \"bean\"\n  splitWords: true, // if set to false, \"bean garb\" wouldn't match \"garbanzo bean\"\n  punctuation: false, // if set to true, \"(raw)\" wouldn't match \"raw\"\n  success: function (match) {\n    // a callback function to be run for each matching item\n    // receives a `match` object with the following properties\n    // - `field` -- the field in which the match was found\n    // - `original` -- original object (from data array) in which match was found\n    // - `charPos` -- array of indexes of matched characters\n    //                e.g. [0, 1, 3] for \"bean\" given search string \"ben\"\n  },\n  fail: function (original) {\n    // callback to be run if match fails\n    // receives the original object that was tested for a match\n  }\n});\n```\n\nFarther future, we're looking into the Levenshtein algorithm to do fuzzy matching. This way, we'll be able to:\n\n- Give each match a score, based on similarity to the search term\n- Sort by score before returning the filtered array (and before calling success/fail callback functions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlms13%2Fsimplesearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlms13%2Fsimplesearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlms13%2Fsimplesearch/lists"}