@query-graph/core 1.1.5 → 1.1.6

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2020 N-API for Rust
+Copyright (c) 2026 Viktor Marichev
+Copyright (c) 2020 N-API for Rust contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,6 +17,7 @@
 - выбор JOIN только для реально запрошенных полей и условий;
 - scalar и list parameters без подстановки значений в SQL;
 - <code>exists</code>, <code>firstBy</code>, nullable projection objects и именованные ordering;
+- вычисляемые проекции с переносимыми строковыми и числовыми функциями;
 - summary-графы с dimensions, measures, <code>GROUP BY</code> и <code>HAVING</code>;
 - batch relations для загрузки коллекций после пагинации root;
 - один семантический definition для SQL Server и Oracle.
@@ -38,8 +39,8 @@ npm install @query-graph/core
 
 ```ts
 import { registerDefinition } from '@query-graph/core'
-import { constraint, defineGraph, eq, param, project, requiredParameter, source } from '@query-graph/core/dsl'
-import type { QueryOperation, ResultOf } from '@query-graph/core/dsl'
+import { constraint, defineGraph, eq, project, requiredParam, source } from '@query-graph/core/dsl'
+import type { ResultOf } from '@query-graph/core/dsl'
 
 const users = source('users', {
   id: 'int64',
@@ -47,7 +48,7 @@ const users = source('users', {
   email: 'string',
 })
 
-const organisationId = requiredParameter('organisationId', 'int64')
+const organisationId = requiredParam('organisationId', 'int64')
 
 const usersDefinition = defineGraph({
   name: 'users',
@@ -56,7 +57,7 @@ const usersDefinition = defineGraph({
   parameters: [organisationId],
   constraints: [
     constraint({
-      predicate: eq(users.field('organisationId'), param(organisationId)),
+      predicate: eq(users.field('organisationId'), organisationId),
     }),
   ],
   projection: [
@@ -76,13 +77,8 @@ const usersGraph = registerDefinition(usersDefinition).withRelationalMapping({
   },
 })
 
-const operation = {
-  select: ['id', 'email'],
-  parameters: { organisationId: 42 },
-} as const satisfies QueryOperation<typeof usersDefinition>
-
-const statement = usersGraph.compileSqlServer(operation, { version: '2022' })
-type UserRow = ResultOf<typeof usersDefinition, typeof operation>
+const statement = usersGraph.compileSqlServer({ parameters: { organisationId: 42 } }, { version: '2022' })
+type UserRow = ResultOf<typeof usersDefinition>
 ```
 
 <code>statement</code> содержит:
@@ -95,16 +91,108 @@ type UserRow = ResultOf<typeof usersDefinition, typeof operation>
 | <code>objects</code>   | presence metadata для nullable вложенных объектов                                 |
 | <code>relations</code> | связи, выбранные planner для этой operation                                       |
 
-Executor берет значения из <code>operation.parameters</code> по
+Executor берет значения из <code>parameters</code> переданной operation по
 <code>bindings</code>, вызывает DB driver и восстанавливает объект по
 <code>columns</code> и <code>objects</code>. Разбирать SQL не нужно.
 
 Тот же mapped graph можно скомпилировать в Oracle:
 
 ```ts
-const oracleStatement = usersGraph.compileOracle(operation, { version: '19c' })
+const oracleStatement = usersGraph.compileOracle({ parameters: { organisationId: 42 } }, { version: '19c' })
+```
+
+## Зачем нужен planner
+
+В реальном графе преимущество проявляется, когда одна definition обслуживает
+разные формы результата:
+
+```text
+orders
+|-- customer
+|   `-- organisation
+|-- latestPayment [firstBy]
+`-- items [batch many]
+
+constraints: organisationId, exists(activePromotion)
+```
+
+<code>ordersDefinition</code> содержит показанные на схеме relations и
+projection. Его небанальные части выглядят так:
+
+```ts
+const latestPayment = relation({
+  name: 'latestPayment',
+  from: orders,
+  to: payments,
+  on: eq(orders.field('id'), payments.field('orderId')),
+  selection: firstBy(desc(payments.field('createdAt'))),
+})
+
+const hasActivePromotion = constraint({
+  predicate: exists(promotions, eq(promotions.field('active'), true)),
+})
+
+const ordersDefinition = defineGraph({
+  name: 'orders',
+  root: orders,
+  sources: [orders, customers, organisations, payments, promotions],
+  parameters: [organisationId],
+  relations: [customer, customerOrganisation, latestPayment, activePromotion],
+  constraints: [byOrganisation, hasActivePromotion],
+  objects: [customerObject, latestPaymentObject],
+  projection: [orderId, customerName, customerOrganisationName, latestPaymentAmount],
+})
+
+const items = batchRelation({
+  name: 'items',
+  from: 'id',
+  query: batchQuery({
+    graph: orderItemsGraph,
+    key: { path: 'orderId', parameter: orderIds },
+  }),
+  cardinality: 'many',
+})
+
+const mappedOrders = registerDefinition(ordersDefinition).withRelationalMapping(orderMapping)
+const ordersGraph = composeGraph({ root: mappedOrders, relations: [items] })
+```
+
+Обычные source и projection declarations здесь свернуты в именованные
+константы. <code>customerObject</code> и <code>latestPaymentObject</code> созданы
+через <code>projectObject</code>, поэтому отсутствующая to-one строка становится
+<code>null</code>.
+
+Одна и та же definition теперь обслуживает дешевый список:
+
+```ts
+const listPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id'],
+  parameters: { organisationId: 42 },
+})
+
+listPlan.root.relations // []
+listPlan.batches // []
+```
+
+И подробное представление:
+
+```ts
+const detailsPlan = ordersGraph.compileSqlServerPlan({
+  select: ['id', 'customer.name', 'latestPayment.amount', 'items.name'],
+  parameters: { organisationId: 42 },
+})
+
+detailsPlan.root.relations.map(({ name }) => name)
+// ['customer', 'latestPayment']
+
+detailsPlan.batches.map(({ name }) => name)
+// ['items']
 ```
 
