# @baukit/data-contracts-expo-sqlite 中文文档

规范地址：https://npmcn.com/package/%40baukit/data-contracts-expo-sqlite/

版本：0\.18\.3
npm 元数据更新时间：2026-11-07T02:37:30.444Z
中文译文更新时间：2026-11-07T18:33:35.201Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40baukit/data-contracts-expo-sqlite
原文对照：https://npmcn.com/package/%40baukit/data-contracts-expo-sqlite/?lang=original
项目主页：https://github.com/PatrickKoss/baukit#readme
源码仓库：https://github.com/PatrickKoss/baukit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：216 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：expo-sqlite ^57\.0\.3，@baukit/data-contracts ^0\.18\.3
- 首次发布：2026-08-25T18:46:24.288Z
- 最新版本发布：2026-11-07T02:37:30.128Z
- 近 30 天下载量：8248（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

Expo SQLite 执行@baukit/data-contracts 基础存储合同.

## 安装

```sh
npm install @baukit/data-contracts-expo-sqlite
```

也可以使用：`pnpm add @baukit/data-contracts-expo-sqlite`、`yarn add @baukit/data-contracts-expo-sqlite`、`bun add @baukit/data-contracts-expo-sqlite`

## README

# `@baukit/data-contracts-expo-sqlite`

执行零产品-逻辑博览会SQLite `@baukit/data-contracts`' 基本储存合同.

```ts
import { SqliteRecordStore } from '@baukit/data-contracts-expo-sqlite';
import * as SQLite from 'expo-sqlite';

interface CachedRecord {
  readonly id: string;
  readonly value: string;
}

const database = await SQLite.openDatabaseAsync('product.db');
const records = new SqliteRecordStore<CachedRecord>(database, 'cached-records');
await records.initialize();
```

对于关键数据/值数据,计划元数据和原子复合物写作,请使用 复合适配器:

```ts
import { ExpoSqliteStore } from '@baukit/data-contracts-expo-sqlite';

const storage = new ExpoSqliteStore<CachedRecord>(database, 'product');
await storage.initialize();
await storage.withTransaction((transaction) =>
  transaction.withTransaction((sameTransaction) =>
    sameTransaction.records.put({ id: 'one', value: 'cached' }),
  ),
);
```

对交易范围上下文的暗中呼叫加入环境专属 交易. `close()` 关闭逻辑适配器; 通过 `{ closeDatabase: true }` 当它也拥有所提供的数据库手柄时.

命名空间共享一个固定 `baukit_records` 桌子没有相撞。 打电话 `initialize()` 在使用商店之前。 记录是按JSON顺序排列的,标注是受约束的并基于密钥集的,而有缺陷的持久有效载荷会产生无内容的错误.

## 操作命令

Expo SQLite 运行 `withExclusiveTransactionAsync` 连接到 同一个文件。 在交易运行时的基控上声明 打开失败 `database is locked`因此,适配器运行根读取, 根写出, `initialize()`, (中文(简体) ), `withTransaction()`,以及 `close()` 一次一个, 按呼叫顺序,每个数据库文件一个队列(`SQLiteDatabase.databasePath`) (中文(简体) ). 每个 `ExpoSqliteStore`, (中文(简体) ), `SqliteRecordStore`, (中文(简体) ), `SqliteKeyValueStore`,以及 `SqliteSchemaMetadataStore` 在该文件中共享队列, 以控件和 它使用的命名空间。 不同文件中的存储不相等 .

-   交易上下文的工作运行在交易连接上,从未 输入队列.
-   一个被拒绝的操作会释放下一个呼叫者的队列 .
-   `close()` 拒绝新电话 `storage_closed`,等待工作已经 被接受, 关闭自有控件一次, 并返回同样的承诺 包括一个被拒绝的人.
-   SQLite 的锁定错误未更改联系人 。 适配器从不重复.

内部a `withTransaction` 调回,请使用它传递的上下文。 根调用 在交易后面的相同文件队列上, 交易 等待那个电话, 和两个结束。 保持网络和文件工作 召回,因为它为文件的每个商店排队。 原始内容 语句中,一个产品运行在手柄上本身绕过队列。 运行他们 结束 `ExpoSqliteConnection` 换句话说.

