Match highlight plugin

The plugin-match-highlight plugin allows Orama to keep track of all token positions on each property of each document.

Installation

You can install the plugin using any major Node.js package manager:

npm install @orama/plugin-match-highlight 

Usage

Plugin usage depends on the runtime that you are using, even though the goal is to expose the exact same APIs for browsers, Deno, and all the other JavaScript engines.

The plugin exports afterInsertHook, which will be the hook used by Orama to add positions, and searchWithHighlight which wraps the original Orama's search function to return positions alongside docs.

import { afterInsert as highlightAfterInsert, searchWithHighlight } from '@orama/plugin-match-highlight'
import { create, insert } from '@orama/orama'
 
// Create a new Orama instance
const db = await create({
  schema: {
    text: 'string'
  },
  components: {
    // Register the hook
    afterInsert: [highlightAfterInsert]
  }
})
 
// Insert a document
await insert(db, { text: 'hello world' })
 
// Use the plugin's searchWithHighlight function to query the database
const results = await searchWithHighlight(db, 'hello')

This will add the positions property to each hit:

{
  elapsed: {...},
  count: ...,
  hits: [
    {
      id: ...,
      score: ...,
      document: { text: 'hello world' },
      positions: {
        text: {
          hello: [
            {
              start: 0,
              length: 5
            }
          ]
        }
      }
    }
  ]
}

CommonJS Imports

Orama plugins ship ESM modules by default. This allows us to move faster when providing new features and bug fixes, as well as using the "exports" field in package.json to provide a better developer experience.

CommonJS imports are still supported, but we suggest you to migrate to ESM.

TypeScript

Set moduleResolution in the compilerOptions in your tsconfig.json to be either Node16 or NodeNext.

When importing types, always refer to the standard import:

import { searchWithHighlight } from '@orama/plugin-match-highlight'