@soda-gql/core 0.8.0 → 0.9.0

package/dist/{index-rBHv6RJz.d.ts → index-Ib9pb2Si.d.cts}

@@ -1,11 +1,77 @@
-import { C as ObjectTypeProfile, Ct as GetSignature, Et as ConstValue, F as AnyMetadataAdapter, G as FragmentMetadataBuilder, I as DefaultAdapter, L as DefaultMetadataAdapter, N as Adapter, Ot as FieldPath, P as AnyAdapter, R as ExtractAdapterTypes, S as GetModifiedType, St as ApplyTypeModifier, T as TypeProfile, X as AnyVarRef, Z as AnyVarRefBrand, bt as OutputTypenameSpecifier, c as InferOutputProfile, dt as InputTypeSpecifier, et as VarRef, f as ObjectFieldRecord, ft as InputTypeSpecifiers, g as ResolveInputProfileFromMeta, gt as OutputScalarSpecifier, h as PickTypeSpecifierByFieldName, ht as OutputObjectSpecifier, i as AnyTypeName, it as AnyDefaultValue, m as OperationType, mt as OutputInferrableTypeSpecifier, n as AnyFieldName, o as InferInputKind, pt as OutputEnumSpecifier, q as MetadataBuilder, r as AnyGraphqlSchema, s as InferInputProfile, t as AllInputTypeNames, ut as InputTypeKind, vt as OutputTypeSpecifier, w as PrimitiveTypeProfile, wt as TypeModifier, x as GetConstAssignableType, xt as OutputUnionSpecifier, y as UnionMemberName } from "./schema-CFMmSBhl.js";
+import { C as ObjectTypeProfile, Ct as GetSignature, Et as ConstValue, F as AnyMetadataAdapter, G as FragmentMetadataBuilder, I as DefaultAdapter, L as DefaultMetadataAdapter, N as Adapter, Ot as FieldPath, P as AnyAdapter, R as ExtractAdapterTypes, S as GetModifiedType, St as ApplyTypeModifier, T as TypeProfile, X as AnyVarRef, Z as AnyVarRefBrand, bt as OutputTypenameSpecifier, c as InferOutputProfile, dt as InputTypeSpecifier, et as VarRef, f as ObjectFieldRecord, ft as InputTypeSpecifiers, g as ResolveInputProfileFromMeta, gt as OutputScalarSpecifier, h as PickTypeSpecifierByFieldName, ht as OutputObjectSpecifier, i as AnyTypeName, it as AnyDefaultValue, m as OperationType, mt as OutputInferrableTypeSpecifier, n as AnyFieldName, o as InferInputKind, pt as OutputEnumSpecifier, q as MetadataBuilder, r as AnyGraphqlSchema, s as InferInputProfile, t as AllInputTypeNames, ut as InputTypeKind, vt as OutputTypeSpecifier, w as PrimitiveTypeProfile, wt as TypeModifier, x as GetConstAssignableType, xt as OutputUnionSpecifier, y as UnionMemberName } from "./schema-CPTxQbTv.cjs";
 import { ConstValueNode, NamedTypeNode, OperationTypeNode, TypeNode, ValueNode } from "graphql";
 import { TypedDocumentNode } from "@graphql-typed-document-node/core";
 
+//#region packages/core/src/types/type-foundation/directive-ref.d.ts
+
+/**
+ * DirectiveRef type for representing field-level directives.
+ *
+ * Similar to VarRef, DirectiveRef uses a branded type pattern to carry
+ * type information about the directive (name, locations, arguments) while
+ * allowing relaxed type checking at the field builder level.
+ *
+ * @module
+ */
+/**
+ * Valid locations where a directive can be applied.
+ * Subset of GraphQL DirectiveLocation enum relevant for soda-gql.
+ */
+type DirectiveLocation = "QUERY" | "MUTATION" | "SUBSCRIPTION" | "FIELD" | "FRAGMENT_DEFINITION" | "FRAGMENT_SPREAD" | "INLINE_FRAGMENT" | "VARIABLE_DEFINITION";
+/**
+ * Brand interface for DirectiveRef type information.
+ * Contains the directive name and valid locations.
+ */
+interface AnyDirectiveRefBrand {
+  readonly directiveName: string;
+  readonly locations: readonly DirectiveLocation[];
+}
+/**
+ * Internal structure of a DirectiveRef.
+ * Contains the directive name, arguments, and valid locations.
+ */
+type DirectiveRefInner = {
+  readonly name: string;
+  readonly arguments: Readonly<Record<string, unknown>>;
+  readonly locations: readonly DirectiveLocation[];
+};
+declare const __DIRECTIVE_REF_BRAND__: unique symbol;
+/**
+ * A reference to a directive that can be applied to fields.
+ *
+ * DirectiveRef carries type information about the directive via the TBrand
+ * type parameter, but this information is only used for type inference,
+ * not for runtime validation.
+ *
+ * @example
+ * ```typescript
+ * const skipDirective = new DirectiveRef({
+ *   name: "skip",
+ *   arguments: { if: true },
+ *   locations: ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"],
+ * });
+ * ```
+ */
+declare class DirectiveRef<TBrand extends AnyDirectiveRefBrand> {
+  private readonly inner;
+  readonly [__DIRECTIVE_REF_BRAND__]: TBrand;
+  constructor(inner: DirectiveRefInner);
+  /**
+   * Extracts the inner structure from a DirectiveRef.
+   * Used by build-document.ts to generate DirectiveNode.
+   */
+  static getInner(ref: AnyDirectiveRef): DirectiveRefInner;
+}
+/**
+ * Type-erased DirectiveRef for use in contexts where
+ * the specific directive type is not needed.
+ */
+type AnyDirectiveRef = DirectiveRef<AnyDirectiveRefBrand>;
+//#endregion
 //#region packages/core/src/types/type-foundation/type-modifier-extension.generated.d.ts
 type Op_0<T> = T[];
 type Op_1<T> = T[] | null | undefined;
