Breaking changes to the @id directive (#3823)

* Break `@id` `global` argument out into `@relayId`

* Remove arguments from `@id`

* Add changeset

* Address first PR comments

* Switch back to default name for constraints

* Fix directive description

* Remove automatic constraint for `@id`

* Fix typo

* Fix tests

Author: darrellwarde

.changeset/purple-hairs-glow.md

@@ -0,0 +1,14 @@
+---
+"@neo4j/graphql": major
+---
+
+The `@id` directive has had a number of breaking changes.
+
+The `unique` argument has been removed. In an effort to simplify directives, `@id` will now only only be responsible for the autogeneration of UUID values.
+If you would like the property to also be backed by a unique node property constraint, use the `@unique` directive alongside `@id`.
+
+The `autogenerate` argument has been removed. With this value set to `false` and the above removal of constraint management, this would make the directive a no-op.
+
+The `global` argument has been removed. This quite key feature of specifying the globally unique identifier for Relay was hidden away inside the `@id` directive. This functionality has been moved into its own directive, `@relayId`, which is used with no arguments. The use of the `@relayId` directive also implies that the field will be backed by a unique node property constraint.
+
+Note, if using the `@id` and `@relayId` directive together on the same field, this will be an autogenerated ID compatible with Relay, and be backed by a single unique node property constraint. If you wish to give this constraint a name, use the `@unique` directive also with the `constraintName` argument.

packages/graphql/src/classes/Neo4jGraphQL.ts

@@ -25,7 +25,7 @@ import type Node from "./Node";
 import type Relationship from "./Relationship";
 import checkNeo4jCompat from "./utils/verify-database";
 import type { AssertIndexesAndConstraintsOptions } from "./utils/asserts-indexes-and-constraints";
-import assertIndexesAndConstraints from "./utils/asserts-indexes-and-constraints";
+import { assertIndexesAndConstraints } from "./utils/asserts-indexes-and-constraints";
 import { wrapQueryAndMutation } from "../schema/resolvers/composition/wrap-query-and-mutation";
 import type { WrapResolverArguments } from "../schema/resolvers/composition/wrap-query-and-mutation";
 import { defaultFieldResolver } from "../schema/resolvers/field/defaultField";

packages/graphql/src/classes/utils/asserts-indexes-and-constraints.ts

@@ -29,6 +29,32 @@ export interface AssertIndexesAndConstraintsOptions {
     create?: boolean;
 }
 
+export async function assertIndexesAndConstraints({
+    driver,
+    sessionConfig,
+    nodes,
+    options,
+}: {
+    driver: Driver;
+    sessionConfig?: Neo4jGraphQLSessionConfig;
+    nodes: Node[];
+    options?: AssertIndexesAndConstraintsOptions;
+}): Promise<void> {
+    await driver.verifyConnectivity();
+
+    const session = driver.session(sessionConfig);
+
+    try {
+        if (options?.create) {
+            await createIndexesAndConstraints({ nodes, session });
+        } else {
+            await checkIndexesAndConstraints({ nodes, session });
+        }
+    } finally {
+        await session.close();
+    }
+}
+
 async function createIndexesAndConstraints({ nodes, session }: { nodes: Node[]; session: Session }) {
     const constraintsToCreate = await getMissingConstraints({ nodes, session });
     const indexesToCreate: { indexName: string; label: string; properties: string[] }[] = [];
@@ -261,31 +287,3 @@ async function getMissingConstraints({
 
     return missingConstraints;
 }
-
-async function assertIndexesAndConstraints({
-    driver,
-    sessionConfig,
-    nodes,
-    options,
-}: {
-    driver: Driver;
-    sessionConfig?: Neo4jGraphQLSessionConfig;
-    nodes: Node[];
-    options?: AssertIndexesAndConstraintsOptions;
-}): Promise<void> {
-    await driver.verifyConnectivity();
-
-    const session = driver.session(sessionConfig);
-
-    try {
-        if (options?.create) {
-            await createIndexesAndConstraints({ nodes, session });
-        } else {
-            await checkIndexesAndConstraints({ nodes, session });
-        }
-    } finally {
-        await session.close();
-    }
-}
-
-export default assertIndexesAndConstraints;

packages/graphql/src/graphql/directives/id.ts

@@ -17,26 +17,10 @@
  * limitations under the License.
  */
 
-import { DirectiveLocation, GraphQLBoolean, GraphQLDirective, GraphQLNonNull } from "graphql";
+import { DirectiveLocation, GraphQLDirective } from "graphql";
 
 export const idDirective = new GraphQLDirective({
     name: "id",
-    description:
-        "Indicates that the field is an identifier for the object type. By default; autogenerated, and has a unique node property constraint in the database.",
+    description: "Enables the autogeneration of UUID values for an ID field. The field becomes immutable.",
     locations: [DirectiveLocation.FIELD_DEFINITION],
-    args: {
-        autogenerate: {
-            defaultValue: false,
-            type: new GraphQLNonNull(GraphQLBoolean),
-        },
-        unique: {
-            defaultValue: true,
-            type: new GraphQLNonNull(GraphQLBoolean),
-        },
-        global: {
-            description: "Opt-in to implementing the Node interface with a globally unique id",
-            type: new GraphQLNonNull(GraphQLBoolean),
-            defaultValue: false,
-        },
-    },
 });

packages/graphql/src/graphql/directives/index.ts

@@ -35,6 +35,7 @@ export { limitDirective } from "./limit";
 export { readonlyDirective } from "./readonly";
 export { relationshipPropertiesDirective } from "./relationship-properties";
 export { relationshipDirective } from "./relationship";
+export { relayIdDirective } from "./relay-id";
 export { timestampDirective } from "./timestamp";
 export { uniqueDirective } from "./unique";
 export { writeonlyDirective } from "./writeonly";

…rser/annotations-parser/id-annotation.ts …aphql/src/graphql/directives/relay-id.tspackages/graphql/src/schema-model/parser/annotations-parser/id-annotation.ts renamed to packages/graphql/src/graphql/directives/relay-id.ts packages/graphql/src/schema-model/parser/annotations-parser/id-annotation.ts renamed to packages/graphql/src/graphql/directives/relay-id.ts

@@ -17,21 +17,11 @@
  * limitations under the License.
  */
 
-import { type DirectiveNode } from "graphql";
-import { IDAnnotation } from "../../annotation/IDAnnotation";
-import { parseArguments } from "../parse-arguments";
-import { idDirective } from "../../../graphql/directives";
+import { DirectiveLocation, GraphQLDirective } from "graphql";
 
-export function parseIDAnnotation(directive: DirectiveNode): IDAnnotation {
-    const { autogenerate, unique, global } = parseArguments(idDirective, directive) as {
-        autogenerate: boolean;
-        unique: boolean;
-        global: boolean;
-    };
-
-    return new IDAnnotation({
-        autogenerate,
-        unique,
-        global,
-    });
-}
+export const relayIdDirective = new GraphQLDirective({
+    name: "relayId",
+    description:
+        "Mark the field to be used as the global node identifier for Relay. This field will be backed by a unique node property constraint.",
+    locations: [DirectiveLocation.FIELD_DEFINITION],
+});

packages/graphql/src/schema-model/annotation/IDAnnotation.ts

@@ -17,14 +17,4 @@
  * limitations under the License.
  */
 
-export class IDAnnotation {
-    public readonly autogenerate: boolean;
-    public readonly unique: boolean;
-    public readonly global: boolean;
-
-    constructor({ autogenerate, unique, global }: { autogenerate: boolean; unique: boolean; global: boolean }) {
-        this.autogenerate = autogenerate;
-        this.unique = unique;
-        this.global = global;
-    }
-}
+export class IDAnnotation {}

packages/graphql/src/schema-model/parser/annotations-parser/id-annotation.test.ts

@@ -22,7 +22,6 @@ import { parseCoalesceAnnotation } from "./annotations-parser/coalesce-annotatio
 import { parseCypherAnnotation } from "./annotations-parser/cypher-annotation";
 import { parseCustomResolverAnnotation } from "./annotations-parser/custom-resolver-annotation";
 import { parseDefaultAnnotation } from "./annotations-parser/default-annotation";
-import { parseIDAnnotation } from "./annotations-parser/id-annotation";
 import { parseFilterableAnnotation } from "./annotations-parser/filterable-annotation";
 import { parseMutationAnnotation } from "./annotations-parser/mutation-annotation";
 import { parsePluralAnnotation } from "./annotations-parser/plural-annotation";
@@ -44,6 +43,7 @@ import { parseSubscriptionsAuthorizationAnnotation } from "./annotations-parser/
 import { filterTruthy } from "../../utils/utils";
 import type { Annotation } from "../annotation/Annotation";
 import { AnnotationsKey } from "../annotation/Annotation";
+import { IDAnnotation } from "../annotation/IDAnnotation";
 
 export function parseAnnotations(directives: readonly DirectiveNode[]): Annotation[] {
     return filterTruthy(
@@ -66,7 +66,7 @@ export function parseAnnotations(directives: readonly DirectiveNode[]): Annotati
                 case AnnotationsKey.fulltext:
                     return parseFullTextAnnotation(directive);
                 case AnnotationsKey.id:
-                    return parseIDAnnotation(directive);
+                    return new IDAnnotation();
                 case AnnotationsKey.jwtClaim:
                     return parseJWTClaimAnnotation(directive);
                 case AnnotationsKey.jwtPayload:

packages/graphql/src/schema-model/parser/parse-annotation.ts

@@ -30,7 +30,7 @@ function checkDirectiveCombinations(directives: readonly DirectiveNode[] = []):
         customResolver: ["alias", "authentication", "authorization", "id", "readonly", "relationship", "writeonly"],
         cypher: [],
         default: [],
-        id: ["cypher", "customResolver", "relationship", "timestamp", "unique"],
+        id: ["cypher", "customResolver", "relationship", "timestamp"],
         populatedBy: ["id", "default", "relationship"],
         private: [],
         readonly: ["cypher", "customResolver"],
@@ -47,7 +47,7 @@ function checkDirectiveCombinations(directives: readonly DirectiveNode[] = []):
             "readonly",
         ],
         timestamp: ["id", "unique"],
-        unique: ["cypher", "id", "customResolver", "relationship", "timestamp"],
+        unique: ["cypher", "customResolver", "relationship", "timestamp"],
         writeonly: ["cypher", "customResolver"],
         // OBJECT
         node: [],