@lovrabet/sdk 1.1.20 → 1.1.21

package/README.md

@@ -354,6 +354,10 @@ import {
   type TokenResult,
   type ListResponse,
   type ListParams,
+  type FilterParams,
+  type WhereCondition,
+  type FieldCondition,
+  type ConditionOperator,
   type SortList,
   type SelectOption,
   type SelectOptionsParams,
@@ -426,10 +430,143 @@ const options = await client.models.users.getSelectOptions({
 // 返回: [{ label: '张三', value: 'user001' }, { label: '李四', value: 'user002' }]
 ```
 
+### 🔍 高级过滤查询（推荐）
+
+`filter()` 方法提供比 `getList()` 更强大的查询能力，支持复杂的条件筛选、字段选择和排序。
+
+#### 基础用法
+
+```typescript
+// 简单条件查询
+const result = await client.models.users.filter({
+  where: {
+    age: { $gte: 18 } // 年龄 >= 18
+  },
+  currentPage: 1,
+  pageSize: 20
+});
+
+console.log(result.tableData); // 数据列表
+console.log(result.total);     // 总数量
+```
+
+#### 复杂条件组合
+
+```typescript
+import { SortOrder } from "@lovrabet/sdk";
+
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      // 年龄区间
+      { age: { $gte: 18, $lte: 45 } },
+      // 国家在集合内
+      { country: { $in: ['中国', '美国', '日本'] } },
+      // VIP 字段非空
+      { vip: { $ne: null } },
+      // 名称模糊匹配
+      { name: { $contain: 'hello' } }
+    ]
+  },
+  // 选择返回的字段
+  select: ['id', 'name', 'age', 'country', 'lastLoginAt'],
+  // 多字段排序：先按登录时间倒序，再按名称升序
+  orderBy: [
+    { lastLoginAt: SortOrder.DESC },
+    { name: SortOrder.ASC }
+  ],
+  currentPage: 1,
+  pageSize: 20
+});
+```
+
+#### 支持的操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ status: { $eq: 'active' } }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$gte` / `$gteq` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lte` / `$lteq` | 小于等于 | `{ age: { $lte: 65 } }` |
+| `$in` | 在集合内 | `{ country: { $in: ['中国', '美国'] } }` |
+| `$contain` | 包含（模糊匹配） | `{ name: { $contain: 'test' } }` |
+| `$startWith` | 以...开头 | `{ name: { $startWith: 'Mr.' } }` |
+| `$endWith` | 以...结尾 | `{ email: { $endWith: '@example.com' } }` |
+
+#### 逻辑连接符
+
+```typescript
+// $and - 所有条件都满足
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      { age: { $gte: 18 } },
+      { status: { $eq: 'active' } }
+    ]
+  }
+});
+
+// $or - 任一条件满足
+const result = await client.models.users.filter({
+  where: {
+    $or: [
+      { country: { $eq: '中国' } },
+      { country: { $eq: '美国' } }
+    ]
+  }
+});
+
+// 嵌套条件
+const result = await client.models.users.filter({
+  where: {
+    $and: [
+      { age: { $gte: 18 } },
+      {
+        $or: [
+          { country: { $eq: '中国' } },
+          { country: { $eq: '美国' } }
+        ]
+      }
+    ]
+  }
+});
+```
+
+#### 字段选择
+
+```typescript
+// 只返回指定字段
+const result = await client.models.users.filter({
+  select: ['id', 'name', 'email'],
+  currentPage: 1,
+  pageSize: 20
+});
+
+// 访问 JSON 字段
+const result = await client.models.users.filter({
+  select: ['id', "value['name']", 'age'],
+  currentPage: 1,
+  pageSize: 20
+});
+```
+
+#### filter vs getList
+
+| 特性 | `filter()` | `getList()` |
+|------|-----------|------------|
+| 复杂条件查询 | ✅ 支持 $and, $or 等 | ❌ 仅支持简单参数 |
+| 字段选择 | ✅ 支持 select | ❌ 返回所有字段 |
+| 条件操作符 | ✅ 支持 11 种操作符 | ❌ 仅支持精确匹配 |
+| 排序 | ✅ 支持多字段排序 | ✅ 支持多字段排序 |
+| 分页 | ✅ 支持 | ✅ 支持 |
+| 性能 | 更优（减少数据传输） | 一般 |
+| 使用场景 | **推荐用于复杂查询** | 简单列表查询 |
+
 ### ⚠️ 操作限制
 
 **OpenAPI 模式暂不支持以下操作：**
 
+- ❌ `filter()` - 高级过滤查询（如需使用，请使用 WebAPI 模式）
 - ❌ `delete()` - 删除操作（如需删除，请使用 WebAPI 模式）
 - ❌ `getSelectOptions()` - 获取下拉选项（仅 WebAPI 模式支持）
 

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export { ApiNamespace } from "./src/api/index";
 export { AuthManager, } from "./src/auth/index";
 export { generateOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type TokenResult } from "./src/auth/index";
 export type { ClientConfig, LovrabetClient, ModelConfig, ModelsConfig, } from "./src/types/index";
-export type { ListParams, ListResponse, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
+export type { ListParams, ListResponse, FilterParams, WhereCondition, FieldCondition, ConditionOperator, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
 export type { SqlExecuteRequest, SqlExecuteResult, } from "./src/api/types";
 export { SortOrder, } from "./src/types/index";