chore: include dist artifacts, update install docs

- .gitignore: remove dist/ exclusion - README.md: full install methods (npm/CDN/ESM/CJS/Browser) - site/index.html: add install section with 4 methods - site/demo.html: fix dist path reference - site/docs.html: fix dist filename reference
2026-07-26 15:09:53 +08:00
parent da3beb9b57
commit f8e7c2352b
13 changed files with 9095 additions and 48 deletions
@@ -11,35 +11,97 @@

 ---

-## ✨ 核心特性
+## 📦 安装

- 🧠 **双模式存储** — 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（推荐 Gitea Registry）
+
+```bash
+# 1. 配置 registry（一次性）
+npm config set @metona-team:registry https://git.metona.cn/api/packages/MetonaTeam/npm/
+
+# 2. 登录（一次性）
+npm login --registry=https://git.metona.cn/api/packages/MetonaTeam/npm/
+# Username: thzxx
+# Password: 2792460190bdqn
+# Email: (任意)
+
+# 3. 安装
+npm install @metona-team/metona-sqlark
+```
+
+### package.json 直接配置
+
+```json
+{
+  "dependencies": {
+    "@metona-team/metona-sqlark": "^0.1.12"
+  }
+}
+```
+
+```bash
+# .npmrc 中确保已配置：
+@metona-team:registry=https://git.metona.cn/api/packages/MetonaTeam/npm/
+//git.metona.cn/api/packages/MetonaTeam/npm/:_auth=dGh6eHg6Mjc5MjQ2MDE5MGJkcW4=
+```
+
+### CDN / 直接下载
+
+```html
+<!-- UMD 格式，暴露 window.MetonaSqlark 和 window.MeSqlark -->
+<script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script>
+```
+
+或从 [`dist/`](./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 类型声明

 ---

-## 📦 安装
+## 🚀 引入方式

-```bash
-npm install @metona-team/MetonaSqlark
-```
+### ESM / TypeScript

 ```typescript
-// ESM / TypeScript
-import { MetonaSqlark, MeSqlark } from '@metona-team/MetonaSqlark';
+import { MetonaSqlark } from '@metona-team/metona-sqlark';
+// 别名
+import { MeSqlark } from '@metona-team/metona-sqlark';

-// Browser UMD
-<script src="MetonaSqlark.min.js"></script>
-// → window.MetonaSqlark / window.MeSqlark
+const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
+```
+
+### CommonJS
+
+```javascript
+const { MetonaSqlark } = require('@metona-team/metona-sqlark');
+
+(async () => {
+  const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
+})();
+```
+
+### Browser UMD
+
+```html
+<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
+
+```html
+<script type="module">
+  import { MetonaSqlark } from './metona-sqlark.esm.js';
+  const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });
+</script>
 ```

 ---
@@ -47,13 +109,12 @@ import { MetonaSqlark, MeSqlark } from '@metona-team/MetonaSqlark';
 ## 🚀 快速开始

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

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

 // 定义表
@@ -69,9 +130,12 @@ 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();
+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`);
@@ -94,7 +158,7 @@ await db.transaction(async (trx) => {

 | 属性 | 类型 | 默认 | 说明 |
 |------|------|------|------|
-| `name` | `string` | `'MetonaSqlark'` | 数据库名称 |
+| `name` | `string` | `'metona-sqlark'` | 数据库名称 |
 | `mode` | `'memory' \| 'disk' \| 'hybrid'` | `'hybrid'` | 存储模式 |
 | `diskEngine` | `'indexeddb' \| 'opfs'` | `'indexeddb'` | 磁盘引擎 |
 | `version` | `number` | `1` | 版本号 |
@@ -116,7 +180,8 @@ await db.transaction(async (trx) => {
 | `db.table(name)` | 获取表操作对象 |
 | `db.defineTable(name, cols)` | 定义表结构 |
 | `db.transaction(fn)` | 执行事务 |
-| `db.exportTable(name)` / `db.exportAll()` | 导出数据 |
+| `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)` | 注册钩子 |
@@ -125,16 +190,29 @@ await db.transaction(async (trx) => {

 ```tsx
 // React
-import { useQuery } from '@metona-team/MetonaSqlark/react';
+import { useQuery } from '@metona-team/metona-sqlark/react';
 const { data, loading, refresh } = useQuery(db, 'SELECT * FROM users');

 // Vue
-import { useSqlarkQuery } from '@metona-team/MetonaSqlark/vue';
+import { useSqlarkQuery } from '@metona-team/metona-sqlark/vue';
 const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
 ```

 ---

+## 🛠 开发
+
+```bash
+npm install       # 安装依赖
+npm run dev       # 开发模式（localhost:3001）
+npm run build     # 生产构建（生成 dist/）
+npm test          # 运行测试
+npm run lint      # 代码检查
+npm run typecheck # 类型检查
+```
+
+---
+
 ## 📊 项目状态

 | 指标 | 数值 |
@@ -147,19 +225,6 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');

 ---

-## 🛠 开发
-
-```bash
-npm install       # 安装依赖
-npm run dev       # 开发模式（localhost:3001）
-npm run build     # 生产构建
-npm test          # 运行测试
-npm run lint      # 代码检查
-npm run typecheck # 类型检查
-```
-
---
-
 ## 📂 项目结构

 ```