Skip to content

Build your personal knowledge base with Trilium Notes

feat(search): report what the engine refuses while the query is typed

Elian Doran015284448405
diff --git a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
index 7813c67e3e..1173c3891d 100644
--- a/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
+++ b/apps/client/src/widgets/ribbon/SearchStringEditor.tsx
@@ -1,11 +1,13 @@
import "./SearchStringEditor.css";
import type { SearchLintMessages } from "@triliumnext/codemirror/src/extensions/trilium_search_lint";
+import type { SearchLintResponse } from "@triliumnext/commons";
import type { SingleLineEditor } from "@triliumnext/codemirror/src/single_line";
import clsx from "clsx";
import { useEffect, useRef } from "preact/hooks";
import { t } from "../../services/i18n";
+import server from "../../services/server";
import { searchCompletionIcon, searchCompletionReactivates, searchCompletionSource } from "./search_completions";
interface SearchStringEditorProps {
@@ -54,7 +56,7 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
parent: parentRef.current,
doc: propsRef.current.currentValue,
placeholder,
- extensions: [ triliumSearchHighlighter, triliumSearchLinter(searchLintMessages()) ],
+ extensions: [ triliumSearchHighlighter, triliumSearchLinter(searchLintMessages(), validateOnServer) ],
completionSource: searchCompletionSource,
completionIcon: searchCompletionIcon,
activateOnCompletion: searchCompletionReactivates,
@@ -107,6 +109,17 @@ export default function SearchStringEditor({ currentValue, noteId, placeholder,
return <div ref={parentRef} className={clsx("search-string-editor form-control tn-input-field", className)} />;
}
+/**
+ * Asks the engine to read the query without running it, for the faults the rules in the editor do
+ * not cover. Only reached once those rules are satisfied, so a query they already object to costs
+ * no request.
+ */
+async function validateOnServer(searchString: string) {
+ const { error } = await server.post<SearchLintResponse>("search/lint", { searchString });
+
+ return error;
+}
+
/** Read once the editor is built, so the wording follows a language switched while the app runs. */
function searchLintMessages(): SearchLintMessages {
return {
diff --git a/packages/codemirror/src/extensions/trilium_search_lint.spec.ts b/packages/codemirror/src/extensions/trilium_search_lint.spec.ts
index 75db4ad952..2dbce440f8 100644
--- a/packages/codemirror/src/extensions/trilium_search_lint.spec.ts
+++ b/packages/codemirror/src/extensions/trilium_search_lint.spec.ts
@@ -1,6 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
-import { diagnoseSearchQuery, type SearchLintMessages } from "./trilium_search_lint.js";
+import { diagnoseSearchQuery, type SearchLintMessages, searchDiagnostics, type SearchValidator } from "./trilium_search_lint.js";
// The wording is the consumer's; the keys identify which rule answered.
const MESSAGES: SearchLintMessages = {
@@ -79,6 +79,52 @@ describe("diagnoseSearchQuery", () => {
});
});
+describe("searchDiagnostics", () => {
+ it("asks the engine only about a query its own rules accept", async () => {
+ const validate = vi.fn(async () => "Mixed usage of AND/OR");
+
+ // A fault of its own is reported without a round trip, since the engine would name the
+ // same one less precisely.
+ expect(await ranges("~author = tolkien", validate)).toEqual([ { from: 8, to: 9, message: "relation" } ]);
+ expect(validate).not.toHaveBeenCalled();
+
+ expect(await ranges("#a and #b or #c", validate)).toEqual([
+ { from: 0, to: 15, message: "Mixed usage of AND/OR" }
+ ]);
+ expect(validate).toHaveBeenCalledWith("#a and #b or #c");
+
+ // Nothing to say about an empty field, and nothing to ask.
+ validate.mockClear();
+ expect(await ranges(" ", validate)).toEqual([]);
+ expect(validate).not.toHaveBeenCalled();
+ });
+
+ it("keeps the editor working when the engine cannot be reached", async () => {
+ const failing = vi.fn(async () => { throw new Error("offline"); });
+
+ expect(await ranges("#a and #b or #c", failing)).toEqual([]);
+ expect(failing).toHaveBeenCalled();
+ });
+
+ it("drops an answer that describes a query already typed over", async () => {
+ const diagnostics = await searchDiagnostics(
+ "#a and #b or #c",
+ MESSAGES,
+ async () => "Mixed usage of AND/OR",
+ () => "#a and #b"
+ );
+
+ expect(diagnostics).toEqual([]);
+ });
+});
+
+/** Drives the real lint source and keeps only what a squiggle is drawn from. */
+async function ranges(query: string, validate: SearchValidator) {
+ const diagnostics = await searchDiagnostics(query, MESSAGES, validate);
+
+ return diagnostics.map(({ from, to, message }) => ({ from, to, message }));
+}
+
function messagesFor(query: string) {
return diagnoseSearchQuery(query, MESSAGES).map((diagnostic) => diagnostic.message);
}
diff --git a/packages/codemirror/src/extensions/trilium_search_lint.ts b/packages/codemirror/src/extensions/trilium_search_lint.ts
index 301767da74..1d6214b3ba 100644
--- a/packages/codemirror/src/extensions/trilium_search_lint.ts
+++ b/packages/codemirror/src/extensions/trilium_search_lint.ts
@@ -21,17 +21,64 @@ export interface SearchLintMessages {
useOperator(operator: string): string;
}
+/**
+ * Reads a query by the engine's own rules, without running it. Answers the first fault, or `null`
+ * where the query has none.
+ */
+export type SearchValidator = (query: string) => Promise<string | null>;
+
/**
* Marks the comparisons `parse.ts` refuses, which a query reaches only by being rewritten: no token
* typed after `~author =` makes it valid again, so a completion has nothing to offer there and the
* mistake would otherwise surface only once the search is run.
*
- * It reads the same tokens the highlighter colours and holds to what they decide on their own. The
- * parser in `trilium-core` stays the authority on whether a query is valid, and the error it
- * reports is still what the ribbon shows.
+ * The rules below read the same tokens the highlighter colours and hold to what they decide on
+ * their own, which keeps them instant and lets them mark the operator they object to. `validate`
+ * covers the rest of what the engine refuses, at the cost of a round trip and of a message it can
+ * only attach to the whole query, since `SearchContext` records no offsets.
+ */
+export function triliumSearchLinter(messages: SearchLintMessages, validate?: SearchValidator): Extension {
+ return linter((view) => searchDiagnostics(
+ view.state.doc.toString(),
+ messages,
+ validate,
+ () => view.state.doc.toString()
+ ));
+}
+
+/**
+ * The lint source, apart from an editor, which is also how the spec drives it. `currentQuery` is
+ * read again once `validate` answers, so a message describing text already typed over is dropped.
*/
-export function triliumSearchLinter(messages: SearchLintMessages): Extension {
- return linter((view) => diagnoseSearchQuery(view.state.doc.toString(), messages));
+export async function searchDiagnostics(
+ query: string,
+ messages: SearchLintMessages,
+ validate?: SearchValidator,
+ currentQuery: () => string = () => query
+): Promise<Diagnostic[]> {
+ const local = diagnoseSearchQuery(query, messages);
+
+ // The local rules already name a fault, and the engine would only report the same one again,
+ // less precisely. They also answer for an empty query, which has nothing to say.
+ if (local.length > 0 || !validate || query.trim() === "") {
+ return local;
+ }
+
+ let error: string | null;
+ try {
+ error = await validate(query);
+ } catch {
+ // The editor keeps working without the engine's opinion.
+ return [];
+ }
+
+ // Typing during the round trip has already queued another run, whose answer describes what the
+ // query says now.
+ if (!error || currentQuery() !== query) {
+ return [];
+ }
+
+ return [ { from: 0, to: query.length, severity: "error", message: error } ];
}
/** Runs the rules over `query`, apart from an editor, which is also how the spec drives them. */
diff --git a/packages/commons/src/lib/server_api.ts b/packages/commons/src/lib/server_api.ts
index 4d39246c34..fb217165bf 100644
--- a/packages/commons/src/lib/server_api.ts
+++ b/packages/commons/src/lib/server_api.ts
@@ -361,6 +361,16 @@ export interface SearchResultDetailsRequest {
noteIds: string[];
}
+/** Request body for `POST /api/search/lint`, which reads a query without running it. */
+export interface SearchLintRequest {
+ searchString: string;
+}
+
+/** Response for `POST /api/search/lint`: the first fault in the query, or `null` where it has none. */
+export interface SearchLintResponse {
+ error: string | null;
+}
+
/**
* Per-note snippet + highlight details for one search result, built lazily for a
* page of results. Snippet fields are absent when there is nothing to show (e.g.
diff --git a/packages/trilium-core/src/routes/api/search.ts b/packages/trilium-core/src/routes/api/search.ts
index 66270ce7e5..558b6902c6 100644
--- a/packages/trilium-core/src/routes/api/search.ts
+++ b/packages/trilium-core/src/routes/api/search.ts
@@ -1,6 +1,7 @@
import {
- dayjs, type SearchResultDetails, type SearchResultDetailsRequest,
- type SearchResultDetailsResponse, type SearchWithTokensResponse, type TemplatesResponse
+ dayjs, type SearchLintRequest, type SearchLintResponse, type SearchResultDetails,
+ type SearchResultDetailsRequest, type SearchResultDetailsResponse, type SearchWithTokensResponse,
+ type TemplatesResponse
} from "@triliumnext/commons";
import type { Request } from "../../http_interface";
@@ -110,6 +111,21 @@ function getSearchResultDetails(req: Request<{ noteId: string }>): SearchResultD
};
}
+/**
+ * Reads a search string without running it, so the editor can report what is wrong with a query
+ * while it is being typed rather than once it is run. Carries the message alone: `SearchContext`
+ * records no offsets, so the caller cannot mark where the fault is.
+ */
+function lintSearchString(req: Request): SearchLintResponse {
+ const { searchString } = (req.body ?? {}) as Partial<SearchLintRequest>;
+
+ if (typeof searchString !== "string") {
+ throw new ValidationError("searchString must be a string.");
+ }
+
+ return { error: searchService.validateSearchQuery(searchString) };
+}
+
function quickSearch(req: Request<{ searchString: string }>) {
const { searchString } = req.params;
@@ -252,6 +268,7 @@ export function isNewTemplate(utcDateCreated: string | null, rootCreationDate: s
}
export default {
+ lintSearchString,
searchFromNote,
getSearchResultDetails,
searchAndExecute,
diff --git a/packages/trilium-core/src/routes/api/search_lint.spec.ts b/packages/trilium-core/src/routes/api/search_lint.spec.ts
new file mode 100644
index 0000000000..19bbbf98c5
--- /dev/null
+++ b/packages/trilium-core/src/routes/api/search_lint.spec.ts
@@ -0,0 +1,51 @@
+import type { SearchLintResponse } from "@triliumnext/commons";
+import { beforeAll, describe, expect, it } from "vitest";
+
+import { CoreApiTester } from "../../test/api_tester";
+
+let api: CoreApiTester;
+
+describe("Search lint (core)", () => {
+ beforeAll(() => {
+ api = CoreApiTester.build();
+ });
+
+ it("answers nothing for a query the engine accepts", async () => {
+ for (const searchString of [ "", "towers #book", "~author.title = tolkien", "note.text *=* hello" ]) {
+ const res = await api.post("/api/search/lint", { body: { searchString } });
+
+ expect(res.status, searchString).toBe(200);
+ expect(res.body, searchString).toEqual({ error: null });
+ }
+ });
+
+ it("reports the fault in a query the engine refuses", async () => {
+ const res = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "~author = tolkien" } });
+
+ expect(res.status).toBe(200);
+ expect(res.body.error).toContain("Relation can be compared only with property");
+
+ // Faults the client's own rules do not cover, which is the point of asking the engine.
+ const mixed = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "#a and #b or #c" } });
+ expect(mixed.body.error).toContain("Mixed usage of AND/OR");
+
+ const ordering = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString: "#book orderBy foo" } });
+ expect(ordering.body.error).toContain("must start with 'note'");
+ });
+
+ it("describes a query cut short rather than throwing out of the route", async () => {
+ // `parseNoteProperty` reads the token past the end of these, so validation has to survive it.
+ for (const searchString of [ "note.labels", "note.relations", "note.parents" ]) {
+ const res = await api.post<SearchLintResponse>("/api/search/lint", { body: { searchString } });
+
+ expect(res.status, searchString).toBe(200);
+ expect(res.body.error, searchString).toBeTruthy();
+ }
+ });
+
+ it("refuses a body that carries no query", async () => {
+ const res = await api.post("/api/search/lint", { body: {} });
+
+ expect(res.status).toBe(400);
+ });
+});
diff --git a/packages/trilium-core/src/routes/index.ts b/packages/trilium-core/src/routes/index.ts
index 11d2d5d87c..545b2ae673 100644
--- a/packages/trilium-core/src/routes/index.ts
+++ b/packages/trilium-core/src/routes/index.ts
@@ -240,6 +240,9 @@ export function buildSharedApiRoutes({ route, asyncRoute, asyncRouteWithoutTrans
apiRoute(PST, "/api/search-note/:noteId/result-details", searchRoute.getSearchResultDetails);
apiRoute(PST, "/api/search-and-execute-note/:noteId", searchRoute.searchAndExecute);
apiRoute(PST, "/api/search-related", searchRoute.getRelatedNotes);
+ // Ahead of the `:searchString` catch-all below, which would otherwise claim the literal path
+ // were it ever given a POST handler too.
+ apiRoute(PST, "/api/search/lint", searchRoute.lintSearchString);
apiRoute(GET, "/api/search/:searchString", searchRoute.search);
apiRoute(GET, "/api/search-templates", searchRoute.searchTemplates);
diff --git a/packages/trilium-core/src/services/search/services/search.ts b/packages/trilium-core/src/services/search/services/search.ts
index 240222586b..47d255c837 100644
--- a/packages/trilium-core/src/services/search/services/search.ts
+++ b/packages/trilium-core/src/services/search/services/search.ts
@@ -484,6 +484,30 @@ function parseQueryToExpression(query: string, searchContext: SearchContext) {
return expression;
}
+/**
+ * Reads `query` the way a search would, and answers the first thing wrong with it, or `null` where
+ * nothing is. Nothing is executed, so this costs a lex and a parse rather than a search.
+ *
+ * Two things the caller has to live with. `SearchContext` keeps only the first error, so a query
+ * holding several faults reports the earliest. And some faults are only found while the search
+ * runs — `note.content >= x` parses and is refused by `NoteContentFulltextExp` — so silence here
+ * is not a promise that the search will succeed.
+ */
+function validateSearchQuery(query: string): string | null {
+ const searchContext = new SearchContext();
+ searchContext.originalQuery = query;
+
+ try {
+ parseQueryToExpression(query || "", searchContext);
+ } catch (e: unknown) {
+ // The parser reads past the end of a query cut short after `note.labels` and the like, so a
+ // validator that let the throw out would fail on the very text it exists to describe.
+ return e instanceof Error ? e.message : String(e);
+ }
+
+ return searchContext.getError();
+}
+
function searchNotes(query: string, params: SearchParams = {}): BNote[] {
const searchResults = findResultsWithQuery(query, new SearchContext(params));
@@ -897,6 +921,7 @@ export default {
findResultsWithQuery,
findFirstNoteWithQuery,
searchNotes,
+ validateSearchQuery,
extractContentSnippet,
extractAttributeSnippet,
highlightSearchResults