Deprecate old mutation operations

.changeset/four-insects-repeat.md

@@ -0,0 +1,15 @@
+---
+"@neo4j/graphql": patch
+---
+
+Deprecate individual mutations in favor of generic mutations
+
+-   `_SET`
+-   `_POP`
+-   `_PUSH`
+-   `_INCREMENT`
+-   `_ADD`
+-   `_DECREMENT`
+-   `_SUBTRACT`
+-   `_MULTIPLY`
+-   `_DIVIDE`

packages/graphql/src/schema/constants.ts

@@ -17,4 +17,33 @@
  * limitations under the License.
  */
 
+import { DEPRECATED } from "../constants";
+
 // TODO: Add constant deprecations here
+
+export function DEPRECATE_SET_MUTATION(name: string) {
+    return {
+        name: DEPRECATED,
+        args: {
+            reason: `Please use the generic mutation '${name}: { set: ... } }' instead.`,
+        },
+    };
+}
+
+export function DEPRECATE_ARRAY_MUTATIONS(name: string, operation: "push" | "pop") {
+    return {
+        name: DEPRECATED,
+        args: {
+            reason: `Please use the generic mutation '${name}: { ${operation}: ... } }' instead.`,
+        },
+    };
+}
+
+export function DEPRECATE_MATH_MUTATIONS(name: string, operation: string) {
+    return {
+        name: DEPRECATED,
+        args: {
+            reason: `Please use the relevant generic mutation '${name}: { ${operation}: ... } }' instead.`,
+        },
+    };
+}

packages/graphql/src/schema/create-relationship-fields/create-relationship-fields.ts

@@ -144,7 +144,7 @@ function doForRelationshipPropertiesType({
         composer,
     });
     withSortInputType({ relationshipAdapter, userDefinedFieldDirectives, composer });
