Nik/include space ids (#571)

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

Author: nikgraf

.changeset/tiny-dodos-help.md

@@ -0,0 +1,7 @@
+---
+"@graphprotocol/hypergraph-react": patch
+"@graphprotocol/hypergraph": patch
+---
+
+Added `includeSpaceIds` parameter to `findOnePublic`, `findManyPublic`, `searchManyPublic`, `useEntities` and `useEntity`
+  

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

@@ -37,9 +37,14 @@ function RouteComponent() {
           valueSpaces: ['021265e2-d839-47c3-8d03-0ee3dfb29ffc', '95a4a1cc-bfcc-4038-b7a1-02c513d27700'],
         },
       },
+      skillsTotalCount: true,
     },
+    includeSpaceIds: true,
   });
   console.log({ person, personInvalidEntity, personInvalidRelationEntities });
+  if (person) {
+    console.log('person', person.skillsTotalCount);
+  }
 
   const {
     data: podcast,

docs/docs/query-public-data.md

@@ -90,7 +90,76 @@ const { data: project } = useEntity(Project, {
 - `relationSpaces` controls which spaces are searched for the relation edges themselves (`relations`/`backlinks`). Pass an array to whitelist specific spaces, `'all'` to drop the filter entirely, or `[]` if you intentionally want the branch to match nothing.
 - `valueSpaces` applies the same override to the `valuesList` lookups for the related entities. This lets you fetch relation edges from one space while trusting the canonical values that live in another.
 
-Each nested branch can have its own `_config` settings,so you can attach `_config` anywhere within the two supported include levels. Mix and match the settings per branch to stitch together data that spans multiple public spaces without issuing separate queries.
+Each nested branch can have its own `_config` settings, so you can attach `_config` anywhere within the two supported include levels. Mix and match the settings per branch to stitch together data that spans multiple public spaces without issuing separate queries.
+
+### Accessing space IDs
+
+Public entities can live in multiple spaces. Set `includeSpaceIds: true` on `useEntities`, `useEntity`, `Entity.findOnePublic`, `Entity.findManyPublic`, or `Entity.searchManyPublic` whenever you want the response entities to include a normalized (no `null` entries) `spaceIds: string[]` array. The flag defaults to `false` so responses stay small unless you opt in.
+
+#### `useEntities`
+
+```tsx
+const { data: projects } = useEntities(Project, {
+  mode: 'public',
+  space: '3f32353d-3b27-4a13-b71a-746f06e1f7db',
+  includeSpaceIds: true,
+});
+
+projects.forEach((project) => {
+  console.log(project.id, project.spaceIds); // => ["3f3235...", "95a4a1..."]
+});
+```
+
+#### `useEntity`
+
+```tsx
+const { data: project } = useEntity(Project, {
+  id: '9f130661-8c3f-4db7-9bdc-3ce69631c5ef',
+  mode: 'public',
+  space: '3f32353d-3b27-4a13-b71a-746f06e1f7db',
+  includeSpaceIds: true,
+});
+
+console.log(project?.spaceIds); // => ["3f3235..."]
+```
+
+#### `Entity.findOnePublic`
+
+```ts
+const project = await Entity.findOnePublic(Project, {
+  id: '9f130661-8c3f-4db7-9bdc-3ce69631c5ef',
+  space: '3f32353d-3b27-4a13-b71a-746f06e1f7db',
+  includeSpaceIds: true,
+});
+
+console.log(project?.spaceIds); // => ["3f3235...", "95a4a1..."]
+```
+
+#### `Entity.findManyPublic`
+
+```ts
+const { data: rounds } = await Entity.findManyPublic(InvestmentRound, {
+  spaces: ['3f32353d-3b27-4a13-b71a-746f06e1f7db', '95a4a1cc-bfcc-4038-b7a1-02c513d27700'],
+  includeSpaceIds: true,
+});
+
+rounds.map((round) => ({
+  id: round.id,
+  spaceIds: round.spaceIds,
+}));
+```
+
+#### `Entity.searchManyPublic`
+
+```ts
+const { data: searchMatches } = await Entity.searchManyPublic(Project, {
+  query: 'hypergraph',
+  space: '3f32353d-3b27-4a13-b71a-746f06e1f7db',
+  includeSpaceIds: true,
+});
+
+console.log(searchMatches[0]?.spaceIds); // => ["3f3235..."]
+```
 
 ### Querying from a specific space
 

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

@@ -2,19 +2,20 @@ 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 { type UseEntitiesPublicResult, useEntitiesPublic } from '../internal/use-entities-public.js';
 import { useHypergraphSpaceInternal } from '../internal/use-hypergraph-space-internal.js';
 
 type SpaceSelectionInputOptionInContext = {
   space?: never;
   spaces?: never;
 };
 
-type UseEntitiesParams<S extends Schema.Schema.AnyNoContext> = (
-  | Entity.SpaceSelectionInput
-  | SpaceSelectionInputOptionInContext
-) & {
-  mode: 'public' | 'private';
+type UseEntitiesParams<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined = boolean | undefined,
+  Mode extends 'public' | 'private' = 'public' | 'private',
+> = (Entity.SpaceSelectionInput | SpaceSelectionInputOptionInContext) & {
+  mode: Mode;
   filter?: Entity.EntityFilter<Schema.Schema.Type<S>> | undefined;
   // TODO: restrict multi-level nesting to the actual relation keys
   include?: Entity.EntityInclude<S> | undefined;
@@ -27,10 +28,34 @@ type UseEntitiesParams<S extends Schema.Schema.AnyNoContext> = (
       }
     | undefined;
   backlinksTotalCountsTypeId1?: string | undefined;
+  includeSpaceIds?: IncludeSpaceIds;
   logInvalidResults?: boolean;
 };
 
-export function useEntities<const S extends Schema.Schema.AnyNoContext>(type: S, params: UseEntitiesParams<S>) {
+type UseEntitiesPublicReturn<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined,
+> = UseEntitiesPublicResult<S, IncludeSpaceIds> & { deleted: [] };
+
+type UseEntitiesPrivateResult<S extends Schema.Schema.AnyNoContext> = Omit<
+  UseEntitiesPublicResult<S, false>,
+  'data'
+> & {
+  data: (Entity.Entity<S> & { backlinksTotalCountsTypeId1?: number })[];
+  deleted: Entity.Entity<S>[];
+};
+
+type UseEntitiesResult<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined,
+  Mode extends 'public' | 'private',
+> = Mode extends 'public' ? UseEntitiesPublicReturn<S, IncludeSpaceIds> : UseEntitiesPrivateResult<S>;
+
+export function useEntities<
+  const S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined = false,
+  Mode extends 'public' | 'private' = 'public',
+>(type: S, params: UseEntitiesParams<S, IncludeSpaceIds, Mode>): UseEntitiesResult<S, IncludeSpaceIds, Mode> {
   const {
     mode,
     filter,
@@ -41,21 +66,23 @@ export function useEntities<const S extends Schema.Schema.AnyNoContext>(type: S,
     offset,
     orderBy,
     backlinksTotalCountsTypeId1,
+    includeSpaceIds,
     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, {
+  const publicResult = useEntitiesPublic<S, IncludeSpaceIds>(type, {
     enabled: mode === 'public',
     filter,
     include,
     first,
     offset,
     orderBy,
     backlinksTotalCountsTypeId1,
+    ...(includeSpaceIds !== undefined ? { includeSpaceIds } : {}),
     ...publicSpaceParams,
     logInvalidResults,
   });
@@ -65,12 +92,12 @@ export function useEntities<const S extends Schema.Schema.AnyNoContext>(type: S,
     return {
       ...publicResult,
       deleted: [],
-    };
+    } as UseEntitiesResult<S, IncludeSpaceIds, Mode>;
   }
 
   return {
     ...publicResult,
     data: localResult.entities as (Entity.Entity<S> & { backlinksTotalCountsTypeId1?: number })[],
     deleted: localResult.deletedEntities,
-  };
+  } as UseEntitiesResult<S, IncludeSpaceIds, Mode>;
 }

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

@@ -2,36 +2,60 @@ import type { Entity, Id } from '@graphprotocol/hypergraph';
 import type * as Schema from 'effect/Schema';
 import { useHypergraphApp } from '../HypergraphAppContext.js';
 import { useEntityPrivate } from '../internal/use-entity-private.js';
-import { useEntityPublic } from '../internal/use-entity-public.js';
+import { type UseEntityPublicResult, useEntityPublic } from '../internal/use-entity-public.js';
 
-export function useEntity<const S extends Schema.Schema.AnyNoContext>(
-  type: S,
-  params: {
-    id: string | Id;
-    space?: string;
-    mode: 'private' | 'public';
-    include?: Entity.EntityInclude<S> | undefined;
-    logInvalidResults?: boolean;
-  },
-) {
-  const { mode, logInvalidResults: logInvalidResultsParam, ...restParams } = params;
+type UseEntityParams<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined = boolean | undefined,
+  Mode extends 'private' | 'public' = 'private' | 'public',
+> = {
+  id: string | Id;
+  space?: string;
+  mode: Mode;
+  include?: Entity.EntityInclude<S> | undefined;
+  includeSpaceIds?: IncludeSpaceIds;
+  logInvalidResults?: boolean;
+};
+
+type UseEntityPrivateResult<S extends Schema.Schema.AnyNoContext> = Omit<
+  UseEntityPublicResult<S, false>,
+  'data' | 'invalidEntity' | 'invalidRelationEntities'
+> & {
+  data: Entity.Entity<S> | undefined;
+  invalidEntity: Entity.InvalidEntity | undefined;
+  invalidRelationEntities: [];
+};
+
+type UseEntityResult<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined,
+  Mode extends 'public' | 'private',
+> = Mode extends 'public' ? UseEntityPublicResult<S, IncludeSpaceIds> : UseEntityPrivateResult<S>;
+
+export function useEntity<
+  const S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined = false,
+  Mode extends 'public' | 'private' = 'public',
+>(type: S, params: UseEntityParams<S, IncludeSpaceIds, Mode>): UseEntityResult<S, IncludeSpaceIds, Mode> {
+  const { mode, includeSpaceIds, logInvalidResults: logInvalidResultsParam, ...restParams } = params;
   const { logInvalidResults: contextLogInvalidResults = true } = useHypergraphApp();
   const logInvalidResults = logInvalidResultsParam ?? contextLogInvalidResults ?? true;
-  const resultPublic = useEntityPublic(type, {
+  const resultPublic = useEntityPublic<S, IncludeSpaceIds>(type, {
     ...restParams,
+    ...(includeSpaceIds !== undefined ? { includeSpaceIds } : {}),
     logInvalidResults,
     enabled: mode === 'public',
   });
   const resultPrivate = useEntityPrivate(type, { ...restParams, enabled: mode === 'private' });
 
   if (mode === 'public') {
-    return resultPublic;
+    return resultPublic as UseEntityResult<S, IncludeSpaceIds, Mode>;
   }
 
   return {
     ...resultPublic,
     data: resultPrivate.data,
     invalidEntity: resultPrivate.invalidEntity,
     invalidRelationEntities: [],
-  };
+  } as UseEntityResult<S, IncludeSpaceIds, Mode>;
 }

packages/hypergraph-react/src/internal/types.ts

@@ -1,6 +1,9 @@
 import type { Entity } from '@graphprotocol/hypergraph';
 import type * as Schema from 'effect/Schema';
 
-export type QueryPublicParams<S extends Schema.Schema.AnyNoContext> = {
+export type QueryPublicParams<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined = boolean | undefined,
+> = {
   enabled?: boolean | undefined;
-} & Entity.FindManyPublicParams<S>;
+} & Entity.FindManyPublicParams<S, IncludeSpaceIds>;

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

@@ -1,12 +1,31 @@
 import { Constants, Entity } from '@graphprotocol/hypergraph';
+import type { UseQueryResult } from '@tanstack/react-query';
 import { useQuery as useQueryTanstack } from '@tanstack/react-query';
 import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import type { QueryPublicParams } from './types.js';
 import { useHypergraphSpaceInternal } from './use-hypergraph-space-internal.js';
 
-export const useEntitiesPublic = <S extends Schema.Schema.AnyNoContext>(type: S, params?: QueryPublicParams<S>) => {
+type FindManyPublicResult<S extends Schema.Schema.AnyNoContext, IncludeSpaceIds extends boolean | undefined> = Awaited<
+  ReturnType<typeof Entity.findManyPublic<S, IncludeSpaceIds>>
+>;
+
+export type UseEntitiesPublicResult<
+  S extends Schema.Schema.AnyNoContext,
+  IncludeSpaceIds extends boolean | undefined,
+> = Omit<UseQueryResult<FindManyPublicResult<S, IncludeSpaceIds>, Error>, 'data'> & {
+  data: FindManyPublicResult<S, IncludeSpaceIds>['data'];
+  invalidEntities: FindManyPublicResult<S, IncludeSpaceIds>['invalidEntities'];
+  invalidRelationEntities: FindManyPublicResult<S, IncludeSpaceIds>['invalidRelationEntities'];
+};
+
+type UseEntitiesPublicFn = <S extends Schema.Schema.AnyNoContext, IncludeSpaceIds extends boolean | undefined = false>(
+  type: S,
+  params?: QueryPublicParams<S, IncludeSpaceIds>,
+) => UseEntitiesPublicResult<S, IncludeSpaceIds>;
+
+export const useEntitiesPublic: UseEntitiesPublicFn = (type, params) => {
   const {
     enabled = true,
     filter,
@@ -17,8 +36,10 @@ export const useEntitiesPublic = <S extends Schema.Schema.AnyNoContext>(type: S,
     offset,
     orderBy,
     backlinksTotalCountsTypeId1,
+    includeSpaceIds: includeSpaceIdsParam,
     logInvalidResults = true,
   } = params ?? {};
+  const includeSpaceIds = includeSpaceIdsParam ?? false;
   const { space: spaceFromContext } = useHypergraphSpaceInternal();
   const space = spaceFromParams ?? spaceFromContext;
   const spaceSelectionKey = spaces ?? space;
@@ -37,6 +58,7 @@ export const useEntitiesPublic = <S extends Schema.Schema.AnyNoContext>(type: S,
       offset,
       orderBy,
       backlinksTotalCountsTypeId1,
+      includeSpaceIds,
     ],
     queryFn: async () => {
       return Entity.findManyPublic(type, {
@@ -47,6 +69,7 @@ export const useEntitiesPublic = <S extends Schema.Schema.AnyNoContext>(type: S,
         offset,
         orderBy,
         backlinksTotalCountsTypeId1,
+        ...(includeSpaceIdsParam !== undefined ? { includeSpaceIds: includeSpaceIdsParam } : {}),
         logInvalidResults,
       });
     },