[WIP] Add 'sortIntrospectionQuery' utility function

[IvanGoncharov]

Based on discussion in #941 and #889
Some of GraphQL servers doesn't preserve the order of types/fields and we need to sort them to provide consistent results. I think it is the primary use case for schema sorting so it makes sense to sort the result of introspection query and it makes implementation super simple.

As for other use-cases (e.g. tests) you can query introspection with graphqlSync then sort it and build sorted schema using buildClientSchema.

[IvanGoncharov]

Should be type Query implements FooA & FooB & FooC fixed #1179

[mjmahone]

I'm not sure how much we should value simplicity (take in $ReadOnlyArray, output $ReadOnlyArray) and DRYness vs copies with slightly more complexity. I don't think copies are very costly in this case, but I haven't benchmarked this recently so I don't really know. So all the suggestions below are just suggestions, as I think they'd make the code a little less clear in the process.

[mjmahone]

there's no reason to use sortBy here: just directive.locations.slice().sort((a, b) => a.compareLocale(b));

This is useful because then we can make sortBy take a mutable array, and avoid one array-copy-per-sortByName

[mjmahone]

a bit of a nit, but we can remove this slice with a bit of trickery. We also will no longer need the special sortBy<T>.

function sortFields(
  fields: $ReadOnlyArray<IntrospectionField>,
): $ReadOnlyArray<IntrospectionField> {
  return sortByName(fields.map(field => ({
    name: field.name,
    description: field.description,
    args: sortByName(field.args.slice()),
    type: field.type,
    isDeprecated: field.isDeprecated,
    deprecationReason: field.deprecationReason,
  }));
 }

// This cannot be called on an original ReadOnly array, or it would mutate them
function sortByName<T: { +name: string }>(
  array: Array<T>,
): $ReadOnlyArray<T> {
  return array.sort((obj1, obj2) => obj1.name.localeCompare(obj2.name));
}

This ends up being a little more code (you now have to slice() whenever you want to sortByName), but now we save one array copy per field list.

[mjmahone]

similar to below, given sortByName now takes in a mutable array, we could save one copy here vs. the current code if we flipped this:

types: sortByName(schema.types.map(sortType)),

[mjmahone]

And the same thing here

[IvanGoncharov]

a bit of a nit, but we can remove this slice with a bit of trickery

@mjmahone Great suggestion 👍
I changed sortBy:

function sortBy<T>(
  array: $ReadOnlyArray<T>,
  mapToKey: T => string,
  sortValue?: T => T,
): $ReadOnlyArray<T> {
  const newArray = sortValue ? array.map(sortValue) : array.slice();
  //...
}

What do you think?

I also remembered that locations is a new field and could be missing if you work with old GraphQL API so I change sortBy to simply ignore all non-array values.

[IvanGoncharov]

I changed my mind sorting introspection have one big disadvantage you lose a lot of data when you convert schema to introspection (resolve callback, directives, etc.). I started working on sortSchema function.

Please don't merge this PR

[leebyron]

Going to close this PR at your suggestion, @IvanGoncharov

I agree with you that the right place for sorting is the GraphQLSchema instance itself - introspection is an intermediate representation, and since we have utilities for converting to and from introspection and schema instances, support for sorting a schema instance can be easily derived to sort any other intermediate representation, including introspection