@cache-kit/cache-key

Deterministic, URL-style cache key generation from any JS object. Fully standalone — no dependency on @cache-kit/cache or anything else. Also available as cache.buildKey(...) if you're using @cache-kit/cache.

npm install @cache-kit/cache-key

import { buildKey, parseKey } from '@cache-kit/cache-key';

buildKey({ category: 1, price: { min: 100 } });
// => "category=1&price[min]=100"

buildKey({ price: { min: 100 }, category: 1 });
// => "category=1&price[min]=100"   (same key — property order never matters)

Options

buildKey(input, {
  excludedValues: [undefined, null, ''], // default: [undefined]
  normalizeArrays: true, // default: false (order preserved)
  hash: 'sha256', // default: false (readable string)
  hashLength: 16, // truncate the digest; default: full length
});

parseKey — read this before relying on it

parseKey reverses the structure of a key perfectly (bracket notation is naturally invertible). It does not guarantee recovering the exact original value, for three reasons, all deliberate tradeoffs rather than bugs:

1. Exclusion is destructive by design. excludedValues erases information from the key entirely — that's the point (so {a: 1, b: undefined} and {a: 1} hit the same cache entry). There's no way to tell from the key alone that b was ever present.
2. No type tags. 100 (number) and "100" (string) serialize identically, so parseKey always resolves ambiguous scalars the same way (numeric/boolean-looking strings become numbers/booleans). This is the same well-known limitation the popular qs library's parse() has.
3. normalizeArrays is also destructive to original ordering, for the same reason as (1).

Safe use: debugging, logging, or an admin UI showing "what filters produced this cache entry." Not safe: reconstructing a query object you then feed into a typed query builder or DB call expecting exact types — keep storing the original object for that.

Hashed output (hash option set) cannot be parsed — hashing is one-way.

License

MIT