@soda-gql/core 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { $ as NestedValueElement, A as InputDepthOverrides, At as appendToPath, B as FragmentMetaInfo, C as ObjectTypeProfile, Ct as GetSignature, D as DefaultDepth, Dt as ConstValues, E as DecrementDepth, Et as ConstValue, F as AnyMetadataAdapter, G as FragmentMetadataBuilder, H as createDefaultAdapter, I as DefaultAdapter, J as MetadataBuilderTools, K as FragmentMetadataBuilderTools, L as DefaultMetadataAdapter, M as NumberToDepth, Mt as isListType, N as Adapter, Nt as withFieldPath, O as DepthCounter, Ot as FieldPath, P as AnyAdapter, Q as NestedValue, R as ExtractAdapterTypes, S as GetModifiedType, St as ApplyTypeModifier, T as TypeProfile, Tt as ValidTypeModifier, U as defaultMetadataAdapter, V as MetadataAdapter, W as ExtractMetadata, X as AnyVarRef, Y as OperationMetadata, Z as AnyVarRefBrand, _ as ScalarDefinition, _t as OutputTypeKind, a as EnumDefinition, at as AnyTypeSpecifier, b as UnionTypeRecord, bt as OutputTypenameSpecifier, c as InferOutputProfile, ct as InputInputObjectSpecifier, d as ObjectDefinition, 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, j as IsDepthExhausted, jt as getCurrentFieldPath, k as GetInputTypeDepth, kt as FieldPathSegment, l as InputDefinition, lt as InputScalarSpecifier, m as OperationType, mt as OutputInferrableTypeSpecifier, n as AnyFieldName, nt as createVarRefFromNestedValue, o as InferInputKind, ot as InputEnumSpecifier, p as OperationRoots, pt as OutputEnumSpecifier, q as MetadataBuilder, r as AnyGraphqlSchema, rt as createVarRefFromVariable, s as InferInputProfile, st as InputInferrableTypeSpecifier, t as AllInputTypeNames, tt as VarRefInner, u as InputFieldRecord, ut as InputTypeKind, v as UnionDefinition, vt as OutputTypeSpecifier, w as PrimitiveTypeProfile, wt as TypeModifier, x as GetConstAssignableType, xt as OutputUnionSpecifier, y as UnionMemberName, yt as OutputTypeSpecifiers, z as ExtractUnifiedAdapterTypes } from "./schema-2qqtKss4.js";
-import { $ as NestedUnionFieldsBuilder, A as AnyOperationOf, At as AnyAssignableInput, B as AnyFieldSelectionFactory, Bt as ConstAssignableInput, C as withFragmentUsageCollection, Ct as AnyFields, D as createVarRefs, Dt as InferField, E as createVarAssignments, Et as FieldSelectionTemplateOf, F as FragmentInferMeta, Ft as DeclaredVariables, G as FieldSelectionFactoryObjectReturn, H as FieldSelectionFactories, Ht as GetAssignableType, I as GqlElement, It as FieldArgumentValue, J as FieldSelectionFactoryUnionReturn, K as FieldSelectionFactoryPrimitiveReturn, L as GqlElementAttachment, Lt as AnyConstDirectiveAttachments, M as OperationInferMeta, Mt as AnyAssigningInput, N as AnyFragment, Nt as AssignableInput, O as createFieldFactories, Ot as InferFields, P as Fragment, Pt as AssignableInputByFieldName, Q as NestedObjectFieldsBuilderTools, R as GqlElementContext, Rt as AnyConstAssignableInput, S as recordFragmentUsage, St as AnyFieldSelection, T as createGqlFragmentComposers, Tt as AnyNestedUnion, U as FieldSelectionFactory, V as AnyFieldSelectionFactoryReturn, Vt as ConstAssignableInputValue, W as FieldSelectionFactoryFieldArguments, X as FieldsBuilderTools, Y as FieldsBuilder, Z as NestedObjectFieldsBuilder, _ as VarSpecifier, _t as buildConstValueNode, a as ExtractMetadataAdapter, at as AttachmentShape, b as createVarMethodFactory, bt as buildWithTypeModifier, c as GqlElementComposerOptions, ct as ColocateHelper, d as InputTypeMethods, dt as createColocateHelper, et as EmptyObject, f as ResolveTypeFromMeta, ft as StripFunctions, g as VarBuilderMethods, gt as buildArgumentValue, h as VarBuilder, ht as UnionToIntersection, i as createOperationComposerFactory, it as empty, j as Operation, jt as AnyAssignableInputValue, k as AnyOperation, kt as AnyDirectiveAttachments, l as createGqlElementComposer, lt as ColocatedEntries, m as SchemaAwareGetValueAt, mt as Tuple, n as Hidden, nt as OptionalArg, o as FragmentBuildersAll, ot as AttachmentToProperty, p as SchemaAwareGetNameAt, pt as StripSymbols, q as FieldSelectionFactoryReturn, r as hidden, rt as SwitchIfOmittable, s as GqlElementComposer, st as AttachmentsTupleToIntersection, t as wrapByKey, tt as IfOmittable, u as InputTypeMethod, ut as ColocatedFields, v as createVarBuilder, vt as buildDocument, w as FragmentBuilderFor, wt as AnyNestedObject, x as FragmentUsageRecord, xt as AbstractFieldSelection, y as createVarMethod, yt as buildOperationTypeNode, z as GqlElementDefinitionFactory, zt as AnyConstAssignableInputValue } from "./index-tyIBKIKa.js";
+import { $ as NestedUnionFieldsBuilder, $t as AnyDirectiveRefBrand, A as AnyOperationOf, At as AbstractFieldSelection, B as AnyFieldSelectionFactory, Bt as AnyAssignableInputValue, C as withFragmentUsageCollection, Ct as Tuple, D as createVarRefs, Dt as buildDocument, E as createVarAssignments, Et as buildConstValueNode, F as FragmentInferMeta, Ft as FieldSelectionTemplateOf, G as FieldSelectionFactoryObjectReturn, Gt as FieldArgumentValue, H as FieldSelectionFactories, Ht as AssignableInput, I as GqlElement, It as InferField, J as FieldSelectionFactoryUnionReturn, Jt as AnyConstAssignableInputValue, K as FieldSelectionFactoryPrimitiveReturn, Kt as AnyConstDirectiveAttachments, L as GqlElementAttachment, Lt as InferFields, M as OperationInferMeta, Mt as AnyFields, N as AnyFragment, Nt as AnyNestedObject, O as createFieldFactories, Ot as buildOperationTypeNode, P as Fragment, Pt as AnyNestedUnion, Q as NestedObjectFieldsBuilderTools, Qt as AnyDirectiveRef, R as GqlElementContext, Rt as AnyDirectiveAttachments, S as recordFragmentUsage, St as StripSymbols, T as createGqlFragmentComposers, Tt as buildArgumentValue, U as FieldSelectionFactory, Ut as AssignableInputByFieldName, V as AnyFieldSelectionFactoryReturn, Vt as AnyAssigningInput, W as FieldSelectionFactoryFieldArguments, Wt as DeclaredVariables, X as FieldsBuilderTools, Xt as ConstAssignableInputValue, Y as FieldsBuilder, Yt as ConstAssignableInput, Z as NestedObjectFieldsBuilder, Zt as GetAssignableType, _ as VarSpecifier, _t as ColocateHelper, a as ExtractMetadataAdapter, at as AttachmentShape, b as createVarMethodFactory, bt as createColocateHelper, c as GqlElementComposerOptions, ct as AnyDirectiveMethod, d as InputTypeMethods, dt as DirectiveMethod, en as DirectiveLocation, et as EmptyObject, f as ResolveTypeFromMeta, ft as StandardDirectives, g as VarBuilderMethods, gt as isDirectiveRef, h as VarBuilder, ht as createStandardDirectives, i as createOperationComposerFactory, it as empty, j as Operation, jt as AnyFieldSelection, k as AnyOperation, kt as buildWithTypeModifier, l as createGqlElementComposer, lt as DirectiveArgValue, m as SchemaAwareGetValueAt, mt as createDirectiveMethod, n as Hidden, nn as DirectiveRefInner, nt as OptionalArg, o as FragmentBuildersAll, ot as AttachmentToProperty, p as SchemaAwareGetNameAt, pt as createDirectiveBuilder, q as FieldSelectionFactoryReturn, qt as AnyConstAssignableInput, r as hidden, rt as SwitchIfOmittable, s as GqlElementComposer, st as AttachmentsTupleToIntersection, t as wrapByKey, tn as DirectiveRef, tt as IfOmittable, u as InputTypeMethod, ut as DirectiveBuilder, v as createVarBuilder, vt as ColocatedEntries, w as FragmentBuilderFor, wt as UnionToIntersection, x as FragmentUsageRecord, xt as StripFunctions, y as createVarMethod, yt as ColocatedFields, z as GqlElementDefinitionFactory, zt as AnyAssignableInput } from "./index-wkJ6KSwK.js";
 import { n as defineOperationRoots, r as defineScalar, t as define } from "./schema-builder-Dhss2O1I.js";
 
 //#region packages/core/src/types/type-foundation/modified-type-name.d.ts
