advise against using schema wrapping

[n1ru4l]

wrapSchema usually results in bad performance as it generates a proxy schema.

From looking at https://www.graphql-tools.com/docs/schema-wrapping it is unclear to me which use-cases I might wanna use wrapSchema and what I should prefer to use instead?

The page should start with an disclaimer and guidance on what to use, preferably with real-world examples.
E.g. For use-case X use wrapSchema, otherwise use Y.

[klippx]

Interested in this, but what do you mean "advise against"? People who come to wrapSchema are in the need to wrap a remote schema. The performance of it is not a consideration.

But the question we have is - what do we use? I agree this can be a bit unclear, but for me this helped:

Note that schema stitching is a superset of the wrapping API. If you want to combine multiple services (with optional transforms) into one combined gateway schema, then you should use the stitchSchemas method directly and allow it to handle all of the subservice wrappings.

We started with wrapSchema while we had only a single remote schema to wrap, and then switched to stitchSchemas as soon as we had more schemas to wrap. To me it feels like the use case for wrapSchema simply is when you want a single remote schema wrapped with only the customization limited to what SubschemaConfig offers.

stitchSchemas on the other hand can wrap multiple schemas and has customization options that goes way beyond that of SubschemaConfig.

IMO the docs should be restructured. Today we have:

Schema Wrapping <-- Introduction, starts with a subset of stitching. Feels a bit random that this has its own section outside the superset of stitching.
Schema Merging <-- merging wedged in between
> Schema Stitching
    Combining schemas <-- this is the "real" introduction to schema wrapping imo
    Type merging
    ...

I think that it should be like this:

Schema Merging <-- merging moved outside of the stitching topics
Schema Stitching <-- Introduction, starts with the superset of stitching from "Combining schemas"
> Topics
    Type merging    
    ...
    Schema Wrapping <-- Introduce a simpler subset of stitching API here, under the superset of stitching where it belongs.

[n1ru4l]

People have used wrapSchema (including me :D) where mapSchema is more performant if you simply have a GraphQL schema with resolvers.

I dont wanna say there is no need for wrapSchema at all, we should streamline more whether people should use it for achieving X or not.