readme updates

Author: shalarewicz

README.md

@@ -117,15 +117,25 @@ For queries that return a list, the complexity can be determined by providing a
 
 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: To use directives, `@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>)` where `<Int>` is the complexity you want applied to the list when queried.
+2. Directives: To use directives, `@listCost` must be defined in your schema with `directive @listCost(cost: Int!) on FIELD_DEFINITION`. Then, on any field which resolves to an unbounded list, add `@listCost(cost: [Int])` where `[Int]` is the complexity for this field.
 
-(Note: Slicing arguments are preferred! `@listCost` is in place for any reason slicing arguments cannot be used.)
+(Note: Slicing arguments are preferred and will override the the `@listCost` directive! `@listCost` is in place as a fall back.)
+
+```graphql
+directive @listCost(cost: Int!) on FIELD_DEFINITION
+type Human {
+    id: ID!
+}
+type Query {
+    humans: [Human] @listCost(cost: 10)
+}
+```
 
 ## <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 startup, 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.
 
@@ -134,19 +144,23 @@ Requests for each user are processed sequentially by the rate limiter.
 Example (with default weights):
 
 ```graphql
-query {   # 1 query 
-   hero (episode: EMPIRE) {   # 1 object 
-      name   # 0 scalar
-      id   # 0 scalar
-      friends (first: 3) {   # 3 objects
-         name   # 0 scalar
-         id   # 0 scalar
-      }
-   }
-   reviews (episode: EMPIRE, limit: 5) { #   5 objects
-      stars   # 0 scalar
-      commentary   # 0 scalar
-   }
+query {
+    # 1 query
+    hero(episode: EMPIRE) {
+        # 1 object
+        name # 0 scalar
+        id # 0 scalar
+        friends(first: 3) {
+            # 3 objects
+            name # 0 scalar
+            id # 0 scalar
+        }
+    }
+    reviews(episode: EMPIRE, limit: 5) {
+        #   5 objects
+        stars # 0 scalar
+        commentary # 0 scalar
+    }
 } # total complexity of 10
 ```
 
@@ -155,10 +169,10 @@ query {   # 1 query
 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
+    - `Retry-After` header indicating the time to wait in seconds before the request could be approved (`Infinity` if the complexity is greater than rate-limiting capacity).
+    - A JSON response with the remaining `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`
+2. <b>Successful Requests</b>: successful requests are passed on to the next function in the middleware chain with the following properties saved to `res.locals`
 
 ```javascript
 {
@@ -167,15 +181,15 @@ query {   # 1 query
       tokens: number, // tokens available after request
       compexity: number, // complexity of the query
       depth: number, // depth of the query
-      timestamp: number, // ms
+      timestamp: number, // UNIX timestamp
    }
 }
 ```
 
 ## <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.
+-   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 piece of middleware in the chain.
 
 ## <a name="future-development"></a> Future Development