qast 1.2.0 → 2.0.2

package/README.md

@@ -1,520 +1,775 @@
-# QAST — Query to AST to 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** is a small, ORM-agnostic library that parses human-readable query strings (e.g. `age gt 25 and (name eq "John" or city eq "Paris")`) into an **Abstract Syntax Tree (AST)** and then transforms that AST into **ORM-compatible filter objects** such as Prisma or TypeORM filters.
-
-It aims to provide a secure, declarative, and type-safe way to support advanced filtering in REST APIs — without falling into the pitfalls of raw string-based query patterns.
-
-## Features
-
-- 🔒 **Safe**: Validates operators, values, and fields against whitelists
-- 🎯 **Type-Safe**: Full TypeScript support for parsed ASTs and generated filters
-- 🔌 **ORM-Agnostic**: Works with Prisma, TypeORM, Sequelize, and more via adapters
-- 📝 **Simple Syntax**: Natural query expressions using logical operators
-- 🚀 **Lightweight**: No dependencies, small bundle size
-
-## Installation
-
-```bash
-npm install qast
-```
-
-## Quick Start
-
-### Basic Usage
-
-```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);
-```
-
-### With Validation
-
-```typescript
-import { parseQuery, toPrismaFilter } from 'qast';
-
-const query = 'age gt 25 and name eq "John"';
-
-// Parse with whitelist validation
-const ast = parseQuery(query, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt'],
-  validate: true,
-});
-
-const prismaFilter = toPrismaFilter(ast);
-await prisma.user.findMany(prismaFilter);
-```
-
-## Query Syntax
-
-### Operators
-
-QAST supports the following comparison operators:
-
-- `eq` - Equal
-- `ne` - Not equal
-- `gt` - Greater than
-- `lt` - Less than
-- `gte` - Greater than or equal
-- `lte` - Less than or equal
-- `in` - In array
-- `contains` - Contains substring (string matching)
-
-### Logical Operators
-
-- `and` - Logical AND
-- `or` - Logical OR
-
-### Values
-
-- **Strings**: Use single or double quotes: `"John"` or `'John'`
-- **Numbers**: Integers or floats: `25`, `25.99`, `-10`
-- **Booleans**: `true` or `false`
-- **Arrays**: For `in` operator: `[1,2,3]` or `["John","Jane"]`
-
-### Examples
-
-```typescript
-// Simple comparison
-'age gt 25'
-
-// String comparison
-'name eq "John"'
-
-// Boolean comparison
-'active eq true'
-
-// Array (in operator)
-'age in [1,2,3]'
-
-// AND operation
-'age gt 25 and name eq "John"'
-
-// OR operation
-'name eq "John" or name eq "Jane"'
-
-// Nested parentheses
-'age gt 25 and (name eq "John" or city eq "Paris")'
-
-// Complex query
-'age gt 25 and (name eq "John" or city eq "Paris") and active eq true'
-```
-
-## ORM Adapters
-
-### 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);
-
-// Note: TypeORM requires operator functions for non-equality comparisons
-// The adapter returns a structure that you can transform using TypeORM operators
-// For equality, TypeORM accepts plain values directly
-
-// filter.where = {
-//   age: { __qast_operator__: 'gt', value: 25 },
-//   name: "John"
-// }
-
-// Transform to use TypeORM operators:
-// const transformed = {
-//   age: MoreThan(25),
-//   name: "John"
-// }
-
-await userRepository.find({ where: transformed });
-```
-
-**Note**: TypeORM requires operator functions (`MoreThan`, `LessThan`, etc.) for non-equality comparisons. The adapter returns a structure with metadata that you can transform. For equality comparisons, TypeORM accepts plain values.
-
-### 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' }
-//   ]
-// }
-
-// Transform to use Sequelize Op operators:
-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 });
-```
-
-**Note**: Sequelize uses the `Op` object from 'sequelize'. Since Sequelize is an optional peer dependency, the adapter returns a structure with metadata (`__qast_operator__` and `__qast_logical__`) that you need to transform to use `Op` operators. For simple equality (`eq`), the adapter returns plain values which Sequelize accepts directly.
-
-## API Reference
-
-### `parseQuery(query: string, options?: ParseOptions): QastNode`
-
-Parse a query string into an AST.
-
-**Parameters:**
-- `query` - The query string to parse
-- `options` - Optional parsing options:
-  - `allowedFields?: string[]` - Whitelist of allowed field names
-  - `allowedOperators?: Operator[]` - Whitelist of allowed operators
-  - `validate?: boolean` - Whether to validate against whitelists (default: true if whitelists are provided)
-  - `maxDepth?: number` - Maximum allowed AST depth (to limit nested logical expressions)
-  - `maxNodes?: number` - Maximum allowed number of AST nodes (to limit overall query complexity)
-  - `maxQueryLength?: number` - Maximum allowed length of the raw query string (checked before parsing)
-  - `maxArrayLength?: number` - Maximum allowed length of array values (for `in` operator)
-  - `maxStringLength?: number` - Maximum allowed length of string values
-
-**Returns:** The parsed AST node
-
-**Example:**
-```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`
-
-Transform an AST to a Prisma filter.
-
-**Returns:** Prisma filter object with `where` property
-
-### `toTypeORMFilter(ast: QastNode): TypeORMFilter`
-
-Transform an AST to a TypeORM filter.
-
-**Returns:** TypeORM filter object with `where` property
-
-**Note:** TypeORM requires operator functions for non-equality comparisons. You may need to transform the result.
-
-### `toSequelizeFilter(ast: QastNode): SequelizeFilter`
-
-Transform an AST to a Sequelize filter.
-
-**Returns:** Sequelize filter object
-
-**Note:** Sequelize uses the `Op` object. You need to transform `$`-prefixed operators to use `Op` operators.
-
-### `validateQuery(ast: QastNode, whitelist: WhitelistOptions): void`
-
-Validate an AST against whitelists.
-
-**Parameters:**
-- `ast` - The AST to validate
-- `whitelist` - Whitelist options:
-  - `allowedFields?: string[]` - Allowed field names
-  - `allowedOperators?: Operator[]` - Allowed operators
-
-**Throws:** `ValidationError` if validation fails
-
-### `extractFields(ast: QastNode): string[]`
-
-Extract all field names used in an AST.
-
-**Returns:** Array of unique field names
-
-### `extractOperators(ast: QastNode): Operator[]`
-
-Extract all operators used in an AST.
-
-**Returns:** Array of unique operators
-
-### `validateQueryComplexity(ast: QastNode, options: ComplexityOptions): void`
-
-Validate an AST against complexity limits.
-
-**Parameters:**
-- `ast` - The AST to validate
-- `options` - Complexity options:
-  - `maxDepth?: number` - Maximum allowed AST depth
-  - `maxNodes?: number` - Maximum allowed number of nodes
-  - `maxArrayLength?: number` - Maximum allowed array length
-  - `maxStringLength?: number` - Maximum allowed string length
-
-**Throws:** `ValidationError` if any limit is exceeded
-
-**Example:**
-```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,
-});
-```
-
-## Security Best Practices
-
-1. **Always use whitelists**: Restrict which fields and operators can be used in queries.
-
-```typescript
-const ast = parseQuery(req.query.filter, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt'],
-  validate: true,
-});
-```
-
-2. **Validate user input**: Don't trust user-provided query strings without validation.
-
-3. **Limit query complexity**: Use complexity limits to prevent DoS attacks.
-
-```typescript
-const ast = parseQuery(req.query.filter, {
-  allowedFields: ['age', 'name', 'city'],
-  allowedOperators: ['gt', 'eq', 'lt', 'in'],
-  validate: true,
-  // Complexity limits
-  maxQueryLength: 1000,  // Reject queries longer than 1000 chars
-  maxDepth: 5,           // Max 5 levels of nesting
-  maxNodes: 20,          // Max 20 conditions
-  maxArrayLength: 100,   // Max 100 items in 'in' arrays
-  maxStringLength: 200,  // Max 200 chars per string value
-});
-```
-
-4. **Use type checking**: Ensure values match expected types for fields.
-
-## Error Handling
-
-QAST provides custom error classes:
-
-- `ParseError` - Syntax errors in query strings
-- `ValidationError` - Validation failures (disallowed fields/operators)
-- `TokenizationError` - Tokenization errors
-
-```typescript
-import { parseQuery, ParseError, ValidationError } from 'qast';
-
-try {
-  const ast = parseQuery(query, { allowedFields: ['age'], validate: true });
-} catch (error) {
-  if (error instanceof ParseError) {
-    console.error('Parse error:', error.message);
-  } else if (error instanceof ValidationError) {
-    console.error('Validation error:', error.message);
-    console.error('Field:', error.field);
-    console.error('Operator:', error.operator);
-  }
-}
-```
-
-## TypeScript Support
-
-QAST is written in TypeScript and provides full type definitions:
-
-```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);
-  }
-}
-```
-
-## Examples
-
-### REST API Endpoint
-
-```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;
-    
-    // Parse and validate query
-    const ast = parseQuery(query, {
-      allowedFields: ['age', 'name', 'city', 'active'],
-      allowedOperators: ['gt', 'lt', 'eq', 'in'],
-      validate: true,
-    });
-    
-    // Transform to Prisma filter
-    const filter = toPrismaFilter(ast);
-    
-    // Query database
-    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: 'Internal server error' });
-    }
-  }
-});
-```
-
-### Express Middleware
-
-```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);
-      }
-    }
-  };
-}
-```
-
-## Comparison with Alternatives
-
-### Why QAST?
-
-| Feature | QAST | GraphQL | OData | Custom Parsers |
-|---------|------|---------|-------|----------------|
-| **Type Safety** | ✅ Full TypeScript | ❌ Runtime only | ⚠️ Partial | ❌ Usually none |
-| **Security** | ✅ Whitelist validation | ✅ Built-in | ✅ Built-in | ⚠️ Manual |
-| **ORM Agnostic** | ✅ Yes | ❌ No | ❌ No | ⚠️ Varies |
-| **Zero Dependencies** | ✅ Yes | ❌ No | ❌ No | ⚠️ Varies |
-| **Learning Curve** | ✅ Simple | ❌ Complex | ❌ Complex | ⚠️ Varies |
-| **REST API Friendly** | ✅ Yes | ❌ Requires GraphQL endpoint | ✅ Yes | ⚠️ Varies |
-| **Bundle Size** | ✅ < 10KB | ❌ Large | ❌ Large | ⚠️ Varies |
-
-**Use QAST when:**
-- You want a simple, secure query language for REST APIs
-- You need type-safe query parsing with TypeScript
-- You're using Prisma, TypeORM, or Sequelize
-- You want zero dependencies and a small bundle size
-- You need field and operator whitelisting for security
-
-**Consider alternatives when:**
-- You need GraphQL's full query capabilities
-- You require standardized query protocols (OData)
-- You have complex nested data relationships
-
-## Examples
-
-See the [`examples`](./examples) directory for complete, working examples:
-
-- [Express.js REST API](./examples/express) - Full Express.js server with Prisma
-- [Next.js API Routes](./examples/nextjs) - Next.js API routes with QAST
-- [NestJS Integration](./examples/nestjs) - NestJS controller with query filtering
-- [Interactive Playground](./examples/playground.html) - Try QAST queries in your browser (demo)
-
-## License
-
-MIT © 2025
-
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
-
-- GitHub Repository: https://github.com/hocestnonsatis/qast
-- Issues: https://github.com/hocestnonsatis/qast/issues
-
-## Acknowledgments
-
-QAST is inspired by the need for safe, type-safe query parsing in REST APIs. It aims to provide a lightweight alternative to complex query protocols while maintaining security and developer experience.
+# QAST — Query to AST to 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** is a small, ORM-agnostic library that parses human-readable query strings (e.g. `age gt 25 and (name eq "John" or city eq "Paris")`) into an **Abstract Syntax Tree (AST)** and then transforms that AST into **ORM-compatible filter objects** such as Prisma or TypeORM filters.
+
+It aims to provide a secure, declarative, and type-safe way to support advanced filtering in REST APIs — without falling into the pitfalls of raw string-based query patterns.
+
+## Features
+
+- 🔒 **Safe**: Validates operators, values, and fields against whitelists
+- 🎯 **Type-Safe**: Full TypeScript support for parsed ASTs and generated filters
+- 🔌 **ORM-Agnostic**: Works with Prisma, TypeORM, Sequelize, and more via adapters
+- 📝 **Simple Syntax**: Natural query expressions using logical operators
+- 🚀 **Lightweight**: No dependencies, small bundle size
+
+## Installation
+
+```bash
+npm install qast
+```
+
+## Quick Start
+
+### Basic Usage
+
+```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);
+```
+
+### With Validation
+
+```typescript
+import { parseQuery, toPrismaFilter } from 'qast';
+
+const query = 'age gt 25 and name eq "John"';
+
+// Parse with whitelist validation
+const ast = parseQuery(query, {
+  allowedFields: ['age', 'name', 'city'],
+  allowedOperators: ['gt', 'eq', 'lt'],
+  validate: true,
+});
+
+const prismaFilter = toPrismaFilter(ast);
+await prisma.user.findMany(prismaFilter);
+```
+
+## Query Syntax
+
+### Operators
+
+QAST supports the following comparison operators:
+
+- `eq` - Equal
+- `ne` - Not equal
+- `gt` - Greater than
+- `lt` - Less than
+- `gte` - Greater than or equal
+- `lte` - Less than or equal
+- `in` - In array
+- `notIn` - Not in array
+- `contains` - Contains substring (string matching)
+- `startsWith` - String starts with pattern
+- `endsWith` - String ends with pattern
+- `like` - Pattern matching with wildcards (`%` and `_`)
+- `regex` / `matches` - Regex pattern matching
+- `between` - Range check: `age between 18 and 65`
+- `isNull` - Null check: `email isNull`
+- `isNotNull` - Not null check: `email isNotNull`
+
+### Logical Operators
+
+- `and` - Logical AND
+- `or` - Logical OR
+- `not` - Logical NOT: `not (age gt 25)`
+
+### Query Clauses
+
+- **Sorting**: `orderBy age desc, name asc` - Sort by multiple fields
+- **Pagination**: `limit 10 offset 20` - Limit and offset results
+- **Nested fields**: `user.profile.name eq "John"` - Access nested fields with dot notation
+
+### Values
+
+- **Strings**: Use single or double quotes: `"John"` or `'John'`
+- **Numbers**: Integers or floats: `25`, `25.99`, `-10`
+- **Booleans**: `true` or `false`
+- **Null**: `null` - For null checks
+- **Arrays**: For `in` and `notIn` operators: `[1,2,3]` or `["John","Jane"]`
+
+### Examples
+
+```typescript
+// Simple comparison
+'age gt 25'
+
+// String comparison
+'name eq "John"'
+
+// Boolean comparison
+'active eq true'
+
+// Array (in operator)
+'age in [1,2,3]'
+
+// AND operation
+'age gt 25 and name eq "John"'
+
+// OR operation
+'name eq "John" or name eq "Jane"'
+
+// Nested parentheses
+'age gt 25 and (name eq "John" or city eq "Paris")'
+
+// Complex query
+'age gt 25 and (name eq "John" or city eq "Paris") and active eq true'
+
+// New operators
+'age between 18 and 65'
+'age notIn [1,2,3]'
+'name like "John%"'
+'email matches "^[a-z]+@example\.com$"'
+'email isNull'
+'email isNotNull'
+'not (age gt 25)'
+
+// Sorting and pagination
+'age gt 25 orderBy age desc limit 10 offset 20'
+'name eq "John" orderBy name asc, age desc limit 5'
+```
+
+## ORM Adapters
+
+### 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);
+
+// Note: TypeORM requires operator functions for non-equality comparisons
+// The adapter returns a structure that you can transform using TypeORM operators
+// For equality, TypeORM accepts plain values directly
+
+// filter.where = {
+//   age: { __qast_operator__: 'gt', value: 25 },
+//   name: "John"
+// }
+
+// Transform to use TypeORM operators:
+// const transformed = {
+//   age: MoreThan(25),
+//   name: "John"
+// }
+
+await userRepository.find({ where: transformed });
+```
+
+**Note**: TypeORM requires operator functions (`MoreThan`, `LessThan`, etc.) for non-equality comparisons. The adapter returns a structure with metadata that you can transform. For equality comparisons, TypeORM accepts plain values.
+
+### 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' }
+//   ]
+// }
+
+// Transform to use Sequelize Op operators:
+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 });
+```
+
+**Note**: Sequelize uses the `Op` object from 'sequelize'. Since Sequelize is an optional peer dependency, the adapter returns a structure with metadata (`__qast_operator__` and `__qast_logical__`) that you need to transform to use `Op` operators. For simple equality (`eq`), the adapter returns plain values which Sequelize accepts directly.
+
+### Mongoose
+
+```typescript
+import { parseQueryFull, toMongooseFilter } from 'qast';
+
+const query = 'age gt 25 orderBy age desc limit 10';
+const queryAST = parseQueryFull(query);
+const filter = toMongooseFilter(queryAST);
+
+// filter = {
+//   filter: { age: { $gt: 25 } },
+//   sort: { age: -1 },
+//   limit: 10
+// }
+
+await User.find(filter.filter)
+  .sort(filter.sort)
+  .limit(filter.limit);
+```
+
+### Knex.js
+
+```typescript
+import { parseQueryFull, toKnexFilter } from 'qast';
+
+const query = 'age gt 25 orderBy age desc limit 10';
+const queryAST = parseQueryFull(query);
+const filter = toKnexFilter(queryAST);
+
+// Use with Knex query builder
+knex('users')
+  .where(filter.whereCallback)
+  .orderBy(filter.orderBy!)
+  .limit(filter.limit!)
+  .offset(filter.offset);
+```
+
+### Drizzle ORM
+
+```typescript
+import { parseQueryFull, toDrizzleFilter, transformDrizzleConditions } from 'qast';
+import { and, gt, eq, desc } from 'drizzle-orm';
+
+const query = 'age gt 25 and name eq "John"';
+const queryAST = parseQueryFull(query);
+const filter = toDrizzleFilter(queryAST);
+
+// Transform to Drizzle conditions
+const columnMap = { age: users.age, name: users.name };
+const where = transformDrizzleConditions(filter.where, { and, gt, eq }, columnMap);
+
+await db.select().from(users).where(where);
+```
+
+## Query Builder API
+
+Build queries programmatically using a fluent API:
+
+```typescript
+import { queryBuilder } from 'qast';
+
+const query = queryBuilder()
+  .field('age').gt(25)
+  .and(queryBuilder().field('name').eq('John'))
+  .orderBy('age', 'desc')
+  .limit(10)
+  .offset(20)
+  .build();
+
+// query.filter - the filter AST
+// query.orderBy - sorting specifications
+// query.limit - limit value
+// query.offset - offset value
+```
+
+## AST Serialization
+
+Convert AST back to query string:
+
+```typescript
+import { parseQuery, serializeQuery } from 'qast';
+
+const query = 'age gt 25 and name eq "John"';
+const ast = parseQuery(query);
+const serialized = serializeQuery(ast);
+// serialized = 'age gt 25 and name eq "John"'
+```
+
+## AST Utilities
+
+### Clone AST
+
+```typescript
+import { parseQuery, cloneAST } from 'qast';
+
+const ast = parseQuery('age gt 25');
+const cloned = cloneAST(ast);
+```
+
+### Merge Queries
+
+```typescript
+import { parseQuery, mergeQueries } from 'qast';
+
+const query1 = parseQuery('age gt 25');
+const query2 = parseQuery('name eq "John"');
+const merged = mergeQueries(query1, query2, 'AND');
+```
+
+### Get Query Statistics
+
+```typescript
+import { parseQuery, getQueryStats } from 'qast';
+
+const ast = parseQuery('age gt 25 and name eq "John"');
+const stats = getQueryStats(ast);
+// stats.depth, stats.nodeCount, stats.fields, etc.
+```
+
+### Optimize AST
+
+```typescript
+import { parseQuery, optimizeAST } from 'qast';
+
+const ast = parseQuery('age gt 25 and age gt 25'); // Redundant
+const optimized = optimizeAST(ast);
+```
+
+### Compare Queries
+
+```typescript
+import { parseQuery, diffQueries } from 'qast';
+
+const query1 = parseQuery('age gt 25');
+const query2 = parseQuery('age gt 30');
+const diff = diffQueries(query1, query2);
+```
+
+## Performance Features
+
+### Query Caching
+
+```typescript
+import { QueryCache, createCachedParser, parseQuery } from 'qast';
+
+// Create a cached parser
+const cachedParse = createCachedParser(parseQuery, 100, 60000); // 100 items, 60s TTL
+
+// Use cached parser
+const ast = cachedParse('age gt 25'); // Cached on subsequent calls
+```
+
+## Security Features
+
+### Field Sanitization
+
+```typescript
+import { sanitizeFieldName } from 'qast';
+
+const safeField = sanitizeFieldName('user.name'); // Removes dangerous characters
+```
+
+### Query Cost Estimation
+
+```typescript
+import { parseQuery, estimateQueryCost } from 'qast';
+
+const ast = parseQuery('age gt 25 and name eq "John"');
+const cost = estimateQueryCost(ast);
+// cost.estimatedComplexity, cost.depth, cost.nodeCount, etc.
+```
+
+### Rate Limiting
+
+```typescript
+import { RateLimiter } from 'qast';
+
+const limiter = new RateLimiter(100, 60000); // 100 requests per 60 seconds
+
+if (limiter.isAllowed(userId)) {
+  // Process query
+} else {
+  // Rate limit exceeded
+}
+```
+
+## API Reference
+
+### `parseQuery(query: string, options?: ParseOptions): QastNode`
+
+Parse a query string into an AST.
+
+**Parameters:**
+- `query` - The query string to parse
+- `options` - Optional parsing options:
+  - `allowedFields?: string[]` - Whitelist of allowed field names
+  - `allowedOperators?: Operator[]` - Whitelist of allowed operators
+  - `validate?: boolean` - Whether to validate against whitelists (default: true if whitelists are provided)
+  - `maxDepth?: number` - Maximum allowed AST depth (to limit nested logical expressions)
+  - `maxNodes?: number` - Maximum allowed number of AST nodes (to limit overall query complexity)
+  - `maxQueryLength?: number` - Maximum allowed length of the raw query string (checked before parsing)
+  - `maxArrayLength?: number` - Maximum allowed length of array values (for `in` operator)
+  - `maxStringLength?: number` - Maximum allowed length of string values
+
+**Returns:** The parsed AST node
+
+**Example:**
+```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`
+
+Transform an AST to a Prisma filter.
+
+**Returns:** Prisma filter object with `where` property
+
+### `toTypeORMFilter(ast: QastNode): TypeORMFilter`
+
+Transform an AST to a TypeORM filter.
+
+**Returns:** TypeORM filter object with `where` property
+
+**Note:** TypeORM requires operator functions for non-equality comparisons. You may need to transform the result.
+
+### `parseQueryFull(query: string, options?: ParseOptions): QueryAST`
+
+Parse a query string into a full QueryAST (includes filter, sorting, pagination).
+
+**Returns:** QueryAST with filter, orderBy, limit, and offset
+
+### `toPrismaFilter(ast: QastNode | QueryAST): PrismaFilter`
+
+Transform an AST or QueryAST to a Prisma filter.
+
+**Returns:** Prisma filter object with `where`, `orderBy`, `take`, and `skip` properties
+
+### `toTypeORMFilter(ast: QastNode | QueryAST): TypeORMFilter`
+
+Transform an AST or QueryAST to a TypeORM filter.
+
+**Returns:** TypeORM filter object with `where`, `order`, `take`, and `skip` properties
+
+**Note:** TypeORM requires operator functions for non-equality comparisons. Use `transformTypeORMOperators()` helper function.
+
+### `toSequelizeFilter(ast: QastNode | QueryAST): SequelizeFilter`
+
+Transform an AST or QueryAST to a Sequelize filter.
+
+**Returns:** Sequelize filter object with `where`, `order`, `limit`, and `offset` properties
+
+**Note:** Sequelize uses the `Op` object. Use `transformSequelizeOperators()` helper function.
+
+### `toMongooseFilter(ast: QastNode | QueryAST): MongooseFilter`
+
+Transform an AST or QueryAST to a Mongoose filter.
+
+**Returns:** Mongoose filter object with `filter`, `sort`, `limit`, and `skip` properties
+
+### `toKnexFilter(ast: QastNode | QueryAST): KnexFilter`
+
+Transform an AST or QueryAST to a Knex filter.
+
+**Returns:** Knex filter object with `whereCallback`, `orderBy`, `limit`, and `offset` properties
+
+### `toDrizzleFilter(ast: QastNode | QueryAST): DrizzleFilter`
+
+Transform an AST or QueryAST to a Drizzle filter.
+
+**Returns:** Drizzle filter object with `where`, `orderBy`, `limit`, and `offset` properties
+
+**Note:** Use `transformDrizzleConditions()` helper function to convert to actual Drizzle conditions.
+
+### `validateQuery(ast: QastNode, whitelist: WhitelistOptions): void`
+
+Validate an AST against whitelists.
+
+**Parameters:**
+- `ast` - The AST to validate
+- `whitelist` - Whitelist options:
+  - `allowedFields?: string[]` - Allowed field names
+  - `allowedOperators?: Operator[]` - Allowed operators
+
+**Throws:** `ValidationError` if validation fails
+
+### `extractFields(ast: QastNode): string[]`
+
+Extract all field names used in an AST.
+
+**Returns:** Array of unique field names
+
+### `extractOperators(ast: QastNode): Operator[]`
+
+Extract all operators used in an AST.
+
+**Returns:** Array of unique operators
+
+### `validateQueryComplexity(ast: QastNode, options: ComplexityOptions): void`
+
+Validate an AST against complexity limits.
+
+**Parameters:**
+- `ast` - The AST to validate
+- `options` - Complexity options:
+  - `maxDepth?: number` - Maximum allowed AST depth
+  - `maxNodes?: number` - Maximum allowed number of nodes
+  - `maxArrayLength?: number` - Maximum allowed array length
+  - `maxStringLength?: number` - Maximum allowed string length
+
+**Throws:** `ValidationError` if any limit is exceeded
+
+**Example:**
+```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,
+});
+```
+
+## Security Best Practices
+
+1. **Always use whitelists**: Restrict which fields and operators can be used in queries.
+
+```typescript
+const ast = parseQuery(req.query.filter, {
+  allowedFields: ['age', 'name', 'city'],
+  allowedOperators: ['gt', 'eq', 'lt'],
+  validate: true,
+});
+```
+
+2. **Validate user input**: Don't trust user-provided query strings without validation.
+
+3. **Limit query complexity**: Use complexity limits to prevent DoS attacks.
+
+```typescript
+const ast = parseQuery(req.query.filter, {
+  allowedFields: ['age', 'name', 'city'],
+  allowedOperators: ['gt', 'eq', 'lt', 'in'],
+  validate: true,
+  // Complexity limits
+  maxQueryLength: 1000,  // Reject queries longer than 1000 chars
+  maxDepth: 5,           // Max 5 levels of nesting
+  maxNodes: 20,          // Max 20 conditions
+  maxArrayLength: 100,   // Max 100 items in 'in' arrays
+  maxStringLength: 200,  // Max 200 chars per string value
+});
+```
+
+4. **Use type checking**: Ensure values match expected types for fields.
+
+## Error Handling
+
+QAST provides custom error classes:
+
+- `ParseError` - Syntax errors in query strings
+- `ValidationError` - Validation failures (disallowed fields/operators)
+- `TokenizationError` - Tokenization errors
+
+```typescript
+import { parseQuery, ParseError, ValidationError } from 'qast';
+
+try {
+  const ast = parseQuery(query, { allowedFields: ['age'], validate: true });
+} catch (error) {
+  if (error instanceof ParseError) {
+    console.error('Parse error:', error.message);
+  } else if (error instanceof ValidationError) {
+    console.error('Validation error:', error.message);
+    console.error('Field:', error.field);
+    console.error('Operator:', error.operator);
+  }
+}
+```
+
+## TypeScript Support
+
+QAST is written in TypeScript and provides full type definitions:
+
+```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);
+  }
+}
+```
+
+## Examples
+
+### REST API endpoint
+
+```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;
+    
+    // Parse and validate query
+    const ast = parseQuery(query, {
+      allowedFields: ['age', 'name', 'city', 'active'],
+      allowedOperators: ['gt', 'lt', 'eq', 'in'],
+      validate: true,
+    });
+    
+    // Transform to Prisma filter
+    const filter = toPrismaFilter(ast);
+    
+    // Query database
+    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: 'Internal server error' });
+    }
+  }
+});
+```
+
+### Express middleware
+
+```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);
+      }
+    }
+  };
+}
+```
+
+## Comparison with Alternatives
+
+### Why QAST?
+
+| Feature | QAST | GraphQL | OData | Custom Parsers |
+|---------|------|---------|-------|----------------|
+| **Type Safety** | ✅ Full TypeScript | ❌ Runtime only | ⚠️ Partial | ❌ Usually none |
+| **Security** | ✅ Whitelist validation | ✅ Built-in | ✅ Built-in | ⚠️ Manual |
+| **ORM Agnostic** | ✅ Yes | ❌ No | ❌ No | ⚠️ Varies |
+| **Zero Dependencies** | ✅ Yes | ❌ No | ❌ No | ⚠️ Varies |
+| **Learning Curve** | ✅ Simple | ❌ Complex | ❌ Complex | ⚠️ Varies |
+| **REST API Friendly** | ✅ Yes | ❌ Requires GraphQL endpoint | ✅ Yes | ⚠️ Varies |
+| **Bundle Size** | ✅ < 10KB | ❌ Large | ❌ Large | ⚠️ Varies |
+
+**Use QAST when:**
+- You want a simple, secure query language for REST APIs
+- You need type-safe query parsing with TypeScript
+- You're using Prisma, TypeORM, or Sequelize
+- You want zero dependencies and a small bundle size
+- You need field and operator whitelisting for security
+
+**Consider alternatives when:**
+- You need GraphQL's full query capabilities
+- You require standardized query protocols (OData)
+- You have complex nested data relationships
+
+### Example Projects
+
+See the [`examples`](./examples) directory for complete, working examples:
+
+- [Express.js REST API](./examples/express) — Full Express.js server with Prisma
+- [Next.js API Routes](./examples/nextjs) — Next.js API routes with QAST
+- [NestJS Integration](./examples/nestjs) — NestJS controller with query filtering
+- [Interactive Playground](./examples/playground.html) — Try QAST queries in your browser
+
+## License
+
+MIT © 2025
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+- GitHub Repository: https://github.com/hocestnonsatis/qast
+- Issues: https://github.com/hocestnonsatis/qast/issues
+
+## Acknowledgments
+
+QAST is inspired by the need for safe, type-safe query parsing in REST APIs. It aims to provide a lightweight alternative to complex query protocols while maintaining security and developer experience.