@webda/ql 4.0.0-beta.5 → 4.0.0-beta.6

package/README.md

@@ -23,14 +23,10 @@ You need WQL when you call `store.query()` or a relation's `.query()` method. Ev
 
 ```typescript
 // Query the User repository
-const { results } = await User.getRepository().query(
-  `email = 'alice@example.com' LIMIT 1`
-);
+const { results } = await User.getRepository().query(`email = 'alice@example.com' LIMIT 1`);
 
 // Query a relation
-const { results: posts } = await user.posts.query(
-  `status = 'published' ORDER BY createdAt DESC LIMIT 10`
-);
+const { results: posts } = await user.posts.query(`status = 'published' ORDER BY createdAt DESC LIMIT 10`);
 ```
 
 ### Install
@@ -44,10 +40,19 @@ npm install @webda/ql
 ### Syntax overview
 
 ```
-expression? orderExpression? limitExpression? offsetExpression?
+expression? orderExpression? limitExpression? offsetExpression?      -- a filter query (implicit SELECT)
+SELECT f1, f2 [WHERE expression] [ORDER BY ...] [LIMIT n] [OFFSET t]
+SELECT g, COUNT(*) AS n, SUM(f) AS s [WHERE expression] [GROUP BY g] [ORDER BY ...] [LIMIT n]
+DELETE [WHERE expression] [LIMIT n]
+UPDATE SET a = v, b.c = v [WHERE expression] [LIMIT n]
 ```
 
+Keywords are uppercase only: `select`, `delete`, `set`, `where`... in lowercase are field names. Since the
+aggregation syntax, uppercase `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `AS`, `DISTINCT` and `GROUP BY` are reserved too
+(breaking for attributes with those uppercase names).
+
 **Filter expressions** support:
+
 - Comparison: `field = value`, `field != value`, `field > value`, `field >= value`, `field < value`, `field <= value`
 - Pattern match: `field LIKE "pattern"` (`_` = single char, `%` = any chars)
 - Set membership: `field IN [value, value, ...]`
@@ -56,6 +61,7 @@ expression? orderExpression? limitExpression? offsetExpression?
 - Logic: `AND`, `OR`, `( ... )`
 
 **Pagination / ordering:**
+
 - `ORDER BY field [ASC|DESC], ...`
 - `LIMIT <integer>`
 - `OFFSET "<continuationToken>"`
@@ -66,17 +72,12 @@ expression? orderExpression? limitExpression? offsetExpression?
 import * as WebdaQL from "@webda/ql";
 
 // Parse and evaluate against an in-memory object
-const validator = new WebdaQL.QueryValidator(
-  `status = 'published' AND viewCount >= 100`
-);
+const validator = new WebdaQL.QueryValidator(`status = 'published' AND viewCount >= 100`);
 const post = { status: "published", viewCount: 150 };
 console.log(validator.eval(post)); // true
 
 // Prepend a mandatory condition to a user-supplied query
-const merged = WebdaQL.PrependCondition(
-  `status = 'published' ORDER BY title LIMIT 10`,
-  `authorId = 'u-123'`
-);
+const merged = WebdaQL.PrependCondition(`status = 'published' ORDER BY title LIMIT 10`, `authorId = 'u-123'`);
 // => 'status = "published" AND authorId = "u-123" ORDER BY title ASC LIMIT 10'
 ```
 
@@ -93,30 +94,70 @@ WebdaQL.bind("priority >= ? LIMIT ?", [2, 10]); // priority >= 2 LIMIT 10
 
 Placeholders are only allowed where a value is expected, values are escaped by type, and `= ?` / `!= ?` with `null` become `IS NULL` / `IS NOT NULL`. Template literals passed straight to a query method are escaped the same way at compile time by `webdac`. See [Parameters](../../docs/pages/Modules/ql/Parameters.md).
 
