added directive documentation

Author: jondeweydev

README.md

@@ -81,7 +81,7 @@ app.use(
 
     - `depthLimit: number` | throttle queies by the depth of the nested stucture | defaults to `Infinity` (ie. no limit)
     - `enforceBoundedLists: boolean` | if true, an error will be thrown if any lists types are not bound by slicing arguments [`first`, `last`, `limit`] or directives | defaults to `false`
-    - `dark: boolean` | if true, the package will calculate complexity, depth and tokens but not throttle any queries. Use this to dark launch the package and monitor the rate limiter's impact without limiting user requests. 
+    - `dark: boolean` | if true, the package will calculate complexity, depth and tokens but not throttle any queries. Use this to dark launch the package and monitor the rate limiter's impact without limiting user requests.
 
     All configuration options
 
@@ -109,26 +109,27 @@ app.use(
         dark: false, // defaults to false
         depthLimit: 7 // defaults to Infinity (ie. no depth limiting)
     });
-   ```   
-    
+    ```
+
 ## <a name="lists"></a> Notes on Lists
 
-For queries that return a list, the complexity can be determined with schema directives, or by providing a slicing argument to the query (`first`, `last`, `limit).
+For queries that return a list, the complexity can be determined by providing a slicing argument to the query (`first`, `last`, `limit`), or using a schema directive.
 
 1. Slicing arguments: lists must be bounded by one integer slicing argument in order to calculate the complexity for the field. This package supports the slicing arguments `first`, `last` and `limit`. The complexity of the list will be the value passed as the argument to the field.
 
-2. Directives: ... TODO ...
-   
+2. Directives: First, `@listCost` must be defined in your schema with `directive @listCost(cost: Int!) on FIELD_DEFINITION`. Then, on any unbounded list field, add `@listCost(cost: Int)` and pass into `Int` the complexity you want applied whenever the list is queried.
+
+(Note: Slicing arguments are preferred! `@listCost` is in place for any reason slicing arguments cannot be used.)
 
 ## <a name="how-it-works"></a> How It Works
 
 Requests are rate-limited based on the IP address associated with the request.
 
-On server start, the GraphQL (GQL) schema is parsed to build an object that maps GQL types/fields to their corresponding weights. Type weights can be provided during <a href="typeWeights">initial configuration</a>. When a request is received, this object is used to cross reference the fields queried by the user and compute the complexity of each field. The total complexity of the request is the sum of these values.  
+On server start, the GraphQL (GQL) schema is parsed to build an object that maps GQL types/fields to their corresponding weights. Type weights can be provided during <a href="typeWeights">initial configuration</a>. When a request is received, this object is used to cross reference the fields queried by the user and compute the complexity of each field. The total complexity of the request is the sum of these values.
 
 Complexity is determined, statically (before any resolvers are called) to estimate the upper bound of the response size - a proxy for the work done by the server to build the response. The total complexity is then used to allow/block the request based on popular rate-limiting algorithms.
 
-Requests for each user are processed sequentially by the rate limiter. 
+Requests for each user are processed sequentially by the rate limiter.
 
 Example (with default weights):
 
@@ -144,20 +145,20 @@ query { //  1 (complexity)
    }
    reviews(episode: EMPIRE, limit: 5) { // 5
       stars // stars 0
-      commentary // commentary 0 
-   } 
+      commentary // commentary 0
+   }
 }
 // total complexity of 10
 ```
 
 ## <a name="response"></a> Response
 
-1. <b>Blocked Requests</b>: blocked requests recieve a response with, 
+1. <b>Blocked Requests</b>: blocked requests recieve a response with,
+
+    - status of `429` for `Too Many Requests`
+    - `Retry-After` header with a value of the time to wait in seconds before the request would be approved (`Infinity` if the complexity is greater than rate-limiting capacity).
+    - A JSON response with the `tokens` available, `complexity` of the query, `depth` of the query, `success` of the query set to `false`, and the UNIX `timestamp` of the request
 
-   -  status of `429` for `Too Many Requests` 
-   -  `Retry-After` header with a value of the time to wait in seconds before the request would be approved (`Infinity` if the complexity is greater than rate-limiting capacity). 
-   -  A JSON response with the `tokens` available, `complexity` of the query, `depth` of the query, `success` of the query set to `false`, and the UNIX `timestamp` of the request
-   
 2. <b>Successful Requests</b>: successful requests are passed onto the next function in the middleware chain with the following properties saved to `res.locals`
 
 ```javascript
@@ -174,8 +175,8 @@ query { //  1 (complexity)
 
 ## <a name="error-handling"></a> Error Handling
 
--  Incoming queries are validated against the GraphQL schema. If the query is invalid, a response with status code `400` is returned along with an array of GraphQL Errors that were found.
--  To avoid disrupting server activity, errors thrown during the analysis and rate-limiting of the query are logged and the request is passed onto the next middleware function in the chain.
+-   Incoming queries are validated against the GraphQL schema. If the query is invalid, a response with status code `400` is returned along with an array of GraphQL Errors that were found.
+-   To avoid disrupting server activity, errors thrown during the analysis and rate-limiting of the query are logged and the request is passed onto the next middleware function in the chain.
 
 ## <a name="future-development"></a> Future Development
 
@@ -184,7 +185,7 @@ query { //  1 (complexity)
 -   Implement leaky bucket algorithm for rate-limiting
 -   Experiment with performance improvements
     -   caching optimization
--   Ensure connection pagination conventions can be accuratly acconuted for in complexity analysis 
+-   Ensure connection pagination conventions can be accuratly acconuted for in complexity analysis
 -   Ability to use middleware with other server frameworks
 
 ## <a name="contributions"></a> Contributions