@graphql-eslint/eslint-plugin 3.14.0-alpha-20221221142641-4e1a924 → 3.14.0-alpha-20221222124206-b82954b

package/docs/rules/require-description.md

@@ -0,0 +1,147 @@
+# `require-description`
+
+✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/require-description`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Enforce descriptions in type definitions and operations.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/require-description: ['error', { types: true, FieldDefinition: true }]
+
+type someTypeName {
+  name: String
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-description: ['error', { types: true, FieldDefinition: true }]
+
+"""
+Some type description
+"""
+type someTypeName {
+  """
+  Name description
+  """
+  name: String
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-description: ['error', { OperationDefinition: true }]
+
+# Create a new user
+mutation createUser {
+  # ...
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-description: ['error', { rootField: true }]
+
+type Mutation {
+  "Create a new user"
+  createUser: User
+}
+
+type User {
+  name: String
+}
+```
+
+## Config Schema
+
+The schema defines the following properties:
+
+### `types` (boolean)
+
+Includes:
+
+- `ObjectTypeDefinition`
+- `InterfaceTypeDefinition`
+- `EnumTypeDefinition`
+- `ScalarTypeDefinition`
+- `InputObjectTypeDefinition`
+- `UnionTypeDefinition`
+
+### `rootField` (boolean)
+
+Definitions within `Query`, `Mutation`, and `Subscription` root types.
+
+### `DirectiveDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#DirectiveDefinition).
+
+### `EnumTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#EnumTypeDefinition).
+
+### `EnumValueDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#EnumValueDefinition).
+
+### `FieldDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#FieldDefinition).
+
+### `InputObjectTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#InputObjectTypeDefinition).
+
+### `InputValueDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#InputValueDefinition).
+
+### `InterfaceTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#InterfaceTypeDefinition).
+
+### `ObjectTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#ObjectTypeDefinition).
+
+### `OperationDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#OperationDefinition).
+
+> You must use only comment syntax `#` and not description syntax `"""` or `"`.
+
+### `ScalarTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#ScalarTypeDefinition).
+
+### `UnionTypeDefinition` (boolean)
+
+Read more about this kind on
+[spec.graphql.org](https://spec.graphql.org/October2021/#UnionTypeDefinition).
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/require-description.ts)
+- [Test source](../../packages/plugin/tests/require-description.spec.ts)

package/docs/rules/require-field-of-type-query-in-mutation-result.md

@@ -0,0 +1,50 @@
+# `require-field-of-type-query-in-mutation-result`
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/require-field-of-type-query-in-mutation-result`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Allow the client in one round-trip not only to call mutation but also to get a wagon of data to
+update their application.
+
+> Currently, no errors are reported for result type `union`, `interface` and `scalar`.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/require-field-of-type-query-in-mutation-result: 'error'
+
+type User { ... }
+
+type Mutation {
+  createUser: User!
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-field-of-type-query-in-mutation-result: 'error'
+
+type User { ... }
+
+type Query { ... }
+
+type CreateUserPayload {
+  user: User!
+  query: Query!
+}
+
+type Mutation {
+  createUser: CreateUserPayload!
+}
+```
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/require-field-of-type-query-in-mutation-result.ts)
+- [Test source](../../packages/plugin/tests/require-field-of-type-query-in-mutation-result.spec.ts)

package/docs/rules/require-id-when-available.md

@@ -0,0 +1,91 @@
+# `require-id-when-available`
+
+✅ The `"extends": "plugin:@graphql-eslint/operations-recommended"` property in a configuration file
+enables this rule.
+
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/require-id-when-available`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `true`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Enforce selecting specific fields when they are available on the GraphQL type.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/require-id-when-available: 'error'
+
+# In your schema
+type User {
+  id: ID!
+  name: String!
+}
+
+# Query
+query {
+  user {
+    name
+  }
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/require-id-when-available: 'error'
+
+# In your schema
+type User {
+  id: ID!
+  name: String!
+}
+
+# Query
+query {
+  user {
+    id
+    name
+  }
+}
+
+# Selecting `id` with an alias is also valid
+query {
+  user {
+    id: name
+  }
+}
+```
+
+## Config Schema
+
+The schema defines the following properties:
+
+### `fieldName`
+
+The object must be one of the following types:
+
+- `asString`
+- `asArray`
+
+Default: `"id"`
+
+---
+
+# Sub Schemas
+
+The schema defines the following additional types:
+
+## `asString` (string)
+
+## `asArray` (array)
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/require-id-when-available.ts)
+- [Test source](../../packages/plugin/tests/require-id-when-available.spec.ts)

