@query-graph/core 1.1.4 → 1.1.5

package/definition.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Import the object authoring API from `@query-graph/core/dsl`.
+ * This compatibility entrypoint will be removed in 2.0.
+ */
 export * from './dsl.js'
 
 import type {
@@ -25,8 +29,10 @@ import type {
   TypedProjectionField,
 } from './dsl.js'
 
+/** @deprecated Import authoring primitives from `@query-graph/core/dsl`. */
 export const GRAPH_DEFINITION_VERSION: 10
 
+/** @deprecated Use `source.field(name)` from `@query-graph/core/dsl`. */
 export function field<
   const Key extends string,
   const Fields extends FieldSpecMap,
@@ -53,6 +59,7 @@ export interface RelationOptions<
   selection?: RelationSelection
 }
 
+/** @deprecated Use `relation({ name, from, to, on, ...options })`. */
 export function relation<
   const Name extends string,
   const From extends string | SourceRef,
@@ -71,12 +78,14 @@ export interface ConstraintOptions {
   when?: string | ParameterRef
 }
 
+/** @deprecated Use `constraint({ predicate, when })`. */
 export function constraint(predicate: Expression, options?: ConstraintOptions): ConstraintDefinition
 
 export interface ProjectionOptions<SelectedByDefault extends boolean = boolean> {
   default?: SelectedByDefault
 }
 
+/** @deprecated Use `project({ path, expression, default })`. */
 export function project<
   const Path extends string,
   const Value extends ExpressionInput,
@@ -106,6 +115,7 @@ export function project<
   SelectedByDefault
 >
 
+/** @deprecated Use `dimension({ path, expression, default })`. */
 export function dimension<
   const Path extends string,
   const Value extends ExpressionInput,
@@ -135,6 +145,7 @@ export function dimension<
   SelectedByDefault
 >
 
+/** @deprecated Use `measure({ path, expression, default })`. */
 export function measure<
   const Path extends string,
   const Value extends ExpressionInput,

package/definition.js

@@ -1,8 +1,7 @@
 'use strict'
 
 const objectDsl = require('./dsl.js')
