# quicklider

**Repository Path**: jl15988/quicklider

## Basic Information

- **Project Name**: quicklider
- **Description**: 一个类型安全、链式调用的SQL构建工具库，专为SQLite数据库优化设计。它让您能够用简洁、直观的方式构建和执行各种SQL操作，同时保持完整的类型检查和安全性。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-01
- **Last Updated**: 2025-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Sqlite, sqlite3, Database, query-builder, SQL

## README

# QuickLider

QuickLider 是一个类型安全、链式调用的SQL构建工具库，专为SQLite数据库优化设计。它让您能够用简洁、直观的方式构建和执行各种SQL操作，同时保持完整的类型检查和安全性。

## 核心优势

- **完全类型安全**：利用TypeScript类型系统提供字段名自动补全和类型检查
- **防SQL注入**：自动参数化处理所有查询，确保安全性
- **链式API**：流畅的调用体验，使代码简洁易读
- **JSON配置支持**：可通过JSON对象定义表结构，便于动态创建和管理表
- **全面覆盖**：支持所有常见SQL操作（查询、插入、更新、删除和表管理）
- **高性能设计**：缓存预编译语句，支持批量操作
- **条件构建**：强大的条件表达式构建，支持复杂查询逻辑
- **与执行器集成**：统一执行接口，简化数据库交互

## 模块结构

```
src/
├── builders/          # SQL构建器相关类
│   ├── SqlBuilder.ts      # 主SQL构建器
│   ├── SelectBuilder.ts   # 查询语句构建器
│   ├── InsertBuilder.ts   # 插入语句构建器
│   ├── UpdateBuilder.ts   # 更新语句构建器
│   ├── DeleteBuilder.ts   # 删除语句构建器
│   └── TableBuilder.ts    # 表结构构建器
├── conditions/        # 条件构建相关类
│   ├── ConditionBuilder.ts # 条件构建器
│   └── SqlFilter.ts        # SQL过滤器
├── execution/         # 执行相关类
│   └── SqlExecutor.ts      # SQL执行器
└── common/            # 公共类和类型
```

## 快速开始

### 创建构建器

```typescript
import { SqlBuilder } from 'quicklider';

// 定义实体类型
interface User {
  id: number;
  username: string;
  email: string;
  age: number;
  isActive: boolean;
}

// 创建SQL构建器
const userTable = SqlBuilder.forEntity<User>('users');
```

### 执行查询

```typescript
import { SqlExecutor } from 'quicklider';
import Database from 'better-sqlite3';

// 创建数据库连接和执行器
const db = new Database(':memory:');
const executor = new SqlExecutor(db);
userTable.setExecutor(executor);

// 条件查询 - 使用便捷方法
const activeUsers = userTable
  .select('id', 'username', 'email')
  .eq('isActive', true)
  .gt('age', 21)
  .orderBy('username')
  .execute();

// 复杂查询 - 使用条件组
const results = userTable
  .select()
  .eq('isActive', true)
  .and(builder => {
    builder
      .like('username', 'j')      // LIKE '%j%'
      .or()
      .like('email', 'gmail.com') // LIKE '%gmail.com%'
  })
  .limit(20)
  .execute();
```

### 数据修改

```typescript
// 插入数据
const insertResult = userTable
  .insert({
    username: 'alice',
    email: 'alice@example.com',
    age: 28,
    isActive: true
  })
  .execute();

// 更新数据
const updateResult = userTable
  .update({ isActive: false })
  .where('lastLogin', '<', '2023-01-01')
  .execute();

// 删除数据
const deleteResult = userTable
  .delete()
  .where('isActive', '=', false)
  .execute();
```

### 创建表结构

**链式方法创建**

```typescript
import { TableBuilder } from 'quicklider';

// 创建表
TableBuilder.create('users')
  .ifNotExist()
  .autoId()
  .text('username', { notNull: true, unique: true })
  .text('email', { notNull: true })
  .integer('age')
  .boolean('isActive', { defaultValue: true })
  .defaultTimestamp('createdAt')
  .defaultTimestamp('updatedAt')
  .execute(executor);
```

**JSON格式创建**

```typescript
import { TableBuilder } from 'quicklider';

// 使用JSON配置创建表
const userTable = TableBuilder.fromJSON({
  name: 'users',
  ifNotExists: true,
  columns: [
    { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
    { name: 'username', type: 'TEXT', notNull: true, unique: true },
    { name: 'email', type: 'TEXT', notNull: true },
    { name: 'age', type: 'INTEGER' },
    { name: 'isActive', type: 'INTEGER', defaultValue: 1 },
    { name: 'createdAt', type: 'TEXT', defaultValue: 'CURRENT_TIMESTAMP' },
    { name: 'updatedAt', type: 'TEXT', defaultValue: 'CURRENT_TIMESTAMP' }
  ],
  indices: [
    { name: 'users_email_idx', columns: ['email'], unique: true },
    { name: 'users_age_idx', columns: ['age'] }
  ]
}).execute(executor);
```

## 核心功能一览

### 便捷条件方法

```typescript
// 无需使用where，直接使用便捷方法
userTable
  .select()
  .eq('status', 'active')         // 等于
  .ne('role', 'guest')            // 不等于
  .gt('age', 18)                  // 大于
  .lt('price', 100)               // 小于
  .in('role', ['admin', 'editor']) // IN条件
  .like('name', 'john')           // 包含搜索
  .isNull('deletedAt')            // IS NULL
  .between('created', '2023-01-01', '2023-12-31') // 范围查询
  .execute();
```

### 条件分组

```typescript
userTable
  .select()
  .eq('status', 'active')
  .and(builder => {
    // 价格低或评分高
    builder
      .lt('price', 100)
      .or()
      .gt('rating', 4.5);
  })
  .execute();
```

### 交易支持

```typescript
executor.transaction(tx => {
  // 在事务中执行多个操作
  const userId = tx.execute(
    userTable.insert({ username: 'bob', email: 'bob@example.com' })
  ).lastInsertRowid;
  
  tx.execute(
    profileTable.insert({ userId, bio: 'New user' })
  );
  
  // 自动提交或出错时回滚
});
```

## 详细文档

每个模块都有详细的文档，您可以参考对应目录下的README文件：

- [构建器文档](./src/builders/README.md) - 详细了解各种SQL构建器的使用方法
- [条件文档](./src/conditions/README.md) - 学习如何构建各类查询条件和过滤器
- [执行器文档](./src/execution/README.md) - 了解SQL执行和事务管理

## 使用提示

1. **利用类型系统**：充分发挥TypeScript的优势，为表定义明确的接口
2. **合理使用事务**：将相关操作放入单一事务，保证数据一致性
3. **使用便捷方法**：优先使用`eq()`, `gt()`等便捷方法代替`where()`，代码更简洁
4. **动态查询**：对于API过滤需求，使用`SqlFilter`可以轻松处理请求参数
5. **批量操作**：处理大量数据时，使用批量方法提高性能
6. **表结构管理**：通过`TableBuilder`规范化表创建和管理，复杂表结构可使用JSON方式定义
7. **调试模式**：开发时可开启执行器的调试模式查看生成的SQL