+### Statements: SELECT, DELETE, UPDATE
+
+WebdaQL parses `SELECT`, `DELETE` and `UPDATE` statements; the parsed `Query` carries `type` (`"SELECT"` for a plain filter), `fields` (SELECT) and `assignments` (UPDATE), and `toString()` round-trips them.
+
+- **Field lists are parse-level only**: the Query operations (REST, gRPC, MCP, GraphQL) refuse a `SELECT` field list with a 400, and repositories refuse it in `query()`.
+- **DELETE and UPDATE are repository-level operations**: `useRepository(Model).deleteMany("DELETE WHERE ...")` and `updateMany("UPDATE SET ... WHERE ...")` run them in bulk and return the affected count. They **bypass events, hooks, validation and `canAct`**. The Query operations refuse them with a 400, and `query()` / `iterate()` refuse them.
+
+```typescript
+const q = WebdaQL.parse("UPDATE SET status = 'archived' WHERE owner = 'bob' LIMIT 10");
+q.type; // "UPDATE"
+q.assignments; // [{ field: "status", value: "archived" }]
+await useRepository(Task).updateMany("UPDATE SET status = ? WHERE owner = ?", ["archived", "bob"]); // count
+```
+
+See [Statements](../../docs/pages/Modules/ql/Statements.md).
+
+### Aggregations
+
+A `SELECT` with aggregate functions or `GROUP BY` parses into an `AggregationQuery` (`parse(q).aggregation`), the
+same AST `toAggregationQuery()` builds from the object form used by `Model.aggregate()`. Stores translate it
+natively, or stream objects through the in-memory `Aggregator`.
+
+```typescript
+const q = WebdaQL.parse("SELECT status, COUNT(*) AS n, SUM(points) AS total GROUP BY status ORDER BY total DESC");
+q.aggregation.metrics; // { n: { fn: "COUNT" }, total: { fn: "SUM", field: "points" } }
+```
+
+See [Statements](../../docs/pages/Modules/ql/Statements.md#aggregation-select--group-by) and
+[Repositories](../../docs/pages/Concepts/Stores/Repositories.md#aggregation).
+
 ### API reference
 
-| Export | Description |
-|--------|-------------|
-| `QueryValidator` | Parses a WQL string; `eval(obj)` evaluates it, `toString()` normalizes it |
-| `bind(query, params)` | Binds `?` / `:name` placeholders to escaped values |
-| `escape(parts, values)` | Escapes template literal values (used by the compile-time rewrite) |
-| `validateSyntax(query)` | Checks a query against the grammar without evaluating it; placeholders allowed |
-| `PrependCondition(query, condition)` | Merges a condition in front of an existing query, preserving ORDER BY / LIMIT / OFFSET |
-| `ExpressionBuilder` | ANTLR visitor that builds the optimized expression AST |
-| `AndExpression` | Logic AND node |
-| `OrExpression` | Logic OR node |
-| `ComparisonExpression` | Comparison leaf node |
-| `Query` | Parsed query result: `{ filter, orderBy?, limit?, continuationToken? }` |
-| `OrderBy` | `{ field: string; direction: "ASC" \| "DESC" }` |
+| Export                                | Description                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `QueryValidator`                      | Parses a WQL string; `eval(obj)` evaluates it, `toString()` normalizes it                                          |
+| `bind(query, params)`                 | Binds `?` / `:name` placeholders to escaped values                                                                 |
+| `escape(parts, values)`               | Escapes template literal values (used by the compile-time rewrite)                                                 |
+| `validateSyntax(query)`               | Checks a query against the grammar without evaluating it; placeholders allowed                                     |
+| `PrependCondition(query, condition)`  | Merges a condition in front of an existing query, preserving ORDER BY / LIMIT / OFFSET                             |
+| `ExpressionBuilder`                   | ANTLR visitor that builds the optimized expression AST                                                             |
+| `AndExpression`                       | Logic AND node                                                                                                     |
+| `OrExpression`                        | Logic OR node                                                                                                      |
+| `ComparisonExpression`                | Comparison leaf node                                                                                               |
+| `parse(query, allowedFields?)`        | Parses a filter or statement; `allowedFields` checks SELECT fields and SET targets                                 |
+| `validateQueryFields(query, allowed)` | Checks SELECT fields and SET targets against a field list                                                          |
+| `assertFilterQuery(query)`            | Refuses DELETE, UPDATE, SELECT field lists and aggregations                                                        |
+| `toAggregationQuery(input, params?)`  | Converts the object form of an aggregation to a validated `AggregationQuery`                                       |
+| `validateAggregation(query)`          | Validates an `AggregationQuery` (paths, aliases, functions, ORDER BY, LIMIT)                                       |
+| `Aggregator`                          | In-memory aggregation engine: `add(item)` then `rows()`                                                            |
+| `compareValues(a, b)`                 | The cross-backend ordering of aggregated values (null < numbers < strings)                                         |
+| `AggregationError`                    | Runtime aggregation error with a `code` (`AGGREGATION_NOT_NATIVE`, `AGGREGATION_TOO_MANY_GROUPS`)                  |
+| `Query`                               | Parsed query result: `{ type, filter, fields?, assignments?, aggregation?, orderBy?, limit?, continuationToken? }` |
+| `OrderBy`                             | `{ field: string; direction: "ASC" \| "DESC" }`                                                                    |
 
 ### See also
 
 - [WQL Syntax reference](../../docs/pages/Modules/ql/Syntax.md)
 - [Operators](../../docs/pages/Modules/ql/Operators.md)
 - [Parameters](../../docs/pages/Modules/ql/Parameters.md) — binding values safely
+- [Statements](../../docs/pages/Modules/ql/Statements.md) — SELECT, DELETE, UPDATE and repository bulk operations
 - [Store Translators](../../docs/pages/Modules/ql/Translators.md) — how each Store backend converts WQL
 
 <!-- README_FOOTER -->
+
 ## Sponsors
 
 <!--

package/lib/WebdaQLLexer.d.ts

@@ -11,36 +11,50 @@ export declare class WebdaQLLexer extends Lexer {
     static readonly DOUBLE_QUOTE_SYMB = 6;
     static readonly LR_SQ_BRACKET = 7;
     static readonly RR_SQ_BRACKET = 8;
-    static readonly AND = 9;
-    static readonly OR = 10;
-    static readonly EQUAL = 11;
-    static readonly NOT_EQUAL = 12;
-    static readonly GREATER = 13;
-    static readonly GREATER_OR_EQUAL = 14;
-    static readonly LESS = 15;
-    static readonly LESS_OR_EQUAL = 16;
-    static readonly LIKE = 17;
-    static readonly IN = 18;
-    static readonly CONTAINS = 19;
-    static readonly IS = 20;
-    static readonly NOT = 21;
-    static readonly NULL = 22;
-    static readonly TRUE = 23;
-    static readonly FALSE = 24;
-    static readonly LIMIT = 25;
-    static readonly OFFSET = 26;
-    static readonly ORDER_BY = 27;
-    static readonly ASC = 28;
-    static readonly DESC = 29;
-    static readonly DQUOTED_STRING_LITERAL = 30;
-    static readonly SQUOTED_STRING_LITERAL = 31;
-    static readonly INTEGER_LITERAL = 32;
-    static readonly NUMBER_LITERAL = 33;
-    static readonly POSITIONAL_PARAMETER = 34;
-    static readonly NAMED_PARAMETER = 35;
-    static readonly IDENTIFIER = 36;
-    static readonly IDENTIFIER_WITH_NUMBER = 37;
-    static readonly FUNCTION_IDENTIFIER_WITH_UNDERSCORE = 38;
+    static readonly DELETE = 9;
+    static readonly UPDATE = 10;
+    static readonly SELECT = 11;
+    static readonly SET = 12;
+    static readonly WHERE = 13;
+    static readonly AND = 14;
+    static readonly OR = 15;
+    static readonly EQUAL = 16;
+    static readonly NOT_EQUAL = 17;
+    static readonly GREATER = 18;
+    static readonly GREATER_OR_EQUAL = 19;
+    static readonly LESS = 20;
+    static readonly LESS_OR_EQUAL = 21;
+    static readonly LIKE = 22;
+    static readonly IN = 23;
+    static readonly CONTAINS = 24;
+    static readonly IS = 25;
+    static readonly NOT = 26;
+    static readonly NULL = 27;
+    static readonly TRUE = 28;
+    static readonly FALSE = 29;
+    static readonly LIMIT = 30;
+    static readonly OFFSET = 31;
+    static readonly ORDER_BY = 32;
+    static readonly ASC = 33;
+    static readonly DESC = 34;
+    static readonly GROUP_BY = 35;
+    static readonly AS = 36;
+    static readonly DISTINCT = 37;
+    static readonly COUNT = 38;
+    static readonly SUM = 39;
+    static readonly AVG = 40;
+    static readonly MIN = 41;
+    static readonly MAX = 42;
+    static readonly STAR = 43;
+    static readonly DQUOTED_STRING_LITERAL = 44;
+    static readonly SQUOTED_STRING_LITERAL = 45;
+    static readonly INTEGER_LITERAL = 46;
+    static readonly NUMBER_LITERAL = 47;
+    static readonly POSITIONAL_PARAMETER = 48;
+    static readonly NAMED_PARAMETER = 49;
+    static readonly IDENTIFIER = 50;
+    static readonly IDENTIFIER_WITH_NUMBER = 51;
+    static readonly FUNCTION_IDENTIFIER_WITH_UNDERSCORE = 52;
     static readonly channelNames: string[];
     static readonly modeNames: string[];
     static readonly ruleNames: string[];

package/lib/WebdaQLLexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebdaQLLexer.d.ts","sourceRoot":"","sources":["../src/WebdaQLLexer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAK1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKpD,qBAAa,YAAa,SAAQ,KAAK;IACrC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,GAAG,KAAK;IAC/B,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,SAAS,MAAM;IACtC,gBAAuB,OAAO,MAAM;IACpC,gBAAuB,gBAAgB,MAAM;IAC7C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,aAAa,MAAM;IAC1C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,cAAc,MAAM;IAC3C,gBAAuB,oBAAoB,MAAM;IACjD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,UAAU,MAAM;IACvC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,mCAAmC,MAAM;IAGhE,gBAAuB,YAAY,EAAE,MAAM,EAAE,CAAuC;IAGpF,gBAAuB,SAAS,EAAE,MAAM,EAAE,CAAoB;IAE9D,gBAAuB,SAAS,EAAE,MAAM,EAAE,CA6CxC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAoCpC;IACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAwCrC;IACF,gBAAuB,UAAU,EAAE,UAAU,CAI3C;IAIF,IAAW,UAAU,IAAI,UAAU,CAElC;IAGD,YAAY,KAAK,EAAE,UAAU,EAG5B;IAGD,IAAW,eAAe,IAAI,MAAM,CAEnC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAGD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAGD,IAAW,YAAY,IAAI,MAAM,EAAE,CAElC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAED,gBAAuB,cAAc,EAAE,MAAM,CAuIU;IACvD,OAAc,KAAK,EAAE,GAAG,CAAC;IACzB,WAAkB,IAAI,IAAI,GAAG,CAM5B;CACF"}
+{"version":3,"file":"WebdaQLLexer.d.ts","sourceRoot":"","sources":["../src/WebdaQLLexer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAK1C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKpD,qBAAa,YAAa,SAAQ,KAAK;IACrC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,UAAU,KAAK;IACtC,gBAAuB,KAAK,KAAK;IACjC,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,iBAAiB,KAAK;IAC7C,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,aAAa,KAAK;IACzC,gBAAuB,MAAM,KAAK;IAClC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,SAAS,MAAM;IACtC,gBAAuB,OAAO,MAAM;IACpC,gBAAuB,gBAAgB,MAAM;IAC7C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,aAAa,MAAM;IAC1C,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,MAAM,MAAM;IACnC,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,EAAE,MAAM;IAC/B,gBAAuB,QAAQ,MAAM;IACrC,gBAAuB,KAAK,MAAM;IAClC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,GAAG,MAAM;IAChC,gBAAuB,IAAI,MAAM;IACjC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,cAAc,MAAM;IAC3C,gBAAuB,oBAAoB,MAAM;IACjD,gBAAuB,eAAe,MAAM;IAC5C,gBAAuB,UAAU,MAAM;IACvC,gBAAuB,sBAAsB,MAAM;IACnD,gBAAuB,mCAAmC,MAAM;IAGhE,gBAAuB,YAAY,EAAE,MAAM,EAAE,CAAuC;IAGpF,gBAAuB,SAAS,EAAE,MAAM,EAAE,CAAoB;IAE9D,gBAAuB,SAAS,EAAE,MAAM,EAAE,CA2DxC;IAEF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAkDpC;IACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAsDrC;IACF,gBAAuB,UAAU,EAAE,UAAU,CAI3C;IAIF,IAAW,UAAU,IAAI,UAAU,CAElC;IAGD,YAAY,KAAK,EAAE,UAAU,EAG5B;IAGD,IAAW,eAAe,IAAI,MAAM,CAEnC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAGD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAGD,IAAW,YAAY,IAAI,MAAM,EAAE,CAElC;IAGD,IAAW,SAAS,IAAI,MAAM,EAAE,CAE/B;IAED,gBAAuB,cAAc,EAAE,MAAM,CAwL4B;IACzE,OAAc,KAAK,EAAE,GAAG,CAAC;IACzB,WAAkB,IAAI,IAAI,GAAG,CAM5B;CACF"}