docs: 全站点版本迭代至 v0.5.1 + 功能描述与实现对齐(移除已删 utils/Slotted 宣称、补加密/页面化/锁/维护语句、修正 walSyncMode 默认值、数字校准 1009 测试/87.3%)
CI / test (18.x) (push) Successful in 10m11s
CI / test (20.x) (push) Successful in 10m8s
CI / test (22.x) (push) Successful in 10m6s
CI / test (24.x) (push) Successful in 10m4s
CI / e2e (push) Successful in 9m50s

This commit is contained in:
thzxx
2026-08-10 12:44:26 +08:00
parent 334067d89e
commit 2668bd47cf
6 changed files with 688 additions and 636 deletions
+11 -11
View File
@@ -1,10 +1,10 @@
# MetonaSqlark
<p align="center">
<img src="https://img.shields.io/badge/version-0.5.0-blue?style=flat-square" alt="version">
<img src="https://img.shields.io/badge/version-0.5.1-blue?style=flat-square" alt="version">
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
<img src="https://img.shields.io/badge/coverage-86.7%25-brightgreen?style=flat-square" alt="coverage">
<img src="https://img.shields.io/badge/tests-1022%20passed-success?style=flat-square" alt="tests">
<img src="https://img.shields.io/badge/coverage-87.3%25-brightgreen?style=flat-square" alt="coverage">
<img src="https://img.shields.io/badge/tests-1009%20passed-success?style=flat-square" alt="tests">
</p>
> 基于 TypeScript 的**前端关系型数据库**,支持完整 SQL 查询、Query Builder 链式 API、与 **AriaEngine 自研存储引擎**。
@@ -17,6 +17,7 @@
- 💾 **OPFS 自研存储后端** — 纯浏览器文件系统,零 IndexedDB 依赖,二进制页面文件,schema 持久化,单文件 COW 原子写,崩溃残留自动清理
- 🔒 **生产级数据安全** — WAL 原子写入 + 标准 CRC32 完整性校验(SSTable 整文件校验 + WAL 记录校验)、**全库 AES-256-GCM 透明加密**PBKDF2 密钥派生 + salt 持久化 + 密码验证,v0.5.0 真实接线)、`RESTRICT` 外键约束、崩溃恢复自愈
- 🔐 **多标签页独占锁** — Web Locks API,第二个标签页打开同一库抛 `ARIA_LOCKED`v0.5.0
- 🛠 **维护语句 SQL 入口**`EXPLAIN`/`ANALYZE`/`REINDEX`/`VACUUM`/`SAVEPOINT` 原生 SQL 支持(v0.5.1 补齐)
- 🛡 **输入校验全覆盖**`maxLength`/`min`/`max` 约束、类型检查、必填验证
- 💾 **多引擎架构** — Memory / IndexedDB / OPFS / Hybrid(write-through) / Aria 五种模式
- 📝 **完整 SQL 支持** — SELECT/JOIN/子查询/GROUP BY/HAVING/ORDER BY/LIMIT/BETWEEN/IF NOT EXISTS/ALTER TABLE/TRUNCATE TABLE/UNION/INSERT...SELECT/事务语句/CREATE INDEX/EXISTSv0.3.0+ CASE WHEN/哈希连接/组提交(v0.3.1+ 多标签页同步(v0.3.2
@@ -31,7 +32,7 @@
- 🌲 **RB-Tree 完整实现** — 标准红黑树插入+删除修复,O(log n) 保证
-**性能优化** — SSTableReader 二分查找统一、IndexedDB 索引利用、crypto 实例化避免全局状态
- 🌐 **浏览器兼容** — Chrome 80+ / Firefox 80+ / Safari 14+ / Edge 80+ / Node.js 16+
- 🧪 **1022 测试 · 86.7% 覆盖率** — 62 套件 + 7 个 Playwright 真实 Chromium e2e,生产级质量保证
- 🧪 **1009 测试 · 87.3% 覆盖率** — 62 套件 + 7 个 Playwright 真实 Chromium e2e,生产级质量保证
---
@@ -308,7 +309,7 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
| **查询性能** | ⚡ O(1) PK | 🟡 O(1) PK | 🟡 O(1) PK | ⚡ O(1) PK | ⚡ O(log n) |
| **数据上限** | 内存限制 | ~2GB(IDB限制) | ~磁盘可用(页面化后大表可行) | ~2GB(IDB) | 内存限制 |
| **浏览器** | 全部 | 全部 | Chrome/Edge 102+ / Firefox 111+ / Safari 15.2+ | 全部 | 全部 |
| **多标签页** | — | ✅ | ❌(Web Locks 独占锁v0.5.0 | ❌ | ✅ 锁保护 |
| **多标签页** | — | ✅ versionchange | ❌ 无保护 | ❌ 无保护 | ✅ Web Locks 独占锁v0.5.0 |
| **全库加密** | — | — | — | — | ✅ AES-GCMv0.5.0 |
| **适用场景** | 缓存/测试 | 标准持久化 | Chromium+ 持久化 | 速度+持久化 | 大规模/分析 |
| **测试覆盖** | 30+ | 30+ | 15+e2e | 15+ | 400+ |
@@ -333,7 +334,7 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
### Hybrid 模式
- **环境**: 所有浏览器
- **限制**: 磁盘引擎决定底层限制(IndexedDB ~2GB / OPFS Chrome only
- **限制**: 磁盘引擎决定底层限制(IndexedDB ~2GB / OPFS 需 OPFS 支持浏览器
- **能力**: write-through 双写(内存+磁盘)、提交顺序保证(磁盘优先)、读从内存
- **适用**: 需要内存速度 + 磁盘持久化的混合场景
@@ -374,7 +375,7 @@ const rows = await db.query('SELECT * FROM users');
```
┌──────────────────────────────────────────┐
│ AriaEngine v0.5.0
│ AriaEngine v0.5.1
│ (implements IStorageEngine) │
├──────────────────────────────────────────┤
│ LSM-Tree │ Buffer Pool │ WAL │
@@ -428,10 +429,10 @@ npm run typecheck # 类型检查
| 指标 | 数值 |
|------|------|
| 测试用例 | 1022 |
| 测试用例 | 1009 |
| 测试套件 | 62+7 Playwright e2e |
| 行覆盖率 | 86.7% |
| SQL 关键字 | 36 |
| 行覆盖率 | 87.3% |
| SQL 关键字 | 72 |
| 存储引擎 | 5Memory / IndexedDB / OPFS / Hybrid / **Aria** |
### 🌐 浏览器兼容性
@@ -462,7 +463,6 @@ src/
├── core.ts # 主类
├── constants.ts # 类型定义 + 配置 + DatabaseError
├── connection-manager.ts # 连接池管理
├── utils.ts # 工具函数
├── engine/ # 存储引擎(Memory/IndexedDB/OPFS/Aria
├── hybrid/ # 混合引擎(write-through
├── table/ # 表管理 + Schema 校验