Modernise JS examples in the documentation

@mandiwise

Description

Much of the code in the "learn" docs uses promise-based APIs:

graphql.github.io/src/pages/learn/execution.mdx

Lines 61 to 65 in b1215ce

    
           function Query_human(obj, args, context, info) { 
        
             return context.db.loadHumanByID(args.id).then( 
        
               userData => new Human(userData) 
        
             ) 
        
           }

This would be much easier to read in the more modern async/await code:

async function Query_human(obj, args, context, info) { 
  const userData = await context.db.loadHumanByID(args.id)
  return new Human(userData) 
}

Motivation

async/await has been around long enough now that this should be the norm, and is much easier to read and reason about. This will also help reduce the need to explain about promises in the documentation (though we will still need to note alternative techniques in other languages).

Collaboration

I do not currently have sufficient bandwidth to make these changes; but if they're not done in a year definitely ping me!

Additional Context

Inspired by @mandiwise's overhaul of the documentation.

This is not the only issue. Some examples ain't working at all. Take for instance this one: https://github.com/graphql/graphql.github.io/blob/source/src/pages/graphql-js/running-an-express-graphql-server.mdx

And the way that you should use graphql-http per their doc is like this:

import express from 'express'; // yarn add express
import { createHandler } from 'graphql-http/lib/use/express';
import { schema } from './previous-step';

// Create an express instance serving all methods on `/graphql`
// where the GraphQL over HTTP express request handler is
const app = express();
app.all('/graphql', createHandler({ schema }));

app.listen({ port: 4000 });
console.log('Listening to port 4000');

Note that the current doc is broken and cannot be run without issue.

BTW to just communicate it clearly. Now I am questioning whether I should read your doc or not. I mean usually I tend to read docs all the time when I start something new. But at this rate I feel what I'll learn from your doc will be something that someone back in 2018 would have learned. Not to mention the NodeJS now is at version 22. While in your doc it is talking about examples being compatible with version 6. I am not sure except some old code bases if anybody else uses Node V6.

@kasir-barati

@kasir-barati wanna help us fix it? 😄

Love to if I get the chance. Since TBF I have already done part of it (link to repo). Or at least it is done in TS, but I can get rid of all typings and replace them with JSDoc. But I also need some inputs along the way.

Here is my own doc compiled mainly from: https://graphql.org/graphql-js.

Awesome - would be great to have your help! The graphql-js.org website is currently being rewritten - if you'd like to get involved in that I encourage you to talk with Jovi and Yaacov in #graphql-js on the GraphQL Discord or get involved with the graphql-js-wg: https://github.com/graphql/graphql-js-wg

This issue specifically relates to the /learn pages rather than the /graphql-js pages, and there we're just looking for much simpler changes as there's a lot of editorial already in progress thanks to Mandi's work.

@benjie

BTW @benjie I am also going through the /learn. So I am looking forward to this issue being resolved.

If you can keep the changes small (but ensure that the surrounding text is correctly adjusted) please do go ahead :) AFAIK no-one else is scheduled to make these specific changes.

Navigation Menu

Repository navigation

Modernise JS examples in the documentation #1821

Description

Motivation

Collaboration

Additional Context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	function Query_human(obj, args, context, info) {
	return context.db.loadHumanByID(args.id).then(
	userData => new Human(userData)
	)
	}

Modernise JS examples in the documentation #1821

Description

Description

Motivation

Collaboration

Additional Context

Activity

kasir-barati commented on Nov 14, 2024

kasir-barati commented on Nov 14, 2024

jorydotcom commented on Nov 15, 2024

kasir-barati commented on Nov 15, 2024

benjie commented on Nov 21, 2024

kasir-barati commented on Nov 22, 2024

benjie commented on Nov 28, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions