Specify from in @ref to apply refs to a single type

.changeset/two-panthers-laugh.md

@@ -0,0 +1,5 @@
+---
+"graphile-build-pg": minor
+---
+
+Specify `from` in `@ref` to apply refs to a single type

grafast/dataplan-pg/src/interfaces.ts

@@ -45,6 +45,7 @@ export type PgDecode<TForJavaScript, TFromPostgres = string> = (
 export type PgRefDefinitionExtensions = DataplanPg.PgRefDefinitionExtensions;
 export interface PgRefDefinition {
   graphqlType?: string;
+  sourceGraphqlType?: string;
   singular?: boolean;
   description?: string;
   extensions?: DataplanPg.PgRefDefinitionExtensions;

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

@@ -133,6 +133,7 @@ export const PgRefsPlugin: GraphileConfig.Plugin = {
             args: [name],
             params: {
               to,
+              from,
               plural: rawPlural,
               singular: rawSingular,
               via: rawVia,
@@ -154,6 +155,7 @@ export const PgRefsPlugin: GraphileConfig.Plugin = {
           refDefinitions[name] = {
             singular,
             graphqlType: to,
+            sourceGraphqlType: from,
             extensions: {
               via: rawVia,
               tags: {

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

@@ -751,19 +751,31 @@ function addRelations(
   }> = isMutationPayload
     ? []
     : codec.refs
-    ? Object.entries(codec.refs).map(([refName, spec]) => ({
-        refName,
-        refDefinition: spec.definition,
-        ref: spec,
-      }))
+    ? Object.entries(codec.refs)
+        .filter(
+          ([, spec]) =>
+            !spec.definition.sourceGraphqlType ||
+            spec.definition.sourceGraphqlType === context.Self.name,
+        )
+        .map(([refName, spec]) => ({
+          refName,
+          refDefinition: spec.definition,
+          ref: spec,
+        }))
     : Object.entries(
         codec.extensions?.refDefinitions ??
           (Object.create(null) as Record<string, never>),
-      ).map(([refName, refDefinition]) => ({
-        refName,
-        refDefinition,
-        codec,
-      }));
+      )
+        .filter(
+          ([, refDefinition]) =>
+            !refDefinition.sourceGraphqlType ||
+            refDefinition.sourceGraphqlType === context.Self.name,
+        )
+        .map(([refName, refDefinition]) => ({
+          refName,
+          refDefinition,
+          codec,
+        }));
 
   type Digest = {
     identifier: string;

postgraphile/postgraphile/__tests__/kitchen-sink-schema.sql

@@ -1364,6 +1364,7 @@ comment on table polymorphic.single_table_items is $$
   @type CHECKLIST name:SingleTableChecklist attributes:title
   @type CHECKLIST_ITEM name:SingleTableChecklistItem attributes:description,note,priority_id
   @ref rootTopic to:SingleTableTopic singular via:(root_topic_id)->polymorphic.single_table_items(id)
+  @ref rootChecklistTopic from:SingleTableChecklist to:SingleTableTopic singular via:(root_topic_id)->polymorphic.single_table_items(id)
   $$;
 
 comment on constraint single_table_items_root_topic_fkey on polymorphic.single_table_items is $$

postgraphile/postgraphile/__tests__/schema/v4/polymorphic.1.graphql

@@ -5775,6 +5775,11 @@ type SingleTableChecklist implements Node & SingleTableItem {
   personByAuthorId: Person
   position: BigInt!
 
+  """
+  Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
+  """
+  rootChecklistTopic: SingleTableTopic
+
   """
   Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
   """

postgraphile/postgraphile/__tests__/schema/v4/skipNodePlugin.polymorphic.1.graphql

@@ -5082,6 +5082,11 @@ type SingleTableChecklist implements SingleTableItem {
   personByAuthorId: Person
   position: BigInt!
 
+  """
+  Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
+  """
+  rootChecklistTopic: SingleTableTopic
+
   """
   Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
   """

postgraphile/postgraphile/__tests__/schema/v5/skipNodePlugin.polymorphic.1.graphql

@@ -6252,6 +6252,11 @@ type SingleTableChecklist implements SingleTableItem {
   personByAuthorId: Person
   position: BigInt!
 
+  """
+  Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
+  """
+  rootChecklistTopic: SingleTableTopic
+
   """
   Reads a single `SingleTableTopic` that is related to this `SingleTableChecklist`.
   """

postgraphile/website/postgraphile/refs.md

@@ -14,6 +14,7 @@ The easiest way to define a ref is with a `@ref` smart tag. The first argument t
 is the name for your reference, and then it supports the following optional parameters:
 
 - `to:` - the name of the GraphQL type we're referencing (required if `via:` is not present)
+- `from:` - the name of the GraphQL type we're applying the reference to when using polymorphism
 - `via:`- the route string (see below) through which we can reach the target
 - `singular` - present if this is a singular relationship
 - `plural` - indicates that the ref is plural (default). Not allowed if