itemsjs

    2.1.14 • Public • Published

    npm version GitHub package.json version NPM monthly downloads GitHub license

    ItemsJS - search engine in javascript

    Full text, faceted, dependency free search library in javascript. Created to perform fast search on json dataset (up to 100K items).

    Demo

    demo

    See another demo examples

    Use cases

    Itemsjs is being used mostly for data classification of companies, products, publications, documents, jobs or plants

    The solution has been implemented by people from Amazon, Hermes, Apple, Microsoft, James Cook University, Carnegie Mellon University and more. You can find a list of real implementations - here

    Features

    • faceted search
    • full text
    • pagination
    • no dependencies (only javascript)
    • working on backend and frontend
    • working with custom full text search

    Getting Started

    NPM

    npm install itemsjs
    const itemsjs = require('itemsjs')(data, configuration);
    const items = itemsjs.search();

    Client side

    or using from the client side:

    npm install itemsjs
    <!-- CDN -->
    <!-- unpkg: use the latest release -->
    <script src="https://unpkg.com/itemsjs@latest/dist/itemsjs.min.js"></script>
    <!-- unpkg: use a specific version -->
    <script src="https://unpkg.com/itemsjs@1.0.49/dist/itemsjs.min.js"></script>
    <!-- jsdelivr: use a specific version -->
    <script src="https://cdn.jsdelivr.net/npm/itemsjs@1.0.49/dist/itemsjs.min.js"></script>
    
    <!-- locally -->
    <script src="/node_modules/itemsjs/dist/itemsjs.js"></script>
    itemsjs = itemsjs(data, configuration);
    itemsjs.search()

    Gulp task:

    function itemjs() {
      return src('node_modules/itemsjs/dist/itemsjs.min.js')
          .pipe(dest('source/javascripts/'));
    }; // Will copy to source/javascripts/itemsjs.min.js

    Example

    npm install itemsjs
    
    # download json data
    wget https://raw.githubusercontent.com/itemsapi/itemsapi-example-data/master/items/movies-processed.json -O data.json

    Create search.js:

    var data = require('./data.json');
    
    var itemsjs = require('itemsjs')(data, {
      sortings: {
        name_asc: {
          field: 'name',
          order: 'asc'
        }
      },
      aggregations: {
        tags: {
          title: 'Tags',
          size: 10,
          conjunction: false
        },
        actors: {
          title: 'Actors',
          size: 10
        },
        genres: {
          title: 'Genres',
          size: 10
        }
      },
      searchableFields: ['name', 'tags']
    });
    
    /**
     * get filtered list of movies 
     */
    var movies = itemsjs.search({
      per_page: 1,
      sort: 'name_asc',
      // full text search
      // query: 'forrest gump',
      filters: {
        tags: ['1980s']
      }
    })
    console.log(JSON.stringify(movies, null, 2));
    
    /**
     * get list of top tags 
     */
    var top_tags = itemsjs.aggregation({
      name: 'tags',
      per_page: 10
    })
    console.log(JSON.stringify(top_tags, null, 2));

    Test that with :

    node search.js

    Integrations

    If native full text search is not enough then you can integrate with external full text search.

    How it works:

    • each item of your data needs to have id field
    • native_search_enabled option in configuration should be disabled
    • index data once in your search and itemsjs
    • make search in your custom search and provide ids data into itemsjs
    • done!

    Examples:

    API

    var itemsjs = ItemsJS(data, [configuration])

    data

    The first data argument is an array of objects.

    configuration

    Responsible for defining global configuration. Look for full example here - configuration

    • aggregations filters configuration i.e. for tags, actors, colors, etc. Responsible for generating facets.

    • sortings you can configure different sortings like tags_asc, tags_desc with options and later use it with one key.

    • searchableFields an array of searchable fields.

    • native_search_enabled if native full text search is enabled (true | false. It's enabled by default)

    itemsjs.search(options)

    options

    • per_page amount of items per page.

    • page page number - used for pagination.

    • query used for full text search.

    • sort used for sorting. one of sortings key

    • filters filtering items based on specific aggregations i.e. {tags: ['drama' , 'historical']}

    • filter function responsible for items filtering. The way of working is similar to js native filter function. See example

    • isExactSearch set to true if you want to always show exact search matches. See lunr stemmer and lunr stopWordFilter.

    • removeStopWordFilter set to true if you want to remove the stopWordFilter. See https://github.com/itemsapi/itemsjs/issues/46.

    • is_all_filtered_items set to true if you want to return the whole filtered dataset.

    itemsjs.aggregation(options)

    It returns full list of filters for specific aggregation

    options

    • name aggregation name
    • per_page filters per page
    • page page number
    • query used for quering filters. It's not full text search
    • conjunction choose between AND, OR

    itemsjs.similar(id, options)

    It returns similar items to item for given id

    options

    • field field name for computing similarity (i.e. tags, actors, colors)
    • minimum what is the minimum intersection between field of based item and similar item to show them in the result
    • per_page filters per page
    • page page number

    itemsjs.reindex(data)

    It's used in case you need to reindex the whole data

    data

    An array of objects.

    Install

    npm i itemsjs

    DownloadsWeekly Downloads

    1,745

    Version

    2.1.14

    License

    Apache-2.0

    Unpacked Size

    2.66 MB

    Total Files

    35

    Last publish

    Collaborators

    • cigolpl