@query-graph/core 1.1.6 → 1.1.7

package/definition.d.ts

@@ -30,7 +30,7 @@ import type {
 } from './dsl.js'
 
 /** @deprecated Import authoring primitives from `@query-graph/core/dsl`. */
-export const GRAPH_DEFINITION_VERSION: 11
+export const GRAPH_DEFINITION_VERSION: 12
 
 /** @deprecated Use `source.field(name)` from `@query-graph/core/dsl`. */
 export function field<

package/definition.js

@@ -76,6 +76,11 @@ exports.requiredListParameter = objectDsl.requiredListParameter
 exports.requiredListParam = objectDsl.requiredListParam
 exports.optionalListParameter = objectDsl.optionalListParameter
 exports.optionalListParam = objectDsl.optionalListParam
+exports.requiredGroupsParameter = objectDsl.requiredGroupsParameter
+exports.requiredGroupsParam = objectDsl.requiredGroupsParam
+exports.optionalGroupsParameter = objectDsl.optionalGroupsParameter
+exports.optionalGroupsParam = objectDsl.optionalGroupsParam
+exports.allGroups = objectDsl.allGroups
 exports.eq = objectDsl.eq
 exports.neq = objectDsl.neq
 exports.lt = objectDsl.lt

package/docs/authoring.md

@@ -1,7 +1,7 @@
 # Authoring DSL
 
 Authoring API находится в <code>@query-graph/core/dsl</code>. Он создает
-семантический definition версии 11, который не содержит таблиц, SQL aliases или
+семантический definition версии 12, который не содержит таблиц, SQL aliases или
 синтаксиса диалекта.
 
 ## Sources и поля
@@ -36,6 +36,76 @@ Scalar parameter передается в expression напрямую, list param
 тех же factories. Optional parameter не активирует constraint с
 <code>when</code>, пока значение отсутствует.
 
+### Группированные параметры
+
+Grouped list parameter описывает массив групп <code>{ key, values }</code>.
+Каждая группа содержит один ключ и список значений:
+
+```ts
+import { allGroups, and, constraint, eq, inParam, optionalGroupsParam, source } from '@query-graph/core/dsl'
+
+const attributes = source('attributes', { name: 'string', valueId: 'int64' })
+const filters = optionalGroupsParam('filters', { key: 'string', value: 'int64' })
+const attributeFilter = constraint({
+  predicate: allGroups(filters, ({ key, values }) =>
+    and(eq(attributes.field('name'), key), inParam(attributes.field('valueId'), values)),
+  ),
+})
+
+// Operation parameters:
+const parameters = {
+  filters: [
+    { key: 'color', values: [1, 2] },
+    { key: 'size', values: [3] },
+  ],
+}
+```
+
+Добавьте <code>filters</code> в <code>parameters</code> definition, а
+<code>attributeFilter</code> в <code>constraints</code>. Если разные группы
+должны совпасть с разными связанными строками, поместите <code>exists</code>
+внутрь callback и объявите соответствующую relation.
+
+<code>requiredGroupsParam</code> требует присутствия массива в operation.
+Полные имена <code>optionalGroupsParameter</code> и
+<code>requiredGroupsParameter</code> являются алиасами тех же factories.
+Неизвестные поля конфигурации, scalar types и некорректные аргументы factories
+отклоняются сразу при authoring.
+
+Callback <code>allGroups</code> вызывается ровно один раз при построении AST,
+а не для каждой runtime-группы. <code>key</code> является типизированным scalar
+expression, <code>values</code> является отдельной scoped list reference только
+для <code>inParam</code>/<code>inParameter</code>. Ни grouped parameter, ни
+<code>values</code> нельзя передать в <code>param</code> или использовать как
+обычное scalar expression. <code>values</code> также нельзя объявить root parameter.
+
+Каждый binder получает UUID scope через <code>node:crypto.randomUUID()</code>,
+независимо от загрузки отдельных экземпляров или копий DSL. Вложенный callback
+может захватить <code>key</code> и <code>values</code> внешнего callback;
+одноименные параметры не смешивают их scopes. Ссылки за пределами своего binder,
+в том числе захваченные из соседнего callback, отклоняются Rust при регистрации.
+Scope является внутренним идентификатором, его конкретное значение не гарантируется.
+
+Семантика компиляции:
+
+- отсутствующий optional parameter и пустой массив групп дают <code>true</code>;
+- неактивное тело не требует optional scalar parameters или JOIN, используемых
+  только внутри него;
+- predicates всех групп объединяются через <code>AND</code>;
+- повторяющиеся ключи остаются независимыми группами, их values не объединяются;
+- пустой <code>values</code> дает <code>false</code> в <code>inParam</code>;
+- nullable predicate сохраняет обычную трехзначную SQL-семантику.
+
+Rust разрешает <code>allGroups</code> только в constraint predicates, включая
+вложенные boolean expressions и <code>exists</code>. Projection, ordering,
+relation predicates и aggregate bodies не поддерживают binder.
+
+Wire definition сохраняет тип элементов в <code>scalarType</code> и добавляет
+<code>shape: 'groupedList'</code> и <code>keyType</code>. AST использует
+<code>{ kind: 'allGroups', parameter, scope, predicate }</code>,
+<code>{ kind: 'groupKey', scope }</code> и
+<code>{ kind: 'inGroupValues', expression, scope }</code>.
+
 ## Expressions
 
 DSL предоставляет сравнения, boolean groups, null tests, semantic functions,

package/docs/diagnostics.md

