Query Keys

What is a query key?

Every cache entry is identified by a query key — a deterministic string derived from the endpoint method, path, and parameters:

METHOD:path:serializedParams

For example:

GET:/users:{}
GET:/users/1:{"path":{"id":1}}
POST:/users/search:{"body":{"role":"admin"}}

Keys are generated automatically — you never construct them manually unless you’re building custom tooling.

Stable serialization

Parameters are JSON-serialized with alphabetically sorted keys, ensuring that { b: 2, a: 1 } and { a: 1, b: 2 } produce the same cache key:

stableSerialize({ z: 3, a: 1, m: 2 })
// → '{"a":1,"m":2,"z":3}'

Additional behaviors:

undefined values are dropped from objects
Date objects are serialized to ISO strings
NaN and Infinity are preserved as "NaN" / "Infinity"
null is preserved
Arrays preserve order
Functions and symbols throw in development

Hashing for large keys

When a serialized key exceeds 1024 characters, kweri hashes it with crypto.subtle.digest('SHA-256') and stores the hash instead. The original key is kept alongside for display in DevTools. This keeps memory usage bounded when params contain large objects (e.g., full filter sets).

Reading a key

const key = kweri.getQueryKey(getUsers, { role: 'admin' })
// → 'GET:/users:{"role":"admin"}'

Key-based invalidation

The invalidateByKey and removeByKey methods accept the serialized key string directly — primarily used by DevTools:

kweri.invalidateQueryByKey('GET:/users:{}')

For application code, prefer invalidateByPath or invalidateQuery since they don’t require you to construct the key string.

How params are flattened

When you call kweri.query(endpoint, params), params in the nested { path, query, body } shape are flattened before being passed to the ApiClient:

// Input
{ path: { id: 1 }, query: { expand: true }, body: { name: 'Alice' } }

// Flattened for URL building
{ id: 1, expand: true, body: { name: 'Alice' } }

path.* keys merge to the top level (used for {id} substitution)
query.* keys merge to the top level (appended as query string)
body stays as body (JSON-encoded as the request body)

The cache key is computed from the original (un-flattened) params to avoid collisions.

Getting Started

Core Concepts

Core API

Framework Adapters

CLI

Guides

Advanced

API Reference

What is a query key?

Stable serialization

Hashing for large keys

Reading a key

Key-based invalidation

How params are flattened

​What is a query key?

​Stable serialization

​Hashing for large keys

​Reading a key

​Key-based invalidation

​How params are flattened

What is a query key?

Stable serialization

Hashing for large keys

Reading a key

Key-based invalidation

How params are flattened