liqe

Liqe provides high-level functions to perform in-memory searches on JSON documents using the Liqe Query Language (LQL).

• filter(parsedQuery, collection): Returns a subset of the collection that matches the query.
• test(parsedQuery, object): Returns true if the specific object matches the query, otherwise false.
• highlight(parsedQuery, object): Returns an array of match metadata, including the path to the field and a query (RegExp) for the matching substring, useful for UI highlighting.

import {
  filter,
  highlight,
  parse,
  test,
} from 'liqe';

const persons = [
  { height: 180, name: 'John Morton' },
  { height: 175, name: 'David Barker' },
  { height: 170, name: 'Thomas Castro' },
];

// Filter a collection
filter(parse('height:>170'), persons);

// Test a single object
test(parse('name:John'), persons[0]); // true

// Highlight matches
highlight(parse('name:john'), persons[0]);
// [
//   { path: 'name', query: /(John)/ }
// ]

LQL is a Lucene-inspired language for searching JSON documents.

Keyword & Phrase Matching

• foo: Case-insensitive search for "foo" anywhere in the document.
• 'foo' or "foo": Case-sensitive search for "foo".
• name:foo: Search for "foo" in the name field.
• 'full name':foo: Search for "foo" in a field with spaces.
• name.first:foo: Search for a nested field (e.g., {name: {first: 'foo'}}).

Regex & Wildcards

• name:/foo/: Regex search.
• name:/foo/o: Regex search with specific flags.
• name:foo*bar: Wildcard search (* for multiple characters).
• name:foo?bar: Wildcard search (? for a single character).

Numbers & Ranges

• height:=100: Exact match.
• height:>100, height:>=100, height:<100, height:<=100: Comparison operators.
• height:[100 TO 200]: Inclusive range.
• height:{100 TO 200}: Exclusive range.

Boolean Operators

• AND, OR, NOT, -: Standard boolean logic.
• name:foo height:=100: Implicit AND operator.
• (expression): Grouping expressions.

Special Values

• member:true / member:false: Boolean search.
• member:null: Null search.

# search for "foo" term anywhere in the document (case insensitive)
foo

# search for "foo" term anywhere in the document (case sensitive)
'foo'
"foo"

# search for "foo" term in `name` field
name:foo

# search for "foo" term in `full name` field
'full name':foo
"full name":foo

# search for "foo" term in `first` field, member of `name`, i.e.
# matches {name: {first: 'foo'}}
name.first:foo

# search using regex
name:/foo/
name:/foo/o

# search using wildcard
name:foo*bar
name:foo?bar

# boolean search
member:true
member:false

# null search
member:null

# search for age =, >, >=, <, <=
height:=100
height:>100
height:>=100
height:<100
height:<=100

# search for height in range (inclusive, exclusive)
height:[100 TO 200]
height:{100 TO 200}

# boolean operators
name:foo AND height:=100
name:foo OR name:bar

# unary operators
NOT foo
-foo
NOT foo:bar
-foo:bar
name:foo AND NOT (bio:bar OR bio:baz)

# implicit AND boolean operator
name:foo height:=100

# grouping
name:foo AND (bio:bar OR bio:baz)

The highlight function identifies matching parts of a data object based on a provided LiqeQuery AST. It returns an array of Highlight objects, where each object specifies a path (the location in the data object) and a query (a regular expression used to match the keywords found at that path). This is useful for UI components that need to visually emphasize search terms within search results.

Parameters:

• ast: A LiqeQuery representing the search query structure.
• data: The data object T to be scanned for matches.

Returns: An array of Highlight objects. Each object contains:

• path: A string representing the path to the matched data.
• query (optional): A RegExp constructed from the keywords found at that path, used to identify the exact substrings to highlight.

import { highlight } from './highlight';

// Example usage (conceptual):
// const highlights = highlight(queryAst, dataObject);
// highlights.forEach(({ path, query }) => {
//   if (query) {
//     console.log(`At ${path}, match with regex: ${query}`);
//   }
// });

The serialize function converts a LiqeQuery Abstract Syntax Tree (AST) back into its original Liqe query string representation. This is useful for debugging, logging, or reconstructing queries after programmatic manipulation of the AST.

Supported AST types include:

• Tag: Represents a field-level operation (e.g., field:value).
• LogicalExpression: Combines expressions using boolean operators (e.g., AND, OR).
• UnaryOperator: Handles operators like NOT.
• ParenthesizedExpression: Wraps expressions in parentheses ().
• EmptyExpression: Returns an empty string.

Note: For ParenthesizedExpression and LogicalExpression, the serializer relies on location metadata within the AST to preserve the original whitespace and formatting.

import { serialize } from './serialize';

// Assuming 'ast' is a valid LiqeQuery object
const queryString = serialize(ast);
console.log(queryString);