IDBKeyRange
===========

IndexedDB API の **`IDBKeyRange`** インターフェイスは、キーとして使われるデータ型における 1 個の連続した範囲を表します。`IDBObjectStore` および `IDBIndex` のオブジェクトから、キーまたはキーの範囲を用いてレコードを取り出すことができます。下限および上限により、範囲を制限できます。たとえば、キーが A 〜 Z の範囲にある全ての値を反復できます。

キーの範囲は、単一の値、もしくは上限および下限 (端点ともいう) をもつ範囲になり得ます。キーの範囲が上限と下限の両方を持つ場合、*有界* と呼びます。境界が無い場合、*非有界* と呼びます。有界のキーの範囲は、開 (端点を含まない) にも閉 (端点を含む) にもなり得ます。特定の範囲のキーを全て取得するには、以下のコードの構成を用いることができます。

| 範囲 | コード |
| --- | --- |
| ≥ **x** の全キー | `IDBKeyRange.lowerBound` `(x)` |
| > **x** の全キー | `IDBKeyRange.lowerBound` `(x, true)` |
| ≤ **y** の全キー | `IDBKeyRange.upperBound` `(y)` |
| < **y** の全キー | `IDBKeyRange.upperBound` `(y, true)` |
| ≥ **x** && ≤ **y** の全キー | `IDBKeyRange.bound` `(x, y)` |
| > **x** && < **y** の全キー | `IDBKeyRange.bound` `(x, y, true, true)` |
| > **x** && ≤ **y** の全キー | `IDBKeyRange.bound` `(x, y, true, false)` |
| ≥ **x** && < **y** の全キー | `IDBKeyRange.bound` `(x, y, false, true)` |
| 特定のキー = **z** | `IDBKeyRange.only` `(z)` |

キーは、以下の条件を満たすとき、キーの範囲に含まれます。

* キーの範囲の `lower` の値が、以下のいずれかである
    + `undefined`
    + キーの値より小さい
    + `lowerOpen` が `false` であり、キーの値と等しい
* キーの範囲の `upper` の値が、以下のいずれかである
    + `undefined`
    + キーの値より大きい
    + `upperOpen` が `false` であり、キーの値と等しい

**注:** この機能は Web Worker 内で利用可能です

インスタンスプロパティ
-----------

`IDBKeyRange.lower` 読取専用 

キーの範囲の下限です。

`IDBKeyRange.upper` 読取専用 

キーの範囲の上限です。

`IDBKeyRange.lowerOpen` 読取専用 

下限の値がキーの範囲に含まれるとき、`false` を返します。

`IDBKeyRange.upperOpen` 読取専用 

上限の値がキーの範囲に含まれるとき、`false` を返します。

静的メソッド
------

`IDBKeyRange.bound()`

上限と下限を持つ新しいキーの範囲を生成します。

`IDBKeyRange.only()`

単一の値のみからなる新しいキーの範囲を生成します。

`IDBKeyRange.lowerBound()`

下限のみを持つ新しいキーの範囲を生成します。

`IDBKeyRange.upperBound()`

上限のみを持つ新しいキーの範囲を生成します。

インスタンスメソッド
----------

`IDBKeyRange.includes()`

指定されたキーがこのキーの範囲に含まれるかを表す `boolean` を返します。

例
-

以下の例で、キーの範囲の使い方を示します。`"A"` と `"F"` の間の値を表す範囲として `keyRangeValue` を定義します。(`IDBTransaction` を用いて) トランザクションを開き、オブジェクトストアを開き、`IDBObjectStore.openCursor` を用いてカーソルを開きます。このとき、省略可能なキーの範囲の値として `keyRangeValue` を指定します。これにより、このカーソルはこの範囲に含まれるキーを持つレコードのみを取り出します。開区間にするよう指定していないので、この範囲は値 `"A"` および `"F"` を含みます。`IDBKeyRange.bound("A", "F", true, true);` を使った場合は、`"A"` と `"F"` は範囲に含まれず、その間の値のみが含まれます。

**メモ:** キーの範囲に関する実験ができるより完全な例は、IDBKeyRange-example レポジトリを参照してください。(動く例も見る)


```js
function displayData() {
  const keyRangeValue = IDBKeyRange.bound("A", "F");

  const transaction = db.transaction(["fThings"], "readonly");
  const objectStore = transaction.objectStore("fThings");

  objectStore.openCursor(keyRangeValue).onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const listItem = document.createElement("li");
      listItem.textContent = `${cursor.value.fThing}, ${cursor.value.fRating}`;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("全エントリーを表示しました。");
    }
  };
}
```

仕様書
---

| Specification |
| --- |
| Indexed Database API 3.0 # keyrange |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* IndexedDB の使用
* トランザクションの開始: `IDBDatabase`
* トランザクションの使用: `IDBTransaction`
* キーの範囲の設定: `IDBKeyRange`
* データの取得と変更: `IDBObjectStore`
* カーソルの使用: `IDBCursor`
* リファレンス例: To-do Notifications (動く例を見る)