qast 1.2.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`
@@ -268,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.
+
+**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 to a Sequelize filter.
+Transform an AST or QueryAST to a Drizzle filter.
 
-**Returns:** Sequelize filter object
+**Returns:** Drizzle filter object with `where`, `orderBy`, `limit`, and `offset` properties
 
-**Note:** Sequelize uses the `Op` object. You need to transform `$`-prefixed operators to use `Op` operators.
+**Note:** Use `transformDrizzleConditions()` helper function to convert to actual Drizzle conditions.
 
 ### `validateQuery(ast: QastNode, whitelist: WhitelistOptions): void`