+Planner не добавляет невыбранную <code>customerOrganisation</code>,
+<code>exists(activePromotion)</code> остается semijoin без размножения root-строк,
+а <code>items</code> загружается одним batch-запросом для всех найденных orders.
+
 ## Модель
 
 ```text
@@ -160,9 +248,9 @@ import { defineGraph, relation, project } from '@query-graph/core/dsl'
 ```
 
 <code>@query-graph/core/definition</code> сохраняет позиционные фабрики только
-для совместимости линии 1.2.x. <code>@query-graph/dsl-object</code> остается
-тонким deprecated facade над <code>@query-graph/core/dsl</code>. Новому коду эти
-entrypoint не нужны.
+для обратной совместимости с ранним API 1.x.
+<code>@query-graph/dsl-object</code> остается тонким deprecated facade над
+<code>@query-graph/core/dsl</code>. Новому коду эти entrypoint не нужны.
 
 Batch-фабрики временно доступны из package root, но новый код должен импортировать
 их из <code>@query-graph/core/dsl</code>.
@@ -177,7 +265,3 @@ JavaScript.
 SQL execution намеренно остается у потребителя. Это позволяет использовать
 любой pool, transaction model, tracing и политику retry, не связывая planner с
 конкретным DB driver.
-
-### Rule 34
-
-Every sufficiently generic abstraction eventually gets an implementation.

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: 10
+export const GRAPH_DEFINITION_VERSION: 11
 
 /** @deprecated Use `source.field(name)` from `@query-graph/core/dsl`. */
 export function field<

package/definition.js

@@ -65,13 +65,17 @@ exports.hidden = objectDsl.hidden
 exports.source = objectDsl.source
 exports.field = field
 exports.requiredParameter = objectDsl.requiredParameter
+exports.requiredParam = objectDsl.requiredParam
 exports.optionalParameter = objectDsl.optionalParameter
+exports.optionalParam = objectDsl.optionalParam
 exports.param = objectDsl.param
 exports.literal = objectDsl.literal
 exports.integer = objectDsl.integer
 exports.decimal = objectDsl.decimal
 exports.requiredListParameter = objectDsl.requiredListParameter
+exports.requiredListParam = objectDsl.requiredListParam
 exports.optionalListParameter = objectDsl.optionalListParameter
+exports.optionalListParam = objectDsl.optionalListParam
 exports.eq = objectDsl.eq
 exports.neq = objectDsl.neq
 exports.lt = objectDsl.lt
@@ -86,11 +90,15 @@ exports.not = objectDsl.not
 exports.isNull = objectDsl.isNull
 exports.isNotNull = objectDsl.isNotNull
 exports.inParameter = objectDsl.inParameter
+exports.inParam = objectDsl.inParam
 exports.exists = objectDsl.exists
 exports.lower = objectDsl.lower
 exports.upper = objectDsl.upper
 exports.coalesce = objectDsl.coalesce
 exports.concat = objectDsl.concat
