MetonaSqlark/CONTRIBUTING.md

# Contributing to MetonaSqlark

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

## Prerequisites

- Node.js >= 16.0.0
- npm >= 8.0.0

## Setup

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

## Development

```bash
# Start dev server with hot reload (port 3001)
npm run dev

# Run tests in watch mode
npm run test:watch

# Type check
npm run typecheck

# Lint
npm run lint
npm run lint:fix

# Format
npm run format
```

## Project Structure

```
src/
├── index.ts              # Entry point, global API (MetonaSqlark + MeSqlark)
├── core.ts               # MetonaSqlark main class
├── constants.ts          # Types, defaults, enums, errors
├── connection-manager.ts # Connection pool (connect/disconnect)
├── engine/               # Storage engines
│   ├── interface.ts      # IStorageEngine interface
│   ├── memory.ts         # MemoryEngine (Map-based)
│   ├── kvstore_engine.ts # KVStoreEngine (disk mode, self-built KV store)
│   ├── kvstore/          # KVStore (log + snapshot + atomic multi-key write)
│   └── aria/             # AriaEngine (LSM-Tree page storage engine)
│       ├── index/        # LSM / MemTable / SSTable / Bloom / MergeIterator
│       ├── page/         # 4KB slotted page format
│       ├── buffer/       # Buffer Pool (LRU eviction)
│       ├── wal/          # Write-Ahead Log + Checkpoint
│       ├── transaction/  # MVCC manager
│       ├── store/        # Backends (OPFS / KVStore / Memory / Encrypted)
│       ├── locks.ts      # Web Locks multi-tab exclusive lock
│       └── compression/  # LZ4
├── hybrid/               # HybridEngine (write-through)
├── migration/            # Legacy IndexedDB migration tool (one-shot)
├── 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
│   └── params.ts         # Parameter binding (? placeholders)
├── transaction/          # Transaction manager
├── plugin/               # Plugin system (14 lifecycle hooks)
└── integrations/         # React & Vue hooks

tests/                    # Test suite (1304 test cases, 76 suites + 12 e2e)
tests/helpers/             # 共享测试工具（OPFS mock 等）
tests/e2e/                # Playwright e2e（真实 Chromium + OPFS）
site/                     # Documentation site (index / docs / demo)
```

## Code Conventions

### TypeScript
- **Strict mode** is enabled — all code must pass `tsc --noEmit`.
- Export types explicitly. Avoid `any` where possible.
- Use `interface` for object shapes, `type` for unions/primitives.

### Style
- Run `npm run format` before committing (uses Prettier).
- Follow existing comment patterns: JSDoc `/** */` for public APIs, `//` for inline notes.
- Keep functions focused and under ~60 lines where practical.

### Testing
- **Every new feature must include tests.**
- Test files mirror source structure: `src/foo.ts` → `tests/foo.test.ts`.
- Use descriptive test names: `('does X when Y')`.
- Run the full suite before submitting: `npm test`.

### Commits
- Use conventional commit messages:
  - `feat: add SQL GROUP BY support`
  - `fix: JOIN with multiple ON conditions`
  - `docs: update API reference`
  - `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 let plugins observe and adjust database
   operations without modifying core code. **Hook contract (v0.8.0)**:
   - return values are **ignored** (you cannot cancel an operation by returning `false`,
     nor rewrite the SQL by returning a string);
   - **mutate the argument object in place** to change it — this works on the Table API
     path (`db.table(...).insert(rows)`);
   - **throw** to abort the operation (the error propagates to the caller);
   - the SQL path passes a **copy** for `beforeInsert`, so mutating it there has no effect.
     Use the Table API when you need to transform rows.
   These rules are covered by tests; changing them requires updating this section.

4. **Hand-Written SQL Parser**: No dependencies on parser generators — a recursive-descent parser keeps the bundle size minimal.

## Building

```bash
# Production build (all formats)
npm run build

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

## Plugin Development

Plugins follow a simple convention:

```typescript
import type { MetonaPlugin } from '@metona-team/metona-sqlark';

const myPlugin: MetonaPlugin = {
  name: 'myPlugin',
  version: '1.0.0',
  description: 'Description of my plugin',
  // higher = executed first（v0.8.0 起真正生效：install 与钩子都按优先级降序；
  // 同优先级保持 plugins 数组顺序）
  priority: 50,

  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() {
    // 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/constants.ts` (`VERSION` constant).
2. Update `CHANGELOG.md`.
3. Run full test suite: `npm test`.
4. Build: `npm run build`.
5. Publish: `npm publish`.

## Questions?

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