npm package: @meituan-nocode/backend-sdk
Description: NoCode Backend TypeScript SDK
Latest version: 0.2.7

# NoCode Entity SDK

NoCode 实体操作 SDK

## 安装

```bash
npm install @nocode/backend-sdk
# or
yarn add @nocode/backend-sdk
```

## 快速开始

### 基础配置

```javascript
import { createClient } from '@nocode/backend-sdk';

// Create a client instance
export const nocodeBackend = createClient({
   appId: "your-app-id",
   serverUrl: "https://nocode.cn",
   env: 'test',
});
```

###  实体操作

```javascript
// 获取Todo实体
export const Todo = nocodeBackend.entities.Todo;

// 获取所有Todo数据
await Todo.filter()

// 带条件筛选Todo数据
await Todo.filter({
  where: { priority: "极高", done: false },
  orderBy: "created_at",
  limit: 10,
  offset: 0
})

// 复杂排序条件
await Todo.filter({
  where: { priority: "极高" },
  orderBy: [
    { field: "priority", direction: "DESC" },
    { field: "created_at", direction: "ASC" }
  ],
  limit: 20
})

// 创建一条新Todo
await Todo.create({todo_content: "Todo 1", priority: "极高", "ddl": "1970-01-01 00:00:00"})

// 更新一条Todo数据
await Todo.update(1, {todo_content: "This is new content"})

// 删除一条Todo数据
await Todo.delete(1)
```

## API 参考

### 实体操作

每个实体支持以下四种操作：

- `filter(conditions?)` - 获取实体数据，支持筛选条件
- `create(data)` - 创建新实体
- `update(id, data)` - 更新指定ID的实体
- `delete(id)` - 删除指定ID的实体

### 筛选条件 (FilterConditions)

`filter` 方法支持以下筛选条件，所有参数都是可选的：

```typescript
interface FilterConditions {
  where?: Record<string, unknown>;    // 查询条件，支持字段名-值对
  orderBy?: string | Array<{          // 排序条件
    field: string;                    // 排序字段
    direction: 'ASC' | 'DESC';        // 排序方向
  }>;
  limit?: number;                     // 限制返回数量
  offset?: number;                    // 跳过前N条记录
}
```

**使用示例：**

#### 1. 无条件查询 - 获取所有数据
```javascript
await Todo.filter()
```

#### 2. where 条件筛选 - 根据字段值过滤数据
```javascript
// 单个条件：查找优先级为"极高"的Todo
await Todo.filter({ where: { priority: "极高" } })

// 多个条件：查找优先级为"极高"且pd为0的Todo
await Todo.filter({ where: { priority: "极高", pd: 0 } })

// 字符串匹配：查找已完成的任务 (pd=1)
await Todo.filter({ where: { pd: 1 } })
```

#### 3. orderBy 排序 - 控制返回数据的排序方式
```javascript
// 字符串格式：按创建时间降序排列
await Todo.filter({ orderBy: "created_at DESC" })

// 字符串格式：按截止时间升序排列
await Todo.filter({ orderBy: "ddl ASC" })

// 对象数组格式：多字段排序（先按优先级降序，再按创建时间升序）
await Todo.filter({
  orderBy: [
    { field: "priority", direction: "DESC" },
    { field: "created_at", direction: "ASC" }
  ]
})
```

#### 4. limit 限制数量 - 控制返回记录的最大数量
```javascript
// 只返回前3条记录
await Todo.filter({ limit: 3 })

// 结合where条件，只返回前2条优先级为"极高"的记录
await Todo.filter({
  where: { priority: "极高" },
  limit: 2
})
```

#### 5. offset 分页偏移 - 跳过指定数量的记录
```javascript
// 跳过前2条记录
await Todo.filter({ offset: 2 })

// 分页示例：获取第2页数据（每页2条）
await Todo.filter({ limit: 2, offset: 2 })  // 跳过前2条，取2条

// 分页示例：获取第1页数据
await Todo.filter({ limit: 2, offset: 0 })   // 从第1条开始，取2条
```

#### 6. 组合条件 - 同时使用多个筛选参数
```javascript
// 完整的筛选和分页示例
await Todo.filter({
  where: { priority: "极高", pd: 0 },     // 筛选条件：优先级极高且未完成
  orderBy: "created_at DESC",              // 排序：按创建时间降序
  limit: 2,                                // 限制：最多返回2条
  offset: 0                                // 偏移：从第1条开始
})

// 复杂排序的组合示例
await Todo.filter({
  where: { priority: "极高" },
  orderBy: [
    { field: "ddl", direction: "ASC" },        // 先按截止时间升序
    { field: "created_at", direction: "DESC" }  // 再按创建时间降序
  ],
  limit: 2,
  offset: 1
})
```

## 测试

本SDK提供了完整的测试套件，包括结构测试和功能测试。

### Filter功能测试

```bash
npm run test:filter
```

**⚠️ 注意：此测试需要真实的NoCode服务器连接**

### 运行Filter测试前的配置

编辑 `test/test_filter.mjs` 文件，修改配置：

```javascript
const nocodeBackend = createClient({
  appId: "your-real-app-id",           // 替换为真实的应用ID
  serverUrl: "https://your-server.com", // 替换为你的NoCode服务器地址
  env: 'test',
});
```

测试流程：
1. **数据插入阶段**：向数据库插入5条测试Todo数据
2. **Filter测试阶段**：执行7种不同的筛选测试
   - 无条件查询 (`await Todo.filter()`)
   - where条件筛选 (`{ where: { priority: "极高" } }`)
   - 多条件筛选 (`{ where: { priority: "极高", pd: 0 } }`)
   - orderBy排序 (`{ orderBy: "created_at DESC" }`)
   - limit限制 (`{ limit: 3 }`)
   - offset分页 (`{ limit: 2, offset: 2 }`)
   - 组合条件 (`{ where: {...}, orderBy: "...", limit: 2 }`)

## License

MIT