+exports.divide = objectDsl.divide
+exports.truncate = objectDsl.truncate
+exports.modulo = objectDsl.modulo
 exports.count = objectDsl.count
 exports.countDistinct = objectDsl.countDistinct
 exports.sum = objectDsl.sum

package/docs/authoring.md

@@ -1,7 +1,7 @@
 # Authoring DSL
 
 Authoring API находится в <code>@query-graph/core/dsl</code>. Он создает
-семантический definition версии 10, который не содержит таблиц, SQL aliases или
+семантический definition версии 11, который не содержит таблиц, SQL aliases или
 синтаксиса диалекта.
 
 ## Sources и поля
@@ -22,13 +22,18 @@ const users = source('users', {
 ## Параметры
 
 ```ts
-const id = requiredParameter('id', 'int64')
-const status = optionalParameter('status', 'string')
-const ids = requiredListParameter('ids', 'int64')
+const id = requiredParam('id', 'int64')
+const status = optionalParam('status', 'string')
+const ids = requiredListParam('ids', 'int64')
+const optionalIds = optionalListParam('optionalIds', 'int64')
 ```
 
-Scalar parameter используется через <code>param</code>, list parameter через
-<code>inParameter</code>. Optional parameter не активирует constraint с
+Scalar parameter передается в expression напрямую, list parameter используется
+через <code>inParam</code>. Явная форма <code>param(id)</code> поддерживается
+для совместимости. Полные имена <code>requiredParameter</code>,
+<code>optionalParameter</code>, <code>requiredListParameter</code>,
+<code>optionalListParameter</code> и <code>inParameter</code> остаются алиасами
+тех же factories. Optional parameter не активирует constraint с
 <code>when</code>, пока значение отсутствует.
 
 ## Expressions
@@ -37,11 +42,34 @@ DSL предоставляет сравнения, boolean groups, null tests, s
 агрегаты и literals:
 
 ```ts
-const predicate = and(eq(users.field('organisationId'), param(organisationId)), isNull(users.field('dateDelete')))
+const predicate = and(eq(users.field('organisationId'), organisationId), isNull(users.field('dateDelete')))
 ```
 
-Типы operands проверяются TypeScript во время authoring и повторно Rust при
-регистрации.
+Semantic functions позволяют оставить вычисляемые поля частью графа, не
+привязывая definition к синтаксису Oracle или SQL Server:
+
+```ts
+const durationProjection = [
+  project({
+    path: 'hoursDuration',
+    expression: truncate(divide(services.field('durationMinutes'), 60)),
+  }),
+  project({
+    path: 'minutesDuration',
+    expression: modulo(services.field('durationMinutes'), 60),
+  }),
+]
+```
+
+<code>divide</code> возвращает decimal для точных числовых типов и float64,
+если хотя бы один operand имеет тип float64. <code>truncate</code> отбрасывает
+дробную часть по направлению к нулю и сохраняет scalar type. <code>modulo</code>
+принимает int32, int64 и decimal; float64 отклоняется, чтобы definition одинаково
+работал в поддерживаемых диалектах. Nullability распространяется от operands к
+результату.
+
+TypeScript выводит тип и nullability результата во время authoring. Rust при
+регистрации повторно проверяет arity и совместимость типов operands.
 
 ## Relations
 
@@ -72,7 +100,7 @@ const profileRelation = relation({
 ```ts
 constraint({
   when: organisationId,
-  predicate: eq(users.field('organisationId'), param(organisationId)),
+  predicate: eq(users.field('organisationId'), organisationId),
 })
 
 constraint({

package/docs/composition.md

@@ -19,7 +19,7 @@ Many-связь в одном SQL может размножить root-стро
 Child-модуль один раз закрепляет контракт ключа:
 
 ```ts
-const itemIds = requiredListParameter('itemIds', 'int64')
+const itemIds = requiredListParam('itemIds', 'int64')
 
 const childrenQuery = batchQuery({
   graph: childrenGraph,

package/docs/diagnostics.md

@@ -47,6 +47,6 @@ JavaScript.
 
 ## Совместимость diagnostics
 
-Wire schema остается версии 10. В совместимых выпусках сохраняются diagnostic
+Wire schema остается версии 11. В совместимых выпусках сохраняются diagnostic
 codes и locations. Message предназначен человеку и не должен использоваться как
 machine-readable contract.

package/docs/sql.md

@@ -33,6 +33,18 @@ const oracle = graph.compileOracle(operation, { version: '19c' })
 Version capabilities проверяются до возврата SQL. Например, pagination и
 <code>firstBy</code> могут требовать более новую версию диалекта.
 
+Semantic functions рендерятся с одинаковым поведением через разные конструкции
+диалектов:
+
+| DSL                              | Oracle                        | SQL Server                        |
+| -------------------------------- | ----------------------------- | --------------------------------- |
+| <code>divide(left, right)</code> | <code>left / right</code>     | дробное <code>left / right</code> |
+| <code>truncate(value)</code>     | <code>TRUNC(value)</code>     | <code>ROUND(value, 0, 1)</code>   |
+| <code>modulo(left, right)</code> | <code>MOD(left, right)</code> | <code>left % right</code>         |
+
+SQL Server compiler принудительно переводит <code>divide</code> в дробную
+арифметику, чтобы два integer operands не дали integer division.
+
 ## Bindings
 
 Compiler никогда не вставляет operation values в SQL. Каждый binding содержит:

package/dsl.d.ts

@@ -120,9 +120,13 @@ export {
   hidden,
   source,
   requiredParameter,
+  requiredParam,
   optionalParameter,
+  optionalParam,
   requiredListParameter,
+  requiredListParam,
   optionalListParameter,
+  optionalListParam,
   param,
   literal,
   integer,
@@ -137,6 +141,7 @@ export {
   inList,
   and,
   inParameter,
+  inParam,
   or,
   not,
   isNull,
@@ -146,6 +151,9 @@ export {
   upper,
   coalesce,
   concat,
+  divide,
+  truncate,
+  modulo,
   count,
   countDistinct,
   sum,

package/dsl.js

@@ -9,13 +9,17 @@ exports.nullable = primitives.nullable
 exports.hidden = primitives.hidden
 exports.source = primitives.source
 exports.requiredParameter = primitives.requiredParameter
+exports.requiredParam = primitives.requiredParam
 exports.optionalParameter = primitives.optionalParameter
+exports.optionalParam = primitives.optionalParam
 exports.param = primitives.param
 exports.literal = primitives.literal
 exports.integer = primitives.integer
 exports.decimal = primitives.decimal
 exports.requiredListParameter = primitives.requiredListParameter
+exports.requiredListParam = primitives.requiredListParam
 exports.optionalListParameter = primitives.optionalListParameter
+exports.optionalListParam = primitives.optionalListParam
 exports.eq = primitives.eq
 exports.neq = primitives.neq
 exports.lt = primitives.lt
@@ -30,11 +34,15 @@ exports.not = primitives.not
 exports.isNull = primitives.isNull
 exports.isNotNull = primitives.isNotNull
 exports.inParameter = primitives.inParameter
+exports.inParam = primitives.inParam
 exports.exists = primitives.exists
 exports.lower = primitives.lower
 exports.upper = primitives.upper
 exports.coalesce = primitives.coalesce
 exports.concat = primitives.concat
+exports.divide = primitives.divide
+exports.truncate = primitives.truncate
+exports.modulo = primitives.modulo
 exports.count = primitives.count
 exports.countDistinct = primitives.countDistinct
 exports.sum = primitives.sum

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 = 10
+const GRAPH_DEFINITION_VERSION = 11
 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,7 @@
 'use strict'
 
 const { arrayOf, configurationOf, nonEmptyString, objectOf, optionalBoolean } = require('../configuration.js')
-const { SUMMARY_FIELD_BRAND } = require('./symbols.js')
+const { PARAMETER_REF_BRAND, SUMMARY_FIELD_BRAND } = require('./symbols.js')
 
 const SCALAR_TYPES = new Set([
   'boolean',
@@ -266,6 +266,18 @@ function concat(first, ...rest) {
   return call('concat', first, ...rest)
 }
 
+function divide(left, right) {
+  return call('divide', left, right)
+}
+
+function truncate(expression) {
+  return call('truncate', expression)
+}
+
+function modulo(left, right) {
+  return call('modulo', left, right)
+}
+
 function aggregate(functionName, expression) {
   const definition = {
     kind: 'aggregate',
@@ -325,6 +337,7 @@ function parameterDefinition(name, scalarType, required, shape = 'scalar') {
   if (shape === 'list') {
     definition.shape = 'list'
   }
+  Object.defineProperty(definition, PARAMETER_REF_BRAND, { value: true })
   return definition
 }
 
@@ -354,6 +367,9 @@ function asExpression(value) {
   if (value?.[SUMMARY_FIELD_BRAND] === true) {
     return value.expression
   }
+  if (value?.[PARAMETER_REF_BRAND] === true) {
+    return param(value)
+  }
   if (value && typeof value === 'object' && typeof value.kind === 'string') {
     return value
   }
@@ -399,6 +415,7 @@ module.exports = {
   count,
   countDistinct,
   decimal,
+  divide,
   eq,
   exists,
   fieldType,
@@ -406,6 +423,7 @@ module.exports = {
   gte,
   hidden,
   inList,
+  inParam: inParameter,
   inParameter,
   integer,
   isNotNull,
@@ -417,17 +435,23 @@ module.exports = {
   lte,
   maximum,
   minimum,
+  modulo,
   neq,
   not,
   nullable,
+  optionalListParam: optionalListParameter,
   optionalListParameter,
+  optionalParam: optionalParameter,
   optionalParameter,
   or,
   param,
   referenceName,
+  requiredListParam: requiredListParameter,
   requiredListParameter,
+  requiredParam: requiredParameter,
   requiredParameter,
   source,
   sum,
+  truncate,
   upper,
 }

package/lib/authoring/symbols.js

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

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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+        bindingPackageVersion !== '1.1.6' &&
         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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+          `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+            bindingPackageVersion !== '1.1.6' &&
             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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+              `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5' &&
+          bindingPackageVersion !== '1.1.6' &&
           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.5 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`,
+            `Native binding package version mismatch, expected 1.1.6 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.5",
+  "version": "1.1.6",
   "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.5",
-    "@query-graph/core-darwin-x64": "1.1.5",
-    "@query-graph/core-linux-x64-gnu": "1.1.5",
-    "@query-graph/core-darwin-arm64": "1.1.5"
+    "@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"
   }
 }

package/types/authoring.d.ts

@@ -84,11 +84,14 @@ export interface SourceRef<Key extends string = string, Fields extends FieldSpec
   >
 }
 
+declare const parameterRefBrand: unique symbol
+
 export interface ScalarParameterRef<
   Name extends string = string,
   Type extends ScalarType = ScalarType,
   Required extends boolean = boolean,
 > extends ParameterDefinition {
+  readonly [parameterRefBrand]: true
   name: Name
   scalarType: Type
   shape?: 'scalar'
@@ -100,6 +103,7 @@ export interface ListParameterRef<
   Type extends ScalarType = ScalarType,
   Required extends boolean = boolean,
 > extends ParameterDefinition {
+  readonly [parameterRefBrand]: true
   name: Name
   scalarType: Type
   shape: 'list'
@@ -121,7 +125,7 @@ export type RelationRef<
 > = RelationDefinition<Name, From, To, Required, Cardinality>
 
 export type LiteralInput = null | boolean | string | number
-export type ExpressionInput = Expression | LiteralInput | SummaryFieldDefinition
+export type ExpressionInput = Expression | LiteralInput | ScalarParameterRef | SummaryFieldDefinition
 
 type NumberLiteralScalarType<Value extends number> = number extends Value
   ? 'int64' | 'decimal'
@@ -134,26 +138,30 @@ type InputScalarType<Input extends ExpressionInput> =
     ? Type
     : Input extends ProjectionFieldDefinition<infer _Path, infer Type, infer _Nullability, infer _SelectedByDefault>
       ? Type
-      : Input extends null
-        ? null
-        : Input extends boolean
-          ? 'boolean'
-          : Input extends string
-            ? 'string'
-            : Input extends number
-              ? NumberLiteralScalarType<Input>
-              : ScalarType
+      : Input extends ScalarParameterRef<infer _Name, infer Type, infer _Required>
+        ? Type
+        : Input extends null
+          ? null
+          : Input extends boolean
+            ? 'boolean'
+            : Input extends string
+              ? 'string'
+              : Input extends number
+                ? NumberLiteralScalarType<Input>
+                : ScalarType
 
 type InputNullability<Input extends ExpressionInput> =
   Input extends ExpressionTypeMetadata<infer _Type, infer Nullability>
     ? Nullability
     : Input extends ProjectionFieldDefinition<infer _Path, infer _Type, infer Nullability, infer _SelectedByDefault>
       ? Nullability
-      : Input extends null
-        ? true
-        : Input extends Expression
-          ? boolean
-          : false
+      : Input extends ScalarParameterRef
+        ? false
+        : Input extends null
+          ? true
+          : Input extends Expression
+            ? boolean
+            : false
 
 export type ExpressionScalarType<Input extends ExpressionInput> = InputScalarType<Input>
 export type ExpressionNullability<Input extends ExpressionInput> = InputNullability<Input>
@@ -176,6 +184,8 @@ type AverageScalarType<Type extends ScalarType | null> = Type extends 'float64'
     ? 'decimal'
     : Exclude<Type, null>
 
+type DivideScalarType<Type extends ScalarType | null> = 'float64' extends Type ? 'float64' : 'decimal'
+
 type InputNullabilities<Inputs extends readonly ExpressionInput[]> = {
   [Index in keyof Inputs]: InputNullability<Inputs[Index]>
 }
@@ -211,18 +221,23 @@ export function requiredParameter<const Name extends string, const Type extends
   name: Name,
   scalarType: Type,
 ): ScalarParameterRef<Name, Type, true>
+export const requiredParam: typeof requiredParameter
 export function optionalParameter<const Name extends string, const Type extends ScalarType>(
   name: Name,
   scalarType: Type,
 ): ScalarParameterRef<Name, Type, false>
+export const optionalParam: typeof optionalParameter
 export function requiredListParameter<const Name extends string, const Type extends ScalarType>(
   name: Name,
   scalarType: Type,
 ): ListParameterRef<Name, Type, true>
+export const requiredListParam: typeof requiredListParameter
 export function optionalListParameter<const Name extends string, const Type extends ScalarType>(
   name: Name,
   scalarType: Type,
 ): ListParameterRef<Name, Type, false>
+export const optionalListParam: typeof optionalListParameter
+/** @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>,
 ): TypedExpression<ParameterExpression<Name>, Type, false>
@@ -282,6 +297,7 @@ export function inParameter<
   expression: Value,
   parameter: ListParameterRef<Name, Type>,
 ): TypedExpression<InParameterExpression<Name>, 'boolean', InputNullability<Value>>
+export const inParam: typeof inParameter
 export function or<const Expressions extends readonly ExpressionInput[]>(
   ...expressions: Expressions
 ): TypedExpression<ExpressionGroup, 'boolean', AnyInputNullability<Expressions>>
@@ -326,6 +342,25 @@ export function concat<const First extends ExpressionInput, const Rest extends r
   first: First,
   ...rest: Rest
 ): TypedExpression<FunctionExpression, 'string', AllInputNullability<readonly [First, ...Rest]>>
+export function divide<const Left extends ExpressionInput, const Right extends ExpressionInput>(
+  left: Left,
+  right: Right,
+): TypedExpression<
+  FunctionExpression,
+  DivideScalarType<InputScalarType<Left | Right>>,
+  AnyInputNullability<readonly [Left, Right]>
+>
+export function truncate<const Value extends ExpressionInput>(
+  expression: Value,
+): TypedExpression<FunctionExpression, Exclude<InputScalarType<Value>, null>, InputNullability<Value>>
+export function modulo<const Left extends ExpressionInput, const Right extends ExpressionInput>(
+  left: Left,
+  right: Right,
+): TypedExpression<
+  FunctionExpression,
+  PromoteScalarType<InputScalarType<Left | Right>>,
+  AnyInputNullability<readonly [Left, Right]>
+>
 
 export function count(expression?: ExpressionInput): TypedExpression<AggregateExpression, 'int64', false>
 export function countDistinct(expression: ExpressionInput): TypedExpression<AggregateExpression, 'int64', false>

package/types/model.d.ts

@@ -28,7 +28,7 @@ export type ParameterShape = 'scalar' | 'list'
 export type RelationCardinality = 'one' | 'many'
 export type OrderDirection = 'asc' | 'desc'
 export type NullsOrder = 'first' | 'last'
-export type SemanticFunctionName = 'lower' | 'upper' | 'coalesce' | 'concat'
+export type SemanticFunctionName = 'lower' | 'upper' | 'coalesce' | 'concat' | 'divide' | 'truncate' | 'modulo'
 export type AggregateFunctionName = 'count' | 'countDistinct' | 'sum' | 'average' | 'minimum' | 'maximum'
 export type ProjectionFieldRole = 'value' | 'dimension' | 'measure'
 
@@ -376,7 +376,7 @@ export interface FirstBySelection {
 export type RelationSelection = FirstBySelection
 
 export interface GraphDefinitionInput {
-  schemaVersion: 10
+  schemaVersion: 11
   name: string
   root: string
   sources: SourceDefinition[]