improve handling invalid entities (#565)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: nikgraf

.changeset/eager-boxes-wash.md

@@ -0,0 +1,7 @@
+---
+"@graphprotocol/hypergraph-react": minor
+"@graphprotocol/hypergraph": minor
+---
+
+Change behavior of entity validation by filtering out invalid entities of relations and adding them to `invalidRelationEntities`
+  

.changeset/loose-candles-attack.md

@@ -0,0 +1,7 @@
+---
+"@graphprotocol/hypergraph-react": minor
+"@graphprotocol/hypergraph": minor
+---
+
+enrich `invalidEntities` to expose both the raw payload and decode error for each invalid entity
+  

.changeset/rotten-animals-hunt.md

@@ -0,0 +1,7 @@
+---
+"@graphprotocol/hypergraph-react": minor
+"@graphprotocol/hypergraph": minor
+---
+
+Entity.findOnePublic will return { entity: null, invalidEntity: { raw: {…}, error: … } } instead of throwing an error in case it's an invalid entity
+  

.changeset/shaky-guests-report.md

@@ -0,0 +1,7 @@
+---
+"@graphprotocol/hypergraph-react": patch
+"@graphprotocol/hypergraph": patch
+---
+
+Add a logInvalidResults toggle to `Entity.findOnePublic/findManyPublic`, plus pass-through support in the React provider and hooks, so apps can selectively silence or surface schema-validation warnings while still receiving the invalid payload lists.
+  

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

@@ -1,4 +1,4 @@
-import { useEntities, usePublicSpaces } from '@graphprotocol/hypergraph-react';
+import { useEntities, useEntity, usePublicSpaces } from '@graphprotocol/hypergraph-react';
 import { createLazyFileRoute } from '@tanstack/react-router';
 import { Podcast, Topic } from '@/schema';
 
@@ -22,19 +22,23 @@ function RouteComponent() {
   //   }, 1000);
   // }, []);
 
-  // const { data: podcast } = useEntity(Podcast, {
-  //   id: 'f5d27d3e-3a51-452d-bac2-702574381633',
-  //   mode: 'public',
-  //   space: space,
-  //   include: {
-  //     listenOn: {},
-  //     hosts: {
-  //       avatar: {},
-  //     },
-  //     episodes: {},
-  //   },
-  // });
-  // console.log({ podcast });
+  const {
+    data: podcast,
+    invalidEntity,
+    invalidRelationEntities,
+  } = useEntity(Podcast, {
+    id: 'f5d27d3e-3a51-452d-bac2-702574381633',
+    mode: 'public',
+    space: space,
+    include: {
+      listenOn: {},
+      hosts: {
+        avatar: {},
+      },
+      episodes: {},
+    },
+  });
+  console.log({ podcast, invalidEntity, invalidRelationEntities });
 
   const { data, isLoading, isError } = useEntities(Podcast, {
     mode: 'public',

docs/docs/query-private-data.md

@@ -50,7 +50,7 @@ Please learn more about filtering in the [Filtering query results](#filtering-qu
 useEntities for private data returns:
 
 - data - a list of entities defined in your schema
-- invalidEntities - a list of entities that are in your space storage with correct type, but can't be parsed to your schema
+- invalidEntities - each entry contains the invalid raw payload (`raw`) alongside the decode `error`
 - deleted - a list of entities that are marked as deleted, we keep them around to be able to later be able to publish the deleted information to the public knowledge graph
 
 ```ts

docs/docs/query-public-data.md

@@ -83,17 +83,18 @@ Please learn more about filtering in the [Filtering query results](#filtering-qu
 
 ### Returned data
 
-useEntities for private data returns:
+useEntities for public data returns:
 
 - data - a list of entities defined in your schema
-- invalidEntities - a list of entities that are in your space storage with correct type, but can't be parsed to your schema
+- invalidEntities - each entry includes the invalid raw payload (`raw`) plus the corresponding `error` explaining why decoding failed
+- invalidRelationEntities - each entry includes the invalid raw payload (`raw`) plus the corresponding `error` explaining why decoding failed
 - isPending - a boolean indicating if the query is loading
 - isError - a boolean indicating if the query failed
 
 In addition you have access to the full response from `@tanstack/react-query`'s `useQuery` hook, which is used internally to query the public data.
 
 ```ts
-const { data, isPending, isError } = useEntities(Event, { mode: 'public' });
+const { data, invalidEntities, invalidRelationEntities, isPending, isError } = useEntities(Event, { mode: 'public' });
 ```
 
 ## Fetching a single public entity
@@ -106,7 +107,7 @@ When you only need a single entity—for example to power a detail page—you ca
 import { useEntity } from '@graphprotocol/hypergraph-react';
 import { Project } from '../schema';
 
-const { data: project, isPending, isError } = useEntity(Project, {
+const { data: project, invalidEntity, invalidRelationEntities, isPending, isError } = useEntity(Project, {
   id: '9f130661-8c3f-4db7-9bdc-3ce69631c5ef',
   space: '3f32353d-3b27-4a13-b71a-746f06e1f7db',
   mode: 'public',

packages/hypergraph-react/src/HypergraphAppContext.tsx

@@ -124,6 +124,7 @@ export type HypergraphAppCtx = {
         error: string;
       };
   syncServerUri: string;
+  logInvalidResults: boolean;
 };
 
 export const HypergraphAppContext = createContext<HypergraphAppCtx>({
@@ -209,6 +210,7 @@ export const HypergraphAppContext = createContext<HypergraphAppCtx>({
     throw new Error('processConnectAuthSuccess is missing');
   },
   syncServerUri: '',
+  logInvalidResults: true,
 });
 
 export function useHypergraphApp() {
@@ -229,6 +231,7 @@ export type HypergraphAppProviderProps = Readonly<{
   chainId?: number;
   children: ReactNode;
   appId: string;
+  logInvalidResults?: boolean;
 }>;
 
 const mockStorage = {
@@ -245,6 +248,7 @@ export function HypergraphAppProvider({
   chainId = Connect.GEO_TESTNET.id,
   appId,
   children,
+  logInvalidResults = true,
 }: HypergraphAppProviderProps) {
   const [websocketConnection, setWebsocketConnection] = useState<WebSocket>();
   const [isConnecting, setIsConnecting] = useState(true);
@@ -1567,6 +1571,7 @@ export function HypergraphAppProvider({
         redirectToConnect: redirectToConnectForContext,
         processConnectAuthSuccess: processConnectAuthSuccessForContext,
         syncServerUri,
+        logInvalidResults,
       }}
     >
       <QueryClientProvider client={queryClient}>

packages/hypergraph-react/src/hooks/use-entities-public-infinite.ts

@@ -3,15 +3,27 @@ import { useInfiniteQuery as useInfiniteQueryTanstack } from '@tanstack/react-qu
 import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import { useHypergraphApp } from '../HypergraphAppContext.js';
 import type { QueryPublicParams } from '../internal/types.js';
 import { useHypergraphSpaceInternal } from '../internal/use-hypergraph-space-internal.js';
 
 export const useEntitiesPublicInfinite = <S extends Schema.Schema.AnyNoContext>(
   type: S,
   params?: QueryPublicParams<S>,
 ) => {
-  const { enabled = true, filter, include, space: spaceFromParams, spaces, first = 2, offset = 0 } = params ?? {};
+  const {
+    enabled = true,
+    filter,
+    include,
+    space: spaceFromParams,
+    spaces,
+    first = 2,
+    offset = 0,
+    logInvalidResults: logInvalidResultsParam,
+  } = params ?? {};
   const { space: spaceFromContext } = useHypergraphSpaceInternal();
+  const { logInvalidResults: contextLogInvalidResults = true } = useHypergraphApp();
+  const logInvalidResults = logInvalidResultsParam ?? contextLogInvalidResults ?? true;
   const space = spaceFromParams ?? spaceFromContext;
   const spaceSelectionKey = spaces ?? space;
   const typeIds = SchemaAST.getAnnotation<string[]>(Constants.TypeIdsSymbol)(type.ast as SchemaAST.TypeLiteral).pipe(
@@ -27,6 +39,7 @@ export const useEntitiesPublicInfinite = <S extends Schema.Schema.AnyNoContext>(
         ...(spaces ? { spaces } : { space }),
         first,
         offset: pageParam,
+        logInvalidResults,
       });
     },
     getNextPageParam: (_lastPage, pages) => {

packages/hypergraph-react/src/hooks/use-entities.tsx

@@ -1,5 +1,6 @@
 import type { Entity } from '@graphprotocol/hypergraph';
 import type * as Schema from 'effect/Schema';
+import { useHypergraphApp } from '../HypergraphAppContext.js';
 import { useEntitiesPrivate } from '../internal/use-entities-private.js';
 import { useEntitiesPublic } from '../internal/use-entities-public.js';
 import { useHypergraphSpaceInternal } from '../internal/use-hypergraph-space-internal.js';
@@ -26,11 +27,25 @@ type UseEntitiesParams<S extends Schema.Schema.AnyNoContext> = (
       }
     | undefined;
   backlinksTotalCountsTypeId1?: string | undefined;
+  logInvalidResults?: boolean;
 };
 
 export function useEntities<const S extends Schema.Schema.AnyNoContext>(type: S, params: UseEntitiesParams<S>) {
-  const { mode, filter, include, space, spaces, first, offset, orderBy, backlinksTotalCountsTypeId1 } = params;
+  const {
+    mode,
+    filter,
+    include,
+    space,
+    spaces,
+    first,
+    offset,
+    orderBy,
+    backlinksTotalCountsTypeId1,
+    logInvalidResults: logInvalidResultsParam,
+  } = params;
   const { space: spaceFromContext } = useHypergraphSpaceInternal();
+  const { logInvalidResults: contextLogInvalidResults = true } = useHypergraphApp();
+  const logInvalidResults = logInvalidResultsParam ?? contextLogInvalidResults ?? true;
   const resolvedSpace = space ?? spaceFromContext;
   const publicSpaceParams = spaces ? { spaces } : { space: resolvedSpace };
   const publicResult = useEntitiesPublic(type, {
@@ -42,6 +57,7 @@ export function useEntities<const S extends Schema.Schema.AnyNoContext>(type: S,
     orderBy,
     backlinksTotalCountsTypeId1,
     ...publicSpaceParams,
+    logInvalidResults,
   });
   const localResult = useEntitiesPrivate(type, { enabled: mode === 'private', filter, include, space: resolvedSpace });