-
-const GRAPH_DEFINITION_VERSION = 10
+const { GRAPH_DEFINITION_VERSION } = require('./lib/authoring/definition.js')
 
 function field(sourceReference, name) {
   if (typeof sourceReference === 'string') {

package/docs/authoring.md

@@ -0,0 +1,161 @@
+# Authoring DSL
+
+Authoring API находится в <code>@query-graph/core/dsl</code>. Он создает
+семантический definition версии 10, который не содержит таблиц, SQL aliases или
+синтаксиса диалекта.
+
+## Sources и поля
+
+```ts
+import { fieldType, hidden, nullable, source } from '@query-graph/core/dsl'
+
+const users = source('users', {
+  id: 'int64',
+  email: nullable('string'),
+  internalRank: hidden(fieldType('int32', { nullable: true })),
+})
+```
+
+Поле имеет scalar type, nullability и флаг selectable. Hidden-поля можно
+использовать в constraints и relations, но нельзя вывести в projection.
+
+## Параметры
+
+```ts
+const id = requiredParameter('id', 'int64')
+const status = optionalParameter('status', 'string')
+const ids = requiredListParameter('ids', 'int64')
+```
+
+Scalar parameter используется через <code>param</code>, list parameter через
+<code>inParameter</code>. Optional parameter не активирует constraint с
+<code>when</code>, пока значение отсутствует.
+
+## Expressions
+
+DSL предоставляет сравнения, boolean groups, null tests, semantic functions,
+агрегаты и literals:
+
+```ts
+const predicate = and(eq(users.field('organisationId'), param(organisationId)), isNull(users.field('dateDelete')))
+```
+
+Типы operands проверяются TypeScript во время authoring и повторно Rust при
+регистрации.
+
+## Relations
+
+```ts
+const profileRelation = relation({
+  name: 'profile',
+  from: users,
+  to: profiles,
+  on: eq(users.field('id'), profiles.field('userId')),
+  cardinality: 'one',
+  required: false,
+  selection: firstBy(asc(profiles.field('id'))),
+})
+```
+
+- <code>cardinality</code> описывает форму связи: <code>one</code> или
+  <code>many</code>.
+- <code>required</code> определяет, может ли отсутствие связанной строки удалить
+  root из результата.
+- <code>firstBy</code> детерминированно выбирает одну строку среди кандидатов и
+  компилируется через dialect-specific APPLY/LATERAL семантику.
+
+У каждого source должен быть единственный путь от root. Planner использует этот
+инвариант для минимального набора JOIN.
+
+## Constraints и exists
+
+```ts
+constraint({
+  when: organisationId,
+  predicate: eq(users.field('organisationId'), param(organisationId)),
+})
+
+constraint({
+  predicate: exists(memberships, eq(memberships.field('active'), true)),
+})
+```
+
+<code>exists</code> является semijoin: он фильтрует множество root и не
+материализует many relation. В relation predicate корреляция задается явно:
+
+```ts
+exists(flags, flagPredicate, { from: profiles })
+```
+
+## Projection и presence
+
+```ts
+const projection = [
+  project({ path: 'id', expression: users.field('id'), default: true }),
+  projectObject({ path: 'profile', presence: profiles.field('id') }),
+  project({
+    path: 'profile.name',
+    expression: profiles.field('name'),
+    default: true,
+  }),
+]
+```
+
+<code>projectObject</code> позволяет executor отличить отсутствующий to-one
+объект от существующего объекта, все поля которого равны NULL.
+
+## Ordering
+
+```ts
+const byName = ordering({
+  name: 'nameAsc',
+  by: [asc(users.field('name'), { nulls: 'last' })],
+  default: true,
+})
+```
+
+Operation выбирает ordering по имени. SQL expression остается частью
+definition, поэтому потребитель не передает произвольный ORDER BY.
+
+## GraphModule
+
+<code>defineGraphModule</code> объединяет sources, parameters, relations,
+constraints, projection objects и orderings без собственного root:
+
+```ts
+const auditModule = defineGraphModule({
+  name: 'audit',
+  sources: [audit],
+  relations: [auditRelation],
+  projection: [createdAtProjection],
+})
+
+const definition = defineGraph({
+  name: 'users',
+  root: users,
+  modules: [auditModule],
+  sources: [users],
+  projection: [idProjection],
+})
+```
+
+Повторно подключенный тот же constraint object дедуплицируется по identity.
+Конфликтующие sources, parameters, relations и projection paths отклоняются.
+
+## Summary
+
+<code>defineSummaryGraph</code> принимает dimensions и measures:
+
+```ts
+const summary = defineSummaryGraph({
+  name: 'ordersByStatus',
+  root: orders,
+  sources: [orders],
+  dimensions: [dimension({ path: 'status', expression: orders.field('status'), default: true })],
+  measures: [measure({ path: 'count', expression: count(), default: true })],
+})
+```
+
+Dimensions становятся GROUP BY, aggregate constraints становятся HAVING. Rust
+отклоняет nested aggregates, неагрегированные поля вне dimensions и независимые
+many-ветви, которым нужен отдельный aggregate subquery plan.

package/docs/composition.md

@@ -0,0 +1,100 @@
+# Composition
+
+В query-graph есть два разных вида композиции.
+
+- <code>GraphModule</code> расширяет один SQL-граф до регистрации.
+- <code>batchRelation</code> связывает уже зарегистрированные графы несколькими
+  SQL-запросами.
+
+## Когда использовать GraphModule
+
+GraphModule подходит, когда данные безопасно входят в один relational plan:
+to-one связи, общие constraints, набор projection fields или ordering.
+
+Many-связь в одном SQL может размножить root-строки и нарушить пагинацию. Для
+таких полей нужен batch.
+
+## Batch query
+
+Child-модуль один раз закрепляет контракт ключа:
+
+```ts
+const itemIds = requiredListParameter('itemIds', 'int64')
+
+const childrenQuery = batchQuery({
+  graph: childrenGraph,
+  key: {
+    path: 'itemId',
+    parameter: itemIds,
+  },
+})
+```
+
+<code>key.path</code> должен быть projection child-графа.
+<code>key.parameter</code> должен быть list parameter того же scalar type.
+
+## Batch relation
+
+Root-граф подключает child query:
+
+```ts
+const children = batchRelation({
+  name: 'children',
+  from: 'id',
+  query: childrenQuery,
+  cardinality: 'many',
+  parameters: {
+    state: 'active',
+  },
+})
+
+const graph = composeGraph({
+  root: rootGraph,
+  relations: [children],
+})
+```
+
+<code>from</code> является projection path root-графа. Static parameters
+проверяются при композиции. Сам list parameter ключей в <code>parameters</code>
+передавать нельзя: compiled plan заполняет его автоматически.
+
+## Компиляция плана
+
+```ts
+const plan = graph.compileOraclePlan({
+  select: ['id', 'children.id', 'children.name'],
+  parameters: rootParameters,
+})
+```
+
+Planner:
+
+1. отделяет root selection от child selections;
+2. добавляет root key в select, если потребитель его не запросил;
+3. добавляет child key в child select;
+4. компилирует только root statement;
+5. возвращает metadata выбранных batch steps.
+
+Batch relation не компилируется и не выполняется, если ее поля не выбраны.
+
+## Deferred batch
+
+После выполнения root executor собирает уникальные ключи и компилирует один
+child statement:
+
+```ts
+for (const batch of plan.batches) {
+  const keys = collectKeys(rootRows, batch.parentKey)
+  const statement = plan.compileBatch(batch.name, keys)
+  const childRows = await driver.query(statement.sql, bind(statement, keys))
+  attach(rootRows, childRows, batch)
+}
+```
+
+При <code>cardinality: 'many'</code> executor присоединяет массив. При
+<code>cardinality: 'one'</code> он присоединяет объект или NULL. Cardinality
+описывает результат, а не количество SQL-запросов.
+
+Metadata сообщает <code>parentKeyInjected</code> и
+<code>childKeyInjected</code>. Executor может удалить технически добавленные
+ключи после сборки результата.

package/docs/diagnostics.md

@@ -0,0 +1,52 @@
+# Diagnostics
+
+Ошибки Node API представлены как <code>QueryGraphError</code>:
+
+```ts
+try {
+  registerDefinition(definition)
+} catch (error) {
+  if (error instanceof Error && error.name === 'QueryGraphError') {
+    console.table(error.issues)
+  }
+}
+```
+
+Поля ошибки:
+
+- <code>name</code>: всегда <code>QueryGraphError</code>;
+- <code>phase</code>: definition, mapping, composition, operation или sql;
+- <code>code</code>: основной код ошибки;
+- <code>issues</code>: все diagnostics текущей фазы.
+
+Каждый diagnostic содержит stable code, location и message. Location указывает
+на wire path, например
+<code>relations[1].selection.orderBy[0].expression</code>.
+
+## Границы проверки
+
+JavaScript DSL выполняет shallow validation сразу:
+
+- configuration должна быть object;
+- неизвестные ключи отклоняются;
+- boolean и enum options проверяются до построения wire object;
+- пустые обязательные строки отклоняются.
+
+Rust выполняет semantic validation:
+
+- уникальность и topology;
+- ссылки и expression scope;
+- scalar types и parameter shapes;
+- projection conflicts и visibility;
+- aggregate semantics;
+- mapping completeness;
+- operation select, ordering и parameter values.
+
+Такое разделение дает ранние ошибки опечаток, не дублируя planner rules в
+JavaScript.
+
+## Совместимость diagnostics
+
+Wire schema остается версии 10. В совместимых выпусках сохраняются diagnostic
+codes и locations. Message предназначен человеку и не должен использоваться как
+machine-readable contract.

package/docs/sql.md

@@ -0,0 +1,68 @@
+# SQL Compilation
+
+Definition не содержит физическую схему БД. Mapping добавляется после
+регистрации:
+
+```ts
+const graph = registerDefinition(definition).withRelationalMapping({
+  sources: {
+    users: {
+      table: { catalog: 'app', schema: 'dbo', name: 'Users' },
+      columns: { displayName: 'display_name' },
+    },
+  },
+})
+```
+
+Можно передать несколько fragments через
+<code>withRelationalMappings</code>. Одинаковые mappings объединяются,
+конфликтующие table/column names возвращают ошибку фазы mapping.
+
+## Диалекты
+
+```ts
+const sqlServer = graph.compileSqlServer(operation, { version: '2022' })
+const oracle = graph.compileOracle(operation, { version: '19c' })
+```
+
+Поддерживаемые версии:
+
+- SQL Server: 2008, 2012, 2016, 2019, 2022;
+- Oracle: 11g, 12c, 19c, 21c, 23ai.
+
+Version capabilities проверяются до возврата SQL. Например, pagination и
+<code>firstBy</code> могут требовать более новую версию диалекта.
+
+## Bindings
+
+Compiler никогда не вставляет operation values в SQL. Каждый binding содержит:
+
+- SQL placeholder name;
+- имя parameter;
+- scalar type;
+- index элемента для list parameter.
+
+Повторное использование parameter переиспользует binding. Пустой list
+компилируется в ложное условие без placeholders.
+
+## Result metadata
+
+SQL columns получают технические aliases <code>c0</code>,
+<code>c1</code> и так далее. <code>statement.columns</code> хранит logical path,
+scalar type, nullability и relation path. <code>statement.objects</code> хранит
+presence columns для nullable объектов.
+
+Executor должен опираться на metadata, а не анализировать SQL.
+
+## Граница исполнения
+
+query-graph не владеет:
+
+- connection pool и transaction;
+- timeout, cancellation и retry;
+- tracing и logging;
+- преобразованием driver-specific bind values;
+- hydration rows и batch attachment.
+
+Эти обязанности остаются у приложения. Один и тот же graph можно использовать
+с разными executors, пока они соблюдают контракт statement metadata.

package/docs/type-system.md

@@ -0,0 +1,86 @@
+# Type System
+
+TypeScript помогает автору до регистрации, Rust остается авторитетной runtime
+проверкой wire definition.
+
+## Scalar types
+
+| Scalar                         | Operation value   | Результат по умолчанию |
+| ------------------------------ | ----------------- | ---------------------- |
+| boolean                        | boolean           | boolean                |
+| int32, float64                 | number            | number                 |
+| int64, decimal                 | number или string | number или string      |
+| string, date, dateTime, binary | string            | string                 |
+| json                           | JSON value        | JSON value             |
+
+<code>int64</code> принимает number только в безопасном диапазоне JavaScript.
+Decimal string проверяется как конечная десятичная запись.
+
+## QueryOperation
+
+Definition передает свои параметры, projection paths и ordering names в
+operation:
+
+```ts
+const operation = {
+  select: ['id', 'profile.name'],
+  ordering: 'nameAsc',
+  parameters: {
+    organisationId: 42,
+  },
+} as const satisfies QueryOperation<typeof definition>
+```
+
+Required parameters обязательны, optional параметры могут отсутствовать,
+list parameters принимают readonly arrays.
+
+## Nullability
+
+Nullability выражения складывается из:
+
+- nullable исходного поля;
+- optional relation на пути к source;
+- семантики функции;
+- projection object presence.
+
+Required relation под optional ancestor остается nullable. Это свойство
+вычисляется из topology один раз при регистрации.
+
+## ResultOf
+
+```ts
+type Row = ResultOf<typeof definition, typeof operation>
+```
+
+<code>ResultOf</code> строит вложенный объект из выбранных projection paths.
+Если operation не передана, используются поля с <code>default: true</code>.
+Для composed graph выбранные batch relations добавляются как массивы либо
+nullable объекты согласно cardinality.
+
+Driver может заменить представление scalar values:
+
+```ts
+interface DriverScalars extends DefaultScalarOutputTypeMap {
+  int64: bigint
+  decimal: string
+  dateTime: Date
+}
+
+type DriverRow = ResultOf<typeof definition, typeof operation, DriverScalars>
+```
+
+Этот mapping существует только на уровне TypeScript. Wire schema и SQL
+compilation не меняются.
+
+## Runtime checker
+
+Rust проверяет:
+
+- ссылки на sources, fields и parameters;
+- scalar/list shape параметров;
+- совместимость сравнений и функций;
+- boolean тип predicates;
+- orderable и groupable expressions;
+- aggregate context и concrete projection types.
+
+Ошибки собираются в diagnostics с location исходного definition.