@query-graph/core 1.1.0 → 1.1.2

package/dsl.d.ts

@@ -224,11 +224,15 @@ declare const projectionPathType: unique symbol
 declare const projectionScalarType: unique symbol
 declare const projectionNullabilityType: unique symbol
 declare const projectionDefaultType: unique symbol
+declare const projectionObjectPathType: unique symbol
+declare const projectionObjectNullabilityType: unique symbol
 declare const summaryFieldType: unique symbol
 declare const typedProjectionPathType: unique symbol
 declare const typedProjectionScalarType: unique symbol
 declare const typedProjectionNullabilityType: unique symbol
 declare const typedProjectionDefaultType: unique symbol
+declare const typedProjectionObjectPathType: unique symbol
+declare const typedProjectionObjectNullabilityType: unique symbol
 
 export interface ProjectionTypeMetadata<
   Path extends string = string,
@@ -242,6 +246,19 @@ export interface ProjectionTypeMetadata<
   readonly [typedProjectionDefaultType]: SelectedByDefault
 }
 
+export interface ProjectionObjectTypeMetadata<
+  Path extends string = string,
+  Nullability extends NullabilityExpression = NullabilityExpression,
+> {
+  readonly [typedProjectionObjectPathType]: Path
+  readonly [typedProjectionObjectNullabilityType]: Nullability
+}
+
+export type TypedProjectionObject<
+  Path extends string = string,
+  Nullability extends NullabilityExpression = NullabilityExpression,
+> = ProjectionObjectDefinition<Path, Nullability> & ProjectionObjectTypeMetadata<Path, Nullability>
+
 export type TypedProjectionField<
   Path extends string = string,
   Type extends ScalarType = ScalarType,
@@ -282,6 +299,16 @@ export interface ProjectionFieldDefinition<
   selectedByDefault?: boolean
 }
 
+export interface ProjectionObjectDefinition<
+  Path extends string = string,
+  Nullability extends NullabilityExpression = NullabilityExpression,
+> {
+  path: string[]
+  readonly [projectionObjectPathType]?: Path
+  readonly [projectionObjectNullabilityType]?: Nullability
+  presence: Expression
+}
+
 export interface DimensionDefinition<
   Path extends string = string,
   Type extends ScalarType = ScalarType,
@@ -314,15 +341,19 @@ export type SummaryFieldDefinition<
 export interface ProjectionDefinition<
   Path extends string = string,
   Field extends ProjectionFieldDefinition = ProjectionFieldDefinition<Path>,
+  Object extends ProjectionObjectDefinition = ProjectionObjectDefinition,
 > {
   fields: Field[]
+  objects: Object[]
 }
 
 export interface ProjectionDefinitionInput<
   Path extends string = string,
   Field extends ProjectionFieldDefinition = ProjectionFieldDefinition<Path>,
