feat: site全面更新 + CONTRIBUTING/CHANGELOG完善，准备v0.1.13迭代

2026-07-26 16:13:34 +08:00
parent 7858cf3720
commit 7a53cfd530
5 changed files with 811 additions and 265 deletions
@@ -1,4 +1,4 @@
-# Contributing to MetonaEditor
+# Contributing to MetonaSqlark

 Thanks for your interest in contributing! This document outlines the development workflow and conventions.

@@ -10,8 +10,8 @@ Thanks for your interest in contributing! This document outlines the development
 ## Setup

 ```bash
-git clone https://git.metona.cn/MetonaTeam/MetonaEditor.git
-cd MetonaEditor
+git clone https://git.metona.cn/MetonaTeam/MetonaSqlark.git
+cd MetonaSqlark
 npm install
 ```

@@ -39,34 +39,33 @@ npm run format

 ```
 src/
-├── index.ts       # Entry point, global API
-├── core.ts        # MarkdownEditor class
-├── parser.ts      # Markdown parser (tokenizer + renderer)
-├── plugins.ts     # Plugin system & 6 presets
-├── themes.ts      # Theme system
-├── i18n.ts        # Internationalization
-├── styles.ts      # CSS-in-JS injection
-├── constants.ts   # Types, defaults, configs
-├── utils.ts       # Utility functions
-├── animations.ts  # Animation metadata
-├── icons.ts       # Toolbar SVG icons
-└── locales.ts     # Translation data
+├── index.ts              # Entry point, global API (MetonaSqlark + MeSqlark)
+├── core.ts               # MetonaSqlark main class
+├── constants.ts          # Types, defaults, enums, errors
+├── utils.ts              # Utility functions
+├── engine/               # Storage engines
+│   ├── interface.ts      # IStorageEngine interface
+│   ├── memory.ts         # MemoryEngine (Map-based)
+│   ├── indexeddb.ts      # IndexedDBEngine (browser persistence)
+│   └── opfs.ts           # OPFSEngine (Origin Private File System)
+├── hybrid/               # HybridEngine (write-through)
+├── table/                # Table management & Schema validation
+├── query/                # Query system
+│   ├── ast.ts            # SQL AST type definitions
+│   ├── builder.ts        # Chainable QueryBuilder API
+│   ├── compiler.ts       # AST → QueryPlan compiler
+│   ├── executor.ts       # QueryExecutor with JOIN/GROUP BY support
+│   └── where-matcher.ts  # Unified WHERE matching logic
+├── sql/                  # SQL parser
+│   ├── tokens.ts         # Token types & keywords
+│   ├── lexer.ts          # Tokenizer
+│   └── parser.ts         # Recursive descent parser
+├── transaction/          # Transaction manager
+├── plugin/               # Plugin system (14 lifecycle hooks)
+└── integrations/         # React & Vue hooks

-tests/
-├── parser.test.ts
-├── core.test.ts
-├── plugins.test.ts
-├── themes.test.ts
-├── i18n.test.ts
-├── utils.test.ts
-├── animations.test.ts
-├── index.test.ts
-└── styles.test.ts
-
-site/
-├── index.html     # Landing page
-├── demo.html      # Full-featured demo
-└── docs.html      # API documentation
+tests/                    # Test suite (264+ test cases, 15 test suites)
+site/                     # Documentation site (index / docs / demo)
 ```

 ## Code Conventions
@@ -89,12 +88,43 @@ site/

 ### Commits
 - Use conventional commit messages:
-  - `feat: add reference link resolution`
-  - `fix: autoSave plugin state conflict`
+  - `feat: add SQL GROUP BY support`
+  - `fix: JOIN with multiple ON conditions`
  - `docs: update API reference`
-  - `test: add index.ts global API tests`
+  - `test: add edge case coverage`
  - `chore: optimize rollup dev build`

