From 385d63043f2f629524024e30c60faf6106ab774e Mon Sep 17 00:00:00 2001
From: Hugh Willson <hugh@octonary.com>
Date: Tue, 4 Feb 2020 05:52:30 -0500
Subject: [PATCH] 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 https://github.com/apollographql/graphql-tag/pull/151 and
  https://github.com/apollographql/graphql-tag/pull/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 |  7 ++++++-
 index.d.ts   | 23 ++++++++++++++++++++---
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2eb9002..c039af53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # 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)
@@ -7,7 +12,7 @@
 ### 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
diff --git a/index.d.ts b/index.d.ts
index d010ae40..62532fff 100644
--- a/index.d.ts
+++ b/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;
+}