套装的快速Vitest套装 运行共享合同 对抗决定主义 数据库伪造和反对 `NodeSqliteDatabase` (见下文)。 这个 [Expo SQLite 设备兼容应用程序](https://npmcn.com/examples/expo-sqlite-conformance/README.md) 反映对实际合同的共享合同案例 `expo-sqlite` 在安卓上, 包括创建/重新打开、命名空间隔离、数据畸形、回滚、, schema-metadata 升级, 根与交易在两个到达时重叠 命令, `ExpoSqliteConnection` 命令、 外国密钥和回滚 `ExpoSqliteStore`,并认证E F E数据库隔离。 产品 生成数据库名称并用 `@baukit/data-contracts` 在打开博览会数据库之前。 iOS是一个预定/手动macOS门.

## 原始 SQL 连接

`ExpoSqliteConnection` 运行产品自己的SQL,例如关系计划 和它的迁移跑者, 与上面的仓库相同.

```ts
import { ExpoSqliteConnection } from '@baukit/data-contracts-expo-sqlite';

const connection = new ExpoSqliteConnection(database);
await connection.exec('CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT)');
await connection.transaction(async (transaction) => {
  await transaction.run('INSERT INTO notes (id, body) VALUES (?, ?)', 'one', 'first');
  return transaction.get<{ readonly body: string }>('SELECT body FROM notes WHERE id = ?', 'one');
});
```

-   `exec(source)` 运行一个没有参数的脚本. `run`, (中文(简体) ), `get`,以及 `all` 绑定参数为 `expo-sqlite` 是: 变量值, 一个数组, 或者一个 其密钥保存对象 `$`, (中文(简体) ), `:`,或 `@` 前缀. `run` 决定: `{ changes, lastInsertRowId }`, (中文(简体) ), `get` 转到第一行或 `undefined`,以及 `all` 给每一行.
-   每根语句, `transaction()`,以及 `close()` 等待它打开 队列显示同一数据库文件共享的每个商店。 根语句 当交易打开时,另一个呼叫者会发出 交易承诺或退缩, 永远不会在里面.
-   `transaction(work)` 运行 `BEGIN IMMEDIATE` 在提供的手柄上,承诺 何时 `work` 决心,当 `work` 或拒绝犯罪。 这个 原始错误到达呼叫器时没有改变,结果为: `work` 实值 已经返回.
-   交易上下文有相同的声明方法. 之后 交易结算,其报表以 `storage_closed`。 。 。 .
-   环境 `transaction(work)` 巢: 它运行 `SAVEPOINT` 同样的 手柄不等待队列,所以它永远不会陷入僵局 包含队列的交易。 它释放出保存点时 `work` 解决并返回结果。 何时 `work` 拒绝,它滚回 保存点,只撤销嵌入式语句和计划变化,以及 以同样的错误拒绝。 除非 呼叫者发现了这个错误。 释放的巢穴活儿仍然会卷回 附加关卡失败 。 尼斯廷没有深度限制.
-   只有内心最开放的关卡接受工作. 虽然一个嵌入式交易 开放、发言和发言 `transaction()` 附加上下文时以 `TypeError`,所以运行兄弟关系 巢交易一个接一个,而不是与 `Promise.all`。 。 。 .
-   连接运行 `PRAGMA foreign_keys = ON` 放在手柄上 第一次声明。 因为交易运行在那个手柄, 外国钥匙和 `ON DELETE` 行动在他们内部执行。 一个必须重建 表格仍然可以运行 `PRAGMA foreign_keys = OFF` 作为前面的根语句 它的交易,然后恢复它.
-   `close()` 拒绝新电话 `storage_closed`等待被认可的工作, 并仅关闭控件 `{ closeDatabase: true }`。 。 。 .
-   SQLite 错误,包括 `database is locked`,通过不变,和 没有重复.

连接不使用 `withExclusiveTransactionAsync`。博览会运行 `BEGIN` 在调用任务前新建连接, SQLite 忽略 `PRAGMA foreign_keys` 在交易中,所以第二个连接会离开 外国钥匙关了 没法打开.

同样的僵局规则与 `withTransaction` 应用: 内 `work`,使用 交易上下文,并通过其嵌入 `transaction()`。对 连接或任何商店,用于交易后相同的文件队列 从来没有完成.

输入的帮助对象 `Pick<SqliteTransaction, 'transaction'>` 接受两者 连接和交易上下文,从而打开寄存器方法 其自己的交易在根部单独进行,或作为呼叫者内部的保存点 交易.

这与 `ExpoSqliteStore.withTransaction`他们的巢中呼唤 按照共享存储合同的要求进行环境交易.

## 节点测试

`@baukit/data-contracts-expo-sqlite/testing` 在节点单位中运行 Expo SQLite 代码 在节点的内置测试(Vites或Jest) `node:sqlite`它需要节点24或 以后不增加依赖性.

```ts
import { ExpoSqliteStore } from '@baukit/data-contracts-expo-sqlite';
import { NodeSqliteDatabase } from '@baukit/data-contracts-expo-sqlite/testing';

const database = new NodeSqliteDatabase();
const storage = new ExpoSqliteStore<CachedRecord>(database, 'product', { closeDatabase: true });
await storage.initialize();
```

`NodeSqliteDatabase` 执行 `ExpoSqliteDatabase`, 博览会的部分 `SQLiteDatabase` 这个适配器呼叫: `databasePath`, (中文(简体) ), `execAsync`, (中文(简体) ), `runAsync`, (中文(简体) ), `getFirstAsync`, (中文(简体) ), `getAllAsync`, (中文(简体) ), `withExclusiveTransactionAsync`,以及 `closeAsync`。对照这些方法输入的产品驱动程序接受该方法而不使用 铸出。 没有参数, 它打开一个新的临时文件并删除它 `closeAsync()`。有了路径,它打开了文件,就放在原地,所以测试一下 可关闭和重开同一数据库. `:memory:` 丢出一个 `TypeError`,因为 独家交易必须打开与同一数据库的第二个连接.

它复制了产品测试倾向于隐藏的设备行为:

-   `withExclusiveTransactionAsync` 运行 `BEGIN`,任务,和 `COMMIT` 一个新的 连接到同一文件,并在任务抛出时返回。 写信 打开交易时的根控点失败 `database is locked`。 。 。 .
-   每条连接都会打开外国的密钥. `PRAGMA foreign_keys = ON` 打开 根控点没有到达交易连接.
-   布尔和整数作为整数结合, `undefined` 绑定为 NULL,并 已命名参数需要其 `$`, (中文(简体) ), `:`,或 `@` 前缀.
-   行为平地物体,和 `getFirstAsync` 返回时 `null` 没有排行.

它与装置在三个地方不同. 未知的命名参数或 额外位置值抛出而不是被忽略。 根读取时 打开交易成功并查看承诺状态。 外的整数 安全射程抛出。 没有 `withTransactionAsync`, (中文(简体) ), `prepareAsync`,或 同步方法.

变革的最佳项目 `@baukit/*` 通过 Babel 解析条目 联合国 `default` 条件.

## 移徙人员合规情况

`createSqliteMigrationConformanceTests(adapter)` 返回框架中和大小写 一个产品自己的SQLite迁移跑者。 每个人通过测试注册 运行 :

```ts
import {
  createSqliteMigrationConformanceTests,
  type SqliteMigrationConformanceAdapter,
} from '@baukit/data-contracts-expo-sqlite/testing';

const adapter: SqliteMigrationConformanceAdapter = {
  migrate: (database, steps) => runMigrations(new ProductSqliteDriver(database), steps),
};

for (const testCase of createSqliteMigrationConformanceTests(adapter)) {
  it(testCase.name, testCase.run);
}
```

`migrate` 收到一个 `NodeSqliteDatabase` 和清单 `{ version, name, sql }` 步骤,一个应用程序建造船只的完整列表。 这个 当运行者失败或拒绝数据库时,必须拒绝。 案件核实 跑者:

-   将每个步骤应用到新的数据库;
-   更新旧的数据库并保持其行;
-   重新启动后不再应用;
-   完全滚回一个失败的步骤, 没有表或栏从早先的 遗留的语句,并应用重启后的固定步骤;
-   拒绝新建的数据库迁移,使其保持不变.

该套房不读跑者的历史表或 `user_version`,所以没有 记录版本的跑步者 某处通过。 一个步骤 `sql` 持有若干 语句,所以执行者必须执行它作为脚本(`execAsync`) (中文(简体) ). 每个案件 使用自己的临时文件。 失败的大小写会丢出一个开始的错误 `SQLite migration conformance failed:` 并点出破碎的期望.

## 边界

软件包执行 `@baukit/data-contracts` 在博览会SQLite上,没有别的。 它不选择一个 数据库名称,打开单通,定义产品实体,或执行缓存政策.

通过数据库的手柄而不是打开手柄,使认证的产品能够 获得每个身份的数据库名称,这是共享的E-F-E隔离案例.

`@baukit/data-contracts-dexie` 在网络上是同一个合同.

## 常见问题

### @baukit/data-contracts-expo-sqlite 是什么？

Expo SQLite 执行@baukit/data-contracts 基础存储合同\.

### 如何安装 @baukit/data-contracts-expo-sqlite？

在项目目录运行 npm install @baukit/data-contracts-expo-sqlite，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：expo-sqlite（^57\.0\.3）、@baukit/data-contracts（^0\.18\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @baukit/data-contracts-expo-sqlite 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @baukit/data-contracts-expo-sqlite 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @baukit/data-contracts-expo-sqlite 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @baukit/data-contracts-expo-sqlite 可以商用吗？

@baukit/data-contracts-expo-sqlite 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @baukit/data-contracts-expo-sqlite 的下载量有多少？

根据 npm 官方下载统计，@baukit/data-contracts-expo-sqlite 在 2026/10/08 – 2026/11/06 这 30 天内被下载 8,248 次，日均约 275 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @baukit/data-contracts-expo-sqlite 还在维护吗？

最新版本 0\.18\.3 发布于 2026/11/07（今天）；至今共发布 67 个版本，其中过去 12 个月发布了 67 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。