Added fieldConfigEstimator / legacyEstimator tests

Author: ivome

README.md

@@ -19,6 +19,10 @@ npm install -S graphql-query-complexity
 Create the rule with a maximum query complexity:
 
 ```javascript
+import queryComplexity, {
+  simpleEstimator
+} from 'graphql-query-complexity';
+
 const rule = queryComplexity({
   // The maximum allowed query complexity, queries above this threshold will be rejected
   maximumComplexity: 1000,
@@ -35,10 +39,69 @@ const rule = queryComplexity({
   // Optional function to create a custom error
   createError: (max: number, actual: number) => {
     return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
-  }
+  },
+  
+  // Add any number of estimators. The estimators are invoked in order, the first
+  // numeric value that is being returned by an estimator is used as the field complexity.
+  // If no estimator returns a value, an exception is raised. 
+  estimators: [
+    // Add more estimators here...
+    
+    // This will assign each field a complexity of 1 if no other estimator
+    // returned a value. 
+    simpleEstimator({
+      defaultComplexity: 1
+    })
+  ]
 });
 ```
 
+## Configuration / Complexity Estimators
+
+The complexity calculation of a GraphQL query can be customized with so called complexity estimators.
+A complexity estimator is a simple function that calculates the complexity for a field. You can add
+any number of complexity estimators to the rule, which are then executed one after another. 
+The first estimator that returns a numeric complexity value determines the complexity for that field. 
+
+At least one estimator has to return a complexity value, otherwise an exception is raised. You can
+for example use the [simpleEstimator](./src/estimators/simple/README.md) as the last estimator
+in your chain to define a default value. 
+
+You can use any of the available estimators to calculate the complexity of a field
+or write your own:
+
+*   **[`simpleEstimator`](src/estimators/simple/README.md):** The simple estimator returns a fixed complexity for each field. Can be used as
+    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. 
+*   **[`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...
+
+
+## Creating Custom Estimators
+
+An estimator has the following function signature: 
+
+```typescript
+type ComplexityEstimatorArgs = {
+  // The composite type (interface, object, union) that the evaluated field belongs to
+  type: GraphQLCompositeType,
+  
+  // The GraphQLField that is being evaluated
+  field: GraphQLField<any, any>,
+  
+  // The input arguments of the field
+  args: {[key: string]: any},
+  
+  // The complexity of all child selections for that field
+  childComplexity: number
+}
+
+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: 

package.json

@@ -3,6 +3,7 @@
   "version": "0.1.2",
   "description": "Validation rule for GraphQL query complexity analysis",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "lint": "eslint src/**/*.ts",
     "clean": "rimraf dist/*",

src/QueryComplexity.ts

@@ -14,7 +14,7 @@ import {
   FragmentSpreadNode,
   InlineFragmentNode,
   assertCompositeType,
-  GraphQLField, isCompositeType, GraphQLCompositeType,
+  GraphQLField, isCompositeType, GraphQLCompositeType, GraphQLFieldMap,
 } from 'graphql';
 import {
   GraphQLUnionType,
@@ -29,22 +29,23 @@ import {
   legacyEstimator
 } from './estimators';
 
+declare module 'graphql/type/definition' {
+  export interface GraphQLField<TSource, TContext, TArgs = { [argName: string]: any }> {
+    complexity?: Complexity;
+  }
+}
+
 export type ComplexityEstimatorArgs = {
   type: GraphQLCompositeType,
-  field: ComplexityGraphQLField<any, any>,
+  field: GraphQLField<any, any>,
   args: {[key: string]: any},
   childComplexity: number
 }
 
 export type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;
 
-type ComplexityGraphQLField<TSource, TContext> = GraphQLField<TSource, TContext> & {
-  complexity?: any
-}
-
-type ComplexityGraphQLFieldMap<TSource, TContext> = {
-  [key: string]: ComplexityGraphQLField<TSource, TContext>
-}
+// Complexity can be anything that is supported by the configured estimators
+export type Complexity = any;
 
 export interface QueryComplexityOptions {
   // The maximum allowed query complexity, queries above this threshold will be rejected
@@ -62,8 +63,7 @@ export interface QueryComplexityOptions {
   // Optional function to create a custom error
   createError?: (max: number, actual: number) => GraphQLError,
 
-  // An array of complexity estimators to use if no estimator or value is defined
-  // in the field configuration
+  // An array of complexity estimators to use for estimating the complexity
   estimators?: Array<ComplexityEstimator>;
 }
 
@@ -146,7 +146,7 @@ export default class QueryComplexity {
     complexity: number = 0
   ): number {
     if (node.selectionSet) {
-      let fields:ComplexityGraphQLFieldMap<any, any> = {};
+      let fields:GraphQLFieldMap<any, any> = {};
       if (typeDef instanceof GraphQLObjectType || typeDef instanceof GraphQLInterfaceType) {
         fields = typeDef.getFields();
       }

src/estimators/fieldConfig/README.md

@@ -0,0 +1,83 @@
+# Field Config Estimator
+
+The `fieldConfigEstimator` lets you define a numeric value or a custom estimator
+in the field config of your GraphQL schema. If no complexity is set in the field config,
+the estimator does not return any value and the next estimator in the chain is executed. 
+
+## Usage
+
+````typescript
+import queryComplexity, {fieldConfigEstimator} from 'graphql-query-complexity';
+
+const rule = queryComplexity({
+  estimators: [
+    fieldConfigEstimator()
+  ]
+  // ... other config
+});
+````
+
+You can set a custom complexity as a numeric value in the field config:
+
+```javascript
+const Post = new GraphQLObjectType({
+  name: 'Post',
+  fields: () => ({
+    title: { type: GraphQLString },
+    text: { type: GraphQLString, complexity: 5 },
+  }),
+});
+```
+
+**Example Query:**
+
+```graphql
+query {
+  posts(count: 10) {
+    title
+    text
+  }
+}
+```
+
+This query would result in a complexity of 7. 
+5 for the `text` field and 1 for each of the other fields. 
+
+You can also pass an estimator 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.
+
+The function signature is the same as for the main estimator which lets you reuse estimators:
+
+```typescript
+type ComplexityEstimatorArgs = {
+  type: GraphQLCompositeType,
+  field: GraphQLField<any, any>,
+  args: {[key: string]: any},
+  childComplexity: number
+}
+
+type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;
+```
+
+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`).