Cache and share requests
Reuse successful normalized responses locally with explicit TTL, capacity, and independent caller cancellation.
On this page
Configure reuse explicitly
import { createSearch } from '@belweave/search-sdk';
import { createMockProvider } from '@belweave/search-sdk/testing';
const client = createSearch({
provider: createMockProvider(),
cache: { ttlMs: 30_000, maxEntries: 100 },
deduplicate: true,
maxConcurrency: 4,
});
const request = { query: 'SQLite concurrency', limit: 5 };
await client.web.search(request);
const reused = await client.web.search(request);
console.log(reused.reuse); // cache
Successful-result cache
The cache is per client and in memory. Only successful responses are stored; errors are not. TTL starts at insertion and cache hits do not extend it. Capacity defaults to 100 entries and uses least-recently-used eviction. Stored and returned responses are defensive snapshots. Entry count is bounded, not total bytes; there is no persistent cache or invalidation API.
Keys reflect the normalized request. Domain lists are sorted for equivalence without rewriting the query. The cached response keeps its original retrieval time, attempt trace, and usage; it does not represent a fresh provider call or fresh charge. Reuse is labeled reuse: 'cache'.
Identical in-flight searches
With deduplicate: true, matching active requests share one execution and each subscriber receives a response snapshot. Joined subscribers receive reuse: 'inflight'. Each caller can cancel independently; the shared operation is aborted when no subscribers remain.
Bound active operations
Normalized maxConcurrency is optional and has no active-operation limit when omitted. When configured, it bounds active SDK operations, including retry/backoff time, and queue time counts toward the caller's total deadline. Native transports separately default to eight active operations per transport instance. FIFO queues allow up to 1,024 waiting operations, then return unavailable.