@query-graph/core 1.0.0 → 1.1.1

package/README.md

@@ -496,6 +496,63 @@ JavaScript number и десятичная строка, а list-параметр
 типа. Эти проверки существуют только в декларациях TypeScript; сериализация
 definition, N-API вызов, runtime-валидация Rust и SQL compilation не меняются.
 
+### Тип результата проекции
+
+DSL сохраняет scalar type и nullability каждого projection expression в compile-time metadata.
+`ResultOf` строит из этих сведений вложенный тип результата по projection paths:
+
+```ts
+import type { QueryOperation, ResultOf } from '@query-graph/core/dsl'
+
+const operation = {
+  select: ['id', 'profile.displayName'],
+  parameters: { userId: 42 },
+} as const satisfies QueryOperation<typeof definition>
+
+type UserRow = ResultOf<typeof definition, typeof operation>
+// {
+//   id: number | string
+//   profile: { displayName: string | null }
+// }
+```
+
+Если второй аргумент не передан, в результат входят только поля с `default: true`.
+`ResultOf` также принимает тип, возвращенный `registerDefinition`, или mapped graph:
+
+```ts
+type DefaultUserRow = ResultOf<typeof graph>
+// { id: number | string }
+```
+
+Nullability учитывает nullable-поле и всю цепочку optional relations до его source.
+Required relation после optional relation не делает значение обязательным. Семантика
+выражений тоже сохраняется: например, `coalesce(nullableField, 'fallback')` выводится
+как non-null `string`.
+
+Типы значений по умолчанию нейтральны к DB driver: `int64` и `decimal` представлены
+как `number | string`, а `date`, `dateTime` и `binary` - как `string`. Адаптер
+исполнения может передать третьим аргументом собственную полную scalar map:
+
+```ts
+import type { DefaultScalarOutputTypeMap, ResultOf } from '@query-graph/core/dsl'
+
+type DriverScalars = Omit<DefaultScalarOutputTypeMap, 'int64' | 'dateTime'> & {
+  int64: bigint
+  dateTime: Date
+}
+
+type DriverUserRow = ResultOf<typeof definition, typeof operation, DriverScalars>
+```
+
+Для точного учета явного `select` operation должна сохранять literal tuple через
+`as const` или `satisfies`. Это только TypeScript API: wire definition, N-API и
+Rust planner не получают дополнительного runtime state.
+
+`ResultOf` описывает логическую форму одной строки, восстановленную из путей
+проекции. Он не выполняет запрос и не превращает relation `many` в массив.
+Группировка строк, дедупликация и гидратация коллекций остаются ответственностью
+потребителя модуля.
+
 ## Диагностика
 
 Ошибки N-API имеют имя `QueryGraphError` и сохраняют обычный `message` и stack.
@@ -659,3 +716,62 @@ relation `many` для него допустим. Для пагинации вл
 
 Полный пример графа, отображения, операции, сгенерированного SQL и замера
 производительности компиляции находится в `benchmark/bench.ts`.
