graphql alias per relation + backlinks support #557

nikgraf · 2025-11-19T18:11:33Z

No description provided.

…tion alias

…ve recursion

Copilot

Pull Request Overview

This PR introduces GraphQL alias support per relation and adds backlink functionality to the hypergraph package. The changes enable more efficient querying of relations by using aliased fields in GraphQL queries, eliminating the need for client-side filtering, and adds a new Type.Backlink API for defining reverse relations.

Key changes:

Introduced Type.Backlink function and RelationBacklinkSymbol to support backlink relations
Refactored GraphQL query generation to use dynamic aliasing per relation type ID instead of multiple static query documents
Updated relation conversion logic to leverage aliased fields for improved query efficiency

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/hypergraph/src/constants.ts	Added new `RelationBacklinkSymbol` constant for marking backlink relations
packages/hypergraph/src/type/type.ts	Introduced `Backlink` function and updated `Relation` to support backlink option
packages/hypergraph/src/utils/get-relation-type-ids.ts	Refactored to return structured `RelationTypeIdInfo` objects with listField metadata
packages/hypergraph/src/utils/relation-query-helpers.ts	New utility for building GraphQL relation selections with aliases and backlink support
packages/hypergraph/src/utils/convert-relations.ts	Updated to use aliased relation fields with fallback to legacy behavior
packages/hypergraph/src/entity/find-one-public.ts	Simplified query building using dynamic relation selection helpers
packages/hypergraph/src/entity/find-many-public.ts	Consolidated multiple query variants into single dynamic query builder
packages/hypergraph/src/entity/search-many-public.ts	Refactored to use dynamic query building with relation aliases
packages/hypergraph-react/src/internal/use-entity-public.tsx	Simplified to delegate to `Entity.findOnePublic` instead of duplicating logic
packages/hypergraph-react/src/internal/use-entities-public.tsx	Removed manual relation type ID extraction, now handled internally
packages/hypergraph-react/src/hooks/use-entities-public-infinite.ts	Updated query key to use `include` parameter instead of relation type IDs
apps/events/src/schema.ts	Added example schema demonstrating backlink usage with `Episode2` and `Podcast`
apps/events/src/routes/podcasts.lazy.tsx	Updated test route with commented debugging code
.changeset/plain-turkeys-matter.md	Added changeset for the new feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-19T19:35:02Z

packages/hypergraph/src/entity/find-many-public.ts

