Metona CN OpenSource Team
中国-四川-成都
Repositories
7
 Projects Packages Members
2

@metona-team/metona-sqlark (0.1.12)

Published 2026-07-26 15:18:59 +08:00 by thzxx in MetonaTeam/MetonaSqlark

Installation

@metona-team:registry=https://git.metona.cn/api/packages/MetonaTeam/npm/
npm install @metona-team/metona-sqlark@0.1.12
"@metona-team/metona-sqlark": "0.1.12"

About this package

Frontend SQL database with in-memory and disk dual-mode storage

MetonaSqlark

version license coverage tests

基于 TypeScript 的前端关系型数据库，内存与磁盘双模式运行，支持完整 SQL 查询与 Query Builder 链式 API。

📦 安装

npm install @metona-team/metona-sqlark

如果提示找不到包，先配置 scope registry（一次性）：

npm config set @metona-team:registry https://git.metona.cn/api/packages/MetonaTeam/npm/

CDN / 直接下载

<!-- UMD 格式，暴露 window.MetonaSqlark 和 window.MeSqlark -->
<script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script>

或从 dist/ 目录下载：

  • metona-sqlark.js — UMD 开发版（含 sourcemap）
  • metona-sqlark.min.js — UMD 压缩版（~42KB）
  • metona-sqlark.esm.js — ES Module
  • metona-sqlark.cjs.js — CommonJS
  • metona-sqlark.d.ts — TypeScript 类型声明

🚀 引入方式

ESM / TypeScript

import { MetonaSqlark } from '@metona-team/metona-sqlark';
// 别名
import { MeSqlark } from '@metona-team/metona-sqlark';

const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });

CommonJS

const { MetonaSqlark } = require('@metona-team/metona-sqlark');

(async () => {
  const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
})();

Browser UMD

<script src="metona-sqlark.min.js"></script>
<script>
  (async () => {
    const db = await window.MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
    // 或 window.MeSqlark（完全等价）
  })();
</script>

ES Module in Browser

<script type="module">
  import { MetonaSqlark } from './metona-sqlark.esm.js';
  const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
</script>

🚀 快速开始

import { MetonaSqlark } from '@metona-team/metona-sqlark';

const db = await MetonaSqlark.create({
  name: 'my-app',
  mode: 'hybrid',          // 'memory' | 'disk' | 'hybrid'
  diskEngine: 'indexeddb', // 'indexeddb' | 'opfs'
});

// 定义表
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 result = await db.table('users')
  .select(['name', 'age'])
  .where({ age: { $gt: 18 } })
  .orderBy('age', 'desc')
  .limit(10)
  .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() 导出数据 JSON
db.importTable(name, data) 导入数据
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');

🛠 开发

npm install       # 安装依赖
npm run dev       # 开发模式（localhost:3001）
npm run build     # 生产构建（生成 dist/）
npm test          # 运行测试
npm run lint      # 代码检查
npm run typecheck # 类型检查

📊 项目状态

指标 数值
测试用例 264
测试套件 15
语句覆盖率 93.46%
SQL 关键字 29
存储引擎 4（Memory / IndexedDB / OPFS / Hybrid）

📂 项目结构

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

Dependencies

Development Dependencies

ID Version
@babel/core ^7.22.0
@babel/plugin-transform-modules-commonjs ^7.22.0
@babel/preset-env ^7.22.0
@babel/preset-typescript ^7.22.0
@rollup/plugin-commonjs ^25.0.0
@rollup/plugin-node-resolve ^15.0.0
@rollup/plugin-terser ^0.4.0
@rollup/plugin-typescript ^11.1.0
@types/jest ^29.5.0
@typescript-eslint/eslint-plugin ^8.0.0
@typescript-eslint/parser ^8.0.0
babel-jest ^29.5.0
eslint ^8.40.0
fake-indexeddb ^6.2.5
jest ^29.5.0
jest-environment-jsdom ^29.5.0
prettier ^2.8.0
rollup ^3.20.0
rollup-plugin-dts ^5.3.0
rollup-plugin-livereload ^2.0.5
rollup-plugin-serve ^2.0.1
tslib ^2.6.0
typescript ^5.0.0

Keywords

database sql frontend indexeddb opfs memory browser typescript
Details
npm
MetonaTeam/MetonaSqlark
2026-07-26 15:18:59 +08:00
0
thzxx
Project Site
MIT
140 KiB
Assets (1)
metona-sqlark-0.1.12.tgz 140 KiB
Versions (3) View all
0.1.14 2026-07-26
0.1.13 2026-07-26
0.1.12 2026-07-26
Issues