+## Architecture
+
+MetonaSqlark follows a layered architecture:
+
+```
+┌──────────────────────────────────────────────────┐
+│         MetonaSqlark / MeSqlark (Public API)      │
+├──────────────────────────────────────────────────┤
+│  SQL Parser  │ QueryBuilder │ Transaction │ Plugin │
+│  (Lexer→AST) │ (.select…)   │  Manager    │ System │
+├──────────────────────────────────────────────────┤
+│         QueryExecutor (AST → Results)             │
+│    JOIN · GROUP BY · HAVING · DISTINCT · Agg     │
+├──────────────────────────────────────────────────┤
+│         IStorageEngine (Interface)                │
+├─────────┬──────────┬──────────┬──────────────────┤
+│ Memory  │ IndexedDB │ OPFS     │ Hybrid           │
+│ Engine  │ Engine    │ Engine   │ Engine           │
+└─────────┴──────────┴──────────┴──────────────────┘
+```
+
+### Key Design Decisions
+
+1. **AST as Universal Intermediate Representation**: Both SQL strings and Query Builder produce the same AST, ensuring consistent behavior regardless of API used.
+
+2. **Write-Through Hybrid Strategy**: When using `mode: 'hybrid'`, all writes go to both memory and disk simultaneously. Reads always hit memory for maximum speed.
+
+3. **Plugin Hook Pipeline**: 14 lifecycle hooks allow intercepting database operations without modifying core code.
+
+4. **Hand-Written SQL Parser**: No dependencies on parser generators — a recursive-descent parser keeps the bundle size minimal.
+
 ## Building

 ```bash
@@ -102,11 +132,11 @@ site/
 npm run build

 # Output in dist/
-# ├── metona-editor.js        UMD
-# ├── metona-editor.min.js    UMD minified
-# ├── metona-editor.esm.js    ES Module
-# ├── metona-editor.cjs.js    CommonJS
-# └── metona-editor.d.ts      TypeScript declarations
+# ├── metona-sqlark.js        UMD
+# ├── metona-sqlark.min.js    UMD minified (~42KB / ~10KB gzip)
+# ├── metona-sqlark.esm.js    ES Module
+# ├── metona-sqlark.cjs.js    CommonJS
+# └── metona-sqlark.d.ts      TypeScript declarations
 ```

 ## Plugin Development
@@ -114,29 +144,58 @@ npm run build
 Plugins follow a simple convention:

 ```typescript
-const myPlugin = {
+import type { MetonaPlugin } from '@metona-team/metona-sqlark';
+
+const myPlugin: MetonaPlugin = {
  name: 'myPlugin',
  version: '1.0.0',
  description: 'Description of my plugin',
-  depends: [],        // optional: plugin names this depends on
-  priority: 50,       // optional: for topological sort ordering
+  priority: 50,  // higher = executed first

-  install(editor, options?) {
-    // Called when plugin is installed
-    // Use editor.on() to subscribe to events
-    // Return a Promise for async initialization
+  install(db) {
+    // Use db.on() to subscribe to hooks
+    db.on('beforeInsert', async (rows) => {
+      // Validate or transform data
+    });
+    db.on('afterQuery', async (sql, result) => {
+      // Log or cache query results
+    });
  },

-  destroy(editor) {
-    // Called when plugin is uninstalled
-    // Clean up event listeners, timers, DOM nodes
+  destroy() {
+    // Clean up event listeners, timers, etc.
  },
 };
+
+// Register in config
+const db = await MetonaSqlark.create({
+  name: 'my-app',
+  plugins: [myPlugin],
+});
 ```

+### Available Lifecycle Hooks
+
+| Hook | Trigger | Parameters |
+|------|---------|------------|
+| `beforeCreateTable` | Before table creation | schema |
+| `afterCreateTable` | After table creation | schema |
+| `beforeDropTable` | Before table drop | tableName |
+| `afterDropTable` | After table drop | tableName |
+| `beforeInsert` | Before row insert | rows[] |
+| `afterInsert` | After row insert | rows[] |
+| `beforeUpdate` | Before row update | query, updates |
+| `afterUpdate` | After row update | query, updates, count |
+| `beforeDelete` | Before row delete | query |
+| `afterDelete` | After row delete | query, count |
+| `beforeQuery` | Before SQL query | sql |
+| `afterQuery` | After SQL query | sql, result |
+| `beforeTransaction` | Before transaction | - |
+| `afterTransaction` | After transaction | - |
+
 ## Releasing

-1. Update version in `package.json` and `src/index.ts` (`VERSION` constant).
+1. Update version in `package.json` and `src/constants.ts` (`VERSION` constant).
 2. Update `CHANGELOG.md`.
 3. Run full test suite: `npm test`.
 4. Build: `npm run build`.
@@ -144,4 +203,4 @@ const myPlugin = {

 ## Questions?

-Open an issue at [git.metona.cn/MetonaTeam/MetonaEditor/issues](https://git.metona.cn/MetonaTeam/MetonaEditor/issues).
+Open an issue at [git.metona.cn/MetonaTeam/MetonaSqlark/issues](https://git.metona.cn/MetonaTeam/MetonaSqlark/issues).