+
+## Batch-связи и двухфазное выполнение
+
+Поля из отдельного запроса подключаются без изменения обычного relational-графа:
+
+```ts
+const childrenQuery = batchQuery({
+  graph: childrenGraph,
+  key: {
+    path: 'parentId',
+    parameter: parentIds,
+  },
+})
+
+const children = batchRelation({
+  name: 'children',
+  from: 'id',
+  query: childrenQuery,
+  cardinality: 'many',
+})
+
+const graph = composeGraph({ root: rootGraph, relations: [children] })
+const plan = graph.compileOraclePlan({
+  select: ['id', 'children.id'],
+  parameters: {},
+  limit: 20,
+})
+```
+
+`batchQuery` принадлежит child-модулю и один раз закрепляет его graph,
+projection path ключа и list-параметр. Поэтому разные root-графы могут
+переиспользовать query, не повторяя внутренний контракт child-запроса.
+
+`composeGraph` оставляет в JavaScript только декларативный фасад. Проверка
+совместимости ключей и параметров, разделение operation на root и batch-шаги и
+компиляция SQL выполняются в Rust. `compileOraclePlan` или
+`compileSqlServerPlan` сразу компилирует только `plan.root`; child SQL создаётся
+при вызове `compileBatch`. Plan сохраняет выбранные dialect и version, поэтому
+отложенный statement компилируется с теми же настройками, что и root.
+
+Для подготовки child bindings каждый шаг в `plan.batches` также содержит имя
+ключевого параметра `keyParameter` и снимок статических `parameters`. Executor
+объединяет их с `{ [batch.keyParameter]: keys }` и сопоставляет полученные значения
+с возвращёнными `statement.bindings`.
+
+Executor потребителя выполняет `plan.root`, собирает уникальные ненулевые
+значения `parentKey` из `plan.batches`, вызывает
+`plan.compileBatch('children', parentIds)`, выполняет child statement и
+связывает строки по `childKey`. `cardinality: 'one'` означает объект или `null`,
+а `many` — массив. Query-graph не подключается к БД, не дедуплицирует ключи, не
+выполняет statements и не гидратирует результат; при пустом наборе ключей
+executor должен пропустить child-запрос.
+
+Ordering, offset и limit корневой operation применяются только к `plan.root`.
+Batch-связь может задать собственный `ordering`, но child pagination не
+добавляется. Batch-поля выбираются только явно (`children.id`); без prefixed
+path соответствующего шага в `plan.batches` нет. Флаги injection в metadata
+показывают executor, какие ключи были добавлены исключительно для связывания и
+не должны попасть в публичный результат.

package/composition.js

