graphql 17.0.0-beta.1 → 17.0.0-beta.2

package/validation/rules/OverlappingFieldsCanBeMergedRule.d.ts

@@ -1,3 +1,4 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from "../../language/visitor.js";
 import type { ValidationContext } from "../ValidationContext.js";
 /**
@@ -8,5 +9,37 @@ import type { ValidationContext } from "../ValidationContext.js";
  * without ambiguity.
  *
  * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { OverlappingFieldsCanBeMergedRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     name: String
+ *     barkVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { value: barkVolume value: name } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { barkVolume name } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function OverlappingFieldsCanBeMergedRule(context: ValidationContext): ASTVisitor;

package/validation/rules/OverlappingFieldsCanBeMergedRule.js

@@ -8,9 +8,6 @@ const printer_ts_1 = require("../../language/printer.js");
 const definition_ts_1 = require("../../type/definition.js");
 const sortValueNode_ts_1 = require("../../utilities/sortValueNode.js");
 const typeFromAST_ts_1 = require("../../utilities/typeFromAST.js");
-/* eslint-disable max-params */
-// This file contains a lot of such errors but we plan to refactor it anyway
-// so just disable it for entire file.
 function reasonMessage(reason) {
     if (Array.isArray(reason)) {
         return reason
@@ -20,24 +17,9 @@ function reasonMessage(reason) {
     }
     return reason;
 }
-/**
- * Overlapping fields can be merged
- *
- * A selection set is only valid if all fields (including spreading any
- * fragments) either correspond to distinct response names or can be merged
- * without ambiguity.
- *
- * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
- */
 function OverlappingFieldsCanBeMergedRule(context) {
-    // A memoization for when fields and a fragment or two fragments are compared
-    // "between" each other for conflicts. Comparisons made be made many times,
-    // so memoizing this can dramatically improve the performance of this validator.
     const comparedFieldsAndFragmentPairs = new OrderedPairSet();
     const comparedFragmentPairs = new PairSet();
-    // A cache for the "field map" and list of fragment spreads found in any given
-    // selection set. Selection sets may be asked for this information multiple
-    // times, so this improves the performance of this validator.
     const cachedFieldsAndFragmentSpreads = new Map();
     return {
         SelectionSet(selectionSet) {
@@ -49,78 +31,13 @@ function OverlappingFieldsCanBeMergedRule(context) {
         },
     };
 }
-/**
- * Algorithm:
- *
- * Conflicts occur when two fields exist in a query which will produce the same
- * response name, but represent differing values, thus creating a conflict.
- * The algorithm below finds all conflicts via making a series of comparisons
- * between fields. In order to compare as few fields as possible, this makes
- * a series of comparisons "within" sets of fields and "between" sets of fields.
- *
- * Given any selection set, a collection produces both a set of fields by
- * also including all inline fragments, as well as a list of fragments
- * referenced by fragment spreads.
- *
- * A) Each selection set represented in the document first compares "within" its
- * collected set of fields, finding any conflicts between every pair of
- * overlapping fields.
- * Note: This is the *only time* that a the fields "within" a set are compared
- * to each other. After this only fields "between" sets are compared.
- *
- * B) Also, if any fragment is referenced in a selection set, then a
- * comparison is made "between" the original set of fields and the
- * referenced fragment.
- *
- * C) Also, if multiple fragments are referenced, then comparisons
- * are made "between" each referenced fragment.
- *
- * D) When comparing "between" a set of fields and a referenced fragment, first
- * a comparison is made between each field in the original set of fields and
- * each field in the the referenced set of fields.
- *
- * E) Also, if any fragment is referenced in the referenced selection set,
- * then a comparison is made "between" the original set of fields and the
- * referenced fragment (recursively referring to step D).
- *
- * F) When comparing "between" two fragments, first a comparison is made between
- * each field in the first referenced set of fields and each field in the the
- * second referenced set of fields.
- *
- * G) Also, any fragments referenced by the first must be compared to the
- * second, and any fragments referenced by the second must be compared to the
- * first (recursively referring to step F).
- *
- * H) When comparing two fields, if both have selection sets, then a comparison
- * is made "between" both selection sets, first comparing the set of fields in
- * the first selection set with the set of fields in the second.
- *
- * I) Also, if any fragment is referenced in either selection set, then a
- * comparison is made "between" the other set of fields and the
- * referenced fragment.
- *
- * J) Also, if two fragments are referenced in both selection sets, then a
- * comparison is made "between" the two fragments.
- *
- */
-// Find all conflicts found "within" a selection set, including those found
-// via spreading in fragments. Called when visiting each SelectionSet in the
-// GraphQL Document.
 function findConflictsWithinSelectionSet(context, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, parentType, selectionSet) {
     const conflicts = [];
     const [fieldMap, fragmentSpreads] = getFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, parentType, selectionSet, undefined);
-    // (A) Find find all conflicts "within" the fields and f of this selection set.
-    // Note: this is the *only place* `collectConflictsWithin` is called.
     collectConflictsWithin(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, fieldMap);
     if (fragmentSpreads.length !== 0) {
-        // (B) Then collect conflicts between these fields and those represented by
-        // each spread found.
         for (let i = 0; i < fragmentSpreads.length; i++) {
             collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, false, fieldMap, fragmentSpreads[i]);
-            // (C) Then compare this fragment with all other fragments found in this
-            // selection set to collect conflicts between fragments spread together.
-            // This compares each item in the list of fragment spreads to every other
-            // item in that same list (except for itself).
             for (let j = i + 1; j < fragmentSpreads.length; j++) {
                 collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, false, fragmentSpreads[i], fragmentSpreads[j]);
             }
@@ -128,11 +45,7 @@ function findConflictsWithinSelectionSet(context, cachedFieldsAndFragmentSpreads
     }
     return conflicts;
 }
-// Collect all conflicts found between a set of fields and a fragment reference
-// including via spreading in any nested fragments.
 function collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap, fragmentSpread) {
-    // Memoize so the fields and fragments are not compared for conflicts more
-    // than once.
     if (comparedFieldsAndFragmentPairs.has(fieldMap, fragmentSpread.key, areMutuallyExclusive)) {
         return;
     }
@@ -142,23 +55,15 @@ function collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFiel
         return;
     }
     const [fieldMap2, referencedFragmentSpreads] = getReferencedFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, fragment, fragmentSpread.varMap);
