@zeldrisho/pi-web-search 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-09-28
+
+### Changed
+
+- Simplify search guidance to favor broad discovery and avoid overly restrictive `site:` paths
+- Expose only core search controls (`mode`, `count`, `freshness`, and `spellcheck`) in the model-facing tool schema
+
+### Fixed
+
+- Document mode-specific result limits and correctly escape square brackets in rendered result links
+
+## [0.8.2] - 2026-09-24
+
+### Fixed
+
+- Handle already-aborted search requests and preserve provider errors when response-body cancellation or reading fails.
+
 ## [0.8.1] - 2026-09-12
 
 ### Fixed
@@ -91,7 +108,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add bounded Brave web search ([cbc9491](https://github.com/zeldrisho/pi-packages/commit/cbc9491dce36555ab91b6bef203ec8b380596a89))
 
-[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.8.1...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.8.3...HEAD
+[0.8.3]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.8.2...pi-web-search-v0.8.3
+[0.8.2]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.8.1...pi-web-search-v0.8.2
 [0.8.1]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.8.0...pi-web-search-v0.8.1
 [0.8.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.7.0...pi-web-search-v0.8.0
 [0.7.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.6.0...pi-web-search-v0.7.0

package/README.md

@@ -23,9 +23,7 @@ If unset, the tool reads the first matching `BRAVE_SEARCH_API_KEY=` line from th
 
 ## Usage
 
-`web_search` returns compact Brave results by default. Use `mode: "context"` for Brave's LLM Context API; it never fetches result URLs, so use `web_fetch` when live-page inspection is needed. Context queries are limited to 400 characters; web-mode queries are limited to 400 characters. Both modes accept an optional result count, freshness, language, country, `spellcheck`, and `goggles`.
-
-Web mode supports SafeSearch, extra snippets, search operators, result filters, page `offset` (0–9), UI language, and a version-scoped `dateRange` (`YYYY-MM-DDtoYYYY-MM-DD`). It allows up to 20 results. Context mode supports `threshold` (`strict`, `balanced`, `lenient`, `disabled`) and `depth` (`quick`, `standard`, `deep`), with up to 50 results. Options belonging to the other mode fail before a provider request.
+`web_search` returns compact Brave results by default. Its model-facing options are `mode` (`web` or `context`), `count`, `freshness`, and `spellcheck`. Context mode uses Brave's LLM Context API and never fetches result URLs; use `web_fetch` to inspect a live page. Context queries are limited to 400 characters; web-mode queries are limited to 400 characters.
 
 Identical searches are cached in byte-bounded memory and coalesced while in flight; cancelling one caller does not cancel work needed by another. Large output is written to a private temporary file and removed on write failure or session shutdown. Pi's interactive preview is collapsed by default (`Ctrl+O` expands it), and tool output remains bounded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-search",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Pi extension for bounded Brave web search and LLM context retrieval",
   "keywords": [
     "brave-search",
@@ -23,22 +23,20 @@
   },
   "files": [
     "src",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "CHANGELOG.md"
   ],
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.2",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
-    "typebox": "^1.3.16",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "typebox": "^1.3.30",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
-    "vite-plus": "0.3.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
+    "vite-plus": "0.3.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/brave.ts

@@ -1,26 +1,23 @@
-import {
-  SEARCH_CONTEXT_MAX_QUERY_CHARACTERS,
-  SEARCH_CONTEXT_MAX_RESULT_COUNT,
-  SEARCH_MAX_DATE_RANGE_CHARACTERS,
-  SEARCH_MAX_GOGGLES_CHARACTERS,
-  SEARCH_MAX_OFFSET,
-  SEARCH_MAX_RESULT_FILTER_CHARACTERS,
-  SEARCH_MIN_OFFSET,
-  SEARCH_MIN_RESULT_COUNT,
-  SEARCH_RESULT_FILTER_VALUES,
-  SEARCH_WEB_MAX_QUERY_CHARACTERS,
-  SEARCH_WEB_MAX_RESULT_COUNT,
-} from "./limits";
+import { SEARCH_RESULT_FILTER_VALUES } from "./limits";
 import { normalizeText, requestJson } from "./provider";
+import { normalizeResultFilter, validateProviderRequest } from "./request-validation";
+
+export { normalizeResultFilter, validateProviderRequest } from "./request-validation";
 
 export type Provider = "brave";
+
 export type Freshness = "day" | "week" | "month" | "year";
+
 export type SafesearchMode = "off" | "moderate" | "strict";
+
 export type SearchMode = "web" | "context";
+
 /** Relevance threshold for the LLM context endpoint. */
 export type ContextThresholdMode = "strict" | "balanced" | "lenient" | "disabled";
+
 /** Token-budget preset for the LLM context endpoint (coding-oriented). */
 export type ContextDepth = "quick" | "standard" | "deep";
+
 /** Allowed Brave `result_filter` values. */
 export type ResultFilterValue = (typeof SEARCH_RESULT_FILTER_VALUES)[number];
 
@@ -71,18 +68,27 @@ export interface SearchResponse {
 export function parseQueryMeta(query: BraveQuery | undefined): BraveQueryMeta {
   if (!query) return {};
   const meta: BraveQueryMeta = {};
+
   if (query.altered) meta.altered = query.altered;
+
   if (query.cleaned) meta.cleaned = query.cleaned;
+
   if (query.spellcheck_off !== undefined) meta.spellcheckOff = query.spellcheck_off;
+
   if (query.show_strict_warning !== undefined) meta.showStrictWarning = query.show_strict_warning;
+
   if (query.more_results_available !== undefined)
     meta.moreResultsAvailable = query.more_results_available;
   const operators = query.search_operators;
+
   if (operators) {
     if (operators.applied !== undefined) meta.operatorsApplied = operators.applied;
+
     if (operators.cleaned_query) meta.cleanedQuery = operators.cleaned_query;
+
     if (Array.isArray(operators.sites)) meta.operatorSites = [...operators.sites];
   }
+
   return meta;
 }
 
@@ -175,8 +181,11 @@ export interface ContextSearchExtras {
  */
 export function classifyResultQuality(result: { title: string; snippet: string }): ResultQuality {
   if (!result.title && !result.snippet) return "low";
+
   if (result.snippet.length >= 80) return "high";
+
   if (result.title || result.snippet) return "medium";
+
   return "low";
 }
 
@@ -188,118 +197,8 @@ const CONTEXT_DEPTH_BUDGETS = {
   ContextDepth,
   { tokens: number; snippets: number; tokensPerUrl: number; snippetsPerUrl: number }
 >;
-const BRAVE_MAX_EXTRA_SNIPPETS = 5;
-const DATE_RANGE_PATTERN = /^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/;
-const COUNTRY_PATTERN = /^([A-Za-z]{2}|ALL)$/;
-
-/**
- * Validates a search query and requested result count against the provider limits.
- *
- * @param query - The search query to validate
- * @param count - The requested number of results
- * @param mode - The search mode whose query and count limits apply
- * @param extras - Optional per-mode search options to validate
- * @throws If the query, count, or any option is outside the allowed range
- */
-export function validateProviderRequest(
-  query: string,
-  count: number,
-  mode: SearchMode,
-  extras?: ProviderRequestExtras,
-): void {
-  if (
-    mode === "context" &&
-    (extras?.extraSnippets !== undefined ||
-      extras?.operators !== undefined ||
-      extras?.resultFilter !== undefined ||
-      extras?.offset !== undefined ||
-      extras?.uiLang !== undefined ||
-      extras?.dateRange !== undefined)
-  ) {
-    throw new Error(
-      "The extraSnippets, operators, resultFilter, offset, uiLang, and dateRange options are only supported in web mode.",
-    );
-  }
-  if (mode === "web" && (extras?.threshold !== undefined || extras?.depth !== undefined)) {
-    throw new Error("The threshold and depth options are only supported in context mode.");
-  }
-  const maximumQueryCharacters =
-    mode === "context" ? SEARCH_CONTEXT_MAX_QUERY_CHARACTERS : SEARCH_WEB_MAX_QUERY_CHARACTERS;
-  if (query.length > maximumQueryCharacters) {
-    throw new Error(`Search queries cannot exceed ${maximumQueryCharacters} characters.`);
-  }
-  const maximumCount =
-    mode === "context" ? SEARCH_CONTEXT_MAX_RESULT_COUNT : SEARCH_WEB_MAX_RESULT_COUNT;
-  if (!Number.isInteger(count) || count < SEARCH_MIN_RESULT_COUNT || count > maximumCount) {
-    throw new Error(
-      `Search result count must be an integer between ${SEARCH_MIN_RESULT_COUNT} and ${maximumCount} in ${mode} mode.`,
-    );
-  }
-  if (extras?.country !== undefined && !COUNTRY_PATTERN.test(extras.country)) {
-    throw new Error('Search country must be a 2-letter code (e.g. "US") or "ALL".');
-  }
-  if (extras?.goggles !== undefined) {
-    if (!extras.goggles || extras.goggles.length > SEARCH_MAX_GOGGLES_CHARACTERS) {
-      throw new Error(
-        `Search goggles must be between 1 and ${SEARCH_MAX_GOGGLES_CHARACTERS} characters.`,
-      );
-    }
-  }
-  if (extras?.offset !== undefined) {
-    if (
-      !Number.isInteger(extras.offset) ||
-      extras.offset < SEARCH_MIN_OFFSET ||
-      extras.offset > SEARCH_MAX_OFFSET
-    ) {
-      throw new Error(
-        `Search offset must be an integer between ${SEARCH_MIN_OFFSET} and ${SEARCH_MAX_OFFSET}.`,
-      );
-    }
-  }
-  if (extras?.resultFilter !== undefined) {
-    normalizeResultFilter(extras.resultFilter);
-  }
-  if (extras?.dateRange !== undefined) {
-    if (
-      extras.dateRange.length > SEARCH_MAX_DATE_RANGE_CHARACTERS ||
-      !DATE_RANGE_PATTERN.test(extras.dateRange)
-    ) {
-      throw new Error(
-        "Search dateRange must use YYYY-MM-DDtoYYYY-MM-DD (e.g. 2025-01-01to2025-06-30).",
-      );
-    }
-  }
-  if (extras?.uiLang !== undefined && (extras.uiLang.length < 2 || extras.uiLang.length > 20)) {
-    throw new Error("Search uiLang must be between 2 and 20 characters (e.g. en-US).");
-  }
-}
 
-/**
- * Normalizes a comma-separated `result_filter` value.
- *
- * @param value - The raw filter list (e.g. `web,discussions,faq`)
- * @returns The normalized, deduplicated filter list
- * @throws If the list is empty, too long, or contains an unknown value
- */
-export function normalizeResultFilter(value: string): string {
-  const values = value
-    .split(",")
-    .map((item) => item.trim().toLowerCase())
-    .filter(Boolean);
-  const unique = [...new Set(values)];
-  const allowed = new Set<string>(SEARCH_RESULT_FILTER_VALUES);
-  if (
-    unique.length === 0 ||
-    value.length > SEARCH_MAX_RESULT_FILTER_CHARACTERS ||
-    unique.some((item) => !allowed.has(item)) ||
-    !unique.includes("web")
-  ) {
-    throw new Error(
-      `Search resultFilter must be a comma-separated list of: ${SEARCH_RESULT_FILTER_VALUES.join(", ")}, and must include "web" (only web results are mapped).`,
-    );
-  }
-  return unique.join(",");
-}
+const BRAVE_MAX_EXTRA_SNIPPETS = 5;
 
 /**
  * Maps `freshness`/`dateRange` tool options to Brave's `freshness` parameter.
@@ -316,8 +215,11 @@ export function mapFreshness(
   if (freshness && dateRange) {
     throw new Error("Search freshness and dateRange are mutually exclusive; set only one.");
   }
+
   if (dateRange) return dateRange;
+
   if (freshness) return { day: "pd", week: "pw", month: "pm", year: "py" }[freshness];
+
   return undefined;
 }
 
@@ -330,6 +232,7 @@ export function mapFreshness(
 function normalizeUrl(value: string): string {
   try {
     const url = new URL(value);
+
     return url.protocol === "http:" || url.protocol === "https:"
       ? url.toString().slice(0, 2048)
       : "";
@@ -346,30 +249,39 @@ function escapeMarkdownCell(value: string): string {
   return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
 }
 
+/** Renders a structured Brave snippet as a bounded Markdown table when possible. */
 function structuredSnippetToMarkdown(value: BraveSnippet): string | undefined {
   const table = value.table;
+
   if (!table || table.length === 0) return undefined;
 
   const rows = table.filter(Boolean);
   const headers = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+
   if (headers.length === 0) return undefined;
 
   const caption = value.caption ? `**${escapeMarkdownLinkText(value.caption)}**\n\n` : "";
   const header = `| ${headers.map(escapeMarkdownCell).join(" | ")} |`;
   const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+
   const body = rows
     .map((row) => `| ${headers.map((key) => escapeMarkdownCell(String(row[key]))).join(" | ")} |`)
     .join("\n");
+
   return `${caption}${header}\n${separator}\n${body}`;
 }
 
+/** Converts a Brave structured snippet payload to bounded, display-safe Markdown. */
 function braveSnippetToMarkdown(value: string): string {
   try {
     const snippet = value.trim();
+
     if (!snippet) return "";
     const parsed: BraveSnippet = JSON.parse(snippet);
     const rendered = structuredSnippetToMarkdown(parsed);
+
     if (rendered !== undefined) return rendered.slice(0, 8000);
+
     return `\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``.slice(0, 8000);
   } catch {
     return String(value)
@@ -403,18 +315,28 @@ export async function searchBraveWeb(
   url.searchParams.set("count", String(count));
   url.searchParams.set("safesearch", extras.safesearch ?? "moderate");
   url.searchParams.set("text_decorations", "false");
+
   if (language) url.searchParams.set("search_lang", language);
+
   if (extras.country) url.searchParams.set("country", extras.country.toUpperCase());
+
   if (extras.extraSnippets) url.searchParams.set("extra_snippets", "true");
+
   if (extras.operators !== undefined) url.searchParams.set("operators", String(extras.operators));
+
   if (extras.spellcheck !== undefined)
     url.searchParams.set("spellcheck", String(extras.spellcheck));
+
   if (extras.resultFilter)
     url.searchParams.set("result_filter", normalizeResultFilter(extras.resultFilter));
+
   if (extras.goggles) url.searchParams.set("goggles", extras.goggles);
+
   if (extras.offset !== undefined) url.searchParams.set("offset", String(extras.offset));
+
   if (extras.uiLang) url.searchParams.set("ui_lang", extras.uiLang);
   const mappedFreshness = mapFreshness(freshness, extras.dateRange);
+
   if (mappedFreshness) url.searchParams.set("freshness", mappedFreshness);
 
   const data = await requestJson<BraveWebResponse & { query?: BraveQuery }>(
@@ -432,15 +354,18 @@ export async function searchBraveWeb(
     results: (data.web?.results ?? []).map((item) => {
       const title = normalizeText(item.title ?? "", 300);
       let snippet = normalizeText(item.description ?? "", 600);
+
       if (extras.extraSnippets && item.extra_snippets?.length) {
         const additional = item.extra_snippets
           .slice(0, BRAVE_MAX_EXTRA_SNIPPETS)
           .map((value) => normalizeText(value ?? "", 300))
           .filter(Boolean);
+
         if (additional.length) {
           snippet = normalizeText([snippet, ...additional].filter(Boolean).join("\n\n"), 2000);
         }
       }
+
       return {
         title,
         url: normalizeUrl(item.url ?? ""),
@@ -480,12 +405,18 @@ export async function searchBraveContext(
   url.searchParams.set("maximum_number_of_tokens_per_url", String(budget.tokensPerUrl));
   url.searchParams.set("maximum_number_of_snippets_per_url", String(budget.snippetsPerUrl));
   url.searchParams.set("context_threshold_mode", extras.threshold ?? "strict");
+
   if (language) url.searchParams.set("search_lang", language);
+
   if (extras.country) url.searchParams.set("country", extras.country.toUpperCase());
+
   if (extras.safesearch) url.searchParams.set("safesearch", extras.safesearch);
+
   if (extras.spellcheck !== undefined)
     url.searchParams.set("spellcheck", String(extras.spellcheck));
+
   if (extras.goggles) url.searchParams.set("goggles", extras.goggles);
+
   if (freshness)
     url.searchParams.set(
       "freshness",
@@ -508,8 +439,10 @@ export async function searchBraveContext(
       const snippets = [
         ...new Set((item.snippets ?? []).map(braveSnippetToMarkdown).filter(Boolean)),
       ];
+
       const title = normalizeText(item.title ?? "", 300);
       const snippet = snippets.slice(0, budget.snippetsPerUrl).join("\n\n");
+
       return {
         title,
         url: normalizeUrl(item.url ?? ""),

package/src/cache.ts

@@ -48,9 +48,11 @@ export function stableKeyHash(key: string): string {
 export function resolveCachePath(directory: string, keyPath: string): string {
   const base = resolve(directory);
   const full = resolve(base, keyPath);
+
   if (full !== base && !full.startsWith(base + sep)) {
     throw new Error(`Refusing to write cache entry outside ${base}: ${keyPath}`);
   }
+
   return full;
 }
 
@@ -63,10 +65,12 @@ export function resolveCachePath(directory: string, keyPath: string): string {
 function encodeExpiresAt(expiresAt: number): Uint8Array {
   const out = new Uint8Array(8);
   let value = BigInt(Math.round(expiresAt));
+
   for (let index = 7; index >= 0; index -= 1) {
     out[index] = Number(value & 0xffn);
     value >>= 8n;
   }
+
   return out;
 }
 
@@ -78,7 +82,9 @@ function encodeExpiresAt(expiresAt: number): Uint8Array {
  */
 function decodeExpiresAt(bytes: Uint8Array): number {
   let value = 0n;
+
   for (let index = 0; index < 8; index += 1) value = (value << 8n) | BigInt(bytes[index]);
+
   return Number(value);
 }
 
@@ -123,19 +129,26 @@ export class ExpiringLruCache<K, V> {
    */
   get(key: K): V | undefined {
     const entry = this.#entries.get(key);
+
     if (entry) {
       if (entry.expiresAt <= this.now()) {
         this.#delete(key);
+
         return undefined;
       }
+
       this.#entries.delete(key);
       this.#entries.set(key, entry);
+
       return entry.value;
     }
+
     if (this.persistence) {
       const loaded = this.#loadFromDisk(key);
+
       if (loaded !== undefined) return loaded.value;
     }
+
     return undefined;
   }
 
@@ -150,13 +163,16 @@ export class ExpiringLruCache<K, V> {
   set(key: K, value: V, expiresAt: number): boolean {
     this.#delete(key);
     const size = this.sizeOf(value);
+
     if (size > this.maxBytes) return false;
 
     this.#entries.set(key, { expiresAt, size, value });
     this.#byteSize += size;
     this.#evict();
     const stored = this.#entries.has(key);
+
     if (stored && this.persistence) this.#writeToDisk(key, value, expiresAt);
+
     return stored;
   }
 
@@ -164,6 +180,7 @@ export class ExpiringLruCache<K, V> {
     let bytes: Uint8Array;
     const path = resolveCachePath(this.persistence!.directory, this.persistence!.keyToPath(key));
     let fileSize: number;
+
     try {
       // Serialized metadata can exceed the value budget, but never allow an
       // unbounded cache file to be read into memory.
@@ -171,37 +188,50 @@ export class ExpiringLruCache<K, V> {
     } catch {
       return undefined;
     }
+
     if (fileSize < 8 || fileSize > this.maxBytes * 2 + 65_536) {
       this.#removeFromDisk(key);
+
       return undefined;
     }
+
     try {
       bytes = readFileSync(path);
     } catch {
       return undefined;
     }
+
     let entry: ExpiringCacheEntry<V>;
+
     try {
       const expiresAt = decodeExpiresAt(bytes);
       const value = this.persistence!.deserialize(bytes.subarray(8));
+
       if (this.persistence!.validate && !this.persistence!.validate(value)) {
         throw new Error("invalid cache entry");
       }
+
       const size = this.sizeOf(value);
+
       if (!Number.isFinite(size) || size < 0 || size > this.maxBytes)
         throw new Error("oversized cache entry");
       entry = { expiresAt, size, value };
     } catch {
       this.#removeFromDisk(key);
+
       return undefined;
     }
+
     if (entry.expiresAt <= this.now()) {
       this.#removeFromDisk(key);
+
       return undefined;
     }
+
     this.#entries.set(key, entry);
     this.#byteSize += entry.size;
     this.#evict();
+
     return this.#entries.get(key);
   }
 
@@ -211,10 +241,12 @@ export class ExpiringLruCache<K, V> {
       mkdirSync(directory, { recursive: true, mode: 0o700 });
       chmodSync(directory, 0o700);
       const payload = this.persistence!.serialize(value);
+
       if (payload.byteLength > this.maxBytes * 2 + 65_536)
         throw new Error("oversized cache payload");
       const path = resolveCachePath(directory, this.persistence!.keyToPath(key));
       const temp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+
       try {
         writeFileSync(temp, Buffer.concat([encodeExpiresAt(expiresAt), payload]), { mode: 0o600 });
         chmodSync(temp, 0o600);
@@ -241,27 +273,35 @@ export class ExpiringLruCache<K, V> {
 
   #maintainDisk(): void {
     const persistence = this.persistence!;
+
     try {
       const files = readdirSync(persistence.directory);
       const candidates: Array<{ path: string; size: number; mtime: number }> = [];
+
       for (const file of files) {
         const path = resolveCachePath(persistence.directory, file);
+
         if (file.endsWith(".tmp")) {
           try {
             unlinkSync(path);
           } catch {
             // Best effort cleanup.
           }
+
           continue;
         }
+
         try {
           const stat = statSync(path);
+
           if (!stat.isFile() || stat.size < 8 || stat.size > this.maxBytes * 2 + 65_536) {
             unlinkSync(path);
             continue;
           }
+
           const descriptor = openSync(path, "r");
           const header = new Uint8Array(8);
+
           try {
             if (
               readSync(descriptor, header, 0, 8, 0) !== 8 ||
@@ -273,17 +313,22 @@ export class ExpiringLruCache<K, V> {
           } finally {
             closeSync(descriptor);
           }
+
           candidates.push({ path, size: stat.size, mtime: stat.mtimeMs });
         } catch {
           // Ignore races and inaccessible files in this best-effort sweep.
         }
       }
+
       candidates.sort((a, b) => a.mtime - b.mtime);
       let total = candidates.reduce((sum, candidate) => sum + candidate.size, 0);
+
       while (candidates.length > this.maxEntries || total > this.maxBytes * 2 + 65_536) {
         const oldest = candidates.shift();
+
         if (!oldest) break;
         total -= oldest.size;
+
         try {
           unlinkSync(oldest.path);
         } catch {
@@ -298,6 +343,7 @@ export class ExpiringLruCache<K, V> {
   #evict(): void {
     while (this.#entries.size > this.maxEntries || this.#byteSize > this.maxBytes) {
       const oldest = this.#entries.keys().next().value;
+
       if (oldest === undefined) break;
       this.#delete(oldest);
     }
@@ -305,12 +351,16 @@ export class ExpiringLruCache<K, V> {
 
   #delete(key: K): void {
     const entry = this.#entries.get(key);
+
     if (!entry) {
       if (this.persistence) this.#removeFromDisk(key);
+
       return;
     }
+
     this.#entries.delete(key);
     this.#byteSize -= entry.size;
+
     if (this.persistence) this.#removeFromDisk(key);
   }
 }