Type System Consistency

This guide explains how to ensure consistency between TypeScript types in shared-types and the GraphQL schema in shared-graphql.

Overview

The type system has three layers:

1. shared-types - Canonical TypeScript type definitions
2. shared-graphql - GraphQL schema definitions and generated types
3. Generated types - Auto-generated TypeScript from GraphQL schema using GraphQL Code Generator

Workflow

Adding a New Type

1. Define TypeScript type in packages/shared-types/src/lib/core.ts
2. Export the type from packages/shared-types/src/index.ts
3. Create GraphQL schema in packages/shared-graphql/src/schemas/
4. Add GraphQL-specific type (if needed) to packages/shared-graphql/src/types.ts for date handling
5. Run type generation: nx generate shared-graphql
6. Update schema loader in apps/web/src/lib/graphql/schema.ts
7. Implement resolvers with proper type annotations

Type Mapping

TypeScript (shared-types)	GraphQL Schema
string	String!
string | undefined	String
number	Int! or Float!
boolean	Boolean!
Date	String! (ISO format)
T[]	[T!]!
T | null	T

Date Handling

TypeScript types use Date objects; GraphQL uses ISO strings. Add GraphQL-specific types to packages/shared-graphql/src/types.ts with string dates, and use toISOString() in resolvers.

Key Files

File	Purpose
packages/shared-types/src/lib/core.ts	Canonical TypeScript types
packages/shared-graphql/src/schemas/*.graphql	GraphQL schema definitions
packages/shared-graphql/src/types.ts	GraphQL-specific types, OAuth scopes
packages/shared-graphql/src/generated/types.ts	Auto-generated resolver types
packages/shared-graphql/codegen.ts	Code generation configuration

Checklist for New Types

• TypeScript type defined in packages/shared-types
• Type exported from packages/shared-types/src/index.ts
• GraphQL schema created in packages/shared-graphql/src/schemas/
• Schema includes doc comments referencing shared-types
• Schema path added to packages/shared-graphql/codegen.ts
• GraphQL-specific type added (if dates) to packages/shared-graphql/src/types.ts
• Generate run: nx generate shared-graphql
• Schema loader updated in apps/web/src/lib/graphql/schema.ts
• Resolvers implemented with proper type annotations
• Tests added for new queries/mutations

Validation

To verify type consistency, compare:

1. The TypeScript type in packages/shared-types
2. The GraphQL type in packages/shared-graphql/src/schemas/*.graphql
3. The generated type in packages/shared-graphql/src/generated/types.ts

All three should have the same fields (accounting for Date → String conversion).