catsearch queries

@appulsauce/ninja-keys/catsearch is a searcher that reads the search box as a query in a small language: plain words as before, plus fields (section:git), negation, alternatives, and paths up the menu tree (under.title:settings). Completions for field names and values appear under the input as you type. It is built on catsearch, the web port of the Python textual-catsearch, which uses the same language in terminal apps.

import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
} from '@appulsauce/ninja-keys/catsearch';
const ninja: NinjaKeysninja.NinjaKeys.searcher: Searcher

Decides which actions a search shows, and may add a notice and completions under the search box. The default is the regular-expression match over title and keywords; @appulsauce/ninja-keys/catsearch provides a field query language (section:guides under.title:rendering).

searcher
= catsearchSearcher<INinjaAction>(options?: CatsearchOptions<INinjaAction> | undefined): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
();

Install catsearch next to @appulsauce/ninja-keys first (see Installation). The main @appulsauce/ninja-keys entry never imports it.

Why queries in a palette

A palette with a few dozen actions needs nothing more than words. Queries pay off when the list is long and structured, which is when a palette starts to stand in for navigation:

  • Many actions with the same words. “Delete branch”, “Delete file”, “Delete row” all match delete; delete parent.title:git or delete section:git keeps the one you mean.
  • Deep trees. Docs, settings, file trees. Search at the top level finds a leaf only by its own words; under.title:rendering lists everything below a branch, however deep.
  • Metadata people know. Kind, tags, dates, status: kind:page updated:>=2026 -is:draft is one line instead of a filter UI (see custom fields).
  • Shareable searches. A query is text, so it can go in a link and run through open({search}).

The language

QueryMatches
commit pushactions whose title or keywords contain both words
title:branchthe title contains “branch”
keyword:remote, kw:remotea keyword contains “remote”
section:gitthe section is Git; section:git,editor for either
section:noneactions with no section
has:hotkey, has:children, has:parentactions with a hotkey, that open a menu, that are inside one
parent.title:branchesactions directly inside the menu titled Branches
under.title:gitactions anywhere below Git, however deep
-section:view, !section:viewnegation
a OR b, a \| beither; binds tighter than a space, so a OR b c is (a OR b) c
(…), -(…)grouping, and negating a group
title:"new branch"quotes make one value with spaces

Matching ignores case and accents. Different fields AND; the same field written twice ORs (section:git section:editor is section:git,editor). A path asks its question of the actions the relation leads to: parent.has:hotkey is “inside a menu that has a hotkey”.

The parser never fails. An unknown field (a typo such as secton:git) is searched as text and reported on the notice line under the input; a half-typed section: constrains nothing yet. So every keystroke shows something sensible.

How it behaves in the palette

  • An empty box lists the open menu, exactly like the default search.
  • A query searches every level below the open menu, not only its own actions. At the top level that is everything; inside Git it is everything under Git.
  • Completions appear for the word under the caret: field names (sec offers section:), values from your actions (section: offers each section, most used first), and relations (under.). Tab takes the first; click any. Nothing is offered while the caret sits after a space, so a finished query has no row of chips under it.
  • Order is the order of data, grouped by section.

Fields of your own

Actions can carry properties of their own, and catsearchSearcher takes fields over them. Type the actions as an interface extending INinjaAction and build the fields with catsearch’s constructors:

import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
} from '@appulsauce/ninja-keys/catsearch';
import {function enumField<Row>(spec: Options<EnumField<Row>, "name" | "get">): EnumField<Row>enumField,
function flagField<Row>(spec: Omit<Options<FlagField<Row>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Row) => boolean> | Readonly<Record<string, (row: Row) => boolean>>;
}): FlagField<Row>
flagField
, function numberField<Row>(spec: Options<NumberField<Row>, "name" | "get">): NumberField<Row>numberField, function textField<Row>(spec: Options<TextField<Row>, "name" | "get">): TextField<Row>textField} from 'catsearch';
interface Doc extends INinjaAction { Doc.kind: "guide" | "reference" | "example"kind: 'guide' | 'reference' | 'example'; Doc.tags: string[]tags: string[]; Doc.updated: numberupdated: number; Doc.draft: booleandraft: boolean; } const ninja: NinjaKeysninja.NinjaKeys.searcher: Searcher

Decides which actions a search shows, and may add a notice and completions under the search box. The default is the regular-expression match over title and keywords; @appulsauce/ninja-keys/catsearch provides a field query language (section:guides under.title:rendering).

searcher
= catsearchSearcher<Doc>(options?: CatsearchOptions<Doc> | undefined): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
<Doc>({
CatsearchOptions<Doc>.fields?: readonly Field<Doc>[]

More fields over your actions, after the built-in ones. A name or alias that clashes with a built-in field makes the Schema constructor throw.

fields
: [
enumField<Doc>(spec: Options<EnumField<Doc>, "name" | "get">): EnumField<Doc>enumField<Doc>({ name: stringname: 'kind', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.kind: "guide" | "reference" | "example"kind, detail?: string

What completion calls this field's values; defaults to the name.

detail
: 'guide, reference or example',
}), textField<Doc>(spec: Options<TextField<Doc>, "name" | "get">): TextField<Doc>textField<Doc>({name: stringname: 'tag', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.tags: string[]tags, aliases?: readonly string[]aliases: ['t']}), numberField<Doc>(spec: Options<NumberField<Doc>, "name" | "get">): NumberField<Doc>numberField<Doc>({name: stringname: 'updated', get: (row: Doc) => Numbersget: (d: Docd) => d: Docd.Doc.updated: numberupdated}),
flagField<Doc>(spec: Omit<Options<FlagField<Doc>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>;
}): FlagField<Doc>
flagField
<Doc>({
name: stringname: 'is', flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>flags: {draft: (d: Doc) => booleandraft: (d: Docd) => d: Docd.Doc.draft: booleandraft, published: (d: Doc) => booleanpublished: (d: Docd) => !d: Docd.Doc.draft: booleandraft}, }), ], }); // kind:guide tag:gpu updated:>=2026 -is:draft
ConstructorMatchesQuery
textFielda substring, ignoring case and accents; get may return several valuestag:gp
enumFielda whole value, ignoring case and accentskind:guide
numberFielda number or a rangeupdated:2024..2026, updated:>=2026
flagFieldnamed yes/no predicatesis:draft

Every field takes aliases and a detail shown beside its completions. A name or alias that clashes with a built-in field (title, keyword, section, has) makes the constructor throw, at once rather than at the first search.

The query cookbook runs these fields over a docs tree, with a query for each kind of question.

Options

catsearchSearcher(options) takes:

  • fields: more fields, after the built-in ones.
  • relations: more relations, after parent and under, built with catsearch’s relation(). A relation follows from an action to other actions, such as “links to” or “same author”.
  • limit: how many completions to offer at once; 10 by default.

The full signatures are in the API reference.