@wundergraph/composition 0.59.0 → 0.63.0

package/dist/v1/normalization/normalization-factory.js

@@ -60,6 +60,11 @@ class NormalizationFactory {
     directiveDefinitionDataByName = (0, utils_2.initializeDirectiveDefinitionDatas)();
     doesParentRequireFetchReasons = false;
     edfsDirectiveReferences = new Set();
+    /* Cached entity configs keyed by type name, populated by extractEntityCacheDirective() from
+     * @openfed__entityCache. Future caching directives (@openfed__queryCache etc.) use this as a lookup
+     * to verify a field's return type is a cached entity.
+     */
+    entityCacheConfigByTypeName = new Map();
     errors = new Array();
     entityDataByTypeName = new Map();
     entityInterfaceDataByTypeName = new Map();
@@ -888,13 +893,11 @@ class NormalizationFactory {
             this.updateCompositeOutputDataByNode(node, parentData, extensionType);
             if (!directivesByName.has(string_constants_1.INTERFACE_OBJECT)) {
                 this.addConcreteTypeNamesForImplementedInterfaces(parentData.implementedInterfaceTypeNames, typeName);
+                this.extractEntityCacheDirective(parentData);
             }
             return;
         }
         const implementedInterfaceTypeNames = this.extractImplementedInterfaceTypeNames(node, new Set());
-        if (!directivesByName.has(string_constants_1.INTERFACE_OBJECT)) {
-            this.addConcreteTypeNamesForImplementedInterfaces(implementedInterfaceTypeNames, typeName);
-        }
         const newParentData = {
             configureDescriptionDataBySubgraphName: new Map(),
             directivesByName: directivesByName,
@@ -913,6 +916,10 @@ class NormalizationFactory {
             subgraphNames: new Set([this.subgraphName]),
             description: (0, utils_1.formatDescription)('description' in node ? node.description : undefined),
         };
+        if (!directivesByName.has(string_constants_1.INTERFACE_OBJECT)) {
+            this.addConcreteTypeNamesForImplementedInterfaces(implementedInterfaceTypeNames, typeName);
+            this.extractEntityCacheDirective(newParentData);
+        }
         this.extractConfigureDescriptionsData(newParentData);
         this.parentDefinitionDataByTypeName.set(typeName, newParentData);
     }
@@ -1146,40 +1153,57 @@ class NormalizationFactory {
             }
         }
     }