@@ -45,8 +45,32 @@ Rust выполняет semantic validation:
 Такое разделение дает ранние ошибки опечаток, не дублируя planner rules в
 JavaScript.
 
+Циклические зависимости relation predicates через <code>exists</code> отклоняются
+при регистрации definition: <code>invalidExistsContext</code> указывает на
+<code>relations[i].on</code>, замыкающий цикл. Параметры, необходимые вложенным
+<code>exists</code>, проверяются в фазе <code>operation</code>; отсутствующий
+параметр получает <code>missingParameter</code> с location
+<code>parameters.&lt;name&gt;</code>.
+
+Статические параметры batch relation проверяются при <code>composeGraph</code>:
+ошибки относятся к фазе <code>composition</code>, в том числе для имен параметров
+с квадратными скобками. Параметр batch key исключается из этой проверки по точному
+имени; значения ключей проверяются позже, при <code>compileBatch</code>, в фазе
+<code>operation</code>.
+
 ## Совместимость diagnostics
 
-Wire schema остается версии 11. В совместимых выпусках сохраняются diagnostic
+Wire schema версии 12 добавляет grouped-параметры и scoped-шаблоны `allGroups`.
+Сохранённые raw definitions предыдущей версии требуют обновления; обычные
+DSL-фабрики формируют актуальную версию автоматически. JS DSL и native binding
+должны быть из одного выпуска пакета.
+
+Невалидные данные группы получают `invalidParameterType` с точным путём,
+например `parameters.characteristics[0].values[1]`. Ссылка вне своего шаблона
+получает `unknownGroupScope`; повторное объявление активного scope получает
+`shadowedGroupScope`. `allGroups` вне constraint predicate получает
+`invalidAllGroupsContext`. Эти проверки выполняются и для raw wire definitions.
+
+Для прежних ошибок сохраняются diagnostic
 codes и locations. Message предназначен человеку и не должен использоваться как
 machine-readable contract.

package/docs/sql.md

@@ -45,6 +45,29 @@ Semantic functions рендерятся с одинаковым поведени
 SQL Server compiler принудительно переводит <code>divide</code> в дробную
 арифметику, чтобы два integer operands не дали integer division.
 
