Search Query AST Parser for JS

NPM | Documentation

This is a package for JS applications that parses search queries with the common search operator features such as logical or/and, grouping, phrases (in quotes), etc.

This package only implements a very simple filter utility function that takes a list of items or objects with a map to string function, and returns elements matching the query.

For more advanced use-cases, you can easily implement your own filter function.
See utils.ts#filter for an example.

---

Table of contents

• Example results
• How to use
• Supported operators
  • Implemented
  • To Do

---

Example results

Input: orange OR "golden apple"

Explanation: the word "orange" or the exact phrase "golden apple"

Output:

const result = [
  {
    type: 'operator',
    value: 'or',
    left: {
      type: 'word',
      value: 'orange',
    },
    right: {
      type: 'phrase',
      value: 'golden apple',
      quote: '"',
    },
  },
]
Copy

Input: (mango banana lemon) OR apple -pineapple

Explanation: Either one of the words: "mango", "banana", or "lemon"; OR the word "apple"; exclude all results containing "pineapple"

Output:

const result = [
  {
    type: 'operator',
    value: 'or',
    left: {
      type: 'group',
      children: [
        {
          type: 'word',
          value: 'mango',
        },
        {
          type: 'word',
          value: 'banana',
        },
        {
          type: 'word',
          value: 'lemon',
        },
      ],
    },
    right: {
      type: 'word',
      value: 'apple',
    },
  },
  {
    type: 'exclude',
    value: 'pineapple',
  },
]
Copy

How to use

Install the package using pnpm, npm or yarn:

pnpm add search-parse
npm install search-parse
yarn add search-parse
Copy

Simply pass a string to the parse function to get the results.

import { parse } from 'search-parse'
const results = parse('(mango banana lemon) OR apple -pineapple')
Copy

Supported operators

This is the comprehensive list of operators and their object results:

Implemented

• Word: example

  Any single word. Only alpha-numeric characters, dashes and underscores are considered a word. The rest is considered whitespace, which is ignored by the parser, but will cause the surrounding tokens to be broken apart.

  Object:

  {
    type: 'word', // constant
    value: 'example' // this is the actual word in the string
  }
  Copy

• Phrase: "an example" or 'an example'

  A phrase can contain one or more characters. These characters are used as is and not validated as words, so they can include all sorts of special characters.

  A phrase can start with either a single or double quote, and must terminate using the same quote. The other type of quote than the one starting this sequence is ignored and considered part of the phrase itself when it inside it.

  Object:

  {
    type: 'phrase', // constant
    value: 'an example', // the phrase contained in the quote
    quote: '"' // the quote used to start and end this sequence
  }
  Copy

• Group: (one two three)

  A group can consist of one or more words or other types of values such as phrases or exclusions. A group logically puts its contents together, usually this is meant as an implicit OR operation but you can implement it as you require.

  Object:

  {
    type: 'group', // constant
    children: [
      // all types of children nodes such as word, phrase, etc
      {
        type: 'word',
        value: 'one'
      },
      {
        type: 'word',
        value: 'two'
      },
      {
        type: 'word',
        value: 'three'
      }
    ]
  }
  Copy

• Logical operators OR and AND: a OR b or a | b, and a AND b or a & b

  Logical operators group their immediate left and immediate right in a logical operation.

  Object:

  {
    type: 'operator',
    value: 'or', // or: 'and'
    left: { // whatever is on the left of the operator - word, phrase, etc
      type: 'word',
      value: 'a'
    },
    right: { // whatever is on the right of the operator - word, phrase, etc
      type: 'word',
      value: 'b'
    }
  }
  Copy

To Do

• Exclusion: -example

  An exclusion is an indication to not include results using the given word, phrase or group.

  Object:

  {
    type: 'exclusion',
    value: { // all types of children nodes such as word, phrase, etc
      type: 'word',
      value: 'example'
    }
  }
  Copy

• Domain: example-domain:example-token

  A domain prefix signals the following token to only refer to the prefixing domain. For example, a user could search name:apple to only search the word apple within the name property of the object being searched on.

  Object:

  {
    type: 'domain',
    domain: 'example-domain',
    value: { // all types of children nodes such as word, phrase, etc
      type: 'word',
      value: 'example-token',
    }
  }
  Copy

• User: @example-user

  A user query can signal only searching content from a specific user.

  Object:

  {
    type: 'user',
    value: 'example-user',
  }
  Copy