Add valueToLiteral() (graphql#3812)

[graphql#3065 rebased on
main](graphql#3065).

Depends on graphql#3811

@leebyron comments from original PR:

> **Provides the "Value to Literal" methods in this [data flow
chart](https://user-images.githubusercontent.com/50130/118379946-51ac5300-b593-11eb-839f-c483ecfbc875.png).**
> 
> * Adds `valueToLiteral()` which takes an external input value and
translates it to a literal, allowing for custom scalars to define this
behavior.
> 
> **This also adds important changes to Input Coercion, especially for
custom scalars:**
> 
> * The value provided to `parseLiteral` is now `ConstValueNode` and the
second `variables` argument has been removed. For all built-in scalars
this has no effect, but any custom scalars which use complex literals no
longer need to do variable reconciliation manually (in fact most do not
-- this has been an easy subtle bug to miss).
>   This behavior is possible with the addition of `replaceVariables`

Changes to the original:
1. Instead of changing the signature of `parseLiteral()`, a new method
`parseConstLiteral()` has been added with the simpler signature.
`parseLiteral()` has been marked for deprecation.
2. `replaceVariables()` has access to operation and fragment variables.

Co-authored-by: Lee Byron <[email protected]>

integrationTests/ts/kitchenSink-test.ts

@@ -8,7 +8,7 @@ new GraphQLScalarType({
   name: 'SomeScalar',
   serialize: undefined,
   parseValue: undefined,
-  parseLiteral: undefined,
+  parseConstLiteral: undefined,
 });
 
 new GraphQLError('test', { nodes: undefined });

src/execution/__tests__/variables-test.ts

@@ -47,7 +47,7 @@ const TestFaultyScalar = new GraphQLScalarType({
   parseValue() {
     throw TestFaultyScalarGraphQLError;
   },
-  parseLiteral() {
+  parseConstLiteral() {
     throw TestFaultyScalarGraphQLError;
   },
 });
@@ -58,7 +58,7 @@ const TestComplexScalar = new GraphQLScalarType({
     expect(value).to.equal('SerializedValue');
     return 'DeserializedValue';
   },
-  parseLiteral(ast) {
+  parseConstLiteral(ast) {
     expect(ast).to.include({ kind: 'StringValue', value: 'SerializedValue' });
     return 'DeserializedValue';
   },
@@ -281,7 +281,7 @@ describe('Execute: Handles inputs', () => {
         });
       });
 
-      it('properly runs parseLiteral on complex scalar types', () => {
+      it('properly runs parseConstLiteral on complex scalar types', () => {
         const result = executeQuery(`
           {
             fieldWithObjectInput(input: {c: "foo", d: "SerializedValue"})

src/index.ts

@@ -445,6 +445,10 @@ export {
   // A helper to use within recursive-descent visitors which need to be aware of the GraphQL type system.
   TypeInfo,
   visitWithTypeInfo,
+  // Converts a value to a const value by replacing variables.
+  replaceVariables,
+  // Create a GraphQL literal (AST) from a JavaScript input value.
+  valueToLiteral,
   // Coerces a JavaScript value to a GraphQL type, or produces errors.
   coerceInputValue,
   // Coerces a GraphQL literal (AST) to a GraphQL type, or returns undefined.

src/type/__tests__/definition-test.ts

@@ -5,7 +5,7 @@ import { identityFunc } from '../../jsutils/identityFunc.js';
 import { inspect } from '../../jsutils/inspect.js';
 
 import { Kind } from '../../language/kinds.js';
-import { parseValue } from '../../language/parser.js';
+import { parseConstValue } from '../../language/parser.js';
 
 import type { GraphQLNullableType, GraphQLType } from '../definition.js';
 import {
@@ -55,13 +55,13 @@ describe('Type System: Scalars', () => {
     ).not.to.throw();
   });
 
-  it('accepts a Scalar type defining parseValue and parseLiteral', () => {
+  it('accepts a Scalar type defining parseValue and parseConstLiteral', () => {
     expect(
       () =>
         new GraphQLScalarType({
           name: 'SomeScalar',
           parseValue: dummyFunc,
-          parseLiteral: dummyFunc,
+          parseConstLiteral: dummyFunc,
         }),
     ).to.not.throw();
   });
@@ -72,25 +72,23 @@ describe('Type System: Scalars', () => {
     expect(scalar.serialize).to.equal(identityFunc);
     expect(scalar.parseValue).to.equal(identityFunc);
     expect(scalar.parseLiteral).to.be.a('function');
+    expect(scalar.parseConstLiteral).to.be.a('function');
   });
 
-  it('use parseValue for parsing literals if parseLiteral omitted', () => {
+  it('use parseValue for parsing literals if parseConstLiteral omitted', () => {
     const scalar = new GraphQLScalarType({
       name: 'Foo',
       parseValue(value) {
         return 'parseValue: ' + inspect(value);
       },
     });
 
-    expect(scalar.parseLiteral(parseValue('null'))).to.equal(
+    expect(scalar.parseConstLiteral(parseConstValue('null'))).to.equal(
       'parseValue: null',
     );
-    expect(scalar.parseLiteral(parseValue('{ foo: "bar" }'))).to.equal(
-      'parseValue: { foo: "bar" }',
-    );
     expect(
-      scalar.parseLiteral(parseValue('{ foo: { bar: $var } }'), { var: 'baz' }),
-    ).to.equal('parseValue: { foo: { bar: "baz" } }');
+      scalar.parseConstLiteral(parseConstValue('{ foo: "bar" }')),
+    ).to.equal('parseValue: { foo: "bar" }');
   });
 
   it('rejects a Scalar type defining parseLiteral but not parseValue', () => {
@@ -104,6 +102,18 @@ describe('Type System: Scalars', () => {
       'SomeScalar must provide both "parseValue" and "parseLiteral" functions.',
     );
   });
+
+  it('rejects a Scalar type defining parseConstLiteral but not parseValue', () => {
+    expect(
+      () =>
+        new GraphQLScalarType({
+          name: 'SomeScalar',
+          parseConstLiteral: dummyFunc,
+        }),
+    ).to.throw(
+      'SomeScalar must provide both "parseValue" and "parseConstLiteral" functions.',
+    );
+  });
 });
 
 describe('Type System: Objects', () => {