Largely inspired by Stripe's search query language.
The purpose of this library is to safely parse any user-provided input string,
and returning a Query
instance, which is the parsed result. You can then use
this parse result to turn it into an arbitrary search query.
The parser definition defines what queries are considered legal for your use case. Invalid queries will get rejected.
import { QueryParser } from "@liveblocks/query-parser";
// Set up your parser instance
const parser = new QueryParser({
// Define what fields you want users to be able to query
fields: {
id: "token",
name: "string",
description: "string",
email: "string",
age: "numeric",
resolved: "boolean",
},
// Define what fields are indexable
indexableFields: {
meta: "mixed",
},
});
The following field types are possible:
Type | Data type | Operators |
---|---|---|
token |
String |
: (exact) |
boolean |
Boolean |
: (exact) |
string |
String |
: (exact), ^ (prefix) |
numeric |
Number |
: (exact), > , < , >= , <= (comparison) |
mixed |
String or number |
: (exact), ^ (prefix), > , < , >= , <= (comparison) |
// Token fields
parser.parse('id:"abc123"');
parser.parse('id^"abc123"'); // ❌ Token field cannot be prefix matched
// Boolean fields
parser.parse('resolved:true');
parser.parse('resolved:false');
// String fields
parser.parse('email:"vincent@liveblocks.io"');
parser.parse('email^"vincent@"');
// Numeric fields
parser.parse("age:42");
parser.parse("age<42");
parser.parse("age<=42");
parser.parse("age>42");
parser.parse("age>=42");
// Indexable fields
parser.parse('metadata["color"]:"red"');
parser.parse('metadata["last-updated"]>1709122155');
parser.parse('metadata["resolved"]:true');
parser.parse('metadata["org"]^"liveblocks:engineering"');
// Combining
parser.parse('id:"abc123" metadata["color"]:"red"'); // AND is the default mode
parser.parse('id:"abc123" AND email:"vincent@liveblocks.io"');
parser.parse('id:"abc123" OR email:"vincent@liveblocks.io"');
parser.parse('id:"abc123" AND name:"Vincent" OR email:"vincent@liveblocks.io"'); // ❌ AND and OR are mutually exclusive
// Negative matches
parser.parse('id:"abc123" -name:"Vincent");
The output is a fully-typed AST. TypeScript auto-completion is your best friend. Here is a high-level example output.