qast 1.1.0 → 2.0.0

package/README.md

@@ -70,19 +70,35 @@ QAST supports the following comparison operators:
 - `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`
-- **Arrays**: For `in` operator: `[1,2,3]` or `["John","Jane"]`
+- **Null**: `null` - For null checks
+- **Arrays**: For `in` and `notIn` operators: `[1,2,3]` or `["John","Jane"]`
 
 ### Examples
 
@@ -110,6 +126,19 @@ QAST supports the following comparison operators:
 
 // 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
@@ -220,6 +249,192 @@ 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`
@@ -232,6 +447,11 @@ Parse a query string into an AST.
   - `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
 
@@ -241,6 +461,11 @@ const ast = parseQuery('age gt 25', {
   allowedFields: ['age', 'name'],
   allowedOperators: ['gt', 'eq'],
   validate: true,
+  maxDepth: 5,
+  maxNodes: 50,
+  maxQueryLength: 1000,
+  maxArrayLength: 100,
+  maxStringLength: 200,
 });
 ```
 
@@ -258,13 +483,53 @@ Transform an AST to a TypeORM filter.
 
 **Note:** TypeORM requires operator functions for non-equality comparisons. You may need to transform the result.
 
-### `toSequelizeFilter(ast: QastNode): SequelizeFilter`
+### `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.
 
-Transform an AST to a Sequelize filter.
+**Returns:** TypeORM filter object with `where`, `order`, `take`, and `skip` properties
 
-**Returns:** Sequelize filter object
+**Note:** TypeORM requires operator functions for non-equality comparisons. Use `transformTypeORMOperators()` helper function.
 
-**Note:** Sequelize uses the `Op` object. You need to transform `$`-prefixed operators to use `Op` operators.
+### `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`
 
@@ -290,6 +555,33 @@ 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.
@@ -304,7 +596,21 @@ const ast = parseQuery(req.query.filter, {
 
 2. **Validate user input**: Don't trust user-provided query strings without validation.
 
-3. **Limit query complexity**: Consider limiting the depth of nested queries to prevent DoS attacks.
+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.