@liveblocks/query-parser

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:"[e-mail]"');
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:"[e-mail]"');
parser.parse('id:"abc123" OR email:"[e-mail]"');
parser.parse('id:"abc123" AND name:"Vincent" OR email:"[e-mail]"'); // ❌ 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.