@soda-gql/core 0.8.2 → 0.9.0

package/dist/index.cjs

@@ -1,6 +1,37 @@
 const require_schema = require('./schema-D2MW4DOF.cjs');
 let graphql = require("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: graphql.Kind.DIRECTIVE,
+			name: {
+				kind: graphql.Kind.NAME,
+				value: inner.name
+			},
+			arguments: buildArguments(inner.arguments)
+		};
+	});
+};
 const buildUnionSelection = (union) => Object.entries(union).map(([typeName, object]) => {
 	return object ? {
 		kind: graphql.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: graphql.Kind.FIELD,
-	name: {
-		kind: graphql.Kind.NAME,
-		value: field$1
-	},
-	alias: alias !== field$1 ? {
-		kind: graphql.Kind.NAME,
-		value: alias
-	} : void 0,
-	arguments: buildArguments(args),
-	selectionSet: object ? {
-		kind: graphql.Kind.SELECTION_SET,
-		selections: buildField(object)
-	} : union ? {
-		kind: graphql.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: graphql.Kind.FIELD,
+		name: {
+			kind: graphql.Kind.NAME,
+			value: field$1
+		},
+		alias: alias !== field$1 ? {
+			kind: graphql.Kind.NAME,
+			value: alias
+		} : void 0,
+		arguments: buildArguments(args),
+		directives: builtDirectives.length > 0 ? builtDirectives : void 0,
+		selectionSet: object ? {
+			kind: graphql.Kind.SELECTION_SET,
+			selections: buildField(object)
+		} : union ? {
+			kind: graphql.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) => require_schema.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 ?? {}
 	};
@@ -1200,10 +1357,13 @@ exports.buildOperationTypeNode = buildOperationTypeNode;
 exports.buildWithTypeModifier = buildWithTypeModifier;
 exports.createColocateHelper = createColocateHelper;
 exports.createDefaultAdapter = createDefaultAdapter;
+exports.createDirectiveBuilder = createDirectiveBuilder;
+exports.createDirectiveMethod = createDirectiveMethod;
 exports.createFieldFactories = createFieldFactories;
 exports.createGqlElementComposer = createGqlElementComposer;
 exports.createGqlFragmentComposers = createGqlFragmentComposers;
 exports.createOperationComposerFactory = createOperationComposerFactory;
+exports.createStandardDirectives = createStandardDirectives;
 exports.createVarAssignments = createVarAssignments;
 exports.createVarBuilder = createVarBuilder;
 exports.createVarMethod = createVarMethod;
@@ -1214,6 +1374,7 @@ exports.define = require_schema.define;
 exports.defineOperationRoots = require_schema.defineOperationRoots;
 exports.defineScalar = require_schema.defineScalar;
 exports.getCurrentFieldPath = getCurrentFieldPath;
+exports.isDirectiveRef = isDirectiveRef;
 exports.isListType = isListType;
 exports.recordFragmentUsage = recordFragmentUsage;
 exports.unsafeInputType = require_schema.unsafeInputType;