open-index/open-npm huggingface dataset:
npm package: @liveblocks/query-parser
Description: Liveblocks query language parser
Latest version: 0.1.1

# Liveblocks query parser

Largely inspired by
[Stripe's search query language](https://docs.stripe.com/search#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.

```ts
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

```ts
// 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](https://github.com/liveblocks/liveblocks-cloudflare/blob/49b0ffe120b845f26d029ae16590b24d419ec001/packages/liveblocks-query-parser/test/high-level.test.ts#L56-L102).