@@ -0,0 +1,126 @@
+'use strict'
+
+const BATCH_QUERY_KEYS = new Set(['graph', 'key'])
+const BATCH_QUERY_KEY_KEYS = new Set(['path', 'parameter'])
+const BATCH_RELATION_KEYS = new Set(['name', 'from', 'query', 'cardinality', 'parameters', 'ordering'])
+const COMPOSE_KEYS = new Set(['root', 'relations'])
+const batchQueryBrand = Symbol('BatchQuery')
+const batchBrand = Symbol('BatchRelation')
+
+function configurationOf(factory, value, allowedKeys) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${factory} expects a configuration object`)
+  }
+
+  const unknownKeys = Reflect.ownKeys(value).filter((key) => typeof key !== 'string' || !allowedKeys.has(key))
+  if (unknownKeys.length > 0) {
+    const label = unknownKeys.length === 1 ? 'field' : 'fields'
+    const keys = unknownKeys.map((key) => JSON.stringify(String(key))).join(', ')
+    throw new TypeError(`${factory} received unknown configuration ${label} ${keys}`)
+  }
+
+  return value
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${label} must be a non-empty string`)
+  }
+  return value
+}
+
+function relationalGraph(value, label) {
+  if (value === null || typeof value !== 'object' || typeof value.compose !== 'function') {
+    throw new TypeError(`${label} must be a RelationalQueryGraph`)
+  }
+  return value
+}
+
+function batchQueryOf(value, label) {
+  if (value === null || typeof value !== 'object' || value[batchQueryBrand] !== true) {
+    throw new TypeError(`${label} must be created by batchQuery`)
+  }
+  return value
+}
+
+function batchQuery(value) {
+  const configuration = configurationOf('batchQuery', value, BATCH_QUERY_KEYS)
+  const graph = relationalGraph(configuration.graph, 'batchQuery.graph')
+  const keyConfiguration = configurationOf('batchQuery.key', configuration.key, BATCH_QUERY_KEY_KEYS)
+  const path = nonEmptyString(keyConfiguration.path, 'batchQuery.key.path')
+  const parameter = nonEmptyString(
+    typeof keyConfiguration.parameter === 'string' ? keyConfiguration.parameter : keyConfiguration.parameter?.name,
+    'batchQuery.key.parameter',
+  )
+
+  return Object.freeze({
+    graph,
+    key: Object.freeze({
+      path,
+      parameter,
+    }),
+    [batchQueryBrand]: true,
+  })
+}
+
+function batchRelation(value) {
+  const configuration = configurationOf('batchRelation', value, BATCH_RELATION_KEYS)
+  const name = nonEmptyString(configuration.name, 'batchRelation.name')
+  if (name.includes('.')) {
+    throw new TypeError('batchRelation.name must be a single projection path segment')
+  }
+
+  const from = nonEmptyString(configuration.from, 'batchRelation.from')
+  const query = batchQueryOf(configuration.query, 'batchRelation.query')
+
+  if (configuration.cardinality !== 'one' && configuration.cardinality !== 'many') {
+    throw new TypeError("batchRelation.cardinality must be 'one' or 'many'")
+  }
+  if (
+    configuration.parameters !== undefined &&
+    (configuration.parameters === null ||
+      typeof configuration.parameters !== 'object' ||
+      Array.isArray(configuration.parameters))
+  ) {
+    throw new TypeError('batchRelation.parameters must be an object')
+  }
+  if (configuration.ordering !== undefined) {
+    nonEmptyString(configuration.ordering, 'batchRelation.ordering')
+  }
+
+  return Object.freeze({
+    name,
+    from,
+    query,
+    cardinality: configuration.cardinality,
+    parameters: Object.freeze({ ...configuration.parameters }),
+    ...(configuration.ordering === undefined ? {} : { ordering: configuration.ordering }),
+    [batchBrand]: true,
+  })
+}
+
+function composeGraph(value) {
+  const configuration = configurationOf('composeGraph', value, COMPOSE_KEYS)
+  const root = relationalGraph(configuration.root, 'composeGraph.root')
+  if (!Array.isArray(configuration.relations)) {
+    throw new TypeError('composeGraph.relations must be an array')
+  }
+
+  return configuration.relations.reduce((graph, relation, index) => {
+    if (relation?.[batchBrand] !== true) {
+      throw new TypeError(`composeGraph.relations[${index}] must be created by batchRelation`)
+    }
+
+    return graph.withBatchRelation(relation.query.graph, {
+      name: relation.name,
+      from: relation.from,
+      to: relation.query.key.path,
+      parameter: relation.query.key.parameter,
+      cardinality: relation.cardinality,
+      parameters: relation.parameters,
+      ...(relation.ordering === undefined ? {} : { ordering: relation.ordering }),
+    })
+  }, root.compose())
+}
+
+module.exports = { batchQuery, batchRelation, composeGraph }

package/definition.d.ts

@@ -2,19 +2,27 @@ export * from './dsl.js'
 
 import type {
   ConstraintDefinition,
-  DimensionDefinition,
   Expression,
   ExpressionInput,
+  ExpressionNullability,
+  ExpressionScalarType,
   FieldExpression,
+  FieldSpecIsNullable,
   FieldSpecMap,
+  FieldSpecScalarType,
   JoinProjectionPath,
-  MeasureDefinition,
   ParameterRef,
-  ProjectionFieldDefinition,
   RelationCardinality,
   RelationRef,
   RelationSelection,
+  ScalarType,
+  SourceFieldNullability,
+  SourceReferenceKey,
   SourceRef,
+  TypedExpression,
+  TypedDimensionDefinition,
+  TypedMeasureDefinition,
+  TypedProjectionField,
 } from './dsl.js'
 
 export const GRAPH_DEFINITION_VERSION: 9
@@ -23,25 +31,41 @@ export function field<
   const Key extends string,
   const Fields extends FieldSpecMap,
   const Name extends Extract<keyof Fields, string>,
