Cache.keys() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.keys(request, options)

Beschreibung

Mit Cache.keys() fragt man ab, welche Anfragen in einem bestimmten Cache gespeichert sind. Jeder Eintrag eines Caches besteht aus einem Paar aus Request (Schlüssel) und Response (Wert). Die Methode liefert nur die Schlüssel, die Antworten selbst nicht.

Ohne Argument gibt die Methode alle Schlüssel des Caches zurück. Übergibt man eine Anfrage oder eine URL, erhält man nur die passenden Einträge. Mit dem Parameter options lässt sich der Abgleich lockern, etwa indem man den Query-String, die HTTP-Methode oder den Vary-Header ignoriert.

Typische Einsatzfälle sind:

Aufräumen veralteter Einträge in einem Service Worker
Größe eines Caches begrenzen (z. B. nur die neuesten N Einträge behalten)
Debugging und Werkzeuge, die den Cache-Inhalt anzeigen

Die Reihenfolge der zurückgegebenen Schlüssel entspricht laut Spezifikation der Reihenfolge, in der die Einträge eingefügt wurden. Das ist praktisch für einfache FIFO-Strategien.

Parameter

Name	Typ	Default	Beschreibung
$request	Request \| string \| URL		Optional. Die Anfrage, nach der gefiltert werden soll. Das kann ein `Request`-Objekt oder eine URL sein. Fehlt der Parameter, werden alle Schlüssel zurückgegeben.
$options	object	{}	Optional. Objekt, das den Abgleich steuert. Es gibt folgende Eigenschaften: `ignoreSearch` (`boolean`, Standard `false`): Ignoriert den Query-String der URL. `ignoreMethod` (`boolean`, Standard `false`): Lässt auch andere Methoden als `GET`/`HEAD` als Suchanfrage zu. `ignoreVary` (`boolean`, Standard `false`): Ignoriert den `Vary`-Header beim Abgleich. `cacheName`: Wird von `Cache.keys()` ignoriert und ist nur für `CacheStorage.match()` relevant.

Rückgabewert

Typ

Promise<ReadonlyArray<Request>>

Beschreibung

Ein Promise, das mit einem Array von Request-Objekten erfüllt wird. Das Array ist leer, wenn der Cache leer ist oder kein Eintrag passt.

Beispiele

Alle gecachten URLs auflisten

const listCachedUrls = async (cacheName) => {
  const cache = await caches.open(cacheName);
  const requests = await cache.keys();
  return requests.map((req) => req.url);
};

listCachedUrls('static-v1').then((urls) => console.log(urls));

["https://example.com/", "https://example.com/app.css", "https://example.com/app.js"]

Cache auf die neuesten 50 Einträge begrenzen (Service Worker)

const trimCache = async (cacheName, maxItems) => {
  const cache = await caches.open(cacheName);
  const keys = await cache.keys();
  // Die Reihenfolge entspricht der Einfügereihenfolge, die ältesten stehen also vorne
  const excess = keys.length - maxItems;
  if (excess <= 0) return 0;
  await Promise.all(keys.slice(0, excess).map((req) => cache.delete(req)));
  return excess;
};

self.addEventListener('fetch', (event) => {
  if (event.request.destination === 'image') {
    event.waitUntil(trimCache('images', 50));
  }
});

Alle Varianten einer URL unabhängig vom Query-String finden und löschen

const purgeVariants = async (url) => {
  const cache = await caches.open('api-cache');
  const matches = await cache.keys(url, { ignoreSearch: true });
  console.log(`${matches.length} Varianten gefunden`);
  await Promise.all(matches.map((req) => cache.delete(req)));
};

purgeVariants('/api/products');

3 Varianten gefunden

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die Cache API steht nur unter HTTPS (oder localhost) zur Verfügung. Sie ist in Fenstern, Web Workern und Service Workern nutzbar. In privaten Fenstern mancher Browser (z. B. älteren Firefox-Versionen) kann caches fehlen oder einen Fehler werfen.
Performance: keys() ohne Filter erzeugt für jeden Eintrag ein Request-Objekt. Bei sehr großen Caches kann das spürbar Speicher und Zeit kosten. Wo es möglich ist, sollte man daher mit request filtern.
Nur Schlüssel: Die Methode liefert keine Response-Objekte. Für die Antworten braucht man Cache.match() oder Cache.matchAll().
Methoden-Abgleich: Ohne ignoreMethod: true passen nur GET- und HEAD-Anfragen. Übergibt man z. B. einen POST-Request, erhält man ein leeres Array.
Vary-Header: Einträge mit Vary-Header passen unter Umständen nicht, wenn sich die Header der Anfrage unterscheiden. Mit ignoreVary: true lässt sich das umgehen.
Die Reihenfolge nach Einfügezeitpunkt ist in der Spezifikation festgelegt. Sehr alte Browser-Implementierungen haben sie aber nicht immer garantiert.

Siehe auch

Cache Cache.match() Cache.delete() Cache.put() CacheStorage.keys() Request