IndexedDB

IndexedDB 提供结构化数据库，支持对象仓库、索引、游标和事务，适合保存需要查询和一致性保障的数据。

先创建并关联资源；关联与共享规则见模块概览。

import { IndexedDB } from 'lexmount:storage';

IndexedDB 为 IDBFactory，与 globalThis.indexedDB 是同一对象。以下 API 使用事件请求和事务，不能把 IDBRequest 当作 Promise 使用。IDB* 类型和 IDBKeyRange 可直接使用，无需额外导入。

键、查询与批量读取选项

普通对象、数组、循环引用、undefined、BigInt、Date、RegExp、Map、Set、Error、ArrayBuffer / TypedArray、Blob / File 等可克隆值可以保存。函数和不支持的宿主对象会导致 DataCloneError。业务值不局限于 JSON。

IndexedDB.open(name, version?)

功能： 打开已有且已关联的数据库，必要时执行结构升级。

参数： name: string 必填，为资源名称；version?: number 为正整数，省略时打开当前版本。控制台新建的空库版本为 0，首次打开升级到版本 1，可在 upgradeneeded 中创建对象仓库和索引。

返回值： IDBOpenDBRequest，同步返回。success 时 result 是 IDBDatabase；不存在或未关联时通过请求 error 事件返回 NotFoundError，不会创建数据库。

IndexedDB.databases()

功能： 列出当前实例已关联的数据库。

参数： 无。

返回值： Promise<IDBDatabaseInfo[]>，各项包含数据库 name 和数字 version。

IndexedDB.cmp(first, second)

功能： 按 IndexedDB 键顺序比较两个键。

参数： first、second 必填，均为 IDBValidKey。

返回值： 同步返回 -1、0 或 1，分别表示小于、相等或大于；非法键抛出 DataError。

IndexedDB.deleteDatabase(name)

功能： 此运行时禁止通过代码删除数据库，资源需在控制台删除。

参数： name: string 为标准接口的数据库名参数。

返回值： 不会返回请求对象，始终同步抛出 NotAllowedError。

IDBDatabase

通过成功的打开请求获得 db。数据库、对象仓库和索引名称最多 1024 UTF-8 字节，不能包含 NUL 或无效 Unicode。

创建和删除对象仓库应在 upgradeneeded 的升级事务中进行，应用日常读写使用 readonly 或 readwrite 事务。durability 接受标准值，但当前均等待后端提交。

数据库支持 onversionchange、onclose、onerror 和 onabort 事件属性。版本事件含 oldVersion: number、newVersion: number | null。同一运行时内支持版本协调；跨实例升级不会广播浏览器式版本事件，需由应用协调并重新打开旧连接。

IDBTransaction

oncomplete 表示后端提交成功，onabort 表示中止，onerror 可观察请求错误。单个请求 success 不代表已持久化。事务会自动提交，发起请求时必须处于活动状态；不要在事务中等待不相关的网络请求或定时器再继续读写。

IDBRequest 与 IDBOpenDBRequest

普通请求通过 onsuccess / onerror 接收结果。打开请求另有 onupgradeneeded 和 onblocked；升级事件提供 oldVersion 和 newVersion。

请求、事务和数据库支持事件属性以及 EventTarget 的 addEventListener(type, listener, options?)、removeEventListener(type, listener, options?) 和 dispatchEvent(event)；前两者返回 void，最后一个返回 boolean。listener 为回调或事件监听对象，options 可控制 capture、once 等标准监听行为。处理请求错误时，可调用事件的 preventDefault() 阻止默认中止，再由应用决定事务处理。

IDBObjectStore

store.name: string 可在升级事务中修改；其余属性为只读：keyPath: string | string[] | null、autoIncrement: boolean、indexNames: DOMStringList、transaction: IDBTransaction。

写操作需要 readwrite 或升级事务。keyPath 从 value 中取键；autoIncrement 可生成键，具体组合仍受 IndexedDB 键规则约束。复合 keyPath 不能与 multiEntry 同时启用。

IDBIndex

index.name: string 可在升级事务中修改；只读属性包括 objectStore: IDBObjectStore、keyPath: string | string[]、unique: boolean、multiEntry: boolean。

空的批量结果为 []。multiEntry 索引可能为同一记录提供多个条目，索引的 count 统计条目数；唯一索引遇到冲突会使相应写请求失败。

IDBCursor 与 IDBCursorWithValue

advance / continue 不返回下一项；它们让原请求再次触发 success，通过 request.result 取得下一游标，遍历结束时为 null。一次前进完成前不能再次前进。

IDBKeyRange

用静态方法构建键范围。返回对象具有只读 lower、upper（有效键或未设边界时的 undefined）以及布尔属性 lowerOpen、upperOpen。

Open 为 true 表示不包含该边界。无效键、颠倒范围或不可成立的边界组合会抛出 DataError。

DOMStringList（例如 objectStoreNames / indexNames）提供 length: number、数字下标、item(index): string | null 和 contains(name): boolean，并可迭代。item 的 index 为数字，contains 的 name 为字符串。

事务示例与限制

import { IndexedDB } from 'lexmount:storage';

const request = IndexedDB.open('application', 1);
request.onupgradeneeded = () => {
  request.result.createObjectStore('notes', { keyPath: 'id' });
};
const db = await new Promise((resolve, reject) => {
  request.onsuccess = () => resolve(request.result);
  request.onerror = () => reject(request.error);
});
try {
  const tx = db.transaction('notes', 'readwrite');
  const completed = new Promise((resolve, reject) => {
    tx.oncomplete = resolve;
    tx.onabort = () => reject(tx.error);
  });
  tx.objectStore('notes').put({ id: 'first', title: 'Hello' });
  await completed;
} finally {
  db.close();
}

单条序列化记录、键、结构元数据及查询结果页上限为 64 MiB，不代表整个数据库的大小上限。数据库连接获取、锁等待、SQL 和事务空闲超时为 30 秒。长事务会阻塞写入；大文件适合放对象存储。

同一资源共享已提交数据，事务中止会回滚。跨实例升级需统一协调，旧连接可能失效并需要重开；连接在提交后断开时可能无法确认结果，重试写入应使用稳定主键。此数据库与网页自身的 window.indexedDB 独立。

请求与事务的错误处理见 IDBRequest，声明见 storage.d.ts。