Query cookbook
A documentation tree, three levels deep (area, topic, page), where each page carries data the palette never shows: a kind, tags, the year it was last updated, and whether it is a draft. Four fields declared over those properties turn them into queries, and catsearch completes their names and values from the actions themselves. This is the shape of a docs site’s search, a settings screen, or a file tree.
- plain words still search titles and keywords
- only leaves, no areas or topics
- every page below one area
- recent GPU material
- a range: what may be out of date
- unfinished pages, for an editor
- published pages in one topic
- grouped alternatives within an area
- pages nobody has tagged yet
- a half-typed path: the completions show what can follow
// catsearch with fields of your own. Each doc page carries a kind, tags,
// a year and a draft flag next to the fields ninja-keys reads; declaring
// fields over them makes `kind:page tag:gpu updated:>=2026 -is:draft`
// a query, with completions for every name and value.
import '@appulsauce/ninja-keys';
import type {INinjaAction, class NinjaKeysA keyboard command palette: a modal list of actions, opened with a hotkey,
searched as you type, with nested menus and per-action hotkeys.
NinjaKeys} from '@appulsauce/ninja-keys';
import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): SearcherA 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';
type type Kind = "area" | "topic" | "page"Kind = 'area' | 'topic' | 'page';
interface Doc extends INinjaAction {
readonly Doc.kind: Kindkind: type Kind = "area" | "topic" | "page"Kind;
readonly Doc.tags: readonly string[]tags: readonly string[];
readonly Doc.updated: numberupdated: number;
readonly Doc.draft: booleandraft: boolean;
}
interface Entry {
readonly Entry.title: stringtitle: string;
readonly Entry.tags?: readonly string[]tags?: readonly string[];
readonly Entry.updated?: numberupdated?: number;
readonly Entry.draft?: booleandraft?: boolean;
readonly Entry.keywords?: stringkeywords?: string;
readonly Entry.children?: readonly Entry[]children?: readonly Entry[];
}
const const KINDS: readonly Kind[]KINDS: readonly type Kind = "area" | "topic" | "page"Kind[] = ['area', 'topic', 'page'];
/** An entry and everything below it, as one nested action. */
function function doc(entry: Entry, depth: number, section: string): DocAn entry and everything below it, as one nested action.
doc(entry: Entryentry: Entry, depth: numberdepth: number, section: stringsection: string): Doc {
return {
INinjaAction.id: stringUnique across all actions. Child actions name their menu by it in
parent, and the breadcrumbs show it while that menu is open.
id: entry: Entryentry.Entry.title: stringtitle,
INinjaAction.title: stringThe text shown in the list, and searched.
title: entry: Entryentry.Entry.title: stringtitle,
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section,
Doc.kind: Kindkind: const KINDS: readonly Kind[]KINDS[var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.min(...values: number[]): numberReturns the smaller of a set of supplied numeric expressions.
min(depth: numberdepth, const KINDS: readonly Kind[]KINDS.ReadonlyArray<Kind>.length: numberGets the length of the array. This is a number one higher than the highest element defined in an array.
length - 1)] ?? 'page',
Doc.tags: readonly string[]tags: entry: Entryentry.Entry.tags?: readonly string[] | undefinedtags ?? [],
Doc.updated: numberupdated: entry: Entryentry.Entry.updated?: number | undefinedupdated ?? 2025,
Doc.draft: booleandraft: entry: Entryentry.Entry.draft?: boolean | undefineddraft ?? false,
...(entry: Entryentry.Entry.keywords?: string | undefinedkeywords !== var undefinedundefined && {INinjaAction.keywords?: stringMore words to match, separated by spaces; not shown.
keywords: entry: Entryentry.Entry.keywords?: stringkeywords}),
...(entry: Entryentry.Entry.children?: readonly Entry[] | undefinedchildren && {
INinjaAction.children?: string[] | INinjaAction[]The menu this action opens: the ids of its children in a flat list, or
the child actions themselves in a tree. ninja-keys flattens a tree into
ids, so a searcher always sees ids.
children: entry: Entryentry.Entry.children?: readonly Entry[]children.ReadonlyArray<Entry>.map<Doc>(callbackfn: (value: Entry, index: number, array: readonly Entry[]) => Doc, thisArg?: any): Doc[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((child: Entrychild) => function doc(entry: Entry, depth: number, section: string): DocAn entry and everything below it, as one nested action.
doc(child: Entrychild, depth: numberdepth + 1, section: stringsection)),
}),
};
}
const const TREE: readonly Entry[]TREE: readonly Entry[] = [
{
Entry.title: stringtitle: 'Rendering',
Entry.tags?: readonly string[]tags: ['gpu'],
Entry.children?: readonly Entry[]children: [
{
Entry.title: stringtitle: 'Lighting',
Entry.children?: readonly Entry[]children: [
{
Entry.title: stringtitle: 'Shadow maps',
Entry.tags?: readonly string[]tags: ['gpu', 'quality'],
Entry.keywords?: stringkeywords: 'pcf cascades',
Entry.updated?: numberupdated: 2026,
},
{
Entry.title: stringtitle: 'Global illumination',
Entry.tags?: readonly string[]tags: ['gpu', 'baking'],
Entry.updated?: numberupdated: 2024,
},
{Entry.title: stringtitle: 'Bloom', Entry.tags?: readonly string[]tags: ['post'], Entry.draft?: booleandraft: true},
],
},
{
Entry.title: stringtitle: 'Materials',
Entry.children?: readonly Entry[]children: [
{
Entry.title: stringtitle: 'PBR basics',
Entry.tags?: readonly string[]tags: ['quality'],
Entry.keywords?: stringkeywords: 'roughness metallic',
},
{Entry.title: stringtitle: 'Texture compression', Entry.tags?: readonly string[]tags: ['memory'], Entry.updated?: numberupdated: 2026},
],
},
],
},
{
Entry.title: stringtitle: 'Audio',
Entry.children?: readonly Entry[]children: [
{
Entry.title: stringtitle: 'Mixing',
Entry.children?: readonly Entry[]children: [
{Entry.title: stringtitle: 'Buses', Entry.updated?: numberupdated: 2023},
{Entry.title: stringtitle: 'Ducking and sidechains', Entry.keywords?: stringkeywords: 'compressor'},
],
},
{
Entry.title: stringtitle: 'Spatial audio',
Entry.children?: readonly Entry[]children: [
{Entry.title: stringtitle: 'HRTF', Entry.tags?: readonly string[]tags: ['quality']},
{
Entry.title: stringtitle: 'Occlusion',
Entry.keywords?: stringkeywords: 'acoustic shadow',
Entry.updated?: numberupdated: 2026,
Entry.draft?: booleandraft: true,
},
],
},
],
},
{
Entry.title: stringtitle: 'Performance',
Entry.children?: readonly Entry[]children: [
{
Entry.title: stringtitle: 'Profiling',
Entry.children?: readonly Entry[]children: [
{Entry.title: stringtitle: 'GPU captures', Entry.tags?: readonly string[]tags: ['gpu'], Entry.updated?: numberupdated: 2026},
{Entry.title: stringtitle: 'Frame budget', Entry.keywords?: stringkeywords: 'ms fps'},
{
Entry.title: stringtitle: 'Shadow cost',
Entry.tags?: readonly string[]tags: ['gpu'],
Entry.keywords?: stringkeywords: 'cascades',
Entry.draft?: booleandraft: true,
},
],
},
],
},
];
export const const docsSearcher: SearcherdocsSearcher = catsearchSearcher<Doc>(options?: CatsearchOptions<Doc> | undefined): SearcherA 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: Kindkind,
choices?: readonly string[]choices: const KINDS: readonly Kind[]KINDS,
detail?: stringWhat completion calls this field's values; defaults to the name.
detail: 'area, topic or page',
}),
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: readonly string[]tags}),
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},
}),
],
});
export default function function setup(ninja: NinjaKeys, report: (message: string) => void): voidsetup(
ninja: NinjaKeysninja: class NinjaKeysA keyboard command palette: a modal list of actions, opened with a hotkey,
searched as you type, with nested menus and per-action hotkeys.
NinjaKeys,
report: (message: string) => voidreport: (message: stringmessage: string) => void
): void {
const const open: (action: INinjaAction) => voidopen = (action: INinjaActionaction: INinjaAction) => {
const const d: Docd = action: INinjaActionaction as Doc;
report: (message: string) => voidreport(`${const d: Docd.INinjaAction.title: stringThe text shown in the list, and searched.
title}: ${const d: Docd.Doc.kind: Kindkind}, ${const d: Docd.Doc.updated: numberupdated}${const d: Docd.Doc.draft: booleandraft ? ', draft' : ''}`);
};
const const withHandlers: (d: Doc) => DocwithHandlers = (d: Docd: Doc): Doc =>
d: Docd.INinjaAction.children?: string[] | INinjaAction[] | undefinedThe menu this action opens: the ids of its children in a flat list, or
the child actions themselves in a tree. ninja-keys flattens a tree into
ids, so a searcher always sees ids.
children?.Array<T>.length: number | undefinedGets or sets the length of the array. This is a number one higher than the highest index in the array.
length
? {
...d: Docd,
INinjaAction.children?: string[] | INinjaAction[]The menu this action opens: the ids of its children in a flat list, or
the child actions themselves in a tree. ninja-keys flattens a tree into
ids, so a searcher always sees ids.
children: (d: Docd.INinjaAction.children?: string[] | INinjaAction[]The menu this action opens: the ids of its children in a flat list, or
the child actions themselves in a tree. ninja-keys flattens a tree into
ids, so a searcher always sees ids.
children as Doc[]).Array<Doc>.map<Doc>(callbackfn: (value: Doc, index: number, array: Doc[]) => Doc, thisArg?: any): Doc[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((child: Docchild) => const withHandlers: (d: Doc) => DocwithHandlers(child: Docchild)),
}
: {...d: Docd, INinjaAction.handler?: (action: INinjaAction) => {
keepOpen?: boolean;
} | void
Runs when the action is chosen, by Enter, a click or its hotkey. The
palette closes afterwards unless it returns {keepOpen: true}.
handler: const open: (action: INinjaAction) => voidopen};
ninja: NinjaKeysninja.NinjaKeys.data: INinjaAction[]The actions, as a flat list (children name their menu in parent) or
a tree (menus hold their children in children). Assign a new array to
change it; the hotkeys are rebound each time.
data = const TREE: readonly Entry[]TREE.ReadonlyArray<Entry>.map<Doc>(callbackfn: (value: Entry, index: number, array: readonly Entry[]) => Doc, thisArg?: any): Doc[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map((entry: Entryentry) => const withHandlers: (d: Doc) => DocwithHandlers(function doc(entry: Entry, depth: number, section: string): DocAn entry and everything below it, as one nested action.
doc(entry: Entryentry, 0, entry: Entryentry.Entry.title: stringtitle)));
ninja: NinjaKeysninja.NinjaKeys.searcher: SearcherDecides 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 = const docsSearcher: SearcherdocsSearcher;
}The fields
import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): SearcherA 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';
const const searcher: Searchersearcher = catsearchSearcher<Doc>(options?: CatsearchOptions<Doc> | undefined): SearcherA 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: "area" | "topic" | "page"kind,
choices?: readonly string[]choices: ['area', 'topic', 'page'],
}),
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: readonly string[]tags}),
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},
}),
],
});Choose the field kind by the question people will ask of it:
| Kind | Use for | Because |
|---|---|---|
enumField | a fixed set of values: kind, status, type | it matches whole values, so kind:page never matches “pager”; choices completes values no action has yet |
textField | free text and lists: tags, authors, paths | it matches substrings, and get can return an array |
numberField | dates, sizes, counts, priorities | it takes ranges: 2023..2024, >=2026, <10 |
flagField | yes/no states with names: draft, pinned, read | several named predicates under one key: is:draft, is:published |
Recipes
Narrow, then search. Put the structural part first and the words last: under.title:audio kind:page occlusion. The completions keep up while you type the words.
Find stale content. updated:<2025 -is:draft lists published pages not touched since 2024: a review queue.
Find gaps. none matches an empty field: tag:none for untagged pages, section:none for actions outside any section.
Scope to the open menu. Inside a menu, a query searches only below it, so opening Rendering and typing kind:page lists Rendering’s pages without saying under..
Link to a search. A query is text, so a link can carry one: read it from the URL and pass it to open({search}) (see the page-driven example).
Every operator is in the catsearch guide.