IDBKeyRange.only() — Methode · JavaScript-Referenz

Signatur

IDBKeyRange.only(value)

Beschreibung

Die statische Methode IDBKeyRange.only() erstellt einen Schlüsselbereich, dessen Unter- und Obergrenze identisch sind und beide eingeschlossen werden. Das Ergebnis entspricht also IDBKeyRange.bound(value, value), liest sich aber klarer.

Man nutzt sie vor allem, um mit openCursor(), getAll(), count() oder delete() gezielt alle Datensätze mit einem bestimmten Schlüssel anzusprechen. Besonders praktisch ist das bei nicht eindeutigen Indizes: Hier liefert ein Cursor über IDBKeyRange.only("Berlin") alle Einträge, deren Indexwert genau "Berlin" ist.

Als Wert ist jeder gültige IndexedDB-Schlüssel erlaubt: number (außer NaN), string, Date (gültiges Datum), ArrayBuffer/Typed Arrays sowie Arrays aus diesen Typen (zusammengesetzte Schlüssel). Viele Methoden wie get() akzeptieren auch direkt einen Schlüssel – only() ist dann nötig, wenn explizit ein IDBKeyRange-Objekt gebraucht wird oder der Code einheitlich mit Bereichen arbeiten soll.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number\|string\|Date\|ArrayBuffer\|ArrayBufferView\|Array		Der einzige Schlüsselwert, den der Bereich enthalten soll. Muss ein gültiger IndexedDB-Schlüssel sein.

Rückgabewert

Typ

IDBKeyRange

Beschreibung

Ein neues IDBKeyRange mit lower === upper === value sowie lowerOpen und upperOpen jeweils false.

Beispiele

Eigenschaften des Bereichs prüfen

const range = IDBKeyRange.only(42);
console.log(range.lower, range.upper, range.lowerOpen, range.upperOpen);
console.log(range.includes(42), range.includes(43));

42 42 false false true false

Alle Kunden einer Stadt über einen Index lesen

const openDb = () => new Promise((resolve, reject) => {
  const req = indexedDB.open('shop', 1);
  req.onupgradeneeded = () => {
    const store = req.result.createObjectStore('kunden', { keyPath: 'id' });
    store.createIndex('stadt', 'stadt', { unique: false });
    store.put({ id: 1, name: 'Anna', stadt: 'Berlin' });
    store.put({ id: 2, name: 'Ben', stadt: 'Hamburg' });
    store.put({ id: 3, name: 'Clara', stadt: 'Berlin' });
  };
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

const kundenAus = async (stadt) => {
  const db = await openDb();
  const index = db.transaction('kunden').objectStore('kunden').index('stadt');
  return new Promise((resolve, reject) => {
    const req = index.getAll(IDBKeyRange.only(stadt));
    req.onsuccess = () => resolve(req.result.map((k) => k.name));
    req.onerror = () => reject(req.error);
  });
};

kundenAus('Berlin').then(console.log);

["Anna", "Clara"]

Cursor über zusammengesetzten Schlüssel und Treffer zählen

// Annahme: Index 'kategorie_jahr' mit keyPath ['kategorie', 'jahr']
const zaehleBuecher = (db) => new Promise((resolve, reject) => {
  const index = db.transaction('buecher').objectStore('buecher').index('kategorie_jahr');
  const req = index.count(IDBKeyRange.only(['Krimi', 2023]));
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

// const anzahl = await zaehleBuecher(db);
// console.log(`Krimis aus 2023: ${anzahl}`);

Krimis aus 2023: 5

// Wichtig · Fallstricke

Ist value kein gültiger Schlüssel (z. B. undefined, null, NaN, true, ein Objekt oder ein ungültiges Date), wirft die Methode eine DOMException vom Typ DataError.
Der Vergleich ist typgenau: IDBKeyRange.only(1) findet keinen Datensatz mit dem Schlüssel "1". Zahlen werden in IndexedDB immer vor Strings einsortiert.
Bei Arrays als Schlüssel müssen Reihenfolge und Typen aller Elemente exakt übereinstimmen.
Für Präfix- oder Bereichssuchen passt only() nicht, dafür gibt es IDBKeyRange.bound(), lowerBound() und upperBound().
In allen modernen Browsern und in Web Workern verfügbar. Sehr alte Browser brauchten Präfixe (webkitIDBKeyRange).

Siehe auch

IDBKeyRange IDBKeyRange.bound() IDBKeyRange.lowerBound() IDBKeyRange.upperBound() IDBKeyRange.prototype.includes() IDBIndex.prototype.openCursor() IDBObjectStore.prototype.getAll()