-    // Do not compare a fragment's fieldMap to itself.
     if (fieldMap === fieldMap2) {
         return;
     }
-    // (D) First collect any conflicts between the provided collection of fields
-    // and the collection of fields represented by the given fragment.
     collectConflictsBetween(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap, undefined, fieldMap2, fragmentSpread.varMap);
-    // (E) Then collect any conflicts between the provided collection of fields
-    // and any fragment names found in the given fragment.
     for (const referencedFragmentSpread of referencedFragmentSpreads) {
         collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap, referencedFragmentSpread);
     }
 }
-// Collect all conflicts found between two fragments, including via spreading in
-// any nested fragments.
 function collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fragmentSpread1, fragmentSpread2) {
-    // No need to compare a fragment to itself.
     if (fragmentSpread1.key === fragmentSpread2.key) {
         return;
     }
@@ -168,7 +73,6 @@ function collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFra
             return;
         }
     }
-    // Memoize so two fragments are not compared for conflicts more than once.
     if (comparedFragmentPairs.has(fragmentSpread1.key, fragmentSpread2.key, areMutuallyExclusive)) {
         return;
     }
@@ -180,42 +84,25 @@ function collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFra
     }
     const [fieldMap1, referencedFragmentSpreads1] = getReferencedFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, fragment1, fragmentSpread1.varMap);
     const [fieldMap2, referencedFragmentSpreads2] = getReferencedFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, fragment2, fragmentSpread2.varMap);
-    // (F) First, collect all conflicts between these two collections of fields
-    // (not including any nested fragments).
     collectConflictsBetween(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap1, fragmentSpread1.varMap, fieldMap2, fragmentSpread2.varMap);
-    // (G) Then collect conflicts between the first fragment and any nested
-    // fragments spread in the second fragment.
     for (const referencedFragmentSpread2 of referencedFragmentSpreads2) {
         collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fragmentSpread1, referencedFragmentSpread2);
     }
-    // (G) Then collect conflicts between the second fragment and any nested
-    // fragments spread in the first fragment.
     for (const referencedFragmentSpread1 of referencedFragmentSpreads1) {
         collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, referencedFragmentSpread1, fragmentSpread2);
     }
 }
-// Find all conflicts found between two selection sets, including those found
-// via spreading in fragments. Called when determining if conflicts exist
-// between the sub-fields of two overlapping fields.
 function findConflictsBetweenSubSelectionSets(context, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, parentType1, selectionSet1, varMap1, parentType2, selectionSet2, varMap2) {
     const conflicts = [];
     const [fieldMap1, fragmentSpreads1] = getFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, parentType1, selectionSet1, varMap1);
     const [fieldMap2, fragmentSpreads2] = getFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, parentType2, selectionSet2, varMap2);
