# Cache and share requests

Reuse successful normalized responses locally with explicit TTL, capacity, and independent caller cancellation.

Canonical: https://searchsdk.dev/docs/reliability/caching
Markdown: https://searchsdk.dev/docs/reliability/caching.md

<a id="configure"></a>

## Configure reuse explicitly

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

**reuse.ts · fixture**

```typescript
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

```

<a id="cache"></a>

## 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'`.

<a id="inflight"></a>

## 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.

> **Shared execution has one upstream lifetime**
> A later subscriber joins the existing operation and its existing deadline. Joining does not restart or extend upstream work. Your cache and sharing scope should match your application's data-isolation boundary.

<a id="concurrency"></a>

## 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.

- [Deadline behavior](https://searchsdk.dev/docs/reliability/timeouts)
- [Usage on reused responses](https://searchsdk.dev/docs/reliability/usage)