adding docs for JsonToTypedObjectRewriter (#12)

Author: chanind

README.md

@@ -298,6 +298,81 @@ query getUser(id: ID!) {
 }
 ```
 
+### JsonToTypedObjectRewriter
+
+`JsonToTypedObjectRewriter` can be used to rewrite a field that previously is just freeform JSON into a typed graphQL field with proper selections and subseelctions. For example, imagine there's a `user` query with type JSON, like `user: { type: GraphQLJSON }`. However, we'd like to improve our API by properly typing the fields within `user` using a graphQL type named `User` with fields `id`, `name`, `isAdmin`, etc.... For example, we have:
+
+```graphql
+query {
+  user
+}
+```
+
+and we want to change it to
+
+```graphql
+query {
+  user {
+    id
+    name
+    isAdmin
+  }
+}
+```
+
+we can make this change with the following rewriter:
+
+```js
+import { JsonToTypedObjectRewriter } from 'graphql-query-rewriter';
+
+// add this to the rewriters array in graphqlRewriterMiddleware(...)
+const rewriter = new JsonToTypedObjectRewriter({
+  fieldName: 'user',
+  objectFields: [
+    { name: 'id' },
+    { name: 'name' },
+    { name: 'isAdmin' },
+  ]
+});
+```
+
+This rewriter also supports rewriting subfields recursively by adding a `subfields` array inside of an object field. For example, the rewriter below:
+
+```js
+import { JsonToTypedObjectRewriter } from 'graphql-query-rewriter';
+
+// add this to the rewriters array in graphqlRewriterMiddleware(...)
+const rewriter = new JsonToTypedObjectRewriter({
+  fieldName: 'user',
+  objectFields: [
+    { name: 'id' },
+    { name: 'name' },
+    {
+      name: 'posts'
+      subfields: [
+        { name: 'id' },
+        { name: 'title' },
+      ]
+    },
+  ]
+});
+```
+
+would rewrite `query { user }` into:
+
+```graphql
+query {
+  user {
+    id
+    name
+    posts {
+      id
+      title
+    }
+  }
+}
+```
+
 ### NestFieldOutputsRewriter
 
 `NestFieldOutputsRewriter` can be used to move mutation outputs into a nested payload object. It's a best-practice for each mutation in GraphQL to have its own output type, and it's required by the [Relay GraphQL Spec](https://facebook.github.io/relay/docs/en/graphql-server-specification.html#mutations). For example, to migrate the mutation `createUser(input: CreateUserInput!): User!` to a mutation with a proper output payload type like:

src/rewriters/JsonToTypedObjectRewriter.ts

@@ -4,7 +4,7 @@ import Rewriter, { RewriterOpts } from './Rewriter';
 
 interface ObjectField {
   name: string;
-  subFields?: ObjectField[];
+  subfields?: ObjectField[];
 }
 
 interface JsonToTypedObjectRewriterOpts extends RewriterOpts {
@@ -44,11 +44,11 @@ export default class JsonToTypedObjectRewriter extends Rewriter {
   private generateSelectionSet(fields: ObjectField[]): SelectionSetNode {
     return {
       kind: 'SelectionSet',
-      selections: fields.map(({ name, subFields }) => ({
+      selections: fields.map(({ name, subfields }) => ({
         kind: 'Field',
         name: { kind: 'Name', value: name },
-        ...(subFields && {
-          selectionSet: this.generateSelectionSet(subFields)
+        ...(subfields && {
+          selectionSet: this.generateSelectionSet(subfields)
         })
       }))
     } as SelectionSetNode;

test/functional/rewriteJsonToTypedObjectRewriter.test.ts

@@ -49,12 +49,12 @@ describe('Rewrite query for GraphQLJSON field to be a query for a nested object
         objectFields: [
           {
             name: 'user',
-            subFields: [
+            subfields: [
               { name: 'userId' },
               { name: 'userHandle' },
               {
                 name: 'item',
-                subFields: [{ name: 'itemMeta' }]
+                subfields: [{ name: 'itemMeta' }]
               }
             ]
           }
@@ -146,12 +146,12 @@ describe('Rewrite query for GraphQLJSON field to be a query for a nested object
         objectFields: [
           {
             name: 'user',
-            subFields: [
+            subfields: [
               { name: 'userId' },
               { name: 'userHandle' },
               {
                 name: 'item',
-                subFields: [{ name: 'itemMeta' }]
+                subfields: [{ name: 'itemMeta' }]
               }
             ]
           }