Better error formatting and another error page with more details #452

.changeset/tame-files-hang.md

@@ -0,0 +1,7 @@
+---
+"graphile-build-pg": patch
+"graphile-build": patch
+"@dataplan/pg": patch
+---
+
+Improve error messages with links to more details.

grafast/dataplan-pg/src/datasource.ts

@@ -1321,12 +1321,11 @@ export function makeRegistryBuilder(): PgRegistryBuilder<{}, {}, {}> {
           throw new Error(
             `Attempted to add a second resource named '${
               resource.name
-            }' (first represented ${printResourceFrom(
+            }':\n  First represented ${printResourceFrom(
               existing,
-            )}, second represents ${printResourceFrom(
+            )}.\n  Second represents ${printResourceFrom(
               resource,
-            )}):\n  Details: ${chalk.bold.blue
-              .underline`https://err.red/p2rc`}`,
+            )}.\n  Details: ${chalk.bold.blue.underline`https://err.red/p2rc`}`,
           );
         }
         return builder;
@@ -1383,12 +1382,12 @@ exportAs("@dataplan/pg", makePgResourceOptions, "makePgResourceOptions");
 
 function printResourceFrom(resource: PgResourceOptions): string {
   if (typeof resource.from === "function") {
-    return `function accepting ${
+    return `a function accepting ${
       resource.parameters?.length
     } parameters and returning SQL type '${
       sql.compile(resource.codec.sqlType).text
     }'`;
   } else {
-    return `table/view/etc called '${sql.compile(resource.from).text}'`;
+    return `a table/view/etc called '${sql.compile(resource.from).text}'`;
   }
 }

graphile-build/graphile-build-pg/src/plugins/PgAttributesPlugin.ts

@@ -100,6 +100,7 @@ function processAttribute(
 
   const {
     scope: { pgCodec: rawPgCodec },
+    Self,
   } = context;
   if (!rawPgCodec || !rawPgCodec.attributes) {
     return;
@@ -252,7 +253,7 @@ function processAttribute(
         fieldSpec,
       ),
     },
-    `Adding '${attributeName}' attribute field to PgCodec '${pgCodec.name}'`,
+    `Adding '${attributeName}' attribute field to GraphQL type '${Self.name}' (representing PgCodec '${pgCodec.name}')`,
   );
 }
 

graphile-build/graphile-build-pg/src/plugins/PgRelationsPlugin.ts

@@ -1388,7 +1388,7 @@ function addRelations(
             },
           ),
         },
-        `Adding '${identifier}' single relation field to ${Self.name}`,
+        `Adding field to GraphQL type '${Self.name}' for singular relation '${identifier}'`,
         "recoverable",
       );
     }

graphile-build/graphile-build/src/extend.ts

@@ -42,7 +42,7 @@ export default function extend<
           key,
         )}'.\n\n${indent(firstEntityDetails)}\n\n${indent(
           secondEntityDetails,
-        )}`,
+        )}.\n  Details: ${chalk.blue.bold.underline`https://err.red/pnc`}`,
       );
     }
     if (hintB) {

postgraphile/postgraphile/graphile.config.ts

@@ -120,7 +120,7 @@ const NonNullRelationsPlugin: GraphileConfig.Plugin = {
         } = build;
         // Extract details about why this field was defined.
         const { isPgSingleRelationField, pgRelationDetails } = context.scope;
-        // See if the field was defined to be a single relation field
+        // See if the field was defined for a singular relation
         if (isPgSingleRelationField && pgRelationDetails) {
           // If so, extract details about the relation
           const { codec, relationName } = pgRelationDetails;

postgraphile/website/postgraphile/errors/2rc.md

@@ -4,8 +4,12 @@ title: Two resources conflicted
 
 You're probably here because you just received an error like:
 
-`Error: Attempted to add a second resource named 'foo' (first represented function accepting 0 parameters and returning SQL type '"bool"', second represents table/view/etc called '"public"."foo"')
-  Details: https://err.red/p2rc`
+```
+Error: Attempted to add a second resource named 'foo':
+  First represented a function accepting 0 parameters and returning SQL type '"bool"'.
+  Second represents a table/view/etc called '"public"."foo"'.
+  Details: https://err.red/p2rc
+```
 
 This happens when PostGraphile is building the
 [resources](../registry.md#resources) for your schema, and the inflection rules

postgraphile/website/postgraphile/errors/nc.md

@@ -0,0 +1,52 @@
+---
+title: Naming conflict
+---
+
+You're probably here because you just received an error like:
+
+```
+Error: A naming conflict has occurred - two entities have tried to define the same key 'task'.
+  The first entity was:
+    Adding 'task' attribute field to GraphQL type 'Subtask' (representing PgCodec 'subtask')
+  The second entity was:
+    Adding field to GraphQL type 'Subtask' for singular relation 'taskByMyTask'
+  Details: https://err.red/pnc
+```
+
+This happens when PostGraphile tries to add an entry to an object, where that
+object already has an entry with that name. There is a very large number of
+circumstances under which this can happen since the `build.extend` method is
+used to avoid conflicts throughout the PostGraphile schema building process:
+when creating codecs, resources or relations; when adding attributes; when
+defining GraphQL fields, arguments or enum values; and much more.
+
+Fortunately we try and give you more details about how the error has come
+about by detailing the key (`'task'` above) that has conflicted, and where the
+first and second conflicting entities originated from.
+
+When reading about the entities, you should keep in mind that codec/PgCodec,
+resource/PgResource, and relation/PgCodecRelation relate to the concepts
+described in the [registry documentation](../registry.md).
+
+A common situation where this would occur is where you have two different
+things (e.g. a column and a relationship) that are trying to be assigned to the
+same field name in the GraphQL schema. This is particularly common when using
+`@graphile/simplify-inflection` because it deliberately shortens the names of
+relations for better ergonomics (e.g. `userByAuthorId` might become simply
+`author`), at the risk of causing more conflicts - this is the main reason this
+preset isn't enabled by default.
+
+Another common situation is where you have two things of the same type (e.g.
+two columns) whose names are made the same after inflection (e.g. columns named
+`thing_2name`, `thing2_name`, `thing2name` and `thing2Name` would all transform
+to a GraphQL field called `thing2Name` in the default inflectors).
+
+To resolve the issue, you should either:
+
+1. use a [smart tag](../smart-tags.md) to assign a different name or field name to one or both of the entities, or
+2. use a custom inflector to change the way the names are generated for the entities, or
+3. do something else suitable for the situation.
+
+If you really are not sure what to do, please come ask us in the
+#help-and-support channel on our Discord at https://discord.gg/graphile - we
+might even add the solution to this page for future users!

postgraphile/website/postgraphile/why-nullable.md

@@ -211,7 +211,7 @@ const NonNullRelationsPlugin: GraphileConfig.Plugin = {
         } = build;
         // Extract details about why this field was defined.
         const { isPgSingleRelationField, pgRelationDetails } = context.scope;
-        // See if the field was defined to be a single relation field
+        // See if the field was defined for a singular relation
         if (isPgSingleRelationField && pgRelationDetails) {
           // If so, extract details about the relation
           const { codec, relationName } = pgRelationDetails;