+В SQL Server 2012 и новее <code>concat</code> с одним аргументом компилируется
+с дополнительной пустой строкой <code>''</code>. Списки длиннее 254 аргументов
+разделяются на вложенные вызовы с сохранением порядка. Промежуточные группы
+используют <code>nvarchar(max)</code>, чтобы избежать обрезания строк при
+объединении. <code>NULL</code> обрабатывается как пустая строка согласно
+[семантике CONCAT в SQL Server](https://learn.microsoft.com/en-us/sql/t-sql/functions/concat-transact-sql).
+
+## Boolean expressions
+
+Компилятор различает значения и условия. Boolean-поле в <code>WHERE</code>,
+<code>ON</code> или логическом выражении превращается в сравнение с <code>1</code>.
+Условие в <code>SELECT</code>, <code>GROUP BY</code> или аргументе функции
+превращается в <code>CASE</code>: <code>TRUE</code> дает <code>1</code>,
+<code>FALSE</code> — <code>0</code>, <code>UNKNOWN</code> — <code>NULL</code>.
+Boolean metadata и TypeScript-типы сохраняются; преобразование значений драйвера
+остается ответственностью executor.
+
+В Oracle 23ai условия сохраняют нативный SQL-тип <code>BOOLEAN</code> в контексте
+значения. В контексте условия скалярные значения оборачиваются в
+<code>TO_BOOLEAN</code>, который принимает как числовое, так и boolean-представление.
+Прямые проекции полей и существующие сравнения с boolean literals сохраняют
+прежний SQL.
+
 ## Bindings
 
 Compiler никогда не вставляет operation values в SQL. Каждый binding содержит:
@@ -52,11 +75,64 @@ Compiler никогда не вставляет operation values в SQL. Каж
 - SQL placeholder name;
 - имя parameter;
 - scalar type;
-- index элемента для list parameter.
+- index элемента для list parameter;
+- path до вложенного значения для grouped parameter.
 
 Повторное использование parameter переиспользует binding. Пустой list
 компилируется в ложное условие без placeholders.
 
+Для scalar отсутствуют и `index`, и `path`. Для обычного list сохраняется
+`index`. Для grouped list используется только `path`, например:
+
+```ts
+;[
+  { name: 'p0', parameter: 'characteristics', scalarType: 'int64', path: [0, 'key'] },
+  { name: 'p1', parameter: 'characteristics', scalarType: 'int64', path: [0, 'values', 1] },
+]
+```
+
+Executor извлекает значение из `operation.parameters[binding.parameter]`,
+последовательно проходя по сегментам `path`. `index` и `path` взаимно исключаются;
+отсутствующий сегмент должен приводить к ошибке, а не к подстановке `null`.
+Тип binding соответствует конкретному ключу или элементу values, а не контейнеру.
+Повторное обращение к тому же параметру и пути переиспользует placeholder.
+Потребитель должен обновить resolver bindings до начала использования grouped-параметров.
+
+`allGroups` разворачивает шаблон в условия, соединённые `AND`, только при
+компиляции операции. Для отсутствующего optional-параметра и пустого списка
+групп результат равен `TRUE`; зависимости тела шаблона не включаются в план.
+Каждый `exists` остаётся коррелированным подзапросом по описанному пути relations,
+включая `firstBy`. Definition не изменяется, но SQL зависит от количества групп
+и значений. Это один SQL-запрос, а не отдельное выполнение на каждую группу.
+
+На один statement допускается до 10 000 разворачиваний тела `allGroups`
+суммарно по всем шаблонам, включая вложенные. Превышение возвращает
+`groupExpansionLimitExceeded`: вложенность может увеличить SQL многократно,
+даже когда все bindings переиспользуются. Лимит применяется отдельно к каждой
+компиляции и не ограничивает каталог доступных групп в приложении.
+
+Также ограничено суммарное число элементов параметров-массивов, развёрнутых
+внутри этих шаблонов: до 100 000 на statement. Повторное использование
+одинаковых placeholders считается повторно, поскольку увеличивает SQL.
+Ограничение охватывает и `values` группы, и обычный list parameter внутри
+`allGroups`; превышение даёт `groupValueExpansionLimitExceeded`.
+
+SQL Server compiler отклоняет statement с более чем 2100 уникальными bindings
+с диагностикой `tooManyParameters`. Считаются все scalar, list и grouped bindings
+вместе; разбиение `IN` не уменьшает их количество. Для больших выборок нужна
+другая стратегия передачи данных, которой текущий grouped DSL не подменяет
+явную ошибку. Ограничение согласовано с
+[бюджетом параметров SQL Server](https://learn.microsoft.com/sql/sql-server/maximum-capacity-specifications-for-sql-server).
+
+В Oracle большие <code>inParam</code> (включая values группы) и <code>inList</code> разбиваются на
+группы <code>IN</code>, объединённые <code>OR</code> в общих скобках внутри
+одного SQL. Размер группы — до 1000 выражений в 11g–21c и до 65535 в 23ai
+согласно [лимитам Oracle](https://python-oracledb.readthedocs.io/en/v2.5.1/user_guide/bind.html#binding-a-large-number-of-items-in-an-in-list).
+<code>not</code> применяется ко всей группе и сохраняет SQL-семантику
+<code>NULL</code>. Порядок элементов и индексы bindings сохраняются, включая
+дубликаты. Пустой литеральный <code>inList</code> по-прежнему отклоняется при
+валидации definition.
+
 ## Result metadata
 
 SQL columns получают технические aliases <code>c0</code>,

package/docs/type-system.md

@@ -16,6 +16,10 @@ TypeScript помогает автору до регистрации, Rust ос
 <code>int64</code> принимает number только в безопасном диапазоне JavaScript.
 Decimal string проверяется как конечная десятичная запись.
 
+<code>integer(value)</code> поддерживает весь диапазон от
+<code>Number.MIN_SAFE_INTEGER</code> до <code>Number.MAX_SAFE_INTEGER</code>,
+включая значения за пределами 32 бит.
+
 ## QueryOperation
 
 Definition передает свои параметры, projection paths и ordering names в
@@ -34,6 +38,49 @@ const operation = {
 Required parameters обязательны, optional параметры могут отсутствовать,
 list parameters принимают readonly arrays.
 
+Grouped list parameters выводятся как:
+
+```ts
+readonly {
+  key: ScalarParameterValue<KeyType>
+  values: readonly ScalarParameterValue<ValueType>[]
+}[]
+```
+
+Например, <code>requiredGroupsParam('filters', { key: 'string', value: 'int64' })</code>
+требует <code>parameters.filters</code> типа
+<code>readonly { key: string; values: readonly (number | string)[] }[]</code>.
+Optional grouped parameter может отсутствовать, но не заменяться на <code>null</code>.
+Оба массива принимают readonly tuples, в том числе из <code>as const</code>.
+
+Контейнер групп, отдельная группа и контейнер <code>values</code> не могут быть
+<code>null</code>. Ключ и элементы списка следуют обычному scalar contract:
+<code>null</code> запрещен для всех типов, кроме <code>json</code>. JSON сохраняет
+существующую семантику JSON values, включая <code>null</code> и вложенные структуры.
+Rust проверяет наличие <code>key</code>/<code>values</code>, неизвестные поля
+группы и scalar types, включая ограничения числовых значений.
+
+Grouped parameters сохраняют эти типы при композиции GraphModule и могут быть
+статическими параметрами дочернего <code>batchRelation</code>. Ключ
+<code>batchQuery</code> по-прежнему требует обычный list parameter, не grouped list.
+
+В callback <code>allGroups</code> ключ имеет scalar type <code>KeyType</code>,
+а <code>GroupValuesRef&lt;ValueType&gt;</code> принимается только как второй аргумент
+<code>inParameter</code>/<code>inParam</code>. TypeScript исключает эту reference
+из scalar expressions и root parameters; Rust проверяет lexical scope и
+совместимость типов сравнения и membership.
+
+Для grouped bindings <code>path</code> указывает на значение внутри operation
+parameter: <code>[groupIndex, 'key']</code> или
+<code>[groupIndex, 'values', valueIndex]</code>. Scalar bindings остаются без
+<code>index</code>/<code>path</code>, обычные list bindings сохраняют
+<code>index</code>. Поля <code>index</code> и <code>path</code> взаимоисключающие.
+Это же правило действует для результатов <code>compileBatch</code>.
+
+В Node API <code>offset</code> и <code>limit</code> принимают безопасные целые
+JavaScript, включая значения больше <code>2 \*\* 32 - 1</code>.
+<code>offset</code> должен быть неотрицательным, <code>limit</code> — положительным.
+
 ## Nullability
 
 Nullability выражения складывается из:
@@ -46,6 +93,20 @@ Nullability выражения складывается из:
 Required relation под optional ancestor остается nullable. Это свойство
 вычисляется из topology один раз при регистрации.
 
+В <code>fieldType</code> флаг <code>nullable</code> типа <code>boolean</code>
+означает, что поле может быть NULL. Литеральные <code>true</code> и
+<code>false</code> позволяют вывести точную nullability.
+
+Сравнения <code>eq</code>/<code>neq</code> с гарантированным <code>null</code>
+(включая <code>literal(null)</code>) дают non-null результат. Тип операнда
+<code>string | null</code> сам по себе не гарантирует сравнение именно с NULL:
+nullable поле при сравнении со строкой может дать NULL.
+
+<code>allGroups</code> возвращает boolean с nullability predicate шаблона.
+Пустой набор групп дает <code>true</code>, но при наличии групп nullable
+сравнение внутри callback может дать SQL UNKNOWN. Если callback возвращает
+<code>exists</code>, результат остается non-null boolean.
+
 ## ResultOf
 
 ```ts
@@ -77,7 +138,8 @@ compilation не меняются.
 Rust проверяет:
 
 - ссылки на sources, fields и parameters;
-- scalar/list shape параметров;
+- scalar/list/groupedList shape параметров и key type grouped parameters;
+- lexical scopes ключей и списков групп, допустимость binder в constraint context;
 - совместимость сравнений и функций;
 - boolean тип predicates;
 - orderable и groupable expressions;

package/dsl.d.ts

@@ -27,6 +27,9 @@ export type {
   LikeExpression,
   InExpression,
   InParameterExpression,
+  GroupKeyExpression,
+  InGroupValuesExpression,
+  AllGroupsExpression,
   ExpressionGroup,
   UnaryExpression,
   ExistsExpression,
@@ -94,6 +97,10 @@ export type {
   SourceRef,
   ScalarParameterRef,
   ListParameterRef,
+  GroupedListParameterRef,
+  GroupedListParameterTypes,
+  GroupValuesRef,
+  GroupScope,
   ParameterRef,
   RelationRef,
   LiteralInput,
@@ -127,6 +134,11 @@ export {
   requiredListParam,
   optionalListParameter,
   optionalListParam,
+  requiredGroupsParameter,
+  requiredGroupsParam,
+  optionalGroupsParameter,
+  optionalGroupsParam,
+  allGroups,
   param,
   literal,
   integer,

package/dsl.js

@@ -20,6 +20,11 @@ exports.requiredListParameter = primitives.requiredListParameter
 exports.requiredListParam = primitives.requiredListParam
 exports.optionalListParameter = primitives.optionalListParameter
 exports.optionalListParam = primitives.optionalListParam
+exports.requiredGroupsParameter = primitives.requiredGroupsParameter
+exports.requiredGroupsParam = primitives.requiredGroupsParam
+exports.optionalGroupsParameter = primitives.optionalGroupsParameter
+exports.optionalGroupsParam = primitives.optionalGroupsParam
+exports.allGroups = primitives.allGroups
 exports.eq = primitives.eq
 exports.neq = primitives.neq
 exports.lt = primitives.lt

package/lib/authoring/definition.js

@@ -11,7 +11,7 @@ const {
 const { asExpression, copySource, referenceName } = require('./primitives.js')
 const { GRAPH_MODULE_BRAND, SUMMARY_FIELD_BRAND } = require('./symbols.js')
 
-const GRAPH_DEFINITION_VERSION = 11
+const GRAPH_DEFINITION_VERSION = 12
 const RELATION_CONFIGURATION_KEYS = new Set(['name', 'from', 'to', 'on', 'required', 'cardinality', 'selection'])
 const CONSTRAINT_CONFIGURATION_KEYS = new Set(['predicate', 'when'])
 const PROJECTION_CONFIGURATION_KEYS = new Set(['path', 'expression', 'default'])

package/lib/authoring/primitives.js

@@ -1,7 +1,8 @@
 'use strict'
 
+const { randomUUID } = require('node:crypto')
 const { arrayOf, configurationOf, nonEmptyString, objectOf, optionalBoolean } = require('../configuration.js')
-const { PARAMETER_REF_BRAND, SUMMARY_FIELD_BRAND } = require('./symbols.js')
+const { GROUP_VALUES_REF_BRAND, PARAMETER_REF_BRAND, SUMMARY_FIELD_BRAND } = require('./symbols.js')
 
 const SCALAR_TYPES = new Set([
   'boolean',
@@ -18,6 +19,7 @@ const SCALAR_TYPES = new Set([
 const FIELD_TYPE_OPTIONS_KEYS = new Set(['nullable', 'selectable'])
 const FIELD_SPECIFICATION_KEYS = new Set(['scalarType', 'nullable', 'selectable'])
 const EXISTS_CONFIGURATION_KEYS = new Set(['from'])
+const GROUPED_LIST_CONFIGURATION_KEYS = new Set(['key', 'value'])
 
 function fieldType(scalarType, options = {}) {
   assertScalarType(scalarType)
@@ -100,10 +102,32 @@ function optionalListParameter(name, scalarType) {
   return parameterDefinition(name, scalarType, false, 'list')
 }
 
+function requiredGroupsParameter(name, types) {
+  return groupedListParameterDefinition(name, types, true)
+}
+
+function optionalGroupsParameter(name, types) {
+  return groupedListParameterDefinition(name, types, false)
+}
+
+function groupedListParameterDefinition(name, types, required) {
+  const configuration = configurationOf('grouped list parameter', types, GROUPED_LIST_CONFIGURATION_KEYS)
+  assertScalarType(configuration.key)
+  const definition = parameterDefinition(name, configuration.value, required, 'groupedList')
+  definition.keyType = configuration.key
+  return definition
+}
+
 function param(parameterReference) {
   if (typeof parameterReference !== 'string' && parameterReference?.shape === 'list') {
     throw new TypeError(`List parameter ${parameterReference.name} cannot be used as a scalar expression`)
   }
+  if (parameterReference?.shape === 'groupedList') {
+    throw new TypeError(`Grouped list parameter ${parameterReference.name} cannot be used as a scalar expression`)
+  }
+  if (parameterReference?.[GROUP_VALUES_REF_BRAND] === true) {
+    throw new TypeError('Group values cannot be used as a scalar expression')
+  }
 
   return {
     kind: 'parameter',
@@ -184,6 +208,13 @@ function inList(expression, values) {
 }
 
 function inParameter(expression, parameterReference) {
+  if (parameterReference?.[GROUP_VALUES_REF_BRAND] === true) {
+    return {
+      kind: 'inGroupValues',
+      expression: asExpression(expression),
+      scope: parameterReference.scope,
+    }
+  }
   if (typeof parameterReference !== 'string' && parameterReference?.shape !== 'list') {
     throw new TypeError(`Parameter ${parameterReference?.name ?? '<unknown>'} is not a list parameter`)
   }
@@ -195,6 +226,31 @@ function inParameter(expression, parameterReference) {
   }
 }
 
+function allGroups(parameterReference, predicate) {
+  if (parameterReference?.[PARAMETER_REF_BRAND] !== true || parameterReference.shape !== 'groupedList') {
+    throw new TypeError('allGroups requires a grouped list parameter')
+  }
+  const parameter = referenceName(parameterReference, 'parameter')
+  assertScalarType(parameterReference.keyType)
+  assertScalarType(parameterReference.scalarType)
+  if (typeof predicate !== 'function') {
+    throw new TypeError('allGroups predicate must be a function')
+  }
+
+  const scope = randomUUID()
+  const key = Object.freeze({ kind: 'groupKey', scope })
+  const values = { scope }
+  Object.defineProperty(values, GROUP_VALUES_REF_BRAND, { value: true })
+  Object.freeze(values)
+
+  return {
+    kind: 'allGroups',
+    parameter,
+    scope,
+    predicate: asExpression(predicate({ key, values })),
+  }
+}
+
 function and(...expressions) {
   return {
     kind: 'and',
@@ -334,8 +390,8 @@ function parameterDefinition(name, scalarType, required, shape = 'scalar') {
   if (required) {
     definition.required = true
   }
-  if (shape === 'list') {
-    definition.shape = 'list'
+  if (shape !== 'scalar') {
+    definition.shape = shape
   }
   Object.defineProperty(definition, PARAMETER_REF_BRAND, { value: true })
   return definition
@@ -364,6 +420,9 @@ function unaryExpression(kind, expression) {
 }
 
 function asExpression(value) {
+  if (value?.[GROUP_VALUES_REF_BRAND] === true) {
+    throw new TypeError('Group values cannot be used as a scalar expression')
+  }
   if (value?.[SUMMARY_FIELD_BRAND] === true) {
     return value.expression
   }
@@ -406,6 +465,7 @@ function assertScalarType(scalarType) {
 }
 
 module.exports = {
+  allGroups,
   and,
   asExpression,
   average,
@@ -439,6 +499,8 @@ module.exports = {
   neq,
   not,
   nullable,
+  optionalGroupsParam: optionalGroupsParameter,
+  optionalGroupsParameter,
   optionalListParam: optionalListParameter,
   optionalListParameter,
   optionalParam: optionalParameter,
@@ -446,6 +508,8 @@ module.exports = {
   or,
   param,
   referenceName,
+  requiredGroupsParam: requiredGroupsParameter,
+  requiredGroupsParameter,
   requiredListParam: requiredListParameter,
   requiredListParameter,
   requiredParam: requiredParameter,

package/lib/authoring/symbols.js

@@ -1,5 +1,6 @@
 'use strict'
 
 exports.GRAPH_MODULE_BRAND = Symbol('GraphModule')
+exports.GROUP_VALUES_REF_BRAND = Symbol('GroupValuesRef')
 exports.PARAMETER_REF_BRAND = Symbol('ParameterRef')
 exports.SUMMARY_FIELD_BRAND = Symbol('SummaryField')

package/native.d.ts

@@ -95,4 +95,5 @@ export interface SqlBinding {
   parameter: string
   scalarType: import('./dsl.js').ScalarType
   index?: number
+  path?: Array<number | string>
 }

package/native.js

@@ -81,12 +81,12 @@ function requireNative() {
         const binding = require('@query-graph/core-android-arm64')
         const bindingPackageVersion = require('@query-graph/core-android-arm64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -103,12 +103,12 @@ function requireNative() {
         const binding = require('@query-graph/core-android-arm-eabi')
         const bindingPackageVersion = require('@query-graph/core-android-arm-eabi/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -129,12 +129,12 @@ function requireNative() {
         const binding = require('@query-graph/core-win32-x64-msvc')
         const bindingPackageVersion = require('@query-graph/core-win32-x64-msvc/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -151,12 +151,12 @@ function requireNative() {
         const binding = require('@query-graph/core-win32-ia32-msvc')
         const bindingPackageVersion = require('@query-graph/core-win32-ia32-msvc/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -173,12 +173,12 @@ function requireNative() {
         const binding = require('@query-graph/core-win32-arm64-msvc')
         const bindingPackageVersion = require('@query-graph/core-win32-arm64-msvc/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -198,12 +198,12 @@ function requireNative() {
       const binding = require('@query-graph/core-darwin-universal')
       const bindingPackageVersion = require('@query-graph/core-darwin-universal/package.json').version
       if (
-        bindingPackageVersion !== '1.1.6' &&
+        bindingPackageVersion !== '1.1.7' &&
         process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
         process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
       ) {
         throw new Error(
-          `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+          `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
         )
       }
       return binding
@@ -220,12 +220,12 @@ function requireNative() {
         const binding = require('@query-graph/core-darwin-x64')
         const bindingPackageVersion = require('@query-graph/core-darwin-x64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -242,12 +242,12 @@ function requireNative() {
         const binding = require('@query-graph/core-darwin-arm64')
         const bindingPackageVersion = require('@query-graph/core-darwin-arm64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -268,12 +268,12 @@ function requireNative() {
         const binding = require('@query-graph/core-freebsd-x64')
         const bindingPackageVersion = require('@query-graph/core-freebsd-x64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -290,12 +290,12 @@ function requireNative() {
         const binding = require('@query-graph/core-freebsd-arm64')
         const bindingPackageVersion = require('@query-graph/core-freebsd-arm64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -317,12 +317,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-x64-musl')
           const bindingPackageVersion = require('@query-graph/core-linux-x64-musl/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -339,12 +339,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-x64-gnu')
           const bindingPackageVersion = require('@query-graph/core-linux-x64-gnu/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -363,12 +363,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-arm64-musl')
           const bindingPackageVersion = require('@query-graph/core-linux-arm64-musl/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -385,12 +385,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-arm64-gnu')
           const bindingPackageVersion = require('@query-graph/core-linux-arm64-gnu/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -409,12 +409,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-arm-musleabihf')
           const bindingPackageVersion = require('@query-graph/core-linux-arm-musleabihf/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -431,12 +431,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@query-graph/core-linux-arm-gnueabihf/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -455,12 +455,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-loong64-musl')
           const bindingPackageVersion = require('@query-graph/core-linux-loong64-musl/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -477,12 +477,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-loong64-gnu')
           const bindingPackageVersion = require('@query-graph/core-linux-loong64-gnu/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -501,12 +501,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-riscv64-musl')
           const bindingPackageVersion = require('@query-graph/core-linux-riscv64-musl/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -523,12 +523,12 @@ function requireNative() {
           const binding = require('@query-graph/core-linux-riscv64-gnu')
           const bindingPackageVersion = require('@query-graph/core-linux-riscv64-gnu/package.json').version
           if (
-            bindingPackageVersion !== '1.1.6' &&
+            bindingPackageVersion !== '1.1.7' &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
             process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
           ) {
             throw new Error(
-              `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
             )
           }
           return binding
@@ -546,12 +546,12 @@ function requireNative() {
         const binding = require('@query-graph/core-linux-ppc64-gnu')
         const bindingPackageVersion = require('@query-graph/core-linux-ppc64-gnu/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -568,12 +568,12 @@ function requireNative() {
         const binding = require('@query-graph/core-linux-s390x-gnu')
         const bindingPackageVersion = require('@query-graph/core-linux-s390x-gnu/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -594,12 +594,12 @@ function requireNative() {
         const binding = require('@query-graph/core-openharmony-arm64')
         const bindingPackageVersion = require('@query-graph/core-openharmony-arm64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -616,12 +616,12 @@ function requireNative() {
         const binding = require('@query-graph/core-openharmony-x64')
         const bindingPackageVersion = require('@query-graph/core-openharmony-x64/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding
@@ -638,12 +638,12 @@ function requireNative() {
         const binding = require('@query-graph/core-openharmony-arm')
         const bindingPackageVersion = require('@query-graph/core-openharmony-arm/package.json').version
         if (
-          bindingPackageVersion !== '1.1.6' &&
+          bindingPackageVersion !== '1.1.7' &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK &&
           process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0'
         ) {
           throw new Error(
-            `Native binding package version mismatch, expected 1.1.6 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.7 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
           )
         }
         return binding

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-graph/core",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Native query graph planner and SQL compiler for Node.js",
   "workspaces": [
     "packages/*"
@@ -141,9 +141,9 @@
   },
   "packageManager": "yarn@4.13.0",
   "optionalDependencies": {
-    "@query-graph/core-win32-x64-msvc": "1.1.6",
-    "@query-graph/core-darwin-x64": "1.1.6",
-    "@query-graph/core-linux-x64-gnu": "1.1.6",
-    "@query-graph/core-darwin-arm64": "1.1.6"
+    "@query-graph/core-win32-x64-msvc": "1.1.7",
+    "@query-graph/core-darwin-x64": "1.1.7",
+    "@query-graph/core-linux-x64-gnu": "1.1.7",
+    "@query-graph/core-darwin-arm64": "1.1.7"
   }
 }

package/types/authoring.d.ts

@@ -1,5 +1,6 @@
 import type {
   AggregateExpression,
+  AllGroupsExpression,
   AllNullability,
   AnyNullability,
   BinaryExpression,
@@ -13,7 +14,9 @@ import type {
   FirstBySelection,
   FunctionExpression,
   GraphDefinition,
+  GroupKeyExpression,
   InExpression,
+  InGroupValuesExpression,
   InParameterExpression,
   JoinProjectionPath,
   LikeExpression,
@@ -110,11 +113,45 @@ export interface ListParameterRef<
   required?: Required
 }
 
+export interface GroupedListParameterRef<
+  Name extends string = string,
+  Key extends ScalarType = ScalarType,
+  Value extends ScalarType = ScalarType,
+  Required extends boolean = boolean,
+> extends ParameterDefinition {
+  readonly [parameterRefBrand]: true
+  name: Name
+  scalarType: Value
+  shape: 'groupedList'
+  keyType: Key
+  required?: Required
+}
+
+declare const groupValuesRefBrand: unique symbol
+
+export interface GroupValuesRef<Type extends ScalarType = ScalarType> {
+  readonly [groupValuesRefBrand]: Type
+  readonly scope: string
+}
+
+export interface GroupedListParameterTypes<Key extends ScalarType = ScalarType, Value extends ScalarType = ScalarType> {
+  key: Key
+  value: Value
+}
+
+export interface GroupScope<Key extends ScalarType = ScalarType, Value extends ScalarType = ScalarType> {
+  key: TypedExpression<GroupKeyExpression, Key, false>
+  values: GroupValuesRef<Value>
+}
+
 export type ParameterRef<
   Name extends string = string,
   Type extends ScalarType = ScalarType,
   Required extends boolean = boolean,
-> = ScalarParameterRef<Name, Type, Required> | ListParameterRef<Name, Type, Required>
+> =
+  | ScalarParameterRef<Name, Type, Required>
+  | ListParameterRef<Name, Type, Required>
+  | GroupedListParameterRef<Name, ScalarType, Type, Required>
 
 export type RelationRef<
   Name extends string = string,
@@ -198,7 +235,13 @@ export interface FieldTypeOptions {
   selectable?: boolean
 }
 
-type OptionNullable<Options extends FieldTypeOptions> = Options extends { nullable: true } ? true : false
+type OptionNullable<Options extends FieldTypeOptions> = Options extends unknown
+  ? Options['nullable'] extends infer Nullable
+    ? Nullable extends true
+      ? true
+      : false
+    : never
+  : never
 type OptionSelectable<Options extends FieldTypeOptions> = Options extends { selectable: false } ? false : true
 
 export function fieldType<const Type extends ScalarType, const Options extends FieldTypeOptions = Record<never, never>>(
@@ -237,6 +280,27 @@ export function optionalListParameter<const Name extends string, const Type exte
   scalarType: Type,
 ): ListParameterRef<Name, Type, false>
 export const optionalListParam: typeof optionalListParameter
+export function requiredGroupsParameter<
+  const Name extends string,
+  const Key extends ScalarType,
+  const Value extends ScalarType,
+>(name: Name, types: GroupedListParameterTypes<Key, Value>): GroupedListParameterRef<Name, Key, Value, true>
+export const requiredGroupsParam: typeof requiredGroupsParameter
+export function optionalGroupsParameter<
+  const Name extends string,
+  const Key extends ScalarType,
+  const Value extends ScalarType,
+>(name: Name, types: GroupedListParameterTypes<Key, Value>): GroupedListParameterRef<Name, Key, Value, false>
+export const optionalGroupsParam: typeof optionalGroupsParameter
+export function allGroups<
+  const Name extends string,
+  const Key extends ScalarType,
+  const Value extends ScalarType,
+  const Predicate extends ExpressionInput,
+>(
+  parameter: GroupedListParameterRef<Name, Key, Value>,
+  predicate: (group: GroupScope<Key, Value>) => Predicate,
+): TypedExpression<AllGroupsExpression<Name>, 'boolean', InputNullability<Predicate>>
 /** @deprecated Pass a scalar parameter reference directly to an expression factory. */
 export function param<const Name extends string, const Type extends ScalarType>(
   parameter: ScalarParameterRef<Name, Type>,
@@ -248,11 +312,20 @@ export function literal<const Value extends LiteralInput>(
 export function integer(value: number): TypedExpression<LiteralExpression, 'int64', false>
 export function decimal(value: string | number): TypedExpression<LiteralExpression, 'decimal', false>
 
-type EqualityNullability<Left extends ExpressionInput, Right extends ExpressionInput> = null extends
-  | InputScalarType<Left>
-  | InputScalarType<Right>
+// A null literal becomes IS NULL / IS NOT NULL, so literals do not add equality nullability.
+type EqualityOperandNullability<Input extends ExpressionInput> = Input extends LiteralExpression
   ? false
-  : AnyInputNullability<readonly [Left, Right]>
+  : InputNullability<Input>
+
+type EqualityNullability<Left extends ExpressionInput, Right extends ExpressionInput> = Left extends unknown
+  ? Right extends unknown
+    ? [InputScalarType<Left>] extends [null]
+      ? false
+      : [InputScalarType<Right>] extends [null]
+        ? false
+        : AnyNullability<readonly [EqualityOperandNullability<Left>, EqualityOperandNullability<Right>]>
+    : never
+  : never
 
 export function eq<const Left extends ExpressionInput, const Right extends ExpressionInput>(
   left: Left,
@@ -297,6 +370,10 @@ export function inParameter<
   expression: Value,
   parameter: ListParameterRef<Name, Type>,
 ): TypedExpression<InParameterExpression<Name>, 'boolean', InputNullability<Value>>
+export function inParameter<const Value extends ExpressionInput, const Type extends ScalarType>(
+  expression: Value,
+  values: GroupValuesRef<Type>,
+): TypedExpression<InGroupValuesExpression, 'boolean', InputNullability<Value>>
 export const inParam: typeof inParameter
 export function or<const Expressions extends readonly ExpressionInput[]>(
   ...expressions: Expressions

package/types/composition.d.ts

@@ -12,35 +12,17 @@ import type {
   DefinitionParameter,
   DefinitionProjectionField,
   DefinitionProjectionPath,
-  OperationParameters,
+  OperationParameterInput,
+  OptionalParameter,
   OracleCompileOptions,
   ParameterValue,
   QueryOperationBase,
   RelationalQueryGraph,
+  RequiredParameter,
   SqlServerCompileOptions,
 } from './runtime.js'
 import type { ListParameterRef } from './authoring.js'
 
-type RequiredParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
-  ? Parameter extends { required?: true }
-    ? Parameter
-    : never
-  : never
-
-type OptionalParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
-  ? Parameter extends { required?: true }
-    ? never
-    : Parameter
-  : never
-
-type OperationParameterInput<Definition extends GraphDefinitionInput> = [DefinitionParameter<Definition>] extends [
-  never,
-]
-  ? { parameters?: never }
-  : [RequiredParameter<DefinitionParameter<Definition>>] extends [never]
-    ? { parameters?: OperationParameters<Definition> }
-    : { parameters: OperationParameters<Definition> }
-
 type ProjectionFieldPath<Field> =
   Field extends ProjectionTypeMetadata<infer Path, infer _Type, infer _Nullability, infer _SelectedByDefault>
     ? Path

package/types/model.d.ts

@@ -24,7 +24,7 @@ export type ScalarParameterValue<Type extends ScalarType> = Type extends 'boolea
           ? JsonValue
           : never
 
-export type ParameterShape = 'scalar' | 'list'
+export type ParameterShape = 'scalar' | 'list' | 'groupedList'
 export type RelationCardinality = 'one' | 'many'
 export type OrderDirection = 'asc' | 'desc'
 export type NullsOrder = 'first' | 'last'
@@ -86,6 +86,7 @@ export interface ParameterDefinition {
   name: string
   scalarType: ScalarType
   shape?: ParameterShape
+  keyType?: ScalarType
   required?: boolean
 }
 
@@ -144,6 +145,24 @@ export interface InParameterExpression<Name extends string = string> {
   parameter: Name
 }
 
+export interface GroupKeyExpression {
+  kind: 'groupKey'
+  scope: string
+}
+
+export interface InGroupValuesExpression {
+  kind: 'inGroupValues'
+  expression: Expression
+  scope: string
+}
+
+export interface AllGroupsExpression<Name extends string = string> {
+  kind: 'allGroups'
+  parameter: Name
+  scope: string
+  predicate: Expression
+}
+
 export interface ExpressionGroup {
   kind: 'and' | 'or'
   expressions: Expression[]
@@ -181,6 +200,9 @@ export type Expression =
   | LikeExpression
   | InExpression
   | InParameterExpression
+  | GroupKeyExpression
+  | InGroupValuesExpression
+  | AllGroupsExpression
   | ExpressionGroup
   | UnaryExpression
   | ExistsExpression
@@ -376,7 +398,7 @@ export interface FirstBySelection {
 export type RelationSelection = FirstBySelection
 
 export interface GraphDefinitionInput {
-  schemaVersion: 11
+  schemaVersion: 12
   name: string
   root: string
   sources: SourceDefinition[]

package/types/runtime.d.ts

@@ -6,6 +6,7 @@ import type {
   ProjectionDefinitionInput,
   RelationalMapping,
   ScalarParameterValue,
+  ScalarType,
 } from './model.js'
 
 export interface QueryOperationBase<SelectPath extends string = string, OrderingName extends string = string> {
@@ -66,17 +67,22 @@ export type DefinitionRelation<Definition extends GraphDefinitionInput> = NonNul
 
 export type DefinitionRoot<Definition extends GraphDefinitionInput> = Definition['root']
 
-export type ParameterValue<Parameter extends ParameterDefinition> = Parameter extends { shape: 'list' }
-  ? readonly ScalarParameterValue<Parameter['scalarType']>[]
-  : ScalarParameterValue<Parameter['scalarType']>
+export type ParameterValue<Parameter extends ParameterDefinition> = Parameter extends {
+  shape: 'groupedList'
+  keyType: infer Key extends ScalarType
+}
+  ? readonly { key: ScalarParameterValue<Key>; values: readonly ScalarParameterValue<Parameter['scalarType']>[] }[]
+  : Parameter extends { shape: 'list' }
+    ? readonly ScalarParameterValue<Parameter['scalarType']>[]
+    : ScalarParameterValue<Parameter['scalarType']>
 
-type RequiredParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
+export type RequiredParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
   ? Parameter extends { required?: true }
     ? Parameter
     : never
   : never
 
-type OptionalParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
+export type OptionalParameter<Parameter extends ParameterDefinition> = Parameter extends unknown
   ? Parameter extends { required?: true }
     ? never
     : Parameter
@@ -88,9 +94,9 @@ export type OperationParameters<Definition extends GraphDefinitionInput> = {
   [Parameter in OptionalParameter<DefinitionParameter<Definition>> as Parameter['name']]?: ParameterValue<Parameter>
 }
 
-type OperationParameterInput<Definition extends GraphDefinitionInput> = [DefinitionParameter<Definition>] extends [
-  never,
-]
+export type OperationParameterInput<Definition extends GraphDefinitionInput> = [
+  DefinitionParameter<Definition>,
+] extends [never]
   ? { parameters?: never }
   : [RequiredParameter<DefinitionParameter<Definition>>] extends [never]
     ? { parameters?: OperationParameters<Definition> }