@graphql-codegen/gql-tag-operations 1.5.7 → 1.5.8

package/cjs/index.js

@@ -28,7 +28,16 @@ const plugin = (_, __, { sourcesWithOperations, useTypeImports, augmentedModuleN
         }
         code.push([
             `\n`,
+            `/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n *\n`,
+            ` *\n * @example\n`,
+            ' * ```ts\n',
+            ' * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);\n',
+            ' * ```\n *\n',
+            ` * The query argument is unknown!\n`,
+            ` * Please regenerate the types.\n`,
+            `**/\n`,
             `export function ${gqlTagName}(source: string): unknown;\n`,
+            `\n`,
             `export function ${gqlTagName}(source: string) {\n`,
             `  return (documents as any)[source] ?? {};\n`,
             `}\n`,
@@ -57,6 +66,11 @@ const plugin = (_, __, { sourcesWithOperations, useTypeImports, augmentedModuleN
 exports.plugin = plugin;
 function getDocumentRegistryChunk(sourcesWithOperations = []) {
     const lines = new Set();
+    lines.add(`/**\n * Map of all GraphQL operations in the project.\n *\n * This map has several performance disadvantages:\n`);
+    lines.add(` * 1. It is not tree-shakeable, so it will include all operations in the project.\n`);
+    lines.add(` * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.\n`);
+    lines.add(` * 3. It does not support dead code elimination, so it will add unused operations.\n *\n`);
+    lines.add(` * Therefore it is highly recommended to use the babel-plugin for production.\n */\n`);
     lines.add(`const documents = {\n`);
     for (const { operations, ...rest } of sourcesWithOperations) {
         const originalString = rest.source.rawSDL;
@@ -77,7 +91,8 @@ function getGqlOverloadChunk(sourcesWithOperations, gqlTagName, mode, emitLegacy
             : emitLegacyCommonJSImports
                 ? `typeof import('./graphql').${operations[0].initialName}`
                 : `typeof import('./graphql.js').${operations[0].initialName}`;
-        lines.add(`export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`);
+        lines.add(`/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n */\n` +
+            `export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`);
     }
     return lines;
 }

package/esm/index.js

@@ -25,7 +25,16 @@ export const plugin = (_, __, { sourcesWithOperations, useTypeImports, augmented
         }
         code.push([
             `\n`,
+            `/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n *\n`,
+            ` *\n * @example\n`,
+            ' * ```ts\n',
+            ' * const query = gql(`query GetUser($id: ID!) { user(id: $id) { name } }`);\n',
+            ' * ```\n *\n',
+            ` * The query argument is unknown!\n`,
+            ` * Please regenerate the types.\n`,
+            `**/\n`,
             `export function ${gqlTagName}(source: string): unknown;\n`,
+            `\n`,
             `export function ${gqlTagName}(source: string) {\n`,
             `  return (documents as any)[source] ?? {};\n`,
             `}\n`,
@@ -53,6 +62,11 @@ export const plugin = (_, __, { sourcesWithOperations, useTypeImports, augmented
 };
 function getDocumentRegistryChunk(sourcesWithOperations = []) {
     const lines = new Set();
+    lines.add(`/**\n * Map of all GraphQL operations in the project.\n *\n * This map has several performance disadvantages:\n`);
+    lines.add(` * 1. It is not tree-shakeable, so it will include all operations in the project.\n`);
+    lines.add(` * 2. It is not minifiable, so the string of a GraphQL query will be multiple times inside the bundle.\n`);
+    lines.add(` * 3. It does not support dead code elimination, so it will add unused operations.\n *\n`);
+    lines.add(` * Therefore it is highly recommended to use the babel-plugin for production.\n */\n`);
     lines.add(`const documents = {\n`);
     for (const { operations, ...rest } of sourcesWithOperations) {
         const originalString = rest.source.rawSDL;
@@ -73,7 +87,8 @@ function getGqlOverloadChunk(sourcesWithOperations, gqlTagName, mode, emitLegacy
             : emitLegacyCommonJSImports
                 ? `typeof import('./graphql').${operations[0].initialName}`
                 : `typeof import('./graphql.js').${operations[0].initialName}`;
-        lines.add(`export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`);
+        lines.add(`/**\n * The ${gqlTagName} function is used to parse GraphQL queries into a document that can be used by GraphQL clients.\n */\n` +
+            `export function ${gqlTagName}(source: ${JSON.stringify(originalString)}): ${returnType};\n`);
     }
     return lines;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphql-codegen/gql-tag-operations",
-  "version": "1.5.7",
+  "version": "1.5.8",
   "description": "GraphQL Code Generator plugin for generating a typed gql tag function",
   "peerDependencies": {
     "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"