Package Exports
- @liveblocks/query-parser
- @liveblocks/query-parser/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@liveblocks/query-parser) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
Liveblocks query parser
Largely inspired by Stripe's search query language.
Step 1: Configure your parser
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) |
Step 2: Use it
// 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");Step 3: Use the output
The output is a fully-typed AST. TypeScript auto-completion is your best friend. Here is a high-level example output.