JavaScript parser, stringifier and simplifier for Twitter search queries
Clone or download
tgvashworth feat: support URLs
Merge pull request #5 from tweetdeck/urls
Latest commit b544bab Nov 3, 2017
Type Name Latest commit message Commit time
Failed to load latest commit information.
grammar feat: basic url support Nov 3, 2017
src test: another test for urls Nov 3, 2017
.babelrc babelify Jun 21, 2016
.editorconfig editorconfig Jun 21, 2016
.gitignore npmify a bit Jun 22, 2016
.travis.yml chore: enable semantic-release Jun 27, 2016 CoC Jun 27, 2016
LICENSE chore: add LICENSE Jul 25, 2016 docs: not WIP anymore! Aug 1, 2016
package.json fix(deps): add missing babel-register dependency Jun 27, 2016
try.js More disallowed -> disallow Jun 23, 2016


semantic-release Build Status

Parser, simplifier and stringifier of Twitter search queries.


npm install --save twitter-search-query-parser


parse turns a search query into a data structure:

import {parse} from 'twitter-search-query-parser';

parse('@jack from:twitter') ===
  [ 'And',
    [ [ 'Including', [ 'Text', '@jack' ] ],
      [ 'Including', [ 'Pair', 'from', 'twitter' ] ] ] ]

stringify turns a data structure back into a query:

import {stringify} from 'twitter-search-query-parser';

  [ 'And',
    [ [ 'Including', [ 'Text', '@jack' ] ],
      [ 'Including', [ 'Pair', 'from', 'twitter' ] ] ] ]
) === '@jack from:twitter'

simplify squashes the data structure by turning complex types into text. This makes it easier to build an interface for the query, and it stringifies just the same.

import {parse, simplify} from 'twitter-search-query-parser';

const parsed = parse('@jack OR @twitter -(@support OR @twitterdev)');

parsed ===
  [ 'And',
    [ [ 'Including',
        [ 'Or',
          [ [ 'Including', [ 'Text', '@jack' ] ],
            [ 'Including', [ 'Text', '@twitter' ] ] ] ] ],
      [ 'Excluding',
        [ 'Group',
          [ 'And',
            [ [ 'Including',
                [ 'Or',
                  [ [ 'Including', [ 'Text', '@support' ] ],
                    [ 'Including', [ 'Text', '@twitterdev' ] ] ] ] ] ] ] ] ] ] ]

const simplified = simplify(parsed, {
  disallow: ['Group', 'Or']

simplified ===
  [ 'And',
    [ [ 'Including', [ 'Text', '@jack OR @twitter' ] ],
      [ 'Excluding', [ 'Text', '(@support OR @twitterdev)' ] ] ] ]


The parsed data stucture follows the format: [Type, ...values]. The nature of the values depends on the Type.


Represents a text value, including hashtags, mentions and cashtags. For example:


Contains a single string value.

['Text', 'x']


Represents an exact text match, in quotes.

"b c"

Contains one string value.

['Exactly', 'b c']


Represents a conjunction of other terms, and is the root of the query and grouped sub-queries. For example:

x #y

Contains an Array value of other terms.

['And', [ ... ]]


Represents a disjunction of other terms. For example:

x OR #y

Contains an Array value of other terms.

['Or', [ ... ]]


Represents the inclusion of the contained term. Every term is either included or excluded.

Contains a single value, another term.

['Including', ['Text', 'x']]


Represents the exclusion of the contained term. Every term is either included or excluded.

Contains a single value, another term.

['Excluding', ['Text', 'x']]


Represents a group of terms. For example:

(a b) OR (c d)

Contains a single value, another term.

['Group', [ ... ]]


Represents a search facet operator. For example:

filter:vine exclude:retweets

Contains two string values: they key and the value.

['Pair', 'filter', 'vine']


Represents a list facet operator.


Contains two values: user name and list slug.

['List', 'NASA', 'astronauts-in-space-now']

Known bugs

  • This library has only been tested in English and likely has insufficient query parsing cababilities in other alphabets


$ npm install
$ npm run gen
$ npm run try "some -search from:twitter @jack #tagged OR \"exactly this\""

Commit messages should follow the Angular commit message guidelines.


This repository uses semantic-release. Changes will automatically be released to npm.