GraphQL Infrastructure

GraphQL operations provide type-safe data access through the executeGraphQL executor.

Key Files

Type	Location
Executor	`packages/core/src/infrastructure/graphql/executor.ts`
Generated Types	`packages/core/src/infrastructure/graphql/generated/operations.ts`
Operations	`packages/core/src/infrastructure/repositories/[entity]/*.graphql`

executeGraphQL Usage

import { executeGraphQL } from '../graphql/executor';
import { FindEngagementsDocument } from '../graphql/generated/operations';

// Basic usage - fully type-safe
const result = await executeGraphQL(FindEngagementsDocument, {
  where: { id: { eq: engagementId } },
});

// Admin context
const result = await executeGraphQL(SomeDocument, variables, { asAdmin: true });

// User context
const result = await executeGraphQL(SomeDocument, variables, { token: userJwt });

$where Parameter Patterns

Equality

where: { id: { eq: 'abc' } }
where: { status: { eq: 'active' } }

String Search

where: { name: { contains: 'search term' } }

In Array

where: { id: { in: ['id1', 'id2', 'id3'] } }

Relationship Filter

where: { organisation: { id: { eq: orgId } } }

AND/OR

where: {
  AND: [
    { status: { eq: 'active' } },
    { name: { contains: 'test' } }
  ]
}

All Records

where: {}

Update Input Patterns

Set Field

update: { name: { set: 'New Name' } }

Connect Relationship

connect: { organisation: { where: { node: { id: orgId } } } }

Disconnect Relationship

disconnect: { respondents: { where: { node: { id: userId } } } }

Code Generation

After creating/modifying .graphql files:

pnpm codegen

Generates:

TypeScript types for all operations
TypedDocumentNode exports
Input/output types

Best Practices

Single flexible query - use $where for all reads
Type pass-through - don't manually map types
Run codegen - after any .graphql change
Check generated types - ensure they match expectations

Type	Location
Executor	`packages/core/src/infrastructure/graphql/executor.ts`
Transaction Support	`packages/core/src/infrastructure/graphql/with-transaction.ts`
Generated Types	`packages/core/src/infrastructure/graphql/generated/`
Codegen Config	`codegen.ts`

On this page