qast 2.0.3 → 2.0.4

package/README.zh-CN.md

@@ -1,520 +0,0 @@
-# QAST — 查询字符串转AST转ORM
-
-[![npm version](https://img.shields.io/npm/v/qast.svg)](https://www.npmjs.com/package/qast)
-[![npm downloads](https://img.shields.io/npm/dm/qast.svg)](https://www.npmjs.com/package/qast)
-[![GitHub stars](https://img.shields.io/github/stars/hocestnonsatis/qast.svg)](https://github.com/hocestnonsatis/qast)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/npm/l/qast.svg)](https://github.com/hocestnonsatis/qast/blob/main/LICENSE)
-
-**QAST** 是一个轻量级、ORM无关的库，它可以将人类可读的查询字符串（例如 `age gt 25 and (name eq "John" or city eq "Paris")`）解析为**抽象语法树（AST）**，然后将该AST转换为**ORM兼容的过滤对象**，如Prisma或TypeORM过滤器。
-
-它旨在为REST API提供一种安全、声明式且类型安全的高级过滤支持方式——避免原始字符串查询模式的陷阱。
-
-## 特性
-
-- 🔒 **安全**：根据白名单验证操作符、值和字段
-- 🎯 **类型安全**：完整的TypeScript支持，包括解析后的AST和生成的过滤器
-- 🔌 **ORM无关**：通过适配器支持Prisma、TypeORM、Sequelize等
-- 📝 **简单语法**：使用逻辑操作符的自然查询表达式
-- 🚀 **轻量级**：无依赖，包体积小
-
-## 安装
-
-```bash
-npm install qast
-```
-
-## 快速开始
-
-### 基本用法
-
-```typescript
-import { parseQuery, toPrismaFilter } from 'qast';
-
-const query = 'age gt 25 and (name eq "John" or city eq "Paris")';
-
-const ast = parseQuery(query);
-const prismaFilter = toPrismaFilter(ast);
-
-await prisma.user.findMany(prismaFilter);
-```
-
-### 带验证的用法
-
-```typescript
-import { parseQuery, toPrismaFilter } from 'qast';
-
-const query = 'age gt 25 and name eq "John"';
-
-// 使用白名单验证进行解析
-const ast = parseQuery(query, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt'],
-  validate: true,
-});
-
-const prismaFilter = toPrismaFilter(ast);
-await prisma.user.findMany(prismaFilter);
-```
-
-## 查询语法
-
-### 操作符
-
-QAST支持以下比较操作符：
-
-- `eq` - 等于
-- `ne` - 不等于
-- `gt` - 大于
-- `lt` - 小于
-- `gte` - 大于等于
-- `lte` - 小于等于
-- `in` - 在数组中
-- `contains` - 包含子字符串（字符串匹配）
-
-### 逻辑操作符
-
-- `and` - 逻辑与
-- `or` - 逻辑或
-
-### 值类型
-
-- **字符串**：使用单引号或双引号：`"John"` 或 `'John'`
-- **数字**：整数或浮点数：`25`、`25.99`、`-10`
-- **布尔值**：`true` 或 `false`
-- **数组**：用于 `in` 操作符：`[1,2,3]` 或 `["John","Jane"]`
-
-### 示例
-
-```typescript
-// 简单比较
-'age gt 25'
-
-// 字符串比较
-'name eq "John"'
-
-// 布尔值比较
-'active eq true'
-
-// 数组（in操作符）
-'age in [1,2,3]'
-
-// AND操作
-'age gt 25 and name eq "John"'
-
-// OR操作
-'name eq "John" or name eq "Jane"'
-
-// 嵌套括号
-'age gt 25 and (name eq "John" or city eq "Paris")'
-
-// 复杂查询
-'age gt 25 and (name eq "John" or city eq "Paris") and active eq true'
-```
-
-## ORM适配器
-
-### Prisma
-
-```typescript
-import { parseQuery, toPrismaFilter } from 'qast';
-
-const query = 'age gt 25 and name eq "John"';
-const ast = parseQuery(query);
-const filter = toPrismaFilter(ast);
-
-// filter = {
-//   where: {
-//     age: { gt: 25 },
-//     name: { equals: "John" }
-//   }
-// }
-
-await prisma.user.findMany(filter);
-```
-
-### TypeORM
-
-```typescript
-import { parseQuery, toTypeORMFilter } from 'qast';
-import { MoreThan, Equal } from 'typeorm';
-
-const query = 'age gt 25 and name eq "John"';
-const ast = parseQuery(query);
-const filter = toTypeORMFilter(ast);
-
-// 注意：TypeORM需要操作符函数来进行非等值比较
-// 适配器返回一个结构，您可以使用TypeORM操作符进行转换
-// 对于等值比较，TypeORM直接接受普通值
-
-// filter.where = {
-//   age: { __qast_operator__: 'gt', value: 25 },
-//   name: "John"
-// }
-
-// 转换为使用TypeORM操作符：
-// const transformed = {
-//   age: MoreThan(25),
-//   name: "John"
-// }
-
-await userRepository.find({ where: transformed });
-```
-
-**注意**：TypeORM需要操作符函数（`MoreThan`、`LessThan`等）来进行非等值比较。适配器返回带有元数据的结构，您需要进行转换。对于等值比较，TypeORM直接接受普通值。
-
-### Sequelize
-
-```typescript
-import { parseQuery, toSequelizeFilter } from 'qast';
-import { Op } from 'sequelize';
-
-const query = 'age gt 25 and name eq "John"';
-const ast = parseQuery(query);
-const filter = toSequelizeFilter(ast);
-
-// filter = {
-//   __qast_logical__: 'and',
-//   conditions: [
-//     { age: { __qast_operator__: 'gt', value: 25 } },
-//     { name: 'John' }
-//   ]
-// }
-
-// 转换为使用Sequelize Op操作符：
-function transformSequelizeFilter(filter: any): any {
-  if (filter.__qast_logical__) {
-    const op = filter.__qast_logical__ === 'and' ? Op.and : Op.or;
-    return {
-      [op]: filter.conditions.map(transformSequelizeFilter),
-    };
-  }
-  
-  const result: any = {};
-  for (const [key, value] of Object.entries(filter)) {
-    if (value && typeof value === 'object' && '__qast_operator__' in value) {
-      const opKey = value.__qast_operator__;
-      const op = Op[opKey as keyof typeof Op];
-      if (opKey === 'contains') {
-        result[key] = { [Op.like]: `%${value.value}%` };
-      } else {
-        result[key] = { [op]: value.value };
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-const transformed = transformSequelizeFilter(filter);
-// transformed = {
-//   [Op.and]: [
-//     { age: { [Op.gt]: 25 } },
-//     { name: 'John' }
-//   ]
-// }
-
-await User.findAll({ where: transformed });
-```
-
-**注意**：Sequelize使用来自'sequelize'的`Op`对象。由于Sequelize是可选的对等依赖，适配器返回带有元数据（`__qast_operator__`和`__qast_logical__`）的结构，您需要将其转换为使用`Op`操作符。对于简单的等值比较（`eq`），适配器返回Sequelize直接接受的普通值。
-
-## API参考
-
-### `parseQuery(query: string, options?: ParseOptions): QastNode`
-
-将查询字符串解析为AST。
-
-**参数：**
-- `query` - 要解析的查询字符串
-- `options` - 可选的解析选项：
-  - `allowedFields?: string[]` - 允许的字段名白名单
-  - `allowedOperators?: Operator[]` - 允许的操作符白名单
-  - `validate?: boolean` - 是否根据白名单进行验证（如果提供了白名单，默认为true）
-  - `maxDepth?: number` - 最大允许的AST深度（用于限制嵌套逻辑表达式）
-  - `maxNodes?: number` - 最大允许的AST节点数（用于限制整体查询复杂度）
-  - `maxQueryLength?: number` - 最大允许的原始查询字符串长度（在解析前检查）
-  - `maxArrayLength?: number` - 最大允许的数组值长度（用于`in`操作符）
-  - `maxStringLength?: number` - 最大允许的字符串值长度
-
-**返回值：** 解析后的AST节点
-
-**示例：**
-```typescript
-const ast = parseQuery('age gt 25', {
-  allowedFields: ['age', 'name'],
-  allowedOperators: ['gt', 'eq'],
-  validate: true,
-  maxDepth: 5,
-  maxNodes: 50,
-  maxQueryLength: 1000,
-  maxArrayLength: 100,
-  maxStringLength: 200,
-});
-```
-
-### `toPrismaFilter(ast: QastNode): PrismaFilter`
-
-将AST转换为Prisma过滤器。
-
-**返回值：** 带有`where`属性的Prisma过滤对象
-
-### `toTypeORMFilter(ast: QastNode): TypeORMFilter`
-
-将AST转换为TypeORM过滤器。
-
-**返回值：** 带有`where`属性的TypeORM过滤对象
-
-**注意：** TypeORM需要操作符函数来进行非等值比较。您可能需要转换结果。
-
-### `toSequelizeFilter(ast: QastNode): SequelizeFilter`
-
-将AST转换为Sequelize过滤器。
-
-**返回值：** Sequelize过滤对象
-
-**注意：** Sequelize使用`Op`对象。您需要将`$`前缀的操作符转换为使用`Op`操作符。
-
-### `validateQuery(ast: QastNode, whitelist: WhitelistOptions): void`
-
-根据白名单验证AST。
-
-**参数：**
-- `ast` - 要验证的AST
-- `whitelist` - 白名单选项：
-  - `allowedFields?: string[]` - 允许的字段名
-  - `allowedOperators?: Operator[]` - 允许的操作符
-
-**抛出：** 如果验证失败，抛出`ValidationError`
-
-### `extractFields(ast: QastNode): string[]`
-
-提取AST中使用的所有字段名。
-
-**返回值：** 唯一字段名数组
-
-### `extractOperators(ast: QastNode): Operator[]`
-
-提取AST中使用的所有操作符。
-
-**返回值：** 唯一操作符数组
-
-### `validateQueryComplexity(ast: QastNode, options: ComplexityOptions): void`
-
-根据复杂度限制验证AST。
-
-**参数：**
-- `ast` - 要验证的AST
-- `options` - 复杂度选项：
-  - `maxDepth?: number` - 最大允许的AST深度
-  - `maxNodes?: number` - 最大允许的节点数
-  - `maxArrayLength?: number` - 最大允许的数组长度
-  - `maxStringLength?: number` - 最大允许的字符串长度
-
-**抛出：** 如果超出任何限制，抛出`ValidationError`
-
-**示例：**
-```typescript
-import { parseQuery, validateQueryComplexity } from 'qast';
-
-const ast = parseQuery('age in [1,2,3,4,5]');
-validateQueryComplexity(ast, {
-  maxDepth: 5,
-  maxNodes: 20,
-  maxArrayLength: 100,
-  maxStringLength: 200,
-});
-```
-
-## 安全最佳实践
-
-1. **始终使用白名单**：限制查询中可以使用的字段和操作符。
-
-```typescript
-const ast = parseQuery(req.query.filter, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt'],
-  validate: true,
-});
-```
-
-2. **验证用户输入**：不要在没有验证的情况下信任用户提供的查询字符串。
-
-3. **限制查询复杂度**：使用复杂度限制来防止DoS攻击。
-
-```typescript
-const ast = parseQuery(req.query.filter, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt', 'in'],
-  validate: true,
-  // 复杂度限制
-  maxQueryLength: 1000,  // 拒绝超过1000字符的查询
-  maxDepth: 5,           // 最多5层嵌套
-  maxNodes: 20,          // 最多20个条件
-  maxArrayLength: 100,   // 'in'数组最多100项
-  maxStringLength: 200,  // 每个字符串值最多200字符
-});
-```
-
-4. **使用类型检查**：确保值与字段的预期类型匹配。
-
-## 错误处理
-
-QAST提供自定义错误类：
-
-- `ParseError` - 查询字符串中的语法错误
-- `ValidationError` - 验证失败（不允许的字段/操作符）
-- `TokenizationError` - 词法分析错误
-
-```typescript
-import { parseQuery, ParseError, ValidationError } from 'qast';
-
-try {
-  const ast = parseQuery(query, { allowedFields: ['age'], validate: true });
-} catch (error) {
-  if (error instanceof ParseError) {
-    console.error('解析错误:', error.message);
-  } else if (error instanceof ValidationError) {
-    console.error('验证错误:', error.message);
-    console.error('字段:', error.field);
-    console.error('操作符:', error.operator);
-  }
-}
-```
-
-## TypeScript支持
-
-QAST使用TypeScript编写，并提供完整的类型定义：
-
-```typescript
-import { QastNode, ComparisonNode, LogicalNode, Operator } from 'qast';
-
-function processNode(node: QastNode): void {
-  if (node.type === 'COMPARISON') {
-    const comparison = node as ComparisonNode;
-    console.log(comparison.field, comparison.op, comparison.value);
-  } else if (node.type === 'AND' || node.type === 'OR') {
-    const logical = node as LogicalNode;
-    processNode(logical.left);
-    processNode(logical.right);
-  }
-}
-```
-
-## 示例
-
-### REST API端点
-
-```typescript
-import { parseQuery, toPrismaFilter } from 'qast';
-import { PrismaClient } from '@prisma/client';
-
-const prisma = new PrismaClient();
-
-app.get('/users', async (req, res) => {
-  try {
-    const query = req.query.filter as string;
-    
-    // 解析和验证查询
-    const ast = parseQuery(query, {
-      allowedFields: ['age', 'name', 'city', 'active'],
-      allowedOperators: ['gt', 'lt', 'eq', 'in'],
-      validate: true,
-    });
-    
-    // 转换为Prisma过滤器
-    const filter = toPrismaFilter(ast);
-    
-    // 查询数据库
-    const users = await prisma.user.findMany(filter);
-    
-    res.json(users);
-  } catch (error) {
-    if (error instanceof ValidationError) {
-      res.status(400).json({ error: error.message });
-    } else {
-      res.status(500).json({ error: '内部服务器错误' });
-    }
-  }
-});
-```
-
-### Express中间件
-
-```typescript
-import { parseQuery, toPrismaFilter, ValidationError } from 'qast';
-
-function qastMiddleware(allowedFields: string[], allowedOperators: Operator[]) {
-  return (req, res, next) => {
-    try {
-      if (req.query.filter) {
-        const ast = parseQuery(req.query.filter, {
-          allowedFields,
-          allowedOperators,
-          validate: true,
-        });
-        
-        req.qastFilter = toPrismaFilter(ast);
-      }
-      next();
-    } catch (error) {
-      if (error instanceof ValidationError) {
-        res.status(400).json({ error: error.message });
-      } else {
-        next(error);
-      }
-    }
-  };
-}
-```
-
-## 与替代方案的比较
-
-### 为什么选择QAST？
-
-| 特性 | QAST | GraphQL | OData | 自定义解析器 |
-|------|------|---------|-------|-------------|
-| **类型安全** | ✅ 完整TypeScript | ❌ 仅运行时 | ⚠️ 部分 | ❌ 通常没有 |
-| **安全性** | ✅ 白名单验证 | ✅ 内置 | ✅ 内置 | ⚠️ 手动 |
-| **ORM无关** | ✅ 是 | ❌ 否 | ❌ 否 | ⚠️ 因情况而异 |
-| **零依赖** | ✅ 是 | ❌ 否 | ❌ 否 | ⚠️ 因情况而异 |
-| **学习曲线** | ✅ 简单 | ❌ 复杂 | ❌ 复杂 | ⚠️ 因情况而异 |
-| **REST API友好** | ✅ 是 | ❌ 需要GraphQL端点 | ✅ 是 | ⚠️ 因情况而异 |
-| **包大小** | ✅ < 10KB | ❌ 大 | ❌ 大 | ⚠️ 因情况而异 |
-
-**适合使用QAST的场景：**
-- 您想要一个简单、安全的REST API查询语言
-- 您需要使用TypeScript进行类型安全的查询解析
-- 您正在使用Prisma、TypeORM或Sequelize
-- 您想要零依赖和小的包大小
-- 您需要字段和操作符白名单以确保安全
-
-**考虑替代方案的场景：**
-- 您需要GraphQL的完整查询能力
-- 您需要标准化的查询协议（OData）
-- 您有复杂的嵌套数据关系
-
-## 示例项目
-
-查看[`examples`](./examples)目录获取完整的工作示例：
-
-- [Express.js REST API](./examples/express) - 完整的Express.js服务器与Prisma
-- [Next.js API路由](./examples/nextjs) - 使用QAST的Next.js API路由
-- [NestJS集成](./examples/nestjs) - 带有查询过滤的NestJS控制器
-- [交互式演示](./examples/playground.html) - 在浏览器中尝试QAST查询（演示）
-
-## 许可证
-
-MIT © 2025
-
-## 贡献
-
-欢迎贡献！详情请参阅[CONTRIBUTING.md](./CONTRIBUTING.md)。
-
-- GitHub仓库：https://github.com/hocestnonsatis/qast
-- 问题反馈：https://github.com/hocestnonsatis/qast/issues
-
-## 致谢
-
-QAST的灵感来源于REST API中对安全、类型安全的查询解析的需求。它旨在提供一个轻量级的替代方案，同时保持安全性和开发者体验。