-    getFieldSetParent(isProvides, parentData, fieldName, parentTypeName) {
+    getFieldSetParent({ isProvides, parentData, fieldName, fieldSet, parentTypeName, }) {
         if (!isProvides) {
-            return { fieldSetParentData: parentData };
+            return {
+                data: parentData,
+                success: true,
+            };
         }
         const fieldData = (0, utils_5.getOrThrowError)(parentData.fieldDataByName, fieldName, `${parentTypeName}.fieldDataByFieldName`);
         const fieldNamedTypeName = (0, ast_1.getTypeNodeNamedTypeName)(fieldData.node.type);
         const fieldCoords = `${parentTypeName}.${fieldName}`;
         if (constants_1.BASE_SCALARS.has(fieldNamedTypeName)) {
             return {
-                errorString: (0, errors_1.incompatibleTypeWithProvidesErrorMessage)({
+                error: (0, errors_1.incompatibleTypeWithProvidesError)({
                     fieldCoords,
                     responseType: fieldNamedTypeName,
                     subgraphName: this.subgraphName,
                 }),
+                success: false,
             };
         }
         const namedTypeData = this.parentDefinitionDataByTypeName.get(fieldNamedTypeName);
         // This error should never happen
         if (!namedTypeData) {
             return {
-                errorString: (0, errors_1.unknownNamedTypeErrorMessage)(fieldCoords, fieldNamedTypeName),
+                error: (0, errors_1.unknownNamedTypeError)(fieldCoords, fieldNamedTypeName),
+                success: false,
             };
         }
         // @TODO handle abstract types and fragments
-        if (namedTypeData.kind !== graphql_1.Kind.INTERFACE_TYPE_DEFINITION && namedTypeData.kind !== graphql_1.Kind.OBJECT_TYPE_DEFINITION) {
-            return {
-                errorString: (0, errors_1.incompatibleTypeWithProvidesErrorMessage)({
+        if ((0, utils_1.isValidProvidesParentData)(namedTypeData)) {
+            if ((0, utils_3.isUnionDefinitionData)(namedTypeData)) {
+                this.warnings.push((0, warnings_1.providesOnUnionWarning)({
                     fieldCoords,
-                    responseType: fieldNamedTypeName,
+                    fieldSet,
+                    namedTypeName: fieldNamedTypeName,
                     subgraphName: this.subgraphName,
-                }),
+                }));
+            }
+            return {
+                data: namedTypeData,
+                success: true,
             };
         }
-        return { fieldSetParentData: namedTypeData };
+        return {
+            error: (0, errors_1.incompatibleTypeWithProvidesError)({
+                fieldCoords,
+                responseType: fieldNamedTypeName,
+                subgraphName: this.subgraphName,
+            }),
+            success: false,
+        };
     }
     #handleNonExternalConditionalField({ currentFieldCoords, directiveCoords, directiveName, fieldSet, }) {
         if (this.isSubgraphVersionTwo) {
@@ -1357,10 +1381,6 @@ class NormalizationFactory {
                         shouldDefineSelectionSet = true;
                         return;
                     }
-                    if (!(0, utils_1.isKindAbstract)(parentData.kind)) {
-                        errorMessages.push((0, errors_1.invalidInlineFragmentTypeErrorMessage)(fieldSet, fieldCoordsPath, typeConditionName, parentTypeName));
-                        return graphql_1.BREAK;
-                    }
                     const fragmentNamedTypeData = nf.parentDefinitionDataByTypeName.get(typeConditionName);
                     if (!fragmentNamedTypeData) {
                         errorMessages.push((0, errors_1.unknownInlineFragmentTypeConditionErrorMessage)(fieldSet, fieldCoordsPath, parentTypeName, typeConditionName));
@@ -1369,13 +1389,31 @@ class NormalizationFactory {
                     shouldDefineSelectionSet = true;
                     switch (fragmentNamedTypeData.kind) {
                         case graphql_1.Kind.INTERFACE_TYPE_DEFINITION: {
-                            if (!fragmentNamedTypeData.implementedInterfaceTypeNames.has(parentTypeName)) {
+                            // The enclosing type is an Object
+                            if (!(0, utils_1.isKindAbstract)(parentData.kind)) {
+                                if (!(0, utils_3.isObjectDefinitionData)(parentData) ||
+                                    !parentData.implementedInterfaceTypeNames.has(typeConditionName)) {
+                                    break;
+                                }
+                                parentDatas.push(fragmentNamedTypeData);
+                                return;
+                            }
+                            // The enclosing type is an Interface or Union
+                            const concreteTypeNames = nf.concreteTypeNamesByAbstractTypeName.get(typeConditionName);
+                            const parentConcreteTypeNames = nf.concreteTypeNamesByAbstractTypeName.get(parentData.name);
+                            if (!concreteTypeNames ||
+                                !parentConcreteTypeNames ||
+                                parentConcreteTypeNames.isDisjointFrom(concreteTypeNames)) {
                                 break;
                             }
                             parentDatas.push(fragmentNamedTypeData);
                             return;
                         }
                         case graphql_1.Kind.OBJECT_TYPE_DEFINITION: {
+                            if (!(0, utils_1.isKindAbstract)(parentData.kind)) {
+                                errorMessages.push((0, errors_1.invalidInlineFragmentTypeErrorMessage)(fieldSet, fieldCoordsPath, typeConditionName, parentTypeName));
+                                return graphql_1.BREAK;
+                            }
                             const concreteTypeNames = nf.concreteTypeNamesByAbstractTypeName.get(parentTypeName);
                             if (!concreteTypeNames || !concreteTypeNames.has(typeConditionName)) {
                                 break;
@@ -1384,6 +1422,24 @@ class NormalizationFactory {
                             return;
                         }
                         case graphql_1.Kind.UNION_TYPE_DEFINITION: {
+                            const concreteTypeNames = nf.concreteTypeNamesByAbstractTypeName.get(typeConditionName);
+                            if (!concreteTypeNames) {
+                                break;
+                            }
+                            // The enclosing type is an Object
+                            if (!(0, utils_1.isKindAbstract)(parentData.kind)) {
+                                // The enclosing Object is a valid part of the Union
+                                if (concreteTypeNames.has(parentTypeName)) {
+                                    parentDatas.push(fragmentNamedTypeData);
+                                    return;
+                                }
+                                break;
+                            }
+                            // The enclosing type is an Interface or Union; fetch its implementations/members respectively.
+                            const parentConcreteTypeNames = nf.concreteTypeNamesByAbstractTypeName.get(parentTypeName);
+                            if (!parentConcreteTypeNames || parentConcreteTypeNames.isDisjointFrom(concreteTypeNames)) {
+                                break;
+                            }
                             parentDatas.push(fragmentNamedTypeData);
                             return;
                         }
@@ -1392,7 +1448,7 @@ class NormalizationFactory {
                             return graphql_1.BREAK;
                         }
                     }
-                    errorMessages.push((0, errors_1.invalidInlineFragmentTypeConditionErrorMessage)(fieldSet, fieldCoordsPath, typeConditionName, (0, utils_5.kindToNodeType)(parentData.kind), parentTypeName));
+                    errorMessages.push((0, errors_1.invalidInlineFragmentTypeConditionErrorMessage)(fieldSet, fieldCoordsPath, typeConditionName, (0, utils_5.kindToNodeType)(parentData.kind), parentTypeName, (0, utils_5.kindToNodeType)(fragmentNamedTypeData.kind)));
                     return graphql_1.BREAK;
                 },
             },
@@ -1459,16 +1515,19 @@ class NormalizationFactory {
              Consequently, at that time, it is unknown whether the named type is an entity.
              If it isn't, the @provides directive does not make sense and can be ignored.
             */
-            const { fieldSetParentData, errorString } = this.getFieldSetParent(isProvides, parentData, fieldName, parentTypeName);
-            const fieldCoords = `${parentTypeName}.${fieldName}`;
-            if (errorString) {
-                allErrorMessages.push(errorString);
-                continue;
-            }
-            if (!fieldSetParentData) {
+            const result = this.getFieldSetParent({
+                fieldName,
+                fieldSet,
+                isProvides,
+                parentData,
+                parentTypeName,
+            });
+            if (!result.success) {
+                allErrorMessages.push(result.error.message);
                 continue;
             }
-            const { errorMessages, configuration } = this.validateConditionalFieldSet(fieldSetParentData, fieldSet, fieldName, isProvides, parentTypeName);
+            const fieldCoords = `${parentTypeName}.${fieldName}`;
+            const { errorMessages, configuration } = this.validateConditionalFieldSet(result.data, fieldSet, fieldName, isProvides, parentTypeName);
             /*
              * It is possible to return no error messages nor configuration if the @provides or @requires directive is
              * considered completely redundant, i.e.,:
@@ -2956,6 +3015,179 @@ class NormalizationFactory {
             }
         }
     }
+    extractEntityCacheDirective({ directivesByName, name: typeName }) {
+        const entityCacheDirectives = directivesByName.get(string_constants_1.OPENFED_ENTITY_CACHE);
+        if (!entityCacheDirectives || entityCacheDirectives.length === 0) {
+            return;
+        }
+        if (!this.keyFieldSetDatasByTypeName.has(typeName)) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_ENTITY_CACHE, typeName, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.entityCacheWithoutKeyErrorMessage)(typeName),
+            ]));
+            return;
+        }
+        /* validateDirectives() (run earlier in normalize()) has already guaranteed each argument's type —
+         * Int for maxAge/negativeCacheTTL, Boolean for the flags — so the generic ConstDirectiveNode is
+         * narrowed once to the precise typed node, mirroring RequestScopedDirectiveNode/ComposeDirectiveNode.
+         * Optional arguments may be absent (definition defaults are not materialized onto the usage AST),
+         * so the config starts at the directive's documented defaults and each present argument overrides it.
+         */
+        const directive = entityCacheDirectives[0];
+        if (this.entityCacheConfigByTypeName.has(typeName)) {
+            // The error would be caught in directive validation as an invalid repeated directive use.
+            return;
+        }
+        const config = {
+            typeName,
+            maxAgeSeconds: 0,
+            notFoundCacheTtlSeconds: 0,
+            includeHeaders: false,
+            partialCacheLoad: false,
+            shadowMode: false,
+        };
+        for (const arg of directive.arguments) {
+            if (!arg) {
+                continue;
+            }
+            const { name, value } = arg;
+            switch (value.kind) {
+                case graphql_1.Kind.INT: {
+                    switch (name.value) {
+                        case string_constants_1.MAX_AGE: {
+                            config.maxAgeSeconds = parseInt(value.value, 10);
+                            break;
+                        }
+                        case string_constants_1.NEGATIVE_CACHE_TTL: {
+                            config.notFoundCacheTtlSeconds = parseInt(value.value, 10);
+                            break;
+                        }
+                    }
+                    break;
+                }
+                default: {
+                    switch (name.value) {
+                        case string_constants_1.INCLUDE_HEADERS: {
+                            config.includeHeaders = value.value;
+                            break;
+                        }
+                        case string_constants_1.PARTIAL_CACHE_LOAD: {
+                            config.partialCacheLoad = value.value;
+                            break;
+                        }
+                        case string_constants_1.SHADOW_MODE: {
+                            config.shadowMode = value.value;
+                            break;
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+        const entityCacheErrors = [];
+        if (config.maxAgeSeconds <= 0) {
+            entityCacheErrors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_ENTITY_CACHE, typeName, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.maxAgeNotPositiveIntegerErrorMessage)(config.maxAgeSeconds),
+            ]));
+        }
+        if (config.notFoundCacheTtlSeconds < 0) {
+            entityCacheErrors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_ENTITY_CACHE, typeName, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.negativeCacheTTLNotNonNegativeIntegerErrorMessage)(config.notFoundCacheTtlSeconds),
+            ]));
+        }
+        if (entityCacheErrors.length > 0) {
+            this.errors.push(...entityCacheErrors);
+            return;
+        }
+        this.entityCacheConfigByTypeName.set(typeName, config);
+        const configurationData = (0, utils_5.getValueOrDefault)(this.configurationDataByTypeName, typeName, () => (0, utils_6.newConfigurationData)(true, typeName));
+        (0, utils_6.getOrInitializeEntityCaching)(configurationData).entityCacheConfigurations.push(config);
+    }
+    // Returns true if the directive is defined and false otherwise
+    extractCacheInvalidateConfig(fieldData) {
+        if (!fieldData.directivesByName.has(string_constants_1.OPENFED_CACHE_INVALIDATE)) {
+            return false;
+        }
+        const operationType = this.getOperationTypeNodeForRootTypeName(fieldData.originalParentTypeName);
+        const fieldCoords = `${fieldData.originalParentTypeName}.${fieldData.name}`;
+        if (!operationType || operationType === graphql_1.OperationTypeNode.QUERY) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_CACHE_INVALIDATE, fieldCoords, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.invalidMutationOrSubscriptionFieldCoordsErrorMessage)(fieldCoords),
+            ]));
+            return true;
+        }
+        const returnTypeName = (0, ast_1.getTypeNodeNamedTypeName)(fieldData.node.type);
+        if (!this.entityCacheConfigByTypeName.has(returnTypeName)) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_CACHE_INVALIDATE, fieldCoords, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.invalidEntityReturnTypeErrorMessage)({ fieldCoords, returnTypeName: returnTypeName }),
+            ]));
+            return true;
+        }
+        const configurationData = (0, utils_5.getValueOrDefault)(this.configurationDataByTypeName, fieldData.renamedParentTypeName, () => (0, utils_6.newConfigurationData)(false, fieldData.renamedParentTypeName));
+        const config = {
+            entityTypeName: returnTypeName,
+            fieldName: fieldData.name,
+            operationType: operationType,
+        };
+        (0, utils_6.getOrInitializeEntityCaching)(configurationData).cacheInvalidateConfigurations.push(config);
+        return true;
+    }
+    /* Extracts @openfed__cachePopulate from Mutation/Subscription fields.
+     * The return type must be a cached entity (@key & @openfed__entityCache).
+     * Argument `maxAge` is optional; if absent, the router falls back to the entity's @openfed__entityCache TTL;
+     * if provided, must be a positive integer.
+     *
+     * Returns true if the directive is defined and false otherwise
+     */
+    extractCachePopulateConfig(fieldData) {
+        if (!fieldData.directivesByName.has(string_constants_1.OPENFED_CACHE_POPULATE)) {
+            return false;
+        }
+        const fieldCoords = `${fieldData.originalParentTypeName}.${fieldData.name}`;
+        const operationType = this.getOperationTypeNodeForRootTypeName(fieldData.originalParentTypeName);
+        if (!operationType || operationType === graphql_1.OperationTypeNode.QUERY) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_CACHE_POPULATE, fieldCoords, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.invalidMutationOrSubscriptionFieldCoordsErrorMessage)(fieldCoords),
+            ]));
+            return true;
+        }
+        const returnTypeName = (0, ast_1.getTypeNodeNamedTypeName)(fieldData.node.type);
+        const entityCacheConfig = this.entityCacheConfigByTypeName.get(returnTypeName);
+        if (!entityCacheConfig) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_CACHE_POPULATE, fieldCoords, string_constants_1.FIRST_ORDINAL, [
+                (0, errors_1.invalidEntityReturnTypeErrorMessage)({ fieldCoords, returnTypeName }),
+            ]));
+            return true;
+        }
+        /* validateDirectives() has already guaranteed maxAge is an Int when present, so the generic
+         * ConstDirectiveNode is narrowed once to the precise typed node — mirroring the other caching
+         * directives. maxAge is the only argument and is optional.
+         */
+        const cachePopulateDirective = fieldData.directivesByName.get(string_constants_1.OPENFED_CACHE_POPULATE)[0];
+        const config = {
+            entityTypeName: returnTypeName,
+            fieldName: fieldData.name,
+            operationType,
+            maxAgeSeconds: entityCacheConfig.maxAgeSeconds, // Set fallback immediately; overridden where appropriate.
+        };
+        const maxAgeArgument = cachePopulateDirective.arguments[0];
+        if (!maxAgeArgument) {
+            const configurationData = (0, utils_5.getValueOrDefault)(this.configurationDataByTypeName, fieldData.renamedParentTypeName, () => (0, utils_6.newConfigurationData)(false, fieldData.renamedParentTypeName));
+            (0, utils_6.getOrInitializeEntityCaching)(configurationData).cachePopulateConfigurations.push(config);
+            return true;
+        }
+        config.maxAgeSeconds = parseInt(maxAgeArgument.value.value, 10);
+        // This syntax handles possible NaN.
+        if (isNaN(config.maxAgeSeconds) || config.maxAgeSeconds <= 0) {
+            this.errors.push((0, errors_1.invalidDirectiveError)(string_constants_1.OPENFED_CACHE_POPULATE, fieldCoords, string_constants_1.FIRST_ORDINAL, [
+                // If null is explicitly provided in GraphQL the value in JS is undefined.
+                (0, errors_1.maxAgeNotPositiveIntegerErrorMessage)(maxAgeArgument.value.value ?? null),
+            ]));
+            return true;
+        }
+        const configurationData = (0, utils_5.getValueOrDefault)(this.configurationDataByTypeName, fieldData.renamedParentTypeName, () => (0, utils_6.newConfigurationData)(false, fieldData.renamedParentTypeName));
+        (0, utils_6.getOrInitializeEntityCaching)(configurationData).cachePopulateConfigurations.push(config);
+        return true;
+    }
     addFieldNamesToConfigurationData(fieldDataByFieldName, configurationData) {
         const externalFieldNames = new Set();
         for (const [fieldName, fieldData] of fieldDataByFieldName) {
@@ -3013,6 +3245,18 @@ class NormalizationFactory {
         }
         definitions.push(...dependencies);
     }
+    // Only Object fields should be passed to this method
+    handleFieldCacheDirectives(data) {
+        /* A field can't both evict (@openfed__cacheInvalidate) and write (@openfed__cachePopulate)
+         * the cache for the same entity, so the two directives are mutually exclusive.
+         */
+        const definesInvalidate = this.extractCacheInvalidateConfig(data);
+        const definesPopulate = this.extractCachePopulateConfig(data);
+        if (definesInvalidate && definesPopulate) {
+            const fieldCoords = `${data.originalParentTypeName}.${data.name}`;
+            this.errors.push((0, errors_1.invalidMutuallyExclusiveCacheDirectivesError)(fieldCoords));
+        }
+    }
     normalize(document) {
         // Collect any renamed root types
         (0, walkers_1.upsertDirectiveSchemaAndEntityDefinitions)(this, document);
@@ -3119,7 +3363,10 @@ class NormalizationFactory {
                     }
                     const externalInterfaceFieldNames = [];
                     for (const [fieldName, fieldData] of parentData.fieldDataByName) {
-                        if (!isObject && fieldData.externalFieldDataBySubgraphName.get(this.subgraphName)?.isDefinedExternal) {
+                        if (isObject) {
+                            this.handleFieldCacheDirectives(fieldData);
+                        }
+                        else if (fieldData.externalFieldDataBySubgraphName.get(this.subgraphName)?.isDefinedExternal) {
                             externalInterfaceFieldNames.push(fieldName);
                         }
                         // Arguments can only be fully validated once all parents types are known