v5 Roadmap

[yaacovCR]

Track and try out the new alpha v5 releases.

New Features

Build

• support cjs, esm, mjs module format (closes Error importing with --experimental-modules #913 via ESM CJS + Jest #1320 and Support Node ESModule #1329)
• fix circular dependencies (closes Can't build with Rollup due to Circular dependencies  #924 via Fix circular dependencies #1326)

Transformation

• add TransformQuery transform to allow delegating to subfields with error preservation (closes Add a way to delegate to a non-root field #543 via merge graphql-tools-fork into v5 #1307)
• add FilterObjectFields transform to filter specific fields on objects (closing Add transform to filter arbitrary type fields #819 via merge graphql-tools-fork into v5 #1307)
• add WrapType transform to namespace subschema root queries (closing Merge remote GraphQL schema into a nested structure #961, Make it easy to prevent merging of root query fields #439 via merge graphql-tools-fork into v5 #1307), not for use with mutations.
• add HoistFields transform to hoist subfields from field to parent type (closing Help for moving field from Viewer to Query #781 via merge graphql-tools-fork into v5 #1307)

Stitching

• add ability to specify custom root type names, with new transform RenameRootTypes that allows changing a subschemas root type, a necessary transform when the subschema includes the root query type within another output type (closing mergeSchemas not working with Shopify Admin GraphQL schema #892 via merge graphql-tools-fork into v5 #1307)
• add type merging, and otherwise restore onTypeConflict (closing mergeSchemas onTypeConflict still mentioned in docs, but no longer exists #1133, Schema stitching and transforms to remove ID pointers #1118, Remove onTypeConflict from public api #1044, deprecated onTypeConflict substitution? #863, Merge conflictive types #642, Is there a way to not expose relationship ids when stitching schemas? #447 by merge graphql-tools-fork into v5 #1307).
• expose createRequest functionality for alternative method of batching besides using links (closing createRequest with transforms API #724 via merge graphql-tools-fork into v5 #1307)
• provide support for GraphQLUpload scalar with schema stitching (closing Merging schemas that use apollo-upload-server #671 via merge graphql-tools-fork into v5 #1307)
• add ability to makeRemoteExecutableSchema/wrapSchema/transformSchema/mergeSchemas to specify custom delegating resolver ("createSubscriptionResolver" should be allowed to be overridden with a custom resolver as happens with "createResolver" function #1302)

Utilities

• expose mapSchema (which creates new schemas), visitSchema (which modifies existing schemas), healSchema (which visitSchema uses), toConfig, as well as additional utility functions (closing Export healSchema, visitSchema and SchemaVisitor from index.js #1070, Make visitSchema (and other transform helper functions) top-level exports. #922, Add fragment parameter to delegateToSchema #786, Enum no longer work with graphql master branch #761 via merge graphql-tools-fork into v5 #1307)

Bug fixes:

• fix types (closed Can't get correct types extending SchemaDirectiveVisitor #1298 via Generics for Arguments and Context in SchemaDirectiveVisitor #1325, closed Support for defining field extensions property in Apollo resolvers #1279 via Allow to use a map of extensions in a field resolver #1324, closed VisitableSchemaType is no longer exported #837 via merge graphql-tools-fork into v5 #1307)
• issues involving nullable fields and schema stitching (closing defaultMergedResolver unexpected behaviour for aliased and nullable fields #1171 via merge graphql-tools-fork into v5 #1307)
• issues involving custom enums/scalars and schema stitching (closing custom GraphQLScalarType not used on mergedSchemas. #1200, Directive disappears when an enum has resolvers defined #1148, enums are broken after transformSchema #1056, An enum type that uses a custom value in mergeSchemas reports an error #1033, Enums with custom values fail to stitch correctly #510, Custom scalars break when being stitched together by mergeSchemas #501, Object given to custom scalar serialize changes type #454 via merge graphql-tools-fork into v5 #1307)
• issues involving default fields and schema stitching (closing BugFix: Default fields do not work when passing schema as string to mergeSchemas #1121 via merge graphql-tools-fork into v5 #1307)
• issues involving root field renaming, subscriptions, and schema stitching (closing Subscriptions not working if using RenameRootFields #997, schema transform bug: cannot return null for non nullable type subscription_root.user #1002 via merge graphql-tools-fork into v5 #1307)
• issues involving directives and schema stitching (closing Declaring schema directive on extended type does not populate astNode.directive property #1296, Deprecated directive used in extend type is broken with mergeSchemas #1254, 4.0.5 patch breaks @skip and @include directives in schema stitching #1159, via merge graphql-tools-fork into v5 #1307)
• issues involving default field resolvers and schema stitching (closing Default resolver for fields that are functions does not work when passing resolvers to mergeSchemas #1061 via merge graphql-tools-fork into v5 #1307)
• issues involving error handling and schema stitching (closing mergeSchemas does not report correct NonNullable field errors #1047, Proper error handling [minor changes required]: fixing Object object error messages #1046, code always INTERNAL_SERVER_ERROR when using mergeSchemas #1037, Remote schema incorrectly serialize other contents if error presents #905, Fix error, tracing, and cache control propagation in schema stitching #890, remoteExecutableSchema always returns true when error present for value #832, Schema stitching swallows original error stack traces from the children #743, Stitching with formatError is very limited... #480 via merge graphql-tools-fork into v5 #1307)
• issues involving importing directories (closing TypeError: _1.extractExtensionDefinitions is not a function. (In '_1.extractExtensionDefinitions(astDocument)', '_1.extractExtensionDefinitions' is undefined) #1242 via merge graphql-tools-fork into v5 #1307)
• fix n^2 problem within makeRemoteExecutableSchema (closing makeRemoteExecutableSchema squares remote query field executions #1346 via fix(makeRemoteExecutableSchema): stop sending entire document #1352)

[bionicles]

How would a functional API look for directives?

For example, what would be the arguments to a directive function and what would / could we return from it?

[yaacovCR]

@bionicles

You can currently (in next branch) use visitSchema to modify an existing schema (vs mapSchema which creates a new schema).

visitSchema takes an instantiated SchemaDirectiveVisitor or SchemaVisitor class
or an object of type SchemaVisitorMap that can define visitor functions for each graphql object type, see https://github.com/apollographql/graphql-tools/blob/next/src/Interfaces.ts#L443

You can also pass in a visitorSelector function instead of either of those to dynamically change how each object is visited, which is what is done when using schema directives:

https://github.com/apollographql/graphql-tools/blob/next/src/utils/SchemaDirectiveVisitor.ts#L141

The function instantiates the class to pass in the directive arguments here:

https://github.com/apollographql/graphql-tools/blob/next/src/utils/SchemaDirectiveVisitor.ts#L197

What could easily be done is passing in a special function instead of a SchemaDirectiveVisitor class. This function might take as its arguments the same arguments as the SchemaDirectiveVisitor constructor, but most importantly, the directive arguments, and could return a SchemaVisitorMap. Or, if implementers know which types they are visiting, they could do the extra discrimination and return the correct type visitor.

So, it would be a functional approach, the provided function for each named directive would take in all the info for each graphql object including the directive args and return an object containing a set of functions, one of which being the appropriate one, or the exact appropriate one.

[yaacovCR]

But ideally, thinking more broadly, to allow directives specified on object fields to easily modify the input fields of the resolver arguments (see parallel approach https://github.com/profusion/apollo-validation-directives/blob/master/README.md#value-validation), we can think of a different architecture altogether that is more generic. The schema directive is meant to transform the schema, but perhaps a number of schema directives are meant to work together to modify a schema. A schema directive implementation should really be a function that takes a list of directive names (so users of schema directives can use whatever names they want, to prevent conflicts) and returns a function that takes a schema as an argument and returns a schema.

The implementation can rely on visitSchema or mapSchema to assess how the graphql objects are annotated and modify them accordingly.

An additional single exported helper would be useful to extract a map of the directives and their arguments from the AST

[yaacovCR]

Moved several new features to #1337 so we could get v5 out as soon as possible.

[yaacovCR]

Let's continue discussion on how to easily use combinations of directives to modify schemas at #1234.