feat: implement persistedDocuments.hashAlgorithm

[charpeni]

Description

Proposal to add the ability to specify the hash algorithm used for persisted documents as mentioned by #9108.

Ideally, we would like the ability to pass our own generateDocumentHash function so consumers could use their own hash implementation. But, I figured we mostly want to comply with Apollo Server and/or still rely on crypto and therefore to avoid the dance with crypto: createHash, update, and digest, it should be more friendly to accept an algorithm directly.

import { type CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: 'schema.graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      presetConfig: {
-       persistedDocuments: true
+       persistedDocuments: {
+         hashAlgorithm: 'sha256',
+       },
      }
    }
  }
}

Related #9108

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Warning: There's no documentation related to persistedDocuments accepting an object instead of a boolean, outside of within the code. We should document those options (mode, hashPropertyName) and document hashAlgorithm at the same time.

How Has This Been Tested?

• Still defaults to sha1
• Passing hashAlgorithm: 'sha256' uses sha256
• Passing hashAlgorithm: 'sha1' uses sha1
• Added test

Checklist:

• I have followed the CONTRIBUTING doc and the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[changeset-bot]

🦋 Changeset detected

Latest commit: 79aae0a

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

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

[beerose]

There are more options accepted by crypto -- we can include them here and maybe even use a type from Crypto to type this (nevermind, it's typed as string in crypto anyway)

[charpeni]

Crypto's algorithm parameter is typed as a string rather than a union because it solely depends on algorithms supported by the version of OpenSSL on the platform.

I don't know what is a proper type here, as in, what would be an appropriate subset of algorithms that are mainly supported everywhere. If we do something like 'sha1' | 'sha256' | string, it will end up simplified as string and we'll lose the ability to suggest.

I went down the path of only suggesting the default one sha1 as well as the "new" one sha256 that could be required by the server (e.g., Apollo Server). Consumers could still submit pull requests to extend the type here if something else is commonly used.

Thoughts? Open to feedback here!

[ponbac]

I would suggest typing it as: hashAlgorithm?: 'sha1' | 'sha256' | (string & {});.

Should probably also extend the @description to somehow mention this thing you said:
"Crypto's algorithm parameter is typed as a string rather than a union because it solely depends on algorithms supported by the version of OpenSSL on the platform." This should make the quite weird typing more understandable.

That way you keep the suggestions while still allowing users to step outside of the predefined algorithms.
If you then see that another algorithm is commonly used or requested, add it as one of the suggestions.

[beerose]

I agree with @ponbac. Good idea and a nice TS trick there!

[charpeni]

This is clever! Will send a new commit for it.

[beerose]

btw, don't forget to update the generateDocumentHash function signature as well

[charpeni]

Done in 79aae0a, thanks for the good suggestions. 🙏

[n1ru4l]

Can you please also document this on the docs?

[charpeni]

@n1ru4l persistedDocuments as a config object is currently not documented in the docs—at least, I couldn't find it. I plan on sending another pull request to document all the options of persistedDocuments including this new one.