-type Ref<T extends TypeProfile, M$1 extends string> = VarRef<TypeProfile.VarRefBrand<T, GetSignature<M$1>>>;
+type Ref<T extends TypeProfile, M$1 extends string> = VarRef<TypeProfile.ExpectedVariableType<T, GetSignature<M$1>>>;
 type IsOptionalProfile<TField extends TypeProfile.WithMeta> = TField[1] extends `${string}?` ? true : TField[2] extends TypeProfile.WITH_DEFAULT_INPUT ? true : false;
 type OptionalProfileKeys<TProfileObject extends {
   readonly [key: string]: TypeProfile.WithMeta;
@@ -83,19 +149,27 @@ type AnyAssigningInput = {
   readonly [key: string]: AnyVarRef;
 };
 type IsOptional<TSpecifier$1 extends InputTypeSpecifier> = TSpecifier$1["modifier"] extends `${string}?` ? true : TSpecifier$1["defaultValue"] extends AnyDefaultValue ? true : false;
-type AssignableInput<TSchema extends AnyGraphqlSchema, TSpecifiers extends InputTypeSpecifiers> = { readonly [K in keyof TSpecifiers as IsOptional<TSpecifiers[K]> extends true ? K : never]+?: AssignableInputValue<TSchema, TSpecifiers[K]> } & { readonly [K in keyof TSpecifiers as IsOptional<TSpecifiers[K]> extends false ? K : never]-?: AssignableInputValue<TSchema, TSpecifiers[K]> };
+type AssignableInput<TSchema extends AnyGraphqlSchema, TSpecifiers extends InputTypeSpecifiers> = { readonly [K in keyof TSpecifiers as IsOptional<TSpecifiers[K]> extends true ? K : never]+?: FieldArgumentValue<TSchema, TSpecifiers[K]> } & { readonly [K in keyof TSpecifiers as IsOptional<TSpecifiers[K]> extends false ? K : never]-?: FieldArgumentValue<TSchema, TSpecifiers[K]> };
 /**
- * Assignable input value type using typeName + kind for VarRef comparison.
+ * Field argument value type using typeName + kind for VarRef comparison.
  * Uses GetAssignableType which derives typeName + kind from the profile.
+ * This name appears in TypeScript error messages when argument types don't match.
  */
-type AssignableInputValue<TSchema extends AnyGraphqlSchema, TSpecifier$1 extends InputTypeSpecifier> = GetAssignableType<InferInputProfile<TSchema, TSpecifier$1>>;
-type AssigningInput<TSchema extends AnyGraphqlSchema, TSpecifiers extends InputTypeSpecifiers> = { readonly [K in keyof TSpecifiers]-?: VarRef<TypeProfile.AssigningVarRefBrand<InferInputProfile<TSchema, TSpecifiers[K]>>> };
+type FieldArgumentValue<TSchema extends AnyGraphqlSchema, TSpecifier$1 extends InputTypeSpecifier> = GetAssignableType<InferInputProfile<TSchema, TSpecifier$1>>;
+/**
+ * Declared variables record for an operation or fragment.
+ * Maps variable names to their VarRef types with proper branding.
+ * This name appears in TypeScript error messages when variable access fails.
+ */
+type DeclaredVariables<TSchema extends AnyGraphqlSchema, TSpecifiers extends InputTypeSpecifiers> = { readonly [K in keyof TSpecifiers]-?: VarRef<TypeProfile.DeclaredVariableType<InferInputProfile<TSchema, TSpecifiers[K]>>> };
 type AssignableInputByFieldName<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"], TFieldName$1 extends keyof TSchema["object"][TTypeName$1]["fields"]> = AssignableInput<TSchema, TSchema["object"][TTypeName$1]["fields"][TFieldName$1]["arguments"]>;
 //#endregion
 //#region packages/core/src/types/fragment/directives.d.ts
-type AnyDirectiveAttachments = {
-  readonly [key: string]: AnyAssignableInput;
-};
+/**
+ * Field-level directive attachments as an array of DirectiveRef.
+ * Directives are applied in order and validated at build time.
+ */
+type AnyDirectiveAttachments = readonly AnyDirectiveRef[];
 //#endregion
 //#region packages/core/src/types/fragment/field-selection.d.ts
 /**
@@ -164,10 +238,47 @@ type InferField<TSchema extends AnyGraphqlSchema, TSelection extends AnyFieldSel
 } ? GetModifiedType<InferOutputProfile<TSchema, TSpecifier>, TSpecifier["modifier"]> : never);
 //#endregion
 //#region packages/core/src/composer/build-document.d.ts
+/**
+ * Converts an assignable input value to a GraphQL AST ValueNode.
+ *
+ * Handles primitives, arrays, objects, and variable references.
+ * Returns null for undefined values (field is omitted).
+ */
 declare const buildArgumentValue: (value: AnyAssignableInputValue) => ValueNode | null;
+/**
+ * Converts a constant value to a GraphQL AST ConstValueNode.
+ *
+ * Unlike `buildArgumentValue`, this only handles literal values
+ * (no variable references). Used for default values.
+ */
 declare const buildConstValueNode: (value: ConstValue) => ConstValueNode | null;
+/**
+ * Wraps a named type with modifiers (non-null, list).
+ *
+ * Modifier format: starts with `?` (nullable) or `!` (non-null),
+ * followed by `[]?` or `[]!` pairs for lists.
+ *
+ * @example
+ * - `"!"` → `String!`
+ * - `"?"` → `String`
+ * - `"![]!"` → `[String!]!`
+ * - `"?[]?"` → `[String]`
+ */
 declare const buildWithTypeModifier: (modifier: TypeModifier, buildType: () => NamedTypeNode) => TypeNode;
+/**
+ * Converts an operation type string to a GraphQL AST OperationTypeNode.
+ */
 declare const buildOperationTypeNode: (operation: OperationType) => OperationTypeNode;
+/**
+ * Builds a TypedDocumentNode from operation options.
+ *
+ * This is the main entry point for converting field selections into
+ * a GraphQL document AST. The result can be used with any GraphQL
+ * client that supports TypedDocumentNode.
+ *
+ * @param options - Operation configuration (name, type, variables, fields)
+ * @returns TypedDocumentNode with inferred input/output types
+ */
 declare const buildDocument: <TSchema extends AnyGraphqlSchema, TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers>(options: {
   operationName: string;
   operationType: OperationType;
@@ -220,6 +331,130 @@ type ColocatedFields<TEntries extends ColocatedEntries> = UnionToIntersection<{
 declare const createColocateHelper: () => <TEntries extends ColocatedEntries>(entries: TEntries) => ColocatedFields<TEntries>;
 type ColocateHelper = ReturnType<typeof createColocateHelper>;
 //#endregion
+//#region packages/core/src/composer/directive-builder.d.ts
+/**
+ * A method that creates a DirectiveRef with specific type information.
+ * The TArgs type defines the expected argument shape for the directive.
+ */
+type DirectiveMethod<TDirectiveName extends string, TLocations extends readonly DirectiveLocation[], TArgs> = (args: TArgs) => DirectiveRef<{
+  directiveName: TDirectiveName;
+  locations: TLocations;
+}>;
+/**
+ * Type for directive arguments that can include VarRef values.
+ * This allows using variables in directive arguments like `{ if: $.shouldSkip }`.
+ */
+type DirectiveArgValue = boolean | string | number | null | AnyVarRef;
+/**
+ * Standard GraphQL directives that are always available.
+ */
+type StandardDirectives = {
+  /**
+   * @skip directive - conditionally skip a field.
+   * @example
+   * ```typescript
+   * f.email({}, { directives: [$dir.skip({ if: $.hideEmail })] })
+   * ```
+   */
+  skip: DirectiveMethod<"skip", readonly ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"], {
+    if: DirectiveArgValue;
+  }>;
+  /**
+   * @include directive - conditionally include a field.
+   * @example
+   * ```typescript
+   * f.email({}, { directives: [$dir.include({ if: $.showEmail })] })
+   * ```
+   */
+  include: DirectiveMethod<"include", readonly ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"], {
+    if: DirectiveArgValue;
+  }>;
+};
+/**
+ * Creates a directive method factory for a specific directive.
+ *
+ * @param name - The directive name (without @)
+ * @param locations - Valid locations where the directive can be applied
+ * @returns A function that creates DirectiveRef instances
+ *
+ * @example
+ * ```typescript
+ * const skipMethod = createDirectiveMethod("skip", ["FIELD", "FRAGMENT_SPREAD", "INLINE_FRAGMENT"] as const);
+ * const skipDirective = skipMethod({ if: true });
+ * ```
+ */
+declare const createDirectiveMethod: <TDirectiveName extends string, const TLocations extends readonly DirectiveLocation[]>(name: TDirectiveName, locations: TLocations) => (<TArgs extends Record<string, unknown>>(args: TArgs) => DirectiveRef<{
+  directiveName: TDirectiveName;
+  locations: TLocations;
+}>);
+/**
+ * Creates the standard GraphQL directives (@skip, @include).
+ * These are always available regardless of schema definition.
+ *
+ * @returns Object containing skip and include directive methods
+ *
+ * @example
+ * ```typescript
+ * const $dir = createStandardDirectives();
+ * const skipDirective = $dir.skip({ if: true });
+ * ```
+ */
+declare const createStandardDirectives: () => StandardDirectives;
+/**
+ * Type for any directive method (type-erased).
+ */
+type AnyDirectiveMethod = (args: any) => AnyDirectiveRef;
+/**
+ * Type for the directive builder that includes standard directives
+ * and can be extended with schema-specific directives.
+ */
+type DirectiveBuilder<TCustomDirectives extends Record<string, AnyDirectiveMethod> = {}> = StandardDirectives & TCustomDirectives;
+/**
+ * Creates a directive builder with standard directives and optional custom directives.
+ *
+ * @param customDirectives - Additional directive methods from schema (generated by codegen)
+ * @returns Combined directive builder with all available directives
+ *
+ * @internal Used by codegen to create schema-specific directive builders
+ */
+declare const createDirectiveBuilder: <TCustomDirectives extends Record<string, AnyDirectiveMethod> = {}>(customDirectives?: TCustomDirectives) => DirectiveBuilder<TCustomDirectives>;
+/**
+ * Type guard to check if a value is a DirectiveRef.
+ *
+ * @param value - Value to check
+ * @returns True if value is a DirectiveRef instance
+ */
+declare const isDirectiveRef: (value: unknown) => value is AnyDirectiveRef;
+//#endregion
+//#region packages/core/src/types/element/attachment-types.d.ts
+/**
+ * Shape constraint for attachment objects used in type utilities.
+ */
+type AttachmentShape = {
+  name: string;
+  createValue: (element: any) => object;
+};
+/**
+ * Extracts the property type contribution from a single attachment.
+ * Maps GqlElementAttachment<E, N, V> to { [N]: V }
+ */
+type AttachmentToProperty<TAttachment> = TAttachment extends {
+  name: infer TName extends string;
+  createValue: (element: any) => infer TValue extends object;
+} ? { [K in TName]: TValue } : never;
+/**
+ * Recursively maps a tuple of attachments to an intersection of their properties.
+ *
+ * @example
+ * type Attachments = [
+ *   { name: "a"; createValue: (el: any) => { x: number } },
+ *   { name: "b"; createValue: (el: any) => { y: string } }
+ * ];
+ * type Result = AttachmentsTupleToIntersection<Attachments>;
+ * // Result: { a: { x: number } } & { b: { y: string } }
+ */
+type AttachmentsTupleToIntersection<TAttachments extends readonly AttachmentShape[]> = TAttachments extends readonly [infer First extends AttachmentShape, ...infer Rest extends readonly AttachmentShape[]] ? AttachmentToProperty<First> & AttachmentsTupleToIntersection<Rest> : unknown;
+//#endregion
 //#region packages/core/src/utils/empty-object.d.ts
 declare const __EMPTY_SYMBOL__: unique symbol;
 type EmptyObject = {
@@ -245,25 +480,48 @@ declare const empty: () => EmptyObject;
  * while preserving the original schema information for inference.
  */
 type FieldsBuilder<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string, TVariableDefinitions extends InputTypeSpecifiers, TFields extends AnyFields> = (tools: NoInfer<FieldsBuilderTools<TSchema, TTypeName$1, TVariableDefinitions>>) => TFields;
+/**
+ * Tools provided to field builder callbacks.
+ * - `f`: Field selection factories for the current type
+ * - `$`: Variable references for the current scope
+ */
 type FieldsBuilderTools<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string, TVariableDefinitions extends InputTypeSpecifiers> = {
   f: FieldSelectionFactories<TSchema, TTypeName$1>;
-  $: AssigningInput<TSchema, TVariableDefinitions>;
+  $: DeclaredVariables<TSchema, TVariableDefinitions>;
 };
-/** Narrow builder used when a field resolves to an object and we need nested selections. */
+/**
+ * Builder for nested object field selections.
+ * Used when a field returns an object type requiring sub-selections.
+ */
 type NestedObjectFieldsBuilder<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string, TFields extends AnyNestedObject> = (tools: NoInfer<NestedObjectFieldsBuilderTools<TSchema, TTypeName$1>>) => TFields;
+/**
+ * Tools for nested object builders (no variable access).
+ * @internal
+ */
 type NestedObjectFieldsBuilderTools<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string> = {
   f: FieldSelectionFactories<TSchema, TTypeName$1>;
 };
+/**
+ * Builder for union type selections with per-member field definitions.
+ */
 type NestedUnionFieldsBuilder<TSchema extends AnyGraphqlSchema, TMemberName extends string, TUnionFields extends AnyNestedUnion> = { [TTypename in keyof TUnionFields & TMemberName]?: NestedObjectFieldsBuilder<TSchema, TTypename, NonNullable<TUnionFields[TTypename]>> };
 /** Map each field to a factory capable of emitting fully-typed references. */
 type FieldSelectionFactories<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string> = { [TFieldName in keyof ObjectFieldRecord<TSchema, TTypeName$1>]: TFieldName extends string ? FieldSelectionFactory<TSchema, FieldSelectionTemplateOf<TSchema, TTypeName$1, TFieldName>> : never };
+/**
+ * Type-erased field selection factory.
+ * @internal
+ */
 type AnyFieldSelectionFactory = <TAlias extends string | null = null>(fieldArgs: AnyAssignableInput | void, extras?: {
   alias?: TAlias;
-  directives?: AnyDirectiveAttachments;
+  directives?: AnyDirectiveRef[];
 }) => AnyFieldSelectionFactoryReturn<TAlias>;
+/**
+ * Factory function for creating a typed field selection.
+ * Accepts field arguments and optional alias/directives.
+ */
 type FieldSelectionFactory<TSchema extends AnyGraphqlSchema, TSelection extends AnyFieldSelection> = <TAlias extends string | null = null>(fieldArgs: TSelection["args"] | IfOmittable<TSelection["args"], void | null>, extras?: {
   alias?: TAlias;
-  directives?: TSelection["directives"];
+  directives?: AnyDirectiveRef[];
 }) => FieldSelectionFactoryReturn<TSchema, TSelection, TAlias>;
 type AnyFieldSelectionFactoryReturn<TAlias extends string | null> = FieldSelectionFactoryReturn<AnyGraphqlSchema, AnyFieldSelection & {
   type: OutputObjectSpecifier;
@@ -305,42 +563,138 @@ type LazyEvaluatorContext = {
 //#region packages/core/src/types/element/gql-element.d.ts
 declare const GQL_ELEMENT_FACTORY: unique symbol;
 declare const GQL_ELEMENT_CONTEXT: unique symbol;
+/**
+ * Context passed to element definition factories, containing the canonical ID.
+ */
 type GqlElementContext = LazyEvaluatorContext;
+/**
+ * Factory function that produces the element definition.
+ * May be sync or async (async requires async build mode).
+ */
 type GqlElementDefinitionFactory<T> = (context: GqlElementContext | null) => T | Promise<T>;
-type GqlElementAttachment<TElement extends object, TName$1 extends string, TValue extends object> = {
+/**
+ * Configuration for attaching a computed property to an element.
+ */
+type GqlElementAttachment<TElement extends object, TName$1 extends string, TValue$1 extends object> = {
   name: TName$1;
-  createValue: (element: TElement) => TValue;
+  createValue: (element: TElement) => TValue$1;
 };
+/**
+ * Abstract base class for all GraphQL elements (Fragment, Operation).
+ *
+ * Uses lazy evaluation with caching - definition is computed on first access.
+ * Subclasses should not be instantiated directly; use static `create` methods.
+ *
+ * @template TDefinition - The shape of the evaluated definition
+ * @template TInfer - Type inference metadata (access via `$infer`)
+ */
 declare abstract class GqlElement<TDefinition extends object, TInfer extends object> {
+  /**
+   * Type-only property for inference. Throws at runtime.
+   * Use with `typeof element.$infer` to extract input/output types.
+   */
   readonly $infer: TInfer;
   private [GQL_ELEMENT_FACTORY];
   private [GQL_ELEMENT_CONTEXT];
   protected constructor(define: GqlElementDefinitionFactory<TDefinition>, getDeps?: () => GqlElement<any, any>[]);
-  attach<TName$1 extends string, TValue extends object>(attachment: GqlElementAttachment<this, TName$1, TValue>): this & { [_ in TName$1]: TValue };
+  /**
+   * Attaches lazily-computed properties to this element.
+   * Properties are computed once on first access after evaluation.
+   *
+   * @example Single attachment
+   * ```typescript
+   * const fragment = gql.default(...)
+   *   .attach({ name: "utils", createValue: (el) => ({ ... }) });
+   * ```
+   *
+   * @example Multiple attachments (use `as const` for full type inference)
+   * ```typescript
+   * const fragment = gql.default(...)
+   *   .attach([
+   *     { name: "a", createValue: () => ({ x: 1 }) },
+   *     { name: "b", createValue: () => ({ y: 2 }) },
+   *   ] as const);
+   * ```
+   */
+  attach<TName$1 extends string, TValue$1 extends object>(attachment: GqlElementAttachment<this, TName$1, TValue$1>): this & { [K in TName$1]: TValue$1 };
+  attach<const TAttachments extends readonly AttachmentShape[]>(attachments: TAttachments): this & AttachmentsTupleToIntersection<TAttachments>;
+  /**
+   * Sets the canonical context for an element. Used by the builder.
+   * @internal
+   */
   static setContext<TElement extends GqlElement<any, any>>(element: TElement, context: GqlElementContext): void;
+  /**
+   * Gets the canonical context of an element, if set.
+   * @internal
+   */
   static getContext(element: GqlElement<any, any>): GqlElementContext | null;
+  /**
+   * Creates a generator for async evaluation. Used by the builder.
+   * @internal
+   */
   static createEvaluationGenerator(element: GqlElement<any, any>): Generator<Promise<void>, void, void>;
   private static evaluateInstantly;
+  /**
+   * Forces synchronous evaluation. Throws if async operation is needed.
+   * @internal
+   */
   static evaluateSync(element: GqlElement<any, any>): void;
-  static get<TValue extends object>(element: GqlElement<TValue, any>): TValue;
+  /**
+   * Evaluates and returns the element's definition.
+   * Throws if async operation is needed.
+   * @internal
+   */
+  static get<TValue$1 extends object>(element: GqlElement<TValue$1, any>): TValue$1;
 }
 //#endregion
 //#region packages/core/src/types/element/fragment.d.ts
+/**
+ * Type alias for any Fragment instance.
+ */
 type AnyFragment = Fragment<string, any, AnyFields, any>;
+/**
+ * Type inference metadata for fragments.
+ * Access via `typeof fragment.$infer`.
+ */
 type FragmentInferMeta<TVariables, TOutput extends object> = {
   readonly input: TVariables;
   readonly output: TOutput;
 };
+/**
+ * Internal artifact shape produced by fragment evaluation.
+ * @internal
+ */
 interface FragmentArtifact<TTypeName$1 extends string, TVariables extends Partial<AnyAssignableInput> | void, TFields extends Partial<AnyFields>> {
   readonly typename: TTypeName$1;
   readonly spread: (variables: TVariables) => TFields;
 }
 declare const __FRAGMENT_BRAND__: unique symbol;
+/**
+ * Represents a reusable GraphQL field selection on a specific type.
+ *
+ * Fragments are created via `gql(({ fragment }) => fragment.TypeName({ ... }))`.
+ * Use `spread()` to include the fragment's fields in an operation.
+ *
+ * @template TTypeName - The GraphQL type this fragment selects from
+ * @template TVariables - Variables required when spreading
+ * @template TFields - The selected fields structure
+ * @template TOutput - Inferred output type from selected fields
+ */
 declare class Fragment<TTypeName$1 extends string, TVariables extends Partial<AnyAssignableInput> | void, TFields extends Partial<AnyFields>, TOutput extends object> extends GqlElement<FragmentArtifact<TTypeName$1, TVariables, TFields>, FragmentInferMeta<TVariables, TOutput>> implements FragmentArtifact<TTypeName$1, TVariables, TFields> {
   private readonly [__FRAGMENT_BRAND__];
   private constructor();
+  /** The GraphQL type name this fragment selects from. */
   get typename(): TTypeName$1;
+  /**
+   * Spreads this fragment's fields into a parent selection.
+   * Pass variables if the fragment defines any.
+   */
   get spread(): (variables: TVariables) => TFields;
+  /**
+   * Creates a new Fragment instance.
+   * Prefer using the `gql(({ fragment }) => ...)` API instead.
+   * @internal
+   */
   static create<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string, TVariableDefinitions extends InputTypeSpecifiers, TFields extends AnyFields>(define: () => {
     typename: TTypeName$1;
     spread: (variables: OptionalArg<AssignableInput<TSchema, TVariableDefinitions>>) => TFields;
@@ -352,13 +706,27 @@ declare class Fragment<TTypeName$1 extends string, TVariables extends Partial<An
 }
 //#endregion
 //#region packages/core/src/types/element/operation.d.ts
+/**
+ * Type alias for any Operation instance.
+ */
 type AnyOperation = AnyOperationOf<"query"> | AnyOperationOf<"mutation"> | AnyOperationOf<"subscription">;
+/**
+ * Type alias for an Operation of a specific type.
+ */
 type AnyOperationOf<TOperationType extends OperationType> = Operation<TOperationType, string, string[], any, AnyFields, any>;
+/**
+ * Type inference metadata for operations.
+ * Access via `typeof operation.$infer`.
+ */
 type OperationInferMeta<TVariables, TData extends object> = {
   readonly input: TVariables;
   readonly output: TData;
 };
 declare const __OPERATION_BRAND__: unique symbol;
+/**
+ * Internal artifact shape produced by operation evaluation.
+ * @internal
+ */
 type OperationArtifact<TOperationType extends OperationType, TOperationName extends string, TVariableNames extends string[], TVariables extends AnyConstAssignableInput, TFields extends Partial<AnyFields>, TData extends object> = {
   readonly operationType: TOperationType;
   readonly operationName: TOperationName;
@@ -367,15 +735,42 @@ type OperationArtifact<TOperationType extends OperationType, TOperationName exte
   readonly document: TypedDocumentNode<TData, TVariables>;
   readonly metadata?: unknown;
 };
+/**
+ * Represents a GraphQL operation (query, mutation, or subscription).
+ *
+ * Operations are created via `gql(({ query }) => query.operation({ ... }))`.
+ * Produces a TypedDocumentNode for type-safe execution with GraphQL clients.
+ *
+ * @template TOperationType - 'query' | 'mutation' | 'subscription'
+ * @template TOperationName - The unique operation name
+ * @template TVariableNames - Tuple of variable names
+ * @template TVariables - Variable types for the operation
+ * @template TFields - Selected fields structure
+ * @template TData - Inferred response data type
+ */
 declare class Operation<TOperationType extends OperationType, TOperationName extends string, TVariableNames extends string[], TVariables extends AnyConstAssignableInput, TFields extends Partial<AnyFields>, TData extends object> extends GqlElement<OperationArtifact<TOperationType, TOperationName, TVariableNames, TVariables, TFields, TData>, OperationInferMeta<TVariables, TData>> implements OperationArtifact<TOperationType, TOperationName, TVariableNames, TVariables, TFields, TData> {
   private readonly [__OPERATION_BRAND__];
   private constructor();
+  /** The operation type: 'query', 'mutation', or 'subscription'. */
   get operationType(): TOperationType;
+  /** The unique name of this operation. */
   get operationName(): TOperationName;
+  /** List of variable names defined for this operation. */
   get variableNames(): TVariableNames;
+  /**
+   * Returns the field selections. Used for document reconstruction.
+   * @internal
+   */
   get documentSource(): () => TFields;
+  /** The TypedDocumentNode for use with GraphQL clients. */
   get document(): TypedDocumentNode<TData, TVariables>;
+  /** Custom metadata attached to this operation, if any. */
   get metadata(): unknown;
+  /**
+   * Creates a new Operation instance.
+   * Prefer using the `gql(({ query }) => ...)` API instead.
+   * @internal
+   */
   static create<TSchema extends AnyGraphqlSchema, TOperationType extends OperationType, TOperationName extends string, TVariableDefinitions extends InputTypeSpecifiers, TFields extends AnyFields>(define: (context: GqlElementContext | null) => {
     operationType: TOperationType;
     operationName: TOperationName;
@@ -394,25 +789,70 @@ declare class Operation<TOperationType extends OperationType, TOperationName ext
 }
 //#endregion
 //#region packages/core/src/composer/fields-builder.d.ts
+/**
+ * Creates field selection factories for a given object type.
+ *
+ * Returns an object with a factory for each field defined on the type.
+ * Factories are cached per schema+type to avoid recreation.
+ *
+ * @param schema - The GraphQL schema definition
+ * @param typeName - The object type name to create factories for
+ * @returns Object mapping field names to their selection factories
+ *
+ * @internal Used by operation and fragment composers
+ */
 declare const createFieldFactories: <TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string>(schema: TSchema, typeName: TTypeName$1) => FieldSelectionFactories<TSchema, TTypeName$1>;
 //#endregion
 //#region packages/core/src/composer/input.d.ts
-declare const createVarAssignments: <TSchema extends AnyGraphqlSchema, TVariableDefinitions extends InputTypeSpecifiers>(definitions: TVariableDefinitions, providedValues: AnyAssignableInput | void) => AssigningInput<TSchema, TVariableDefinitions>;
-declare const createVarRefs: <TSchema extends AnyGraphqlSchema, TVarDefinitions extends InputTypeSpecifiers>(definitions: TVarDefinitions) => AssigningInput<TSchema, TVarDefinitions>;
+/**
+ * Creates variable assignments from provided values.
+ *
+ * Maps variable definitions to VarRefs. If a value is provided,
+ * wraps it as a nested-value VarRef. If not provided, creates
+ * an undefined VarRef (field will be omitted).
+ *
+ * Used when spreading fragments with partial variable values.
+ *
+ * @internal
+ */
+declare const createVarAssignments: <TSchema extends AnyGraphqlSchema, TVariableDefinitions extends InputTypeSpecifiers>(definitions: TVariableDefinitions, providedValues: AnyAssignableInput | void) => DeclaredVariables<TSchema, TVariableDefinitions>;
+/**
+ * Creates variable references from variable definitions.
+ *
+ * Maps each variable definition to a VarRef pointing to that variable.
+ * Used in operation builders to create the `$` context object.
+ *
+ * @internal
+ */
+declare const createVarRefs: <TSchema extends AnyGraphqlSchema, TVarDefinitions extends InputTypeSpecifiers>(definitions: TVarDefinitions) => DeclaredVariables<TSchema, TVarDefinitions>;
 //#endregion
 //#region packages/core/src/composer/fragment.d.ts
 /**
  * Type alias for a fragment builder function for a specific object type.
- * Used in codegen to generate explicit fragment builder types instead of mapped types.
+ *
+ * Used by codegen to generate explicit fragment builder types instead of
+ * expensive mapped types. This improves IDE performance for large schemas.
  */
 type FragmentBuilderFor<TSchema extends AnyGraphqlSchema, TTypeName$1 extends keyof TSchema["object"] & string, TAdapter extends AnyMetadataAdapter = DefaultMetadataAdapter> = <TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}>(options: {
   variables?: TVarDefinitions;
   metadata?: FragmentMetadataBuilder<ReturnType<typeof createVarRefs<TSchema, TVarDefinitions>>, ExtractAdapterTypes<TAdapter>["fragmentMetadata"]>;
   fields: FieldsBuilder<TSchema, TTypeName$1, TVarDefinitions, TFields>;
 }) => ReturnType<typeof Fragment.create<TSchema, TTypeName$1, TVarDefinitions, TFields>>;
+/**
+ * Creates fragment builder functions for all object types in the schema.
+ *
+ * Returns an object with a builder for each type (e.g., `fragment.User`, `fragment.Post`).
+ * Each builder creates a `Fragment` that can be spread into operations.
+ *
+ * @param schema - The GraphQL schema definition
+ * @param _adapter - Optional metadata adapter (for fragment metadata)
+ * @returns Object mapping type names to fragment builder functions
+ *
+ * @internal Used by `createGqlElementComposer`
+ */
 declare const createGqlFragmentComposers: <TSchema extends AnyGraphqlSchema, TAdapter extends AnyMetadataAdapter = DefaultMetadataAdapter>(schema: NoInfer<TSchema>, _adapter?: TAdapter) => { readonly [TTypeName in keyof TSchema["object"]]: TTypeName extends string ? <TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}>(options: {
   variables?: TVarDefinitions | undefined;
-  metadata?: FragmentMetadataBuilder<AssigningInput<TSchema, TVarDefinitions>, ExtractAdapterTypes<TAdapter>["fragmentMetadata"]> | undefined;
+  metadata?: FragmentMetadataBuilder<DeclaredVariables<TSchema, TVarDefinitions>, ExtractAdapterTypes<TAdapter>["fragmentMetadata"]> | undefined;
   fields: FieldsBuilder<TSchema, TTypeName, TVarDefinitions, TFields>;
 }) => Fragment<TTypeName, OptionalArg<AssignableInput<TSchema, TVarDefinitions>>, TFields & {
   [key: symbol]: never;
@@ -471,6 +911,18 @@ type PathSegment = string;
  * Proxy type that records property accesses.
  */
 type SelectableProxy<T> = T;
+/**
+ * Gets the full path to a variable within a nested structure.
+ *
+ * Returns path segments starting with `$variableName` followed by
+ * property accesses within that variable's value.
+ *
+ * @example
+ * ```typescript
+ * getVariablePath($.filter, p => p.user.id)
+ * // Returns: ["$filter", "user", "id"]
+ * ```
+ */
 declare const getVariablePath: <T, U>(varRef: VarRef<AnyVarRefBrand>, selector: (proxy: SelectableProxy<T>) => U) => readonly PathSegment[];
 //#endregion
 //#region packages/core/src/composer/var-builder.d.ts
@@ -501,7 +953,9 @@ type AssignableDefaultValue<TSchema extends AnyGraphqlSchema, TKind extends Inpu
   };
 }[TKind]>;
 /**
- * Variable specifier type.
+ * Represents a variable definition with its type, modifier, and optional default.
+ *
+ * Created by `$var.TypeName("modifier", { default?: ... })` calls.
  */
 type VarSpecifier<TKind extends InputTypeKind, TTypeName$1 extends string, TModifier extends TypeModifier, TDefaultFn extends (() => unknown) | null, TDirectives extends AnyConstDirectiveAttachments> = {
   kind: TKind;
@@ -559,7 +1013,19 @@ type WrappedVarMethod<TVarName extends string, TSchema extends AnyGraphqlSchema,
  */
 type VarBuilderMethods<TVarName extends string, TSchema extends AnyGraphqlSchema> = { [TName in AllInputTypeNames<TSchema>]: WrappedVarMethod<TVarName, TSchema, InferInputKind<TSchema, TName>, TName> };
 /**
- * Type for the variable builder function.
+ * Variable builder function type.
+ *
+ * Call with a variable name to get type-specific methods.
+ * Also provides utilities for extracting values from VarRefs.
+ *
+ * @example
+ * ```typescript
+ * // In operation definition:
+ * variables: { userId: $var("userId").ID("!") }
+ *
+ * // In metadata builder:
+ * $var.getValueAt($.userId, p => p)
+ * ```
  */
 type VarBuilder<TSchema extends AnyGraphqlSchema> = {
   <TVarName extends string>(varName: TVarName): VarBuilderMethods<TVarName, TSchema>;
@@ -585,11 +1051,26 @@ type SchemaAwareGetValueAt<TSchema extends AnyGraphqlSchema> = <T extends AnyVar
  */
 type SchemaAwareGetNameAt<TSchema extends AnyGraphqlSchema> = <T extends AnyVarRefBrand, U>(varRef: VarRef<T>, selector: (proxy: ResolveTypeFromMeta<TSchema, T>) => U) => string;
 /**
- * Creates a variable builder that uses injected input type methods.
+ * Creates a variable builder using injected input type methods.
+ *
+ * The returned builder provides type-safe variable definition methods
+ * for all input types in the schema. Also includes utilities for
+ * extracting variable names and values from VarRefs.
+ *
+ * @param inputTypeMethods - Methods for each input type (from codegen)
+ * @returns Variable builder with methods for all input types
+ *
+ * @internal Used by `createGqlElementComposer`
  */
 declare const createVarBuilder: <TSchema extends AnyGraphqlSchema>(inputTypeMethods: InputTypeMethods<TSchema>) => VarBuilder<TSchema>;
 //#endregion
 //#region packages/core/src/composer/gql-composer.d.ts
+/**
+ * Function signature for composing GraphQL elements (fragments or operations).
+ *
+ * The composer provides a context with builders for fragments, operations,
+ * variables, and colocation helpers.
+ */
 type GqlElementComposer<TContext> = <TResult extends AnyFragment | AnyOperation>(composeElement: (context: TContext) => TResult) => TResult;
 /**
  * Extracts the helpers type from an adapter.
@@ -607,24 +1088,57 @@ type ExtractMetadataAdapter<TAdapter extends AnyAdapter> = TAdapter extends {
  * This is the mapped type that's expensive to compute for large schemas.
  */
 type FragmentBuildersAll<TSchema extends AnyGraphqlSchema, TAdapter extends AnyMetadataAdapter = DefaultMetadataAdapter> = { readonly [TTypeName in keyof TSchema["object"]]: TTypeName extends string ? FragmentBuilderFor<TSchema, TTypeName, TAdapter> : never };
-type GqlElementComposerOptions<TSchema extends AnyGraphqlSchema, TAdapter extends AnyAdapter = DefaultAdapter> = {
+/**
+ * Configuration options for `createGqlElementComposer`.
+ */
+type GqlElementComposerOptions<TSchema extends AnyGraphqlSchema, TDirectiveMethods extends StandardDirectives, TAdapter extends AnyAdapter = DefaultAdapter> = {
+  /** Optional adapter for custom helpers and metadata handling. */
   adapter?: TAdapter;
+  /** Methods for building variable type specifiers. */
   inputTypeMethods: InputTypeMethods<TSchema>;
+  /** Optional custom directive methods (including schema-defined directives). */
+  directiveMethods?: TDirectiveMethods;
 };
 /**
  * Creates a GQL element composer for a given schema.
  *
- * @typeParam TSchema - The GraphQL schema type
- * @typeParam TAdapter - The adapter type (optional)
- * @typeParam TFragmentBuilders - Pre-computed fragment builders type (optional, for codegen optimization)
+ * This is the main entry point for defining GraphQL operations and fragments.
+ * The returned function provides a context with:
+ * - `fragment`: Builders for each object type
+ * - `query/mutation/subscription`: Operation builders
+ * - `$var`: Variable definition helpers
+ * - `$dir`: Field directive helpers (@skip, @include)
+ * - `$colocate`: Fragment colocation utilities
+ *
+ * @param schema - The GraphQL schema definition
+ * @param options - Configuration including input type methods and optional adapter
+ * @returns Element composer function
+ *
+ * @example
+ * ```typescript
+ * const gql = createGqlElementComposer(schema, { inputTypeMethods });
+ *
+ * const GetUser = gql(({ query, $var, $dir }) =>
+ *   query.operation({
+ *     name: "GetUser",
+ *     variables: { showEmail: $var("showEmail").Boolean("!") },
+ *     fields: ({ f, $ }) => ({
+ *       ...f.user({ id: "1" })(({ f }) => ({
+ *         ...f.name(),
+ *         ...f.email({}, { directives: [$dir.skip({ if: $.showEmail })] }),
+ *       })),
+ *     }),
+ *   })
+ * );
+ * ```
  */
-declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFragmentBuilders, TAdapter extends AnyAdapter = DefaultAdapter>(schema: NoInfer<TSchema>, options: GqlElementComposerOptions<NoInfer<TSchema>, NoInfer<TAdapter>>) => GqlElementComposer<{
+declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFragmentBuilders, TDirectiveMethods extends StandardDirectives, TAdapter extends AnyAdapter = DefaultAdapter>(schema: NoInfer<TSchema>, options: GqlElementComposerOptions<NoInfer<TSchema>, NoInfer<TDirectiveMethods>, NoInfer<TAdapter>>) => GqlElementComposer<{
   fragment: TFragmentBuilders;
   query: {
     operation: <TOperationName extends string, TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}, TOperationMetadata = unknown>(options: {
       name: TOperationName;
       variables?: TVarDefinitions | undefined;
-      metadata?: MetadataBuilder<AssigningInput<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
+      metadata?: MetadataBuilder<DeclaredVariables<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
       fields: FieldsBuilder<TSchema, TSchema["operations"]["query"] & keyof TSchema["object"] & string, TVarDefinitions, TFields>;
     }) => Operation<"query", TOperationName, (keyof TVarDefinitions & string)[], ConstAssignableInput<TSchema, TVarDefinitions>, TFields, InferFields<TSchema, TFields>>;
   };
@@ -632,7 +1146,7 @@ declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFrag
     operation: <TOperationName extends string, TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}, TOperationMetadata = unknown>(options: {
       name: TOperationName;
       variables?: TVarDefinitions | undefined;
-      metadata?: MetadataBuilder<AssigningInput<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
+      metadata?: MetadataBuilder<DeclaredVariables<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
       fields: FieldsBuilder<TSchema, TSchema["operations"]["mutation"] & keyof TSchema["object"] & string, TVarDefinitions, TFields>;
     }) => Operation<"mutation", TOperationName, (keyof TVarDefinitions & string)[], ConstAssignableInput<TSchema, TVarDefinitions>, TFields, InferFields<TSchema, TFields>>;
   };
@@ -640,15 +1154,31 @@ declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFrag
     operation: <TOperationName extends string, TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}, TOperationMetadata = unknown>(options: {
       name: TOperationName;
       variables?: TVarDefinitions | undefined;
-      metadata?: MetadataBuilder<AssigningInput<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
+      metadata?: MetadataBuilder<DeclaredVariables<TSchema, TVarDefinitions>, TOperationMetadata, ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["aggregatedFragmentMetadata"], ExtractAdapterTypes<ExtractMetadataAdapter<TAdapter>>["schemaLevel"]> | undefined;
       fields: FieldsBuilder<TSchema, TSchema["operations"]["subscription"] & keyof TSchema["object"] & string, TVarDefinitions, TFields>;
     }) => Operation<"subscription", TOperationName, (keyof TVarDefinitions & string)[], ConstAssignableInput<TSchema, TVarDefinitions>, TFields, InferFields<TSchema, TFields>>;
   };
   $var: VarBuilder<TSchema>;
+  $dir: TDirectiveMethods;
   $colocate: <TEntries extends ColocatedEntries>(entries: TEntries) => ColocatedFields<TEntries>;
 } & ExtractHelpers<TAdapter>>;
 //#endregion
 //#region packages/core/src/composer/operation.d.ts
+/**
+ * Creates a factory for composing GraphQL operations.
+ *
+ * Returns a curried function: first select operation type (query/mutation/subscription),
+ * then define the operation with name, variables, and fields.
+ *
+ * Handles metadata aggregation from fragments (sync or async) and builds
+ * the TypedDocumentNode automatically.
+ *
+ * @param schema - The GraphQL schema definition
+ * @param adapter - Optional metadata adapter for custom metadata handling
+ * @returns Operation type selector function
+ *
+ * @internal Used by `createGqlElementComposer`
+ */
 declare const createOperationComposerFactory: <TSchema extends AnyGraphqlSchema, TAdapter extends AnyMetadataAdapter = DefaultMetadataAdapter>(schema: NoInfer<TSchema>, adapter?: TAdapter) => <TOperationType extends OperationType>(operationType: TOperationType) => <TOperationName extends string, TFields extends AnyFields, TVarDefinitions extends InputTypeSpecifiers = {}, TOperationMetadata = unknown>(options: {
   name: TOperationName;
   variables?: TVarDefinitions;
@@ -661,7 +1191,7 @@ declare const hidden: <T>() => (() => T);
 type Hidden<T> = () => T;
 //#endregion
 //#region packages/core/src/utils/wrap-by-key.d.ts
-declare function wrapByKey<TName$1 extends string, TValue>(name: TName$1, value: TValue): { [K in TName$1]: TValue };
+declare function wrapByKey<TName$1 extends string, TValue$1>(name: TName$1, value: TValue$1): { [K in TName$1]: TValue$1 };
 //#endregion
-export { NestedUnionFieldsBuilder as $, AnyOperationOf as A, AssignableInput as At, AnyFieldSelectionFactory as B, withFragmentUsageCollection as C, FieldSelectionTemplateOf as Ct, createVarRefs as D, AnyAssignableInput as Dt, createVarAssignments as E, AnyDirectiveAttachments as Et, FragmentInferMeta as F, AnyConstAssignableInput as Ft, FieldSelectionFactoryObjectReturn as G, FieldSelectionFactories as H, GqlElement as I, AnyConstAssignableInputValue as It, FieldSelectionFactoryUnionReturn as J, FieldSelectionFactoryPrimitiveReturn as K, GqlElementAttachment as L, ConstAssignableInput as Lt, OperationInferMeta as M, AssignableInputValue as Mt, AnyFragment as N, AssigningInput as Nt, createFieldFactories as O, AnyAssignableInputValue as Ot, Fragment as P, AnyConstDirectiveAttachments as Pt, NestedObjectFieldsBuilderTools as Q, GqlElementContext as R, ConstAssignableInputValue as Rt, recordFragmentUsage as S, AnyNestedUnion as St, createGqlFragmentComposers as T, InferFields as Tt, FieldSelectionFactory as U, AnyFieldSelectionFactoryReturn as V, FieldSelectionFactoryFieldArguments as W, FieldsBuilderTools as X, FieldsBuilder as Y, NestedObjectFieldsBuilder as Z, VarSpecifier as _, buildWithTypeModifier as _t, ExtractMetadataAdapter as a, ColocateHelper as at, createVarMethodFactory as b, AnyFields as bt, GqlElementComposerOptions as c, createColocateHelper as ct, InputTypeMethods as d, Tuple as dt, EmptyObject as et, ResolveTypeFromMeta as f, UnionToIntersection as ft, VarBuilderMethods as g, buildOperationTypeNode as gt, VarBuilder as h, buildDocument as ht, createOperationComposerFactory as i, empty as it, Operation as j, AssignableInputByFieldName as jt, AnyOperation as k, AnyAssigningInput as kt, createGqlElementComposer as l, StripFunctions as lt, SchemaAwareGetValueAt as m, buildConstValueNode as mt, Hidden as n, OptionalArg as nt, FragmentBuildersAll as o, ColocatedEntries as ot, SchemaAwareGetNameAt as p, buildArgumentValue as pt, FieldSelectionFactoryReturn as q, hidden as r, SwitchIfOmittable as rt, GqlElementComposer as s, ColocatedFields as st, wrapByKey as t, IfOmittable as tt, InputTypeMethod as u, StripSymbols as ut, createVarBuilder as v, AbstractFieldSelection as vt, FragmentBuilderFor as w, InferField as wt, FragmentUsageRecord as x, AnyNestedObject as xt, createVarMethod as y, AnyFieldSelection as yt, GqlElementDefinitionFactory as z, GetAssignableType as zt };
-//# sourceMappingURL=index-rBHv6RJz.d.ts.map
+export { NestedUnionFieldsBuilder as $, AnyDirectiveRefBrand as $t, AnyOperationOf as A, AbstractFieldSelection as At, AnyFieldSelectionFactory as B, AnyAssignableInputValue as Bt, withFragmentUsageCollection as C, Tuple as Ct, createVarRefs as D, buildDocument as Dt, createVarAssignments as E, buildConstValueNode as Et, FragmentInferMeta as F, FieldSelectionTemplateOf as Ft, FieldSelectionFactoryObjectReturn as G, FieldArgumentValue as Gt, FieldSelectionFactories as H, AssignableInput as Ht, GqlElement as I, InferField as It, FieldSelectionFactoryUnionReturn as J, AnyConstAssignableInputValue as Jt, FieldSelectionFactoryPrimitiveReturn as K, AnyConstDirectiveAttachments as Kt, GqlElementAttachment as L, InferFields as Lt, OperationInferMeta as M, AnyFields as Mt, AnyFragment as N, AnyNestedObject as Nt, createFieldFactories as O, buildOperationTypeNode as Ot, Fragment as P, AnyNestedUnion as Pt, NestedObjectFieldsBuilderTools as Q, AnyDirectiveRef as Qt, GqlElementContext as R, AnyDirectiveAttachments as Rt, recordFragmentUsage as S, StripSymbols as St, createGqlFragmentComposers as T, buildArgumentValue as Tt, FieldSelectionFactory as U, AssignableInputByFieldName as Ut, AnyFieldSelectionFactoryReturn as V, AnyAssigningInput as Vt, FieldSelectionFactoryFieldArguments as W, DeclaredVariables as Wt, FieldsBuilderTools as X, ConstAssignableInputValue as Xt, FieldsBuilder as Y, ConstAssignableInput as Yt, NestedObjectFieldsBuilder as Z, GetAssignableType as Zt, VarSpecifier as _, ColocateHelper as _t, ExtractMetadataAdapter as a, AttachmentShape as at, createVarMethodFactory as b, createColocateHelper as bt, GqlElementComposerOptions as c, AnyDirectiveMethod as ct, InputTypeMethods as d, DirectiveMethod as dt, DirectiveLocation as en, EmptyObject as et, ResolveTypeFromMeta as f, StandardDirectives as ft, VarBuilderMethods as g, isDirectiveRef as gt, VarBuilder as h, createStandardDirectives as ht, createOperationComposerFactory as i, empty as it, Operation as j, AnyFieldSelection as jt, AnyOperation as k, buildWithTypeModifier as kt, createGqlElementComposer as l, DirectiveArgValue as lt, SchemaAwareGetValueAt as m, createDirectiveMethod as mt, Hidden as n, DirectiveRefInner as nn, OptionalArg as nt, FragmentBuildersAll as o, AttachmentToProperty as ot, SchemaAwareGetNameAt as p, createDirectiveBuilder as pt, FieldSelectionFactoryReturn as q, AnyConstAssignableInput as qt, hidden as r, SwitchIfOmittable as rt, GqlElementComposer as s, AttachmentsTupleToIntersection as st, wrapByKey as t, DirectiveRef as tn, IfOmittable as tt, InputTypeMethod as u, DirectiveBuilder as ut, createVarBuilder as v, ColocatedEntries as vt, FragmentBuilderFor as w, UnionToIntersection as wt, FragmentUsageRecord as x, StripFunctions as xt, createVarMethod as y, ColocatedFields as yt, GqlElementDefinitionFactory as z, AnyAssignableInput as zt };
+//# sourceMappingURL=index-Ib9pb2Si.d.cts.map