Reliability & Metrics

In production, search engines often crash due to OOM errors or AI API rate limits. pg-smart-search (v1.3+) introduces native safeguards.

OOM Protection

If a user searches for a highly common term (e.g., "the"), a naive search will load millions of rows into Node.js memory, causing an Out-Of-Memory crash.

The real guard here is maxLimit (default 1000): every search() call clamps its per-page limit to this ceiling before building SQL, regardless of what the caller requests, so a single call can never pull an unbounded number of rows into memory.

Separately, a MAX_ROWS constant (10,000) exists purely as a diagnostic: if you opt into an exact count (skipTotalCount: false) and the resulting total exceeds it, the engine logs a warning via your configured logger. It's informational only — it does not throw, clamp anything, or run by default (since total is undefined unless you explicitly ask for the count).

In-Flight Request Deduplication

Multiple callers requesting the same search at the same time, within a single process, share one in-flight query instead of each issuing their own (reference-counted cancellation, so the shared query only aborts once every attached caller has cancelled). This is process-local — it does not coordinate across multiple Node.js instances sharing a Redis cache; see Caching for what RedisCacheProvider does and doesn't do.

AI API Rate Limiting (p-queue)

Semantic search relies on external APIs (OpenAI, Gemini) which have strict rate limits. The engine includes an intelligent rate-limiting queue (p-queue):

• If the API returns 429 Too Many Requests, the engine automatically pauses vector search requests and retries them, preventing cascade failures.

True Zero-Freeze Networking

Native AbortController propagation ensures timeouts (10s default) actually kill underlying fetch requests to AI APIs, preventing frozen connections from blocking the event loop.