New Patch, Merge?

    @umanghome/fuzzysort

    0.0.1 • Public • Published

    Fuzzysort

    A fuzzy-searching library for JavaScript

    Build Status

    This is a fork of farzher/fuzzysort with some significant changes:

    • Tree-shakable
    • Only synchronous searching
    • No global cache
    • Only works on objects

    The original repository describes this as

    Fast SublimeText-like fuzzy search for JavaScript. Sublime's fuzzy search is... sublime. I wish everything used it. So here's an open source js version.

    Demo at https://umanghome.github.io/fuzzysort/demo.html

    Installation

    Node

    npm install @umanghome/fuzzysort

    and use as

    const fuzzysort = require('@umanghome/fuzzysort');

    or

    import * as fuzzysort from '@umanghome/fuzzysort';

    Browser

    Download and serve dist/fuzzysort.umd.js

    <script src="fuzzysort.umd.js"></script>

    The library will be available under window.fuzzysort

    Exports

    • search - The core function you will use for searching.
    • createCache - For better performance, you should pass a cache to search. This function creates the necessary cache.
    • algorithmWithTypo - You will need to pass an algorithm to search. This algorithm allows a mismatch of one character.
    • algorithmWithoutTypo - You will need to pass an algorithm to search. This algorithm does not allow a mismatch.

    Usage

    createCache

    const cache = createCache();

    A cache can be reused between searches for to gain performance improvement. The recommended way to use a cache using a single cache for different searches across the same targets. If the targets change entirely, use a different cache. This can translated loosely to mean use the same cache for multiple terms across the same targets, but a different cache for each target.

    It's a good idea to free up memory when you know no further searches will be made using the cache. To clear all the internal caches, use

    const cache = fuzzysort.createCache();
    
    // Do stuff
    
    cache.clear();

    The unmount lifecycle hook of your UI component is a good place to use this.

    search

    search(
      term: string, // The search term
      targets: Array<Object>, // The list of objects to search on
      keys: Array<string>, // The keys on each object to consider
      options: Object // Misc. options (see below)
    ): ({
      results: Array<Object>,
      total: number 
    })
    options = {
      algorithm: fuzzysort.algorithmWithTypo, // The algorithm to use
    
      // Optional
      cache: createdCache, // The cache that is created. See `createCache` usage for details.
      limit: 10, // The limit of results to return. Picks the top `limit` results. Default: 9007199254740991
      threshold: -100, // Considers results with a score greater than or equal to `threshold`. Default: -9007199254740991
    }

    keys is the list of keys to search on. Nested keys can be represented as "foo.bar". Example: ["name", "contact.phone"] if your target looks like

    {
      name: 'John Doe',
      contact: {
        phone: '9988776655'
      }
    }

    search returns an object with two keys:

    • results - An array of objects of the shape
    {
      ref: Object; // Reference to the original object in `targets`. Equality check will work since this is an object ref.
      score: number; // The score of the match
    }
    • total - The total number of matches. This might be different than results.length if options.limit is used.

    • meta - An object containing meta-information for all the matches. It is an object with keys as every key of keys. See usage for an example. Each object under meta[key] looks like

    {
      indices: Array<number> | null; // The indices matched, if at all
      score: number | null; // The score if we found any matching characters
      target: string; // The string that we performed the search on
    }

    Example

    const Banks = [
      {
        "code": "HDFC",
        "name": "HDFC Bank"
      },
      {
        "code": "ICIC",
        "name": "ICICI Bank"
      },
      {
        "code": "IOBA",
        "name": "Indian Overseas Bank"
      },
      {
        "code": "SBIN",
        "name": "State Bank of India"
      },
      {
        "code": "UBIN",
        "name": "Union Bank of India"
      },
    ];
    
    const cache = fuzzysort.createCache();
    
    const results = fuzzysort.search('india', Banks, ['name'], {
      algorithm: fuzzysort.algorithmWithTypo,
      cache: cache,
      limit: 2,
    });
    
    cache.clear();
    
    console.log(results);

    will log

    {
      "results": [
        {
          "ref": {
            "code": "IOBA",
            "name": "Indian Overseas Bank"
          },
          "meta": {
            "name": {
              "indices": [0, 1, 2, 3, 4],
              "score": -15,
              "target": "Indian Overseas Bank"
            }
          },
          "score": -15
        },
        {
          "ref": {
            "code": "SBIN",
            "name": "State Bank of India"
          },
          "meta": {
            "name": {
              "indices": [14, 15, 16, 17, 18],
              "score": -28,
              "target": "State Bank of India"
            }
          },
          "score": -28
        }
      ],
      "total": 3
    }

    TODO

    • [ ] Document how to highlight
    • [ ] Allow and document custom scoreFn
    • [ ] Add tests for algorithmWithTypo
    • [ ] Add tests for algorithmWithoutTypo
    • [ ] Modernize algorithmWithTypo
    • [ ] Modernize algorithmWithoutTypo
    • [ ] Fix and add types
    • [ ] Maybe migrate to TypeScript

    License

    This project is licensed under the MIT License - see the LICENSE file for details.

    Install

    npm i @umanghome/fuzzysort

    DownloadsWeekly Downloads

    15

    Version

    0.0.1

    License

    MIT

    Unpacked Size

    86.4 kB

    Total Files

    23

    Last publish

    Collaborators

    • umanghome