query-filter

The language behind Query: free text and key:value qualifiers in one string, such as is:shared -staging api. The module is plain TypeScript with no React import, so a server, a script, or a test can parse and match a query with the same rules the field uses.

1import {2	acceptsValueList,3	countItemsByQuery,4	defineRemoteFilterGrammar,5	filterItemsByQuery,6	filterItemsByTokens,7	findTokenAtCaret,8	formatFacet,9	getFilterKeyDefinition,10	getFilterSuggestions,11	getFilterSyntax,12	getHighlightSegments,13	getValueCandidates,14	isCaretInFacetValue,15	parseFilterQuery,16	queryUsesQualifiers,17	quoteFilterValue,18	resolveFilterKey,19	resolveFilterValue,20	toggleFacet,21} from "@ngrok/mantle/query-filter";22 23import type {24	FilterGrammar,25	FilterKeyDefinition,26	FilterMatchContext,27	FilterSuggestion,28	FilterSuggestions,29	FilterSyntax,30	FilterToken,31	FilterValueDefinition,32	HighlightSegment,33} from "@ngrok/mantle/query-filter";

The language

Keys, values, and their aliases match without regard to case, and never fuzzily. A key the grammar doesn't know stays free text, so a pasted https://api.example.com searches for that URL. A value an enumerated key doesn't know matches no item.

Write a grammar

A grammar is one FilterGrammar<Item> object per list. Declare it as a module constant: the engine caches its alias tables per grammar object.

1import { type FilterGrammar } from "@ngrok/mantle/query-filter";2 3type Project = { id: string; name: string; shared: boolean };4 5const projectFilterGrammar: FilterGrammar<Project> = {⋯6	keys: [⋯7		{⋯8			key: "name",9			aliases: ["title"],10			description: "Text in the project name",11			matches: (project, value) => project.name.toLowerCase().includes(value.toLowerCase()),12		},13		{⋯14			key: "is",15			description: "The project state",16			values: [⋯17				{ value: "shared", description: "Your team can see it" },18				{ value: "private", description: "Only you can see it", aliases: ["personal"] },19			],20			matches: (project, value) => (value === "shared" ? project.shared : !project.shared),21		},22	],23	getSearchText: (project) => [project.name, project.id].join("\n"),24};

• getSearchText builds the text a free-text term searches. Join the fields with a newline, so a term can't match across two fields.
• A matcher that compares a date against the clock reads context.now, never Date.now(). Pass { now } from a ticking state hook, so a memoized filter re-runs as time passes.
• negatable: false on a key removes its -key: suggestion and paints a typed - as invalid. A typed -key:value on that key matches no items.

Filter items

filterItemsByQuery keeps the input order. An empty query returns the same array, so a memoized list keeps its identity.

1import { filterItemsByQuery } from "@ngrok/mantle/query-filter";2 3const visibleProjects = filterItemsByQuery({⋯4	grammar: projectFilterGrammar,5	items: projects,6	query: "is:shared api",7});

countItemsByQuery(grammar, items, query) counts the matches without building the array. It caches up to 1,000 counts per grammar and items array, so the counts in the suggestions cost one scan for each query.

The engine caches the search text per item and per items array. Treat items as immutable: replace a changed item with a new object, and pass a new array, as React state already requires.

A query that a server runs

defineRemoteFilterGrammar declares the vocabulary of a query that another system runs. Nothing matches on the client. Its syntax sets what the highlighter paints as structure:

• "qualifiers" (the default) reads only bare key:value tokens. Quotes, -, OR, and commas stay text. A value with a space can't be written, so defineRemoteFilterGrammar drops it, and drops an alias with a space too. Values often come from a server, so the grammar never throws on one.
• "conjunction" reads one AND group of exclusions, comma lists, and quotes. A bare term paints as invalid, because the executor can't run it.

1import { defineRemoteFilterGrammar } from "@ngrok/mantle/query-filter";2 3const accountSearchGrammar = defineRemoteFilterGrammar({⋯4	keys: [⋯5		{ key: "is", description: "The account state", values: [{ value: "suspended" }] },6		{ key: "email", description: "The account email" },7	],8});

Parse a query

parseFilterQuery is total: it returns tokens for every input and never throws. A query is a hand-edited URL param, and the field re-parses it on every keystroke.

1import { parseFilterQuery } from "@ngrok/mantle/query-filter";2 3parseFilterQuery(projectFilterGrammar, "is:shared -acme");4// => [{ kind: "facet", key: "is", members: [{ value: "shared", … }], negated: false, … },5//     { kind: "text", text: "acme", negated: true, … }]

• formatFacet({ key, value, negated }) writes a qualifier in its canonical form, with quotes where the value needs them.
• toggleFacet({ grammar, query, facet }) adds a qualifier, or takes it out when the query has it. The Filter from a value recipe uses it for a value a person selects in a table row.
• queryUsesQualifiers(grammar, query) reports whether a query holds a qualifier. Use it to pick the advice in a filtered-empty state.
• getFilterSuggestions and getHighlightSegments are what Query renders. Use them to build your own field.

Natural language search

Two helpers connect the language to a model. Neither one calls a model: your server owns the request.

• describeFilterGrammar(grammar) describes the keys, the allowed values, and the syntax rules as plain data. Send it to the model with the person's words.
• checkFilterQuery(grammar, query) returns the unknown keys, the unknown values, and the exclusions a key can't do. Check the model's query before you show it, so an invented filter never empties the list.

1import { checkFilterQuery, describeFilterGrammar } from "@ngrok/mantle/query-filter";2 3const language = JSON.stringify(describeFilterGrammar(projectFilterGrammar));4 5checkFilterQuery(projectFilterGrammar, "is:shared owner:me");6// => [{ kind: "unknown-key", key: "owner", start: 10, end: 18 }]

The natural language query recipe wires them to a Query field.