npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jdsalasc/solvejs-cache

v0.3.1

Published

TypeScript cache utilities for TTL maps, async memoization, LRU eviction, and stale-while-revalidate fetches, with deterministic keys and injectable clocks.

Readme

@jdsalasc/solvejs-cache

npm node

Live documentation: run this package's examples in your browser.

Zero-dependency caching primitives for Node.js and the browser: TTL maps, LRU eviction, async memoization with in-flight deduplication, and stale-while-revalidate reads. Every clock is injectable, so expiry is deterministic in tests.

Utilities

  • stableKey
  • createTtlCache
  • createLruCache
  • memoizeAsync
  • createSingleFlight
  • createStaleWhileRevalidate
  • CacheError

When to use this package

Use it when a hot path recomputes the same thing, when an API client should not call the same endpoint twice in a row, or when a read should keep serving the last good value while a refresh runs. Every cache takes an injectable clock, so expiry is testable without waiting on real time.

Install

npm i @jdsalasc/solvejs-cache

Quick example

import { createSingleFlight, createTtlCache, createLruCache, memoizeAsync, createStaleWhileRevalidate } from "@jdsalasc/solvejs-cache";

const flags = createTtlCache<boolean>({ ttlMs: 60_000 });
flags.set("new-checkout", true);
flags.get("new-checkout"); // true, undefined after 60s

const recent = createLruCache<string>({ maxSize: 500 });
recent.set("user:1", "ada");
recent.get("user:1"); // "ada", and the entry is now the most recently used

const loadUser = memoizeAsync(async (id: string) => fetchUser(id));
await loadUser("u1"); // one request
await loadUser("u1"); // served from memory

const refreshPrices = createSingleFlight(async () => fetchPrices());
await Promise.all([refreshPrices(), refreshPrices()]); // one in-flight request, not cached afterwards

const readConfig = createStaleWhileRevalidate(fetchConfig, { freshMs: 30_000, staleMs: 300_000 });
await readConfig(); // loads
await readConfig(); // fresh, no reload

createSingleFlight deduplicates only concurrent calls. The resolved value is not cached, so the next call after it settles runs the loader again. That is the right shape for manual refresh buttons, webhook fan-in and "load once per request" work; use memoizeAsync when you also want to keep the value for a TTL.

Injectable clocks

Every time-dependent function accepts now, which is what makes expiry deterministic in tests:

let now = 1000;
const cache = createTtlCache<string>({ ttlMs: 100, now: () => now });

cache.set("a", "value");
now += 100;
cache.get("a"); // undefined, no timers and no waiting

stableKey

stableKey sorts object keys at every depth, so two structurally equal values always produce the same string regardless of insertion order. That is what makes it safe as a cache key.

stableKey({ a: 1, b: 2 }) === stableKey({ b: 2, a: 1 }); // true

Array order is preserved, because it carries meaning. Functions, symbols and circular references throw CacheError rather than producing a key that silently collides.

Errors

Failures throw a CacheError with a stable code and a details object.

| Code | Meaning | |---|---| | CACHE_INVALID_OPTION | A duration or size option is missing, non-finite, or not positive. | | CACHE_INVALID_KEY | A cache key is not a non-empty string. | | CACHE_LOADER_FAILED | Reserved for loader failures surfaced by the stale-while-revalidate wrapper. |

Limitations and Constraints

A fractional ttl is valid, a fractional maxSize is not

Durations are milliseconds, so ttlMs: 1.5 is accepted. maxSize counts entries, so it must be a whole number and maxSize: 1.5 throws.

A cached undefined is a hit, not a miss

has reports true for an entry holding undefined, but get still returns undefined. Use has when you need to tell the two apart.

memoizeAsync does not cache a rejection

A call that rejects is removed from the cache, so a transient failure is retried rather than pinned for the whole ttl. Concurrent calls for the same key share one in-flight promise.

stableKey drops undefined properties, like JSON.stringify

stableKey({ a: 1, b: undefined }) equals stableKey({ a: 1 }). If your loader distinguishes those two inputs, give memoizeAsync an explicit key function.

Entries expire lazily

Nothing runs in the background. An expired entry is removed when it is read, or when keys or size is called, so a cache left untouched keeps its expired entries in memory. Call clear on shutdown if that matters.

Review notes

  • createLruCache().set(key, value, { ttlMs }) honors a per-entry TTL that overrides the cache default.