-    withUpdateInputType({ entityAdapter: relationshipAdapter, userDefinedFieldDirectives, composer });
+    withUpdateInputType({ entityAdapter: relationshipAdapter, userDefinedFieldDirectives, composer, features });
     withWhereInputType({
         entityAdapter: relationshipAdapter,
         userDefinedFieldDirectives,

packages/graphql/src/schema/generation/update-input.ts

@@ -33,6 +33,7 @@ import { RelationshipAdapter } from "../../schema-model/relationship/model-adapt
 import type { RelationshipDeclarationAdapter } from "../../schema-model/relationship/model-adapters/RelationshipDeclarationAdapter";
 import type { Neo4jFeaturesSettings } from "../../types";
 import { ensureNonEmptyInput } from "../ensure-non-empty-input";
+import type { AdditionalFieldsCallback } from "../to-compose";
 import { concreteEntityToUpdateInputFields, withArrayOperators, withMathOperators } from "../to-compose";
 import { withConnectFieldInputType } from "./connect-input";
 import { withConnectionWhereInputType } from "./connection-where-input";
@@ -44,10 +45,12 @@ export function withUpdateInputType({
     entityAdapter,
     userDefinedFieldDirectives,
     composer,
+    features,
 }: {
     entityAdapter: ConcreteEntityAdapter | InterfaceEntityAdapter | RelationshipAdapter;
     userDefinedFieldDirectives: Map<string, DirectiveNode[]>;
     composer: SchemaComposer;
+    features: Neo4jFeaturesSettings | undefined;
 }): InputTypeComposer {
     const inputTypeName =
         entityAdapter instanceof RelationshipAdapter
@@ -63,11 +66,17 @@ export function withUpdateInputType({
     });
 
     if (entityAdapter instanceof ConcreteEntityAdapter || entityAdapter instanceof RelationshipAdapter) {
+        const additionalFields: AdditionalFieldsCallback[] = [];
+        if (features?.excludeDeprecatedFields?.mutationOperations !== true) {
+            additionalFields.push(withMathOperators(), withArrayOperators());
+        }
+
         updateInputType.addFields(
             concreteEntityToUpdateInputFields({
                 objectFields: entityAdapter.updateInputFields,
                 userDefinedFieldDirectives,
-                additionalFieldsCallbacks: [withMathOperators(), withArrayOperators()],
+                additionalFieldsCallbacks: additionalFields,
+                features,
             })
         );
     } else {
@@ -77,11 +86,17 @@ export function withUpdateInputType({
             ensureNonEmptyInput(composer, updateInputType);
         }
 
+        const additionalFields: AdditionalFieldsCallback[] = [];
+        if (features?.excludeDeprecatedFields?.mutationOperations !== true) {
+            additionalFields.push(withMathOperators());
+        }
+
         updateInputType.addFields(
             concreteEntityToUpdateInputFields({
                 objectFields: entityAdapter.updateInputFields,
                 userDefinedFieldDirectives,
-                additionalFieldsCallbacks: [withMathOperators()],
+                additionalFieldsCallbacks: additionalFields,
+                features,
             })
         );
     }
@@ -118,6 +133,7 @@ export function augmentUpdateInputTypeWithUpdateFieldInput({
         entityAdapter: relationshipAdapter.source,
         userDefinedFieldDirectives,
         composer,
+        features,
     });
     const relationshipField = makeUpdateInputTypeRelationshipField({
         relationshipAdapter,
@@ -286,6 +302,7 @@ function makeUpdateFieldInputTypeFields({
         ifUnionMemberEntity,
         composer,
         userDefinedFieldDirectives,
+        features,
     });
     if (updateFieldInputType) {
         fields["update"] = {
@@ -380,11 +397,13 @@ function withUpdateConnectionFieldInputType({
     composer,
     userDefinedFieldDirectives,
     ifUnionMemberEntity,
+    features,
 }: {
     relationshipAdapter: RelationshipAdapter | RelationshipDeclarationAdapter;
     composer: SchemaComposer;
     userDefinedFieldDirectives: Map<string, DirectiveNode[]>;
     ifUnionMemberEntity?: ConcreteEntityAdapter;
+    features: Neo4jFeaturesSettings | undefined;
 }): InputTypeComposer | undefined {
     const typeName = relationshipAdapter.operations.getUpdateConnectionInputTypename(ifUnionMemberEntity);
     if (!relationshipAdapter.nestedOperations.has(RelationshipNestedOperationsOption.UPDATE)) {
@@ -398,6 +417,7 @@ function withUpdateConnectionFieldInputType({
         composer,
         userDefinedFieldDirectives,
         ifUnionMemberEntity,
+        features,
     });
 
     const updateFieldInput = composer.createInputTC({ name: typeName, fields });
@@ -408,11 +428,13 @@ function makeUpdateConnectionFieldInputTypeFields({
     composer,
     userDefinedFieldDirectives,
     ifUnionMemberEntity,
+    features,
 }: {
     relationshipAdapter: RelationshipAdapter | RelationshipDeclarationAdapter;
     composer: SchemaComposer;
     userDefinedFieldDirectives: Map<string, DirectiveNode[]>;
     ifUnionMemberEntity?: ConcreteEntityAdapter;
+    features: Neo4jFeaturesSettings | undefined;
 }): InputTypeComposerFieldConfigMapDefinition {
     const fields: InputTypeComposerFieldConfigMapDefinition = {};
     if (relationshipAdapter.target instanceof UnionEntityAdapter) {
@@ -423,6 +445,7 @@ function makeUpdateConnectionFieldInputTypeFields({
             entityAdapter: ifUnionMemberEntity,
             userDefinedFieldDirectives,
             composer,
+            features,
         });
         fields["node"] = updateInputType;
     } else {

packages/graphql/src/schema/make-augmented-schema.ts

@@ -593,7 +593,7 @@ function generateObjectType({
     augmentVectorSchema({ composer, concreteEntityAdapter, features });
     withUniqueWhereInputType({ concreteEntityAdapter, composer });
     withCreateInputType({ entityAdapter: concreteEntityAdapter, userDefinedFieldDirectives, composer });
-    withUpdateInputType({ entityAdapter: concreteEntityAdapter, userDefinedFieldDirectives, composer });
+    withUpdateInputType({ entityAdapter: concreteEntityAdapter, userDefinedFieldDirectives, composer, features });
     withMutationResponseTypes({ concreteEntityAdapter, propagatedDirectives, composer });
     const composeNode = withObjectType({
         entityAdapter: concreteEntityAdapter,
@@ -731,7 +731,7 @@ function generateInterfaceObjectType({
         composer,
     });
     withCreateInputType({ entityAdapter: interfaceEntityAdapter, userDefinedFieldDirectives, composer });
-    withUpdateInputType({ entityAdapter: interfaceEntityAdapter, userDefinedFieldDirectives, composer });
+    withUpdateInputType({ entityAdapter: interfaceEntityAdapter, userDefinedFieldDirectives, composer, features });
 
     const composeInterface = withInterfaceType({
         interfaceEntityAdapter,

packages/graphql/src/schema/to-compose.ts

@@ -30,7 +30,8 @@ import type { Argument } from "../schema-model/argument/Argument";
 import { ArgumentAdapter } from "../schema-model/argument/model-adapters/ArgumentAdapter";
 import type { AttributeAdapter } from "../schema-model/attribute/model-adapters/AttributeAdapter";
 import { parseValueNode } from "../schema-model/parser/parse-value-node";
-import type { InputField } from "../types";
+import type { InputField, Neo4jFeaturesSettings } from "../types";
+import { DEPRECATE_ARRAY_MUTATIONS, DEPRECATE_MATH_MUTATIONS, DEPRECATE_SET_MUTATION } from "./constants";
 import { getMutationInputFromAttributeType } from "./generation/get-mutation-input-from-attribute-type";
 import { idResolver } from "./resolvers/field/id";
 import { numericalResolver } from "./resolvers/field/numerical";
@@ -130,16 +131,18 @@ export function concreteEntityToUpdateInputFields({
     objectFields,
     userDefinedFieldDirectives,
     additionalFieldsCallbacks = [],
+    features,
 }: {
     objectFields: AttributeAdapter[];
     userDefinedFieldDirectives: Map<string, DirectiveNode[]>;
     additionalFieldsCallbacks: AdditionalFieldsCallback[];
+    features: Neo4jFeaturesSettings | undefined;
 }) {
     let updateInputFields: InputTypeComposerFieldConfigMapDefinition = {};
     for (const field of objectFields) {
         const newInputField: InputField = {
             type: field.getInputTypeNames().update.pretty,
-            directives: [],
+            directives: [DEPRECATE_SET_MUTATION(field.name)],
         };
 
         const userDefinedDirectivesOnField = userDefinedFieldDirectives.get(field.name);
@@ -158,7 +161,9 @@ export function concreteEntityToUpdateInputFields({
             directives: userDefinedDirectives,
         };
 
-        updateInputFields[`${field.name}_SET`] = newInputField;
+        if (features?.excludeDeprecatedFields?.mutationOperations !== true) {
+            updateInputFields[`${field.name}_SET`] = newInputField;
+        }
 
         for (const cb of additionalFieldsCallbacks) {
             const additionalFields = cb(field, newInputField);
@@ -172,9 +177,14 @@ export function concreteEntityToUpdateInputFields({
 export function withMathOperators(): AdditionalFieldsCallback {
     return (attribute: AttributeAdapter, fieldDefinition: InputField): Record<string, InputField> => {
         const fields: Record<string, InputField> = {};
+
         if (attribute.mathModel) {
             for (const operation of attribute.mathModel.getMathOperations()) {
-                fields[operation] = fieldDefinition;
+                const newFieldDefinition =
+                    typeof fieldDefinition === "string" ? { type: fieldDefinition } : { ...fieldDefinition };
+                const newOperationName = operation.split("_")[1]!.toLowerCase();
+                newFieldDefinition.directives = [DEPRECATE_MATH_MUTATIONS(attribute.name, newOperationName)];
+                fields[operation] = newFieldDefinition;
             }
         }
         return fields;
@@ -185,14 +195,20 @@ export function withArrayOperators(): AdditionalFieldsCallback {
     return (attribute: AttributeAdapter): InputTypeComposerFieldConfigMapDefinition => {
         const fields: InputTypeComposerFieldConfigMapDefinition = {};
         if (attribute.listModel) {
-            fields[attribute.listModel.getPop()] = GraphQLInt;
-            fields[attribute.listModel.getPush()] = attribute.getInputTypeNames().update.pretty;
+            fields[attribute.listModel.getPop()] = {
+                type: GraphQLInt,
+                directives: [DEPRECATE_ARRAY_MUTATIONS(attribute.name, "pop")],
+            };
+            fields[attribute.listModel.getPush()] = {
+                type: attribute.getInputTypeNames().update.pretty,
+                directives: [DEPRECATE_ARRAY_MUTATIONS(attribute.name, "push")],
+            };
         }
         return fields;
     };
 }
 
-type AdditionalFieldsCallback = (
+export type AdditionalFieldsCallback = (
     attribute: AttributeAdapter,
     fieldDefinition: InputField
 ) => Record<string, InputField> | InputTypeComposerFieldConfigMapDefinition;

packages/graphql/src/types/index.ts

@@ -446,7 +446,10 @@ export type Neo4jFeaturesSettings = {
      *
      * NOTE: this will not remove user defined deprecated fields
      **/
-    excludeDeprecatedFields?: Record<string, never>;
+
+    excludeDeprecatedFields?: {
+        mutationOperations?: boolean;
+    };
     vector?: Neo4jVectorSettings;
 };