# quicklite

**Repository Path**: jl15988/quicklite

## Basic Information

- **Project Name**: quicklite
- **Description**: 一个轻量级的 SQLite ORM 工具包，专为 Node.js 和 Electron 应用程序设计。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-03-22
- **Last Updated**: 2025-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Sqlite, ORM, Nodejs, Database, SQL

## README

# QuickLite

QuickLite 是一个轻量级的 TypeScript SQLite3 数据库管理框架，提供面向对象的 API 和强大的 ORM 功能，使 SQLite 数据库操作变得简单而高效。

[![npm version](https://img.shields.io/npm/v/quicklite.svg)](https://www.npmjs.com/package/quicklite)
[![License](https://img.shields.io/npm/l/quicklite.svg)](https://github.com/yourusername/quicklite/blob/main/LICENSE)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue)](https://www.typescriptlang.org/)

## 特性

- **类型安全**：完全基于 TypeScript，提供类型安全的 API 和编译时检查
- **简单易用**：提供直观、流畅的 API，降低使用门槛
- **装饰器支持**：通过装饰器轻松定义实体、字段和关系
- **关系映射**：支持一对一、一对多、多对一等关系定义和加载
- **自动表管理**：自动创建和同步表结构，无需手动编写 DDL
- **事务支持**：完整的事务管理，确保数据一致性
- **字段填充**：支持字段的自动填充，如创建时间、更新时间
- **逻辑删除**：支持软删除功能，无需物理删除数据
- **乐观锁**：通过版本控制确保数据一致性
- **连接池**：内置连接池管理，优化性能
- **轻量高效**：专为嵌入式数据库设计，性能优良

## 安装

```bash
npm install quicklite
```

## 快速开始

### 1. 创建数据库管理器

```typescript
import { DbManager } from 'quicklite';

// 创建数据库管理器
const db = new DbManager({
  dbFile: 'my-database.sqlite', // 数据库文件路径
  debug: true                   // 开启调试模式，输出 SQL 语句
});
```

### 2. 定义实体

```typescript
import { 
  Table, 
  TableId, 
  TableField, 
  FieldFill 
} from 'quicklite';

@Table({ name: 'users' })
class User {
  @TableId({ strategy: 'UUID' })
  id!: string;
  
  @TableField()
  name!: string;
  
  @TableField()
  email!: string;
  
  @FieldFill({ type: 'INSERT' })
  createTime!: string;
}
```

### 3. 注册实体并创建表

```typescript
// 注册实体
db.addEntity(User);

// 自动创建表
await db.autoCreateTables();
```

### 4. 执行 CRUD 操作

```typescript
// 创建
const user = new User();
user.name = '张三';
user.email = 'zhangsan@example.com';
await db.qk.save(user);

// 查询单个实体
const foundUser = await db.qk.get(User, user.id);

// 条件查询
const users = await db.qk.query(User)
  .where('name', '张三')
  .or('email', 'LIKE', '%example.com')
  .orderBy('createTime', 'DESC')
  .limit(10)
  .toList();

// 更新
user.name = '李四';
await db.qk.update(user);

// 删除
await db.qk.delete(User, user.id);
```

### 5. 使用事务

```typescript
// 事务操作
await db.transaction(async (qk) => {
  const user = new User();
  user.name = '王五';
  user.email = 'wangwu@example.com';
  await qk.save(user);
  
  // 如果有异常，事务将自动回滚
  
  // ... 更多操作 ...
});
```

## 定义关系

```typescript
import { 
  Table, 
  TableId, 
  TableField, 
  OneToMany,
  ManyToOne 
} from 'quicklite';

@Table()
class User {
  @TableId()
  id!: number;
  
  @TableField()
  name!: string;
  
  // 一对多关系
  @OneToMany(() => Post)
  posts!: Post[];
}

@Table()
class Post {
  @TableId()
  id!: number;
  
  @TableField()
  title!: string;
  
  @TableField()
  content!: string;
  
  @TableField()
  userId!: number;
  
  // 多对一关系
  @ManyToOne(() => User)
  user!: User;
}
```

## 加载关系

```typescript
// 查询并加载关系
const users = await db.qk.query(User)
  .include('posts')  // 加载关联的 posts
  .toList();

// 访问关系数据
for (const user of users) {
  console.log(`${user.name} 的文章:`);
  for (const post of user.posts) {
    console.log(`- ${post.title}`);
  }
}
```

## 高级查询

```typescript
const results = await db.qk.query(User)
  .where('name', 'LIKE', '%张%')
  .and('createTime', '>=', '2023-01-01')
  .or(builder => {
    return builder
      .where('email', 'LIKE', '%example.com')
      .and('id', 'IN', [1, 2, 3]);
  })
  .orderBy('name')
  .offset(10)
  .limit(10)
  .toList();
```

## 执行原生 SQL

```typescript
// 执行查询
const rows = await db.qk.execute(
  'SELECT * FROM users WHERE name = ? AND age > ?',
  ['张三', 18]
);

// 执行更新
const result = await db.qk.execute(
  'UPDATE users SET name = ? WHERE id = ?',
  ['李四', 1]
);
console.log(`影响的行数: ${result.changes}`);
```

## 配置选项

```typescript
const db = new DbManager({
  // 必需配置
  dbFile: 'my-database.sqlite',  // 数据库文件路径
  
  // 可选配置
  connectionName: 'default',     // 连接名称
  sqliteOptions: {               // SQLite3 驱动选项
    memory: false,
    readonly: false,
    fileMustExist: false
  },
  pool: {                        // 连接池配置
    min: 1,
    max: 10,
    idleTimeoutMillis: 30000
  },
  debug: true,                   // 调试模式
  autoCreateTables: true,        // 是否自动创建表
  synchronize: false,            // 是否同步表结构
  entities: [User, Post]         // 预注册实体
});
```

## 文档

详细文档请参阅 [核心模块文档](./src/core/README.md)：

- [管理器模块 (Manager)](./src/core/manager/README.md)
- [装饰器模块 (Decorator)](./src/core/manager/decorator/README.md)
- [实体模块 (Entity)](./src/core/manager/entity/README.md)
- [连接模块 (Connection)](./src/core/manager/connection/README.md)
- [快速操作模块 (QuickOper)](./src/core/manager/quickoper/README.md)

## 贡献

欢迎贡献代码、报告问题或提出改进建议。请查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解更多详情。

## 许可证

本项目采用 MIT 许可证，详情请参阅 [LICENSE](./LICENSE) 文件。