@projekt-apollo/query-parser v0.3.1

query-parser

A lightweight TypeScript library for parsing simple search syntax into a structured AST and query object, inspired by Gmail, GitHub, and Discord query systems.

Installation

npm install @projekt-apollo/query-parser

Usage

import {parse} from '@projekt-apollo/query-parser'

const query = parse(`tag:language "typescript" regex, class`)
/* => [
  {filter: 'tag', value: 'language'},
  {filter: 'exact', value: 'typescript'},
  {filter: 'keyword', value: 'regex'},
  {filter: 'keyword', value: 'class'},
] */

tokenize(input: string): Tokens

const tokens = tokenize(`tag:language "typescript" regex, class`)
/* => [
  { type: 'ColonFilter', filter: 'tag', value: 'language' },
  { type: 'ExactTerm', value: 'typescript' },
  { type: 'KeywordTerm', value: 'regex' },
  { type: 'CommaDelimiter', value: ',' },
  { type: 'KeywordTerm', value: 'class' },
];
] */

build(tokens: Tokens): Query

const query = build(tokens)
/* => [
  {filter: 'tag', value: 'language'},
  {filter: 'exact', value: 'typescript'},
  {filter: 'keyword', value: 'regex'},
  {filter: 'keyword', value: 'class'},
] */

parse(input: string): Query

Combines the tokenize and build functions. Accepts a string and returns a Query array.

Syntax

The Query object is an array of QueryFilter objects. Each QueryFilter represents a filter constraint for a particular query on some property. For example this is a QueryFilter that filters on a property of language with the value typescript:

{filter: 'language', value: 'typescript'}

The QueryFilter above is represented using the following syntax:

language:typescript

A query syntax without the colon operator is a shorthand for a QueryFilter with the filter value set to keyword:

javascript => {filter: 'keyword', value: 'javascript'}

If a comma is present between two keywords, it will be parsed as two separate keyword filters. Otherwise two adjacent keywords are parsed as one keyword filter:

javascript typescript => {filter: 'keyword', value: 'javascript typescript'}

javascript, typescript => {filter: 'keyword', value: 'javascript'}, {filter: 'keyword', value: 'typescript'}

Likewise, a query syntax that surrounds a string with single or double quotes is a shorthand for a QueryFilter with the filter value set to exact:

"regex" => {filter: 'exact', value: 'regex'}

This quote syntax can also be used for a filter value containing whitespace(s):

tag:"ux design" => {filter: 'tag', value: 'ux design'}

Contributing

This project is not currently open to pull requests. But for bugs and suggestions, please feel free to open an issue.

Acknowledgment

Thank you to the authors of the following libraries for inspiration.

• search-query-parser
• n-search-parser

License

MIT