Registry / serialization / search-query-parser

search-query-parser

library1.6.0jsnpmunverified

The `search-query-parser` library provides a robust, dependency-free solution for parsing advanced search query strings into a structured JavaScript object. It supports syntax similar to popular search engines, allowing for field-specific searches (e.g., `from:user`, `subject:topic`), date ranges (`date:1/10/2013-15/04/2014`), multi-value fields, and exclusion syntax (`-keyword:value`). The current stable version is 1.6.0, released over five years ago, indicating a mature and stable, but not actively developed, state. Key features include configurable keywords and range fields, optional tokenization of free text, the ability to always return matched keyword values as arrays, and the inclusion of character offsets for parsed elements. Since version 1.6.0, it also offers a `stringify` method to convert the parsed object back into a query string. This package primarily targets CommonJS environments, relying on the `require` syntax.

serialization

npm install search-query-parser

github ↗package ↗

INSTALL

IMPORT

SIG · SEARCH-QUERY-PARSE

search-query-parser

serializationjavascriptv1.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

searchQuery

✓ const searchQuery = require('search-query-parser');

✗ import searchQuery from 'search-query-parser';

This package is a CommonJS module. Use `require` for Node.js environments. Direct ES module `import` syntax is not supported without a transpiler or specific Node.js configuration for CJS interoperability.

parse

✓ const { parse } = require('search-query-parser');

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

While `parse` is a method of the default export, it can be destructured from the `require` call for conciseness in CommonJS.

stringify

✓ const { stringify } = require('search-query-parser');

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

`stringify` was added in v1.6.0. Ensure your package version is >=1.6.0. Like `parse`, it's available as a method of the default export and can be destructured.

Demonstrates parsing a complex search query with keywords, ranges, exclusion, and then stringifying the result. It highlights configuring parser options and accessing different parts of the parsed object.

const searchQuery = require('search-query-parser'); const query = 'from:hi@example.com,foo@example.org to:me subject:vacations date:1/10/2023-15/04/2024 important photos -archive'; const options = { keywords: ['from', 'to', 'subject', 'important'], ranges: ['date'], tokenize: true, alwaysArray: true, offsets: false }; const parsedQuery = searchQuery.parse(query, options); console.log('Parsed Query Object:'); console.log(JSON.stringify(parsedQuery, null, 2)); console.log('\nSpecific fields:'); console.log('From:', parsedQuery.from); // Expected: ['hi@example.com', 'foo@example.org'] console.log('To:', parsedQuery.to); // Expected: ['me'] console.log('Subject:', parsedQuery.subject); // Expected: ['vacations'] console.log('Text:', parsedQuery.text); // Expected: ['photos'] console.log('Date From:', parsedQuery.date.from); console.log('Excluded from archive:', parsedQuery.exclude.archive); const queryStringified = searchQuery.stringify(parsedQuery); console.log('\nStringified Query:', queryStringified);

Debug

Known issues

gotchaThe package is a CommonJS module and does not directly support ES module `import` syntax. Attempting to use `import` without proper transpilation or Node.js configuration for CJS interoperability will result in errors.

fix

Always use `const searchQuery = require('search-query-parser');` for importing the module in Node.js environments.

affects: >=1.0.0

gotchaThe `stringify()` method was introduced in version 1.6.0. Using this method on older versions of the library will result in a `TypeError`.

fix

Ensure `search-query-parser` is updated to version `1.6.0` or higher to use the `stringify()` method. Run `npm install search-query-parser@latest`.

affects: <1.6.0

gotchaBy default, if no keywords or ranges are matched and `tokenize` is `false`, the parser returns a plain string containing the remaining text, not an object. This can be unexpected when expecting a structured object every time.

fix

Set the `tokenize: true` option to receive non-keyword text terms as an array under the `text` key, or ensure keywords/ranges are configured to capture all intended structured data.

affects: >=1.0.0

gotchaThe `alwaysArray` option defaults to `false`. This means that keyword values might be returned as a string if only a single value is present, or an array if multiple values are present (e.g., `to:me` vs `from:a,b`). This inconsistency can lead to runtime type errors.

fix

Set `alwaysArray: true` in the options object (`{ alwaysArray: true }`) to ensure all matched keyword values are always returned as arrays, simplifying type handling.

affects: >=1.0.0

gotchaThe `offsets` option, which provides `offsetStart` and `offsetEnd` for parsed elements, defaults to `true`. While useful for highlighting or rich UI, these objects can become large with long queries, potentially impacting memory or object serialization if not needed.

fix

If offset information is not required, disable it by setting `offsets: false` in the options object to reduce the size of the parsed output.

affects: >=1.3.0

Errors

Common errors & fixes

TypeError: searchQuery.parse is not a function

Attempting to use ES module `import` syntax or destructuring the module incorrectly in a CommonJS environment, or trying to call `parse` on a non-module value.

fix

Ensure you are using `const searchQuery = require('search-query-parser');` and then calling `searchQuery.parse(query, options);`.

Cannot read properties of undefined (reading 'from') or property 'text' is not an array

This usually occurs when the parsed output is a string instead of an object (because no keywords/ranges were matched and `tokenize` was false) or when a keyword value is a string when an array was expected (due to `alwaysArray` being false).

fix

For consistent object output, always provide relevant `keywords` and `ranges` options. To ensure `text` is an array, set `tokenize: true`. For consistent array output for keyword values, set `alwaysArray: true`.

Upgrade

Version history

1.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nepsilon/search-query-parser ↗

packagehttps://www.npmjs.com/package/search-query-parser ↗