# Windychen Utils 项目开发记录

**日期**: 2026-06-06  
**项目**: windychen-untils (v1.0.1)  
**类型**: Storage 模块跨环境兼容改造

---

## 一、本次需求

将 `storage.js` 从**仅浏览器环境**扩展为**浏览器 + Node.js 双环境**可用，并在 Node.js 端使用 SQLite 持久化。

---

## 二、新增存储类

### 1. MemoryStorage（通用兜底）

| 方法                   | 功能         | 后端  |
| ---------------------- | ------------ | ----- |
| `get(key, initValue?)` | 从内存获取值 | `Map` |
| `set(key, value)`      | 写入内存     | `Map` |

- 纯内存，进程退出即丢失
- 所有环境通用，作为最低优先级兜底

### 2. SqliteStorage（Node.js 专用）

| 方法                   | 功能           | 后端             |
| ---------------------- | -------------- | ---------------- |
| `get(key, initValue?)` | 从 SQLite 查询 | `better-sqlite3` |
| `set(key, value)`      | 写入 SQLite    | `better-sqlite3` |

**实现细节：**

```javascript
// 表结构
CREATE TABLE IF NOT EXISTS kv_store (key TEXT PRIMARY KEY, value TEXT)

// set: INSERT OR REPLACE，value 经 JSON.stringify
// get: SELECT value WHERE key = ?，结果经 JSON.parse
```

**优化点：**

- WAL 模式（`PRAGMA journal_mode = WAL`）提升并发读写性能
- 预编译语句（`db.prepare().get/run`）避免重复解析 SQL
- 延迟 require：`_SqliteStorageClass` 工厂函数 + try-catch 包装，使 better-sqlite3 在浏览器/webpack 环境中静默降级为 null

---

## 三、环境自动选择策略（更新后）

```
浏览器：IndexedDB → localStorage → MemoryStorage
Node.js：SqliteStorage → MemoryStorage
```

**改动文件：**

| 文件           | 变更                                                               |
| -------------- | ------------------------------------------------------------------ |
| `storage.js`   | +MemoryStorage 类，+SqliteStorage 类，更新导出逻辑                 |
| `index.js`     | 移除 `try { require('./storage') } catch (e) {}`，改为直接 require |
| `test.js`      | 新增 5 条 Storage 异步测试（对象/字符串/数字/数组/默认值）         |
| `.gitignore`   | 新增 `*.db` `*.db-wal` `*.db-shm`                                  |
| `package.json` | 新增 `better-sqlite3` 依赖                                         |

---

## 四、演进过程

1. **第一版**：`FileStorage`（每 key 一个 JSON 文件，`fs.promises` 读写）
2. **TS 报错**：async 方法在 try-catch 块内部定义类导致解析异常 → 提取为 `_FileStorageClass` 工厂函数
3. **用户反馈**：改用 SQLite 而非 JSON 文件存储
4. **最终方案**：`SqliteStorage`，better-sqlite3 同步 API + WAL 模式

---

## 五、数据文件

```
.windychen-storage/
├── storage.db       # 主数据库
├── storage.db-shm   # WAL 共享内存
└── storage.db-wal   # WAL 日志
```

---

## 六、测试结果

```
共 21 项，21 通过，0 失败

─── Object.getPro ─── (4 项)
─── Object.setPro ─── (2 项)
─── Array.findPro ─── (3 项)
─── Array.filterPro ─── (2 项)
─── Array.findIndexPro ─── (1 项)
─── Array.findLastPro ─── (1 项)
─── Array.somePro / everyPro ─── (3 项)
─── Storage ─── (5 项)
```

---

## 七、关键决策记录

1. **SQLite 选型**: 选择 better-sqlite3（原生编译、同步 API）而非 sql.js（纯 JS），优先性能
2. **降级策略**: Node.js → SqliteStorage → MemoryStorage，与浏览器端 IndexedDB → localStorage → MemoryStorage 保持一致的链式降级模式
3. **JSON 序列化**: 所有值通过 `JSON.stringify/parse` 统一存取，保证类型可靠性
4. **WAL 模式**: 启用 Write-Ahead Logging，避免写阻塞读

---

## 八、待改进方向

- [ ] Storage 模块添加 delete/clear 方法
- [ ] 添加单元测试框架（如 Jest/Vitest）
- [ ] 支持 TypeScript 类型声明 (.d.ts)
- [ ] 考虑添加更多工具方法（日期、字符串、数字等）
- [ ] CI/CD 自动化构建与发布