-`;
+type RelationsListWithTotalCount = {
+  totalCount: number;
+} & RelationsListItem[];


The type definition for RelationsListWithTotalCount is incorrect. It attempts to use an intersection type (&) between an object with a totalCount property and an array type, which is invalid. Consider defining it as an array type with an additional property, or restructure the type to properly represent the API response (e.g., { totalCount: number; items: RelationsListItem[] }).

Suggested change

} & RelationsListItem[];

items: RelationsListItem[];

};

Copilot · 2025-11-19T19:35:02Z

.changeset/plain-turkeys-matter.md

+add Type.Backlink
+


The changeset description is too brief and lacks proper capitalization. Consider providing a more descriptive message that explains what the change does, such as "Add Type.Backlink support for GraphQL alias per relation and backlinks".

Suggested change

add Type.Backlink

Add Type.Backlink support for GraphQL alias per relation and backlinks.

Copilot · 2025-11-19T19:35:03Z

packages/hypergraph-react/src/internal/use-entity-public.tsx

-  }, [result.data, type]);
-
-  return { ...result, data, invalidEntity };
+  return { ...result, data: result.data || null, invalidEntity: null };


The return statement assumes result.data could be null/undefined but uses || which will also treat falsy values (like 0, false, "") as null. Consider using nullish coalescing (??) instead: data: result.data ?? null to only default on null/undefined values.

Suggested change

return { ...result, data: result.data || null, invalidEntity: null };

return { ...result, data: result.data ?? null, invalidEntity: null };

Copilot · 2025-11-19T19:35:03Z

packages/hypergraph/src/entity/search-many-public.ts


-  // @ts-expect-error TODO: fix this
-  const { data, invalidEntities } = parseResult({ entities: result.search }, type);
+  console.log('searchManyPublic result:', result);


Debug console.log statement should be removed before merging to production. This appears to be leftover debugging code.

Suggested change

console.log('searchManyPublic result:', result);

Copilot · 2025-11-19T19:35:03Z

packages/hypergraph/src/entity/find-one-public.ts

-        ? entityQueryDocumentLevel1
-        : entityQueryDocumentLevel0;
+  const queryDocument = buildEntityQuery(relationTypeIds);
+  console.log({ queryDocument });


Debug console.log statement should be removed before merging to production. This appears to be leftover debugging code.

Suggested change

console.log({ queryDocument });

Copilot · 2025-11-19T19:35:04Z

packages/hypergraph/src/entity/find-many-public.ts

+    valuesList: ValuesList;
+  } & {
+    // For nested aliased relationsList_* fields at level 2
+    [K: `relationsList_${string}`]: RelationsListWithTotalCount;


The template literal type syntax [K: \relationsList_${string}`]is incorrect. It should useinfor index signatures:[K in `relationsList_${string}`]. Without in`, this is not a valid TypeScript index signature.

Copilot · 2025-11-19T19:35:04Z

packages/hypergraph/src/utils/convert-relations.ts

+
+type RelationsListWithTotalCount = {
+  totalCount: number;
+} & RelationsListItem[];


The type definition for RelationsListWithTotalCount is incorrect. It attempts to use an intersection type (&) between an object with a totalCount property and an array type, which is invalid. Consider defining it as an array type with an additional property, or restructure the type to properly represent the API response (e.g., { totalCount: number; items: RelationsListItem[] }).

Suggested change

} & RelationsListItem[];

items: RelationsListItem[];

};

Copilot · 2025-11-19T19:35:04Z

packages/hypergraph/src/utils/convert-relations.ts

+  relationsList?: RelationsListItem[];
+} & {
+  // For aliased relationsList_* fields with proper typing
+  [K: `relationsList_${string}`]: RelationsListWithTotalCount;


The template literal type syntax [K: \relationsList_${string}`]is incorrect. It should useinfor index signatures:[K in `relationsList_${string}`]. Without in`, this is not a valid TypeScript index signature.

Suggested change

[K: `relationsList_${string}`]: RelationsListWithTotalCount;

[K in `relationsList_${string}`]: RelationsListWithTotalCount;

Copilot · 2025-11-19T19:35:05Z

packages/hypergraph/src/entity/find-many-public.ts

-  }[];
+  } & {
+    // For aliased relationsList_* fields - provides proper typing with totalCount
+    [K: `relationsList_${string}`]: RelationsListWithTotalCount;


The template literal type syntax [K: \relationsList_${string}`]is incorrect. It should useinfor index signatures:[K in `relationsList_${string}`]. Without in`, this is not a valid TypeScript index signature.

Copilot · 2025-11-19T19:35:05Z

apps/events/src/routes/podcasts.lazy.tsx

+  // useEffect(() => {
+  //   setTimeout(async () => {
+  //     const result = await Entity.searchManyPublic(Podcast, {
+  //       query: 'Joe',
+  //       space: space,
+  //       // include: {
+  //       //   listenOn: {},
+  //       // },
+  //     });
+  //     console.log('searchManyPublic result:', result);
+  //   }, 1000);
+  // }, []);
+
+  // const { data: podcast } = useEntity(Podcast, {
+  //   id: 'f5d27d3e-3a51-452d-bac2-702574381633',
+  //   mode: 'public',
+  //   space: space,
+  //   include: {
+  //     listenOn: {},
+  //     hosts: {
+  //       avatar: {},
+  //     },
+  //     episodes: {},
+  //   },
+  // });
+  // console.log({ podcast });



Large blocks of commented-out code should be removed rather than left in the codebase. If this code is needed for reference, consider preserving it in git history or documentation instead.

Suggested change

// useEffect(() => {

// setTimeout(async () => {

// const result = await Entity.searchManyPublic(Podcast, {

// query: 'Joe',

// space: space,

// // include: {

// // listenOn: {},

// // },

// });

// console.log('searchManyPublic result:', result);

// }, 1000);

// }, []);

// const { data: podcast } = useEntity(Podcast, {

// id: 'f5d27d3e-3a51-452d-bac2-702574381633',

// mode: 'public',

// space: space,

// include: {

// listenOn: {},

// hosts: {

// avatar: {},

// },

// episodes: {},

// },

// });

// console.log({ podcast });

nikgraf added 13 commits November 19, 2025 17:29

split up relations per alias

e7c206d

improve types

4c9eb40

level 2 relations should only be included in the correct level 1 rela…

6e50e90

…tion alias

useEntityPublic to use Entity.findOnePublic

7070c2d

refactor searchManyPublic to construct nested relations aliases

993c4ae

refactor findOnePublic to construct nested relations aliases

9a18176

lint fixes

8336071

cleanup relationTypeIds usage

6def3aa

use the hierarchical children data on each entry in infoLevel1 to dri…

d3fa182

…ve recursion

cleanup getRelationTypeIds

b18538d

add support for Type.Backlink

62492c6

lint fixes

530d8f9

add changeset

c5bb051

vercel bot deployed to Preview – hypergraph-connect November 19, 2025 19:21 View deployment

vercel bot deployed to Preview – hypergraph-docs November 19, 2025 19:22 View deployment

nikgraf changed the title ~~relations per alias + backlinks~~ graphql alias per relation + backlinks support Nov 19, 2025

nikgraf requested a review from Copilot November 19, 2025 19:31

Copilot started reviewing on behalf of nikgraf November 19, 2025 19:32 View session

Copilot finished reviewing on behalf of nikgraf November 19, 2025 19:33

Copilot AI reviewed Nov 19, 2025

View reviewed changes

lint fix

07c2490

vercel bot deployed to Preview – hypergraph-connect November 20, 2025 09:42 View deployment

vercel bot deployed to Preview – hypergraph-docs November 20, 2025 09:42 View deployment

nikgraf merged commit 083edfd into main Nov 20, 2025
6 checks passed

nikgraf deleted the nik/relations-per-alias branch November 20, 2025 09:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

graphql alias per relation + backlinks support #557

graphql alias per relation + backlinks support #557

Uh oh!

nikgraf commented Nov 19, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Copilot AI Nov 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	add Type.Backlink

	Add Type.Backlink support for GraphQL alias per relation and backlinks.

	return { ...result, data: result.data \|\| null, invalidEntity: null };
	return { ...result, data: result.data ?? null, invalidEntity: null };

	[K: `relationsList_${string}`]: RelationsListWithTotalCount;
	[K in `relationsList_${string}`]: RelationsListWithTotalCount;

graphql alias per relation + backlinks support #557

graphql alias per relation + backlinks support #557

Uh oh!

Conversation

nikgraf commented Nov 19, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants