Feature/unique directive

docs/modules/ROOT/content-nav.adoc

@@ -12,6 +12,7 @@
 *** xref:type-definitions/cypher.adoc[]
 *** xref:type-definitions/default-values.adoc[]
 *** xref:type-definitions/database-mapping.adoc[]
+*** xref:type-definitions/constraints.adoc[]
 ** xref:queries.adoc[]
 ** xref:mutations/index.adoc[]
 *** xref:mutations/create.adoc[]

docs/modules/ROOT/pages/api-reference/neo4jgraphql.adoc

@@ -192,3 +192,148 @@ const { CypherRuntime } = require("@neo4j/graphql");
  - `CypherReplanning.FORCE` +
  - `CypherReplanning.SKIP`
 |===
+
+[[api-reference-checkneo4jcompat]]
+== `checkNeo4jCompat`
+
+Asynchronous function to check the compatibility of the specified DBMS, that either resolves to `void` in a successful scenario, or throws an error if the database is not compatible with the Neo4j GraphQL Library.
+
+Takes an `input` object as a parameter, the supported fields of which are described below.
+
+=== Example
+
+Given any valid type definitions saved to the variable `typeDefs` and a valid driver instance saved to the variable `driver`, the following will confirm database compatibility:
+
+[source, javascript, indent=0]
+----
+const neoSchema = new Neo4jGraphQL({ typeDefs, driver });
+await neoSchema.checkNeo4jCompat();
+----
+
+[[api-reference-checkneo4jcompat-input]]
+=== Input
+
+Accepts the arguments below:
+
+|===
+|Name and Type |Description
+
+|`driver` +
+ +
+ Type: https://neo4j.com/docs/javascript-manual/current/[`Driver`]
+|An instance of a Neo4j driver.
+
+|`driverConfig` +
+ +
+ Type: xref::api-reference/neo4jgraphql.adoc#api-reference-checkneo4jcompat-input-driverconfig[`DriverConfig`]
+|Additional driver configuration options.
+|===
+
+[[api-reference-checkneo4jcompat-input-driverconfig]]
+==== `DriverConfig`
+
+|===
+|Name and Type |Description
+
+|`database` +
+ +
+ Type: `string`
+|The name of the database within the DBMS to connect to.
+
+|`bookmarks` +
+ +
+ Type: `string` or `Array<string>`
+|One or more bookmarks to use for the connection.
+|===
+
+[[api-reference-assertconstraints]]
+== `assertConstraints`
+
+Asynchronous function to assert the existence of database constraints, that either resolves to `void` in a successful scenario, or throws an error if the necessary consraints do not exist following its execution.
+
+Takes an `input` object as a parameter, the supported fields of which are described below.
+
+=== Example
+
+Given the following type definitions saved to the variable `typeDefs` and a valid driver instance saved to the variable `driver`:
+
+[source, graphql, indent=0]
+----
+type Book {
+    isbn: String! @unique
+}
+----
+
+And the construction of a `Neo4jGraphQL`, using:
+
+[source, javascript, indent=0]
+----
+const neoSchema = new Neo4jGraphQL({ typeDefs, driver });
+----
+
+The following will check whether a unique node property constraint exists for label "Book" and property "isbn", and throw an error if it does not:
+
+[source, javascript, indent=0]
+----
+await neoSchema.assertConstraints();
+----
+
+The next example will create the constraint if it does not exist:
+
+[source, javascript, indent=0]
+----
+await neoSchema.assertConstraints({ options: { create: true } });
+----
+
+[[api-reference-assertconstraints-input]]
+=== Input
+
+Accepts the arguments below:
+
+|===
+|Name and Type |Description
+
+|`driver` +
+ +
+ Type: https://neo4j.com/docs/javascript-manual/current/[`Driver`]
+|An instance of a Neo4j driver.
+
+|`driverConfig` +
+ +
+ Type: xref::api-reference/neo4jgraphql.adoc#api-reference-assertconstraints-input-driverconfig[`DriverConfig`]
+|Additional driver configuration options.
+
+|`options` +
+ +
+ Type: xref::api-reference/neo4jgraphql.adoc#api-reference-assertconstraints-input-assertconstraintsoptions[`AssertConstraintsOptions`]
+|Options for the execution of `assertConstraints`.
+|===
+
+[[api-reference-assertconstraints-input-driverconfig]]
+==== `DriverConfig`
+
+|===
+|Name and Type |Description
+
+|`database` +
+ +
+ Type: `string`
+|The name of the database within the DBMS to connect to.
+
+|`bookmarks` +
+ +
+ Type: `string` or `Array<string>`
+|One or more bookmarks to use for the connection.
+|===
+
+[[api-reference-assertconstraints-input-assertconstraintsoptions]]
+==== `AssertConstraintsOptions`
+
+|===
+|Name and Type |Description
+
+|`create` +
+ +
+ Type: `boolean`
+|Whether or not to create constraints if they do not yet exist. Disabled by default.
+|===

docs/modules/ROOT/pages/directives.adoc

@@ -91,6 +91,12 @@ The `@timestamp` directive flags fields to be used to store timestamps on create
 
 Reference: xref::type-definitions/autogeneration.adoc#type-definitions-autogeneration-timestamp[`@timestamp`]
 
+== `@unique`
+
+The `@unique` directive indicates that there should be a uniqueness constraint in the database for the fields that it is applied to.
+
+Reference: xref::type-definitions/constraints.adoc#type-definitions-constraints-unique[Unique node property constraints]
+
 == `@writeonly`
 
 The `@writeonly` directive marks fields as write-only.

docs/modules/ROOT/pages/type-definitions/autogeneration.adoc

@@ -4,18 +4,23 @@
 [[type-definitions-autogeneration-id]]
 == `@id`
 
-This directive marks a field as the unique identifier for an object type, and by default enables autogenerated of IDs for the field.
+This directive marks a field as the unique identifier for an object type, and by default; enables autogeneration of IDs for the field and implies that a unique node property constraint should exist for the property.
 
 The format of each generated ID is a UUID generated by https://neo4j.com/docs/cypher-manual/current/functions/scalar/#functions-randomuuid[randomUUID() function].
 
 If autogeneration for an ID field is enabled, the field will not be present in input types for Mutations.
 
+See xref::type-definitions/constraints.adoc#type-definitions-constraints-unique[Unique node property constraints] for details on how to assert the existence of the necessary database constraints for relevant fields.
+
 === Definition
 
 [source, graphql, indent=0]
 ----
-"""Indicates that the field is the unique identifier for the object type, and additionally enables the autogeneration of IDs."""
-directive @id(autogenerate: Boolean! = true) on FIELD_DEFINITION
+"""Indicates that the field is an identifier for the object type. By default; autogenerated, and has a unique node property constraint in the database."""
+directive @id(
+    autogenerate: Boolean! = true
+    unique: Boolean! = true
+) on FIELD_DEFINITION
 ----
 
 === Usage
@@ -48,6 +53,16 @@ type User {
 }
 ----
 
+You can disable the mapping of the `@id` directive to a unique node property constraint by setting the `unique` argument to `false`:
+
+[source, graphql, indent=0]
+----
+type User {
+    id: ID! @id(unique: false)
+    username: String!
+}
+----
+
 [[type-definitions-autogeneration-timestamp]]
 == `@timestamp`
 

docs/modules/ROOT/pages/type-definitions/constraints.adoc

