Skip to content

Email for professionals and teams

5.3 KB
Raw Blame
import type { ParsedSearchQuery, SearchToken } from "./types";
import { dateFromZonedFields, normalizeTimeZone } from "@/lib/time/utils";

/**
 * Gmail-style search grammar shared by the search box and the API:
 *
 *   from:maya to:"sam okoro" subject:invoice has:attachment is:unread
 *   is:starred after:2026-09-01 before:2026-09-30 "exact phrase" -excluded word
 *
 * The older `title:` and bare `:unread` / `:read` forms keep working.
 */
const OPERATOR_RE = /(?:^|\s)(from|to|subject|title|has|is|after|before|newer|older):(?:"([^"]*)"|(\S+))/gi;

export function parseSearchQuery(raw: string, timeZone = "UTC"): ParsedSearchQuery {
	const parsed: ParsedSearchQuery = { text: "", needsFullText: false };
	let rest = raw ?? "";

	rest = rest.replace(OPERATOR_RE, (_match, key: string, quoted: string | undefined, bare: string | undefined) => {
		const value = (quoted ?? bare ?? "").trim();
		switch (key.toLowerCase()) {
			case "from":
				parsed.from = value;
				break;
			case "to":
				parsed.to = value;
				break;
			case "subject":
			case "title":
				parsed.subject = value;
				break;
			case "has":
				if (/^attachments?$/i.test(value)) parsed.hasAttachment = true;
				break;
			case "is":
				if (/^unread$/i.test(value)) parsed.read = "unread";
				else if (/^read$/i.test(value)) parsed.read = "read";
				else if (/^starred$/i.test(value)) parsed.starred = true;
				break;
			case "after":
			case "newer":
				parsed.after = parseDate(value, timeZone) ?? parsed.after;
				break;
			case "before":
			case "older":
				parsed.before = parseDate(value, timeZone) ?? parsed.before;
				break;
		}
		return " ";
	});

	if (/(^|\s):unread(?=\s|$)/i.test(rest)) {
		parsed.read = "unread";
		rest = rest.replace(/(^|\s):unread(?=\s|$)/gi, " ");
	} else if (/(^|\s):read(?=\s|$)/i.test(rest)) {
		parsed.read = "read";
		rest = rest.replace(/(^|\s):read(?=\s|$)/gi, " ");
	}

	parsed.text = rest.replace(/\s+/g, " ").trim();
	parsed.needsFullText = !!(parsed.text || parsed.from || parsed.to || parsed.subject);
	return parsed;
}

function parseDate(value: string, timeZone: string): Date | undefined {
	const match = value.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})$/);
	if (!match) return undefined;
	const date = new Date(0);
	date.setUTCFullYear(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
	if (date.getUTCFullYear() !== Number(match[1]) || date.getUTCMonth() !== Number(match[2]) - 1 || date.getUTCDate() !== Number(match[3])) return undefined;
	return dateFromZonedFields(date, normalizeTimeZone(timeZone));
}

/** Split free text into phrases ("..."), negations (-word) and plain terms. */
export function tokenizeSearchText(text: string): SearchToken[] {
	const tokens: SearchToken[] = [];
	const re = /(-?)"([^"]+)"|(-?)(\S+)/g;
	let match: RegExpExecArray | null;
	while ((match = re.exec(text))) {
		if (match[2] !== undefined) {
			const term = match[2].trim();
			if (term) tokens.push({ term, negate: match[1] === "-", phrase: true });
		} else {
			const term = match[4].replace(/^-+/, "").trim();
			if (term) tokens.push({ term, negate: match[3] === "-", phrase: false });
		}
	}
	return tokens;
}

/** FTS5 string literal: double quotes doubled, so user input can never alter the query grammar. */
function ftsString(value: string): string {
	return `"${value.replace(/"/g, '""')}"`;
}

/**
 * One term. Phrases match whole words; plain terms match by prefix so "inv"
 * finds "invoice". Punctuation FTS5 treats as separators is normalised to
 * spaces first, so "[email protected]" becomes the phrase "maya acme test".
 */
function ftsTerm(term: string, phrase: boolean): string {
	const cleaned = term.replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
	if (!cleaned) return "";
	if (phrase || cleaned.includes(" ")) {
		// A multi-word prefix query needs the last word starred, which FTS5 only
		// allows inside a phrase as `"a b" *`; keep it simple and require whole words.
		return ftsString(cleaned);
	}
	return `${ftsString(cleaned)}*`;
}

/**
 * Build the FTS5 MATCH expression. Column filters restrict a term to one
 * column; free text is ANDed across the whole row. Returns null when there is
 * nothing to match, so callers skip the index entirely.
 */
export function buildFtsMatch(parsed: ParsedSearchQuery): string | null {
	const parts: string[] = [];

	for (const token of tokenizeSearchText(parsed.text)) {
		const expr = ftsTerm(token.term, token.phrase);
		if (!expr) continue;
		parts.push(token.negate ? `NOT ${expr}` : expr);
	}
	const column = (name: string, value: string | undefined) => {
		if (!value) return;
		const terms = tokenizeSearchText(value)
			.map((token) => ftsTerm(token.term, token.phrase))
			.filter(Boolean);
		if (terms.length === 0) return;
		parts.push(`${name} : (${terms.join(" AND ")})`);
	};
	column("subject", parsed.subject);
	column("from_addr", parsed.from);
	column("{to_addr cc_addr}", parsed.to);

	if (parts.length === 0) return null;
	// FTS5 has no unary NOT: "a NOT b" is binary. A leading negation is turned
	// into "match anything" minus the term.
	const positives = parts.filter((part) => !part.startsWith("NOT "));
	const negatives = parts.filter((part) => part.startsWith("NOT ")).map((part) => part.slice(4));
	const base = positives.length > 0 ? positives.join(" AND ") : `${ftsString("")}*`;
	return negatives.length > 0 ? `(${base}) NOT (${negatives.join(" OR ")})` : base;
}