+  Object extends ProjectionObjectDefinition = ProjectionObjectDefinition,
 > {
   fields?: Field[]
+  objects?: Object[]
 }
 
 export interface OrderByDefinition {
@@ -345,7 +376,7 @@ export interface FirstBySelection {
 export type RelationSelection = FirstBySelection
 
 export interface GraphDefinitionInput {
-  schemaVersion: 9
+  schemaVersion: 10
   name: string
   root: string
   sources: SourceDefinition[]
@@ -363,12 +394,13 @@ export interface GraphDefinition<
   ProjectionField extends ProjectionFieldDefinition = ProjectionFieldDefinition<ProjectionPath>,
   Relation extends RelationDefinition = RelationDefinition,
   Root extends string = string,
+  ProjectionObject extends ProjectionObjectDefinition = ProjectionObjectDefinition,
 > extends GraphDefinitionInput {
   root: Root
   parameters: Parameter[]
   relations: Relation[]
   constraints: ConstraintDefinition[]
-  projection: ProjectionDefinition<ProjectionPath, ProjectionField>
+  projection: ProjectionDefinition<ProjectionPath, ProjectionField, ProjectionObject>
   orderings: OrderingDefinition<OrderingName>[]
 }
 
@@ -442,6 +474,9 @@ export type DefinitionOrderingName<Definition extends GraphDefinitionInput> =
 export type DefinitionProjectionField<Definition extends GraphDefinitionInput> = NonNullable<
   NonNullable<Definition['projection']>['fields']
 >[number]
+export type DefinitionProjectionObject<Definition extends GraphDefinitionInput> = NonNullable<
+  NonNullable<Definition['projection']>['objects']
+>[number]
 
 export type DefinitionRelation<Definition extends GraphDefinitionInput> = NonNullable<Definition['relations']>[number]
 
@@ -512,6 +547,278 @@ export interface RelationalQueryGraph<Definition extends GraphDefinitionInput =
   ): import('./index.js').CompiledSqlStatement
 }
 
+export type BatchCardinality = RelationCardinality
+
+export interface BatchRelationWire {
+  name: string
+  from: string
+  to: string
+  parameter: string
+  cardinality: BatchCardinality
+  parameters?: Record<string, unknown>
+  ordering?: string
+}
+
+type ListDefinitionParameter<Definition extends GraphDefinitionInput> =
+  DefinitionParameter<Definition> extends infer Parameter extends ParameterDefinition
+    ? Parameter extends { shape: 'list' }
+      ? Parameter
+      : never
+    : never
+
+type ListParameterReference<Definition extends GraphDefinitionInput> =
+  | ListDefinitionParameter<Definition>
+  | ListDefinitionParameter<Definition>['name']
+
+type ParameterReferenceName<Reference> = Reference extends { name: infer Name extends string }
+  ? Name
+  : Reference extends string
+    ? Reference
+    : never
+
+type ResolveListParameter<Definition extends GraphDefinitionInput, Reference> = Extract<
+  ListDefinitionParameter<Definition>,
+  { name: ParameterReferenceName<Reference> }
+>
+
+type BatchStaticParameterCandidate<
+  Parameter extends ParameterDefinition,
+  KeyName extends string,
+> = Parameter extends ParameterDefinition ? (Parameter['name'] extends KeyName ? never : Parameter) : never
+
+type BatchStaticParameter<
+  Definition extends GraphDefinitionInput,
+  KeyName extends string,
+> = BatchStaticParameterCandidate<DefinitionParameter<Definition>, KeyName>
+
+type BatchStaticParameters<Definition extends GraphDefinitionInput, KeyName extends string> = {
+  [Parameter in RequiredParameter<
+    BatchStaticParameter<Definition, KeyName>
+  > as Parameter['name']]-?: ParameterValue<Parameter>
+} & {
+  [Parameter in OptionalParameter<
+    BatchStaticParameter<Definition, KeyName>
+  > as Parameter['name']]?: ParameterValue<Parameter>
+}
+
+type BatchStaticParameterInput<Definition extends GraphDefinitionInput, KeyName extends string> = [
+  BatchStaticParameter<Definition, KeyName>,
+] extends [never]
+  ? { parameters?: never }
+  : [RequiredParameter<BatchStaticParameter<Definition, KeyName>>] extends [never]
+    ? { parameters?: BatchStaticParameters<Definition, KeyName> }
+    : { parameters: BatchStaticParameters<Definition, KeyName> }
+
+declare const batchQueryType: unique symbol
+
+export interface BatchQuery<
+  Child extends RelationalQueryGraph = RelationalQueryGraph,
+  KeyPath extends string = string,
+  KeyParameter extends ParameterDefinition & { shape: 'list' } = ListParameterRef,
+> {
+  readonly graph: Child
+  readonly key: {
+    readonly path: KeyPath
+    readonly parameter: KeyParameter['name']
+  }
+  readonly [batchQueryType]?: KeyParameter
+}
+
+export type BatchQueryConfiguration<
+  Child extends RelationalQueryGraph,
+  KeyPath extends DefinitionProjectionPath<DefinitionOf<Child>>,
+  ParameterReference extends ListParameterReference<DefinitionOf<Child>>,
+> = {
+  graph: Child
+  key: {
+    path: KeyPath
+    parameter: ParameterReference
+  }
+}
+
+type CompatibleBatchQueryConfiguration<
+  Child extends RelationalQueryGraph,
+  KeyPath extends DefinitionProjectionPath<DefinitionOf<Child>>,
+  KeyParameter extends ParameterDefinition & { shape: 'list' },
+> =
+  EqualScalarType<ProjectionScalarTypeAtPath<DefinitionOf<Child>, KeyPath>, KeyParameter['scalarType']> extends true
+    ? unknown
+    : never
+
+export function batchQuery<
+  const Child extends RelationalQueryGraph,
+  const KeyPath extends DefinitionProjectionPath<DefinitionOf<Child>>,
+  const ParameterReference extends ListParameterReference<DefinitionOf<Child>>,
+>(
+  configuration: BatchQueryConfiguration<Child, KeyPath, ParameterReference> &
+    CompatibleBatchQueryConfiguration<
+      Child,
+      KeyPath,
+      ResolveListParameter<DefinitionOf<Child>, NoInfer<ParameterReference>>
+    >,
+): BatchQuery<Child, KeyPath, ResolveListParameter<DefinitionOf<Child>, ParameterReference>>
+
+type BatchQueryGraph<Query extends BatchQuery> =
+  Query extends BatchQuery<infer Child, infer _KeyPath, infer _KeyParameter> ? Child : never
+
+type BatchQueryKeyPath<Query extends BatchQuery> =
+  Query extends BatchQuery<infer _Child, infer KeyPath, infer _KeyParameter> ? KeyPath : never
+
+type BatchQueryKeyParameter<Query extends BatchQuery> =
+  Query extends BatchQuery<infer _Child, infer _KeyPath, infer KeyParameter> ? KeyParameter : never
+
+declare const batchRelationType: unique symbol
+
+export interface BatchRelation<
+  Name extends string = string,
+  Query extends BatchQuery = BatchQuery,
+  From extends string = string,
+  Cardinality extends BatchCardinality = BatchCardinality,
+> {
+  readonly name: Name
+  readonly from: From
+  readonly query: Query
+  readonly cardinality: Cardinality
+  readonly parameters: BatchStaticParameters<
+    DefinitionOf<BatchQueryGraph<Query>>,
+    BatchQueryKeyParameter<Query>['name']
+  >
+  readonly ordering?: DefinitionOrderingName<DefinitionOf<BatchQueryGraph<Query>>>
+  readonly [batchRelationType]?: Query
+}
+
+export type BatchRelationConfiguration<
+  Name extends string,
+  Query extends BatchQuery,
+  From extends string,
+  Cardinality extends BatchCardinality,
+> = {
+  name: Name
+  from: From
+  query: Query
+  cardinality: Cardinality
+  ordering?: DefinitionOrderingName<DefinitionOf<BatchQueryGraph<Query>>>
+} & BatchStaticParameterInput<DefinitionOf<BatchQueryGraph<Query>>, BatchQueryKeyParameter<Query>['name']>
+
+export function batchRelation<
+  const Name extends string,
+  const Query extends BatchQuery,
+  const From extends string,
+  const Cardinality extends BatchCardinality,
+>(
+  configuration: BatchRelationConfiguration<Name, Query, From, Cardinality>,
+): BatchRelation<Name, Query, From, Cardinality>
+
+type ProjectionScalarTypeAtPath<Definition extends GraphDefinitionInput, Path extends string> =
+  ProjectionFieldByPath<DefinitionProjectionField<Definition>, Path> extends infer Field
+    ? Field extends ProjectionTypeMetadata<infer _Path, infer Type, infer _Nullability, infer _SelectedByDefault>
+      ? Type
+      : Field extends ProjectionFieldDefinition<infer _Path, infer Type>
+        ? Type
+        : never
+    : never
+
+type EqualScalarType<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false
+
+type CompatibleBatchRelation<Root extends RelationalQueryGraph, Relation extends BatchRelation> =
+  Relation extends BatchRelation<infer Name, infer Query, infer From, infer _Cardinality>
+    ? From extends DefinitionProjectionPath<DefinitionOf<Root>>
+      ? Extract<DefinitionProjectionPath<DefinitionOf<Root>>, Name | `${Name}.${string}`> extends never
+        ? EqualScalarType<
+            ProjectionScalarTypeAtPath<DefinitionOf<Root>, From>,
+            ProjectionScalarTypeAtPath<DefinitionOf<BatchQueryGraph<Query>>, BatchQueryKeyPath<Query>>
+          > extends true
+          ? EqualScalarType<
+              ProjectionScalarTypeAtPath<DefinitionOf<BatchQueryGraph<Query>>, BatchQueryKeyPath<Query>>,
+              BatchQueryKeyParameter<Query>['scalarType']
+            > extends true
+            ? Relation
+            : never
+          : never
+        : never
+      : never
+    : never
+
+type CompatibleBatchRelations<Root extends RelationalQueryGraph, Relations extends readonly BatchRelation[]> = {
+  readonly [Index in keyof Relations]: Relations[Index] extends BatchRelation
+    ? CompatibleBatchRelation<Root, Relations[Index]>
+    : never
+}
+
+type RelationName<Relations extends readonly BatchRelation[]> = Relations[number]['name']
+type ChildPathsForRelation<Relation extends BatchRelation> = Relation extends BatchRelation
+  ? `${Relation['name']}.${DefinitionProjectionPath<DefinitionOf<BatchQueryGraph<Relation['query']>>>}`
+  : never
+type ChildPaths<Relations extends readonly BatchRelation[]> = ChildPathsForRelation<Relations[number]>
+
+export type ComposedSelection<Root extends RelationalQueryGraph, Relations extends readonly BatchRelation[]> =
+  | DefinitionProjectionPath<DefinitionOf<Root>>
+  | ChildPaths<Relations>
+
+export interface BatchPlanMetadata<Relation extends BatchRelation = BatchRelation> {
+  name: Relation['name']
+  parentKey: Relation['from']
+  childKey: BatchQueryKeyPath<Relation['query']>
+  keyParameter: BatchQueryKeyParameter<Relation['query']>['name']
+  parameters: Readonly<Relation['parameters']>
+  cardinality: Relation['cardinality']
+  parentKeyInjected: boolean
+  childKeyInjected: boolean
+}
+
+type BatchRelationNamed<Relation extends BatchRelation, Name extends string> = Relation extends BatchRelation
+  ? Relation['name'] extends Name
+    ? Relation
+    : never
+  : never
+
+type BatchRelationByName<Relations extends readonly BatchRelation[], Name extends string> = BatchRelationNamed<
+  Relations[number],
+  Name
+>
+
+type BatchKeyValue<Relation extends BatchRelation> = ScalarParameterValue<
+  BatchQueryKeyParameter<Relation['query']>['scalarType']
+>
+
+export interface CompiledQueryPlan<Relations extends readonly BatchRelation[] = readonly BatchRelation[]> {
+  readonly root: import('./index.js').CompiledSqlStatement
+  readonly batches: readonly BatchPlanMetadata<Relations[number]>[]
+  compileBatch<const Name extends RelationName<Relations>>(
+    name: Name,
+    keys: readonly BatchKeyValue<BatchRelationByName<Relations, Name>>[],
+  ): import('./index.js').CompiledSqlStatement
+}
+
+export type ComposedQueryOperation<
+  Root extends RelationalQueryGraph,
+  Relations extends readonly BatchRelation[],
+> = QueryOperationBase<ComposedSelection<Root, Relations>, DefinitionOrderingName<DefinitionOf<Root>>> &
+  OperationParameterInput<DefinitionOf<Root>>
+
+export interface ComposedQueryGraph<
+  Root extends RelationalQueryGraph = RelationalQueryGraph,
+  Relations extends readonly BatchRelation[] = readonly BatchRelation[],
+> {
+  readonly name: string
+  compileOraclePlan(
+    operation: ComposedQueryOperation<Root, Relations>,
+    options?: OracleCompileOptions,
+  ): CompiledQueryPlan<Relations>
+  compileSqlServerPlan(
+    operation: ComposedQueryOperation<Root, Relations>,
+    options?: SqlServerCompileOptions,
+  ): CompiledQueryPlan<Relations>
+}
+
+export function composeGraph<
+  const Root extends RelationalQueryGraph,
+  const Relations extends readonly BatchRelation[],
+>(configuration: {
+  root: Root
+  relations: Relations & CompatibleBatchRelations<Root, Relations>
+}): ComposedQueryGraph<Root, Relations>
+
 export interface ScalarOutputTypeMap {
   boolean: unknown
   int32: unknown
@@ -659,6 +966,23 @@ type ProjectionFieldPath<Field> =
       ? Path
       : never
 
+type ProjectionObjectPath<Object> =
+  Object extends ProjectionObjectTypeMetadata<infer Path, infer _Nullability>
+    ? Path
+    : Object extends ProjectionObjectDefinition<infer Path>
+      ? Path
+      : never
+
+type ProjectionObjectNullability<Object> =
+  Object extends ProjectionObjectTypeMetadata<infer _Path, infer Nullability>
+    ? Nullability
+    : Object extends ProjectionObjectDefinition<infer _Path, infer Nullability>
+      ? Nullability
+      : boolean
+
+type ProjectionObjectIsNullable<Definition extends GraphDefinitionInput, Object> =
+  true extends EvaluateNullability<Definition, ProjectionObjectNullability<Object>> ? true : false
+
 type ProjectionFieldValue<Definition extends GraphDefinitionInput, Field, TypeMap extends ScalarOutputTypeMap> =
   Field extends ProjectionTypeMetadata<infer _Path, infer Type, infer Nullability, infer _SelectedByDefault>
     ? true extends EvaluateNullability<Definition, Nullability>
@@ -705,6 +1029,19 @@ type SelectedProjectionField<Definition extends GraphDefinitionInput, Operation>
     ? ProjectionFieldByPath<DefinitionProjectionField<Definition>, Path>
     : DefaultProjectionField<DefinitionProjectionField<Definition>>
 
+type ProjectionObjectForField<Object, Field> = Object extends ProjectionObjectDefinition
+  ? Field extends ProjectionFieldDefinition
+    ? ProjectionFieldPath<Field> extends `${ProjectionObjectPath<Object>}.${string}`
+      ? Object
+      : never
+    : never
+  : never
+
+type SelectedProjectionObject<Definition extends GraphDefinitionInput, Field> = ProjectionObjectForField<
+  DefinitionProjectionObject<Definition>,
+  Field
+>
+
 type ProjectionEntry<
   Definition extends GraphDefinitionInput,
   Field,
@@ -716,6 +1053,13 @@ type ProjectionEntry<
     }
   : never
 
+type ProjectionObjectEntry<Definition extends GraphDefinitionInput, Object> = Object extends ProjectionObjectDefinition
+  ? {
+      path: ProjectionObjectPath<Object>
+      nullable: ProjectionObjectIsNullable<Definition, Object>
+    }
+  : never
+
 type ProjectionEntryHead<Entry> = Entry extends { path: infer Path extends string }
   ? Path extends `${infer Head}.${string}`
     ? Head
@@ -740,27 +1084,109 @@ type NestedProjectionEntry<Entry, Key extends string> = Entry extends {
     : never
   : never
 
-type ProjectionValueAtKey<Entry, Key extends string> = [NestedProjectionEntry<Entry, Key>] extends [never]
+type DirectProjectionObjectNullable<ObjectEntry, Key extends string> = ObjectEntry extends {
+  path: infer Path extends string
+  nullable: infer Nullable extends boolean
+}
+  ? Path extends Key
+    ? Nullable
+    : never
+  : never
+
+type NestedProjectionObjectEntry<ObjectEntry, Key extends string> = ObjectEntry extends {
+  path: infer Path extends string
+  nullable: infer Nullable extends boolean
+}
+  ? Path extends `${Key}.${infer Rest}`
+    ? { path: Rest; nullable: Nullable }
+    : never
+  : never
+
+type ApplyProjectionObjectNullability<Value, ObjectEntry, Key extends string> =
+  true extends DirectProjectionObjectNullable<ObjectEntry, Key> ? Value | null : Value
+
+type ProjectionValueAtKeyWithoutObject<Entry, ObjectEntry, Key extends string> = [
+  NestedProjectionEntry<Entry, Key>,
+] extends [never]
   ? DirectProjectionEntryValue<Entry, Key>
   : [DirectProjectionEntryValue<Entry, Key>] extends [never]
-    ? BuildProjectionResult<NestedProjectionEntry<Entry, Key>>
-    : DirectProjectionEntryValue<Entry, Key> | BuildProjectionResult<NestedProjectionEntry<Entry, Key>>
+    ? BuildProjectionResult<NestedProjectionEntry<Entry, Key>, NestedProjectionObjectEntry<ObjectEntry, Key>>
+    :
+        | DirectProjectionEntryValue<Entry, Key>
+        | BuildProjectionResult<NestedProjectionEntry<Entry, Key>, NestedProjectionObjectEntry<ObjectEntry, Key>>
+
+type ProjectionValueAtKey<Entry, ObjectEntry, Key extends string> = ApplyProjectionObjectNullability<
+  ProjectionValueAtKeyWithoutObject<Entry, ObjectEntry, Key>,
+  ObjectEntry,
+  Key
+>
 
-type BuildProjectionResult<Entry> = [Entry] extends [never]
+type BuildProjectionResult<Entry, ObjectEntry = never> = [Entry] extends [never]
   ? Record<never, never>
   : {
-      [Key in ProjectionEntryHead<Entry>]: ProjectionValueAtKey<Entry, Key>
+      [Key in ProjectionEntryHead<Entry>]: ProjectionValueAtKey<Entry, ObjectEntry, Key>
     }
 
 export type ResultOf<
-  Subject extends GraphDefinitionInput | QueryGraph | RelationalQueryGraph,
+  Subject extends GraphDefinitionInput | QueryGraph | RelationalQueryGraph | ComposedQueryGraph,
   Operation = undefined,
   TypeMap extends ScalarOutputTypeMap = DefaultScalarOutputTypeMap,
 > =
-  DefinitionOf<Subject> extends infer Definition extends GraphDefinitionInput
-    ? BuildProjectionResult<ProjectionEntry<Definition, SelectedProjectionField<Definition, Operation>, TypeMap>>
+  Subject extends ComposedQueryGraph<infer Root, infer Relations>
+    ? ComposedResult<Root, Relations, Operation, TypeMap>
+    : DefinitionOf<
+          Extract<Subject, GraphDefinitionInput | QueryGraph | RelationalQueryGraph>
+        > extends infer Definition extends GraphDefinitionInput
+      ? SelectedProjectionField<Definition, Operation> extends infer Field
+        ? BuildProjectionResult<
+            ProjectionEntry<Definition, Field, TypeMap>,
+            ProjectionObjectEntry<Definition, SelectedProjectionObject<Definition, Field>>
+          >
+        : never
+      : never
+
+type SelectedPaths<Operation> = Operation extends { select: readonly (infer Path extends string)[] } ? Path : never
+
+type RootOperation<Operation, Relations extends readonly BatchRelation[]> = Operation extends {
+  select: readonly string[]
+}
+  ? { select: readonly Exclude<SelectedPaths<Operation>, ChildPaths<Relations>>[] }
+  : undefined
+
+type SelectedChildPath<Operation, Name extends string> =
+  Extract<SelectedPaths<Operation>, `${Name}.${string}`> extends `${Name}.${infer Path}` ? Path : never
+
+type ChildOperation<Operation, Name extends string> = {
+  select: readonly SelectedChildPath<Operation, Name>[]
+}
+
+type SelectedRelationCandidate<Relation extends BatchRelation, Operation> = Relation extends BatchRelation
+  ? Extract<SelectedPaths<Operation>, `${Relation['name']}.${string}`> extends never
+    ? never
+    : Relation
+  : never
+
+type SelectedRelation<Relations extends readonly BatchRelation[], Operation> = SelectedRelationCandidate<
+  Relations[number],
+  Operation
+>
+
+type BatchResult<Relation extends BatchRelation, Operation, TypeMap extends ScalarOutputTypeMap> =
+  ResultOf<BatchQueryGraph<Relation['query']>, ChildOperation<Operation, Relation['name']>, TypeMap> extends infer Child
+    ? Relation['cardinality'] extends 'many'
+      ? Child[]
+      : Child | null
     : never
 
+type ComposedResult<
+  Root extends RelationalQueryGraph,
+  Relations extends readonly BatchRelation[],
+  Operation,
+  TypeMap extends ScalarOutputTypeMap,
+> = ResultOf<Root, RootOperation<Operation, Relations>, TypeMap> & {
+  [Relation in SelectedRelation<Relations, Operation> as Relation['name']]: BatchResult<Relation, Operation, TypeMap>
+}
+
 export type SqlServerVersion = '2008' | '2012' | '2016' | '2019' | '2022'
 export type OracleVersion = '11g' | '12c' | '19c' | '21c' | '23ai'
 
@@ -772,7 +1198,7 @@ export interface OracleCompileOptions {
   version?: OracleVersion
 }
 
-export type QueryGraphErrorPhase = 'definition' | 'mapping' | 'operation' | 'sql'
+export type QueryGraphErrorPhase = 'definition' | 'mapping' | 'composition' | 'operation' | 'sql'
 
 export interface QueryGraphDiagnostic {
   code: string
@@ -1134,6 +1560,14 @@ export interface ProjectionConfiguration<
   default?: SelectedByDefault
 }
 
+export interface ProjectionObjectConfiguration<
+  Path extends string | readonly string[] = string | readonly string[],
+  Value extends ExpressionInput = ExpressionInput,
+> {
+  path: Path
+  presence: Value
+}
+
 type ConfigurationPath<Path extends string | readonly string[]> = Path extends string
   ? Path
   : Path extends readonly string[]
@@ -1153,6 +1587,10 @@ export function project<
   SelectedByDefault
 >
 
+export function projectObject<const Path extends string | readonly string[], const Value extends ExpressionInput>(
+  configuration: ProjectionObjectConfiguration<Path, Value>,
+): TypedProjectionObject<ConfigurationPath<Path>, InputNullability<Value>>
+
 export function dimension<
   const Path extends string | readonly string[],
   const Value extends ExpressionInput,
@@ -1206,6 +1644,7 @@ export interface GraphModuleConfiguration {
   relations?: readonly RelationDefinition[]
   constraints?: readonly ConstraintDefinition[]
   projection?: readonly ProjectionFieldDefinition[]
+  objects?: readonly ProjectionObjectDefinition[]
   orderings?: readonly OrderingDefinition[]
 }
 
@@ -1270,6 +1709,18 @@ type ModuleRelation<Module> =
     ? Relation
     : never
 
+type ModuleProjectionObject<Module> =
+  Module extends GraphModule<
+    infer _Parameter,
+    infer _ProjectionPath,
+    infer _OrderingName,
+    infer _ProjectionField,
+    infer _Relation,
+    infer ProjectionObject
+  >
+    ? ProjectionObject
+    : never
+
 type ProjectionPathOf<Field> = Field extends ProjectionFieldDefinition<infer Path> ? Path : never
 
 type OrderingNameOf<Ordering> = Ordering extends OrderingDefinition<infer Name> ? Name : never
@@ -1290,6 +1741,10 @@ type ConfigurationProjectionField<Configuration> =
   | Extract<ConfigurationElement<Configuration, 'measures'>, ProjectionFieldDefinition>
   | ModuleProjectionField<ConfigurationElement<Configuration, 'modules'>>
 
+type ConfigurationProjectionObject<Configuration> =
+  | Extract<ConfigurationElement<Configuration, 'objects'>, ProjectionObjectDefinition>
+  | ModuleProjectionObject<ConfigurationElement<Configuration, 'modules'>>
+
 type ConfigurationOrderingName<Configuration> =
   | OrderingNameOf<ConfigurationElement<Configuration, 'orderings'>>
   | ModuleOrderingName<ConfigurationElement<Configuration, 'modules'>>
@@ -1310,6 +1765,7 @@ export interface GraphModule<
   OrderingName extends string = string,
   ProjectionField extends ProjectionFieldDefinition = ProjectionFieldDefinition<ProjectionPath>,
   Relation extends RelationDefinition = RelationDefinition,
+  ProjectionObject extends ProjectionObjectDefinition = ProjectionObjectDefinition,
 > {
   readonly name: string
   readonly sources: readonly SourceRef[]
@@ -1317,6 +1773,7 @@ export interface GraphModule<
   readonly relations: readonly Relation[]
   readonly constraints: readonly ConstraintDefinition[]
   readonly projection: readonly ProjectionField[]
+  readonly objects: readonly ProjectionObject[]
   readonly orderings: readonly OrderingDefinition<OrderingName>[]
 }
 
@@ -1327,7 +1784,8 @@ export function defineGraphModule<const Configuration extends GraphModuleConfigu
   ConfigurationProjectionPath<Configuration>,
   ConfigurationOrderingName<Configuration>,
   ConfigurationProjectionField<Configuration>,
-  ConfigurationRelation<Configuration>
+  ConfigurationRelation<Configuration>,
+  ConfigurationProjectionObject<Configuration>
 >
 
 export interface GraphConfiguration {
@@ -1339,6 +1797,7 @@ export interface GraphConfiguration {
   relations?: readonly RelationDefinition[]
   constraints?: readonly ConstraintDefinition[]
   projection?: readonly ProjectionFieldDefinition[]
+  objects?: readonly ProjectionObjectDefinition[]
   orderings?: readonly OrderingDefinition[]
 }
 
@@ -1350,7 +1809,8 @@ export function defineGraph<const Configuration extends GraphConfiguration>(
   ConfigurationOrderingName<Configuration>,
   ConfigurationProjectionField<Configuration>,
   ConfigurationRelation<Configuration>,
-  ConfigurationRoot<Configuration>
+  ConfigurationRoot<Configuration>,
+  ConfigurationProjectionObject<Configuration>
 >
 
 export interface SummaryGraphConfiguration {
@@ -1374,5 +1834,6 @@ export function defineSummaryGraph<const Configuration extends SummaryGraphConfi
   ConfigurationOrderingName<Configuration>,
   ConfigurationProjectionField<Configuration>,
   ConfigurationRelation<Configuration>,
-  ConfigurationRoot<Configuration>
+  ConfigurationRoot<Configuration>,
+  never
 >