package/docs/rules/scalar-leafs.md

@@ -0,0 +1,23 @@
+# `scalar-leafs`
+
+✅ The `"extends": "plugin:@graphql-eslint/operations-recommended"` property in a configuration file
+enables this rule.
+
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/scalar-leafs`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL document is valid only if all leaf fields (fields without sub selections) are of scalar or
+enum types.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/ScalarLeafsRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/ScalarLeafsRule-test.ts)

package/docs/rules/selection-set-depth.md

@@ -0,0 +1,86 @@
+# `selection-set-depth`
+
+✅ The `"extends": "plugin:@graphql-eslint/operations-recommended"` property in a configuration file
+enables this rule.
+
+💡 This rule provides
+[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/selection-set-depth`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `true`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Limit the complexity of the GraphQL operations solely by their depth. Based on
+[graphql-depth-limit](https://npmjs.com/package/graphql-depth-limit).
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/selection-set-depth: ['error', { maxDepth: 1 }]
+
+query deep2 {
+  viewer {
+    # Level 0
+    albums {
+      # Level 1
+      title # Level 2
+    }
+  }
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/selection-set-depth: ['error', { maxDepth: 4 }]
+
+query deep2 {
+  viewer {
+    # Level 0
+    albums {
+      # Level 1
+      title # Level 2
+    }
+  }
+}
+```
+
+### Correct (ignored field)
+
+```graphql
+# eslint @graphql-eslint/selection-set-depth: ['error', { maxDepth: 1, ignore: ['albums'] }]
+
+query deep2 {
+  viewer {
+    # Level 0
+    albums {
+      # Level 1
+      title # Level 2
+    }
+  }
+}
+```
+
+## Config Schema
+
+The schema defines the following properties:
+
+### `maxDepth` (number, required)
+
+### `ignore` (array)
+
+The object is an array with all elements of the type `string`.
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/selection-set-depth.ts)
+- [Test source](../../packages/plugin/tests/selection-set-depth.spec.ts)

package/docs/rules/strict-id-in-types.md

@@ -0,0 +1,129 @@
+# `strict-id-in-types`
+
+✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/strict-id-in-types`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Requires output types to have one unique identifier unless they do not have a logical one.
+Exceptions can be used to ignore output types that do not have unique identifiers.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/strict-id-in-types: ['error', { acceptedIdNames: ['id', '_id'], acceptedIdTypes: ['ID'], exceptions: { suffixes: ['Payload'] } }]
+
+# Incorrect field name
+type InvalidFieldName {
+  key: ID!
+}
+
+# Incorrect field type
+type InvalidFieldType {
+  id: String!
+}
+
+# Incorrect exception suffix
+type InvalidSuffixResult {
+  data: String!
+}
+
+# Too many unique identifiers. Must only contain one.
+type InvalidFieldName {
+  id: ID!
+  _id: ID!
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/strict-id-in-types: ['error', { acceptedIdNames: ['id', '_id'], acceptedIdTypes: ['ID'], exceptions: { types: ['Error'], suffixes: ['Payload'] } }]
+
+type User {
+  id: ID!
+}
+
+type Post {
+  _id: ID!
+}
+
+type CreateUserPayload {
+  data: String!
+}
+
+type Error {
+  message: String!
+}
+```
+
+## Config Schema
+
+The schema defines the following properties:
+
+### `acceptedIdNames` (array)
+
+The object is an array with all elements of the type `string`.
+
+Default:
+
+```json
+["id"]
+```
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+### `acceptedIdTypes` (array)
+
+The object is an array with all elements of the type `string`.
+
+Default:
+
+```json
+["ID"]
+```
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+### `exceptions` (object)
+
+Properties of the `exceptions` object:
+
+#### `types` (array)
+
+This is used to exclude types with names that match one of the specified values.
+
+The object is an array with all elements of the type `string`.
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+#### `suffixes` (array)
+
+This is used to exclude types with names with suffixes that match one of the specified values.
+
+The object is an array with all elements of the type `string`.
+
+Additional restrictions:
+
+- Minimum items: `1`
+- Unique items: `true`
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/strict-id-in-types.ts)
+- [Test source](../../packages/plugin/tests/strict-id-in-types.spec.ts)

package/docs/rules/unique-argument-names.md

@@ -0,0 +1,19 @@
+# `unique-argument-names`
+
+✅ The `"extends": "plugin:@graphql-eslint/operations-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/unique-argument-names`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL field or directive is only valid if all supplied arguments are uniquely named.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueArgumentNamesRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueArgumentNamesRule-test.ts)

package/docs/rules/unique-directive-names-per-location.md

@@ -0,0 +1,21 @@
+# `unique-directive-names-per-location`
+
+✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` and
+`"plugin:@graphql-eslint/operations-recommended"` property in a configuration file enables this
+rule.
+
+- Category: `Schema & Operations`
+- Rule name: `@graphql-eslint/unique-directive-names-per-location`
+- Requires GraphQL Schema: `true` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL document is only valid if all non-repeatable directives at a given location are uniquely
+named.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueDirectivesPerLocationRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueDirectivesPerLocationRule-test.ts)

package/docs/rules/unique-directive-names.md

@@ -0,0 +1,19 @@
+# `unique-directive-names`
+
+✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/unique-directive-names`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL document is only valid if all defined directives have unique names.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueDirectiveNamesRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueDirectiveNamesRule-test.ts)

package/docs/rules/unique-enum-value-names.md

@@ -0,0 +1,16 @@
+# `unique-enum-value-names`
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/unique-enum-value-names`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL enum type is only valid if all its values are uniquely named.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueEnumValueNamesRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueEnumValueNamesRule-test.ts)

package/docs/rules/unique-field-definition-names.md

@@ -0,0 +1,19 @@
+# `unique-field-definition-names`
+
+✅ The `"extends": "plugin:@graphql-eslint/schema-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Schema`
+- Rule name: `@graphql-eslint/unique-field-definition-names`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL complex type is only valid if all its fields are uniquely named.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueFieldDefinitionNamesRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueFieldDefinitionNamesRule-test.ts)

package/docs/rules/unique-fragment-name.md

@@ -0,0 +1,52 @@
+# `unique-fragment-name`
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/unique-fragment-name`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `true`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+Enforce unique fragment names across your project.
+
+## Usage Examples
+
+### Incorrect
+
+```graphql
+# eslint @graphql-eslint/unique-fragment-name: 'error'
+
+# user.fragment.graphql
+fragment UserFields on User {
+  id
+  name
+  fullName
+}
+
+# user-fields.graphql
+fragment UserFields on User {
+  id
+}
+```
+
+### Correct
+
+```graphql
+# eslint @graphql-eslint/unique-fragment-name: 'error'
+
+# user.fragment.graphql
+fragment AllUserFields on User {
+  id
+  name
+  fullName
+}
+
+# user-fields.graphql
+fragment UserFields on User {
+  id
+}
+```
+
+## Resources
+
+- [Rule source](../../packages/plugin/src/rules/unique-fragment-name.ts)
+- [Test source](../../packages/plugin/tests/unique-fragment-name.spec.ts)

package/docs/rules/unique-input-field-names.md

@@ -0,0 +1,19 @@
+# `unique-input-field-names`
+
+✅ The `"extends": "plugin:@graphql-eslint/operations-recommended"` property in a configuration file
+enables this rule.
+
+- Category: `Operations`
+- Rule name: `@graphql-eslint/unique-input-field-names`
+- Requires GraphQL Schema: `false` [ℹ️](../../README.md#extended-linting-rules-with-graphql-schema)
+- Requires GraphQL Operations: `false`
+  [ℹ️](../../README.md#extended-linting-rules-with-siblings-operations)
+
+A GraphQL input object value is only valid if all supplied fields are uniquely named.
+
+> This rule is a wrapper around a `graphql-js` validation function.
+
+## Resources
+
+- [Rule source](https://github.com/graphql/graphql-js/blob/main/src/validation/rules/UniqueInputFieldNamesRule.ts)
+- [Test source](https://github.com/graphql/graphql-js/tree/main/src/validation/__tests__/UniqueInputFieldNamesRule-test.ts)