【完全版】IndexedDB API一覧と本質（初心者〜実務まで）

■ 結論（最初にここだけ読めばOK）

IndexedDBは 👉 「イベント駆動の非同期データベースAPI」＋「structured cloneで何でも保存できる仕組み」です。

そして重要なのは：

  • 戻り値ではなく request.result で結果を受け取る
  • すべてが 非同期＋イベントベース
  • データは オブジェクト・配列・Map・Blobなどそのまま保存可能

■ IndexedDBとは何か（ざっくり理解）

IndexedDBは単なる関数ではなく、

👉 複数のインターフェイス（クラス）の集合体

で構成されています。

さらに特徴的なのは：

  • トランザクションベース
  • NoSQL（オブジェクトストア）
  • 非同期（Promiseではなくイベント）

1. IDBFactory（エントリーポイント）

ブラウザの window.indexedDB がこれです。

indexedDB.open(name, version)
indexedDB.deleteDatabase(name)
indexedDB.cmp(key1, key2)

補足

  • cmp() はキー比較用（ほぼ使わない） IndexedDBと同じ並びをJS側で再現したいときに、キーの比較結果（-1 / 0 / 1）を返す関数です。
indexedDB.cmp("a", "b") // -1
indexedDB.cmp("a", "a") // 0
indexedDB.cmp("b", "a") // 1

2. IDBOpenDBRequest（DBオープン専用）

indexedDB.open() の戻り値。

👉 IDBRequestのサブクラス

イベント

  • onsuccess
  • onerror
  • onupgradeneeded（最重要） オブジェクトストアの作成や、インデックスの作成は、このイベントの中で実施する。
  • onblocked（マルチタブ問題）

3. IDBDatabase（DB接続）

DB接続オブジェクト。IDBOpenDBRequestオブジェクトのonsuccessイベント発生後、event.target.result（または request.result）として取得される。

const db = request.result;

メソッド

  • createObjectStore(name, options)
  • deleteObjectStore(name)
  • transaction(storeNames, mode)
  • close()

プロパティ

  • name
  • version
  • objectStoreNames

イベント

  • onversionchange（重要）
  • onclose（ブラウザ依存）

4. IDBTransaction（トランザクション）

トランザクション開始により発生するオブジェクト。IDBDatabase.transaction(storeNames, mode)の戻り値として返される。

db.transaction(storeNames, mode)

mode

  • readonly
  • readwrite
  • versionchange（特殊）

メソッド

  • objectStore(name)
  • abort()

イベント

  • oncomplete
  • onerror
  • onabort

補足（重要）

  • 成功 → 自動コミット
  • エラー → 自動ロールバック

5. IDBObjectStore（テーブル的存在）

トランザクション内で操作するオブジェクトストアオブジェクト。IDBTransaction.objectStore(name)の戻り値として返される。

tx.objectStore(name)

メソッド

  • add(value, key)
  • put(value, key)
  • get(key)
  • getAll(query, count)
  • getKey(key)
  • getAllKeys(query, count)
  • delete(key)
  • clear()
  • count(query)
  • openCursor(query, direction)
  • openKeyCursor(query, direction)
  • index(name)
  • createIndex(name, keyPath, options) options:
    • unique
    • multiEntry
  • deleteIndex(name)

補足

  • add → 重複キーでエラー
  • put → 上書き保存
  • getAll() は大量取得に注意（count指定推奨） getAll(count) は「件数制限付きデータ取得」。最大取得件数の上限を指定し、予期せぬ大量データ取得を防ぐ。

6. IDBIndex（インデックス）

インデックス使用時に操作するオブジェクト。IDBObjectStore.index(name)の戻り値として返される。

store.index(name)

メソッド

  • get(key)
  • getAll(query, count)
  • getKey(key)
  • getAllKeys(query, count)
  • count(query)
  • openCursor(query, direction)
  • openKeyCursor(query, direction)

7. IDBRequest（非同期の基本）

すべての操作のベース。IDBOpenDBRequestオブジェクトの基底オブジェクト。

イベント

  • onsuccess
  • onerror

超重要ポイント

👉 結果は return ではなく request.result

8. IDBCursor（ループ処理）

オブジェクトストアやインデックスのデータを1件ずつ処理する際に操作するオブジェクト。IDBObjectStore.openKeyCursor() や IDBIndex.openKeyCursor() の結果として、イベント内で取得される（request.result）。

store.openKeyCursor()

メソッド

  • advance(n)
  • continue(key)
  • continuePrimaryKey(key, primaryKey)
  • delete()
  • update(value)

プロパティ

  • key
  • primaryKey
  • value（※IDBCursorWithValueの場合）

補足

👉 continue() を呼ばないと次に進まない

9. IDBCursorWithValue

  1. IDBCursorWithValue

オブジェクトストアやインデックスのデータを1件ずつ処理する際に操作するオブジェクト。IDBObjectStore.openCursor() や IDBIndex.openCursor() の結果として取得される。

store.openCursor()
  • cursor.value が使えるカーソル
  • IDBCursorの拡張

10. IDBKeyRange（検索条件）

データの検索条件を指定するオブジェクト。get(), openCursor(), getAll()などに検索条件(query)として渡して使います。

IDBKeyRange.only(value)
IDBKeyRange.lowerBound(value, open)
IDBKeyRange.upperBound(value, open)
IDBKeyRange.bound(lower, upper, lowerOpen, upperOpen)

11. IDBVersionChangeEvent

onupgradeneededイベント時に渡されるイベントオブジェクト。

  • onupgradeneeded で発火
  • event.oldVersion / event.newVersion などが取得可能

(つづく)