@wundergraph/protographic 0.15.6 → 0.16.0

package/dist/src/abstract-selection-rewriter.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @file abstract-selection-rewriter.ts
+ *
+ * This module provides functionality to normalize GraphQL field set selections
+ * when dealing with abstract types (interfaces and unions). It ensures that fields selected
+ * at the interface level are properly distributed into each inline fragment,
+ * maintaining correct selection semantics for proto mapping generation.
+ */
+import { DocumentNode, GraphQLSchema, GraphQLObjectType, GraphQLInterfaceType } from 'graphql';
+type GraphQLTypeWithFields = GraphQLObjectType | GraphQLInterfaceType;
+/**
+ * Rewrites GraphQL selection sets to normalize abstract type selections.
+ *
+ * When a field returns an interface type, selections can be made both at the
+ * interface level and within inline fragments for concrete types. This class
+ * normalizes such selections by moving interface-level fields into each inline
+ * fragment, ensuring consistent selection structure for downstream processing.
+ * This is required to generate the proper proto message definitions as in protobuf
+ * we define abstract types as oneof fields in in a message definition, which defines
+ * the possible concrete types that can be selected.
+ *
+ * As we can select on Interfaces and Unions directly, we need to normalize the selection set
+ * to determine the allowed concrete types that can be selected.
+ *
+ *
+ * @example
+ * Input selection:
+ * ```graphql
+ * media {
+ *   id          # interface-level field
+ *   ... on Book { title }
+ *   ... on Movie { duration }
+ * }
+ * ```
+ *
+ * Output after normalization:
+ * ```graphql
+ * media {
+ *   ... on Book { id title }
+ *   ... on Movie { id duration }
+ * }
+ * ```
+ */
+export declare class AbstractSelectionRewriter {
+    private readonly visitor;
+    private readonly fieldSetDoc;
+    readonly schema: GraphQLSchema;
+    private currentType;
+    private currentCompositeRoot?;
+    private compositeTypeStack;
+    private ancestorStacks;
+    /** Stack for tracking parent types during nested field traversal */
+    private typeStack;
+    /** Boolean stack indicating whether to restore type/selection context when leaving a selection set */
+    private rebalanceStack;
+    /** The current selection set being processed, used for in-place AST mutations */
+    private currentSelectionSet;
+    /** Stack for preserving parent selection set context during nested traversal */
+    private selectionSetStack;
+    private inlineFragmentStack;
+    /** Stack tracking enclosing concrete type inline fragments for correct parent resolution
+     * when unfolding unions/abstracts nested inside concrete type fragments */
+    private concreteFragmentStack;
+    /**
+     * Creates a new AbstractSelectionRewriter instance.
+     *
+     * @param fieldSetDoc - The parsed GraphQL document containing the field set to rewrite
+     * @param schema - The GraphQL schema used for type resolution
+     * @param objectType - The root object type where the field set originates
+     */
+    constructor(fieldSetDoc: DocumentNode, schema: GraphQLSchema, objectType: GraphQLTypeWithFields);
+    /**
+     * Creates the AST visitor that processes selection sets during traversal.
+     *
+     * @returns An ASTVisitor configured to handle SelectionSet nodes
+     */
+    private createASTVisitor;
+    /**
+     * Executes the normalization process on the field set document.
+     *
+     * This method traverses the AST and rewrites any selection sets that target
+     * interface types, distributing interface-level fields into inline fragments.
+     * The modification is performed in-place on the provided document.
+     */
+    normalize(): void;
+    /**
+     * Handles the entry into a SelectionSet node during AST traversal.
+     *
+     * If the selection set's parent field returns an interface type, this method:
+     * 1. Extracts all direct field selections (interface-level fields)
+     * 2. Removes them from the selection set, leaving only inline fragments
+     * 3. Prepends the interface-level fields to each inline fragment's selections
+     *    (unless the fragment already contains that field)
+     *
+     * @param ctx - The visitor context containing the current node and its position in the AST
+     */
+    private onEnterSelectionSet;
+    /**
+     * Handles leaving a SelectionSet node during AST traversal.
+     *
+     * This method performs cleanup operations:
+     * 1. Merges duplicate inline fragments with the same type condition
+     * 2. Removes empty inline fragments (those with no selections)
+     * 3. Restores the previous type and selection set context from stacks
+     *
+     * @param ctx - The visitor context containing the current node and its position in the AST
+     */
+    private onLeaveSelectionSet;
+    /**
+     * Handles entering an InlineFragment node during AST traversal.
+     *
+     * This method processes inline fragments in two ways:
+     *
+     * 1. For concrete type fragments (e.g., `... on Book`):
+     *    - Validates if the fragment type implements the current interface
+     *    - Removes invalid fragments (those targeting types that don't implement the interface)
+     *    - Tracks the fragment for nested union/abstract type resolution
+     *
+     * 2. For interface type conditions (e.g., `... on Employee`):
+     *    - Recursively processes nested interface selections
+     *    - Distributes interface-level fields into concrete type fragments
+     *    - Unwraps the inline fragment by replacing it with its selections
+     *    - Ensures nested interface fields are properly distributed
+     *
+     * @param ctx - The visitor context containing the current inline fragment node
+     * @returns undefined to continue traversal, or nothing to skip
+     */
+    private onEnterInlineFragment;
+    private onLeaveInlineFragment;
+    private unfoldUnionType;
+    private unfoldSelectionNodeToParent;
+    /**
+     * Resolves the correct enclosing selection set for union/abstract type unfolding.
+     *
+     * The resolution order is:
+     * 1. If `inlineFragmentStack` has depth > 1, use the parent fragment's selection set
+     * 2. If the node can be found in `currentSelectionSet`, use it
+     * 3. If inside a concrete type inline fragment (tracked by concreteFragmentStack)
+     *    and the node can be found there, use that fragment's selection set
+     * 4. Fall back to `currentSelectionSet`
+     */
+    private getEnclosingSelectionSet;
+    /**
+     * Merges duplicate inline fragments with the same type condition.
+     *
+     * When multiple inline fragments target the same concrete type, this method
+     * combines them into a single fragment with all selections merged together.
+     * The merged fragment replaces all duplicate fragments in the selection set.
+     *
+     * @param node - The selection set node containing inline fragments to merge
+     */
+    private mergeInlineFragments;
+    /**
+     * Collapses redundant nested inline fragments whose type condition matches
+     * the enclosing inline fragment's type condition.
+     *
+     * When processing abstract types inside a concrete type inline fragment,
+     * the normalization may produce nested fragments like:
+     *   `... on Intern { ... on Intern { scope } }`
+     * This method unwraps the inner fragment, yielding:
+     *   `... on Intern { scope }`
+     *
+     * @param node - The selection set node to clean up
+     * @param parent - The parent AST node (checked for InlineFragment type)
+     */
+    private collapseRedundantFragments;
+    /**
+     * Removes empty inline fragments from a selection set.
+     *
+     * Filters out any inline fragment that has no selections in its selection set.
+     * This cleanup step is performed after field distribution and merging operations
+     * to ensure only meaningful fragments remain in the AST.
+     *
+     * @param node - The selection set node to clean up
+     */
+    private removeEmptyInlineFragments;
+    /**
+     * Appends inline fragments for all possible types that implement the current interface.
+     *
+     * When processing an interface type selection with interface-level fields, this method
+     * ensures that every concrete type implementing the interface has a corresponding
+     * inline fragment. Creates new fragments only for types that don't already have one.
+     *
+     * This guarantees that interface-level fields can be distributed to all implementing
+     * types, even if the original query didn't explicitly include fragments for them.
+     *
+     * @param node - The selection set node to append inline fragments to
+     */
+    private appendValidInlineFragments;
+    private getPossibleIntersectingTypes;
+    /**
+     * Creates an inline fragment AST node for a specific concrete type.
+     *
+     * Constructs a minimal InlineFragmentNode with:
+     * - Type condition targeting the specified object type
+     * - Filtered field selections (only includes fields that exist on the target type)
+     * - Simple field nodes with name only (no aliases, arguments, or directives)
+     *
+     * @param type - The concrete object type to create a fragment for
+     * @param fields - The interface-level fields to include in the fragment
+     * @returns A new InlineFragmentNode with the filtered field selections
+     */
+    private createInlineFragment;
+    /**
+     * Distributes interface-level fields into all inline fragments.
+     *
+     * This is the core normalization logic that:
+     * 1. Extracts all direct field selections from the selection set
+     * 2. Removes those fields from the parent selection set
+     * 3. Adds each field to the inline fragments where it doesn't already exist
+     * 4. Validates that each field exists on the fragment's concrete type
+     *
+     * Fields are prepended to maintain their original order relative to fragment-specific fields.
+     * Duplicate fields within a fragment are avoided by checking existing selections.
+     *
+     * @param node - The selection set node containing fields and inline fragments
+     */
+    private distributeFieldsIntoInlineFragments;
+    /**
+     * Checks if an inline fragment's type condition targets an interface type.
+     *
+     * @param node - The inline fragment node to check
+     * @returns true if the fragment targets an interface type, false otherwise
+     */
+    private inlineFragmentIsAbstractType;
+    /**
+     * Validates whether an inline fragment is valid for the current interface type.
+     *
+     * An inline fragment is considered valid if:
+     * - The current type is not an interface (always valid)
+     * - The fragment's type is an object type that implements the current interface
+     *
+     * Invalid fragments (those targeting types that don't implement the interface)
+     * should be removed from the selection set.
+     *
+     * @param node - The inline fragment node to validate
+     * @returns true if the fragment is valid for the current interface root context, false otherwise
+     */
+    private inlineFragmentIsValidForCurrentAbstractRoot;
+    /**
+     * Type guard to check if an AST node is a FieldNode.
+     *
+     * @param node - The AST node or array of nodes to check
+     * @returns true if the node is a FieldNode, false otherwise
+     */
+    private isFieldNode;
+    /**
+     * Finds the named (unwrapped) type for a field by its name.
+     *
+     * This method looks up the field in the current type's fields and returns
+     * the named type (stripping away any List or NonNull wrappers).
+     *
+     * @param fieldName - The name of the field to look up
+     * @returns The named GraphQL type, or undefined if the field doesn't exist
+     */
+    private findNamedTypeForField;
+    /**
+     * Type guard to check if a GraphQL type has fields.
+     *
+     * @param type - The GraphQL type to check
+     * @returns true if the type is an object type or interface type (both have getFields method)
+     */
+    private isTypeWithFields;
+}
+export {};