npm package: @llii/db
Description: 本库是一个基于Knex封装的 Node.js ORM库，支持 TypeScript 开发，提供简洁的 API 进行数据库操作，包括模型定义、CRUD 操作、关联查询、事务处理等功能。
Latest version: 0.0.16

## 概述

本库是一个基于Knex封装的 Node.js ORM库，支持 TypeScript 开发，提供简洁的 API 进行数据库操作，包括模型定义、CRUD 操作、关联查询、事务处理等功能。

## 注意
1. 本库只是自己学习封装的 ORM库，实际使用中请根据自身需求进行修改.
2. 本库是仿照strapi中的database去封装的部分功能的代码搬运的strapi的代码.

## 安装

```bash
npm install @lli/db
```

## 快速开始

### 1. 初始化数据库连接

```typescript
import { bootstrap } from '@lli/db';
import { FieldTypeEnum } from '@lli/db';

const db = await bootstrap({
  connection: {
    client: 'postgres',
    connection: {
      host: 'your-db-host',
      port: 5432,
      user: 'postgres',
      database: 'your-db',
      password: 'your-password',
    }
  },
  models: [
    {
      code: 'user',
      tableName: 'users',
      attributes: {
        username: {
          type: FieldTypeEnum.TEXT,
          required: true
        },
        email: {
          type: FieldTypeEnum.TEXT,
          required: true
        }
      }
    }
  ]
});
```

### 2. 基本 CRUD 操作

**创建数据**
```typescript
// 创建单条记录
const newUser = await db.query('user').create({
  data: {
    username: 'test-user',
    email: 'test@example.com'
  }
});

// 批量创建
const users = await db.query('user').createMany({
  data: [
    { username: 'user1', email: 'user1@example.com' },
    { username: 'user2', email: 'user2@example.com' }
  ]
});
```

**查询数据**
```typescript
// 查询单条
const user = await db.query('user').findOne({
  where: { username: 'test-user' }
});

// 查询多条（带条件）
const activeUsers = await db.query('user').findMany({
  where: {
    active: true,
    createdAt: { gte: '2023-01-01' }
  }
});

// 分页查询
const pageResult = await db.query('user').queryPage({
  page: 1,
  pageSize: 10,
  orderBy: { createdAt: 'desc' }
});
```

**更新数据**
```typescript
// 更新单条
await db.query('user').update({
  where: { id: 1 },
  data: { username: 'updated-name' }
});

// 批量更新
await db.query('user').updateMany({
  where: { active: false },
  data: { status: 'inactive' }
});
```

**删除数据**
```typescript
// 删除单条
await db.query('user').delete({
  where: { id: 123 }
});

// 批量删除
await db.query('user').deleteMany({
  where: { createdAt: { lt: '2020-01-01' } }
});
```

## 高级功能

### 关联查询

**定义关联模型**
```typescript
{
  code: 'post',
  tableName: 'posts',
  attributes: {
    title: { type: FieldTypeEnum.TEXT },
    author: {
      type: FieldTypeEnum.SINGLE_QUOTE,
      refCode: 'user', // 关联用户模型
      refFieldCode: 'id'
    },
    comments: {
      type: FieldTypeEnum.CHILD,
      refCode: 'comment',
      refFieldCode: 'postId'
    }
  }
}
```

**查询关联数据**
```typescript
// 查询帖子及其作者
const postWithAuthor = await db.query('post').findOne({
  where: { id: 1 },
  populate: {
    author: {
      select: ['username', 'email']
    }
  }
});

// 查询帖子及其评论
const postWithComments = await db.query('post').findOne({
  where: { id: 1 },
  populate: {
    comments: {
      select: ['content', 'createdAt']
    }
  }
});
```

### 复杂条件查询

```typescript
// 多条件组合
const results = await db.query('user').findMany({
  where: {
    or: [
      { username: { startsWith: 'admin' } },
      { 
        and: [
          { email: { endsWith: '@company.com' } },
          { createdAt: { gte: '2023-01-01' } }
        ]
      }
    ]
  }
});

// 关联模型条件
const posts = await db.query('post').findMany({
  where: {
    author: {
      username: 'john_doe'
    }
  }
});
```

### 聚合函数

```typescript
// 计数
const userCount = await db.query('user').count({
  where: { active: true }
});

// 最大值
const maxSalary = await db.query('employee').max({}, 'salary');

// 最小值
const minAge = await db.query('user').min({}, 'age');
```

### 数据克隆

```typescript
// 克隆用户数据
const clonedUser = await db.query('user').clone(originalUserId, {
  data: {
    username: 'cloned-user',
    email: 'clone@example.com'
  }
});
```

## 模型定义参考

### 模型属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `code` | string | 是 | 模型唯一标识 |
| `tableName` | string | 是 | 数据库表名 |
| `name` | string | 否 | 模型显示名称 |
| `attributes` | object | 是 | 字段定义集合 |

### 字段类型

| 类型 | 说明 |
|------|------|
| `TEXT` | 文本类型 |
| `INT` | 整数类型 |
| `FLOAT` | 浮点数类型 |
| `DATETIME` | 日期时间类型 |
| `SWITCH` | 开关/布尔类型 |
| `SINGLE_QUOTE` | 单引用（一对一） |
| `MULTI_QUOTE` | 多引用（多对多） |
| `JSON_OBJECT` | JSON 对象 |
| `JSON_ARRAY` | JSON 数组 |
| `CHILD` | 子表关联 |

### 字段属性

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `type` | FieldTypeEnum | 是 | 字段类型 |
| `required` | boolean | 否 | 是否必填（默认 false） |
| `default` | any | 否 | 默认值 |
| `refCode` | string | 关联字段必填 | 关联模型 code |
| `refFieldCode` | string | 关联字段必填 | 关联模型字段 |