-    // (H) First, collect all conflicts between these two collections of field.
     collectConflictsBetween(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap1, varMap1, fieldMap2, varMap2);
-    // (I) Then collect conflicts between the first collection of fields and
-    // those referenced by each fragment name associated with the second.
     for (const fragmentSpread2 of fragmentSpreads2) {
         collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap1, fragmentSpread2);
     }
-    // (I) Then collect conflicts between the second collection of fields and
-    // those referenced by each fragment name associated with the first.
     for (const fragmentSpread1 of fragmentSpreads1) {
         collectConflictsBetweenFieldsAndFragment(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fieldMap2, fragmentSpread1);
     }
-    // (J) Also collect conflicts between any fragment spreads by the first and
-    // fragment spreads by the second. This compares each item in the first set of
-    // spreads to each item in the second set of spreads.
     for (const fragmentSpread1 of fragmentSpreads1) {
         for (const fragmentSpread2 of fragmentSpreads2) {
             collectConflictsBetweenFragments(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, areMutuallyExclusive, fragmentSpread1, fragmentSpread2);
@@ -223,21 +110,12 @@ function findConflictsBetweenSubSelectionSets(context, cachedFieldsAndFragmentSp
     }
     return conflicts;
 }
-// Collect all Conflicts "within" one collection of fields.
 function collectConflictsWithin(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, fieldMap) {
-    // A field map is a keyed collection, where each key represents a response
-    // name and the value at that key is a list of all fields which provide that
-    // response name. For every response name, if there are multiple fields, they
-    // must be compared to find a potential conflict.
     for (const [responseName, fields] of fieldMap.entries()) {
-        // This compares every field in the list to every other field in this list
-        // (except to itself). If the list only has one item, nothing needs to
-        // be compared.
         if (fields.length > 1) {
             for (let i = 0; i < fields.length; i++) {
                 for (let j = i + 1; j < fields.length; j++) {
-                    const conflict = findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, false, // within one collection is never mutually exclusive
-                    responseName, fields[i], undefined, fields[j], undefined);
+                    const conflict = findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, false, responseName, fields[i], undefined, fields[j], undefined);
                     if (conflict) {
                         conflicts.push(conflict);
                     }
@@ -246,17 +124,7 @@ function collectConflictsWithin(context, conflicts, cachedFieldsAndFragmentSprea
         }
     }
 }
-// Collect all Conflicts between two collections of fields. This is similar to,
-// but different from the `collectConflictsWithin` function above. This check
-// assumes that `collectConflictsWithin` has already been called on each
-// provided collection of fields. This is true because this validator traverses
-// each individual selection set.
 function collectConflictsBetween(context, conflicts, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, parentFieldsAreMutuallyExclusive, fieldMap1, varMap1, fieldMap2, varMap2) {
-    // A field map is a keyed collection, where each key represents a response
-    // name and the value at that key is a list of all fields which provide that
-    // response name. For any response name which appears in both provided field
-    // maps, each field from the first field map must be compared to every field
-    // in the second field map to find potential conflicts.
     for (const [responseName, fields1] of fieldMap1.entries()) {
         const fields2 = fieldMap2.get(responseName);
         if (fields2 != null) {
@@ -271,25 +139,14 @@ function collectConflictsBetween(context, conflicts, cachedFieldsAndFragmentSpre
         }
     }
 }
-// Determines if there is a conflict between two particular fields, including
-// comparing their sub-fields.
 function findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAndFragmentPairs, comparedFragmentPairs, parentFieldsAreMutuallyExclusive, responseName, field1, varMap1, field2, varMap2) {
     const [parentType1, node1, def1] = field1;
     const [parentType2, node2, def2] = field2;
-    // If it is known that two fields could not possibly apply at the same
-    // time, due to the parent types, then it is safe to permit them to diverge
-    // in aliased field or arguments used as they will not present any ambiguity
-    // by differing.
-    // It is known that two parent types could never overlap if they are
-    // different Object types. Interface or Union types might overlap - if not
-    // in the current state of the schema, then perhaps in some future version,
-    // thus may not safely diverge.
     const areMutuallyExclusive = parentFieldsAreMutuallyExclusive ||
         (parentType1 !== parentType2 &&
             (0, definition_ts_1.isObjectType)(parentType1) &&
             (0, definition_ts_1.isObjectType)(parentType2));
     if (!areMutuallyExclusive) {
-        // Two aliases must refer to the same field.
         const name1 = node1.name.value;
         const name2 = node2.name.value;
         if (name1 !== name2) {
@@ -299,7 +156,6 @@ function findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAnd
                 [node2],
             ];
         }
-        // Two field calls must have the same arguments.
         if (!sameArguments(node1.arguments, varMap1, node2.arguments, varMap2)) {
             return [
                 [responseName, 'they have differing arguments'],
@@ -314,7 +170,6 @@ function findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAnd
     if (overlappingStreamReason !== undefined) {
         return [[responseName, overlappingStreamReason], [node1], [node2]];
     }
-    // The return type for each field.
     const type1 = def1?.type;
     const type2 = def2?.type;
     if (type1 && type2 && doTypesConflict(type1, type2)) {
@@ -327,9 +182,6 @@ function findConflict(context, cachedFieldsAndFragmentSpreads, comparedFieldsAnd
             [node2],
         ];
     }
-    // Collect and compare sub-fields. Use the same "visited fragment spreads" list
-    // for both collections so fields in a fragment reference are never
-    // compared to themselves.
     const selectionSet1 = node1.selectionSet;
     const selectionSet2 = node2.selectionSet;
     if (selectionSet1 && selectionSet2) {
@@ -395,23 +247,16 @@ function hasNoOverlappingStreams(directives1, varMap1, directives2, varMap2) {
     const stream1 = getStreamDirective(directives1);
     const stream2 = getStreamDirective(directives2);
     if (!stream1 && !stream2) {
-        // both fields do not have streams
         return;
     }
     else if (stream1 && stream2) {
-        // check if both fields have equivalent streams
         if (sameArguments(stream1.arguments, varMap1, stream2.arguments, varMap2)) {
-            // This was allowed in previous alpha versions of `graphql-js`.
             return 'they have overlapping stream directives. See https://github.com/graphql/defer-stream-wg/discussions/100';
         }
         return 'they have overlapping stream directives';
     }
-    // fields have a mix of stream and no stream
     return 'they have overlapping stream directives';
 }
-// Two types conflict if both types could not apply to a value simultaneously.
-// Composite types are ignored as their individual field types will be compared
-// later recursively. However List and Non-Null types must match.
 function doTypesConflict(type1, type2) {
     if ((0, definition_ts_1.isListType)(type1)) {
         return (0, definition_ts_1.isListType)(type2)
@@ -434,9 +279,6 @@ function doTypesConflict(type1, type2) {
     }
     return false;
 }
-// Given a selection set, return the collection of fields (a mapping of response
-// name to field nodes and definitions) as well as a list of fragment spreads
-// referenced via fragment spreads.
 function getFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, parentType, selectionSet, varMap) {
     const cached = cachedFieldsAndFragmentSpreads.get(selectionSet);
     if (cached) {
@@ -452,10 +294,7 @@ function getFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, pa
     cachedFieldsAndFragmentSpreads.set(selectionSet, result);
     return result;
 }
-// Given a reference to a fragment, return the represented collection of fields
-// as well as a list of nested fragment spreads referenced via fragment spreads.
 function getReferencedFieldsAndFragmentSpreads(context, cachedFieldsAndFragmentSpreads, fragment, varMap) {
-    // Short-circuit building a type from the node if possible.
     const cached = cachedFieldsAndFragmentSpreads.get(fragment.selectionSet);
     if (cached) {
         return cached;
@@ -532,8 +371,6 @@ function getFragmentSpread(context, fragmentSpreadNode, varMap) {
         varMap: newVarMap.size > 0 ? newVarMap : undefined,
     };
 }
-// Given a series of Conflicts which occurred between two sub-fields, generate
-// a single Conflict.
 function subfieldConflicts(conflicts, responseName, node1, node2) {
     if (conflicts.length > 0) {
         return [
@@ -543,13 +380,6 @@ function subfieldConflicts(conflicts, responseName, node1, node2) {
         ];
     }
 }
-/**
- * A way to keep track of pairs of things where the ordering of the pair
- * matters.
- *
- * Provides a third argument for has/set to allow flagging the pair as
- * weakly or strongly present within the collection.
- */
 class OrderedPairSet {
     constructor() {
         this._data = new Map();
@@ -571,10 +401,6 @@ class OrderedPairSet {
         }
     }
 }
-/**
- * A way to keep track of pairs of similar things when the ordering of the pair
- * does not matter.
- */
 class PairSet {
     constructor() {
         this._orderedPairSet = new OrderedPairSet();