feat(graphql-yoga): add support for experimental error coordinate

.changeset/@graphql-yoga_plugin-apollo-usage-report-4288-dependencies.md

@@ -0,0 +1,5 @@
+---
+"@graphql-yoga/plugin-apollo-usage-report": patch
+---
+dependencies updates:
+  - Updated dependency [`@graphql-tools/utils@^10.11.0` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.11.0) (from `^10.9.1`, in `dependencies`)

.changeset/@graphql-yoga_plugin-defer-stream-4288-dependencies.md

@@ -0,0 +1,5 @@
+---
+"@graphql-yoga/plugin-defer-stream": patch
+---
+dependencies updates:
+  - Updated dependency [`@graphql-tools/utils@^10.11.0` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.11.0) (from `^10.6.1`, in `dependencies`)

.changeset/@graphql-yoga_plugin-sofa-4288-dependencies.md

@@ -0,0 +1,5 @@
+---
+"@graphql-yoga/plugin-sofa": patch
+---
+dependencies updates:
+  - Updated dependency [`@graphql-tools/utils@^10.11.0` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.11.0) (from `^10.3.2`, in `dependencies`)

.changeset/fluffy-fans-feel.md

@@ -0,0 +1,78 @@
+---
+'graphql-yoga': minor
+---
+
+Add experimental support for
+[`coordinate` error attribute proposal](https://github.com/graphql/graphql-spec/pull/1200).
+
+The `coordinate` attribute indicates the coordinate in the schema of the resolver which experienced
+the errors. It allows for an easier error source identification than with the `path` which can be
+difficult to walk, or even lead to unsolvable ambiguities when using Union or Interface types.
+
+## Usage
+
+Since this is experimental, it has to be explicitly enabled by adding the appropriate plugin to the
+Yoga instance:
+
+```ts
+import { createYoga, useErrorCoordinate } from 'graphql-yoga'
+import { schema } from './schema'
+
+export const yoga = createYoga({
+  schema,
+  plugins: [useErrorCoordinate()]
+})
+```
+
+Once enabled, located errors will gain the `coordinate` attribute:
+
+```ts
+const myPlugin = {
+  onExecutionResult({ result }) {
+    if (result.errors) {
+      for (const error of result.errors) {
+        console.log('Error at', error.coordinate, ':', error.message)
+      }
+    }
+  }
+}
+```
+
+## Security concerns
+
+Adding a schema coordinate to errors exposes information about the schema, which can be an attack
+vector if you rely on the fact your schema is private and secret.
+
+This is why the `coordinate` attribute is not serialized by default, and will not be exposed to
+clients.
+
+If you want to send this information to client, override either each `toJSON` error's method, or add
+a dedicated extension.
+
+```ts
+import { GraphQLError } from 'graphql'
+import { createYoga, maskError, useErrorCoordinate } from 'graphql-yoga'
+import { schema } from './schema'
+
+export const yoga = createYoga({
+  schema,
+  plugins: [useErrorCoordinate()],
+  maskedErrors: {
+    isDev: process.env['NODE_ENV'] === 'development', // when `isDev` is true, errors are not masked
+    maskError: (error, message, isDev) => {
+      if (error instanceof GraphQLError) {
+        error.toJSON = () => {
+          // Get default graphql serialized error representation
+          const json = GraphQLError.prototype.toJSON.apply(error)
+          // Manually add the coordinate attribute. You can also use extensions instead.
+          json.coordinate = error.coordinate
+          return json
+        }
+      }
+
+      // Keep the default error masking implementation
+      return maskError(error, message, isDev)
+    }
+  }
+})
+```

.changeset/graphql-yoga-4288-dependencies.md

@@ -0,0 +1,6 @@
+---
+"graphql-yoga": patch
+---
+dependencies updates:
+  - Updated dependency [`@graphql-tools/executor@^1.5.0` ↗︎](https://www.npmjs.com/package/@graphql-tools/executor/v/1.5.0) (from `^1.4.0`, in `dependencies`)
+  - Updated dependency [`@graphql-tools/utils@^10.11.0` ↗︎](https://www.npmjs.com/package/@graphql-tools/utils/v/10.11.0) (from `^10.6.2`, in `dependencies`)

examples/egg/package.json

@@ -8,7 +8,7 @@
     "transpile": "tsc"
   },
   "dependencies": {
-    "@graphql-tools/utils": "10.10.1",
+    "@graphql-tools/utils": "10.11.0",
     "egg": "3.31.0",
     "egg-cors": "3.0.1",
     "graphql": "16.12.0",

examples/fastify/package.json

@@ -13,7 +13,7 @@
     "pino-pretty": "13.1.2"
   },
   "devDependencies": {
-    "@graphql-tools/utils": "^10.6.1",
+    "@graphql-tools/utils": "^10.11.0",
     "@types/node": "24.10.0",
     "ts-node": "10.9.2"
   }

examples/live-query/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@envelop/live-query": "10.0.0",
-    "@graphql-tools/utils": "10.10.1",
+    "@graphql-tools/utils": "10.11.0",
     "@n1ru4l/graphql-live-query": "0.10.0",
     "@n1ru4l/in-memory-live-query-store": "0.10.0",
     "graphql": "16.12.0",

packages/graphql-yoga/__tests__/error-masking.spec.ts

@@ -1,5 +1,7 @@
+import { ExecutionResult, GraphQLError } from 'graphql';
 import { inspect } from '@graphql-tools/utils';
 import { createGraphQLError, createLogger, createSchema, createYoga } from '../src/index.js';
+import { useErrorCoordinate } from '../src/plugins/use-error-coordinate.js';
 import { eventStream } from './utilities.js';
 
 describe('error masking', () => {
@@ -859,4 +861,69 @@ describe('error masking', () => {
 }
 `);
   });
+
+  it('should mask experimental coordinate error attribute on production env', async () => {
+    let error: GraphQLError | undefined;
+    const yoga = createYoga({
+      logging: false,
+      plugins: [
+        useErrorCoordinate(),
+        {
+          onExecutionResult({ result }) {
+            error = (result as ExecutionResult).errors?.[0];
+          },
+        },
+      ],
+      schema: createSchema({
+        typeDefs: /* GraphQL */ `
+          type Query {
+            a: String!
+            b: String!
+          }
+        `,
+        resolvers: {
+          Query: {
+            a: () => {
+              throw createGraphQLError('Test Error');
+            },
+            b: () => {
+              throw new Error('Test Error');
+            },
+          },
+        },
+      }),
+    });
+
+    const r1 = await yoga.fetch('http://yoga/graphql', {
+      method: 'POST',
+      headers: {
+        accept: 'application/graphql-response+json',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ query: '{ a }' }),
+    });
+    const b1 = await r1.json();
+
+    expect(error).toMatchObject({
+      message: 'Test Error',
+      coordinate: 'Query.a',
+    });
+    expect(b1.errors[0].coordinate).toBeUndefined();
+
+    const r2 = await yoga.fetch('http://yoga/graphql', {
+      method: 'POST',
+      headers: {
+        accept: 'application/graphql-response+json',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ query: '{ b }' }),
+    });
+    const b2 = await r2.json();
+
+    expect(error).toMatchObject({
+      message: 'Unexpected error.',
+      coordinate: 'Query.b',
+    });
+    expect(b2.errors[0].coordinate).toBeUndefined();
+  });
 });

packages/graphql-yoga/package.json

@@ -51,9 +51,9 @@
   "dependencies": {
     "@envelop/core": "^5.3.0",
     "@envelop/instrumentation": "^1.0.0",
-    "@graphql-tools/executor": "^1.4.0",
+    "@graphql-tools/executor": "^1.5.0",
     "@graphql-tools/schema": "^10.0.11",
-    "@graphql-tools/utils": "^10.6.2",
+    "@graphql-tools/utils": "^10.11.0",
     "@graphql-yoga/logger": "workspace:^",
     "@graphql-yoga/subscription": "workspace:^",
     "@whatwg-node/fetch": "^0.10.6",

packages/graphql-yoga/src/index.ts

@@ -50,6 +50,7 @@ export { createGraphQLError, isPromise, mapMaybePromise } from '@graphql-tools/u
 export { getSSEProcessor } from './plugins/result-processor/sse.js';
 export { processRegularResult } from './plugins/result-processor/regular.js';
 export { useExecutionCancellation } from './plugins/use-execution-cancellation.js';
+export { useErrorCoordinate } from './plugins/use-error-coordinate.js';
 export {
   type LandingPageRenderer,
   type LandingPageRendererOpts,

packages/graphql-yoga/src/plugins/result-processor/stringify.ts

@@ -1,5 +1,5 @@
 import { GraphQLError } from 'graphql';
-import { createGraphQLError } from '@graphql-tools/utils';
+import { createGraphQLError, getSchemaCoordinate } from '@graphql-tools/utils';
 import { isGraphQLError } from '../../error.js';
 import { MaybeArray } from '../../types.js';
 import { ExecutionResultWithSerializer } from '../types.js';
@@ -50,6 +50,7 @@ function omitInternalsFromError<E extends GraphQLError | Error | undefined>(err:
       path: err.path,
       originalError: omitInternalsFromError(err.originalError || undefined),
       extensions: Object.keys(extensions).length ? extensions : undefined,
+      coordinate: getSchemaCoordinate(err),
     }) as E;
   }
   return err;

packages/graphql-yoga/src/plugins/use-error-coordinate.ts

@@ -0,0 +1,10 @@
+import { ExecutionArgs } from '@graphql-tools/executor';
+import { Plugin } from './types.js';
+
+export function useErrorCoordinate(): Plugin {
+  return {
+    onExecute({ args }) {
+      (args as ExecutionArgs).schemaCoordinateInErrors = true;
+    },
+  };
+}

packages/graphql-yoga/src/utils/mask-error.ts

@@ -1,4 +1,4 @@
-import { createGraphQLError } from '@graphql-tools/utils';
+import { createGraphQLError, getSchemaCoordinate } from '@graphql-tools/utils';
 import { isGraphQLError, isOriginalGraphQLError } from '../error.js';
 import { MaskError } from '../types.js';
 
@@ -36,6 +36,7 @@ export const maskError: MaskError = (
     errorOptions.source = error.source;
     errorOptions.positions = error.positions;
     errorOptions.path = error.path;
+    errorOptions.coordinate = getSchemaCoordinate(error);
     if (isDev && error.originalError) {
       errorExtensions['originalError'] = serializeError(error.originalError);
     }

packages/plugins/apollo-usage-report/package.json

@@ -44,7 +44,7 @@
     "@apollo/server-gateway-interface": "^2.0.0",
     "@apollo/usage-reporting-protobuf": "^4.1.1",
     "@apollo/utils.usagereporting": "^2.1.0",
-    "@graphql-tools/utils": "^10.9.1",
+    "@graphql-tools/utils": "^10.11.0",
     "@graphql-yoga/plugin-apollo-inline-trace": "workspace:^",
     "@whatwg-node/promise-helpers": "^1.2.4",
     "tslib": "^2.8.1"

packages/plugins/defer-stream/package.json

@@ -41,7 +41,7 @@
     "graphql-yoga": "workspace:^"
   },
   "dependencies": {
-    "@graphql-tools/utils": "^10.6.1"
+    "@graphql-tools/utils": "^10.11.0"
   },
   "devDependencies": {
     "@graphql-tools/executor-http": "^3.0.0",

packages/plugins/sofa/package.json

@@ -47,7 +47,7 @@
     "graphql-yoga": "workspace:^"
   },
   "dependencies": {
-    "@graphql-tools/utils": "^10.3.2",
+    "@graphql-tools/utils": "^10.11.0",
     "@whatwg-node/promise-helpers": "^1.2.4",
     "sofa-api": "^0.18.8"
   },