{"id":26294473,"url":"https://github.com/chrismichaelps/quantummatcher","last_synced_at":"2025-08-04T11:35:05.719Z","repository":{"id":275328771,"uuid":"925732601","full_name":"chrismichaelps/quantummatcher","owner":"chrismichaelps","description":"QuantumMatcher library is a fuzzy matching algorithm that leverages bitwise operations to efficiently find approximate matches within a collection of items.","archived":false,"fork":false,"pushed_at":"2025-02-04T00:04:26.000Z","size":280,"stargazers_count":21,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-13T10:52:06.067Z","etag":null,"topics":["algorithm","approximate","bitwise","fuzzy","matcher","matching","quantum","search"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/chrismichaelps.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-01T16:04:44.000Z","updated_at":"2025-05-18T06:18:19.000Z","dependencies_parsed_at":"2025-05-08T22:30:44.294Z","dependency_job_id":"ade28aa3-52ed-48ea-8a81-2777c140d347","html_url":"https://github.com/chrismichaelps/quantummatcher","commit_stats":null,"previous_names":["chrismichaelperezsantiago/quantummatcher","chrismichaelps/quantummatcher"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/chrismichaelps/quantummatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrismichaelps%2Fquantummatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrismichaelps%2Fquantummatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrismichaelps%2Fquantummatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrismichaelps%2Fquantummatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrismichaelps","download_url":"https://codeload.github.com/chrismichaelps/quantummatcher/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrismichaelps%2Fquantummatcher/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268689510,"owners_count":24291077,"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","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["algorithm","approximate","bitwise","fuzzy","matcher","matching","quantum","search"],"created_at":"2025-03-15T03:20:05.891Z","updated_at":"2025-08-04T11:35:05.691Z","avatar_url":"https://github.com/chrismichaelps.png","language":"TypeScript","readme":"# QuantumMatcher Library\n\n`QuantumMatcher` library is a fuzzy matching algorithm that leverages bitwise operations to efficiently find approximate matches within a collection of items.\n\nProject in progress ...\n\n## Prerequisites\n\n- [x] `Node.js \u003e= 18.x`\n- [x] `Yarn \u003e= 1.x`\n\n## Features\n\n- **Fuzzy Matching**: Efficiently finds approximate matches in a collection.\n- **Customizable Keys**: Specify which keys of the items to match against.\n- **Match Quality Calculation**: Considers match ratio, contiguity, position, and partial matches.\n- **Sorted Results**: Returns results sorted by match score.\n\n## Algorithm Explanation\n\nThe `QuantumMatcher` class uses a bitwise algorithm to perform fuzzy matching. Here's a breakdown of the process:\n\n1. **Normalization**:\n\n   - The query string is split into parts and normalized using the `normalizeText` function to standardize the text for comparison.\n\n2. **Character Mask Creation**:\n\n   - A character mask is created for each query part using the `createCharMask` method. This mask maps each character to a bitmask representing its positions in the string.\n\n3. **Bitwise Matching**:\n\n   - Bitwise operations are used to calculate matches. Bit vectors `VP`, `HN`, and `HP` track matches and mismatches.\n   - For each character in the normalized text, the algorithm updates the bit vectors based on the character mask.\n\n4. **Score Calculation**:\n\n   - The `calculateMatchQuality` method computes match quality using:\n     - **Match Ratio**: Ratio of matched characters to query length.\n     - **Contiguity**: Checks if matches are contiguous.\n     - **Position Bonus**: Rewards matches closer to the start of the text.\n     - **Partial Match Bonus**: Rewards partial matches if the query is found in the text.\n\n5. **Result Filtering and Sorting**:\n   - Results with a significant score (average score \u003e 0.5 per query part) are included.\n   - Results are sorted by score in descending order and filtered to include only perfect matches (score of 1).\n\n## Installation\n\nEnsure TypeScript is installed in your project. You can install it using npm:\n\n```shell\nnpm install quantummatcher\n# or\nyarn add quantummatcher\n```\n\n# 📚 Documentation\n\n```shell\nnpm run start\n# or\nyarn start\n```\n\n## Example Usage\n\n`constructor(collection: T[], private options: { keys?: (keyof T)[] })`\nThe QuantumMatcher class constructor takes two parameters:\n\n1. Collection : An array of items to search through. Each item should be an object with properties that can be matched against.\n2. Options : An object specifying the keys to match against. The keys property is an array of strings representing the keys in the items that should be considered for matching.\n\n```typescript\nimport { QuantumMatcher } from 'quantummatcher'\n\n// Define a collection of items\nconst options = [\n  {\n    id: 1,\n    title: 'Pythagorean Theorem',\n    description:\n      'In mathematics, the Pythagorean theorem states that in a right-angled triangle, the square of the hypotenuse is equal to the sum of the squares of the other two sides.',\n    tags: ['math', 'geometry', 'theorem'],\n  },\n  // ... more items ...\n]\n\n// Create an instance of QuantumMatcher\nconst matcher = new QuantumMatcher(options, {\n  keys: ['title', 'description', 'tags'],\n})\n\n// Find matches for a query\nconst output = matcher.findMatches('numbers')\nconsole.log(output)\n```\n\n## output:\n\n```json\n[\n  {\n    \"item\": {\n      \"id\": 5,\n      \"title\": \"Random String Example\",\n      \"description\": \"This is a random string that can be used for testing search functionality. It includes special characters like @#$%^\u0026* and numbers like 12345.\",\n      \"tags\": []\n    },\n    \"score\": 1,\n    \"matches\": [[]]\n  },\n  {\n    \"item\": {\n      \"id\": 7,\n      \"title\": \"Fibonacci Sequence\",\n      \"description\": \"The Fibonacci sequence is a series of numbers where each number is the sum of the two preceding ones, starting from 0 and 1.\",\n      \"tags\": []\n    },\n    \"score\": 1,\n    \"matches\": [[]]\n  },\n  {\n    \"item\": {\n      \"id\": 9,\n      \"title\": \"Another Random String\",\n      \"description\": \"This is another random string for testing purposes. It includes mixed case letters, numbers 67890, and symbols !@#$%^\u0026*().\",\n      \"tags\": []\n    },\n    \"score\": 1,\n    \"matches\": [[]]\n  }\n]\n```\n\n...\n\n## **:handshake: Contributing**\n\n- Fork it!\n- Create your feature branch: `git checkout -b my-new-feature`\n- Commit your changes: `git commit -am 'Add some feature'`\n- Push to the branch: `git push origin my-new-feature`\n- Submit a pull request\n\n---\n\n### **:busts_in_silhouette: Credits**\n\n- [Chris Michael](https://github.com/chrismichaelps) (Project Leader, and Developer)\n\n---\n\n### **:anger: Troubleshootings**\n\nThis is just a personal project created for study / demonstration purpose and to simplify my working life, it may or may\nnot be a good fit for your project(s).\n\n---\n\n### **:heart: Show your support**\n\nPlease :star: this repository if you like it or this project helped you!\\\nFeel free to open issues or submit pull-requests to help me improving my work.\n\n\u003ca href=\"https://www.buymeacoffee.com/chrismichael\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-red.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\n---\n\n### **:robot: Author**\n\n_*Chris M. Perez*_\n\n\u003e You can follow me on\n\u003e [github](https://github.com/chrismichaelps)\u0026nbsp;\u0026middot;\u0026nbsp;[twitter](https://twitter.com/Chris5855M)\n\n---\n\nCopyright ©2025 [QuantumMatcher](https://github.com/chrismichaelps/quantummatcher).\n","funding_links":["https://www.buymeacoffee.com/chrismichael"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrismichaelps%2Fquantummatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrismichaelps%2Fquantummatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrismichaelps%2Fquantummatcher/lists"}