@soda-gql/core 0.8.0 → 0.8.2

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

@@ -1,11 +1,11 @@
-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/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,13 +83,19 @@ 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
@@ -164,10 +170,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 +263,35 @@ 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/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,22 +317,45 @@ 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;
 }) => 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"];
@@ -305,42 +400,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 +543,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 +572,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 +626,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 +748,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 +790,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 +850,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 +888,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,16 +925,41 @@ 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 };
+/**
+ * Configuration options for `createGqlElementComposer`.
+ */
 type GqlElementComposerOptions<TSchema extends AnyGraphqlSchema, TAdapter extends AnyAdapter = DefaultAdapter> = {
+  /** Optional adapter for custom helpers and metadata handling. */
   adapter?: TAdapter;
+  /** Methods for building variable type specifiers. */
   inputTypeMethods: InputTypeMethods<TSchema>;
 };
 /**
  * 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
+ * - `$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 }) =>
+ *   query.operation({
+ *     name: "GetUser",
+ *     variables: { id: $var.ID("!") },
+ *     fields: ({ f, $ }) => ({ ...f.user({ id: $.id })(...) }),
+ *   })
+ * );
+ * ```
  */
 declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFragmentBuilders, TAdapter extends AnyAdapter = DefaultAdapter>(schema: NoInfer<TSchema>, options: GqlElementComposerOptions<NoInfer<TSchema>, NoInfer<TAdapter>>) => GqlElementComposer<{
   fragment: TFragmentBuilders;
@@ -624,7 +967,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"]["query"] & keyof TSchema["object"] & string, TVarDefinitions, TFields>;
     }) => Operation<"query", TOperationName, (keyof TVarDefinitions & string)[], ConstAssignableInput<TSchema, TVarDefinitions>, TFields, InferFields<TSchema, TFields>>;
   };
@@ -632,7 +975,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,7 +983,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"]["subscription"] & keyof TSchema["object"] & string, TVarDefinitions, TFields>;
     }) => Operation<"subscription", TOperationName, (keyof TVarDefinitions & string)[], ConstAssignableInput<TSchema, TVarDefinitions>, TFields, InferFields<TSchema, TFields>>;
   };
@@ -649,6 +992,21 @@ declare const createGqlElementComposer: <TSchema extends AnyGraphqlSchema, TFrag
 } & 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 +1019,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 $, AnyOperationOf as A, AnyAssignableInput as At, AnyFieldSelectionFactory as B, ConstAssignableInput as Bt, withFragmentUsageCollection as C, AnyFields as Ct, createVarRefs as D, InferField as Dt, createVarAssignments as E, FieldSelectionTemplateOf as Et, FragmentInferMeta as F, DeclaredVariables as Ft, FieldSelectionFactoryObjectReturn as G, FieldSelectionFactories as H, GetAssignableType as Ht, GqlElement as I, FieldArgumentValue as It, FieldSelectionFactoryUnionReturn as J, FieldSelectionFactoryPrimitiveReturn as K, GqlElementAttachment as L, AnyConstDirectiveAttachments as Lt, OperationInferMeta as M, AnyAssigningInput as Mt, AnyFragment as N, AssignableInput as Nt, createFieldFactories as O, InferFields as Ot, Fragment as P, AssignableInputByFieldName as Pt, NestedObjectFieldsBuilderTools as Q, GqlElementContext as R, AnyConstAssignableInput as Rt, recordFragmentUsage as S, AnyFieldSelection as St, createGqlFragmentComposers as T, AnyNestedUnion as Tt, FieldSelectionFactory as U, AnyFieldSelectionFactoryReturn as V, ConstAssignableInputValue as Vt, FieldSelectionFactoryFieldArguments as W, FieldsBuilderTools as X, FieldsBuilder as Y, NestedObjectFieldsBuilder as Z, VarSpecifier as _, buildConstValueNode as _t, ExtractMetadataAdapter as a, AttachmentShape as at, createVarMethodFactory as b, buildWithTypeModifier as bt, GqlElementComposerOptions as c, ColocateHelper as ct, InputTypeMethods as d, createColocateHelper as dt, EmptyObject as et, ResolveTypeFromMeta as f, StripFunctions as ft, VarBuilderMethods as g, buildArgumentValue as gt, VarBuilder as h, UnionToIntersection as ht, createOperationComposerFactory as i, empty as it, Operation as j, AnyAssignableInputValue as jt, AnyOperation as k, AnyDirectiveAttachments as kt, createGqlElementComposer as l, ColocatedEntries as lt, SchemaAwareGetValueAt as m, Tuple as mt, Hidden as n, OptionalArg as nt, FragmentBuildersAll as o, AttachmentToProperty as ot, SchemaAwareGetNameAt as p, StripSymbols as pt, FieldSelectionFactoryReturn as q, hidden as r, SwitchIfOmittable as rt, GqlElementComposer as s, AttachmentsTupleToIntersection as st, wrapByKey as t, IfOmittable as tt, InputTypeMethod as u, ColocatedFields as ut, createVarBuilder as v, buildDocument as vt, FragmentBuilderFor as w, AnyNestedObject as wt, FragmentUsageRecord as x, AbstractFieldSelection as xt, createVarMethod as y, buildOperationTypeNode as yt, GqlElementDefinitionFactory as z, AnyConstAssignableInputValue as zt };
+//# sourceMappingURL=index-CGLXqMlv.d.cts.map