Cache.matchAll() — Methode · JavaScript-Referenz

Signatur

Cache.prototype.matchAll(request, options)

Beschreibung

matchAll() durchsucht ein Cache-Objekt der Cache Storage API und liefert alle gespeicherten Antworten, die zur übergebenen Anfrage passen. Im Unterschied zu Cache.match(), das nur den ersten Treffer liefert, bekommen Sie hier immer ein Array zurück. Gibt es keinen Treffer, ist das Array leer.

Lassen Sie request weg, gibt die Methode alle Antworten im Cache zurück. Das hilft bei Wartungsaufgaben im Service Worker, etwa um die Cache-Größe zu schätzen, Einträge zu prüfen oder abgelaufene Antworten zu finden.

Mit dem Parameter options steuern Sie den Abgleich: ignoreSearch ignoriert den Query-String, ignoreMethod erlaubt auch andere Methoden als GET/HEAD, und ignoreVary übergeht die Prüfung des Vary-Headers. Mehrere Treffer für dieselbe Anfrage gibt es in der Praxis vor allem mit ignoreSearch: true oder ignoreVary: true.

Die API steht in Service Workern, Fenstern und Web Workern zur Verfügung, allerdings nur in sicheren Kontexten (HTTPS oder localhost). Den Zugriff auf einen konkreten Cache bekommen Sie über caches.open().

Parameter

Name	Typ	Default	Beschreibung
$request	Request \| string \| URL		Die gesuchte Anfrage als `Request`-Objekt oder URL. Wenn Sie den Parameter weglassen, bekommen Sie alle Antworten im Cache zurück.
$options	object	{}	Optionen für den Abgleich: `ignoreSearch` (`boolean`, Standard `false`): ignoriert den Query-String der URL. `ignoreMethod` (`boolean`, Standard `false`): prüft die HTTP-Methode nicht. `ignoreVary` (`boolean`, Standard `false`): ignoriert den `Vary`-Header. `cacheName`: wird bei `Cache`-Methoden ignoriert und wirkt nur bei `CacheStorage.match()`.

Rückgabewert

Typ

Promise<Response[]>

Beschreibung

Ein Promise, das mit einem Array aller passenden Response-Objekte erfüllt wird. Ohne Treffer ist das Array leer ([]). Das Promise wird nie mit undefined erfüllt.

Beispiele

Alle Varianten einer URL unabhängig vom Query-String finden

const findeArtikelVarianten = async () => {
  const cache = await caches.open('artikel-v1');
  // Zum Testen zwei Varianten ablegen
  await cache.put('/api/artikel?page=1', new Response('Seite 1'));
  await cache.put('/api/artikel?page=2', new Response('Seite 2'));

  const antworten = await cache.matchAll('/api/artikel', { ignoreSearch: true });
  console.log(`Treffer: ${antworten.length}`);
  for (const res of antworten) {
    console.log(res.url || '(synthetische Antwort)', await res.text());
  }
};

findeArtikelVarianten();

Treffer: 2 (synthetische Antwort) Seite 1 (synthetische Antwort) Seite 2

Alle Einträge eines Caches auflisten und Größe schätzen

const cacheGroesse = async (name) => {
  const cache = await caches.open(name);
  const antworten = await cache.matchAll(); // ohne Argument: alle Einträge
  let bytes = 0;
  for (const res of antworten) {
    const blob = await res.clone().blob();
    bytes += blob.size;
  }
  console.log(`${antworten.length} Einträge, ca. ${(bytes / 1024).toFixed(1)} KiB`);
  return bytes;
};

cacheGroesse('static-v1');

12 Einträge, ca. 348.7 KiB

Service Worker: abgelaufene Bilder anhand des Date-Headers entfernen

const MAX_ALTER_MS = 7 * 24 * 60 * 60 * 1000; // 7 Tage

self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open('bilder-v1');
    const requests = await cache.keys();
    const jetzt = Date.now();

    await Promise.all(requests.map(async (req) => {
      const [res] = await cache.matchAll(req);
      const datum = res?.headers.get('date');
      if (datum && jetzt - new Date(datum).getTime() > MAX_ALTER_MS) {
        await cache.delete(req);
      }
    }));
  })());
});

// Wichtig · Fallstricke

Response-Bodies lassen sich nur einmal lesen: Wenn Sie eine Antwort mit text() oder blob() auslesen und später noch einmal brauchen, rufen Sie vorher res.clone() auf.
Performance: matchAll() ohne Argument lädt bei großen Caches sehr viele Response-Objekte. Wenn Sie nur die URLs brauchen, ist cache.keys() deutlich günstiger.
HTTP-Methoden: Ohne ignoreMethod: true finden nur Anfragen mit GET oder HEAD einen Treffer. Mit POST bekommen Sie immer ein leeres Array.
Opaque Responses: Antworten aus no-cors-Anfragen haben status 0, und ihr Body lässt sich nicht lesen. Außerdem belegen sie im Browser-Kontingent oft deutlich mehr Speicher, als ihre tatsächliche Größe vermuten lässt.
Kompatibilität: In allen modernen Browsern verfügbar, aber nur in sicheren Kontexten (HTTPS, localhost). Im privaten Modus mancher Browser (z. B. älteres Firefox) kann caches fehlen oder einen Fehler werfen. Prüfen Sie deshalb vorher mit 'caches' in self.
Die Reihenfolge im Array entspricht der Einfügereihenfolge im Cache. Darauf sollten Sie sich aber nicht für Geschäftslogik verlassen.

Siehe auch

Cache Cache.match() Cache.keys() Cache.put() Cache.delete() CacheStorage.open() Response