@graphql-codegen/plugin-helpers 7.2.1 → 7.3.0-alpha-20260831150731-308349d17a63278dee2bccc6aaac7be3ced4bf55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphql-codegen/plugin-helpers",
-  "version": "7.2.1",
+  "version": "7.3.0-alpha-20260831150731-308349d17a63278dee2bccc6aaac7be3ced4bf55",
   "description": "GraphQL Code Generator common utils and types",
   "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 || ^17.0.0"

package/typings/types.d.cts

@@ -3,6 +3,21 @@ import type { ApolloEngineOptions } from '@graphql-tools/apollo-engine-loader';
 import { Source } from '@graphql-tools/utils';
 import type { Profiler } from './profiler.cjs';
 export declare namespace Types {
+    /**
+     * @description Controls how the CLI decides whether the generated content already
+     * matches the output file so the write can be skipped:
+     *
+     * - `'cache-first'` (default): compare against the in-memory hash of what codegen
+     *   last wrote, falling back to reading the file from disk when there is no cached
+     *   entry. Assumes the output is a pure function of the codegen inputs.
+     * - `'disk'`: always compare against the file on disk. Use this when the output
+     *   depends on the file's existing content (e.g. a preset that reads the file and
+     *   rewrites part of it), so a file that was changed on disk is not wrongly skipped
+     *   in watch mode.
+     *
+     * @default 'cache-first'
+     */
+    type ContentComparison = 'cache-first' | 'disk';
     interface GenerateOptions {
         filename: string;
         plugins: Types.ConfiguredPlugin[];
@@ -24,6 +39,11 @@ export declare namespace Types {
         documentTransforms?: ConfiguredDocumentTransform[];
         emitLegacyCommonJSImports?: boolean;
         importExtension?: '' | `.${string}`;
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         */
+        contentComparison?: Types.ContentComparison;
     }
     type FileOutput = {
         filename: string;
@@ -32,6 +52,11 @@ export declare namespace Types {
             beforeOneFileWrite?: LifecycleHooksDefinition['beforeOneFileWrite'];
             afterOneFileWrite?: LifecycleHooksDefinition['afterOneFileWrite'];
         };
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         */
+        contentComparison?: Types.ContentComparison;
     };
     interface DocumentFile extends Source {
         hash?: string | null;
@@ -258,6 +283,14 @@ export declare namespace Types {
          * For more details: https://graphql-code-generator.com/docs/config-reference/codegen-config
          */
         overwrite?: boolean | Partial<NormalizedOverwriteOption>;
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         *
+         * A preset can also set this per output from `buildGeneratesSection`; the value
+         * returned there takes precedence over this one.
+         */
+        contentComparison?: Types.ContentComparison;
         /**
          * @description A pointer(s) to your GraphQL documents: query, mutation, subscription and fragment. These documents will be loaded into for all your output files.
          * You can use one of the following:

package/typings/types.d.ts

@@ -3,6 +3,21 @@ import type { ApolloEngineOptions } from '@graphql-tools/apollo-engine-loader';
 import { Source } from '@graphql-tools/utils';
 import type { Profiler } from './profiler.js';
 export declare namespace Types {
+    /**
+     * @description Controls how the CLI decides whether the generated content already
+     * matches the output file so the write can be skipped:
+     *
+     * - `'cache-first'` (default): compare against the in-memory hash of what codegen
+     *   last wrote, falling back to reading the file from disk when there is no cached
+     *   entry. Assumes the output is a pure function of the codegen inputs.
+     * - `'disk'`: always compare against the file on disk. Use this when the output
+     *   depends on the file's existing content (e.g. a preset that reads the file and
+     *   rewrites part of it), so a file that was changed on disk is not wrongly skipped
+     *   in watch mode.
+     *
+     * @default 'cache-first'
+     */
+    type ContentComparison = 'cache-first' | 'disk';
     interface GenerateOptions {
         filename: string;
         plugins: Types.ConfiguredPlugin[];
@@ -24,6 +39,11 @@ export declare namespace Types {
         documentTransforms?: ConfiguredDocumentTransform[];
         emitLegacyCommonJSImports?: boolean;
         importExtension?: '' | `.${string}`;
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         */
+        contentComparison?: Types.ContentComparison;
     }
     type FileOutput = {
         filename: string;
@@ -32,6 +52,11 @@ export declare namespace Types {
             beforeOneFileWrite?: LifecycleHooksDefinition['beforeOneFileWrite'];
             afterOneFileWrite?: LifecycleHooksDefinition['afterOneFileWrite'];
         };
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         */
+        contentComparison?: Types.ContentComparison;
     };
     interface DocumentFile extends Source {
         hash?: string | null;
@@ -258,6 +283,14 @@ export declare namespace Types {
          * For more details: https://graphql-code-generator.com/docs/config-reference/codegen-config
          */
         overwrite?: boolean | Partial<NormalizedOverwriteOption>;
+        /**
+         * @description How the CLI compares generated content against the output file
+         * to decide whether the write can be skipped. See {@link Types.ContentComparison}.
+         *
+         * A preset can also set this per output from `buildGeneratesSection`; the value
+         * returned there takes precedence over this one.
+         */
+        contentComparison?: Types.ContentComparison;
         /**
          * @description A pointer(s) to your GraphQL documents: query, mutation, subscription and fragment. These documents will be loaded into for all your output files.
          * You can use one of the following: