From 3e2e56626e47dd9f5a770d54af1098325b0fcda9 Mon Sep 17 00:00:00 2001 From: Jovi De Croock Date: Sat, 26 Oct 2024 10:24:16 +0200 Subject: [PATCH] Various fixes to docs (#4256) --- cspell.yml | 67 +++++++++++++++++-- website/css/globals.css | 4 +- .../authentication-and-express-middleware.mdx | 12 ++-- website/pages/basic-types.mdx | 12 ++-- website/pages/constructing-types.mdx | 30 ++++----- website/pages/error.mdx | 2 +- website/pages/execution.mdx | 2 +- website/pages/going-to-production.mdx | 2 +- website/pages/graphql.mdx | 12 ++-- website/pages/language.mdx | 8 +-- website/pages/mutations-and-input-types.mdx | 26 +++---- website/pages/object-types.mdx | 22 +++--- website/pages/passing-arguments.mdx | 34 +++++----- .../running-an-express-graphql-server.mdx | 14 ++-- website/pages/type.mdx | 32 ++++----- website/pages/utilities.mdx | 6 +- website/pages/validation.mdx | 6 +- 17 files changed, 174 insertions(+), 117 deletions(-) diff --git a/cspell.yml b/cspell.yml index 962dfd83b0..d841214551 100644 --- a/cspell.yml +++ b/cspell.yml @@ -5,14 +5,13 @@ ignorePaths: # Excluded from spelling check - cspell.yml - package.json + - package-lock.json + - tsconfig.json - benchmark/github-schema.graphql - benchmark/github-schema.json + - website/icons + - website/css overrides: - - filename: '**/docs-old/APIReference-*.md' - ignoreRegExpList: ['/href="[^"]*"/'] - words: - - sublinks - - instanceof - filename: 'website/**' dictionaries: - fullstack @@ -36,6 +35,8 @@ words: - graphiql - uncoerce - uncoerced + - sublinks + - instanceof # Different names used inside tests - Skywalker @@ -45,6 +46,7 @@ words: - Artoo - Threepio - Odie + - Odie's - Damerau - Alderaan - Tatooine @@ -52,7 +54,60 @@ words: # TODO: contribute upstream - deno - - hashbang + - codecov + + # Website tech + - Nextra + - headlessui + - Fastify + - tailwindcss + - svgr + - ruru + + # used as href anchors + - graphqlerror + - syntaxerror + - formaterror + - graphqlschema + - graphqlscalartype + - graphqlobjecttype + - graphqlinterfacetype + - graphqluniontype + - graphqlenumtype + - graphqlinputobjecttype + - graphqllist + - graphqlnonnull + - graphqlint + - graphqlfloat + - graphqlstring + - graphqlboolean + - graphqlid + - getlocation + - isinputtype + - isoutputtype + - isleaftype + - iscompositetype + - isabstracttype + - getnullabletype + - getnamedtype + - introspectionquery + - buildclientschema + - buildschema + - printschema + - printintrospectionschema + - buildastschema + - typefromast + - astfromvalue + - typeinfo + - isvalidjsvalue + - isvalidliteralvalue + - specifiedrules + - Wordmark + - codeofconduct + - graphqlconf + + # website words + - runtimes # TODO: remove bellow words - QLID # GraphQLID diff --git a/website/css/globals.css b/website/css/globals.css index bb77fa72cc..5bb67072b4 100644 --- a/website/css/globals.css +++ b/website/css/globals.css @@ -48,7 +48,9 @@ footer { &:hover { mask-position: 100%; - transition: mask-position 1s ease, -webkit-mask-position 1s ease; + transition: + mask-position 1s ease, + -webkit-mask-position 1s ease; } } diff --git a/website/pages/authentication-and-express-middleware.mdx b/website/pages/authentication-and-express-middleware.mdx index dea2d71e40..7198b97189 100644 --- a/website/pages/authentication-and-express-middleware.mdx +++ b/website/pages/authentication-and-express-middleware.mdx @@ -10,11 +10,11 @@ To use middleware with a GraphQL resolver, just use the middleware like you woul For example, let's say we wanted our server to log the IP address of every request, and we also want to write an API that returns the IP address of the caller. We can do the former with middleware, and the latter by accessing the `request` object in a resolver. Here's server code that implements this: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); -var schema = buildSchema(` +const schema = buildSchema(` type Query { ip: String } @@ -25,13 +25,13 @@ function loggingMiddleware(req, res, next) { next(); } -var root = { +const root = { ip(args, context) { return context.ip; }, }; -var app = express(); +const app = express(); app.use(loggingMiddleware); app.all( '/graphql', diff --git a/website/pages/basic-types.mdx b/website/pages/basic-types.mdx index 3d16e2d44c..bb69bc145c 100644 --- a/website/pages/basic-types.mdx +++ b/website/pages/basic-types.mdx @@ -13,12 +13,12 @@ To use a list type, surround the type in square brackets, so `[Int]` is a list o Each of these types maps straightforwardly to JavaScript, so you can just return plain old JavaScript objects in APIs that return these types. Here's an example that shows how to use some of these basic types: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); // Construct a schema, using GraphQL schema language -var schema = buildSchema(` +const schema = buildSchema(` type Query { quoteOfTheDay: String random: Float! @@ -27,7 +27,7 @@ var schema = buildSchema(` `); // The root provides a resolver function for each API endpoint -var root = { +const root = { quoteOfTheDay() { return Math.random() < 0.5 ? 'Take it easy' : 'Salvation lies within'; }, @@ -39,7 +39,7 @@ var root = { }, }; -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ diff --git a/website/pages/constructing-types.mdx b/website/pages/constructing-types.mdx index 81cbc2350b..33b9c2fe0e 100644 --- a/website/pages/constructing-types.mdx +++ b/website/pages/constructing-types.mdx @@ -9,11 +9,11 @@ When you are using the `GraphQLSchema` constructor to create a schema, instead o For example, let's say we are building a simple API that lets you fetch user data for a few hardcoded users based on an id. Using `buildSchema` we could write a server with: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); -var schema = buildSchema(` +const schema = buildSchema(` type User { id: String name: String @@ -25,7 +25,7 @@ var schema = buildSchema(` `); // Maps id to User object -var fakeDatabase = { +const fakeDatabase = { a: { id: 'a', name: 'alice', @@ -36,13 +36,13 @@ var fakeDatabase = { }, }; -var root = { +const root = { user({ id }) { return fakeDatabase[id]; }, }; -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ @@ -57,12 +57,12 @@ console.log('Running a GraphQL API server at localhost:4000/graphql'); We can implement this same API without using GraphQL schema language: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var graphql = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const graphql = require('graphql'); // Maps id to User object -var fakeDatabase = { +const fakeDatabase = { a: { id: 'a', name: 'alice', @@ -74,7 +74,7 @@ var fakeDatabase = { }; // Define the User type -var userType = new graphql.GraphQLObjectType({ +const userType = new graphql.GraphQLObjectType({ name: 'User', fields: { id: { type: graphql.GraphQLString }, @@ -83,7 +83,7 @@ var userType = new graphql.GraphQLObjectType({ }); // Define the Query type -var queryType = new graphql.GraphQLObjectType({ +const queryType = new graphql.GraphQLObjectType({ name: 'Query', fields: { user: { @@ -99,9 +99,9 @@ var queryType = new graphql.GraphQLObjectType({ }, }); -var schema = new graphql.GraphQLSchema({ query: queryType }); +const schema = new graphql.GraphQLSchema({ query: queryType }); -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ diff --git a/website/pages/error.mdx b/website/pages/error.mdx index d6483b62de..1338d321de 100644 --- a/website/pages/error.mdx +++ b/website/pages/error.mdx @@ -11,7 +11,7 @@ GraphQL errors. You can import either from the `graphql/error` module, or from t ```js import { GraphQLError } from 'graphql'; // ES6 -var { GraphQLError } = require('graphql'); // CommonJS +const { GraphQLError } = require('graphql'); // CommonJS ``` ## Overview diff --git a/website/pages/execution.mdx b/website/pages/execution.mdx index 64af4194a7..9b97c6e67f 100644 --- a/website/pages/execution.mdx +++ b/website/pages/execution.mdx @@ -11,7 +11,7 @@ fulfilling a GraphQL request. You can import either from the `graphql/execution` ```js import { execute } from 'graphql'; // ES6 -var { execute } = require('graphql'); // CommonJS +const { execute } = require('graphql'); // CommonJS ``` ## Overview diff --git a/website/pages/going-to-production.mdx b/website/pages/going-to-production.mdx index 6da130e99b..000c6842e4 100644 --- a/website/pages/going-to-production.mdx +++ b/website/pages/going-to-production.mdx @@ -1,5 +1,5 @@ --- -title: Enabling Defer & Stream +title: Going to Production --- The `@defer` and `@stream` directives are not enabled by default. In order to use these directives, you must add them to your GraphQL Schema and use the `experimentalExecuteIncrementally` function instead of `execute`. diff --git a/website/pages/graphql.mdx b/website/pages/graphql.mdx index d1766286fb..624aeeb10b 100644 --- a/website/pages/graphql.mdx +++ b/website/pages/graphql.mdx @@ -11,7 +11,7 @@ of GraphQL type systems and servers. ```js import { graphql } from 'graphql'; // ES6 -var { graphql } = require('graphql'); // CommonJS +const { graphql } = require('graphql'); // CommonJS ``` ## Overview @@ -95,27 +95,27 @@ var { graphql } = require('graphql'); // CommonJS diff --git a/website/pages/language.mdx b/website/pages/language.mdx index e6a8435966..897bb00927 100644 --- a/website/pages/language.mdx +++ b/website/pages/language.mdx @@ -10,7 +10,7 @@ The `graphql/language` module is responsible for parsing and operating on the Gr ```js import { Source } from 'graphql'; // ES6 -var { Source } = require('graphql'); // CommonJS +const { Source } = require('graphql'); // CommonJS ``` ## Overview @@ -56,7 +56,7 @@ var { Source } = require('graphql'); // CommonJS
  • - `var Kind` Represents the various kinds of parsed AST nodes. + `const Kind` Represents the various kinds of parsed AST nodes.
    • @@ -72,7 +72,7 @@ var { Source } = require('graphql'); // CommonJS
  • - `var BREAK` A token to allow breaking out of the visitor. + `const BREAK` A token to allow breaking out of the visitor.
    • @@ -198,7 +198,7 @@ a new version of the AST with the changes applied will be returned from the visit function. ```js -var editedAST = visit(ast, { +const editedAST = visit(ast, { enter(node, key, parent, path, ancestors) { // @return // undefined: no action diff --git a/website/pages/mutations-and-input-types.mdx b/website/pages/mutations-and-input-types.mdx index aff58e7e27..91f101107e 100644 --- a/website/pages/mutations-and-input-types.mdx +++ b/website/pages/mutations-and-input-types.mdx @@ -21,8 +21,8 @@ It's often convenient to have a mutation that maps to a database create or updat Both mutations and queries can be handled by root resolvers, so the root that implements this schema can simply be: ```js -var fakeDatabase = {}; -var root = { +const fakeDatabase = {}; +const root = { setMessage({ message }) { fakeDatabase.message = message; return message; @@ -68,12 +68,12 @@ Naming input types with `Input` on the end is a useful convention, because you w Here's some runnable code that implements this schema, keeping the data in memory: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); // Construct a schema, using GraphQL schema language -var schema = buildSchema(/* GraphQL */ ` +const schema = buildSchema(/* GraphQL */ ` input MessageInput { content: String author: String @@ -105,9 +105,9 @@ class Message { } // Maps username to content -var fakeDatabase = {}; +const fakeDatabase = {}; -var root = { +const root = { getMessage({ id }) { if (!fakeDatabase[id]) { throw new Error('no message exists with id ' + id); @@ -116,7 +116,7 @@ var root = { }, createMessage({ input }) { // Create a random id for our "database". - var id = require('crypto').randomBytes(10).toString('hex'); + const id = require('crypto').randomBytes(10).toString('hex'); fakeDatabase[id] = input; return new Message(id, input); @@ -131,7 +131,7 @@ var root = { }, }; -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ @@ -157,9 +157,9 @@ mutation { You can use variables to simplify mutation client logic just like you can with queries. For example, some JavaScript code that calls the server to execute this mutation is: ```js -var author = 'andy'; -var content = 'hope is a good thing'; -var query = /* GraphQL */ ` +const author = 'andy'; +const content = 'hope is a good thing'; +const query = /* GraphQL */ ` mutation CreateMessage($input: MessageInput) { createMessage(input: $input) { id diff --git a/website/pages/object-types.mdx b/website/pages/object-types.mdx index 94a42229b8..6699e049fc 100644 --- a/website/pages/object-types.mdx +++ b/website/pages/object-types.mdx @@ -37,15 +37,15 @@ class RandomDie { } roll({ numRolls }) { - var output = []; - for (var i = 0; i < numRolls; i++) { + const output = []; + for (const i = 0; i < numRolls; i++) { output.push(this.rollOnce()); } return output; } } -var root = { +const root = { getDie({ numSides }) { return new RandomDie(numSides || 6); }, @@ -69,12 +69,12 @@ type Query { Putting this all together, here is some sample code that runs a server with this GraphQL API: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); // Construct a schema, using GraphQL schema language -var schema = buildSchema(/* GraphQL */ ` +const schema = buildSchema(/* GraphQL */ ` type RandomDie { numSides: Int! rollOnce: Int! @@ -97,8 +97,8 @@ class RandomDie { } roll({ numRolls }) { - var output = []; - for (var i = 0; i < numRolls; i++) { + const output = []; + for (const i = 0; i < numRolls; i++) { output.push(this.rollOnce()); } return output; @@ -106,13 +106,13 @@ class RandomDie { } // The root provides the top-level API endpoints -var root = { +const root = { getDie({ numSides }) { return new RandomDie(numSides || 6); }, }; -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ diff --git a/website/pages/passing-arguments.mdx b/website/pages/passing-arguments.mdx index b1ddff3575..db67d98a0e 100644 --- a/website/pages/passing-arguments.mdx +++ b/website/pages/passing-arguments.mdx @@ -23,10 +23,10 @@ The exclamation point in `Int!` indicates that `numDice` can't be null, which me So far, our resolver functions took no arguments. When a resolver takes arguments, they are passed as one “args” object, as the first argument to the function. So rollDice could be implemented as: ```javascript -var root = { +const root = { rollDice(args) { - var output = []; - for (var i = 0; i < args.numDice; i++) { + const output = []; + for (const i = 0; i < args.numDice; i++) { output.push(1 + Math.floor(Math.random() * (args.numSides || 6))); } return output; @@ -37,10 +37,10 @@ var root = { It's convenient to use [ES6 destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) for these parameters, since you know what format they will be. So we can also write `rollDice` as ```javascript -var root = { +const root = { rollDice({ numDice, numSides }) { - var output = []; - for (var i = 0; i < numDice; i++) { + const output = []; + for (const i = 0; i < numDice; i++) { output.push(1 + Math.floor(Math.random() * (numSides || 6))); } return output; @@ -53,29 +53,29 @@ If you're familiar with destructuring, this is a bit nicer because the line of c The entire code for a server that hosts this `rollDice` API is: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); // Construct a schema, using GraphQL schema language -var schema = buildSchema(/* GraphQL */ ` +const schema = buildSchema(/* GraphQL */ ` type Query { rollDice(numDice: Int!, numSides: Int): [Int] } `); // The root provides a resolver function for each API endpoint -var root = { +const root = { rollDice({ numDice, numSides }) { - var output = []; - for (var i = 0; i < numDice; i++) { + const output = []; + for (const i = 0; i < numDice; i++) { output.push(1 + Math.floor(Math.random() * (numSides || 6))); } return output; }, }; -var app = express(); +const app = express(); app.all( '/graphql', createHandler({ @@ -102,9 +102,9 @@ When you're passing arguments in code, it's generally better to avoid constructi For example, some JavaScript code that calls our server above is: ```js -var dice = 3; -var sides = 6; -var query = /* GraphQL */ ` +const dice = 3; +const sides = 6; +const query = /* GraphQL */ ` query RollDice($dice: Int!, $sides: Int) { rollDice(numDice: $dice, numSides: $sides) } diff --git a/website/pages/running-an-express-graphql-server.mdx b/website/pages/running-an-express-graphql-server.mdx index f837dd9b2b..2d51c4b52c 100644 --- a/website/pages/running-an-express-graphql-server.mdx +++ b/website/pages/running-an-express-graphql-server.mdx @@ -12,25 +12,25 @@ npm install express graphql-http graphql --save Let's modify our “hello world” example so that it's an API server rather than a script that runs a single query. We can use the 'express' module to run a webserver, and instead of executing a query directly with the `graphql` function, we can use the `graphql-http` library to mount a GraphQL API server on the “/graphql” HTTP endpoint: ```js -var express = require('express'); -var { createHandler } = require('graphql-http/lib/use/express'); -var { buildSchema } = require('graphql'); +const express = require('express'); +const { createHandler } = require('graphql-http/lib/use/express'); +const { buildSchema } = require('graphql'); // Construct a schema, using GraphQL schema language -var schema = buildSchema(` +const schema = buildSchema(` type Query { hello: String } `); // The root provides a resolver function for each API endpoint -var root = { +const root = { hello() { return 'Hello world!'; }, }; -var app = express(); +const app = express(); // Create and use the GraphQL handler. app.all( @@ -59,7 +59,7 @@ One easy way to add it to your server is via the MIT-licensed [ruru](https://git To do so, install the `ruru` module with `npm install --save ruru` and then add the following to your `server.js` file, then restart the `node server.js` command: ```js -var { ruruHTML } = require('ruru/server'); +const { ruruHTML } = require('ruru/server'); // Serve the GraphiQL IDE. app.get('/', (_req, res) => { diff --git a/website/pages/type.mdx b/website/pages/type.mdx index 9e8cfa3565..0eb05d3302 100644 --- a/website/pages/type.mdx +++ b/website/pages/type.mdx @@ -10,7 +10,7 @@ The `graphql/type` module is responsible for defining GraphQL types and schema. ```js import { GraphQLSchema } from 'graphql'; // ES6 -var { GraphQLSchema } = require('graphql'); // CommonJS +const { GraphQLSchema } = require('graphql'); // CommonJS ``` ## Overview @@ -132,26 +132,26 @@ var { GraphQLSchema } = require('graphql'); // CommonJS @@ -177,7 +177,7 @@ validator and executor. #### Example ```js -var MyAppSchema = new GraphQLSchema({ +const MyAppSchema = new GraphQLSchema({ query: MyAppQueryRootType, mutation: MyAppMutationRootType, }); @@ -208,7 +208,7 @@ functions used to ensure validity. #### Example ```js -var OddType = new GraphQLScalarType({ +const OddType = new GraphQLScalarType({ name: 'Odd', serialize: oddValue, parseValue: oddValue, @@ -303,7 +303,7 @@ that value can always be referenced with `this`. #### Examples ```js -var AddressType = new GraphQLObjectType({ +const AddressType = new GraphQLObjectType({ name: 'Address', fields: { street: { type: GraphQLString }, @@ -317,7 +317,7 @@ var AddressType = new GraphQLObjectType({ }, }); -var PersonType = new GraphQLObjectType({ +const PersonType = new GraphQLObjectType({ name: 'Person', fields: () => ({ name: { type: GraphQLString }, @@ -349,7 +349,7 @@ when the field is resolved. #### Example ```js -var EntityType = new GraphQLInterfaceType({ +const EntityType = new GraphQLInterfaceType({ name: 'Entity', fields: { name: { type: GraphQLString }, @@ -381,7 +381,7 @@ to determine which type is actually used when the field is resolved. ### Example ```js -var PetType = new GraphQLUnionType({ +const PetType = new GraphQLUnionType({ name: 'Pet', types: [DogType, CatType], resolveType(value) { @@ -436,7 +436,7 @@ will be used as its internal value. #### Example ```js -var RGBType = new GraphQLEnumType({ +const RGBType = new GraphQLEnumType({ name: 'RGB', values: { RED: { value: 0 }, @@ -494,7 +494,7 @@ Using `NonNull` will ensure that a value must be provided by the query #### Example ```js -var GeoPoint = new GraphQLInputObjectType({ +const GeoPoint = new GraphQLInputObjectType({ name: 'GeoPoint', fields: { lat: { type: new GraphQLNonNull(GraphQLFloat) }, @@ -519,7 +519,7 @@ an object type. #### Example ```js -var PersonType = new GraphQLObjectType({ +const PersonType = new GraphQLObjectType({ name: 'Person', fields: () => ({ parents: { type: new GraphQLList(PersonType) }, @@ -545,7 +545,7 @@ usually the id field of a database row will never be null. #### Example ```js -var RowType = new GraphQLObjectType({ +const RowType = new GraphQLObjectType({ name: 'Row', fields: () => ({ id: { type: new GraphQLNonNull(String) }, diff --git a/website/pages/utilities.mdx b/website/pages/utilities.mdx index 58267d9fed..ba8533c220 100644 --- a/website/pages/utilities.mdx +++ b/website/pages/utilities.mdx @@ -11,7 +11,7 @@ the GraphQL language and type objects. You can import either from the `graphql/u ```js import { introspectionQuery } from 'graphql'; // ES6 -var { introspectionQuery } = require('graphql'); // CommonJS +const { introspectionQuery } = require('graphql'); // CommonJS ``` ## Overview @@ -21,7 +21,7 @@ var { introspectionQuery } = require('graphql'); // CommonJS