->(source: SourceRef<Key, Fields>, name: Name): FieldExpression<Key, Name>
+>(
+  source: SourceRef<Key, Fields>,
+  name: Name,
+): TypedExpression<
+  FieldExpression<Key, Name>,
+  FieldSpecScalarType<Fields[Name]>,
+  SourceFieldNullability<Key, FieldSpecIsNullable<Fields[Name]>>
+>
 export function field<const Source extends string, const Name extends string>(
   source: Source,
   name: Name,
-): FieldExpression<Source, Name>
+): TypedExpression<FieldExpression<Source, Name>, ScalarType, SourceFieldNullability<Source, boolean>>
 
-export interface RelationOptions {
-  required?: boolean
-  cardinality?: RelationCardinality
+export interface RelationOptions<
+  Required extends boolean = boolean,
+  Cardinality extends RelationCardinality = RelationCardinality,
+> {
+  required?: Required
+  cardinality?: Cardinality
   selection?: RelationSelection
 }
 
-export function relation<const Name extends string>(
+export function relation<
+  const Name extends string,
+  const From extends string | SourceRef,
+  const To extends string | SourceRef,
+  const Required extends boolean = false,
+  const Cardinality extends RelationCardinality = 'one',
+>(
   name: Name,
-  from: string | SourceRef,
-  to: string | SourceRef,
+  from: From,
+  to: To,
   on: Expression,
-  options?: RelationOptions,
-): RelationRef<Name>
+  options?: RelationOptions<Required, Cardinality>,
+): RelationRef<Name, SourceReferenceKey<From>, SourceReferenceKey<To>, Required, Cardinality>
 
 export interface ConstraintOptions {
   when?: string | ParameterRef
@@ -49,39 +73,93 @@ export interface ConstraintOptions {
 
 export function constraint(predicate: Expression, options?: ConstraintOptions): ConstraintDefinition
 
-export interface ProjectionOptions {
-  default?: boolean
+export interface ProjectionOptions<SelectedByDefault extends boolean = boolean> {
+  default?: SelectedByDefault
 }
 
-export function project<const Path extends string>(
+export function project<
+  const Path extends string,
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): ProjectionFieldDefinition<Path>
-export function project<const Path extends readonly string[]>(
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedProjectionField<
+  Path,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>
+export function project<
+  const Path extends readonly string[],
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): ProjectionFieldDefinition<JoinProjectionPath<Path>>
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedProjectionField<
+  JoinProjectionPath<Path>,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>
 
-export function dimension<const Path extends string>(
+export function dimension<
+  const Path extends string,
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): DimensionDefinition<Path>
-export function dimension<const Path extends readonly string[]>(
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedDimensionDefinition<
+  Path,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>
+export function dimension<
+  const Path extends readonly string[],
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): DimensionDefinition<JoinProjectionPath<Path>>
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedDimensionDefinition<
+  JoinProjectionPath<Path>,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>
 
-export function measure<const Path extends string>(
+export function measure<
+  const Path extends string,
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): MeasureDefinition<Path>
-export function measure<const Path extends readonly string[]>(
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedMeasureDefinition<
+  Path,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>
+export function measure<
+  const Path extends readonly string[],
+  const Value extends ExpressionInput,
+  const SelectedByDefault extends boolean = false,
+>(
   path: Path,
-  expression: ExpressionInput,
-  options?: ProjectionOptions,
-): MeasureDefinition<JoinProjectionPath<Path>>
+  expression: Value,
+  options?: ProjectionOptions<SelectedByDefault>,
+): TypedMeasureDefinition<
+  JoinProjectionPath<Path>,
+  Extract<ExpressionScalarType<Value>, ScalarType>,
+  ExpressionNullability<Value>,
+  SelectedByDefault
+>

package/definition.js

@@ -102,6 +102,9 @@ exports.relation = relation
 exports.constraint = constraint
 exports.ordering = objectDsl.ordering
 exports.project = project
+exports.batchQuery = objectDsl.batchQuery
+exports.batchRelation = objectDsl.batchRelation
+exports.composeGraph = objectDsl.composeGraph
 exports.dimension = dimension
 exports.measure = measure
 exports.asc = objectDsl.asc