MetonaSqlark/README.md

metona-sqlark

基于 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

---

📦 安装

npm install @metona-team/metona-sqlark

// ESM / TypeScript
import { MetonaSqlark, MeSqlark } from '@metona-team/metona-sqlark';

// Browser UMD
<script src="metona-sqlark.min.js"></script>
// → window.MetonaSqlark / window.MeSqlark

---

🚀 快速开始

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 集成

// 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）

---

🛠 开发

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