documentsReadOnly implemented by ikusakov2 · Pull Request #10659 · dotansimha/graphql-code-generator

ikusakov2 · 2026-03-31T19:40:56Z

Description

documentsReadOnly implemented, for safe handling of fragment includes between packages in the monorepo

Related # (10658)[https://github.com//issues/10658]

Type of change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Unit testing

changeset-bot · 2026-03-31T19:41:02Z

🦋 Changeset detected

Latest commit: efabaa5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@graphql-codegen/gql-tag-operations	Minor
@graphql-codegen/visitor-plugin-common	Minor
@graphql-codegen/typescript-operations	Minor
@graphql-codegen/plugin-helpers	Minor
@graphql-codegen/cli	Minor
@graphql-codegen/client-preset	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

eddeee888 · 2026-04-03T10:44:25Z

packages/graphql-codegen-cli/src/codegen.ts

-                              throw error;
+                          const readOnlyHash = JSON.stringify(readOnlyPointerMap);
+                          const outputDocumentsReadOnly = await cache(
+                            'documents',


A readonly document is also just a document for hashing purposes.
This ensures there is only one document in the final merged array, because we use the hash to detect the file uniqueness

eddeee888 · 2026-04-03T10:45:32Z

packages/graphql-codegen-cli/src/config.ts


-  async loadDocuments(pointer: Types.OperationDocument[]): Promise<Types.DocumentFile[]> {
+  async loadDocuments(
+    pointer: UnnormalizedTypeDefPointer,


The only caller of this function will be passing in UnnormalizedTypeDefPointer, and nothing else. May as well narrow the type to make it easier to code.

eddeee888 · 2026-04-03T10:46:16Z

packages/graphql-codegen-cli/src/config.ts

-function hashDocument(doc: Types.DocumentFile) {
-  if (doc.rawSDL) {
-    return hashContent(doc.rawSDL);
-  }
+async function addHashToDocumentFiles(
+  documentFilesPromise: Promise<Source[]>,
+  type: 'standard' | 'read-only',
+): Promise<Types.DocumentFile[]> {
+  function hashDocument(doc: Source) {
+    if (doc.rawSDL) {
+      return hashContent(doc.rawSDL);
+    }

-  if (doc.document) {
-    return hashContent(print(doc.document));
-  }
+    if (doc.document) {
+      return hashContent(print(doc.document));
+    }

-  return null;
-}


hashDocument is is only used by one function, so I moved it inline to avoid jumping around.

eddeee888 · 2026-04-03T10:47:55Z

packages/graphql-codegen-cli/src/load.ts

  documentPointers: UnnormalizedTypeDefPointer | UnnormalizedTypeDefPointer[],
  config: Types.Config,
-): Promise<Types.DocumentFile[]> {
+): Promise<Source[]> {


When this function finishes, we'd only get the base Source. Types.DocumentFile is what we get after processing the Source (adding hash and type)

eddeee888 · 2026-04-03T10:52:44Z

packages/plugins/other/visitor-plugin-common/src/optimize-operations.ts

  );

  return newDocuments.map((document, index) => ({
+    ...documents[index],


Context for future me:

Previously we throw away hash when optimising the doc.
When we introduce type (read-only or standard), we need it for further processing, so we need to keep it like this.

Maybe we should not just add these custom Codegen meta directly to the node, since optimizeDocuments implementation may remove it in the future.

Maybe we can add a special key/value to reduce this risk e.g. __meta: { hash: 'abc', types: 'standard' } 🤔

eddeee888 · 2026-04-03T10:54:06Z

packages/utils/plugins-helpers/src/types.ts

+    hash: string;
+    type: 'standard' | 'read-only';


Source is the default from parsing the docs.
DocumentFile is the "processed" source, with Codegen metadata.

We may want to group them to avoid edge cases mentioned in: https://github.com/dotansimha/graphql-code-generator/pull/10659/changes#r3032421307

- Flow documentsReadOnly to typescript-operations - Set up documents-readonly dev-test - Update dev-tests output - Merge standard and read-only documents - Fix Source vs Types.DocumentFile usage for type correctness

eddeee888 · 2026-04-03T11:41:16Z

packages/utils/graphql-codegen-testing/src/operations.ts

Documents now have type being 'standard' | 'read-only'.
If we don't supply that, the plugin will generate nothing.

This utility helps by creating Types.DocumentFile with hash and type hardcoded. If we need to make the params partial with override in the future, we could,.

eddeee888 · 2026-04-04T03:07:12Z

packages/graphql-codegen-cli/src/codegen.ts

+                          const populateDocumentPointerMap = (
+                            allDocumentsDenormalizedPointers: Types.OperationDocument[],
+                          ): UnnormalizedTypeDefPointer => {
+                            const pointer: UnnormalizedTypeDefPointer = {};
+                            for (const denormalizedPtr of allDocumentsDenormalizedPointers) {
+                              if (typeof denormalizedPtr === 'string') {
+                                pointer[denormalizedPtr] = {};
+                              } else if (typeof denormalizedPtr === 'object') {
+                                Object.assign(pointer, denormalizedPtr);
+                              }
+                            }
+                            return pointer;
+                          };


Inlining populateDocumentPointerMap makes it a bit easier to read as we don't jump around the file. We could take this pure function and put it at the bottom of the file if needed.

ikusakov2 · 2026-04-07T19:44:11Z

packages/utils/plugins-helpers/src/types.ts

  export interface DocumentFile extends Source {
-    hash?: string;
+    hash: string;
+    type: 'standard' | 'read-only';


2 non-optional fields introduced. Any existing custom plugin or preset that constructs a DocumentFile manually will now have a TypeScript compile error. This is a breaking change, not a minor one (mentioned in the changeset)

Any existing custom plugin or preset that constructs a DocumentFile manually will now have a TypeScript compile error.

That's a good point, I can make this optional and treat no type as standard

ikusakov2 · 2026-04-07T19:49:55Z

packages/graphql-codegen-cli/src/codegen.ts

+                            processedFile[file.hash] = true;
+
+                            return prev;
+                          }, []);


Looks like the reduce accumulator prev is never used — outputDocuments.push(file) writes to an external array. The return value of the entire reduce is discarded.
It works, by chance, but this is confusing. Maybe a plain for...of loop would be cleaner?

Additionally, if a document has hash: null (which hashDocument() can return when rawSDL and document are both absent), processedFile[null] will be "null" — meaning all null-hash documents get deduped down to 1, which may be wrong.

Looks like the reduce accumulator prev is never used — outputDocuments.push(file) writes to an external array. The return value of the entire reduce is discarded.
It works, by chance, but this is confusing. Maybe a plain for...of loop would be cleaner?

That's true! I think I was trying to reduce the result to outputDocuments, but it's accessible inside the loop anyways. I've made it for...of in 7ec7e06

Additionally, if a document has hash: null (which hashDocument() can return when rawSDL and document are both absent), processedFile[null] will be "null" — meaning all null-hash documents get deduped down to 1, which may be wrong.

Huh, that's true, the typecheck in this repo is not strict enough. Something I'll need to configure after the major release.

I wonder when null would happen though 🤔 When Codegen is parsing an empty file?

ikusakov2 · 2026-04-07T19:56:39Z

.changeset/social-worms-report.md

+'@graphql-codegen/client-preset': minor
+---
+
+Add support for `documentsReadOnly`


It's the last chance to consider other names, such as: externalDocuments, referenceDocuments,
documentsReadOnly has its clear benefits as well, so I don't mind keeping it.

The pro of documentsReadOnly is that it looks related to documents
The con of documentsReadOnly is that it doesn't sound like English.

externalDocuments sounds better. I'm happy to go with that if you are 🙂

Sorry for bringing this one up!
It's really hard to decide!

documentsReadOnly has clear benefits. It is self-descriptive and it appears near documents (for code completion) - which is quite valuable as well. But it is not a proper English.

externalDocuments: The feature is about documents that are loaded for reference but don't produce output. ReadOnly describes how the current output treats them, not a property of the documents themselves - which makes documentsReadOnly name slightly confusing. externalDocuments is a proper name - in terms of English and semantics, but it is not self-explanatory.

I guess a user of this new feature would have to go to the documentation in any case (either slightly confusing name or not informative enough name), so a better sounding name has a slight benefit, imho.

ikusakov2 · 2026-04-07T20:03:48Z

packages/graphql-codegen-cli/src/load.ts

  documentPointers: UnnormalizedTypeDefPointer | UnnormalizedTypeDefPointer[],
  config: Types.Config,
-): Promise<Types.DocumentFile[]> {
+): Promise<Source[]> {


The 2 new fields were added to Types.DocumentFile, not to Source, which makes is harder to see where the contract is established.

Sorry I don't fully understand this statement. However I've traced the CLI code to use the right type:

before adding metadata (hash, type), the documents are Source

after adding metadata the documents are DocumentFile

I feel this may not answer your concern. Could you please help me understand this a bit more?

I was a bit worried that the Types.DocumentFile[] has 2 new properties (hash and type) and Source doesn't have them - which might mislead a user.
But it is correct from the polymorphic world perspective. So - we can leave it as is.

…ateTestDocument utility

eddeee888 · 2026-04-08T14:47:36Z

packages/graphql-codegen-cli/src/codegen.ts

+                          const processedFile: Record<string, true> = {};
+                          const mergedDocuments = [
+                            ...outputDocumentsStandard,
+                            ...outputDocumentsReadOnly,
+                          ];
+                          for (const file of mergedDocuments) {
+                            if (processedFile[file.hash]) {
+                              continue;
                            }
-                          });

-                          outputDocuments = result.documents;
+                            outputDocuments.push(file);
+                            processedFile[file.hash] = true;
+                          }


I've considered forwarding documentsReadOnly as-is but hit a few annoying cases:

documents are processed a lot after the initial loading stage here. If we kept documentsReadOnly separate, we'd need to run the same functions over them

Plugins use positional param, which means documentsReadOnly need to be at the last position to avoid a breaking change. This works, but feels disconnected

For this reason, I feel it's easier if we merge them as early as possible, and run the same processing over both types, and plugins like typescript-operations can handle the filtering without having to access another param

documentsReadOnly implemented

3005df7

eddeee888 force-pushed the feature/documentsReadOnly branch from c88a311 to 3005df7 Compare April 3, 2026 09:14

eddeee888 reviewed Apr 3, 2026

View reviewed changes

Implement documentsReadOnly for typescript-operations

df25ba7

- Flow documentsReadOnly to typescript-operations - Set up documents-readonly dev-test - Update dev-tests output - Merge standard and read-only documents - Fix Source vs Types.DocumentFile usage for type correctness

eddeee888 force-pushed the feature/documentsReadOnly branch from 8f4ba67 to df25ba7 Compare April 3, 2026 10:55

eddeee888 added 2 commits April 3, 2026 21:59

Add changeset

104e6c2

Add createTestDocument to support testing docs

f89eb27

eddeee888 reviewed Apr 3, 2026

View reviewed changes

eddeee888 force-pushed the feature/documentsReadOnly branch from 631abbd to 40f5ca8 Compare April 4, 2026 02:59

Add unit test for readOnly

819cf71

eddeee888 force-pushed the feature/documentsReadOnly branch from 40f5ca8 to 819cf71 Compare April 4, 2026 02:59

eddeee888 reviewed Apr 4, 2026

View reviewed changes

eddeee888 added 2 commits April 5, 2026 15:15

Merge branch 'master' into feature/documentsReadOnly

620da75

Merge branch 'master' into feature/documentsReadOnly

7f460d3

ikusakov2 commented Apr 7, 2026

View reviewed changes

eddeee888 added 6 commits April 8, 2026 23:26

Convert reduce to for...of loop

7ec7e06

Fix missing return type

c5641fc

Revert hash and type being required, update related tests, remove cre…

75e31dd

…ateTestDocument utility

Remove changeset

1001bed

Revert tests

ee0a41f

Rename function to match new purpose

efabaa5

eddeee888 reviewed Apr 8, 2026

View reviewed changes

Conversation

ikusakov2 commented Mar 31, 2026

Description

Type of change

How Has This Been Tested?

Uh oh!

changeset-bot bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eddeee888 Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eddeee888 Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ikusakov2 Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eddeee888 Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Mar 31, 2026 •

edited

Loading

eddeee888 Apr 3, 2026 •

edited

Loading

eddeee888 Apr 3, 2026 •

edited

Loading

ikusakov2 Apr 8, 2026 •

edited

Loading

eddeee888 Apr 8, 2026 •

edited

Loading