@query-graph/core 1.0.0-next.1 → 1.1.0

package/README.md

@@ -55,51 +55,65 @@ import {
   source,
 } from '@query-graph/core/dsl'
 
-const link = source('link', {
-  idOwner: 'int64',
-  idControllerObjectValue: 'int64',
+const users = source('users', {
+  id: 'int64',
+  email: 'string',
 })
 
-const value = source('value', {
+const profiles = source('profiles', {
   id: 'int64',
-  value: nullable('string'),
+  userId: 'int64',
+  displayName: nullable('string'),
 })
 
-const idOwner = requiredParameter('idOwner', 'int64')
-const valueRelation = relation({
-  name: 'value',
-  from: link,
-  to: value,
-  on: eq(link.field('idControllerObjectValue'), value.field('id')),
+const userId = requiredParameter('userId', 'int64')
+const profileRelation = relation({
+  name: 'profile',
+  from: users,
+  to: profiles,
+  on: eq(users.field('id'), profiles.field('userId')),
+  cardinality: 'one',
   required: true,
+  selection: firstBy(asc(profiles.field('id'))),
 })
 
-const attributeValuesModule = defineGraphModule({
-  name: 'attributeValues',
-  sources: [link, value],
-  parameters: [idOwner],
-  relations: [valueRelation],
+const userProfileModule = defineGraphModule({
+  name: 'userProfile',
+  sources: [users, profiles],
+  parameters: [userId],
+  relations: [profileRelation],
   constraints: [
     constraint({
-      predicate: eq(link.field('idOwner'), param(idOwner)),
+      predicate: eq(users.field('id'), param(userId)),
     }),
     constraint({
-      predicate: exists(value, isNotNull(value.field('value'))),
+      predicate: exists(profiles, isNotNull(profiles.field('displayName'))),
     }),
   ],
   projection: [
     project({
-      path: 'value.value',
-      expression: value.field('value'),
+      path: 'id',
+      expression: users.field('id'),
+      default: true,
+    }),
+    project({
+      path: 'profile.displayName',
+      expression: profiles.field('displayName'),
+    }),
+  ],
+  orderings: [
+    ordering({
+      name: 'idAsc',
+      by: [asc(users.field('id'))],
       default: true,
     }),
   ],
 })
 
 const definition = defineGraph({
-  name: 'attributeValues',
-  root: link,
-  modules: [attributeValuesModule],
+  name: 'userProfile',
+  root: users,
+  modules: [userProfileModule],
 })
 
 const graph = registerDefinition(definition)
@@ -149,30 +163,30 @@ npm install @query-graph/core @query-graph/dsl-object
 import { registerDefinition } from '@query-graph/core'
 import { asc, defineGraph, eq, firstBy, project, relation, source } from '@query-graph/dsl-object'
 
-const staff = source('staff', { id: 'int64' })
-const personStaff = source('personStaff', {
+const users = source('users', { id: 'int64' })
+const profiles = source('profiles', {
   id: 'int64',
-  idStaff: 'int64',
-  idPerson: 'int64',
+  userId: 'int64',
+  displayName: 'string',
 })
 
 const definition = defineGraph({
-  name: 'staff',
-  root: staff,
-  sources: [staff, personStaff],
+  name: 'users',
+  root: users,
+  sources: [users, profiles],
   relations: [
     relation({
-      name: 'credentials',
-      from: staff,
-      to: personStaff,
-      on: eq(staff.field('id'), personStaff.field('idStaff')),
+      name: 'profile',
+      from: users,
+      to: profiles,
+      on: eq(users.field('id'), profiles.field('userId')),
       cardinality: 'one',
-      selection: firstBy(asc(personStaff.field('idPerson')), asc(personStaff.field('id'))),
+      selection: firstBy(asc(profiles.field('id'))),
     }),
   ],
   projection: [
-    project({ path: 'id', expression: staff.field('id'), default: true }),
-    project({ path: 'credentials.idPerson', expression: personStaff.field('idPerson') }),
+    project({ path: 'id', expression: users.field('id'), default: true }),
+    project({ path: 'profile.displayName', expression: profiles.field('displayName') }),
   ],
 })
 
@@ -194,7 +208,7 @@ const graph = registerDefinition(definition)
 
 ```ts
 constraint({
-  predicate: exists(businessServiceStaff, eq(businessServiceStaff.field('idService'), param(idService))),
+  predicate: exists(memberships, eq(memberships.field('teamId'), param(teamId))),
 })
 ```
 
@@ -213,7 +227,7 @@ Oracle и SQL Server compiler строят коррелированный `EXIST
 
 ```ts
 constraint({
-  predicate: exists(categoryLinks, categoryPredicate, { from: attributeValues }),
+  predicate: exists(permissions, permissionPredicate, { from: memberships }),
 })
 ```
 
@@ -228,28 +242,38 @@ constraint({
 `number | number[]`.
 
 ```ts
-const idServices = requiredListParameter('idServices', 'int64')
+const users = source('users', {
+  id: 'int64',
+})
+
+const memberships = source('memberships', {
+  id: 'int64',
+  userId: 'int64',
+  teamId: 'int64',
+})
+
+const teamIds = requiredListParameter('teamIds', 'int64')
 
 const definition = defineGraph({
-  name: 'staffByServices',
-  root: staff,
-  sources: [staff, businessServiceStaff],
-  parameters: [idServices],
+  name: 'usersByTeams',
+  root: users,
+  sources: [users, memberships],
+  parameters: [teamIds],
   relations: [
     relation({
-      name: 'staffServices',
-      from: staff,
-      to: businessServiceStaff,
-      on: eq(staff.field('id'), businessServiceStaff.field('idStaff')),
+      name: 'memberships',
+      from: users,
+      to: memberships,
+      on: eq(users.field('id'), memberships.field('userId')),
       cardinality: 'many',
     }),
   ],
   constraints: [
     constraint({
-      predicate: exists(businessServiceStaff, inParameter(businessServiceStaff.field('idService'), idServices)),
+      predicate: exists(memberships, inParameter(memberships.field('teamId'), teamIds)),
     }),
   ],
-  projection: [project({ path: 'id', expression: staff.field('id'), default: true })],
+  projection: [project({ path: 'id', expression: users.field('id'), default: true })],
 })
 ```
 
@@ -257,15 +281,15 @@ Operation передает обычный массив:
 
 ```ts
 const statement = relationalGraph.compileSqlServer({
-  parameters: { idServices: [12, 18, 24] },
+  parameters: { teamIds: [12, 18, 24] },
 })
 ```
 
 Compiler разворачивает его в `IN (@p0, @p1, @p2)`. Каждый элемент получает
-binding `{ parameter: 'idServices', index, scalarType: 'int64' }`, по которому
+binding `{ parameter: 'teamIds', index, scalarType: 'int64' }`, по которому
 adapter исполнения берет значение из исходного массива. Rust проверяет каждый
 элемент отдельно и возвращает путь ошибки наподобие
-`parameters.idServices[2]`.
+`parameters.teamIds[2]`.
 
 Отсутствующий optional list отключает constraint с `when`. Переданный пустой
 список остается присутствующим параметром и компилируется в ложный предикат
@@ -302,12 +326,12 @@ TypeScript выводит union имен из definition и подключенн
 одной строки:
 
 ```ts
-const credentials = relation({
-  name: 'credentials',
-  from: staff,
-  to: personStaff,
-  on: eq(staff.field('id'), personStaff.field('idStaff')),
-  selection: firstBy(asc(personStaff.field('idPerson')), asc(personStaff.field('id'))),
+const profile = relation({
+  name: 'profile',
+  from: users,
+  to: profiles,
+  on: eq(users.field('id'), profiles.field('userId')),
+  selection: firstBy(asc(profiles.field('id'))),
 })
 ```
 
@@ -327,46 +351,60 @@ SQL Server renderer использует `OUTER/CROSS APPLY` и `TOP (1)`, Oracl
 SQL-конструкции `GROUP BY` и `HAVING`:
 
 ```ts
-const serviceId = dimension({
-  path: 'serviceId',
-  expression: service.field('id'),
+const teams = source('teams', {
+  id: 'int64',
+  workspaceId: 'int64',
+})
+
+const memberships = source('memberships', {
+  id: 'int64',
+  userId: 'int64',
+  teamId: 'int64',
+})
+
+const workspaceId = requiredParameter('workspaceId', 'int64')
+const minimumMembers = requiredParameter('minimumMembers', 'int64')
+
+const teamId = dimension({
+  path: 'teamId',
+  expression: teams.field('id'),
   default: true,
 })
 
-const staffCount = measure({
-  path: 'staffCount',
-  expression: countDistinct(serviceStaff.field('idStaff')),
+const memberCount = measure({
+  path: 'memberCount',
+  expression: countDistinct(memberships.field('userId')),
   default: true,
 })
 
 const definition = defineSummaryGraph({
-  name: 'serviceSummary',
-  root: service,
-  sources: [service, serviceStaff],
-  parameters: [idOrganisation, minimumStaff],
+  name: 'teamSummary',
+  root: teams,
+  sources: [teams, memberships],
+  parameters: [workspaceId, minimumMembers],
   relations: [
     relation({
-      name: 'staff',
-      from: service,
-      to: serviceStaff,
-      on: eq(service.field('id'), serviceStaff.field('idService')),
+      name: 'members',
+      from: teams,
+      to: memberships,
+      on: eq(teams.field('id'), memberships.field('teamId')),
       cardinality: 'many',
     }),
   ],
   constraints: [
     constraint({
-      predicate: eq(service.field('idOrganisation'), param(idOrganisation)),
+      predicate: eq(teams.field('workspaceId'), param(workspaceId)),
     }),
     constraint({
-      predicate: gte(staffCount, param(minimumStaff)),
+      predicate: gte(memberCount, param(minimumMembers)),
     }),
   ],
-  dimensions: [serviceId],
-  measures: [staffCount],
+  dimensions: [teamId],
+  measures: [memberCount],
   orderings: [
     ordering({
-      name: 'staffCountDesc',
-      by: [desc(staffCount)],
+      name: 'memberCountDesc',
+      by: [desc(memberCount)],
       default: true,
     }),
   ],
@@ -443,10 +481,9 @@ TypeScript проверяет имена источников, полей и с
 const relationalGraph = registerDefinition(definition).withRelationalMapping(mapping)
 
 relationalGraph.compileSqlServer({
-  select: ['id', 'credentials.idPerson'],
+  select: ['id', 'profile.displayName'],
   parameters: {
-    idOrganisation: 42,
-    personIds: [7, 11],
+    userId: 42,
   },
 })
 ```
@@ -459,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.
@@ -494,18 +588,22 @@ Wire errors, semantic validation и SQL compilation имеют разные ве
 ```ts
 const relationalGraph = graph.withRelationalMapping({
   sources: {
-    link: {
+    users: {
       table: {
         schema: 'dbo',
-        name: 'ControllerAttributeValueLink',
+        name: 'users',
+      },
+    },
+    profiles: {
+      table: {
+        schema: 'dbo',
+        name: 'user_profiles',
       },
       columns: {
-        idOwner: 'owner_id',
+        userId: 'user_id',
+        displayName: 'display_name',
       },
     },
-    value: {
-      table: 'ControllerObjectValue',
-    },
   },
 })
 ```
@@ -515,9 +613,9 @@ const relationalGraph = graph.withRelationalMapping({
 
 ```ts
 const operation = {
-  select: ['value.value'],
+  select: ['id', 'profile.displayName'],
   parameters: {
-    idOwner: 42,
+    userId: 42,
   },
   offset: 0,
   limit: 25,
@@ -532,7 +630,7 @@ console.table(statement.relations)
 ```
 
 `statement.bindings` связывает сгенерированные имена, например `p0`, с
-логическими параметрами, например `idOwner`, и содержит их scalar type.
+логическими параметрами, например `userId`, и содержит их scalar type.
 Потребитель берет значения из `operation.parameters` и передает их
 своему драйверу базы данных.
 

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
+>