@@ -132,5 +132,5 @@ declare const unsafeOutputType: {
   };
 };
 //#endregion
-export { AbstractFieldSelection, Adapter, AllInputTypeNames, AnyAdapter, AnyAssignableInput, AnyAssignableInputValue, AnyAssigningInput, AnyConstAssignableInput, AnyConstAssignableInputValue, AnyConstDirectiveAttachments, AnyDefaultValue, AnyDirectiveAttachments, AnyFieldName, AnyFieldSelection, AnyFieldSelectionFactory, AnyFieldSelectionFactoryReturn, AnyFields, AnyFragment, AnyGraphqlSchema, AnyMetadataAdapter, AnyNestedObject, AnyNestedUnion, AnyOperation, AnyOperationOf, AnyTypeName, AnyTypeSpecifier, AnyVarRef, AnyVarRefBrand, ApplyTypeModifier, AssignableInput, AssignableInputByFieldName, AttachmentShape, AttachmentToProperty, AttachmentsTupleToIntersection, ColocateHelper, ColocatedEntries, ColocatedFields, ConstAssignableInput, ConstAssignableInputValue, ConstValue, ConstValues, DeclaredVariables, DecrementDepth, DefaultAdapter, DefaultDepth, DefaultMetadataAdapter, DepthCounter, EmptyObject, EnumDefinition, ExtractAdapterTypes, ExtractMetadata, ExtractMetadataAdapter, ExtractUnifiedAdapterTypes, FieldArgumentValue, FieldPath, FieldPathSegment, FieldSelectionFactories, FieldSelectionFactory, FieldSelectionFactoryFieldArguments, FieldSelectionFactoryObjectReturn, FieldSelectionFactoryPrimitiveReturn, FieldSelectionFactoryReturn, FieldSelectionFactoryUnionReturn, FieldSelectionTemplateOf, FieldsBuilder, FieldsBuilderTools, Fragment, FragmentBuilderFor, FragmentBuildersAll, FragmentInferMeta, FragmentMetaInfo, FragmentMetadataBuilder, FragmentMetadataBuilderTools, FragmentUsageRecord, GetAssignableType, GetConstAssignableType, GetInputTypeDepth, GetModifiedType, GetSignature, GqlElement, GqlElementAttachment, GqlElementComposer, GqlElementComposerOptions, GqlElementContext, GqlElementDefinitionFactory, Hidden, IfOmittable, InferField, InferFields, InferInputKind, InferInputProfile, InferOutputProfile, InputDefinition, InputDepthOverrides, InputEnumSpecifier, InputFieldRecord, InputInferrableTypeSpecifier, InputInputObjectSpecifier, InputScalarSpecifier, InputTypeKind, InputTypeMethod, InputTypeMethods, InputTypeSpecifier, InputTypeSpecifiers, IsDepthExhausted, MetadataAdapter, MetadataBuilder, MetadataBuilderTools, ModifiedTypeName, NestedObjectFieldsBuilder, NestedObjectFieldsBuilderTools, NestedUnionFieldsBuilder, NestedValue, NestedValueElement, NumberToDepth, ObjectDefinition, ObjectFieldRecord, ObjectTypeProfile, Operation, OperationInferMeta, OperationMetadata, OperationRoots, OperationType, OptionalArg, OutputEnumSpecifier, OutputInferrableTypeSpecifier, OutputObjectSpecifier, OutputScalarSpecifier, OutputTypeKind, OutputTypeSpecifier, OutputTypeSpecifiers, OutputTypenameSpecifier, OutputUnionSpecifier, PickTypeSpecifierByFieldName, PrimitiveTypeProfile, ResolveInputProfileFromMeta, ResolveTypeFromMeta, ScalarDefinition, SchemaAwareGetNameAt, SchemaAwareGetValueAt, StripFunctions, StripSymbols, SwitchIfOmittable, Tuple, TypeModifier, TypeProfile, UnionDefinition, UnionMemberName, UnionToIntersection, UnionTypeRecord, ValidTypeModifier, VarBuilder, VarBuilderMethods, VarRef, VarRefInner, VarSpecifier, appendToPath, buildArgumentValue, buildConstValueNode, buildDocument, buildOperationTypeNode, buildWithTypeModifier, createColocateHelper, createDefaultAdapter, createFieldFactories, createGqlElementComposer, createGqlFragmentComposers, createOperationComposerFactory, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefFromNestedValue, createVarRefFromVariable, createVarRefs, defaultMetadataAdapter, define, defineOperationRoots, defineScalar, empty, getCurrentFieldPath, hidden, isListType, parseModifiedTypeName, recordFragmentUsage, unsafeInputType, unsafeOutputType, withFieldPath, withFragmentUsageCollection, wrapByKey };
+export { AbstractFieldSelection, Adapter, AllInputTypeNames, AnyAdapter, AnyAssignableInput, AnyAssignableInputValue, AnyAssigningInput, AnyConstAssignableInput, AnyConstAssignableInputValue, AnyConstDirectiveAttachments, AnyDefaultValue, AnyDirectiveAttachments, AnyDirectiveMethod, AnyDirectiveRef, AnyDirectiveRefBrand, AnyFieldName, AnyFieldSelection, AnyFieldSelectionFactory, AnyFieldSelectionFactoryReturn, AnyFields, AnyFragment, AnyGraphqlSchema, AnyMetadataAdapter, AnyNestedObject, AnyNestedUnion, AnyOperation, AnyOperationOf, AnyTypeName, AnyTypeSpecifier, AnyVarRef, AnyVarRefBrand, ApplyTypeModifier, AssignableInput, AssignableInputByFieldName, AttachmentShape, AttachmentToProperty, AttachmentsTupleToIntersection, ColocateHelper, ColocatedEntries, ColocatedFields, ConstAssignableInput, ConstAssignableInputValue, ConstValue, ConstValues, DeclaredVariables, DecrementDepth, DefaultAdapter, DefaultDepth, DefaultMetadataAdapter, DepthCounter, DirectiveArgValue, DirectiveBuilder, DirectiveLocation, DirectiveMethod, DirectiveRef, DirectiveRefInner, EmptyObject, EnumDefinition, ExtractAdapterTypes, ExtractMetadata, ExtractMetadataAdapter, ExtractUnifiedAdapterTypes, FieldArgumentValue, FieldPath, FieldPathSegment, FieldSelectionFactories, FieldSelectionFactory, FieldSelectionFactoryFieldArguments, FieldSelectionFactoryObjectReturn, FieldSelectionFactoryPrimitiveReturn, FieldSelectionFactoryReturn, FieldSelectionFactoryUnionReturn, FieldSelectionTemplateOf, FieldsBuilder, FieldsBuilderTools, Fragment, FragmentBuilderFor, FragmentBuildersAll, FragmentInferMeta, FragmentMetaInfo, FragmentMetadataBuilder, FragmentMetadataBuilderTools, FragmentUsageRecord, GetAssignableType, GetConstAssignableType, GetInputTypeDepth, GetModifiedType, GetSignature, GqlElement, GqlElementAttachment, GqlElementComposer, GqlElementComposerOptions, GqlElementContext, GqlElementDefinitionFactory, Hidden, IfOmittable, InferField, InferFields, InferInputKind, InferInputProfile, InferOutputProfile, InputDefinition, InputDepthOverrides, InputEnumSpecifier, InputFieldRecord, InputInferrableTypeSpecifier, InputInputObjectSpecifier, InputScalarSpecifier, InputTypeKind, InputTypeMethod, InputTypeMethods, InputTypeSpecifier, InputTypeSpecifiers, IsDepthExhausted, MetadataAdapter, MetadataBuilder, MetadataBuilderTools, ModifiedTypeName, NestedObjectFieldsBuilder, NestedObjectFieldsBuilderTools, NestedUnionFieldsBuilder, NestedValue, NestedValueElement, NumberToDepth, ObjectDefinition, ObjectFieldRecord, ObjectTypeProfile, Operation, OperationInferMeta, OperationMetadata, OperationRoots, OperationType, OptionalArg, OutputEnumSpecifier, OutputInferrableTypeSpecifier, OutputObjectSpecifier, OutputScalarSpecifier, OutputTypeKind, OutputTypeSpecifier, OutputTypeSpecifiers, OutputTypenameSpecifier, OutputUnionSpecifier, PickTypeSpecifierByFieldName, PrimitiveTypeProfile, ResolveInputProfileFromMeta, ResolveTypeFromMeta, ScalarDefinition, SchemaAwareGetNameAt, SchemaAwareGetValueAt, StandardDirectives, StripFunctions, StripSymbols, SwitchIfOmittable, Tuple, TypeModifier, TypeProfile, UnionDefinition, UnionMemberName, UnionToIntersection, UnionTypeRecord, ValidTypeModifier, VarBuilder, VarBuilderMethods, VarRef, VarRefInner, VarSpecifier, appendToPath, buildArgumentValue, buildConstValueNode, buildDocument, buildOperationTypeNode, buildWithTypeModifier, createColocateHelper, createDefaultAdapter, createDirectiveBuilder, createDirectiveMethod, createFieldFactories, createGqlElementComposer, createGqlFragmentComposers, createOperationComposerFactory, createStandardDirectives, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefFromNestedValue, createVarRefFromVariable, createVarRefs, defaultMetadataAdapter, define, defineOperationRoots, defineScalar, empty, getCurrentFieldPath, hidden, isDirectiveRef, isListType, parseModifiedTypeName, recordFragmentUsage, unsafeInputType, unsafeOutputType, withFieldPath, withFragmentUsageCollection, wrapByKey };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,37 @@
 import { a as unsafeOutputType, i as unsafeInputType, n as defineOperationRoots, o as wrapByKey, r as defineScalar, t as define } from "./schema-BiYcVVvm.js";
 import { Kind, OperationTypeNode } from "graphql";
 
