@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/backend/application/src/@aurora/modules/graphql/core.graphql

@@ -44,46 +44,57 @@ enum CoreSearchKeyLang {
 #############
 """
 -----------------------------------------------------------------------------
-# QueryStatement → Query Options (How-To)
+# QueryStatementInput → the Aurora Query DSL (How-To)
 -----------------------------------------------------------------------------
-It explains how to express Sequelize queries through your GraphQL input:
+The Aurora Query DSL is the ORM-neutral wire contract for querying aggregates.
+It replaced the Sequelize-shaped `QueryStatement` (F3 cutover): it is
+isomorphic to Drizzle's Relational Query Builder v2 and carries NO
+ORM-specific keys — no `include`, `attributes`, `literal`, `fn`, or `col`.
 
 ```graphql
-input QueryStatement {
+input QueryStatementInput {
   where: JSON
-  attributes: JSON
-  include: [GraphQLString]
+  relations: JSON
   order: JSON
-  group: JSON
+  aggregation: JSON
   limit: GraphQLInt
   offset: GraphQLInt
-  distinct: GraphQLBoolean
-  col: GraphQLString
 }
 ```
 
 ## GENERAL NOTES
-- **WHERE operators**: Sequelize uses Symbol operators (e.g., `[Op.gte]`) but the API must use _stringified_ keys wrapped in brackets, e.g. `"[gte]"`, `"[or]"`.
-  ```json
-  { "where": { "age": { "[gte]": 18 } } }
-  ```
-- **INCLUDE**: Prefer association names:
-  ```json
-  { "include": [ { "association": "tableToRelate" } ] }
-  ```
-  You can nest includes, add `where`/`attributes`/`required` per-include, etc.
-- **DIALECTS**: Some operators (`iLike`, `regexp`, array containment) are dialect-specific.
+- **Four blocks, each with ONE job**: `where` filters rows (parent rows,
+  including via a relation-key EXISTS check); `relations` shapes which
+  children get loaded and how, WITHOUT touching which parent rows come back;
+  `order` sorts, including by a relation column via dot-path; `aggregation`
+  routes count/sum/avg/min/max/group queries to the core select builder.
+  This is a deliberate split from Sequelize's `include`, which conflated
+  "load this association", "filter parents by it", and "shape the joined
+  rows" into one option bag — the DSL never lets you accidentally do two of
+  those at once.
+- **No raw escape hatch**: there is no `literal`, `fn`, `col`, or raw-SQL key
+  anywhere in the DSL. Every query is validated by a default-deny whitelist
+  walker before translation — an operator or key that is not on the
+  whitelist is rejected before it reaches the database. This closes the
+  injection surface the old `attributes: { literal: ... }` escape hatch
+  opened.
+- **Operator names are Aurora-owned**, not Sequelize Symbol operators: no
+  `[Op.gte]`/`"[gte]"` bracket-stringified keys — a leaf comparison is a
+  plain object, e.g. `{ "age": { "gte": 18 } }`.
 
 # WHERE — Filtering
-Combine field predicates and logical operators.
+A nested filter tree. Each key is either a logical connector (`and`/`or`/
+`not`) or a field/relation name mapped to a leaf comparison (or, for a
+relation name, a nested `where` node evaluated as an EXISTS check against
+that relation).
 
 ### Logical combinations
 ```json
 {
   "where": {
-    "[and]": [
-      { "status": "active" },
-      { "age": { "[gte]": 18 } }
+    "and": [
+      { "status": { "eq": "active" } },
+      { "age": { "gte": 18 } }
     ]
   }
 }
@@ -91,349 +102,283 @@ Combine field predicates and logical operators.
 
 Other forms:
 ```json
-{ "where": { "[or]": [ { "role": "admin" }, { "role": "editor" } ] } }
-{ "where": { "[not]": { "deletedAt": { "[ne]": null } } } }
+{ "where": { "or": [ { "role": { "eq": "admin" } }, { "role": { "eq": "editor" } } ] } }
+{ "where": { "not": { "deletedAt": { "isNull": false } } } }
 ```
 
-Supported: `[and]`, `[or]`, `[not]`.
+Supported: `and`, `or`, `not`.
 
-### Filtering on included associations
-When you use include to join related tables, you can filter on fields of the included association directly from the top-level where using path syntax.
-This requires wrapping the association and field name in $...$.
+### Filtering parents by a relation (EXISTS, not a join)
+A relation key placed inside `where` filters the PARENT rows by an EXISTS on
+that relation — it does NOT shape or load the related rows. To also load
+the relation's data, add it (independently) to the `relations` block below.
 
-Example: filter by a field of an included association:
 ```json
-{
-  "include": [ { "association": "tableToRelate" } ],
-  "where": { "$tableToRelate.name$": "nameToSearch" }
-}
-```
-This will generate a condition on the name column of the tableToRelate join.
-
-### Disambiguating columns with the same name
-If both the root table and the included association contain columns with the same name, you must qualify the column with its table (or alias) inside $...$ to avoid ambiguity.
-
-Example:
-```json
-{
-  "include": [ { "association": "tableToRelate" } ],
-  "where": { "$TableToRelate.name$": "nameToSearch" }
-}
+{ "where": { "role": { "name": { "iLike": "%admin%" } } } }
 ```
-This makes sure the condition applies to the name column of the TableToRelate table instead of the root table.
-
-Conclusion:
-When performing queries with include joins, you can target columns of either the root table or the included tables by wrapping the table/association name and column in $...$.
-Use the association alias defined in the include or the actual table name to fully control filtering across joined tables.
+Only parent rows that have at least one related `role` whose `name` matches
+are returned. This is the DSL's answer to Sequelize's
+`{ "include": [...], "where": { "$role.name$": "..." } }` path-syntax
+join-filter — no `$...$` qualification needed, no ambiguity about which
+table a bare column name belongs to (the relation key already scopes it).
 
 ### Equality & nulls
 ```json
-{ "where": { "id": 123 } }
-{ "where": { "id": { "[eq]": 123 } } }
-{ "where": { "tenantId": { "[ne]": "public" } } }
-{ "where": { "deletedAt": { "[is]": null } } }
+{ "where": { "id": { "eq": 123 } } }
+{ "where": { "tenantId": { "ne": "public" } } }
+{ "where": { "deletedAt": { "isNull": true } } }
 ```
 
-Supported: `[eq]`, `[ne]`, `[is]`.
+Supported: `eq`, `ne`, `isNull`.
 
 ### Comparisons (numbers/dates)
 ```json
-{ "where": { "price": { "[gt]": 10 } } }
-{ "where": { "price": { "[gte]": 10, "[lte]": 100 } } }
-{ "where": { "createdAt": { "[lt]": "2025-01-01T00:00:00Z" } } }
+{ "where": { "price": { "gt": 10 } } }
+{ "where": { "price": { "gte": 10 } } }
+{ "where": { "createdAt": { "lt": "2025-01-01T00:00:00Z" } } }
 ```
 
-Supported: `[gt]`, `[gte]`, `[lt]`, `[lte]`.
+Supported: `gt`, `gte`, `lt`, `lte`.
 
 ### Ranges
 ```json
-{ "where": { "score": { "[between]": [70, 90] } } }
-{ "where": { "score": { "[notBetween]": [0, 10] } } }
+{ "where": { "score": { "between": [70, 90] } } }
 ```
 
-Supported: `[between]`, `[notBetween]`.
+Supported: `between` (two-element tuple `[min, max]`).
 
 ### Sets (IN / NOT IN)
 ```json
-{ "where": { "status": { "[in]": ["draft", "published"] } } }
-{ "where": { "status": { "[notIn]": ["archived"] } } }
+{ "where": { "status": { "in": ["draft", "published"] } } }
+{ "where": { "status": { "notIn": ["archived"] } } }
 ```
 
-Supported: `[in]`, `[notIn]`.
+Supported: `in`, `notIn`.
 
 ### Pattern matching (strings)
 ```json
-{ "where": { "name": { "[like]": "%desk%" } } }
-{ "where": { "name": { "[notLike]": "Admin%" } } }
-{ "where": { "name": { "[iLike]": "%madrid%" } } }
-{ "where": { "name": { "[notILike]": "TEST%" } } }
-{ "where": { "name": { "[startsWith]": "Pro" } } }
-{ "where": { "name": { "[endsWith]": "Max" } } }
-{ "where": { "name": { "[substring]": "Air" } } }
-{ "where": { "sku":  { "[regexp]": "^[A-Z]{3}-[0-9]+$" } } }
-{ "where": { "sku":  { "[notRegexp]": "test" } } }
-{ "where": { "sku":  { "[iRegexp]": "abc" } } }
-{ "where": { "sku":  { "[notIRegexp]": "xyz" } } }
+{ "where": { "name": { "iLike": "%madrid%" } } }
 ```
 
-Supported: `[like]`, `[notLike]`, `[iLike]`, `[notILike]`, `[startsWith]`, `[endsWith]`, `[substring]`, `[regexp]`, `[notRegexp]`, `[iRegexp]`, `[notIRegexp]`.
-
-### Column vs column
-```json
-{ "where": { "updatedAt": { "[col]": "createdAt" } } }
-```
+Supported: `iLike` (case-insensitive `LIKE`, dialect-specific to Postgres —
+the DSL keeps the name close to the operator most APIs already use).
 
 ### Arrays
 ```json
-{ "where": { "tags": { "[overlap]": ["react", "node"] } } }
-{ "where": { "tags": { "[contains]": ["graphql"] } } }
-{ "where": { "roles": { "[any]": ["admin", "editor"] } } }
+{ "where": { "tags": { "overlap": ["react", "node"] } } }
+{ "where": { "tags": { "contains": ["graphql"] } } }
 ```
 
-# INCLUDE — Eager Loading Associations
-Recommended shape:
-```json
-{ "include": [ { "association": "tableToRelate" } ] }
-```
+Supported: `contains`, `overlap`.
 
-Include with filters:
-```json
-{
-  "include": [
-    {
-      "association": "fleetAircraft",
-      "attributes": ["id", "registration"],
-      "where": { "status": "active" },
-      "required": true
-    }
-  ]
-}
-```
-
-- where inside an include turns the join into a filter on the associated table.
-- required: true makes it an INNER JOIN (exclude parents without a matching child, default is left join).
-- attributes inside an include limits columns of the associated model.
+# RELATIONS — Shaping Loaded Children
+`relations` is a SEPARATE block from `where`. It declares, per relation,
+either `true` (load with no extra shaping) or a recursive query node that
+restricts/orders/paginates the LOADED CHILDREN without touching which parent
+rows come back.
 
-Nested includes:
+Load with no shaping:
 ```json
-{
-  "include": [
-    {
-      "association": "fleetAircraft",
-      "include": [
-        { "association": "aircraftModel" }
-      ]
-    }
-  ]
-}
+{ "relations": { "role": true } }
 ```
 
-You can also rely on { "include": { "all": true, "nested": true } }
-(when building queries in code) to include everything recursively.
-In your API, prefer explicit association names for control and safety.
-
-Many-to-many specifics:
+Shape the loaded children (parents are untouched — a parent with no
+matching child still appears, with an empty relation):
 ```json
 {
-  "include": [
-    {
-      "association": "userRoles",
-      "through": { "attributes": ["assignedAt"] }
+  "relations": {
+    "role": {
+      "where": { "active": { "eq": true } },
+      "order": [{ "field": "name", "dir": "asc" }],
+      "limit": 5
     }
-  ]
+  }
 }
 ```
 
-Ordering & limiting with includes
-- You can order by included fields using top-level `order` with a path
-  (see ORDER section below).
-- Limiting rows inside a hasMany include requires `separate: true` on that
-  include in Sequelize (code-level option). If you need this behavior, mirror
-  it in your API contract; otherwise limits apply at the root result set.
-
----
-
-# ATTRIBUTES — Projection / computed fields
-The attributes option defines which columns should be returned in the query result.
-By default, Sequelize selects all columns from the model. With attributes, you can:
-- Include only specific columns (whitelist).
-- Exclude specific columns (blacklist).
-- Rename (alias) columns.
-- Add computed or aggregated fields using Sequelize functions (fn, col, literal).
-
-Select, alias, and compute:
+Nested relations (recursive):
 ```json
 {
-  "attributes": [
-    "id",
-    "name",
-    ["email", "contactEmail"],  // alias
-    { "fn": "count", "col": "orders.id", "as": "orderCount" }, // aggregate
-    { "literal": "NOW()", "as": "now" }  // raw SQL literal (use with care)
-  ]
+  "relations": {
+    "fleetAircraft": {
+      "relations": {
+        "aircraftModel": true
+      }
+    }
+  }
 }
 ```
 
-Exclude shape:
-```json
-{ "attributes": { "exclude": ["password", "secretToken"] } }
-```
-
-Notes
-- `fn`, `col`, `cast`, and `literal` expressions are supported by Sequelize.
-- Aggregates typically pair with `group`.
+Many-to-many relations use the same shape as any other relation — the DSL
+does not expose a pivot-table option bag (`through`); pivot columns, if
+needed, are modeled as their own aggregate/relation.
 
 ---
 
 # ORDER — Sorting
-The order option defines the sort order of the query result set.
-It accepts an array of sorting rules. Each rule specifies a column (or expression) and the direction (ASC for ascending, DESC for descending).
+An array of `{ field, dir }` entries. `field` accepts a dot-path to a
+relation column; `dir` is `"asc"` or `"desc"`.
 
-Simple:
 ```json
-{ "order": [["createdAt", "DESC"]] }
-{ "order": [["name", "ASC"], ["id", "DESC"]] }
+{ "order": [{ "field": "createdAt", "dir": "desc" }] }
+{ "order": [{ "field": "name", "dir": "asc" }, { "field": "id", "dir": "desc" }] }
 ```
-Order by an included model field (path syntax):
+
+Order by a relation column (dot-path):
 ```json
-{ "order": [["$fleetAircraft.registration$", "ASC"]] }
+{ "order": [{ "field": "role.name", "dir": "asc" }] }
 ```
-Order by a function:
+When the RQB v2 engine cannot express ordering the parent by a relation
+column, the query transparently routes to the core select builder (a join)
+— the caller receives the same DSL result shape either way.
+
+### KNOWN LIMITATION — cannot order by an `aggregation` alias
+`order.field` must name a REAL column (own table, or `relation.column` via
+dot-path) — it is resolved with a plain column lookup against the base table
+(or the joined relation table), never against the `SELECT` list. It CANNOT
+name an `aggregation.fields[].as` alias:
 ```json
-{ "order": [[{ "fn": "lower", "col": "name" }, "ASC"]] }
+{
+  "aggregation": { "fields": [{ "fn": "count", "field": "id", "as": "total" }], "groupBy": ["status"] },
+  "order": [{ "field": "total", "dir": "desc" }]
+}
 ```
+`total` is not a column on the base table, so this resolves to an undefined
+column and fails at the core select builder — the aggregate function is never
+re-materialized in the `ORDER BY` clause the way it is in the `SELECT` clause.
+This differs from the report-engine's cube query builder
+(`ReportServerMode.buildOrderBy`), which sidesteps the problem entirely by
+re-expanding the full aggregate expression (e.g. `COUNT(o.amount) DESC`)
+instead of referencing the alias — that path has no equivalent limitation.
+Until the DSL/`DrizzleCriteria` core-builder fallback gains the same
+re-expansion, order by one of the `groupBy` fields (a real column) instead of
+an aggregation alias.
 
 ---
 
-# GROUP — Aggregation
-The group option is used to aggregate rows in the result set, similar to the SQL GROUP BY clause.
-It is typically combined with aggregate functions in the attributes field (e.g., COUNT, SUM, AVG).
+# AGGREGATION — count / sum / avg / min / max / group
+The aggregation block is ALWAYS routed to Drizzle's core select builder
+(RQB does not support aggregations). It is Aurora-owned keys only — never a
+raw SQL string.
 
-Group by columns/expressions (use with aggregates in attributes):
 ```json
 {
-  "attributes": [
-    "status",
-    { "fn": "count", "col": "*", "as": "cnt" }
-  ],
-  "group": ["status"],
-  "order": [["status", "ASC"]]
+  "aggregation": {
+    "fields": [
+      { "fn": "count", "field": "*", "as": "total" },
+      { "fn": "avg", "field": "salary", "as": "avgSalary" }
+    ],
+    "groupBy": ["status"]
+  }
 }
 ```
 
+Supported functions: `count`, `sum`, `avg`, `min`, `max`.
+
 ---
 
 # LIMIT / OFFSET — Pagination
-The limit and offset options are used to control pagination in query results.
-They correspond to SQL’s LIMIT and OFFSET clauses.
-- limit → maximum number of rows to return.
-- offset → number of rows to skip before starting to return results.
 ```json
 { "limit": 20, "offset": 40 }
 ```
-Notes
-- With hasMany includes, root rows can duplicate due to joins; use
-  `"distinct": true` (and optionally `"col": "id"`) when counting.
-- Per-include limiting needs `separate: true` on that include (code-level).
+- `limit` → maximum number of rows to return.
+- `offset` → number of rows to skip before returning results.
+
+Unlike Sequelize, there is no `distinct`/`col` pair to de-duplicate
+root-row counts inflated by a join: the DSL's `relations` block never joins
+in a way that duplicates parent rows (it is a separate query per relation
+level, RQB-style), so no manual de-duplication flag is needed.
 
 ---
 
-# DISTINCT & COL — Counting
-The distinct option ensures that query results (and counts) are unique, preventing duplicates that may appear when joining associated tables.
-It corresponds to SQL DISTINCT keyword.
-```json
-{ "distinct": true, "col": "id" }
-```
-Notes
-- `distinct: true` applies COUNT(DISTINCT ...) on the PK (or on `col`).
-- Use to avoid inflated counts caused by JOINs when using findAndCountAll.
+# VALIDATION CAPS — hard limits enforced by `QueryDslValidator`
+Every statement is walked by the default-deny whitelist validator BEFORE
+translation. Two structural caps apply regardless of the caller's own
+pagination or nesting choices (`@aurorajs.dev/core-back`,
+`domain/persistence/query-dsl/query-dsl-validator.ts`,
+`DEFAULT_MAX_LIMIT` / `DEFAULT_MAX_DEPTH`):
+- **`limit` ≤ 10000** — a `limit` above this value is rejected outright
+  (closes the unbounded-pagination hole a huge `limit` would otherwise open).
+- **Nesting `depth` ≤ 10** — applies to the `where` tree (including nested
+  `and`/`or`/`not` and relation-EXISTS nesting) and to the `relations` block
+  (including nested `relations.<name>.relations...`). Crafted JSON deeper than
+  10 levels is rejected with a validation error instead of risking a stack
+  overflow.
+
+Both are process-wide defaults, not per-request configurable from the wire —
+a statement that violates either cap never reaches the database.
 
 ---
 
 # END-TO-END EXAMPLES
-### Example 1, Active engines with aircraft ordered by registration
+### Example 1 — Active accounts with roles ordered by role name
 ```json
 {
-  "where": { "status": "active" },
-  "include": [
-    {
-      "association": "fleetAircraft",
-      "attributes": ["id", "registration"],
-      "where": { "registration": { "[notLike]": "TEST%" } },
-      "required": true
-    }
-  ],
-  "order": [["$fleetAircraft.registration$", "ASC"]],
+  "where": { "status": { "eq": "active" } },
+  "relations": {
+    "role": { "order": [{ "field": "name", "dir": "asc" }] }
+  },
+  "order": [{ "field": "role.name", "dir": "asc" }],
   "limit": 50,
-  "offset": 0,
-  "distinct": true
+  "offset": 0
 }
 ```
 
-### Example 2, Case-insensitive search + range + nested include
+### Example 2 — Case-insensitive search + range + nested relation
 ```json
 {
   "where": {
-    "[and]": [
-      { "name": { "[iLike]": "%aion%" } },
-      { "createdAt": { "[between]": ["2025-01-01", "2025-12-31"] } }
+    "and": [
+      { "name": { "iLike": "%aion%" } },
+      { "createdAt": { "between": ["2025-01-01", "2025-12-31"] } }
     ]
   },
-  "include": [
-    { "association": "engineModel", "attributes": ["id", "name"] },
-    {
-      "association": "fleetAircraft",
-      "include": [
-        { "association": "aircraftModel", "attributes": ["code", "name"] }
-      ]
+  "relations": {
+    "engineModel": true,
+    "fleetAircraft": {
+      "relations": { "aircraftModel": true }
     }
-  ],
-  "order": [["createdAt", "DESC"]]
+  },
+  "order": [{ "field": "createdAt", "dir": "desc" }]
 }
 ```
 
-### Example 2, Aggregation with group
+### Example 3 — Aggregation with group
 ```json
 {
-  "attributes": [
-    "status",
-    { "fn": "count", "col": "*", "as": "total" }
-  ],
-  "group": ["status"],
-  "order": [["status", "ASC"]]
+  "aggregation": {
+    "fields": [{ "fn": "count", "field": "*", "as": "total" }],
+    "groupBy": ["status"]
+  },
+  "order": [{ "field": "status", "dir": "asc" }]
 }
 ```
 
 ---
 
 # OPERATOR REFERENCE
-- **Logical**:      [and], [or], [not]
-- **Equality**:     [eq], [ne], [is]
-- **Comparison**:   [gt], [gte], [lt], [lte]
-- **Ranges**:       [between], [notBetween]
-- **Sets**:         [in], [notIn]
-- **Patterns**:     [like], [notLike], [iLike], [notILike],
-                    [startsWith], [endsWith], [substring],
-                    [regexp], [notRegexp], [iRegexp], [notIRegexp]
-- **Column ref**:   [col]
-- **Arrays**:       [overlap], [contains], [contained], [any]
+- **Logical**:      and, or, not
+- **Equality**:     eq, ne, isNull
+- **Comparison**:   gt, gte, lt, lte
+- **Ranges**:        between
+- **Sets**:         in, notIn
+- **Patterns**:     iLike
+- **Arrays**:       contains, overlap
+- **Aggregation**:  count, sum, avg, min, max (with optional groupBy)
+
+Any operator or key NOT in this list is rejected by the default-deny
+whitelist validator before the query is translated — including MySQL-only
+fossils Sequelize used to accept (`IndexHints`) and any raw-SQL escape hatch
+(`literal`, `fn`, `col`). See `openspec/specs/aurora-query-dsl/spec.md` for
+the full normative contract.
 """
-input QueryStatement {
+input QueryStatementInput {
   where: JSON
-  attributes: JSON
-  include: JSON
+  relations: JSON
   order: JSON
-  group: JSON
+  aggregation: JSON
   limit: GraphQLInt
   offset: GraphQLInt
-  lock: Any
-  skipLocked: GraphQLBoolean
-  raw: GraphQLBoolean
-  having: Any
-  subQuery: GraphQLBoolean
-  indexHints: JSON
-  distinct: GraphQLBoolean
-  col: GraphQLString
 }
 
 type Pagination {