@@ -0,0 +1,79 @@
+[[type-definitions-constraints]]
+= Constraints
+
+[[type-definitions-constraints-unique]]
+== Unique node property constraints
+
+Unique node property constraints map to `@unique` directives used in your type definitions, which has the following definition:
+
+[source, graphql, indent=0]
+----
+"""Informs @neo4j/graphql that there should be a uniqueness constraint in the database for the decorated field."""
+directive @unique(
+    """The name which should be used for this constraint. By default; type name, followed by an underscore, followed by the field name."""
+    constraintName: String
+) on FIELD_DEFINITION
+----
+
+Additionally, the usage of the xref::type-definitions/autogeneration.adoc#type-definitions-autogeneration-id[`@id`] directive by default implies that there should be a unique node property constraint in the database for that property.
+
+Using this directive does not automatically ensure the existence of these constraints, and you will need to run a function on server startup. See the section xref::type-definitions/constraints.adoc#type-definitions-constraints-asserting[Asserting constraints] below for details.
+
+=== `@unique` directive usage
+
+`@unique` directives can only be used in GraphQL object types representing nodes, and will only be applied for the "main" label for the node. You can find some examples below.
+
+In the following example, a unique constraint will be asserted for the label `Colour` and the property `hexadecimal`:
+
+[source, graphql, indent=0]
+----
+type Colour {
+    hexadecimal: String! @unique
+}
+----
+
+In the next example, a unique constraint with name `unique_colour` will be asserted for the label `Colour` and the property `hexadecimal`:
+
+[source, graphql, indent=0]
+----
+type Colour {
+    hexadecimal: String! @unique(constraintName: "unique_colour")
+}
+----
+
+The `@node` directive is used to change the database label mapping in this next example, so a unique constraint will be asserted for the label `Color` and the property `hexadecimal`:
+
+[source, graphql, indent=0]
+----
+type Colour @node(label: "Color") {
+    hexadecimal: String! @unique
+}
+----
+
+In the following example, the `additionalLabels` argument of the `@node` directive is ignored when it comes to asserting constraints, so the outcome is the same as the example above:
+
+[source, graphql, indent=0]
+----
+type Colour @node(label: "Color", additionalLabels: ["Hue"]) {
+    hexadecimal: String! @unique
+}
+----
+
+[[type-definitions-constraints-asserting]]
+== Asserting constraints
+
+In order to ensure that the specified constraints exist in the database, you will need to run the function `assertConstraints`, the full details of which can be found in the xref::api-reference/neo4jgraphql.adoc#api-reference-assertconstraints[API reference]. A simple example to create the necessary constraints might look like the following, assuming a valid driver instance in the variable `driver`. This will create two constraints, one for each field decorated with `@id` or `@unique`:
+
+[source, javascript, indent=0]
+----
+const typeDefs = gql`
+    type Colour {
+        id: ID! @id
+        hexadecimal: String! @unique
+    }
+`;
+
+const neoSchema = new Neo4jGraphQL({ typeDefs, driver });
+
+await neoSchema.assertConstraints({ options: { create: true }});
+----

packages/graphql/src/classes/Neo4jGraphQL.ts

@@ -31,6 +31,7 @@ import { getJWT } from "../auth/index";
 import { DEBUG_GRAPHQL } from "../constants";
 import getNeo4jResolveTree from "../utils/get-neo4j-resolve-tree";
 import createAuthParam from "../translate/create-auth-param";
+import assertConstraints, { AssertConstraintOptions } from "./utils/asserts-constraints";
 
 const debug = Debug(DEBUG_GRAPHQL);
 
@@ -170,6 +171,19 @@ class Neo4jGraphQL {
 
         return checkNeo4jCompat({ driver, driverConfig });
     }
+
+    async assertConstraints(
+        input: { driver?: Driver; driverConfig?: DriverConfig; options?: AssertConstraintOptions } = {}
+    ): Promise<void> {
+        const driver = input.driver || this.driver;
+        const driverConfig = input.driverConfig || this.config?.driverConfig;
+
+        if (!driver) {
+            throw new Error("neo4j-driver Driver missing");
+        }
+
+        await assertConstraints({ driver, driverConfig, nodes: this.nodes, options: input.options });
+    }
 }
 
 export default Neo4jGraphQL;

packages/graphql/src/classes/Node.ts

@@ -84,6 +84,8 @@ type AuthableField =
 
 type SortableField = PrimitiveField | CustomScalarField | CustomEnumField | TemporalField | PointField | CypherField;
 
+type ConstrainableField = PrimitiveField | TemporalField | PointField;
+
 class Node extends GraphElement {
     public relationFields: RelationField[];
     public connectionFields: ConnectionField[];
@@ -169,6 +171,10 @@ class Node extends GraphElement {
         ].filter((field) => !field.typeMeta.array);
     }
 
+    public get constrainableFields(): ConstrainableField[] {
+        return [...this.primitiveFields, ...this.temporalFields, ...this.pointFields];
+    }
+
     public getLabelString(context: Context): string {
         return this.nodeDirective?.getLabelsString(this.name, context) || `:${this.name}`;
     }
@@ -177,6 +183,10 @@ class Node extends GraphElement {
         return this.nodeDirective?.getLabels(this.name, context) || [this.name];
     }
 
+    public getMainLabel(): string {
+        return this.nodeDirective?.label || this.name;
+    }
+
     public getPlural(options: { camelCase: boolean }): string {
         // camelCase is optional in this case to maintain backward compatibility
         if (this.nodeDirective?.plural) {