Added draft for directiveEstimator #3

Author: ivome

README.md

@@ -74,10 +74,13 @@ or write your own:
     last estimator in the chain for a default value.
 *   **[`fieldConfigEstimator`](src/estimators/simple/README.md):** The field config estimator lets you set a numeric value or a custom estimator
     function in the field config of your schema. 
+*   **[`directiveEstimator`](src/estimators/directive/README.md):** Set the complexity via a directive in your 
+    schema definition (for example via GraphQL SDL)
 *   **[`legacyEstimator`](src/estimators/legacy/README.md):** The legacy estimator implements the logic of previous versions. Can be used
     to gradually migrate your codebase to new estimators. 
 *   PR welcome...
 
+Consult the documentation of each estimator for information about how to use them. 
 
 ## Creating Custom Estimators
 
@@ -101,65 +104,6 @@ type ComplexityEstimatorArgs = {
 type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;
 ```
 
-
-## Customizing complexity calculation
-
-By default, every field gets a complexity of 1. Let's look at the following example query: 
-
-```graphql
-query {
-  posts(count: 10) {
-    title
-    text
-  }
-}
-```
-
-This would result in a complexity of 3. The fields `posts`, `title` and `text` each add a complexity of 1.
-If we assume that the posts field returns a list of 10 posts, the complexity estimation is pretty inaccurate. 
-
-When defining your fields, you have a two options to customize the calculation.
-
-You can set a custom complexity in the field config:
-
-```javascript
-const Post = new GraphQLObjectType({
-  name: 'Post',
-  fields: () => ({
-    title: { type: GraphQLString },
-    text: { type: GraphQLString, complexity: 5 },
-  }),
-});
-```
-The same query would now result in a complexity of 7. 
-5 for the `text` field and 1 for each of the other fields. 
-
-You can also pass a calculation function in the field config to determine a custom complexity. 
-This function will provide the complexity of the child nodes as well as the field input arguments.
-
-That way you can make a more realistic estimation of individual field complexity values:
-
-```javascript
-const Query = new GraphQLObjectType({
-  name: 'Query',
-  fields: () => ({
-    posts: {
-      type: new GraphQLList(Post),
-      complexity: (args, childComplexity) => childComplexity * args.count,
-      args: {
-        count: {
-          type: GraphQLInt,
-          defaultValue: 10
-        }
-      }
-    },
-  }),
-});
-```
-
-This would result in a complexity of 60 since the `childComplexity` of posts (`text` 5, `title` 1) is multiplied by the
-number of posts (`args.count`).
-
 ## Usage with express-graphql
 
 To use the query complexity analysis validation rule with express-graphql, use something like the

src/estimators/directive/README.md

@@ -0,0 +1,32 @@
+# Directive Estimator
+
+The `directiveEstimator` lets you define the complexity of each field via GraphQL directives. 
+That way you can define your schema and the complexity via GraphQL SDL and you don't have to 
+change the field config manually.
+
+## Usage
+
+Add estimator to rule:
+
+```typescript
+import queryComplexity, {directiveEstimator} from 'graphql-query-complexity';
+
+const rule = queryComplexity({
+  estimators: [
+    directiveEstimator({
+      // Optionally change the name of the directive here... Default value is `complexity`
+      name: 'complexity'
+    })
+  ]
+  // ... other config
+});
+```
+
+Define your schema and add the complexity directive: 
+
+```graphql
+type Query {
+  # Set the complexity values on the fields via the directive
+  someField: String @complexity(value: 5)
+}
+```

src/estimators/directive/__tests__/directiveEstimator-test.ts

@@ -0,0 +1,100 @@
+/**
+ * Created by Ivo Meißner on 28.07.17.
+ */
+
+import {
+  parse,
+  TypeInfo,
+  ValidationContext,
+  visit,
+  visitWithTypeInfo,
+} from 'graphql';
+
+import {expect} from 'chai';
+
+import schema from './fixtures/schema';
+
+import ComplexityVisitor from '../../../QueryComplexity';
+import directiveEstimator from '../index';
+
+describe('directiveEstimator analysis', () => {
+  const typeInfo = new TypeInfo(schema);
+
+  it('should read complexity from directive', () => {
+    const ast = parse(`
+      query {
+        scalar
+      }
+    `);
+
+    const context = new ValidationContext(schema, ast, typeInfo);
+    const visitor = new ComplexityVisitor(context, {
+      maximumComplexity: 100,
+      estimators: [
+        directiveEstimator()
+      ]
+    });
+
+    visit(ast, visitWithTypeInfo(typeInfo, visitor));
+    expect(visitor.complexity).to.equal(5);
+  });
+
+  it('should not allow negative cost', () => {
+    const ast = parse(`
+      query {
+        negativeCostScalar
+      }
+    `);
+
+    const context = new ValidationContext(schema, ast, typeInfo);
+    const visitor = new ComplexityVisitor(context, {
+      maximumComplexity: 100,
+      estimators: [
+        directiveEstimator()
+      ]
+    });
+
+    visit(ast, visitWithTypeInfo(typeInfo, visitor));
+    expect(visitor.complexity).to.equal(0);
+  });
+
+  it('uses default directive name', () => {
+    const ast = parse(`
+      query {
+        multiDirective
+      }
+    `);
+
+    const context = new ValidationContext(schema, ast, typeInfo);
+    const visitor = new ComplexityVisitor(context, {
+      maximumComplexity: 100,
+      estimators: [
+        directiveEstimator()
+      ]
+    });
+
+    visit(ast, visitWithTypeInfo(typeInfo, visitor));
+    expect(visitor.complexity).to.equal(2);
+  });
+
+  it('uses configured directive name', () => {
+    const ast = parse(`
+      query {
+        multiDirective
+      }
+    `);
+
+    const context = new ValidationContext(schema, ast, typeInfo);
+    const visitor = new ComplexityVisitor(context, {
+      maximumComplexity: 100,
+      estimators: [
+        directiveEstimator({
+          name: 'cost'
+        })
+      ]
+    });
+
+    visit(ast, visitWithTypeInfo(typeInfo, visitor));
+    expect(visitor.complexity).to.equal(1);
+  });
+});

src/estimators/directive/__tests__/fixtures/schema.ts

@@ -0,0 +1,15 @@
+/**
+ * Created by Ivo Meißner on 28.07.17.
+ */
+
+import {
+  buildSchema
+} from 'graphql';
+
+export default buildSchema(`
+type Query {
+  scalar: String @complexity(value: 5)
+  negativeCostScalar: String @complexity(value: -20)
+  multiDirective: String @cost(value: 1) @complexity(value: 2)
+}
+`);

src/estimators/directive/index.ts

@@ -0,0 +1,33 @@
+import {ComplexityEstimator, ComplexityEstimatorArgs} from '../../QueryComplexity';
+import {getDirectiveValues, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLString} from 'graphql';
+import { GraphQLDirective } from 'graphql/type/directives';
+import { DirectiveLocation } from 'graphql/language/directiveLocation';
+
+export default function (options?: {}): ComplexityEstimator {
+  const mergedOptions = {
+    name: 'complexity',
+    ...(options || {})
+  };
+
+  const directive = new GraphQLDirective({
+    name: mergedOptions.name,
+    description: 'Define a relation between the field and other nodes',
+    locations: [
+      DirectiveLocation.FIELD,
+    ],
+    args: {
+      value: {
+        type: new GraphQLNonNull(GraphQLInt),
+        description: 'The complexity value for the field'
+      },
+      multipliers: {
+        type: new GraphQLList(new GraphQLNonNull(GraphQLString))
+      }
+    },
+  });
+
+  return (args: ComplexityEstimatorArgs) => {
+    const values = getDirectiveValues(directive, args.field.astNode);
+    return values.value + args.childComplexity;
+  };
+}

src/estimators/fieldConfig/README.md

@@ -6,7 +6,7 @@ the estimator does not return any value and the next estimator in the chain is e
 
 ## Usage
 
-````typescript
+```typescript
 import queryComplexity, {fieldConfigEstimator} from 'graphql-query-complexity';
 
 const rule = queryComplexity({
@@ -15,7 +15,7 @@ const rule = queryComplexity({
   ]
   // ... other config
 });
-````
+```
 
 You can set a custom complexity as a numeric value in the field config:
 

src/estimators/index.ts

@@ -1,3 +1,4 @@
 export {default as simpleEstimator} from './simple';
 export {default as legacyEstimator} from './legacy';
 export {default as fieldConfigEstimator} from './fieldConfig';
+export {default as directiveEstimator} from './directive';