thzxx
e2a590c5b1
- 4种存储引擎：Memory / IndexedDB / OPFS / Hybrid - 完整SQL支持：SELECT/INSERT/UPDATE/DELETE/JOIN/GROUP BY/HAVING/DISTINCT - Query Builder链式API + TypeScript泛型支持 - 聚合函数：COUNT/SUM/AVG/MIN/MAX - 事务、插件系统(14 hooks)、发布订阅、数据迁移、导入导出 - React/Vue框架集成 - 264个测试用例，93.46%覆盖率 - 零运行时依赖
185 lines
5.4 KiB
Markdown
185 lines
5.4 KiB
Markdown
# metona-sqlark
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/version-0.1.12-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-93.46%25-brightgreen?style=flat-square" alt="coverage">
|
||
<img src="https://img.shields.io/badge/tests-264%20passed-success?style=flat-square" alt="tests">
|
||
</p>
|
||
|
||
> 基于 TypeScript 的**前端关系型数据库**，内存与磁盘双模式运行，支持完整 SQL 查询与 Query Builder 链式 API。
|
||
|
||
---
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 🧠 **双模式存储** — Memory / Disk / Hybrid，内存极速 + 磁盘持久化
|
||
- ⚡ **完整 SQL** — SELECT / INSERT / UPDATE / DELETE / JOIN / GROUP BY / HAVING / DISTINCT
|
||
- 🔗 **Query Builder** — 链式 API，TypeScript 类型友好
|
||
- 📊 **聚合函数** — COUNT / SUM / AVG / MIN / MAX
|
||
- 🔒 **事务支持** — 原子性操作，失败自动回滚
|
||
- 🧩 **插件系统** — 14 种生命周期钩子
|
||
- 📡 **发布订阅** — 表级变更监听
|
||
- 🔄 **数据迁移** — 版本化 migration 系统
|
||
- 📤 **导入导出** — JSON 格式全库/单表导入导出
|
||
- ⚛️ **React / Vue** — 原生 hooks & composables
|
||
- 📦 **零运行时依赖** — 纯 TypeScript，约 42KB min+gzip
|
||
|
||
---
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
npm install @metona-team/metona-sqlark
|
||
```
|
||
|
||
```typescript
|
||
// ESM / TypeScript
|
||
import { MetonaSqlark, MeSqlark } from '@metona-team/metona-sqlark';
|
||
|
||
// Browser UMD
|
||
<script src="metona-sqlark.min.js"></script>
|
||
// → window.MetonaSqlark / window.MeSqlark
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
```typescript
|
||
import { MetonaSqlark } from '@metona-team/metona-sqlark';
|
||
|
||
// 创建数据库
|
||
const db = await MetonaSqlark.create({
|
||
name: 'my-app',
|
||
mode: 'hybrid',
|
||
diskEngine: 'indexeddb',
|
||
});
|
||
|
||
// 定义表
|
||
await db.defineTable('users', {
|
||
id: { type: 'string', primaryKey: true },
|
||
name: { type: 'string', required: true },
|
||
age: { type: 'number', default: 0 },
|
||
email: { type: 'string', unique: true, index: true },
|
||
});
|
||
|
||
// SQL 查询
|
||
await db.query("INSERT INTO users VALUES ('1', 'Alice', 30, 'alice@demo.com')");
|
||
const rows = await db.query('SELECT * FROM users WHERE age > 18 ORDER BY name');
|
||
|
||
// Query Builder
|
||
const users = db.table('users');
|
||
await users.insert({ id: '2', name: 'Bob', age: 25, email: 'bob@demo.com' });
|
||
const result = await users.select().where({ age: { $gt: 18 } }).orderBy('age', 'desc').execute();
|
||
|
||
// JOIN
|
||
await db.query(`SELECT u.name, o.product FROM users u INNER JOIN orders o ON u.id = o.user_id`);
|
||
|
||
// GROUP BY
|
||
await db.query(`SELECT dept, COUNT(*) FROM employees GROUP BY dept HAVING COUNT(*) > 1`);
|
||
|
||
// 事务
|
||
await db.transaction(async (trx) => {
|
||
await trx.table('users').insert({ id: '3', name: 'Charlie' });
|
||
await trx.table('orders').insert({ id: 'o1', userId: '3', amount: 99 });
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 API 速览
|
||
|
||
### 数据库配置
|
||
|
||
| 属性 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | `string` | `'metona-sqlark'` | 数据库名称 |
|
||
| `mode` | `'memory' \| 'disk' \| 'hybrid'` | `'hybrid'` | 存储模式 |
|
||
| `diskEngine` | `'indexeddb' \| 'opfs'` | `'indexeddb'` | 磁盘引擎 |
|
||
| `version` | `number` | `1` | 版本号 |
|
||
|
||
### WHERE 操作符
|
||
|
||
| 操作符 | 含义 | 操作符 | 含义 |
|
||
|--------|------|--------|------|
|
||
| `$eq` / 直接值 | 等于 | `$gt` / `$gte` | 大于 / 大于等于 |
|
||
| `$ne` | 不等于 | `$lt` / `$lte` | 小于 / 小于等于 |
|
||
| `$in` / `$nin` | 在列表中 | `$like` | 模糊匹配 |
|
||
| `$and` / `$or` / `$not` | 逻辑组合 | | |
|
||
|
||
### 核心方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `db.query(sql)` | 执行 SQL 字符串 |
|
||
| `db.table(name)` | 获取表操作对象 |
|
||
| `db.defineTable(name, cols)` | 定义表结构 |
|
||
| `db.transaction(fn)` | 执行事务 |
|
||
| `db.exportTable(name)` / `db.exportAll()` | 导出数据 |
|
||
| `db.addMigration(v, fn)` / `db.migrateTo(v)` | 数据迁移 |
|
||
| `db.subscribe(table, fn)` | 订阅表变更 |
|
||
| `db.on(hook, fn)` | 注册钩子 |
|
||
|
||
### React / Vue 集成
|
||
|
||
```tsx
|
||
// React
|
||
import { useQuery } from '@metona-team/metona-sqlark/react';
|
||
const { data, loading, refresh } = useQuery(db, 'SELECT * FROM users');
|
||
|
||
// Vue
|
||
import { useSqlarkQuery } from '@metona-team/metona-sqlark/vue';
|
||
const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 项目状态
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 测试用例 | 264 |
|
||
| 测试套件 | 15 |
|
||
| 语句覆盖率 | 93.46% |
|
||
| SQL 关键字 | 29 |
|
||
| 存储引擎 | 4（Memory / IndexedDB / OPFS / Hybrid） |
|
||
|
||
---
|
||
|
||
## 🛠 开发
|
||
|
||
```bash
|
||
npm install # 安装依赖
|
||
npm run dev # 开发模式（localhost:3001）
|
||
npm run build # 生产构建
|
||
npm test # 运行测试
|
||
npm run lint # 代码检查
|
||
npm run typecheck # 类型检查
|
||
```
|
||
|
||
---
|
||
|
||
## 📂 项目结构
|
||
|
||
```
|
||
src/
|
||
├── index.ts # 入口（MetonaSqlark + MeSqlark）
|
||
├── core.ts # 主类
|
||
├── constants.ts # 类型定义 + 配置
|
||
├── engine/ # 存储引擎（Memory/IndexedDB/OPFS）
|
||
├── hybrid/ # 混合引擎
|
||
├── table/ # 表管理 + Schema 校验
|
||
├── query/ # AST + Builder + Compiler + Executor
|
||
├── sql/ # Lexer + Parser
|
||
├── transaction/ # 事务管理
|
||
├── plugin/ # 插件系统
|
||
└── integrations/ # React / Vue hooks
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT © [MetonaTeam](https://git.metona.cn/MetonaTeam)
|