+//#region packages/core/src/types/type-foundation/directive-ref.ts
+/**
+* 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"],
+* });
+* ```
+*/
+var DirectiveRef = class {
+	constructor(inner) {
+		this.inner = inner;
+	}
+	/**
+	* Extracts the inner structure from a DirectiveRef.
+	* Used by build-document.ts to generate DirectiveNode.
+	*/
+	static getInner(ref) {
+		return ref.inner;
+	}
+};
+
+//#endregion
 //#region packages/core/src/types/type-foundation/var-ref.ts
 var VarRef = class {
 	constructor(inner) {
@@ -97,6 +128,41 @@ const buildArguments = (args) => Object.entries(args ?? {}).map(([name, value])
 		value: valueNode
 	} : null;
 }).filter((item) => item !== null);
+/**
+* Validates that a directive can be used at the specified location.
+*
+* @param directive - The directive reference to validate
+* @param expectedLocation - The location where the directive is being used
+* @throws Error if the directive is not valid at the specified location
+*/
+const validateDirectiveLocation = (directive, expectedLocation) => {
+	const inner = DirectiveRef.getInner(directive);
+	if (!inner.locations.includes(expectedLocation)) throw new Error(`Directive @${inner.name} cannot be used on ${expectedLocation}. Valid locations: ${inner.locations.join(", ")}`);
+};
+/**
+* Builds DirectiveNode array from field directives.
+*
+* Filters for DirectiveRef instances, validates their locations,
+* and converts them to GraphQL AST DirectiveNode objects.
+*
+* @param directives - Array of directive references (or unknown values)
+* @param location - The location context for validation
+* @returns Array of DirectiveNode for the GraphQL AST
+*/
+const buildDirectives = (directives, location) => {
+	return directives.filter((d) => d instanceof DirectiveRef).map((directive) => {
+		validateDirectiveLocation(directive, location);
+		const inner = DirectiveRef.getInner(directive);
+		return {
+			kind: Kind.DIRECTIVE,
+			name: {
+				kind: Kind.NAME,
+				value: inner.name
+			},
+			arguments: buildArguments(inner.arguments)
+		};
+	});
+};
 const buildUnionSelection = (union) => Object.entries(union).map(([typeName, object]) => {
 	return object ? {
 		kind: Kind.INLINE_FRAGMENT,
@@ -113,25 +179,29 @@ const buildUnionSelection = (union) => Object.entries(union).map(([typeName, obj
 		}
 	} : null;
 }).filter((item) => item !== null);
-const buildField = (field) => Object.entries(field).map(([alias, { args, field: field$1, object, union }]) => ({
-	kind: Kind.FIELD,
-	name: {
-		kind: Kind.NAME,
-		value: field$1
-	},
-	alias: alias !== field$1 ? {
-		kind: Kind.NAME,
-		value: alias
-	} : void 0,
-	arguments: buildArguments(args),
-	selectionSet: object ? {
-		kind: Kind.SELECTION_SET,
-		selections: buildField(object)
-	} : union ? {
-		kind: Kind.SELECTION_SET,
-		selections: buildUnionSelection(union)
-	} : void 0
-}));
+const buildField = (field) => Object.entries(field).map(([alias, { args, field: field$1, object, union, directives }]) => {
+	const builtDirectives = buildDirectives(directives, "FIELD");
+	return {
+		kind: Kind.FIELD,
+		name: {
+			kind: Kind.NAME,
+			value: field$1
+		},
+		alias: alias !== field$1 ? {
+			kind: Kind.NAME,
+			value: alias
+		} : void 0,
+		arguments: buildArguments(args),
+		directives: builtDirectives.length > 0 ? builtDirectives : void 0,
+		selectionSet: object ? {
+			kind: Kind.SELECTION_SET,
+			selections: buildField(object)
+		} : union ? {
+			kind: Kind.SELECTION_SET,
+			selections: buildUnionSelection(union)
+		} : void 0
+	};
+});
 /**
 * Converts a constant value to a GraphQL AST ConstValueNode.
 *
@@ -341,6 +411,85 @@ const createColocateHelper = () => {
 	return $colocate;
 };
 
+//#endregion
+//#region packages/core/src/composer/directive-builder.ts
+/**
+* Directive builder utilities for creating field-level directives.
+*
+* Provides type-safe methods for creating directive references that can be
+* applied to field selections. The builder follows a similar pattern to
+* the variable builder ($var).
+*
+* @module
+*/
+/**
+* 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 });
+* ```
+*/
+const createDirectiveMethod = (name, locations) => {
+	return (args) => new DirectiveRef({
+		name,
+		arguments: args,
+		locations
+	});
+};
+/**
+* Standard directive locations for @skip and @include.
+*/
+const CONDITIONAL_DIRECTIVE_LOCATIONS = [
+	"FIELD",
+	"FRAGMENT_SPREAD",
+	"INLINE_FRAGMENT"
+];
+/**
+* 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 });
+* ```
+*/
+const createStandardDirectives = () => ({
+	skip: createDirectiveMethod("skip", CONDITIONAL_DIRECTIVE_LOCATIONS),
+	include: createDirectiveMethod("include", CONDITIONAL_DIRECTIVE_LOCATIONS)
+});
+/**
+* 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
+*/
+const createDirectiveBuilder = (customDirectives) => {
+	return {
+		...createStandardDirectives(),
+		...customDirectives ?? {}
+	};
+};
+/**
+* Type guard to check if a value is a DirectiveRef.
+*
+* @param value - Value to check
+* @returns True if value is a DirectiveRef instance
+*/
+const isDirectiveRef = (value) => {
+	return value instanceof DirectiveRef;
+};
+
 //#endregion
 //#region packages/core/src/composer/field-path-context.ts
 /**
@@ -450,6 +599,7 @@ const createFieldFactoriesInner = (schema, typeName) => {
 	const entries = Object.entries(typeDef.fields).map(([fieldName, type]) => {
 		const factory = (fieldArgs, extras) => {
 			const wrap = (value) => wrapByKey(extras?.alias ?? fieldName, value);
+			const directives = extras?.directives ?? [];
 			if (type.kind === "object") {
 				const factoryReturn = ((nest) => {
 					const nestedFields = withFieldPath(appendToPath(getCurrentFieldPath(), {
@@ -462,7 +612,7 @@ const createFieldFactoriesInner = (schema, typeName) => {
 						field: fieldName,
 						type,
 						args: fieldArgs ?? {},
-						directives: extras?.directives ?? {},
+						directives,
 						object: nestedFields,
 						union: null
 					});
@@ -484,7 +634,7 @@ const createFieldFactoriesInner = (schema, typeName) => {
 						field: fieldName,
 						type,
 						args: fieldArgs ?? {},
-						directives: extras?.directives ?? {},
+						directives,
 						object: null,
 						union: nestedUnion
 					});
@@ -496,7 +646,7 @@ const createFieldFactoriesInner = (schema, typeName) => {
 				field: fieldName,
 				type,
 				args: fieldArgs ?? {},
-				directives: extras?.directives ?? {},
+				directives,
 				object: null,
 				union: null
 			});
@@ -1150,6 +1300,7 @@ const createVarBuilder = (inputTypeMethods) => {
 * - `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
@@ -1160,17 +1311,22 @@ const createVarBuilder = (inputTypeMethods) => {
 * ```typescript
 * const gql = createGqlElementComposer(schema, { inputTypeMethods });
 *
-* const GetUser = gql(({ query, $var }) =>
+* const GetUser = gql(({ query, $var, $dir }) =>
 *   query.operation({
 *     name: "GetUser",
-*     variables: { id: $var.ID("!") },
-*     fields: ({ f, $ }) => ({ ...f.user({ id: $.id })(...) }),
+*     variables: { showEmail: $var("showEmail").Boolean("!") },
+*     fields: ({ f, $ }) => ({
+*       ...f.user({ id: "1" })(({ f }) => ({
+*         ...f.name(),
+*         ...f.email({}, { directives: [$dir.skip({ if: $.showEmail })] }),
+*       })),
+*     }),
 *   })
 * );
 * ```
 */
 const createGqlElementComposer = (schema, options) => {
-	const { adapter, inputTypeMethods } = options;
+	const { adapter, inputTypeMethods, directiveMethods } = options;
 	const helpers = adapter?.helpers;
 	const metadataAdapter = adapter?.metadata;
 	const fragment = createGqlFragmentComposers(schema, metadataAdapter);
@@ -1181,6 +1337,7 @@ const createGqlElementComposer = (schema, options) => {
 		mutation: { operation: createOperationComposer("mutation") },
 		subscription: { operation: createOperationComposer("subscription") },
 		$var: createVarBuilder(inputTypeMethods),
+		$dir: directiveMethods ?? createStandardDirectives(),
 		$colocate: createColocateHelper(),
 		...helpers ?? {}
 	};
@@ -1189,5 +1346,5 @@ const createGqlElementComposer = (schema, options) => {
 };
 
 //#endregion
-export { Fragment, GqlElement, Operation, appendToPath, buildArgumentValue, buildConstValueNode, buildDocument, buildOperationTypeNode, buildWithTypeModifier, createColocateHelper, createDefaultAdapter, createFieldFactories, createGqlElementComposer, createGqlFragmentComposers, createOperationComposerFactory, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefs, defaultMetadataAdapter, define, defineOperationRoots, defineScalar, getCurrentFieldPath, isListType, recordFragmentUsage, unsafeInputType, unsafeOutputType, withFieldPath, withFragmentUsageCollection };
+export { Fragment, GqlElement, Operation, appendToPath, buildArgumentValue, buildConstValueNode, buildDocument, buildOperationTypeNode, buildWithTypeModifier, createColocateHelper, createDefaultAdapter, createDirectiveBuilder, createDirectiveMethod, createFieldFactories, createGqlElementComposer, createGqlFragmentComposers, createOperationComposerFactory, createStandardDirectives, createVarAssignments, createVarBuilder, createVarMethod, createVarMethodFactory, createVarRefs, defaultMetadataAdapter, define, defineOperationRoots, defineScalar, getCurrentFieldPath, isDirectiveRef, isListType, recordFragmentUsage, unsafeInputType, unsafeOutputType, withFieldPath, withFragmentUsageCollection };
 //# sourceMappingURL=index.js.map