Update/fix the existing TS declaration file (#285)

* Update/fix the existing TS declaration file

This commit modernizes/fixes the existing TypeScript declaration
file as follows:

- The module declaration now better represents how exports are
  currently setup, by using module augmentation to give access to
  helper functions that are added to the `gql` function itself.
- Backwards compatibility has been maintained by re-exporting helper
  functions.
- Stronger typing changes; the first param of the `gql` template
  literal is now a read only string based array, and the `gql` return
  type is a `DocumentNode`. We're leveraging TS'
  [import types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-9.html#import-types)
  functionality to reference the `DocumentNode` type, which will
  help avoid issues like the previously reverted attempts to do this
  in #151 and
  #196.
- While the new `gql` type changes could in theory be considered
  breaking, they really shouldn't be in practice. Tagged template
  literals enforce the use of an immutable array of strings, which
  means that even though `literals` was `any` before, the param
  should only ever been an array of strings. Along the same lines,
  the `gql` function has only ever returned a `DocumentNode`, so
  moving away from the `any` return type should be pretty safe.

* Changelog update

CHANGELOG.md

@@ -1,13 +1,18 @@
 # Change log
 
+### vNext
+
+* Update/fix the existing TS `index.d.ts` declaration file.  <br/>
+  [@hwillson](https://github.com/hwillson) in [#285](https://github.com/apollographql/graphql-tag/pull/285)
+
 ### v2.10.1
 
 * Fix failures in IE11 by avoiding unsupported (by IE11) constructor arguments to `Set` by [rocwang](https://github.com/rocwang) in [#190](https://github.com/apollographql/graphql-tag/pull/190)
 
 ### v2.10.0
 * Add support for `graphql@14` by [timsuchanek](https://github.com/timsuchanek) in [#210](https://github.com/apollographql/graphql-tag/pull/210), [#211](https://github.com/apollographql/graphql-tag/pull/211)
 
-### v2.9.1 
+### v2.9.1
 * Fix IE11 support by using a regular for-loop by [vitorbal](https://github.com/vitorbal) in [#176](https://github.com/apollographql/graphql-tag/pull/176)
 
 ### v2.9.0

index.d.ts

@@ -1,3 +1,20 @@
-export default function gql(literals: any, ...placeholders: any[]): any;
-export function resetCaches(): void;
-export function disableFragmentWarnings(): void;
+declare module "graphql-tag" {
+  function gql(
+    literals: ReadonlyArray<string>,
+    ...placeholders: any[]
+  ): import("graphql").DocumentNode
+
+  namespace gql {
+    function resetCaches(): void;
+    function disableFragmentWarnings(): void;
+    function enableExperimentalFragmentVariables(): void;
+    function disableExperimentalFragmentVariables(): void;
+  }
+
+  export default gql;
+
+  export function resetCaches(): void;
+  export function disableFragmentWarnings(): void;
+  export function enableExperimentalFragmentVariables(): void;
+  export function disableExperimentalFragmentVariables(): void;
+}