Forem: ⛵

🥊 Decorators vs Native TS: Which Won 2026’s TypeScript GraphQL Schema Showdown? (8 Frameworks Head-to-Head)

Mon, 05 Jan 2026 16:57:35 +0000

TypeScript GraphQL Schema Framework Comparison

📊 Framework Overview

The 8 frameworks compared in this article:

Framework	Version Evaluated	Architecture Pattern
Garph	garph@0.6.8	Builder Pattern
GQLoom	@gqloom/core@0.15.0	Weaving Pattern
Grats	grats@0.0.34	Static Analysis Pattern
gqtx	gqtx@0.9.3	Builder Pattern
Nexus	nexus@1.3.0	Builder Pattern
Pothos	@pothos/core@4.12.0	Builder (Plugin-based) Pattern
Pylon	@getcronit/pylon@2.9.6	Inference Pattern
TypeGraphQL	type-graphql@2.0.0-rc.2	Decorator Pattern

1. Architecture Pattern: Zero Magic vs Code Generation

Architecture patterns determine a framework's developer experience and learning curve. We evaluate them primarily across four dimensions: dependency complexity, build process, configuration magic, and ecosystem integration.

🏆 First Tier: Zero Magic, Write and Run

GQLoom, gqtx, Pothos — these three frameworks excel in architecture patterns, tied for first place.

GQLoom: The Epitome of Minimalism

GQLoom adopts the Weaving Pattern, combining Resolvers and type definitions into a GraphQL Schema at runtime through the weave() function.

// Minimal dependencies: only depends on graphql standard library
import { weave } from '@gqloom/core'
import { ZodWeaver } from '@gqloom/zod'

const schema = weave(ZodWeaver, zodWeaverConfig, userResolver, menuResolver)
// Run directly, no build step required!

Core Advantages:

✅ Zero runtime dependencies: Only depends on graphql, no third-party libraries
✅ Pure runtime build: weave() directly generates Schema, no CLI or code generation needed
✅ Zero magic: No decorators, reflection metadata, pure native TypeScript
✅ Fully neutral: Not bound to any framework, can integrate with all GraphQL Servers

gqtx: The Exemplar of Functional API

gqtx adopts the Builder Pattern, explicitly building GraphQL Schema through a functional API.

// Equally minimal: only depends on graphql
import { Gql, buildGraphQLSchema } from 'gqtx'

const UserType = Gql.Object<User>({
  name: 'User',
  fields: () => [
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
  ],
})

const schema = buildGraphQLSchema({ query, mutation })
// Runtime build, write and run

Core Advantages:

✅ Same minimal characteristics as GQLoom
✅ Functional API is intuitive and easy to understand
✅ Type safety achieved through TypeScript generics

Pothos: Plugin-based Builder

Pothos also adopts the Builder Pattern, but adds a plugin system for modular functionality.

// Plugin-based design, install on demand
import { SchemaBuilder } from '@pothos/core'
import { ValidationPlugin } from '@pothos/plugin-validation'

const builder = new SchemaBuilder({
  plugins: [ValidationPlugin, DataloaderPlugin],
})

builder.objectType(User, {
  name: 'User',
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
})

const schema = builder.toSchema()

Core Advantages:

✅ Plugin-based architecture, core remains minimal
✅ Features installable on demand, doesn't increase core bundle size
✅ Rich plugin ecosystem (validation, DataLoader, Relay, etc.)

🥈 Second Tier: Lightweight Dependencies or Build Required

Garph: Builder Pattern, Slightly Heavier Dependencies

Garph also uses the Builder Pattern, but depends on graphql-compose and single-user-cache, increasing bundle size.

import { GarphSchema, buildSchema } from 'garph'

const g = new GarphSchema()
const UserType = g.type('User', {
  id: g.int(),
  name: g.string(),
})

const schema = buildSchema({ g, resolvers })

Characteristics:

✅ Zero magic, pure runtime build
⚠️ Depends on graphql-compose, larger bundle size
✅ Standard compatible, can integrate with all Servers

Nexus: Builder Pattern, Type Generation Almost Required

Nexus adopts the Builder Pattern. While it supports pure runtime builds, type generation is almost required for full type safety.

import { objectType, makeSchema } from 'nexus'

const User = objectType({
  name: 'User',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
  },
})

export const schema = makeSchema({
  types: [User],
  outputs: {
    typegen: './nexus-typegen.d.ts',  // Almost required configuration
  },
})

Characteristics:

✅ Minimal dependencies (only graphql + 2 lightweight libraries)
⚠️ Type generation is optional but almost required in practice
⚠️ Need to maintain generated type files

🥉 Third Tier: Special Configuration or Build Required

TypeGraphQL: Decorator Pattern

TypeGraphQL adopts the Decorator Pattern, requiring decorator and reflection metadata support.

// Must import reflect-metadata
import 'reflect-metadata'
import { ObjectType, Field, Int, buildSchema } from 'type-graphql'

@ObjectType()
export class User {
  @Field(() => Int)
  id!: number

  @Field()
  name!: string
}

const schema = await buildSchema({
  resolvers: [UserResolver],
})

Characteristics:

⚠️ Requires reflect-metadata and experimentalDecorators
⚠️ Doesn't conform to native TypeScript best practices
✅ Decorator syntax is intuitive, code readability is good

Grats: Static Analysis Pattern

Grats adopts the Static Analysis Pattern, generating Schema by analyzing JSDoc comments through the TypeScript Compiler API.

/**
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
}

/** @gqlQueryField */
export function users(): User[] {
  return Array.from(userMap.values())
}

// Must run CLI to generate Schema
// npx grats

Characteristics:

⚠️ Must run CLI command to generate Schema
⚠️ Requires extensive JSDoc comments, code is slightly verbose
✅ Uses standard JSDoc, conforms to TypeScript practices

Pylon: Inference Pattern, Deeply Bound to Framework

Pylon adopts the Inference Pattern, using TypeScript Compiler API to statically analyze source code, must run build command.

// Write TypeScript code
export const graphql = {
  Query: {
    user: (id: Int): User => { ... }
  }
}

// Must run build command
// pylon build

Characteristics:

❌ Must run build command, cannot write and run immediately
❌ Deeply bound to Hono framework, not neutral
⚠️ Depends on multiple runtime libraries, larger bundle size

📊 Architecture Pattern Comparison Summary

Framework	Rank	Dependency Complexity	Build Process	Configuration Magic	Ecosystem Integration
GQLoom	🥇	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
gqtx	🥇	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Pothos	🥇	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Garph	🥈	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Nexus	🥈	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
TypeGraphQL	🥉	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐
Grats	🥉	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Pylon	🥉	⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐

💡 Key Conclusions

Builder/Weaving patterns perform best: GQLoom, gqtx, and Pothos all achieve a perfect zero-magic, write-and-run experience.
Decorator pattern increases complexity: TypeGraphQL requires reflect-metadata and experimental features, not conforming to native TypeScript practices.
Code generation impacts developer experience: Grats and Pylon must run build commands, Nexus's type generation is almost required, all increasing maintenance costs.
Framework binding reduces flexibility: Pylon deeply integrates with Hono, not neutral, limiting use cases.

🎯 Recommendations

Pursuing minimalism and zero magic: GQLoom, gqtx, Pothos (tied for first)
Need plugin-based architecture: Pothos (rich plugin ecosystem)
Can accept lightweight dependencies: Garph (depends on graphql-compose)
Can accept type generation: Nexus (type generation almost required)
Not recommended: Pylon (framework binding), TypeGraphQL (decorator dependencies)

2. Type Definition: Which Type System is Most Elegant?

Type definitions are the core of GraphQL Schema construction, directly determining developer experience and code quality. A good type system should: zero duplication, automatic inference, native syntax.

We evaluate across four dimensions: single source of truth implementation, enum and string union support, interface inheritance experience, type inference strength.

🏆 First Tier: Native Syntax + Deep Inference

GQLoom, Pylon, Grats — these three frameworks excel in type definitions, all supporting native TypeScript syntax and powerful type inference.

GQLoom: Zod Schema as Single Source of Truth

GQLoom's biggest highlight is Zod Schema as the single source of truth, used simultaneously for TypeScript types, runtime validation, and GraphQL Schema. This is true "define once, use everywhere".

// Define once, use everywhere
export const Food = z.object({
  id: z.int(),
  name: z.string(),
  price: z.number(),
})

// TypeScript type automatically inferred
type FoodType = z.infer<typeof Food>

// Extend Schema (automatically inherits fields)
export const Coffee = Food.extend({
  sugarLevel: SugarLevel,
  origin: z.string(),
}).register(asObjectType, { interfaces: [Food] })

// Enum zero configuration
const SugarLevel = z.enum(['NONE', 'LOW', 'MEDIUM', 'HIGH'])
// Use directly, automatically converted to GraphQL Enum!

Core Advantages:

✅ True single source of truth: Zod Schema used simultaneously for types, validation, Schema
✅ Automatic field inheritance: Automatically inherits parent type fields through .extend()
✅ Enum zero configuration: Use z.enum() directly, no manual registration needed
✅ Types fully synchronized: TypeScript types and GraphQL Schema automatically synchronized

Pylon: Pure TypeScript, Automatic Inference

Pylon uses pure TypeScript syntax, automatically generating GraphQL Schema through static analysis of source code via TypeScript Compiler API.

// Pure TypeScript interface
export interface Food {
  id: Int
  name: string
  price: number
}

// Class implements interface (automatically inherits fields)
export class Coffee implements Food {
  constructor(
    public id: Int,
    public name: string,
    public price: number,
    public sugarLevel: SugarLevel,
    public origin: string,
  ) {}
}

// String union type automatically converted to enum
export type SugarLevel = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'
// Zero configuration! Automatically generates GraphQL Enum

// Union type automatically handled
export type MenuItem = Coffee | Dessert
// Automatically detects common fields, generates interface!

Core Advantages:

✅ Native TypeScript syntax: Directly use interface, class, type
✅ Smart interface detection: Union types automatically detect common fields and generate interfaces
✅ Enum zero configuration: String union types automatically converted to GraphQL Enum
✅ Deep type inference: Automatically infers types from function signatures, class properties

Grats: JSDoc Comments, Automatic Inheritance

Grats uses standard JSDoc comments to mark types, generating Schema through static analysis. Although comments are required, the syntax fully conforms to TypeScript practices.

// Define interface
export interface Food {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  price: Float
}

// Implement interface (automatically inherits fields)
export class Coffee implements Food {
  __typename = 'Coffee' as const
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  price: Float
  /** @gqlField */
  sugarLevel: SugarLevel
  /** @gqlField */
  origin: string
}

// Enum zero configuration
/**
 * @gqlEnum
 */
export type SugarLevel = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'

Core Advantages:

✅ Standard JSDoc: Uses TypeScript standard comment syntax
✅ Automatic interface inheritance: Fields automatically inherited when implementing interface
✅ Enum zero configuration: String union type + @gqlEnum comment is sufficient
✅ Complete type inference: Automatically generates Schema from TypeScript types

🥈 Second Tier: Builder API + Automatic Inheritance

Garph, Nexus, Pothos — these three frameworks all adopt Builder API. Although explicit API calls are required, interface fields can be automatically inherited, providing a good experience.

Garph: Builder API, Automatic Interface Inheritance

Garph's Builder API is elegantly designed. When implementing interfaces, only unique fields need to be defined, common fields are automatically inherited.

// Define interface
const FoodInterface = g.interface('Food', {
  id: g.int(),
  name: g.string(),
  price: g.float(),
})

// Implement interface (only need to define unique fields)
const CoffeeType = g
  .type('Coffee', {
    sugarLevel: g.ref(SugarLevelEnum),
    origin: g.string(),
  })
  .implements(FoodInterface)  // Automatically inherits id, name, price

// Enum requires as const (this is a TypeScript type inference requirement, not a framework limitation)
const SugarLevelEnum = g.enumType('SugarLevel', [
  'NONE', 'LOW', 'MEDIUM', 'HIGH'
] as const)

Core Advantages:

✅ Automatic interface inheritance: Only need to define unique fields when implementing interface
✅ Type inference: Get TypeScript types through Infer<typeof Type>
✅ Enum support: Supports as const arrays and TypeScript Enum

Nexus: Builder API, Automatic Field Inheritance

Nexus also adopts Builder API. When implementing interfaces, fields are automatically inherited, similar experience to Garph.

// Define interface
export const Food = interfaceType({
  name: 'Food',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
    t.nonNull.float('price')
  },
})

// Implement interface (only need to define unique fields)
export const Coffee = objectType({
  name: 'Coffee',
  definition(t) {
    t.implements('Food')  // Automatically inherits fields
    t.nonNull.field('sugarLevel', { type: SugarLevel })
    t.nonNull.string('origin')
  },
})

// Enum requires explicit registration
export const SugarLevel = enumType({
  name: 'SugarLevel',
  members: ['NONE', 'LOW', 'MEDIUM', 'HIGH'],
})

Core Advantages:

✅ Automatic interface inheritance: Fields automatically inherited when implementing interface
✅ Type generation: Achieve type safety through code generation
✅ Enum support: Supports string arrays, objects, TypeScript Enum

Pothos: Builder API, Powerful Type Inference

Pothos's Builder API is flexibly designed, supporting powerful type inference. Enum types can be inferred through $inferType.

// Define interface
export const Food = builder.interfaceRef<IFood>('Food').implement({
  fields: (t) => ({
    id: t.int(),
    name: t.string(),
    price: t.float(),
  }),
})

// Implement interface (only need to define unique fields)
export const Coffee = builder.objectRef<ICoffee>('Coffee').implement({
  interfaces: [Food],  // Automatically inherits fields
  fields: (t) => ({
    sugarLevel: t.field({ type: SugarLevel, resolve: (parent) => parent.sugarLevel }),
    origin: t.string({ resolve: (parent) => parent.origin }),
  }),
})

// Enum supports as const, powerful type inference
export const SugarLevel = builder.enumType('SugarLevel', {
  values: ['NONE', 'LOW', 'MEDIUM', 'HIGH'] as const,
})

// Type inference
type SugarLevelType = typeof SugarLevel.$inferType
// Result: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'

Core Advantages:

✅ Automatic interface inheritance: Fields automatically inherited when implementing interface
✅ Powerful type inference: $inferType provides complete type inference
✅ Enum support: Supports as const arrays and TypeScript Enum

🥉 Third Tier: Manual Duplication or Explicit Registration Required

gqtx, TypeGraphQL — these two frameworks require more manual work in type definitions, interface fields need to be duplicated.

gqtx: Generic Binding, But Manual Field Duplication Required

gqtx binds TypeScript types through generics, type-safe, but when implementing interfaces, all interface fields must be manually duplicated.

// Define interface
const FoodInterface = Gql.InterfaceType({
  name: 'Food',
  fields: () => [
    Gql.AbstractField({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.AbstractField({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.AbstractField({ name: 'price', type: Gql.NonNull(Gql.Float) }),
  ],
})

// Implement interface (must manually duplicate all fields)
const CoffeeType = Gql.Object<Coffee>({
  name: 'Coffee',
  interfaces: [FoodInterface],
  fields: () => [
    // ⚠️ Must manually duplicate interface fields
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.Field({ name: 'price', type: Gql.NonNull(Gql.Float) }),
    // Unique fields
    Gql.Field({ name: 'sugarLevel', type: Gql.NonNull(SugarLevelEnum) }),
    Gql.Field({ name: 'origin', type: Gql.NonNull(Gql.String) }),
  ],
})

// Enum requires manual mapping of each value
const SugarLevelEnum = Gql.Enum({
  name: 'SugarLevel',
  values: [
    { name: 'NONE', value: 'NONE' },
    { name: 'LOW', value: 'LOW' },
    { name: 'MEDIUM', value: 'MEDIUM' },
    { name: 'HIGH', value: 'HIGH' },
  ],
})

Characteristics:

✅ Type safe: Binds TypeScript types through generic <Coffee>
❌ Field duplication: Must manually duplicate all interface fields when implementing interface
❌ Enum manual mapping: Requires manual mapping of each enum value

TypeGraphQL: Decorator Syntax, Field Duplication Required

TypeGraphQL uses decorator syntax. Although intuitive, when implementing interfaces, all interface fields must be manually duplicated, and enums also require explicit registration.

// Define interface
@InterfaceType()
export abstract class Food {
  @Field(() => Int)
  id!: number

  @Field(() => String)
  name!: string

  @Field(() => Float)
  price!: number
}

// Implement interface (must manually duplicate all fields)
@ObjectType({ implements: Food })
export class Coffee implements Food {
  @Field(() => Int)      // ⚠️ Must duplicate
  id!: number

  @Field(() => String)   // ⚠️ Must duplicate
  name!: string

  @Field(() => Float)    // ⚠️ Must duplicate
  price!: number

  @Field(() => SugarLevel)
  sugarLevel!: SugarLevel

  @Field(() => String)
  origin!: string
}

// Enum must be defined first, then registered
export enum SugarLevel {
  NONE = 'NONE',
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH',
}

registerEnumType(SugarLevel, {
  name: 'SugarLevel',
})

Characteristics:

✅ Decorator syntax intuitive: Classes and decorators define Schema, code structure clear
❌ Field duplication: Must manually duplicate all interface fields when implementing interface
❌ Enum registration required: Must define enum first, then call registerEnumType() to register

📊 Type Definition Comparison Summary

Framework	Object Definition	Interface Inheritance	Enum Declaration	Type Inference
GQLoom	Zod Schema	✅ Automatic	✅ Zero config	⭐⭐⭐⭐⭐ Complete
Pylon	Native TS	✅ Automatic	✅ Zero config	⭐⭐⭐⭐ Deep
Grats	Class + JSDoc	✅ Automatic	✅ Zero config	⭐⭐⭐⭐ Deep
Garph	Builder API	✅ Automatic	⚠️ Requires `as const`	⭐⭐⭐ Type inference
Nexus	Builder API	✅ Automatic	⚠️ Explicit registration	⭐⭐⭐ Code generation
Pothos	Builder API	✅ Automatic	⚠️ Requires `as const`	⭐⭐⭐⭐ Type inference
gqtx	Builder API	❌ Manual duplication	❌ Manual mapping	⭐⭐ Generic binding
TypeGraphQL	Decorator	❌ Manual duplication	❌ Must register	⭐⭐ Decorator binding

💡 Key Conclusions

Single source of truth is king: GQLoom's Zod Schema as the single source of truth truly achieves "define once, use everywhere", this is the most elegant solution.
Native syntax provides best experience: Pylon and Grats use native TypeScript syntax (interface, class, type), lowest learning curve, best developer experience.
Automatic interface inheritance is important: Garph, Nexus, and Pothos all support automatic interface field inheritance, avoiding lots of duplicate code.
Enum zero configuration is a plus: GQLoom, Pylon, and Grats all support zero-config enums (directly use string union types or Zod Enum), while other frameworks require explicit registration or manual mapping.
Field duplication is a pain point: gqtx and TypeGraphQL require manually duplicating all interface fields when implementing interfaces, this is a clear disadvantage.

🎯 Recommendations

Pursuing ultimate single source of truth: GQLoom (Zod Schema used simultaneously for types, validation, Schema)
Pursuing native TypeScript syntax: Pylon, Grats (directly use interface, class, type)
Can accept Builder API: Garph, Nexus, Pothos (automatic interface inheritance, good experience)
Not recommended: gqtx, TypeGraphQL (require manual field duplication, high maintenance cost)

3. Resolver Definition and Input Validation: Which Makes Resolver Writing Most Elegant?

Resolvers are the core of GraphQL, directly determining the experience of writing business logic. A good resolver system should: minimal code, automatic type inference, declarative validation, native DataLoader support.

We evaluate across five dimensions: developer experience (code simplicity), modular design, parameter definition and type derivation, input validation mechanism, batch loading (DataLoader) integration.

🏆 First Tier: Minimal Code + Declarative Validation + Native DataLoader

GQLoom excels in this dimension, leading the pack! It achieves the perfect combination of chained API, validation unified with Schema, and native DataLoader support.

GQLoom: The Ultimate Chained API Experience

GQLoom's resolver system adopts a chained API design, with type definitions, validation logic, and Resolver completely unified, code is minimal and elegant.

// Chained API, type definitions unified with Resolver
export const userResolver = resolver.of(User, {
  // Query - minimal definition
  users: query(z.array(User), () => Array.from(userMap.values())),

  // Query with input - parameter types completely automatically inferred
  user: query(User)
    .input({ id: z.int() })  // Input type automatically inferred as { id: number }
    .resolve(({ id }) => {   // id's type automatically inferred as number, IDE hints perfect
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    }),

  // Mutation - validation unified with Schema definition
  createUser: mutation(User)
    .input({
      name: z.string(),
      email: z.email(),  // Validation logic directly in Schema, automatically executed
    })
    .resolve(({ name, email }) => {
      // Validation already automatically completed, use validated data directly here
      const id = incrementId()
      return { id, name, email }
    }),

  // Field Resolver with DataLoader - native support, almost no boilerplate
  orders: field(z.array(z.lazy(() => Order)))
    .load((users) => {  // Only need to define load function, no Context configuration needed
      const userOrders = new Map<number, Order[]>()
      for (const order of orderMap.values()) {
        const orders = userOrders.get(order.userId) ?? []
        orders.push(order)
        userOrders.set(order.userId, orders)
      }
      return users.map((user) => userOrders.get(user.id) ?? [])
    }),
})

Core Advantages:

✅ Chained API minimal: .input(), .resolve(), .load() methods chain configuration, code intuitive
✅ Validation unified with Schema: Validation logic (like z.email()) directly in Schema definition, automatically executed
✅ Parameter types completely automatically inferred: From .input() automatically inferred to .resolve() function parameters, IDE hints perfect
✅ DataLoader native support: Only need to define .load() function, no Context configuration or DataLoader instance creation needed
✅ Natural domain modularization: Through resolver.of(User, {...}) creates unified module boundaries, all content (Query, Mutation, Field Resolver) in one object

Complex Validation Example:

// Complex validation logic also in Schema definition, automatically executed
createOrder: mutation(Order)
  .input({
    userId: z.int().refine((id) => userMap.has(id), 'User not found'),
    items: z
      .array(z.int().refine((id) => menuMap.has(id), 'Menu item not found'))
      .min(1, 'At least one item is required'),
  })
  .resolve(({ userId, items }) => {
    // All validation logic in Schema definition, automatically executed
    // If validation fails, will automatically throw GraphQLError
  })

🥈 Second Tier: Powerful But Requires Some Configuration

Pothos, Garph — these two frameworks excel in resolver definition, each with unique characteristics.

Pothos: Plugin-based Validation + Automatic Type Inference

Pothos adopts Builder API + plugin-based validation, parameter types completely automatically inferred, validation provides declarative support through plugins.

// Query - Builder API, parameter types completely automatically inferred
builder.queryFields((t) => ({
  users: t.field({
    type: [User],
    resolve: () => Array.from(userMap.values()),
  }),
  user: t.field({
    type: User,
    args: {
      id: t.arg.int({ required: true }),
    },
    resolve: (_parent, { id }) => {  // id automatically inferred as number
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    },
  }),
}))

// Mutation - declarative validation (requires installing @pothos/plugin-validation)
builder.mutationFields((t) => ({
  createUser: t.field({
    type: User,
    args: {
      name: t.arg.string({ required: true }),
      email: t.arg.string({
        required: true,
        validate: z.email(),  // Declarative validation
      }),
    },
    resolve: (_parent, { name, email }) => {
      // Validation already automatically executed
    },
  }),
}))

// Field Resolver with DataLoader (requires installing @pothos/plugin-dataloader)
builder.objectFields(User, (t) => ({
  orders: t.loadableGroup({
    type: Order,
    load: async (userIds: number[]) => {
      return Array.from(orderMap.values())
        .filter((o) => userIds.includes(o.userId))
    },
    group: (order) => order.userId,
    resolve: (user) => user.id,
  }),
}))

Core Advantages:

✅ Parameter types completely automatically inferred: Resolver function parameter types completely automatically inferred, no manual declaration needed
✅ Declarative validation support: Provides declarative validation API through validate option (requires installing plugin)
✅ DataLoader plugin support: Provides batch loading support through plugin-dataloader
✅ Plugin-based architecture: Features installable on demand, core remains minimal
⚠️ Requires installing plugins: Validation and DataLoader require additional plugin installation and configuration
⚠️ Callback pattern increases code volume: Must use fields: (t) => ({ ... }) callback pattern, each field needs t. prefix

Garph: Native DataLoader + Automatic Parameter Inference

Garph's Resolver definition adopts explicit type annotations + automatic type inference, natively supports DataLoader, but validation requires manual implementation.

// Resolver definition (requires explicit type annotations)
const resolvers: InferResolvers<
  {
    Query: typeof queryType
    Mutation: typeof mutationType
    User: typeof UserType
  },
  {}
> = {
  Query: {
    users: () => Array.from(userMap.values()),
    user: (_, { id }) => {  // id automatically inferred as number
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    },
  },
  Mutation: {
    createUser: (_, { name, email }) => {
      // ⚠️ Need to manually write validation logic
      if (!email.includes('@')) {
        throw new GraphQLError('Invalid email format')
      }
      // ...
    },
  },
  // Field Resolver with DataLoader - native support, almost no boilerplate
  User: {
    orders: {
      load(queries) {  // Automatic batch loading, supports caching
        return Promise.resolve(
          queries.map(q => getOrdersByUserId(q.parent.id))
        )
      }
    }
  }
}

Core Advantages:

✅ Parameter type automatic inference: Automatically infers parameter types through InferResolvers, IDE support perfect
✅ DataLoader native support: Built-in DataLoader support, only need to define load function, almost no boilerplate
✅ Code concise: Resolver function definitions intuitive, easy to understand
⚠️ Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation
❌ No built-in validation: All validation logic needs to be manually written
❌ No modularization consideration: Completely organized by operation type (Query/Mutation/Type), not by domain

🥉 Third Tier: Each Has Unique Characteristics But Obvious Shortcomings

Nexus, Grats, TypeGraphQL, Pylon, gqtx — these five frameworks each have unique characteristics in resolver definition, but all have obvious shortcomings.

Nexus: Excellent Modularization, But Validation and DataLoader Require Manual Implementation

Nexus defines resolvers through Builder API, supports modular organization through extendType(), but validation and DataLoader require manual implementation.

// Query - Builder API, code concise
export const UserQuery = extendType({
  type: 'Query',
  definition(t) {
    t.nonNull.list.nonNull.field('users', {
      type: User,
      resolve: () => Array.from(userMap.values()),
    })

    t.nonNull.field('user', {
      type: User,
      args: {
        id: nonNull(intArg()),
      },
      resolve(_parent, { id }) {  // id type automatically inferred as number
        const user = userMap.get(id)
        if (!user) throw new GraphQLError('User not found')
        return user
      },
    })
  },
})

// Mutation - requires manual validation
export const UserMutation = extendType({
  type: 'Mutation',
  definition(t) {
    t.nonNull.field('createUser', {
      type: User,
      args: {
        name: nonNull(stringArg()),
        email: nonNull(stringArg()),
      },
      resolve(_parent, { name, email }) {
        // ⚠️ Need to manually call validation function
        parse(z.string().email(), email)
        // ...
      },
    })
  },
})

Core Advantages:

✅ Excellent modularization: Supports organizing code by domain modules through extendType()
✅ Parameter type automatic inference: Provides parameter types through code generation, IDE hints good
✅ Code structure clear: Builder API intuitive and easy to understand
❌ Validation requires manual implementation: Need to manually call validation functions, validation code mixed with business logic
❌ DataLoader no built-in support: Need to manually create DataLoader instances, define Context types, lots of boilerplate

Grats: Functional API Concise, But No Built-in Validation and DataLoader

Grats's Resolver definition adopts functional API + JSDoc comments, code concise and intuitive, but validation and DataLoader require manual implementation.

// Query - functional API, minimal
/** @gqlQueryField */
export function users(): User[] {
  return Array.from(userMap.values())
}

/** @gqlQueryField */
export function user(id: Int): User {  // Parameter type automatically inferred
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  return user
}

// Mutation - requires manual validation
/** @gqlMutationField */
export function createUser(name: string, email: string): User {
  // ⚠️ Need to manually write validation logic
  if (!email.includes('@')) {
    throw new GraphQLError('Invalid email format')
  }
  // ...
}

// Field Resolver
/** @gqlField */
export function orders(user: User): Order[] {
  return getOrdersByUserId(user.id)
}

Core Advantages:

✅ Functional API concise: Conforms to TypeScript best practices, code intuitive
✅ Parameter type automatic inference: Automatically infers parameter types through TypeScript type system
✅ Supports modularization: Can organize code by domain modules
⚠️ Requires JSDoc comments: Each Resolver needs JSDoc comments, code slightly verbose
❌ No built-in validation: All validation logic needs to be manually written
❌ DataLoader no built-in support: Requires manual implementation, lots of boilerplate

TypeGraphQL: Natural Domain Modularization, But Requires Many Explicit Declarations

TypeGraphQL adopts decorators + class methods, naturally supports domain modularization, but requires many decorators and explicit type declarations.

// Resolver class - natural domain modularization
@Resolver(() => User)
export class UserResolver {
  // Query - requires decorator
  @Query(() => User)
  user(@Arg('id', () => Int) id: number): User {  // Must explicitly provide type function
    const user = userMap.get(id)
    if (!user) throw new GraphQLError('User not found')
    return user
  }

  // Mutation - requires ArgsType class
  @Mutation(() => User)
  createUser(@Args(() => CreateUserArgs) { name, email }: CreateUserArgs): User {
    // Validation already automatically executed (requires configuring validateFn)
  }

  // Field Resolver - requires manual DataLoader call
  @FieldResolver(() => [Order])
  async orders(@Root() user: User, @Ctx() { loaders }: MyContext): Promise<Order[]> {
    return loaders.userOrders.load(user.id)  // Requires manual Context configuration
  }
}

// ArgsType - requires additional class definition
@ArgsType()
class CreateUserArgs {
  @Field(() => String)
  name!: string

  @Field(() => String)
  @IsEmail({}, { message: 'Invalid email format' })  // Validation decorator
  email!: string
}

Core Advantages:

✅ Natural domain modularization: Creates clear module boundaries through Resolver classes
✅ Supports declarative validation: Uses class-validator decorators to provide validation functionality
✅ Code structure clear: Classes and decorators organize code, structure clear
❌ Requires many decorators: Each parameter, each method needs decorators, code verbose
❌ Parameter types require explicit declaration: Each parameter needs @Arg('id', () => Int) explicit type declaration
❌ DataLoader no built-in support: Need to manually create DataLoader instances, define Context types, lots of boilerplate

Pylon: Functional Definition Minimal, But No Modularization and DataLoader

Pylon adopts functional Resolver + decorator validation, code minimal, parameter types completely automatically inferred, but no modularization consideration, DataLoader requires manual implementation.

// Functional definition, code minimal
export const graphql = {
  Query: {
    users: (): User[] => Array.from(userMap.values()),
    user: (id: Int): User => {  // Parameter type automatically inferred from function signature
      const u = userMap.get(id)
      if (!u) throw new GraphQLError('User not found')
      return new User(u.id, u.name, u.email)
    }
  },
  Mutation: {
    // Requires manual creation of validation decorator
    createUser: validateEmail((name: string, email: string): User => {
      const id = incrementId()
      return new User(id, name, email)
    })
  }
}

// Validation decorator requires manual implementation
const validateEmail = createDecorator(async (name: string, email: string) => {
  if (!email || !email.includes('@')) {
    throw new ServiceError('Invalid email format', {
      code: 'INVALID_EMAIL',
      statusCode: 400,
    })
  }
})

// Field Resolver - requires manual DataLoader call
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)  // Requires manual Context configuration
  }
}

Core Advantages:

✅ Code minimal: Functional definition, almost no boilerplate
✅ Parameter types completely automatically inferred: Automatically inferred from function signature, no manual declaration needed
✅ Validation decorator: Uses createDecorator to implement validation, code clear
❌ No modularization consideration: Completely organized by operation type, all Query/Mutation in one object
❌ DataLoader requires manual implementation: Need to manually create DataLoader instances, configure Context, lots of boilerplate

gqtx: Parameter Types Can Be Inferred, But No Modularization, No Validation, No DataLoader

gqtx adopts Builder API, parameter types can be automatically inferred, but requires explicit field definitions, and has no modularization, no validation, no DataLoader support.

// Query - requires explicit definition of each field
const query = Gql.Query({
  fields: () => [
    Gql.Field({
      name: 'users',
      type: Gql.NonNull(Gql.List(Gql.NonNull(UserType))),
      resolve: () => Array.from(userMap.values()),
    }),
    Gql.Field({
      name: 'user',
      type: UserType,
      args: {
        id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
      },
      resolve: (_, { id }) => {  // ✅ id type automatically inferred as number
        const user = userMap.get(id)
        if (!user) throw new GraphQLError('User not found')
        return user
      },
    }),
  ],
})

// Mutation - requires manual validation
const mutation = Gql.Mutation({
  fields: () => [
    Gql.Field({
      name: 'createUser',
      type: Gql.NonNull(UserType),
      args: {
        name: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
        email: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
      },
      resolve: (_, { name, email }) => {
        // ⚠️ Validation logic needs to be manually written
        if (!email.includes('@')) throw new GraphQLError('Invalid email format')
        // ...
      },
    }),
  ],
})

Core Advantages:

✅ Parameter type automatic inference: Resolver parameter types can be automatically inferred
✅ Type safe: Ensures resolve function signature matches type definition through conditional types
❌ Requires explicit field definitions: Each field needs explicit definition through Gql.Field(), more code volume
❌ No modularization consideration: Completely organized by operation type, all Query/Mutation in one object
❌ No built-in validation: All validation logic needs to be manually written
❌ DataLoader no built-in support: Requires manual implementation, lots of boilerplate

📊 Resolver and Validation Comparison Summary

Framework	Developer Experience	Modular Design	Parameter Inference	Validation Mechanism	DataLoader
GQLoom	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Pothos	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Garph	⭐⭐⭐⭐	⭐	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
Nexus	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐
Grats	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	⭐
TypeGraphQL	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐
Pylon	⭐⭐⭐⭐⭐	⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐
gqtx	⭐⭐⭐	⭐	⭐⭐⭐⭐	⭐⭐	⭐

💡 Key Conclusions

GQLoom leads the pack: Chained API, validation unified with Schema, native DataLoader support, achieves perfect resolver definition experience. This is the only framework that excels in all sub-dimensions.
Validation mechanism differences are huge:
- GQLoom: Validation completely unified with Schema definition, implements declarative validation through Zod Schema validation methods (like .refine(), .email())
- Pothos, TypeGraphQL: Support declarative validation, but require additional configuration (plugins or validateFn)
- Other frameworks: Require manual implementation of validation logic, validation code mixed with business logic
DataLoader support is polarized:
- Native support: GQLoom, Garph (only need to define load function, almost no boilerplate)
- Plugin support: Pothos (requires installing plugin, but API is declarative)
- No support: Other frameworks need to manually create DataLoader instances, define Context types, lots of boilerplate
Modular design differences are obvious:
- Excellent: GQLoom, TypeGraphQL (natural domain modularization, forced organization by domain)
- Good: Pothos, Nexus, Grats (support modularization, but require manual organization)
- Insufficient: Pylon, Garph, gqtx (organized by operation type, lack domain boundaries)
Parameter type inference capability:
- Completely automatic inference: GQLoom, Pothos, Pylon (parameter types completely automatically inferred, no manual declaration needed)
- Mostly automatic inference: Garph, Nexus, Grats, gqtx (parameter types mostly automatically inferred)
- Requires explicit declaration: TypeGraphQL (each parameter needs decorator explicit type declaration)

🎯 Recommendations

Pursuing ultimate developer experience: GQLoom (chained API, validation unified with Schema, native DataLoader)
Need plugin-based architecture: Pothos (rich plugin ecosystem, features installable on demand)
Need native DataLoader: GQLoom, Garph (only need to define load function, almost no boilerplate)
Need strong modularization: GQLoom, TypeGraphQL (natural domain modularization, forced organization by domain)
Pursuing functional simplicity: Pylon (functional definition minimal, but no modularization and DataLoader)
Not recommended: gqtx (no modularization, no validation, no DataLoader, weakest functionality)

4. Built-in Features: Which Has the Most Comprehensive Features?

Built-in features determine a framework's out-of-the-box readiness. We mainly focus on: Directives, Extensions, DataLoader (batch loading), Scalars (custom scalars), Subscription, Context, Middleware and other core features.

🏆 First Tier: Comprehensive Features, Rich Native Support

GQLoom, TypeGraphQL — these two frameworks have the most comprehensive built-in features, with the most natively supported functionality.

GQLoom: Native DataLoader + Native Middleware

GQLoom's biggest highlight is native DataLoader and Middleware support, an advantage that other frameworks find hard to match.

// DataLoader - native support, almost no boilerplate
orders: field(z.array(Order))
  .load((users) => {  // Only need to define load function, automatic batch processing
    const userIds = users.map(u => u.id)
    const allOrders = await db.orders.findMany({
      where: { userId: { in: userIds } }
    })
    return users.map(user => 
      allOrders.filter(o => o.userId === user.id)
    )
  })

// Middleware - native support, chained calls
posts: query(z.array(Post))
  .use(async (next) => {  // Middleware chained calls
    const start = Date.now()
    const result = await next()
    console.log(`Resolved in ${Date.now() - start}ms`)
    return result
  })
  .resolve(() => [])

Core Advantages:

✅ DataLoader native support: Only need to define .load() function, automatic batch processing and caching
✅ Middleware native support: Chain calls through .use() method, supports logging, permission checks, etc.
✅ Extensions native support: Can declare extension information like query complexity
✅ Context complete: Provides APIs like useContext(), createMemoization()
⚠️ Directives require plugin: Custom Directives definition not built-in, but can be implemented through plugins

TypeGraphQL: Directives + Middleware Native Support

TypeGraphQL provides native support for Directives and Middleware, API is concise and intuitive.

// Directives - native support
@Directive("@auth(requires: USER)")
@ObjectType()
class User {
  @Field()
  name!: string
}

// Middleware - native support
const ResolveTime: MiddlewareFn = async ({ info }, next) => {
  const start = Date.now()
  await next()
  console.log(`${info.fieldName} took ${Date.now() - start}ms`)
}

@Resolver()
class UserResolver {
  @Query()
  @UseMiddleware(ResolveTime)  // Use via decorator
  users(): User[] {
    return []
  }
}

Core Advantages:

✅ Directives native support: Through @Directive() decorator, supports federation architecture
✅ Middleware native support: Through @UseMiddleware() decorator, API concise
✅ Extensions native support: Declares extension information through @Extensions() decorator
✅ Context complete: Injects context through @Ctx() decorator, type inference perfect
❌ DataLoader no support: Need to manually create DataLoader instances, lots of boilerplate

🥈 Second Tier: Core Features Complete, Advanced Features Require Plugins

Pothos, Nexus, Grats, GQTX — these four frameworks perform well in core features, but advanced features need to be implemented through plugins or manually.

Pothos: Plugin-based Architecture, Feature Rich

Pothos adopts plugin-based architecture, core features natively supported, advanced features provided through official plugins.

// DataLoader - supported through plugin
import { DataloaderPlugin } from '@pothos/plugin-dataloader'

builder.objectFields(User, (t) => ({
  orders: t.loadableGroup({  // Declarative API
    type: Order,
    load: async (userIds) => { /* ... */ },
    group: (order) => order.userId,
  }),
}))

// Directives - supported through plugin
import { DirectivePlugin } from '@pothos/plugin-directives'

builder.queryType({
  directives: {
    rateLimit: { limit: 5, duration: 60 },
  },
})

Core Advantages:

✅ Rich plugin ecosystem: DataLoader, Directives, Complexity all have official plugins
✅ Core features complete: Context, Subscriptions, Scalars natively supported
⚠️ Requires installing plugins: Advanced features require additional plugin installation and configuration

Nexus: Core Features Complete, Advanced Features Require Manual Implementation

Nexus performs excellently in core features, but DataLoader and Middleware require manual implementation.

Core Advantages:

✅ Directives native support: Defined through directive() API
✅ Extensions native support: Can declare extension information like query complexity
✅ Context complete: Configured through contextType, type automatically inferred
❌ DataLoader no support: Need to manually create DataLoader instances
⚠️ Middleware requires plugin: Implemented through plugin system hooks

Grats: Directives Native Support

Grats's biggest highlight is Directives native support, defined through JSDoc comments, conforms to TypeScript practices.

/**
 * @gqlDirective auth(requires: USER) on OBJECT | FIELD_DEFINITION
 */
export function authDirective(args: { requires: string }) {
  // Directive implementation
}

/**
 * @gqlAnnotate @auth(requires: USER)
 */
export type User = {
  id: number
}

Core Advantages:

✅ Directives native support: Through @gqlDirective and @gqlAnnotate comments
✅ Context complete: Marks Context type through @gqlContext
❌ DataLoader no support: Requires manual implementation
❌ Middleware no support: Completely doesn't support middleware mechanism

GQTX: Core Features Complete, But Advanced Features Missing

GQTX performs well in core features, but DataLoader and Middleware are completely unsupported.

Core Advantages:

✅ Directives native support: Defined through GraphQLDirective
✅ Extensions native support: Can declare extension information
✅ Context complete: Extends GqlContext interface through modules
❌ DataLoader no support: Completely unsupported
❌ Middleware no support: Completely unsupported

🥉 Third Tier: Limited Feature Support

Garph, Pylon — these two frameworks excel in certain features, but overall feature support is limited.

Garph: Native DataLoader, But Directives Not Supported

Garph's biggest highlight is native DataLoader support, but Directives are explicitly not supported by the official documentation.

// DataLoader - native support, almost no boilerplate
User: {
  orders: {
    load(queries) {  // Automatic batch loading
      return Promise.resolve(
        queries.map(q => getOrdersByUserId(q.parent.id))
      )
    }
  }
}

Core Advantages:

✅ DataLoader native support: Only need to define load function, automatic batch processing
✅ Context complete: Specified through InferResolvers type parameter
❌ Directives not supported: Official documentation explicitly states "Currently not supported"
❌ Middleware no support: Completely unsupported

Pylon: Middleware Complete, But DataLoader No Support

Pylon provides complete Middleware support through deep integration with Hono, but DataLoader requires manual implementation.

// Middleware - using Hono middleware
app.use('*', async (c, next) => {
  const start = Date.now()
  await next()
  console.log(`Request took ${Date.now() - start}ms`)
})

// Context - native support
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')  // Requires manual configuration
    return loaders.userOrders.load(this.id)
  }
}

Core Advantages:

✅ Middleware complete: Through Hono middleware, powerful functionality
✅ Context complete: Gets context through getContext()
✅ Subscriptions support: Implemented through experimentalCreatePubSub
❌ DataLoader no support: Need to manually create DataLoader instances
⚠️ Directives require plugin: Can be implemented through Envelop plugins

📊 Built-in Features Comparison Summary

Framework	Directives	DataLoader	Middleware	Extensions	Context	Subscription
GQLoom	⚠️ Plugin	✅ Native	✅ Native	✅ Native	✅ Complete	✅ Native
TypeGraphQL	✅ Native	❌ No support	✅ Native	✅ Native	✅ Complete	✅ Native
Pothos	⚠️ Plugin	⚠️ Plugin	⚠️ Plugin	✅ Native	✅ Complete	✅ Native
Nexus	✅ Native	❌ No support	⚠️ Plugin	✅ Native	✅ Complete	✅ Native
Grats	✅ Native	❌ No support	❌ No support	⚠️ Plugin	✅ Complete	✅ Native
GQTX	✅ Native	❌ No support	❌ No support	✅ Native	✅ Complete	✅ Native
Garph	❌ Not supported	✅ Native	❌ No support	⚠️ Plugin	✅ Complete	✅ Native
Pylon	⚠️ Plugin	❌ No support	✅ Native	⚠️ Plugin	✅ Complete	✅ Native

💡 Key Conclusions

DataLoader support is polarized:
- Native support: GQLoom, Garph (only need to define load function, almost no boilerplate)
- Plugin support: Pothos (requires installing plugin, but API is declarative)
- No support: Other frameworks need to manually create DataLoader instances, lots of boilerplate
Middleware support differences are obvious:
- Native support: GQLoom, TypeGraphQL, Pylon (API concise, easy to use)
- Plugin support: Pothos, Nexus (implemented through plugin system)
- No support: Garph, Grats, GQTX (completely unsupported)
Directives support is generally good:
- Native support: TypeGraphQL, Nexus, Grats, GQTX (API intuitive)
- Plugin support: GQLoom, Pothos, Pylon (can be implemented through plugins)
- Not supported: Garph (officially explicitly not supported)
Core features are generally complete: All frameworks perform well in core features like Context, Subscriptions, Scalars, differences mainly in advanced features.

🎯 Recommendations

Need native DataLoader: GQLoom, Garph (only need to define load function, almost no boilerplate)
Need native Middleware: GQLoom, TypeGraphQL, Pylon (API concise, easy to use)
Need Directives: TypeGraphQL, Nexus, Grats, GQTX (native support, API intuitive)
Need complete feature ecosystem: GQLoom (DataLoader + Middleware native support, most comprehensive features)
Need plugin-based architecture: Pothos (rich plugin ecosystem, features installable on demand)

5. Ecosystem Integration: Which Works Best with the Toolchain?

Ecosystem integration determines a framework's long-term maintainability. An excellent framework should seamlessly collaborate with mainstream tools in the TypeScript ecosystem, eliminate "glue code", and build end-to-end type-safe chains.

We mainly focus on four dimensions: ORM integration depth (can directly reuse model definitions), validation library integration (whether validation logic is unified with Schema), GraphQL Server compatibility (can flexibly choose underlying implementation), toolchain integration (runtime environment and build tool support).

🏆 First Tier: Deep Integration, Zero Boilerplate

GQLoom excels in ecosystem integration, achieving perfect fusion with mainstream toolchains.

GQLoom: Official Plugins Full Coverage

GQLoom achieves deep integration with ORM and validation libraries through the official plugin system, types fully synchronized, zero boilerplate.

// ORM integration - Prisma, Drizzle, MikroORM all have official plugins
import { PrismaResolverFactory } from "@gqloom/prisma"
import { drizzleResolverFactory } from "@gqloom/drizzle"

// Prisma - directly reuse models, automatically generate queries
const userResolver = new PrismaResolverFactory(User, db).resolver()

// Drizzle - also zero configuration
const catResolver = drizzleResolverFactory(db, "cats")

// Validation library integration - Zod, Valibot, Yup natively supported
import { ZodWeaver } from '@gqloom/zod'

// Zod Schema used simultaneously for types, validation, GraphQL Schema
export const Food = z.object({
  id: z.int(),
  name: z.string(),
  price: z.number(),
})

const schema = weave(ZodWeaver, zodWeaverConfig, userResolver)

Core Advantages:

✅ ORM deep integration: Prisma, Drizzle, MikroORM official plugins, directly reuse model definitions, types fully synchronized
✅ Validation library seamless integration: Zod, Valibot, Yup natively supported, validation logic completely unified with Schema definition
✅ Server fully compatible: Outputs standard GraphQL Schema, can integrate with all mainstream Servers
✅ Zero boilerplate: All integrations implemented through official plugins, no need to manually write glue code

🥈 Second Tier: Rich Plugin Ecosystem, Smooth Integration

Pothos achieves deep integration with mainstream tools through a powerful plugin system.

Pothos: Plugin-based Integration, Features Installable on Demand

Pothos has a very rich plugin ecosystem, ORM and validation libraries all have official plugin support.

// ORM integration - Prisma, Drizzle official plugins
import { PrismaPlugin } from '@pothos/plugin-prisma'
import { DrizzlePlugin } from '@pothos/plugin-drizzle'

builder.prismaObject('User', {
  fields: (t) => ({
    id: t.exposeID('id'),
    posts: t.relation('posts'),  // Automatically handles relation queries
  }),
})

// Validation library integration - Zod official plugin
import { ValidationPlugin } from '@pothos/plugin-validation'

builder.mutationFields((t) => ({
  createUser: t.field({
    args: {
      email: t.arg.string({
        validate: z.email(),  // Declarative validation
      }),
    },
  }),
}))

Core Advantages:

✅ ORM deep integration: Prisma, Drizzle official plugins, types fully synchronized
✅ Validation library seamless integration: Zod official plugin, validation logic unified with Schema definition
✅ Server fully compatible: Outputs standard GraphQL Schema, can integrate with all mainstream Servers
⚠️ Requires installing plugins: Although feature-rich, requires installing and configuring plugins on demand

🥉 Third Tier: Some Integrations Good, Some Require Manual Configuration

TypeGraphQL, Nexus, Grats — these three frameworks perform well in some integrations, but overall require more manual work.

TypeGraphQL: Validation Library Deeply Bound, ORM Requires Manual Configuration

TypeGraphQL is deeply bound to class-validator, validation experience excellent, but ORM integration requires manual configuration.

// Validation library integration - class-validator deeply bound
@ArgsType()
class CreateUserArgs {
  @Field(() => String)
  @IsEmail({}, { message: 'Invalid email format' })  // Validation decorator
  email!: string
}

// ORM integration - requires manual use of ORM API
@Resolver(() => User)
class UserResolver {
  @Query(() => User)
  async user(@Arg('id') id: number) {
    return await prisma.user.findUnique({ where: { id } })  // Manual query
  }
}

Characteristics:

✅ Validation library deep integration: class-validator deeply bound, validation logic integrated with Schema
⚠️ ORM requires manual configuration: TypeORM, Prisma require manual use of ORM API, cannot automatically generate queries
✅ Server fully compatible: Outputs standard GraphQL Schema

Nexus: Prisma Plugin Support, Validation Requires Manual Implementation

Nexus provides Prisma plugin support, but validation library requires manual implementation.

// ORM integration - Prisma plugin support
import { nexusPrisma } from 'nexus-plugin-prisma'

const schema = makeSchema({
  plugins: [nexusPrisma()],
  // But still need to manually write Resolver logic
})

// Validation library integration - requires manual call to validation function
resolve(_parent, { email }) {
  parse(z.string().email(), email)  // Manual validation
}

Characteristics:

✅ Prisma plugin support: Provides official plugin, but requires manually writing query logic
⚠️ Validation requires manual implementation: Need to manually call validation functions, validation code mixed with business logic
✅ Server fully compatible: Outputs standard GraphQL Schema

Grats: Excellent Server Compatibility, ORM and Validation Require Manual Integration

Grats performs excellently in GraphQL Server compatibility, but ORM and validation libraries require manual integration.

Characteristics:

✅ Server fully compatible: Outputs standard GraphQL Schema, official examples cover Apollo Server, GraphQL Yoga, Express GraphQL HTTP
❌ ORM requires manual integration: No official plugins, need to manually write all database query logic
❌ Validation requires manual implementation: All validation logic needs to be manually written in Resolver

📊 Other Frameworks: Limited Integration Capabilities

GQTX, Garph, Pylon — these three frameworks perform weakly in ecosystem integration, requiring lots of manual work.

GQTX, Garph: Standard Compatible, But Integration Requires Manual

Both frameworks output standard GraphQL Schema, Server compatibility good, but ORM and validation library integration requires manual implementation, lots of glue code needed.

Characteristics:

✅ Server standard compatible: Outputs standard GraphQL Schema, can integrate with all mainstream Servers
❌ ORM no official plugins: Need to manually write all database query logic, type synchronization requires manual maintenance
❌ Validation requires manual implementation: Validation logic separated from Schema definition, lots of boilerplate needed

Pylon: Framework Binding Severe, Flexibility Limited

Pylon is deeply bound to Hono and GraphQL Yoga. Although it supports Prisma and Drizzle, framework binding limits use cases.

Characteristics:

⚠️ ORM basic integration: Supports Prisma and Drizzle, but requires manual integration
❌ Validation library no integration: Need to manually implement all validation logic
❌ Server binding severe: Forced binding to GraphQL Yoga, cannot change underlying Server
❌ Framework binding: Deeply integrated with Hono, not neutral, limits flexibility

📊 Ecosystem Integration Comparison Summary

Framework	ORM Integration	Validation Library Integration	Server Compatibility	Toolchain Integration
GQLoom	✅ Deep integration	✅ Seamless integration	✅ Fully compatible	✅ Complete
Pothos	✅ Deep integration	✅ Seamless integration	✅ Fully compatible	⚠️ Basic support
TypeGraphQL	⚠️ Manual config	✅ Deep integration	✅ Fully compatible	⚠️ Basic support
Nexus	⚠️ Plugin support	⚠️ Manual implementation	✅ Fully compatible	⚠️ Basic support
Grats	❌ Manual integration	❌ Manual implementation	✅ Fully compatible	⚠️ Basic support
GQTX	❌ Manual integration	❌ Manual implementation	⚠️ Standard compatible	⚠️ Basic support
Garph	❌ Manual integration	❌ Manual implementation	⚠️ Standard compatible	⚠️ Basic support
Pylon	⚠️ Basic integration	❌ No integration	❌ Bound to Yoga	❌ Strongly bound to Hono

💡 Key Conclusions

GQLoom has the most complete ecosystem integration: Achieves deep integration with ORM and validation libraries through official plugins, types fully synchronized, zero boilerplate, this is an advantage other frameworks find hard to match.
Pothos has rich plugin ecosystem: Although requires installing plugins, provides official plugins like Prisma, Drizzle, Zod, integration experience excellent.
Validation library integration differences are huge:
- Seamless integration: GQLoom, Pothos (validation logic completely unified with Schema definition)
- Deep integration: TypeGraphQL (class-validator deeply bound)
- Requires manual implementation: Other frameworks need to manually write validation logic
ORM integration is polarized:
- Deep integration: GQLoom, Pothos (official plugins, type synchronization, zero boilerplate)
- Requires manual configuration: Other frameworks need to manually use ORM API, type synchronization requires manual maintenance
Server compatibility is generally good: Except for Pylon binding to GraphQL Yoga, other frameworks all output standard GraphQL Schema, can integrate with all mainstream Servers.
Toolchain integration is generally limited: All frameworks mainly support TypeScript and Node.js, support for other runtimes (Bun, Deno, Cloudflare Workers) and build tools (webpack, vite, rspack) is limited, requires users to verify and configure themselves.

🎯 Recommendations

Pursuing perfect ecosystem integration: GQLoom (ORM and validation library deep integration, zero boilerplate)
Need plugin-based architecture: Pothos (rich plugin ecosystem, features installable on demand)
Using class-validator: TypeGraphQL (validation library deeply bound, excellent experience)
Need Server flexibility: GQLoom, Pothos, TypeGraphQL, Nexus, Grats (standard compatible, can freely choose Server)
Not recommended: Pylon (framework binding severe, flexibility limited)

📝 Summary: Which is the Best Choice?

After comprehensive comparison across five dimensions, we found:

🏆 Best Overall Performance: GQLoom

GQLoom excels in all five dimensions: architecture patterns, type definitions, resolvers and validation, built-in features, and ecosystem integration, especially leading the pack in resolver definition and ecosystem integration. It achieves the perfect combination of zero magic, write-and-run, validation unified with Schema, native DataLoader support, and ORM deep integration.

🥈 Plugin-based Architecture First Choice: Pothos

Pothos achieves a balance between minimal core and rich features through plugin-based architecture, performs excellently in type definitions, resolver definitions, and ecosystem integration, suitable for projects that need flexible expansion.

🥉 Decorator Pattern Representative: TypeGraphQL

TypeGraphQL performs excellently in core features and validation library integration, suitable for teams that prefer decorator syntax.

Other frameworks each have unique characteristics:

Garph: Native DataLoader support, but feature support limited
Nexus: Excellent modularization, but requires type generation
Grats: Native TypeScript syntax, but requires build step
Pylon: Automatic type inference, but framework binding severe
gqtx: Minimal dependencies, but feature support weakest

Final Recommendation: If you pursue ultimate developer experience and perfect ecosystem integration, GQLoom is the best choice. If you need plugin-based architecture and rich feature ecosystem, Pothos is a great choice. If you prefer decorator syntax, TypeGraphQL is worth considering.

When choosing a framework, it's recommended to make the most suitable choice based on your project's specific needs (whether ORM integration is needed, whether validation library integration is needed, whether native DataLoader is needed, etc.).

Hope this comparison article helps you find the GraphQL Schema building framework that best fits your project! If you have any questions or suggestions, welcome to discuss in the comments section.

TypeGraphQL Evaluation Report

Mon, 05 Jan 2026 14:08:07 +0000

📋 Basic Information

Item	Content
Current Version	2.0.0-rc.2
GitHub	https://github.com/MichalLytek/type-graphql
Documentation	https://typegraphql.com
First Commit	2018-01-09
Latest Commit	2026-01-01

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture	3.0	Decorator pattern, moderate dependencies, lightweight build, feature-dependent, good integration
2. Type Definition	2.0	Logical association, explicit registration, logical resolution, strong binding, extensive explicit declarations
3. Resolvers & Validation	2.6	Natural domain modularization, but extensive explicit declarations, no built-in DataLoader support
4. Built-in Features	3.6	Core features complete, but DataLoader and depth limiting have no built-in support
5. Ecosystem Integration	3.5	GraphQL Server fully compatible, validation library deeply integrated, ORM requires manual configuration

1. Architecture

Architecture Pattern Type

Decorator Pattern: TypeGraphQL adopts a class and decorator-based architecture pattern. Decorators (such as @ObjectType, @Field, @Resolver) collect metadata when classes are defined, and then buildSchema() converts the metadata into a standard GraphQL Schema at runtime. This pattern depends on TypeScript decorators and the reflect-metadata reflection library.

Core Implementation Mechanism

Source Code Evidence:

Metadata storage: type-graphql/src/metadata/metadata-storage.ts (lines 38-410) defines the MetadataStorage class for collecting and storing all decorator metadata
Metadata retrieval: type-graphql/src/metadata/getMetadataStorage.ts (lines 8-14) uses the global variable global.TypeGraphQLMetadataStorage to store metadata
Schema building: The buildSchema() function in type-graphql/src/utils/buildSchema.ts (lines 57-66) calls SchemaGenerator.generateFromMetadata() to build the Schema
Schema generator: The generateFromMetadata() method in type-graphql/src/schema/schema-generator.ts (lines 124-157) generates the GraphQL Schema from metadata
Decorator implementation: type-graphql/src/decorators/ObjectType.ts (lines 11-30) and Field.ts (lines 12-64) demonstrate how decorators collect metadata
Business code example: typescript-graphql-schemas/typegraphql/src/schema.ts (lines 10-23) calls buildSchema() to build the Schema

Build Flow:

// 1. Must import reflect-metadata (at the top of entry file)
import 'reflect-metadata'

// 2. Use decorators to define types and Resolvers
@ObjectType()
export class User {
  @Field(() => Int)
  id!: number
}

@Resolver(() => User)
export class UserResolver {
  @Query(() => [User])
  users(): User[] { ... }
}

// 3. Build Schema at runtime (decorators have already collected metadata when classes were loaded)
const schema = await buildSchema({
  resolvers: [UserResolver],
})

Scoring Details

1.1 Dependency Complexity

Score: 3.0

Evidence:

Required dependencies (type-graphql/package.json lines 99-108):
- graphql: ^16.12.0 - GraphQL standard library (peer dependency)
- reflect-metadata: 0.1.13 - Reflection metadata library (in devDependencies, but business code must import)
Optional dependencies (package.json lines 100-107):
- class-validator: >=0.14.3 - Validation library (peer dependency, optional)
- graphql-scalars: ^1.25.0 - Scalar types library (peer dependency, optional)
Runtime dependencies (package.json lines 109-115):
- @graphql-yoga/subscription: ^5.0.5 - Subscription support
- graphql-query-complexity: ^1.1.0 - Query complexity analysis
- semver: ^7.7.3 - Version checking
- tslib: ^2.8.1 - TypeScript runtime library

Actual Usage (typescript-graphql-schemas/typegraphql/src/schema.ts line 1):

import 'reflect-metadata'  // Must import
import { buildSchema } from 'type-graphql'
import { validate } from 'class-validator'  // Optional, for validation

TypeScript Configuration Requirements:

Must enable experimentalDecorators: true
Must enable emitDecoratorMetadata: true
Requires ES5+ target (decorators need class support)

Analysis:

⚠️ Must depend on reflect-metadata, increasing runtime overhead and configuration complexity
⚠️ Requires TypeScript decorator support, must configure experimentalDecorators
✅ Core runtime dependencies are minimal (mainly graphql and reflect-metadata)
✅ class-validator is an optional dependency, use as needed
⚠️ Compared to pure functional APIs (like Pothos, Nexus), the decorator pattern requires more configuration

Conclusion: Moderate dependencies. Requires introducing a reflection library (reflect-metadata) and TypeScript decorator support, but core dependencies are relatively lightweight. Compared to zero-dependency solutions, this adds configuration and runtime overhead.

1.2 Build Flow

Score: 4.0

Evidence:

Pure runtime build: The buildSchema() function in type-graphql/src/utils/buildSchema.ts (lines 57-66) executes at runtime
Metadata collection: Decorators automatically collect metadata into global storage when classes are defined (when modules are loaded) (type-graphql/src/metadata/getMetadataStorage.ts lines 8-14)
No code generation: Business code (typescript-graphql-schemas/typegraphql/src/schema.ts) runs TypeScript directly, no pre-build steps required
Optional Schema file generation: buildSchema() supports the emitSchemaFile option to generate GraphQL SDL files (type-graphql/src/utils/buildSchema.ts lines 60-62)

Actual Usage:

// typescript-graphql-schemas/typegraphql/src/schema.ts
import 'reflect-metadata'
import { buildSchema } from 'type-graphql'
import { UserResolver } from './resolvers/user.resolver.ts'

export const schema = await buildSchema({
  resolvers: [UserResolver, MenuResolver, OrderResolver],
  // Optional: generate schema.graphql file
  emitSchemaFile: './schema.graphql',
})
// Run directly, no build steps required

Metadata Collection Mechanism:

// Decorators automatically execute when classes are defined
@ObjectType()
export class User {
  @Field(() => Int)
  id!: number
  // Decorator calls getMetadataStorage().collectClassFieldMetadata()
  // Metadata is stored in global.TypeGraphQLMetadataStorage
}

Official Example Verification (type-graphql/examples/simple-usage/index.ts lines 10-15):

const schema = await buildSchema({
  resolvers: [RecipeResolver],
  emitSchemaFile: path.resolve(__dirname, "schema.graphql"),
})
// No build steps required, run directly

Analysis:

✅ Pure runtime build, developers can run code directly after writing
✅ Decorators automatically collect metadata when classes are loaded, no manual registration needed
✅ Supports hot reload (e.g., node --watch), good development experience
✅ Optional Schema file generation for review and debugging
⚠️ Must ensure reflect-metadata is imported before decorators are used (usually at the top of entry file)

Conclusion: Lightweight build. Supports runtime build with no code generation steps. Decorators automatically collect metadata when classes are loaded, making the build process transparent. The only requirement is that reflect-metadata must be imported in the entry file.

1.3 Config & Language Magic

Score: 2.0

Evidence:

Must enable decorators: Requires TypeScript configuration experimentalDecorators: true and emitDecoratorMetadata: true
Must import reflect-metadata: All files using decorators must import import 'reflect-metadata' at the top of the entry file (typescript-graphql-schemas/typegraphql/src/schema.ts line 1)
Depends on reflection metadata: Decorators obtain type information through Reflect.getMetadata() (type-graphql/src/decorators/Field.ts lines 34-40)
Global metadata storage: Uses global.TypeGraphQLMetadataStorage to store metadata (type-graphql/src/metadata/getMetadataStorage.ts lines 5-13)

TypeScript Configuration Requirements:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES5"  // or higher, needs class support
  }
}

Actual Usage:

// Must import reflect-metadata (at the top of entry file)
import 'reflect-metadata'

// Use decorators to define types
@ObjectType()
export class User {
  @Field(() => Int)
  id!: number
}

// Decorators depend on reflection metadata to obtain type information
// Field decorator obtains field type through Reflect.getMetadata('design:type', ...)

Decorator Implementation Details (type-graphql/src/decorators/Field.ts lines 34-40):

const { getType, typeOptions } = findType({
  metadataKey: isResolverMethod ? "design:returntype" : "design:type",
  prototype,
  propertyKey,
  returnTypeFunc,
  typeOptions: options,
})
// Depends on Reflect.getMetadata() to obtain type metadata

Analysis:

⚠️ Must enable TypeScript experimental features (experimentalDecorators), not aligned with native TS best practices
⚠️ Must import reflect-metadata, increasing configuration burden
⚠️ Depends on runtime reflection mechanism, type information obtained at runtime rather than compile time
⚠️ Global metadata storage may cause module loading order issues
✅ Decorator syntax is intuitive, code readability is good
✅ Type inference works automatically through reflection metadata, no explicit declarations needed

Conclusion: Feature-dependent. Must enable TS experimental features (experimentalDecorators) and manually configure the reflection environment. Depends on runtime reflection mechanism to obtain type information, not aligned with native TypeScript best practices.

1.4 Ecosystem Integration

Score: 4.0

Evidence:

Standard installation: npm install type-graphql can be used directly, no special requirements
Server compatibility: buildSchema() returns a standard GraphQLSchema object (type-graphql/src/utils/buildSchema.ts line 57), can integrate with any GraphQL Server
Diverse official examples (type-graphql/examples/ directory):
- simple-usage: Apollo Server integration example
- apollo-federation, apollo-federation-2: Apollo Federation integration
- nestjs: NestJS framework integration
- graphql-yoga: GraphQL Yoga integration (via standard Schema)
Frontend support: Provides shim.ts for frontend environments (type-graphql/src/shim.ts lines 1-75), prevents decorator errors in frontend
Business code integration: typescript-graphql-schemas/typegraphql/src/schema.ts directly exports schema, can integrate with any GraphQL Server

Official Example (type-graphql/examples/simple-usage/index.ts lines 18-22):

const schema = await buildSchema({
  resolvers: [RecipeResolver],
})

const server = new ApolloServer({ schema })
// Standard GraphQL Schema, compatible with all GraphQL Servers

Frontend Shim Support (type-graphql/src/shim.ts lines 35-75):

// Provides empty decorator implementations for frontend environments
export const ObjectType: typeof src.ObjectType = dummyDecorator
export const Field: typeof src.Field = dummyDecorator
// Prevents frontend environment errors

ORM Integration Examples (type-graphql/examples/ directory):

typeorm-basic-usage: TypeORM integration
typeorm-lazy-relations: TypeORM lazy relations
mikro-orm: MikroORM integration
typegoose: Typegoose integration

Dependency Injection Container Integration (type-graphql/examples/ directory):

tsyringe: TSyringe integration
using-container: Generic container integration
using-scoped-container: Scoped container integration

Analysis:

✅ Standard npm package, can be freely integrated into any project
✅ Outputs standard GraphQL Schema, compatible with all GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, Hono, etc.)
✅ Not bound to specific frameworks, flexible choice of underlying implementation
✅ Provides frontend Shim, supports code sharing between frontend and backend
✅ Official provides rich integration examples, demonstrating integration with various frameworks and ORMs
⚠️ Must ensure runtime environment supports decorators and reflection metadata (Node.js environment usually supports)

Conclusion: Good integration. Standard installation process, excellent compatibility with mainstream GraphQL Servers and bundlers. Provides frontend Shim support, official examples are rich, demonstrating integration with various frameworks and ORMs.

Architecture Overall Score

Score: 3.0

Scoring Basis:

Dependency complexity: 3.0 (Moderate dependencies, requires reflect-metadata and decorator support)
Build flow: 4.0 (Lightweight build, pure runtime build, decorators automatically collect metadata)
Config & language magic: 2.0 (Feature-dependent, must enable experimental decorators and reflection environment)
Ecosystem integration: 4.0 (Good integration, standard compatibility, rich integration examples)

Advantages:

Intuitive decorator syntax: Uses classes and decorators to define Schema, code structure is clear
Automatic metadata collection: Decorators automatically collect metadata when classes are loaded, no manual registration needed
Runtime build: Pure runtime build, supports hot reload, good development experience
Type inference: Automatically infers types through reflection metadata, reducing explicit declarations
Rich ecosystem: Official provides many integration examples, demonstrating integration with various frameworks and ORMs
Frontend support: Provides Shim for frontend environments, supports code sharing between frontend and backend

Disadvantages:

Depends on reflection library: Must import reflect-metadata, increasing runtime overhead
Experimental features: Must enable TypeScript decorators, not aligned with native TS best practices
Configuration burden: Need to configure experimentalDecorators and emitDecoratorMetadata
Global state: Uses global metadata storage, may cause module loading order issues
Type safety: Depends on runtime reflection to obtain type information, not compile-time type checking

2. Type Definition

Core Implementation Mechanism

TypeGraphQL uses a decorator + reflection metadata approach to implement type definitions. TypeScript class definitions are marked with GraphQL Schema information through decorators (@ObjectType, @Field, @InterfaceType, etc.), metadata is stored in global storage, and then GraphQL Schema is generated at runtime through buildSchema(). Type inference depends on reflect-metadata's design:type and design:returntype metadata, but in most cases explicit type functions must be provided.

Source Code Evidence:

Type lookup: The findType() function in type-graphql/src/helpers/findType.ts (lines 39-91) obtains type information through Reflect.getMetadata()
Metadata keys: type-graphql/src/helpers/findType.ts (line 12) defines MetadataKey = "design:type" | "design:returntype" | "design:paramtypes"
Field decorator: type-graphql/src/decorators/Field.ts (lines 34-40) calls findType() to obtain type information
Business code example: typescript-graphql-schemas/typegraphql/src/resolvers/user.type.ts (lines 4-17) uses decorators to define types

Scoring Details

2.1 Single Source of Truth Implementation

Score: 3.0

Evidence:

TypeScript class definition is the data source: typescript-graphql-schemas/typegraphql/src/resolvers/user.type.ts (lines 4-17) defines TypeScript types through classes
Requires manual decorator marking: Each field needs a @Field(() => Type) decorator, creating duplicate declarations
GraphQL Schema auto-generated: buildSchema() generates GraphQL Schema from decorator metadata (type-graphql/src/utils/buildSchema.ts lines 57-66)
Limited type inference: Basic types can be inferred through reflection metadata, but arrays, Promises, and complex types require explicit type functions

Code Example:

// TypeScript class definition (data source)
@ObjectType()
export class User {
  @Field(() => Int)  // Must explicitly provide type function
  id!: number

  @Field(() => String)  // Must explicitly provide type function
  name!: string

  @Field(() => [Order])  // Array types must be explicitly provided
  orders!: Order[]
}

// GraphQL Schema auto-generated (from decorator metadata)
const schema = await buildSchema({
  resolvers: [UserResolver],
})

Type Inference Mechanism (type-graphql/src/helpers/findType.ts lines 51-62):

const reflectedType: Function[] | Function | undefined = Reflect.getMetadata(
  metadataKey,  // "design:type" or "design:returntype"
  prototype,
  propertyKey,
)
// If reflection metadata exists and is not a banned type, it can be used
// But in most cases, returnTypeFunc must be explicitly provided

Actual Usage Statistics (typescript-graphql-schemas/typegraphql/src):

All fields require explicit type functions () => Type
29 field decorator calls, all use explicit type functions
No fields depend on pure reflection metadata inference

Analysis:

⚠️ TypeScript type definitions and GraphQL Schema definitions need manual synchronization (through decorators)
⚠️ Each field requires an explicit type function, creating duplicate declarations
✅ Decorators bind TypeScript types with GraphQL Schema, maintaining type linkage
⚠️ Limited type inference capability: basic types can be inferred, but arrays, Promises, and complex types must be explicitly declared
⚠️ Cannot auto-generate types from validation rules, requires manual maintenance synchronization

Conclusion: Logical association. TS types and Schema definitions are bound through decorators and other means. Although there is some duplication, type linkage is maintained. Type inference capability is limited, and in most cases explicit type functions must be provided.

2.2 Enum & String Union Support

Score: 3.0

Evidence:

Must manually register: typescript-graphql-schemas/typegraphql/src/resolvers/menu.type.ts (lines 19-21) uses registerEnumType() to register enums
Cannot directly use TypeScript enums: Must first define the enum, then call registerEnumType() to register (type-graphql/src/decorators/enums.ts lines 4-14)
Type safe: Registered enums can be used in decorators, type safe (typescript-graphql-schemas/typegraphql/src/resolvers/menu.type.ts line 48)

Code Example:

// 1. Define TypeScript enum
export enum SugarLevel {
  NONE = 'NONE',
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH',
}

// 2. Must manually register (cannot use directly)
registerEnumType(SugarLevel, {
  name: 'SugarLevel',
})

// 3. Use in type definitions
@ObjectType()
export class Coffee {
  @Field(() => SugarLevel)  // Type safe
  sugarLevel!: SugarLevel
}

Implementation Mechanism (type-graphql/src/decorators/enums.ts lines 4-14):

export function registerEnumType<TEnum extends object>(
  enumObj: TEnum,
  enumConfig: EnumConfig<TEnum>,
) {
  getMetadataStorage().collectEnumMetadata({
    enumObj,
    name: enumConfig.name,
    description: enumConfig.description,
    valuesConfig: enumConfig.valuesConfig || {},
  })
}

Analysis:

⚠️ Must explicitly register: Cannot directly use TypeScript enums, need to call registerEnumType() to manually register
⚠️ Duplicate declarations: Enum values need manual synchronization in TypeScript and GraphQL
✅ Type safe: Registered enums are type-synchronized in TypeScript and GraphQL
✅ Supports descriptions and deprecation: Can configure description and deprecation reason for each enum value through valuesConfig
⚠️ Does not support string union types: Cannot directly use 'A' | 'B' types, must define as enum

Conclusion: Explicit registration. Must call a specific function (registerEnumType) to manually register, but maintains type safety in inference. Compared to directly using TypeScript enums or string union types, requires an additional registration step.

2.3 Interface Inheritance & Union Type Experience

Score: 3.0

Evidence:

Interface fields require manual duplicate declarations: typescript-graphql-schemas/typegraphql/src/resolvers/menu.type.ts (lines 24-69) demonstrates interface implementation
- Food interface defines common fields (id, name, price)
- Coffee and Dessert implement the interface through @ObjectType({ implements: Food })
- But implementing types must manually duplicate all interface fields (lines 39-46 and 58-65)
Union types require manual resolveType implementation: typescript-graphql-schemas/typegraphql/src/resolvers/menu.type.ts (lines 72-84) uses createUnionType() to create union types, requires manual resolveType function implementation
Must manually handle typename: typescript-graphql-schemas/typegraphql/src/resolvers/menu.resolver.ts (lines 8-25) manually adds typename field when defining types

Code Example:

// Interface definition
@InterfaceType()
export abstract class Food {
  @Field(() => Int)
  id!: number

  @Field(() => String)
  name!: string

  @Field(() => Float)
  price!: number
}

// Implement interface - must manually duplicate all fields
@ObjectType({ implements: Food })
export class Coffee implements Food {
  @Field(() => Int)  // Duplicate declaration
  id!: number

  @Field(() => String)  // Duplicate declaration
  name!: string

  @Field(() => Float)  // Duplicate declaration
  price!: number

  @Field(() => SugarLevel)  // Unique field
  sugarLevel!: SugarLevel
}

// Union type - requires manual resolveType implementation
export const MenuItem = createUnionType({
  name: 'MenuItem',
  types: () => [Coffee, Dessert] as const,
  resolveType: (value) => {  // Must manually implement
    if ('__typename' in value && value.__typename === 'Coffee') {
      return 'Coffee'
    }
    if ('__typename' in value && value.__typename === 'Dessert') {
      return 'Dessert'
    }
    return null
  },
})

Implementation Mechanism (type-graphql/src/schema/schema-generator.ts lines 306-315):

// Supports implicit interface implementation - gets fields from interface definition
if (objectType.interfaceClasses) {
  const implementedInterfaces = this.metadataStorage.interfaceTypes.filter(it =>
    objectType.interfaceClasses!.includes(it.target),
  )
  implementedInterfaces.forEach(it => {
    fieldsMetadata.push(...(it.fields || []))  // Automatically adds interface fields
  })
}
// But implementing types still need to manually declare fields (for type checking)

Analysis:

⚠️ Interface fields require manual duplicate declarations: Classes implementing interfaces must manually duplicate all interface fields, cannot auto-inherit
⚠️ Union types require manual resolveType implementation: Cannot automatically handle type resolution, must manually judge __typename
⚠️ Must manually handle __typename: Must manually add __typename field when returning data (typescript-graphql-schemas/typegraphql/src/resolvers/menu.resolver.ts lines 53-54)
✅ Supports abstract types: Interfaces and union types are correctly generated in GraphQL Schema
✅ Type safe: TypeScript type checking ensures implementing classes contain all interface fields
⚠️ Lots of boilerplate: Compared to auto-inheritance solutions, requires more manual code

Conclusion: Logical resolution. Supports abstract types, but requires manual resolveType function implementation and has specific dependencies on original data structure (requires __typename field). Interface fields require manual duplicate declarations, cannot auto-inherit.

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 1.0

Evidence:

Almost all fields require explicit type functions: All 29 field decorators in typescript-graphql-schemas/typegraphql/src use @Field(() => Type) to explicitly provide types
Basic types can be inferred but rarely used: type-graphql/src/helpers/findType.ts (lines 64-66) shows that if returnTypeFunc is not provided and reflection metadata doesn't exist or is banned, an error is thrown
Array types must be explicitly declared: typescript-graphql-schemas/typegraphql/src/resolvers/user.type.ts (line 15) uses @Field(() => [Order]) to explicitly declare array type
Complex types must be explicitly declared: Promises, nested types, Unions, etc. all require explicit type functions

Code Example:

@ObjectType()
export class User {
  // Basic types - must explicitly provide type functions
  @Field(() => Int)  // Cannot omit
  id!: number

  @Field(() => String)  // Cannot omit
  name!: string

  // Array types - must explicitly declare
  @Field(() => [Order])  // Must explicitly provide array type
  orders!: Order[]

  // Optional fields - must explicitly declare
  @Field(() => User, { nullable: true })  // Must explicitly declare nullable
  user?: User | null
}

Type Inference Mechanism (type-graphql/src/helpers/findType.ts lines 64-66):

if (!returnTypeFunc && (!metadataDesignType || bannedTypes.includes(metadataDesignType))) {
  throw new NoExplicitTypeError(...)  // Must provide type function
}

Banned Types (type-graphql/src/helpers/returnTypes.ts):

Basic types like Object, Function, Array cannot be inferred through reflection metadata
Must explicitly provide type functions

Analysis:

⚠️ Every field must manually specify type through decorators or generics, inference capability is limited
⚠️ Arrays, Promises, nested types, Unions, and other complex types frequently require explicit annotations
⚠️ Nullability must be explicitly declared: { nullable: true } option must be manually configured
⚠️ Type inference is almost unusable: Although theoretically possible through reflection metadata inference, in practice almost all fields require explicit declarations
✅ Type safe: Explicit declarations ensure complete type synchronization, no type inconsistencies
⚠️ Lots of boilerplate: Compared to auto-inference solutions, requires extensive explicit type declarations

Conclusion: Strong binding. Every field, parameter, and return value must manually specify type through decorators or generics, inference capability is limited. Although theoretically supports reflection metadata inference, in practice almost all fields require explicit declarations.

Type Definition Overall Score

Score: 2.0

Scoring Basis:

Single source of truth: 3.0 (Logical association, requires manual decorator marking, duplicate declarations exist)
Enum & string union support: 3.0 (Explicit registration, requires manual call to registerEnumType())
Interface inheritance & union type experience: 3.0 (Logical resolution, requires manual resolveType implementation, interface fields need duplicate declarations)
Type inference strength: 1.0 (Strong binding, almost all fields require explicit declarations)

Advantages:

Type safe: Explicit declarations ensure TypeScript types and GraphQL Schema are completely synchronized
Intuitive decorator syntax: Classes and decorators define Schema, code structure is clear
Supports complex types: Supports interfaces, union types, enums, and other GraphQL advanced features
Runtime type checking: Validates types at runtime through reflection metadata

Disadvantages:

Extensive explicit declarations: Almost all fields require explicit type functions, lots of boilerplate
Interface field duplication: Classes implementing interfaces must manually duplicate all interface fields
Union types are complex: Requires manual resolveType implementation and __typename handling
Enums require registration: Cannot directly use TypeScript enums, requires manual registration
Limited type inference: Although theoretically supports reflection metadata inference, in practice it's almost unusable

3. Resolvers & Validation

Core Implementation Mechanism

TypeGraphQL uses a decorator + class methods approach to implement resolver definitions. Resolvers are marked with the @Resolver() decorator on classes, Queries/Mutations are marked with @Query() and @Mutation() decorators on methods, parameters are defined through @Arg() or @Args() decorators, validation is provided through class-validator decorators and validateFn configuration, and DataLoader needs to be manually integrated into Context.

Source Code Evidence:

Resolver decorator: type-graphql/src/decorators/Resolver.ts (lines 5-25) defines the @Resolver() decorator
Query/Mutation decorators: type-graphql/src/decorators/Query.ts (lines 6-18) and Mutation.ts (lines 6-21) define Query and Mutation decorators
Parameter decorators: type-graphql/src/decorators/Arg.ts (lines 18-49) and Args.ts (lines 7-24) define parameter decorators
Validation implementation: type-graphql/src/resolvers/validate-arg.ts (lines 12-59) implements parameter validation logic
Business code example: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (lines 46-93) demonstrates complete Resolver definition

Scoring Details

3.1 Developer Experience (Code Conciseness)

Score: 2.0

Evidence:

Requires many decorators: Each parameter needs an @Arg() decorator, each method needs a @Query() or @Mutation() decorator
Verbose parameter definitions: typescript-graphql-schemas/typegraphql/src/resolvers/menu.resolver.ts (lines 45-50) demonstrates Mutation parameter definitions, each parameter needs an explicit decorator
ArgsType requires additional class definition: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (lines 24-44) requires defining an additional ArgsType class
Type functions must be explicitly provided: All parameters and return values require explicit type functions () => Type

Code Example:

// Query definition - requires decorator
@Query(() => User)
user(@Arg('id', () => Int) id: number): User {
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  return user
}

// Mutation definition - parameters need to be decorated one by one
@Mutation(() => Coffee)
createCoffee(
  @Arg('name', () => String) name: string,
  @Arg('price', () => Float) price: number,
  @Arg('sugarLevel', () => SugarLevel) sugarLevel: SugarLevel,
  @Arg('origin', () => String) origin: string,
): CoffeeItem {
  // Business logic
}

// Using ArgsType - requires additional class definition
@ArgsType()
class CreateUserArgs {
  @Field(() => String)
  name!: string

  @Field(() => String)
  @IsEmail({}, { message: 'Invalid email format' })
  email!: string
}

@Mutation(() => User)
createUser(@Args(() => CreateUserArgs) { name, email }: CreateUserArgs): User {
  // Business logic
}

Analysis:

⚠️ Requires many decorators: Each parameter, each method needs decorators, code is verbose
⚠️ Type functions must be explicitly provided: All parameters and return values require () => Type type functions
⚠️ ArgsType requires additional class definition: Complex parameters require defining additional ArgsType classes, increasing code volume
✅ Code structure is clear: Classes and decorators organize code, structure is clear
✅ Type safe: All types have complete TypeScript type checking

Conclusion: Moderate code volume, lots of template code. Requires additional API wrapping (decorators), each parameter and method needs explicit decorator marking.

3.2 Modular Design (Domain-Driven Development Support)

Score: 5.0

Evidence:

Organized by Resolver classes: The typescript-graphql-schemas/typegraphql/src/resolvers/ directory splits files by domain (user.resolver.ts, menu.resolver.ts, order.resolver.ts)
Type definitions and Resolvers in the same module: Each domain module contains type definitions (.type.ts) and Resolvers (.resolver.ts)
Module boundaries created through Resolver classes: The @Resolver(() => User) decorator clearly identifies the type this Resolver handles
Query, Mutation, Field Resolver all in the same class: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (lines 46-93) contains Query, Mutation, and Field Resolver

Code Example:

// user.resolver.ts - User domain module
@Resolver(() => User)
export class UserResolver {
  // Query
  @Query(() => [User])
  users(): User[] { ... }

  // Mutation
  @Mutation(() => User)
  createUser(@Args(() => CreateUserArgs) args: CreateUserArgs): User { ... }

  // Field Resolver
  @FieldResolver(() => [Order])
  async orders(@Root() user: User, @Ctx() { loaders }: MyContext): Promise<Order[]> {
    return loaders.userOrders.load(user.id)
  }
}

// menu.resolver.ts - Menu domain module
@Resolver()
export class MenuResolver {
  @Query(() => [MenuItem])
  menu(): MenuItemType[] { ... }
  // ...
}

Analysis:

✅ Natural domain modularization: Creates clear module boundaries through Resolver classes
✅ Type definitions, Query, Mutation, Field Resolver are all in the same module
✅ Forces domain organization: Each Resolver class corresponds to a domain module
✅ Clear module boundaries: @Resolver(() => Type) clearly identifies the type the module handles
✅ Easy to maintain: Each domain module is independent, convenient for team collaboration

Conclusion: Natural domain modularization, forces domain organization. Type definitions, Query, Mutation, Field Resolver are all in the same module, creating clear module boundaries through domain boundaries (Resolver classes).

3.3 Parameter Definition & Type Inference

Score: 2.0

Evidence:

Each parameter requires explicit type function: typescript-graphql-schemas/typegraphql/src/resolvers/menu.resolver.ts (lines 47-50) each parameter requires @Arg('name', () => String) explicit type declaration
ArgsType requires manual class definition: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (lines 24-44) requires defining ArgsType class and manually decorating each field
Type inference is almost unusable: Although theoretically possible through reflection metadata inference, in practice all parameters require explicit declarations
Parameter type safety: TypeScript can understand parameter types, but requires manual declaration

Code Example:

// Single parameter - must explicitly provide type function
@Query(() => User)
user(@Arg('id', () => Int) id: number): User {
  // id's type must be explicitly declared as () => Int
}

// Multiple parameters - each parameter needs a decorator
@Mutation(() => Coffee)
createCoffee(
  @Arg('name', () => String) name: string,  // Must explicitly declare
  @Arg('price', () => Float) price: number,  // Must explicitly declare
  @Arg('sugarLevel', () => SugarLevel) sugarLevel: SugarLevel,  // Must explicitly declare
  @Arg('origin', () => String) origin: string,  // Must explicitly declare
): CoffeeItem { ... }

// Using ArgsType - requires manual class definition
@ArgsType()
class CreateUserArgs {
  @Field(() => String)  // Each field requires explicit declaration
  name!: string

  @Field(() => String)  // Each field requires explicit declaration
  email!: string
}

@Mutation(() => User)
createUser(@Args(() => CreateUserArgs) { name, email }: CreateUserArgs): User {
  // TypeScript can understand parameter types, but requires manual ArgsType class definition
}

Analysis:

⚠️ Each parameter requires decorator explicit type declaration, type inference is limited
⚠️ ArgsType requires manual class definition and decorating each field, increasing code volume
⚠️ Type functions must be explicitly provided: () => Type cannot be omitted
✅ Type safe: TypeScript can understand parameter types, compile-time type checking
⚠️ Lots of boilerplate: Compared to auto-inference solutions, requires extensive explicit type declarations

Conclusion: Parameter types require extensive explicit declarations, type inference is limited. Each parameter requires decorator or configuration object explicit type declaration. Although TypeScript can understand parameter types, manual declaration is required.

3.4 Input Validation Mechanism

Score: 4.0

Evidence:

Supports class-validator decorators: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (line 30) uses @IsEmail() decorator for validation
Requires validateFn configuration: typescript-graphql-schemas/typegraphql/src/schema.ts (lines 13-22) requires manual validateFn configuration to call class-validator's validate() function
Supports custom validators: typescript-graphql-schemas/typegraphql/src/resolvers/order.resolver.ts (lines 39-81) demonstrates custom validators (UserExists, MenuItemsExist)
Validation logic separated from Schema definition: Validation decorators (@IsEmail()) and Schema definitions (@Field()) are separated, requires manual maintenance synchronization

Code Example:

// 1. Define ArgsType and add validation decorators
@ArgsType()
class CreateUserArgs {
  @Field(() => String)
  name!: string

  @Field(() => String)
  @IsEmail({}, { message: 'Invalid email format' })  // Validation decorator
  email!: string
}

// 2. Configure validateFn in buildSchema
export const schema = await buildSchema({
  resolvers: [UserResolver, MenuResolver, OrderResolver],
  validateFn: async (argValue) => {
    if (typeof argValue !== 'object' || argValue === null) {
      return
    }
    const errors = await validate(argValue)  // Call class-validator
    if (errors.length > 0) {
      const message = Object.values(errors[0].constraints || {})[0]
      throw new GraphQLError(message)
    }
  },
})

// 3. Custom validators
@ValidatorConstraint({ name: 'userExists', async: false })
class UserExistsConstraint implements ValidatorConstraintInterface {
  validate(userId: number) {
    return userMap.has(userId)
  }
  defaultMessage() {
    return 'User not found'
  }
}

function UserExists(validationOptions?: ValidationOptions) {
  return function (object: object, propertyName: string) {
    registerDecorator({
      target: object.constructor,
      propertyName: propertyName,
      options: validationOptions,
      constraints: [],
      validator: UserExistsConstraint,
    })
  }
}

@ArgsType()
class CreateOrderArgs {
  @Field(() => Int)
  @UserExists()  // Custom validator
  userId!: number
}

Implementation Mechanism (type-graphql/src/resolvers/validate-arg.ts lines 12-59):

export async function validateArg(
  argValue: any | undefined,
  argType: TypeValue,
  resolverData: ResolverData,
  globalValidateSettings: ValidateSettings,
  argValidateSettings: ValidateSettings | undefined,
  globalValidateFn: ValidatorFn | undefined,
  argValidateFn: ValidatorFn | undefined,
): Promise<any | undefined> {
  const validateFn = argValidateFn ?? globalValidateFn;
  if (typeof validateFn === "function") {
    await validateFn(argValue, argType, resolverData);
    return argValue;
  }
  // Use class-validator for validation
  const { validateOrReject } = await import("class-validator");
  await validateOrReject(argValue, validatorOptions);
}

Analysis:

✅ Supports declarative validation: Uses class-validator decorators to provide validation functionality
⚠️ Requires additional configuration: Requires manual validateFn configuration to call class-validator
✅ Supports custom validators: Can define custom validation constraints
⚠️ Validation logic separated from Schema definition: Validation decorators and Schema definitions are separated, requires manual maintenance synchronization
✅ Type safe: Validation decorators integrate with TypeScript type system

Conclusion: Supports declarative validation, but requires additional configuration. Uses decorators or plugins to provide validation functionality, requires parameter type classes or plugin configuration. Validation logic is separated from Schema definition, requires manual maintenance synchronization.

3.5 Batch Loading (DataLoader) Integration

Score: 0.0

Evidence:

Requires manual DataLoader instance creation: typescript-graphql-schemas/typegraphql/src/context.ts (lines 11-23) requires manual DataLoader instance creation
Requires manual Context type definition: typescript-graphql-schemas/typegraphql/src/context.ts (lines 5-9) requires manual Context type definition
Requires manual Context injection configuration: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (line 61) uses @Ctx() decorator to inject Context
Requires manual calls in Resolver: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (line 62) requires manual call to loaders.userOrders.load()

Code Example:

// 1. Manually define Context type
export class MyContext {
  loaders!: {
    userOrders: DataLoader<number, Order[]>
  }
}

// 2. Manually create DataLoader instances
export function createLoaders() {
  return {
    userOrders: new DataLoader<number, Order[]>(async (userIds) => {
      const userOrders = new Map<number, Order[]>()
      for (const order of orderMap.values()) {
        const orders = userOrders.get(order.userId) ?? []
        orders.push(order)
        userOrders.set(order.userId, orders)
      }
      return userIds.map((id) => userOrders.get(id) ?? [])
    }),
  }
}

// 3. Manually use in Resolver
@FieldResolver(() => [Order])
async orders(@Root() user: User, @Ctx() { loaders }: MyContext): Promise<Order[]> {
  return loaders.userOrders.load(user.id)  // Manual call
}

Analysis:

⚠️ No built-in support: Requires manual DataLoader instance creation, Context type definition, Context injection configuration
⚠️ Lots of boilerplate: Requires extensive boilerplate code to integrate DataLoader
⚠️ Requires manual lifecycle management: Need to create new DataLoader instances for each request
⚠️ No declarative API: Cannot declaratively use DataLoader through decorators or configuration
✅ High flexibility: Manual integration provides maximum flexibility

Conclusion: Provides no built-in dataloader support, requires extensive context boilerplate and dataloader boilerplate. Requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate.

Resolvers & Validation Overall Score

Score: 2.6

Scoring Basis:

Developer experience: 2.0 (Moderate code volume, lots of template code)
Modular design: 5.0 (Natural domain modularization, forces domain organization)
Parameter definition & type inference: 2.0 (Parameter types require extensive explicit declarations, type inference is limited)
Input validation mechanism: 4.0 (Supports declarative validation, but requires additional configuration)
Batch loading (DataLoader) integration: 0.0 (Provides no built-in dataloader support)

Advantages:

Natural domain modularization: Creates clear module boundaries through Resolver classes, type definitions, Query, Mutation, Field Resolver are all in the same module
Clear code structure: Classes and decorators organize code, structure is clear
Type safe: All types have complete TypeScript type checking
Complete validation support: Supports class-validator decorators and custom validators

Disadvantages:

Extensive explicit declarations: Each parameter and method requires decorators, type functions must be explicitly provided
ArgsType requires additional class definition: Complex parameters require defining additional ArgsType classes, increasing code volume
No built-in DataLoader support: Requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate
Limited type inference: Although theoretically supports reflection metadata inference, in practice almost all parameters require explicit declarations
Validation requires additional configuration: Requires manual validateFn configuration to call class-validator

4. Built-in Features

Feature Support Overview

TypeGraphQL provides rich built-in feature support. Core features (Directives, Extensions, Subscriptions, Custom Scalars, Context, Middleware) provide native support, but DataLoader and depth limiting require manual implementation, and query complexity analysis requires manual integration of third-party libraries.

Feature Support Details Table

Feature	Support Status	Implementation Method	Evidence/Explanation
Directives	✅ Built-in Support	`@Directive` decorator	`type-graphql/src/decorators/Directive.ts` (lines 5-43) provides `@Directive()` decorator, supports use on classes, fields, parameters, API is concise and type-safe
Extensions	✅ Built-in Support	`@Extensions` decorator	`type-graphql/src/decorators/Extensions.ts` (lines 6-27) provides `@Extensions()` decorator, can declare query complexity, execution time and other extension information, API is intuitive
Batch Loading (DataLoader)	⛔ Cannot Implement	Requires manual integration	Provides no built-in dataloader support, requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate
Custom Scalars	✅ Built-in Support	`scalarsMap` configuration	`type-graphql/src/utils/buildSchema.ts` (line 55) supports `scalarsMap` configuration, `type-graphql/src/scalars/index.ts` (line 2) exports common scalars
Subscriptions	✅ Built-in Support	`@Subscription` decorator	`type-graphql/src/decorators/Subscription.ts` (lines 27-51) provides `@Subscription()` decorator, uses `@graphql-yoga/subscription` package to support real-time data push
Context Injection	✅ Built-in Support	`@Ctx()` decorator	`type-graphql/src/decorators/Ctx.ts` (lines 5-19) provides `@Ctx()` decorator, context type inference is complete, IDE hints are good, no manual type declarations needed
Middleware	✅ Built-in Support	`@UseMiddleware` decorator	`type-graphql/src/decorators/UseMiddleware.ts` (lines 7-37) provides `@UseMiddleware()` decorator, supports injecting logic before and after Resolver execution, API is concise
Query Complexity	⚠️ Plugin/Additional Implementation	Manual integration of `graphql-query-complexity`	`type-graphql/examples/query-complexity/index.ts` (lines 5, 34-66) demonstrates manual integration of `graphql-query-complexity` library, requires additional configuration and custom logic
Depth Limiting	⛔ Cannot Implement	No built-in support	Completely does not support depth limiting, cannot prevent depth query attacks, requires manual implementation or use of third-party libraries

Detailed Analysis

4.1 Directive Support

Status: ✅ Built-in Support

Evidence:

type-graphql/src/decorators/Directive.ts (lines 5-43) provides @Directive() decorator
Supports use of directives on classes, fields, parameters
type-graphql/docs/directives.md (lines 21-50) demonstrates directive usage

Code Example:

// Use directive on class
@Directive("@auth(requires: USER)")
@ObjectType()
class Foo {
  @Field()
  field: string;
}

// Use directive on field
@ObjectType()
class Bar {
  @Directive("@auth(requires: USER)")
  @Field()
  field: string;
}

Analysis:

✅ Native support for defining and using GraphQL Directives
✅ Supports Federation architecture, API is concise and type-safe
✅ Supports use of directives on classes, fields, parameters
⚠️ Does not support use of directives on scalars, enums, union types (documentation states)

Conclusion: Built-in support. Native support for defining and using GraphQL Directives, supports Federation architecture, API is concise and type-safe.

4.2 Extension Support

Status: ✅ Built-in Support

Evidence:

type-graphql/src/decorators/Extensions.ts (lines 6-27) provides @Extensions() decorator
type-graphql/examples/extensions/index.ts demonstrates extension usage examples
Can declare query complexity, execution time and other extension information

Code Example:

@ObjectType()
class Recipe {
  @Field()
  @Extensions({ complexity: 5 })
  title!: string;
}

@Resolver()
class RecipeResolver {
  @Query()
  @Extensions({ complexity: 10 })
  recipes(): Recipe[] {
    // ...
  }
}

Analysis:

✅ Native support for defining and using GraphQL Extensions
✅ Can declare query complexity, execution time and other extension information
✅ API is intuitive, type-safe
✅ Supports defining extensions at type level and field level

Conclusion: Built-in support. Native support for defining and using GraphQL Extensions, can declare query complexity, execution time and other extension information, API is intuitive.

4.3 Batch Loading (DataLoader) Integration

Status: ⛔ Cannot Implement

Evidence:

Provides no built-in dataloader support
typescript-graphql-schemas/typegraphql/src/context.ts (lines 1-23) requires manual DataLoader instance creation
typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (lines 61-62) requires manual call to loaders.userOrders.load()

Code Example:

// Requires manual Context type definition
export class MyContext {
  loaders!: {
    userOrders: DataLoader<number, Order[]>
  }
}

// Requires manual DataLoader instance creation
export function createLoaders() {
  return {
    userOrders: new DataLoader<number, Order[]>(async (userIds) => {
      // Manual batch loading logic implementation
    }),
  }
}

// Requires manual use in Resolver
@FieldResolver(() => [Order])
async orders(@Root() user: User, @Ctx() { loaders }: MyContext): Promise<Order[]> {
  return loaders.userOrders.load(user.id)  // Manual call
}

Analysis:

⚠️ Provides no built-in dataloader support
⚠️ Requires manual DataLoader instance creation, Context type definition, Context injection configuration
⚠️ Lots of boilerplate: Requires extensive boilerplate code to integrate DataLoader
⚠️ Requires manual lifecycle management: Need to create new DataLoader instances for each request

Conclusion: Cannot implement. Provides no built-in dataloader support, and cannot be implemented through plugins, requires extensive context boilerplate and dataloader boilerplate.

4.4 Custom Scalars

Status: ✅ Built-in Support

Evidence:

type-graphql/src/utils/buildSchema.ts (line 55) supports scalarsMap configuration
type-graphql/src/scalars/index.ts (line 2) exports common scalars (GraphQLTimestamp, GraphQLISODateTime)
typescript-graphql-schemas/typegraphql/src/schema.ts (line 12) uses scalarsMap to configure scalars

Code Example:

// Use scalarsMap to configure scalars
export const schema = await buildSchema({
  resolvers: [UserResolver, MenuResolver, OrderResolver],
  scalarsMap: [{ type: Date, scalar: GraphQLDateTime }],
})

// Use in type definitions
@ObjectType()
export class Order {
  @Field(() => GraphQLDateTime)
  createdAt!: Date
}

Analysis:

✅ Built-in support for custom scalar types, defining new scalar types is simple
✅ Built-in common scalar types (GraphQLTimestamp, GraphQLISODateTime)
✅ API is intuitive and type-safe
✅ Supports using third-party scalar libraries (like graphql-scalars)

Conclusion: Built-in support. Built-in common scalar types (like DateTime, Timestamp, etc.), defining new scalar types is simple, API is intuitive and type-safe.

4.5 Subscriptions

Status: ✅ Built-in Support

Evidence:

type-graphql/src/decorators/Subscription.ts (lines 27-51) provides @Subscription() decorator
type-graphql/examples/simple-subscriptions/index.ts (line 17) demonstrates subscription usage
Uses @graphql-yoga/subscription package to support real-time data push

Code Example:

@Resolver()
class NotificationResolver {
  @Subscription({
    topics: "NOTIFICATIONS",
    filter: ({ payload, args }) => args.priorities.includes(payload.priority),
  })
  newNotification(@Root() notification: Notification): Notification {
    return notification;
  }
}

// Configure pubSub in buildSchema
const schema = await buildSchema({
  resolvers: [NotificationResolver],
  pubSub,  // Provide PubSub instance
})

Analysis:

✅ Native support for GraphQL Subscriptions
✅ Supports real-time data push, underlying transport protocol compatibility is good (WebSocket, SSE, etc.)
✅ API is concise, supports topics, filter and other options
✅ Supports dynamic topics and custom subscribe functions

Conclusion: Built-in support. Native support for GraphQL Subscriptions, supports real-time data push, underlying transport protocol compatibility is good (WebSocket, SSE, etc.), API is concise.

4.6 Context Injection

Status: ✅ Built-in Support

Evidence:

type-graphql/src/decorators/Ctx.ts (lines 5-19) provides @Ctx() decorator
typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (line 61) uses @Ctx() to inject context
Context type inference is complete, IDE hints are good

Code Example:

// Define Context type
export class MyContext {
  loaders!: {
    userOrders: DataLoader<number, Order[]>
  }
}

// Use in Resolver
@FieldResolver(() => [Order])
async orders(@Root() user: User, @Ctx() { loaders }: MyContext): Promise<Order[]> {
  return loaders.userOrders.load(user.id)
}

Analysis:

✅ Native support for injecting context in Resolvers
✅ Context type inference is complete, IDE hints are good
✅ No manual type declarations needed, TypeScript can automatically infer types
✅ Supports optional property names: @Ctx('propertyName') can specify property name

Conclusion: Built-in support. Native support for injecting context in Resolvers, context type inference is complete, IDE hints are good, no manual type declarations needed.

4.7 Middleware

Status: ✅ Built-in Support

Evidence:

type-graphql/src/decorators/UseMiddleware.ts (lines 7-37) provides @UseMiddleware() decorator
type-graphql/examples/middlewares-custom-decorators/index.ts (line 19) demonstrates middleware usage
Supports global middleware and field-level middleware

Code Example:

// Define middleware
const LoggerMiddleware: MiddlewareFn = async ({ info }, next) => {
  console.log(`Query: ${info.fieldName}`);
  return next();
};

// Use on Resolver class
@UseMiddleware(LoggerMiddleware)
@Resolver()
class RecipeResolver {
  // ...
}

// Use on field
@Query()
@UseMiddleware(LoggerMiddleware)
recipes(): Recipe[] {
  // ...
}

// Global middleware
const schema = await buildSchema({
  resolvers: [RecipeResolver],
  globalMiddlewares: [LoggerMiddleware],
})

Analysis:

✅ Native support for injecting middleware logic before and after Resolver execution
✅ API is concise, supports chained calls
✅ Supports global middleware and field-level middleware
✅ Supports custom decorators (implemented through middleware)

Conclusion: Built-in support. Native support for injecting middleware logic before and after Resolver execution (like logging, permission checking, performance monitoring), API is concise, supports chained calls.

4.8 Query Complexity Analysis

Status: ⚠️ Plugin/Additional Implementation

Evidence:

type-graphql/examples/query-complexity/index.ts (lines 5, 34-66) demonstrates manual integration of graphql-query-complexity library
Requires manual Apollo Server plugin configuration
Requires manual complexity estimator definition

Code Example:

// Requires manual integration of graphql-query-complexity
import { fieldExtensionsEstimator, getComplexity, simpleEstimator } from "graphql-query-complexity";

const server = new ApolloServer({
  schema,
  plugins: [
    {
      requestDidStart: async () => ({
        async didResolveOperation({ request, document }) {
          const complexity = getComplexity({
            schema,
            query: document,
            variables: request.variables,
            estimators: [
              fieldExtensionsEstimator(),  // Use complexity defined by @Extensions decorator
              simpleEstimator({ defaultComplexity: 1 }),
            ],
          });
          if (complexity > MAX_COMPLEXITY) {
            throw new Error(`Too complicated query!`);
          }
        },
      }),
    },
  ],
});

Analysis:

⚠️ Not built-in support, but can be implemented through manual integration of graphql-query-complexity
✅ Supports using @Extensions decorator to define field complexity
⚠️ Requires manual Apollo Server plugin configuration
⚠️ Requires manual complexity estimator definition

Conclusion: Plugin/Additional implementation. Not built-in support, but can be implemented through plugins or manual integration of graphql-query-complexity for query complexity analysis, requires additional configuration and custom logic.

4.9 Depth Limiting

Status: ⛔ Cannot Implement

Evidence:

Completely does not support depth limiting
Provides no built-in depth limiting functionality
Requires manual implementation or use of third-party libraries (like graphql-depth-limit)

Analysis:

⚠️ Completely does not support depth limiting
⚠️ Cannot prevent depth query attacks
⚠️ Requires manual implementation or use of third-party libraries

Conclusion: Cannot implement. Completely does not support depth limiting, cannot prevent depth query attacks, requires manual implementation or use of third-party libraries.

Built-in Features Overall Score

Score: 3.6

Scoring Basis:

Directives: ✅ Built-in support (5 points) - Through @Directive() decorator, supports use on classes, fields, parameters
Extensions: ✅ Built-in support (5 points) - Through @Extensions() decorator, can declare query complexity, execution time, etc.
DataLoader: ⛔ Cannot implement (0 points) - Provides no built-in dataloader support
Scalars: ✅ Built-in support (5 points) - Through scalarsMap configuration, built-in common scalar types
Subscription: ✅ Built-in support (5 points) - Through @Subscription() decorator, uses @graphql-yoga/subscription package
Context: ✅ Built-in support (5 points) - Through @Ctx() decorator, context type inference is complete
Middleware: ✅ Built-in support (5 points) - Through @UseMiddleware() decorator, supports global and field-level middleware
Query Complexity: ⚠️ Plugin/Additional implementation (2 points) - Requires manual integration of graphql-query-complexity library
Depth Limiting: ⛔ Cannot implement (0 points) - Completely does not support depth limiting

Total Score: 32/45 = 3.6/5.0

Scoring Basis:

Directive support: ✅ Built-in support (5 points) - Through @Directive() decorator, supports use on classes, fields, parameters
Extension support: ✅ Built-in support (5 points) - Through @Extensions() decorator, can declare query complexity, execution time, etc.
Batch loading: ⛔ Cannot implement (0 points) - Provides no built-in dataloader support
Custom scalars: ✅ Built-in support (5 points) - Through scalarsMap configuration, built-in common scalar types
Subscriptions: ✅ Built-in support (5 points) - Through @Subscription() decorator, uses @graphql-yoga/subscription package
Context injection: ✅ Built-in support (5 points) - Through @Ctx() decorator, context type inference is complete
Middleware: ✅ Built-in support (5 points) - Through @UseMiddleware() decorator, supports global and field-level middleware
Query complexity analysis: ⚠️ Plugin/Additional implementation (2 points) - Requires manual integration of graphql-query-complexity library
Depth limiting: ⛔ Cannot implement (0 points) - Completely does not support depth limiting

Advantages:

Core features complete: Core features like Directives, Extensions, Subscriptions, Custom Scalars, Context, Middleware all provide native support
API is concise: Decorator API is intuitive and easy to understand, type-safe
Type inference complete: All features have complete TypeScript type support
Documentation complete: Official provides rich examples and documentation

Disadvantages:

No built-in DataLoader support: Requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate
Depth limiting not supported: Completely does not support depth limiting, cannot prevent depth query attacks
Query complexity requires manual integration: Requires manual integration of graphql-query-complexity library, requires additional configuration

5. Ecosystem Integration

Core Implementation Mechanism

TypeGraphQL implements ecosystem integration through standard GraphQL Schema and decorator patterns. ORM integration requires manual use of ORM APIs (Repository, EntityManager, etc.), validation library integration is provided through class-validator decorators and validateFn configuration, and GraphQL Server and web frameworks integrate through standard GraphQL Schema.

Source Code Evidence:

TypeORM integration: type-graphql/examples/typeorm-basic-usage/resolvers/recipe.resolver.ts (lines 1-80) demonstrates manual use of TypeORM Repository
Prisma integration: type-graphql/docs/prisma.md (lines 6-30) demonstrates code generation through typegraphql-prisma package
NestJS integration: type-graphql/docs/nestjs.md (lines 6-36) demonstrates integration through typegraphql-nestjs package
Validation library integration: type-graphql/docs/validation.md (lines 15-100) demonstrates class-validator integration

Scoring Details

5.1 ORM Integration Depth

Score: <-To Be Scored->

Evidence:

TypeORM integration: type-graphql/examples/typeorm-basic-usage/index.ts (lines 13-14) requires manual TypeORM connection initialization, recipe.resolver.ts (lines 16-20) requires manual Repository retrieval
MikroORM integration: type-graphql/examples/mikro-orm/index.ts (lines 16-22) requires manual MikroORM initialization, line 52 requires manual EntityManager creation
Typegoose integration: type-graphql/examples/typegoose/index.ts (line 16) requires manual Mongoose connection, line 30 requires manual middleware configuration
Prisma integration: type-graphql/docs/prisma.md (lines 6-30) generates code through typegraphql-prisma package, but requires additional code generation steps

Code Example:

// TypeORM integration - requires manual use of Repository
@Resolver(_of => Recipe)
export class RecipeResolver {
  private readonly recipeRepository: Repository<Recipe>;

  constructor() {
    this.recipeRepository = dataSource.getRepository(Recipe);  // Manual retrieval
  }

  @Query(_returns => [Recipe])
  recipes(): Promise<Recipe[]> {
    return this.recipeRepository.find();  // Manual ORM API call
  }
}

// Prisma integration - requires code generation
// 1. Add generator in schema.prisma
generator typegraphql {
  provider = "typegraphql-prisma"
}

// 2. Run prisma generate to generate code
// 3. Use generated resolvers
import { resolvers } from "@generated/type-graphql";

const schema = await buildSchema({
  resolvers,  // Use generated resolvers
  validate: false,
});

Analysis:

⚠️ Supports ORM integration through plugins or manual methods, but requires more configuration and boilerplate
⚠️ TypeORM, MikroORM, Typegoose require manual use of ORM APIs, cannot auto-generate queries
✅ Prisma provides code generation through typegraphql-prisma package, but requires additional build steps
⚠️ Type synchronization requires manual maintenance, cannot auto-sync ORM models to GraphQL Schema
✅ Official provides rich integration examples, demonstrating integration with various ORMs

Conclusion: Basic integration. Supports ORM integration through plugins or manual methods, can reuse some model definitions, but requires more configuration and boilerplate. Cannot auto-generate efficient database queries, type synchronization requires manual maintenance.

5.2 Validation Library Integration

Score: <-To Be Scored->

Evidence:

class-validator deep integration: type-graphql/docs/validation.md (lines 15-100) demonstrates class-validator decorators deeply bound with Schema definitions
Automatic validation: type-graphql/examples/automatic-validation/index.ts (line 16) enables automatic validation through validate: true
Custom validation functions: type-graphql/examples/custom-validation/index.ts (lines 17-24) demonstrates using other validation libraries (like joiful) through validateFn
Validation decorators bound with Schema definition: typescript-graphql-schemas/typegraphql/src/resolvers/user.resolver.ts (line 30) uses @IsEmail() decorator, validation logic integrated with Schema definition

Code Example:

// class-validator integration - deep binding
@ArgsType()
class CreateUserArgs {
  @Field(() => String)
  @IsEmail({}, { message: 'Invalid email format' })  // Validation decorator
  email!: string
}

// Enable automatic validation
const schema = await buildSchema({
  resolvers: [UserResolver],
  validate: true,  // Enable class-validator integration
})

// Custom validation function - supports other validation libraries
const schema = await buildSchema({
  resolvers: [RecipeResolver],
  validateFn: (argValue, _argType) => {
    const { error } = joiful.validate(argValue);  // Use joiful
    if (error) throw error;
  },
})

Analysis:

✅ Official support for mainstream validation libraries (class-validator), validation logic deeply bound with Schema definitions
✅ Type inference is good, validation decorators integrate with TypeScript type system
✅ Supports custom validation functions, can use other validation libraries (like joiful)
⚠️ Requires minimal configuration: Need to set validate: true or configure validateFn
⚠️ Validation rules separated from type definitions: Although validation logic is integrated with Schema definitions, cannot auto-generate types from validation rules

Conclusion: Deep integration. Official support for mainstream validation libraries (class-validator), validation logic deeply bound with Schema definitions, type inference is good, requires minimal configuration.

5.3 GraphQL Server Compatibility

Score: <-To Be Scored->

Evidence:

Apollo Server integration: type-graphql/examples/simple-usage/index.ts (lines 18-22) demonstrates Apollo Server integration, examples/ directory contains many Apollo Server examples
GraphQL Yoga integration: type-graphql/examples/simple-subscriptions/index.ts (lines 21-24) demonstrates GraphQL Yoga integration
Standard GraphQL Schema: buildSchema() returns a standard GraphQLSchema object (type-graphql/src/utils/buildSchema.ts line 57), can integrate with any GraphQL Server
Apollo Federation support: type-graphql/examples/apollo-federation/index.ts (lines 13-32) demonstrates Apollo Federation integration

Code Example:

// Apollo Server integration
const schema = await buildSchema({
  resolvers: [RecipeResolver],
})

const server = new ApolloServer({ schema })  // Standard GraphQL Schema

// GraphQL Yoga integration
const schema = await buildSchema({
  resolvers: [NotificationResolver],
  pubSub,
})

const yoga = createYoga({
  schema,  // Standard GraphQL Schema
  graphqlEndpoint: "/graphql",
})

// Apollo Federation integration
const gateway = new ApolloGateway({
  supergraphSdl: new IntrospectAndCompose({
    subgraphs: [
      { name: "accounts", url: await accounts.listen(4001) },
    ],
  }),
})

Analysis:

✅ Fully compatible with all mainstream GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, Hono, etc.)
✅ Outputs standard GraphQL Schema, provides official adapter examples
✅ Zero configuration required, directly pass Schema to Server
✅ Official provides rich integration examples, demonstrating integration with various Servers

Conclusion: Fully compatible. Fully compatible with all mainstream GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, Hono, etc.), provides official adapter examples, zero configuration required.

5.4 Toolchain Integration

Score: <-To Be Scored->

Evidence:

TypeScript/JavaScript Support:

Must use TypeScript: TypeGraphQL's core features depend on TypeScript decorators, cannot use pure JavaScript
- Documentation clearly states: type-graphql/docs/types-and-fields.md (line 5) "The main idea of TypeGraphQL is to automatically create GraphQL schema definitions from TypeScript classes. To avoid the need for schema definition files and interfaces describing the schema, we use decorators and a bit of reflection magic."
- All official examples are TypeScript: All files in type-graphql/examples/ directory are .ts files
- Must enable decorators: type-graphql/docs/installation.md (lines 37-44) requires experimentalDecorators: true and emitDecoratorMetadata: true
Does not support pure JavaScript: Decorators are TypeScript experimental features, JavaScript does not support decorator syntax
TypeScript configuration requirements: type-graphql/docs/installation.md (lines 46-52) requires target: "es2021" or higher

Runtime Environment Support:

Node.js: ✅ Explicitly Supported
- type-graphql/package.json (lines 188-189) specifies "engines": { "node": ">= 20.11.1" }
- All official examples are Node.js environment: type-graphql/examples/simple-usage/index.ts (line 2) uses import path from "node:path"
- Documentation clearly states: type-graphql/docs/installation.md (line 46) "TypeGraphQL is designed to work with Node.js LTS and the latest stable releases"
Bun: ⚠️ Theoretically supported but not verified
- Source code uses Node.js-specific APIs: type-graphql/src/utils/buildSchema.ts (lines 1, 20) uses import path from "node:path" and process.cwd()
- No Bun-related documentation, examples, or configuration
- All example projects are Node.js environment
Deno: ⚠️ Theoretically supported but not verified
- Source code uses Node.js-specific APIs (node:path, process.cwd()), requires Deno compatibility layer support
- No Deno-related documentation, examples, or configuration
- All example projects are Node.js environment
Cloudflare Workers: ⚠️ Theoretically supported but not verified
- Has Azure Functions integration example: type-graphql/docs/azure-functions.md demonstrates serverless environment integration
- But no Cloudflare Workers-related documentation, examples, or configuration
- Source code uses Node.js-specific APIs (node:path, process.cwd()), may not be compatible in Cloudflare Workers
Browser: ⚠️ Limited Support (Only Class Definition Sharing)
- Provides shim mechanism: type-graphql/src/shim.ts provides empty decorator implementations for sharing class definitions in browsers
- Documentation clearly states: type-graphql/docs/browser-usage.md (lines 7-9) "Since TypeGraphQL is a Node.js framework, it doesn't work in a browser environment"
- Usage scenario limitations: type-graphql/docs/browser-usage.md (line 7) states it's only for "reusing the args or input classes with class-validator decorators or the object type classes with some helpful custom methods"
- Cannot run full framework: Cannot execute buildSchema() and other core functions in browsers

Build Tool Support:

TypeScript Compiler (tsc): ✅ Core Build Method
- All official examples use TypeScript compiler: type-graphql/examples/tsconfig.json demonstrates standard TypeScript configuration
- Framework's own build: type-graphql/package.json (line 57) uses tsc --build to build, outputs both CommonJS and ESM formats
- Dual format output: type-graphql/tsconfig.cjs.json and type-graphql/tsconfig.esm.json output CommonJS and ESM formats respectively
Webpack: ✅ Has Official Documentation and Configuration Examples
- Official documentation: type-graphql/docs/browser-usage.md (lines 14-28) provides Webpack configuration examples
- Configuration method: Use webpack.NormalModuleReplacementPlugin to replace type-graphql with type-graphql/shim
- Usage scenario: Mainly for browser environments, use shim to avoid bundling full framework code
Vite: ⚠️ No Official Configuration Examples
- Documentation and examples do not provide Vite configuration examples
- No Vite-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves
Rspack: ⚠️ No Official Configuration Examples
- Documentation and examples do not provide Rspack configuration examples
- No Rspack-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Code Evidence:

type-graphql/src/utils/buildSchema.ts (lines 1-2):

import path from "node:path";
import { type GraphQLSchema } from "graphql";

type-graphql/src/utils/buildSchema.ts (line 20):

const defaultSchemaFilePath = path.resolve(process.cwd(), "schema.graphql");

type-graphql/package.json (lines 188-189):

"engines": {
  "node": ">= 20.11.1"
}

type-graphql/docs/installation.md (lines 37-44):

It's important to set these options in the `tsconfig.json` file of our project:

{
  "emitDecoratorMetadata": true,
  "experimentalDecorators": true
}

type-graphql/docs/browser-usage.md (lines 7-9):

type-graphql/docs/browser-usage.md (lines 14-28):

## CRA and similar

We simply add this plugin code to our webpack config:

module.exports = {
  // ... Rest of Webpack configuration
  plugins: [
    // ... Other existing plugins
    new webpack.NormalModuleReplacementPlugin(/type-graphql$/, resource => {
      resource.request = resource.request.replace(/type-graphql/, "type-graphql/shim");
    }),
  ];
}

Analysis:

✅ Node.js explicitly supported: Official specifies Node.js version requirements, all examples are Node.js environment
✅ TypeScript compiler support is complete: Core build method, provides dual format output (CommonJS and ESM)
✅ Webpack has official documentation: Provides Webpack configuration examples for browser environments
⚠️ Must use TypeScript: Cannot use pure JavaScript, limits language choice
⚠️ Other runtime environments not verified: Bun, Deno, Cloudflare Workers have no official documentation or examples
⚠️ Browser support is limited: Only supports sharing class definitions through shim, cannot run full framework
⚠️ Other build tools have no official configuration: Vite, Rspack have no official configuration examples, requires user to configure themselves
⚠️ Node.js-specific API dependencies: Source code uses node:path and process.cwd(), limiting cross-platform compatibility

Conclusion: Basic support. Mainly supports TypeScript and Node.js, provides official support for TypeScript compiler and Webpack, but must use TypeScript, other runtime environments and build tools require user to configure themselves, flexibility is limited.

Ecosystem Integration Overall Score

Score: 3.5

Scoring Basis:

ORM integration depth: 3.0 (Basic integration, requires more configuration and boilerplate)
Validation library integration: 4.0 (Deep integration, class-validator deeply bound)
GraphQL Server compatibility: 5.0 (Fully compatible, all mainstream Servers supported)
Toolchain integration: 2.0 (Basic support, mainly supports TypeScript and Node.js, requires reflection environment)

Advantages:

GraphQL Server fully compatible: Fully compatible with all mainstream GraphQL Servers, outputs standard GraphQL Schema
Validation library deeply integrated: class-validator deeply bound, validation logic integrated with Schema definitions
Rich official integration examples: Provides many integration examples, demonstrating integration with various frameworks and ORMs
TypeScript compiler support is complete: Core build method, provides dual format output (CommonJS and ESM)
Webpack has official documentation: Provides Webpack configuration examples for browser environments

Disadvantages:

ORM integration requires manual configuration: TypeORM, MikroORM, Typegoose require manual use of ORM APIs, cannot auto-generate queries
Prisma requires code generation: Although supports Prisma, requires additional code generation steps
Type synchronization requires manual maintenance: Cannot auto-sync ORM models to GraphQL Schema, requires manual maintenance
Lots of boilerplate: ORM integration requires more boilerplate, cannot achieve zero-configuration integration
Must use TypeScript: Cannot use pure JavaScript, limits language choice
Other runtime environments not verified: Bun, Deno, Cloudflare Workers have no official documentation or examples
Other build tools have no official configuration: Vite, Rspack have no official configuration examples, requires user to configure themselves

📝 Summary

Overall Score: 2.9/5.0

Dimension	Score	Description
Architecture	3.0	Decorator pattern, moderate dependencies, lightweight build, feature-dependent, good integration
Type Definition	2.0	Logical association, explicit registration, logical resolution, strong binding, extensive explicit declarations
Resolvers & Validation	2.6	Natural domain modularization, but extensive explicit declarations, no built-in DataLoader support
Built-in Features	3.6	Core features complete, but DataLoader and depth limiting have no built-in support
Ecosystem Integration	3.5	GraphQL Server fully compatible, validation library deeply integrated, ORM requires manual configuration

Overall Evaluation

TypeGraphQL adopts a decorator pattern, defining GraphQL Schema through classes and decorators, achieving intuitive decorator syntax and automatic metadata collection design philosophy. Natural domain modularization creates clear module boundaries through Resolver classes. Core features are complete, Directives, Extensions, Subscriptions, Context, Middleware all provide native support. Validation library is deeply integrated, class-validator is deeply bound. However, it depends on reflection libraries, requires experimental features, type definitions require extensive explicit declarations, and DataLoader has no built-in support.

Core Advantages

Intuitive decorator syntax: Uses classes and decorators to define Schema, code structure is clear
Natural domain modularization: Creates clear module boundaries through Resolver classes, type definitions, Query, Mutation, Field Resolver are all in the same module
Core features complete: Directives, Extensions, Subscriptions, Custom Scalars, Context, Middleware all provide native support
Validation library deeply integrated: class-validator deeply bound, validation logic integrated with Schema definitions
GraphQL Server fully compatible: Fully compatible with all mainstream GraphQL Servers, outputs standard GraphQL Schema

Main Disadvantages

Depends on reflection library: Must import reflect-metadata, increasing runtime overhead
Experimental features: Must enable TypeScript decorators, not aligned with native TS best practices
Type definitions require extensive explicit declarations: Almost all fields require explicit type functions () => Type
Interface fields require duplicate declarations: Classes implementing interfaces must manually duplicate all interface fields
No DataLoader support: Requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate
Depth limiting not supported: Completely does not support depth limiting, cannot prevent depth query attacks

Use Cases

Recommended For

Teams that prefer decorator patterns
Projects requiring domain modularization
Projects requiring complete core features
Projects using class-validator
Projects requiring GraphQL Server full compatibility

Not Recommended For

Projects requiring zero magic
Projects requiring write-and-use (no code generation) workflows
Projects requiring DataLoader or depth limiting
Projects that don't want to use experimental features

Improvement Suggestions

Provide DataLoader and depth limiting support: Reduce manual implementation, improve development efficiency
Enhance type inference capability: Reduce explicit type declarations, improve development experience
Support automatic interface field inheritance: Reduce duplicate declarations
Reduce dependency on reflection library: Reduce runtime reflection requirements through compile-time type checking

Pylon Evaluation Report

Mon, 05 Jan 2026 14:07:07 +0000

📋 Basic Information

Project	Content
Version	2.9.6
GitHub	https://github.com/getcronit/pylon
Docs	https://pylon.cronit.io
First Commit	2023-11-24
Last Commit	2025-10-01

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture	2.5	Inference mode, requires build, deeply integrated with Hono
2. Type Definition	3.75	Deep inference, zero-config enums, smart interface detection, powerful type inference
3. Resolvers & Validation	2.5	Clean code, automatic type inference, but validation and DataLoader require manual implementation
4. Built-in Features	3.1	Context/Middleware/Subscriptions are well-implemented, no built-in DataLoader support
5. Ecosystem Integration	1.0	Basic ORM integration, no validation library integration, severe framework binding

1. Architecture

Architecture Overview

Pylon adopts an Inference (automatic inference) mode to build GraphQL Schema. The framework uses TypeScript Compiler API to statically analyze source code, automatically inferring and generating GraphQL Schema from TypeScript type definitions and Resolver function signatures. Developers only need to write TypeScript code without manually defining Schema. The framework automatically generates .pylon/schema.graphql and .pylon/resolvers.js during build time.

Core Implementation Locations:

packages/pylon-builder/src/schema/builder.ts: SchemaBuilder class, uses TypeScript Compiler API to analyze source code
packages/pylon-builder/src/schema/schema-parser.ts: SchemaParser class, parses type definitions and generates GraphQL Schema
packages/pylon-builder/src/bundler/bundler.ts: Bundler class, responsible for code bundling and Schema injection
packages/pylon/src/define-pylon.ts: Runtime Resolver transformation logic

Actual Usage Flow:

// 1. Write TypeScript code (src/index.ts)
export const graphql = {
  Query: {
    user: (id: Int): User => { ... }
  }
}

// 2. Run build command
pylon build  // or pylon dev

// 3. Auto-generated artifacts
// .pylon/schema.graphql - GraphQL Schema definition
// .pylon/resolvers.js - Union type resolvers
// .pylon/index.js - Bundled application code

1.1 Dependency Complexity

Score: 3.0

Core Dependency Analysis:

Runtime Dependencies (lines 23-38 of packages/pylon/package.json):
- graphql: ^16.9.0 - GraphQL standard library
- graphql-yoga: ^5.6.2 - GraphQL Server implementation
- hono: ^4.0.8 - Web framework (deeply integrated)
- @envelop/core: ^5.0.3 - GraphQL plugin system
- graphql-scalars: ^1.24.0 - Common scalar types
- @sentry/bun, @sentry/node - Error tracking
- jsonwebtoken, openid-client - Authentication support
- consola, winston - Logging libraries
- toucan-js - Cloudflare Workers error tracking
Dev Dependencies (packages/pylon-dev/package.json):
- @getcronit/pylon-builder - Schema build tool (required)
- @gqty/cli - Client code generation (optional)

Evidence:

// packages/pylon/package.json
"dependencies": {
  "@envelop/core": "^5.0.3",
  "@envelop/disable-introspection": "^8.0.0",
  "@hono/sentry": "^1.2.0",
  "@sentry/bun": "^8.17.0",
  "@sentry/node": "^8.54.0",
  "consola": "^3.2.3",
  "graphql": "^16.9.0",
  "graphql-scalars": "^1.24.0",
  "graphql-yoga": "^5.6.2",
  "hono": "^4.0.8",
  "jsonwebtoken": "^9.0.2",
  "openid-client": "^5.6.4",
  "toucan-js": "^4.1.0",
  "winston": "^3.8.2"
}

Analysis:

⚠️ Many runtime dependencies (about 13), including complete GraphQL Server and Web framework
⚠️ Deeply integrated with Hono framework, app is a Hono instance (line 6 of packages/pylon/src/app/index.ts)
⚠️ Built-in Sentry integration increases dependency complexity
✅ No decorators or reflection metadata (reflect-metadata) required
✅ All dependencies are standard npm packages, no proprietary tools

Actual Usage (typescript-graphql-schemas/pylon/package.json):

Business code needs to install @getcronit/pylon and @getcronit/pylon-dev
Runtime dependencies are transitively installed, developers don't need to manage them manually

Conclusion: Medium dependencies. Requires multiple third-party libraries (GraphQL Server, Web framework, authentication, logging, etc.), but all are standard libraries with no proprietary tools.

1.2 Build Flow

Score: 2.0

Build Method:

Must run build command: pylon build or pylon dev to generate Schema (lines 19-37 of packages/pylon-dev/src/index.ts)
Code generation mechanism: Uses TypeScript Compiler API to analyze source code, generating GraphQL Schema and Resolver code
Build artifacts: Generates .pylon/schema.graphql, .pylon/resolvers.js, and .pylon/index.js

Actual Usage Evidence:

// typescript-graphql-schemas/pylon/package.json
"scripts": {
  "dev": "pylon dev",
  "build": "pylon build",
  "print": "pylon build && cp .pylon/schema.graphql schema.graphql"
}

Code Generation Mechanism:

Schema generation: packages/pylon-builder/src/schema/builder.ts (lines 96-143) uses TypeScript Compiler API to analyze graphql exports
Type parsing: packages/pylon-builder/src/schema/schema-parser.ts parses TypeScript types and converts them to GraphQL types
Code injection: packages/pylon-builder/src/bundler/bundler.ts (lines 48-89) injects Schema and Resolver code during build

Core Implementation:

// packages/pylon-builder/src/index.ts:19-40
export const build = async (options: BuildOptions) => {
  const bundler = new Bundler(options.sfiFilePath, options.outputFilePath)

  return await bundler.build({
    getBuildDefs: () => {
      const builder = new SchemaBuilder(
        path.join(process.cwd(), options.sfiFilePath)
      )
      const built = builder.build()  // Uses TypeScript Compiler API for analysis

      return {
        typeDefs: built.typeDefs,      // Generate GraphQL Schema
        resolvers: built.resolvers     // Generate Union type resolvers
      }
    },
    watch: options.watch,
    onWatch: options.onWatch
  })
}

Build Artifact Structure:

.pylon/
├── schema.graphql    # Generated GraphQL Schema
├── resolvers.js      # Generated Union type resolvers
└── index.js          # Bundled application code (includes injected Schema)

Actual Generated Content (typescript-graphql-schemas/pylon/.pylon/resolvers.js):

export const resolvers = {
  MenuItem: {
    __resolveType: function resolveType(node) {
      if (node && typeof node === 'object') {
        if ("id" in node && "name" in node && "price" in node && 
            "sugarLevel" in node && "origin" in node) {
          return 'Coffee'
        }
        if ("id" in node && "name" in node && "price" in node && 
            "calories" in node) {
          return 'Dessert'
        }
      }
    }
  }
}

Shortcomings:

⚠️ Must run build command: Code cannot run directly, must execute pylon build first
⚠️ Development experience impact: Need to wait for build completion on first run or after Schema changes
⚠️ Opaque build process: Uses TypeScript Compiler API and esbuild, build process is opaque to developers
⚠️ Code injection: Injects Schema code through esbuild plugin during build (lines 48-89 of bundler.ts), may affect debugging

Conclusion: Explicit build. Must run CLI command to generate Schema files or type definitions before code can compile or run. Build process uses TypeScript Compiler API and code injection, relatively complex.

1.3 Config & Language Magic

Score: 3.0

Technical Implementation:

Uses TypeScript Compiler API: Generates Schema through static analysis of TypeScript source code (lines 12-26 of packages/pylon-builder/src/schema/builder.ts)
No decorators required: All type definitions use native TypeScript classes and interfaces
No reflection metadata required: Does not depend on reflect-metadata or runtime reflection
Type inference: Automatically infers GraphQL types by analyzing function signatures and return types

Core Implementation Evidence:

// packages/pylon-builder/src/schema/builder.ts:12-26
constructor(sfiFilePath: string) {
  this.sfiFilePath = sfiFilePath

  const tsConfigOptions = this.loadTsConfigOptions()

  const filesInSfiDir = ts.sys
    .readDirectory(path.dirname(this.sfiFilePath), ['.ts'], ['.d.ts'])
    .concat([path.join(path.dirname(this.sfiFilePath), '..', 'pylon.d.ts')])

  this.program = ts.createProgram(filesInSfiDir, tsConfigOptions)
  this.checker = this.program.getTypeChecker()  // Uses TypeScript Compiler API
}

Actual Usage:

// typescript-graphql-schemas/pylon/src/index.ts
// Completely native TypeScript, no decorators
export class Coffee implements Food {
  constructor(
    public id: Int,
    public name: string,
    public price: number,
    public sugarLevel: SugarLevel,
    public origin: string,
  ) {}
}

export const graphql = {
  Query: {
    user: (id: Int): User => { ... }  // Function signature automatically infers type
  }
}

Type Inference Mechanism:

Function parameter inference: Infers GraphQL input types from function parameter types (packages/pylon-builder/src/schema/schema-parser.ts)
Return type inference: Infers GraphQL output types from function return types
Class property inference: Infers GraphQL field types from class public properties
Union type inference: Automatically generates GraphQL Union types from TypeScript union types

Actual Usage Evidence:

// typescript-graphql-schemas/pylon/src/index.ts:227-237
export const graphql = {
  Query: {
    users: (): User[] => { ... },           // Automatically infers return [User!]!
    user: (id: Int): User => { ... },        // Automatically infers parameter Int!, return User!
    menu: (): MenuItem[] => { ... }          // Automatically infers Union type
  }
}

Configuration Requirements:

TypeScript configuration: Requires standard tsconfig.json, but no special configuration needed (lines 54-94 of packages/pylon-builder/src/schema/builder.ts)
No experimental features: Does not require experimentalDecorators or emitDecoratorMetadata
Type declaration file: Requires pylon.d.ts to extend types (typescript-graphql-schemas/pylon/pylon.d.ts)

Shortcomings:

⚠️ Build-time analysis: Although no runtime reflection is needed, build-time use of TypeScript Compiler API increases build complexity
⚠️ Type declaration file: Need to manually create pylon.d.ts to extend Context types (though this is standard TypeScript practice)

Conclusion: Minimal configuration. Only requires a small amount of intuitive configuration, mainly relies on TypeScript's own type inference and Compiler API static analysis. No decorators or reflection metadata required, but build-time analysis is needed.

1.4 Ecosystem Integration

Score: 2.0

Integration Method:

Deep Hono integration: app is a Hono instance (line 6 of packages/pylon/src/app/index.ts), cannot replace underlying framework
GraphQL Yoga integration: Uses GraphQL Yoga as GraphQL Server (lines 131-155 of packages/pylon/src/app/handler/pylon-handler.ts)
Envelop plugin support: Supports Envelop plugins through config.plugins (lines 21-27 of packages/pylon/src/index.ts)

Core Implementation Evidence:

// packages/pylon/src/app/index.ts:6
export const app = new Hono<Env>()  // Deeply integrated with Hono

// packages/pylon/src/app/handler/pylon-handler.ts:131-155
const yoga = createYoga({
  landingPage: false,
  graphqlEndpoint: '/graphql',
  ...config,
  graphiql: async () => resolveGraphiql(config),
  plugins: [
    useSentry(),
    useDisableIntrospection({ ... }),
    useViewer({ ... }),
    ...(config?.plugins || [])  // Supports Envelop plugins
  ],
  schema
})

Deployment Platform Support:

Cloudflare Workers: Official example (examples/cloudflare-drizzle-d1) demonstrates Cloudflare Workers deployment
Node.js: Supports standard Node.js environment (lines 40-42 of packages/pylon/package.json require Node >= 18)
Bun: Supports Bun runtime (official example examples/bun-testing)
Deno: Supports Deno runtime (official template packages/create-pylon/templates/deno)

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

import { app } from '@getcronit/pylon'

// app is a Hono instance, can directly use Hono middleware
app.use('*', async (c, next) => {
  c.set('loaders', createLoaders())
  await next()
})

export default app  // Export Hono app

Official Examples (examples/ directory):

cloudflare-drizzle-d1: Cloudflare Workers + Drizzle ORM integration
nodejs-subscriptions: Node.js subscription support
envelop-plugins: Envelop plugin integration example
interfaces-and-unions: Interface and union type examples

Shortcomings:

⚠️ Strong framework binding: Deeply integrated with Hono, cannot replace underlying Web framework
⚠️ GraphQL Server binding: Uses GraphQL Yoga, though can be extended through Envelop plugins, cannot be replaced
⚠️ Installation method: Although can be installed via npm install, framework design assumes Hono usage, integrating into other frameworks requires adaptation

Conclusion: Environment sensitive. Although installable, has special requirements for runtime environment (must use Hono as Web framework). Although supports multiple runtimes (Node.js, Bun, Deno, Cloudflare Workers), underlying framework binding limits flexibility.

Architecture Overall Score

Score: 2.5

Scoring Basis:

Dependency complexity: <-待评分-> (Medium dependencies, includes complete GraphQL Server and Web framework)
Build flow: <-待评分-> (Explicit build, must run build command)
Config & language magic: <-待评分-> (Minimal config, uses TypeScript Compiler API static analysis)
Ecosystem integration: <-待评分-> (Environment sensitive, deeply integrated with Hono, cannot flexibly replace)

Advantages:

Automatic type inference: Automatically generates Schema from source code through TypeScript Compiler API, reducing manual definitions
Zero decorators: Completely uses native TypeScript, no decorators or reflection metadata needed
Type safety: Automatically infers GraphQL types from TypeScript types, ensuring type consistency
Multi-runtime support: Supports Node.js, Bun, Deno, Cloudflare Workers

Disadvantages:

Must build: Cannot run directly, must execute build command to generate Schema first
Framework binding: Deeply integrated with Hono, cannot replace underlying Web framework
Many dependencies: Runtime dependencies include complete GraphQL Server and Web framework
Build complexity: Uses TypeScript Compiler API and code injection, build process is relatively complex

2. Type Definition

Core Implementation Mechanism

Pylon adopts TypeScript Compiler API static analysis + automatic inference to implement type definitions. The framework automatically generates GraphQL Schema by analyzing TypeScript source code (classes, interfaces, union types, function signatures). TypeScript type definitions are the single source of truth, GraphQL Schema is completely derived from TypeScript types.

Source Code Evidence:

Type analysis: packages/pylon-builder/src/schema/builder.ts (lines 96-143) uses TypeScript Compiler API to analyze types
Schema generation: packages/pylon-builder/src/schema/schema-parser.ts (lines 558-1043) parses types and generates GraphQL Schema
Business code example: typescript-graphql-schemas/pylon/src/index.ts (lines 13-87) defines TypeScript types, automatically generates GraphQL Schema

Actual Usage Flow:

// 1. Define TypeScript types
export interface Food {
  id: Int
  name: string
  price: number
}

export class Coffee implements Food {
  constructor(
    public id: Int,
    public name: string,
    public price: number,
    public sugarLevel: SugarLevel,
    public origin: string,
  ) {}
}

export type MenuItem = Coffee | Dessert

// 2. Automatically generate GraphQL Schema at build time
// .pylon/schema.graphql contains:
// interface MenuItem { id: Int!, name: String!, price: Number! }
// type Coffee implements MenuItem { ... }
// type Dessert implements MenuItem { ... }

Scoring Details

2.1 Single Source of Truth Implementation

Score: 4.0

Evidence:

TypeScript types are the source: typescript-graphql-schemas/pylon/src/index.ts (lines 13-87) defines TypeScript types
GraphQL Schema auto-generated: Automatically generates GraphQL Schema from TypeScript types (.pylon/schema.graphql)
Deep type inference: Supports automatic GraphQL type inference from class properties, function signatures, union types, etc.
Validation logic separated: Validation requires manual implementation using createDecorator (lines 129-168), does not support automatic type generation from validation rules

Code Example:

// typescript-graphql-schemas/pylon/src/index.ts:13-17
export interface Food {
  id: Int
  name: string
  price: number
}

// Automatically generated GraphQL Schema:
// interface MenuItem {
//   id: Int!
//   name: String!
//   price: Number!
// }

Core Implementation (packages/pylon-builder/src/schema/schema-parser.ts):

Lines 558-1043: processSchemaReference method analyzes TypeScript types and generates GraphQL Schema
Line 955: Uses getPublicPropertiesOfType to get class public properties
Line 1019: Checks if class implements interface

Shortcomings:

⚠️ Validation logic separated: Validation requires manual implementation (using createDecorator), does not support automatic type generation from validation rules (e.g., Zod)
⚠️ Explicit type markers needed: Some types need explicit use of marker types like Int, ID (line 1), rather than pure TypeScript types

Conclusion: Deep inference. Core definition is Schema, GraphQL Schema is automatically extracted through TypeScript Compiler API, requires minimal auxiliary configuration. But validation logic requires manual implementation, does not support automatic type generation from validation rules.

2.2 Enum & String Union Support

Score: 5.0

Evidence:

Zero-config reuse: Directly supports TypeScript string union types, no manual registration needed
Automatic conversion: String union types automatically convert to GraphQL enums

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Lines 10-11: Define string union types
export type SugarLevel = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'
export type OrderStatus = 'PENDING' | 'COMPLETED' | 'CANCELLED'

Generated GraphQL Schema (lines 67-88 of .pylon/schema.graphql):

enum OrderStatus {
    PENDING
    COMPLETED
    CANCELLED
}
enum SugarLevel {
    NONE
    LOW
    MEDIUM
    HIGH
}
enum SugarLevelInput {
    NONE
    LOW
    MEDIUM
    HIGH
}
enum OrderStatusInput {
    PENDING
    COMPLETED
    CANCELLED
}

Core Implementation (packages/pylon-builder/src/schema/type-definition-builder.ts):

Lines 175-200: isPrimitiveUnion detects string union types
Lines 185-197: Enum members automatically extracted and converted
Lines 199-220: Automatically generates enum type names

Official Example (examples/interfaces-and-unions/src/index.ts):

Supports various union type scenarios: class unions, object type unions, interface unions, etc.

Analysis:

✅ Completely zero-config, directly uses TypeScript string union types
✅ Automatically handles input and output enums (generates SugarLevel and SugarLevelInput)
✅ Enum member names automatically extracted from string literals, no duplicate definitions needed

Conclusion: Zero-config reuse. Directly supports TypeScript native string union types ('A' | 'B'), no manual registration required. Enum member names automatically extracted from string literals, completely zero-config.

2.3 Interface Inheritance & Union Type Experience

Score: 4.0

Evidence:

Automatic interface inheritance: When classes implement interfaces, interface fields automatically inherit to GraphQL Schema
Union types automatically handled: TypeScript union types automatically convert to GraphQL Union types
Smart interface detection: Framework automatically detects common fields in Union types, generates interfaces (lines 313-348 of packages/pylon-builder/src/schema/schema-parser.ts)

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Lines 13-17: Define interface
export interface Food {
  id: Int
  name: string
  price: number
}

// Lines 66-74: Class implements interface
export class Coffee implements Food {
  constructor(
    public id: Int,
    public name: string,
    public price: number,
    public sugarLevel: SugarLevel,
    public origin: string,
  ) {}
}

// Line 87: Define union type
export type MenuItem = Coffee | Dessert

Generated GraphQL Schema (.pylon/schema.graphql):

interface MenuItem {
  id: Int!
  name: String!
  price: Number!
}
type Coffee implements MenuItem {
  id: Int!
  name: String!
  price: Number!
  sugarLevel: SugarLevel!
  origin: String!
}
type Dessert implements MenuItem {
  id: Int!
  name: String!
  price: Number!
  calories: Number!
}

Core Implementation (packages/pylon-builder/src/schema/schema-parser.ts):

Lines 201-230: Detects common fields in Union types, automatically generates interfaces
Lines 234-273: Handles cases where classes implement interfaces
Lines 350-376: Generates __resolveType function for Union type resolution

Generated Resolver (.pylon/resolvers.js):

export const resolvers = {
  MenuItem: {
    __resolveType: function resolveType(node) {
      if (node && typeof node === 'object') {
        if ("id" in node && "name" in node && "price" in node && 
            "sugarLevel" in node && "origin" in node) {
          return 'Coffee'
        }
        if ("id" in node && "name" in node && "price" in node && 
            "calories" in node) {
          return 'Dessert'
        }
      }
    }
  }
}

Official Example (examples/interfaces-and-unions/src/index.ts):

Lines 3-26: Demonstrates classes implementing interfaces
Lines 28-50: Demonstrates Union types (with common fields, automatically generates interface)
Lines 52-65: Demonstrates Union types (without common fields)

Shortcomings:

⚠️ Union type resolution requires field checks: __resolveType determines type by checking field existence, need to ensure objects contain enough fields
⚠️ Need to manually return __typename: Need to manually set __typename field when creating objects (lines 300-307), though framework generates resolver, data source needs to contain type information

Conclusion: Smart inheritance. Supports field inheritance, Union type resolution handled through auto-generated __resolveType function, but need to ensure objects contain enough fields for type determination. Framework automatically detects common fields in Union types and generates interfaces.

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 3.5

Evidence:

Function signature automatic inference: Automatically infers GraphQL types from function parameters and return types
Class property automatic inference: Automatically infers GraphQL field types from class public properties
Complex type support: Supports Promise, arrays, optional types, union types, etc.

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Lines 227-237: Function signature automatic inference
export const graphql = {
  Query: {
    users: (): User[] => { ... },           // Automatically infers return [User!]!
    user: (id: Int): User => { ... },        // Automatically infers parameter Int!, return User!
    menu: (): MenuItem[] => { ... }          // Automatically infers Union type array
  }
}

Core Implementation (packages/pylon-builder/src/schema/schema-parser.ts):

Lines 842-1043: Analyzes function signatures, automatically infers parameter types and return types
Lines 82-87: Supports Promise types (type-definition-builder.ts)
Lines 159-174: Supports array types (type-definition-builder.ts)
Lines 89-90: Supports optional types (type-definition-builder.ts)

Type Inference Examples:

// Promise type automatically handled
async orders(): Promise<Order[]> {
  // Automatically infers return [Order!]!
}

// Optional parameters automatically handled
updateUser: (id: Int, name?: string, email?: string): User => {
  // Automatically infers name and email as optional parameters
}

// Array type automatically handled
items: Int[]  // Automatically infers as [Int!]!

Shortcomings:

⚠️ Explicit type markers needed: Some types need to use marker types like Int, ID (line 1), rather than pure TypeScript number, string, which limits fully automatic inference capability
⚠️ Union types in input fields not supported: Union types in input parameters will issue warning and default to first type (lines 829-836 of schema-parser.ts)

Core Implementation Evidence:

// packages/pylon-builder/src/schema/schema-parser.ts:829-836
if (firstType.isUnion() && !isPrimitive(firstType)) {
  consola.warn(
    `Warning: Union types in input fields are not supported yet. Defaulting to the first type (${this.checker.typeToString(
      firstType
    )}) at path: ${path.join(' > ')}`
  )
  firstType = firstType.types[0]
}

Analysis:

✅ Powerful automatic inference capability: Function signatures, class properties, Promise, arrays, optional types, etc. can all be automatically inferred
✅ TypeScript Compiler API deep analysis: Implements complete type inference through static analysis
⚠️ Explicit type markers needed: Marker types like Int, ID need explicit use, cannot completely rely on native TypeScript types
⚠️ Input field Union limitation: Union types in input parameters not supported, this is a clear feature limitation

Conclusion: Powerful inference. Can automatically derive most types through TypeScript Compiler API, function signatures and class properties can be automatically inferred, supports complex scenarios like Promise, arrays, optional types. But explicit type markers (Int, ID) and input field Union not supported limitation affects fully automatic inference capability.

Type Definition Overall Score

Score: 3.75

Scoring Basis:

Single source of truth: 4.0 (Deep inference, but validation logic requires manual implementation)
Enum & string union: 5.0 (Zero-config reuse, completely automatic)
Interface inheritance & union types: 4.0 (Smart inheritance, but requires field checks)
Type inference strength: 3.5 (Powerful inference, function signatures and class properties automatically inferred, but explicit type markers needed)

Advantages:

Completely automatic inference: Automatically generates GraphQL Schema from TypeScript types, no manual definitions needed
Zero-config enums: String union types automatically convert to GraphQL enums, completely zero-config
Smart interface detection: Automatically detects common fields in Union types and generates interfaces
Type safety: Ensures type consistency through TypeScript Compiler API
Powerful type inference: Function signatures, class properties, Promise, arrays, optional types, etc. can all be automatically inferred

Disadvantages:

Validation logic separated: Validation requires manual implementation, does not support automatic type generation from validation rules
Explicit type markers needed: Some types need to use marker types like Int, ID, cannot completely rely on native TypeScript types
Input field Union not supported: Union types in input parameters will issue warning and default to first type

3. Resolvers & Validation

Core Implementation Mechanism

Pylon adopts functional Resolver + decorator validation to implement resolver definitions. Resolvers are directly defined as regular functions, parameter types automatically inferred from function signatures, validation implemented through createDecorator, Field Resolvers implemented through class async methods, DataLoader requires manual creation and integration.

Source Code Evidence:

Resolver transformation: packages/pylon/src/define-pylon.ts (lines 165-347) converts functional Resolvers to GraphQL Resolvers
Parameter handling: packages/pylon/src/define-pylon.ts (lines 110-158) spreadFunctionArguments function handles parameter mapping
Validation decorator: packages/pylon/src/create-decorator.ts (lines 3-68) implements validation decorator
Business code example: typescript-graphql-schemas/pylon/src/index.ts (lines 227-398) demonstrates Resolver definitions

Actual Usage Flow:

// 1. Define Resolver functions
export const graphql = {
  Query: {
    user: (id: Int): User => {
      const u = userMap.get(id)
      if (!u) throw new GraphQLError('User not found')
      return new User(u.id, u.name, u.email)
    }
  },
  Mutation: {
    createUser: validateEmail((name: string, email: string): User => {
      // Validation logic in validateEmail decorator
      const id = incrementId()
      return new User(id, name, email)
    })
  }
}

// 2. Field Resolver implemented through class methods
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)
  }
}

Scoring Details

3.1 Developer Experience (Code Conciseness)

Score: 4.5

Evidence:

Functional definition: typescript-graphql-schemas/pylon/src/index.ts (lines 227-270) directly uses functions to define Resolvers, code is extremely concise
Automatic type inference: Function parameters and return types automatically inferred, no manual GraphQL type declarations needed
Validation decorator: Uses createDecorator to implement validation, code is concise (lines 129-168)
Field Resolver concise: Implemented through class async methods, code is intuitive (lines 96-99)

Code Example:

// Query Resolver - extremely concise definition
export const graphql = {
  Query: {
    users: (): User[] => {
      return Array.from(userMap.values()).map((u) => new User(u.id, u.name, u.email))
    },
    user: (id: Int): User => {
      const u = userMap.get(id)
      if (!u) throw new GraphQLError('User not found')
      return new User(u.id, u.name, u.email)
    }
  },
  Mutation: {
    createUser: validateEmail((name: string, email: string): User => {
      const id = incrementId()
      return new User(id, name, email)
    })
  }
}

// Field Resolver - implemented through class methods
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)
  }
}

Core Implementation (packages/pylon/src/define-pylon.ts):

Lines 165-347: resolversToGraphQLResolvers function converts functional Resolvers to GraphQL Resolvers
Lines 110-158: spreadFunctionArguments function handles parameter mapping, maps from GraphQL parameters to function parameters
Lines 44-109: wrapFunctionsRecursively function recursively wraps functions, supports nested objects and methods

Shortcomings:

⚠️ Need to manually create DataLoader: DataLoader requires manual creation and configuration (lines 174-213)
⚠️ Need to manually set Context: Need to manually set loaders in middleware (lines 222-225)

Analysis:

✅ Extremely concise code: Functional definition, almost no boilerplate
✅ Automatic type inference: Parameter types and return types completely automatically inferred
✅ Validation decorator concise: Uses createDecorator to implement validation, code is clear
⚠️ DataLoader requires manual integration: Requires manual creation and configuration, more boilerplate

Conclusion: Clean code, moderate boilerplate. Functional definition is extremely concise, automatic type inference, but DataLoader requires manual integration.

3.2 Modular Design (Domain-Driven Development Support)

Score: 0.0

Evidence:

Organized by operation type: All Resolvers are in one graphql object, organized by Query/Mutation (typescript-graphql-schemas/pylon/src/index.ts lines 227-398)
Type definitions separated from Resolvers: Type definitions (lines 13-123) and Resolvers (lines 227-398) are in the same file, but logically separated
Field Resolvers in classes: Field Resolvers implemented through class methods (lines 96-122), together with type definitions
Requires manual organization: Framework does not enforce modularity, developers need to consciously split files by domain

Code Example:

// All Resolvers in one object
export const graphql = {
  Query: {
    // User queries
    users: (): User[] => { ... },
    user: (id: Int): User => { ... },

    // Menu queries
    menu: (): MenuItem[] => { ... },
    menuItem: (id: Int): MenuItem | undefined => { ... },

    // Order queries
    orders: (): Order[] => { ... },
    order: (id: Int): Order | undefined => { ... },
  },
  Mutation: {
    // User mutations
    createUser: validateEmail((name: string, email: string): User => { ... }),
    // Menu mutations
    createCoffee: (name: string, price: number, ...): Coffee => { ... },
    // Order mutations
    createOrder: validateCreateOrder((userId: Int, items: Int[]): Order => { ... }),
  }
}

Analysis:

⚠️ No modularity consideration: Completely organized by operation type, all Query/Mutation in one object
⚠️ Easy to write coupled giant files: As business grows, single file becomes very large
✅ Field Resolvers in classes: Field Resolvers implemented through class methods, together with type definitions, logic is clear
⚠️ Requires manual merging: If splitting files by domain, need to manually merge graphql object

Conclusion: No modularity consideration. Completely organized by operation type (Query/Mutation), requires manual merging of arrays or objects, easy to write coupled giant files.

3.3 Parameter Definition & Type Inference

Score: 5.0

Evidence:

Parameter types completely automatically inferred: Automatically infers GraphQL parameter types from function signatures (lines 218-235 of packages/pylon/src/define-pylon.ts)
Supports optional parameters: TypeScript optional parameters automatically convert to GraphQL optional parameters (line 279 of typescript-graphql-schemas/pylon/src/index.ts)
Parameter order automatically handled: spreadFunctionArguments function automatically handles parameter order (lines 110-158 of packages/pylon/src/define-pylon.ts)

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Parameter types completely automatically inferred
user: (id: Int): User => { ... }  // Automatically infers parameter Int!

// Optional parameters automatically handled
updateUser: (id: Int, name?: string, email?: string): User => {
  // name and email automatically inferred as optional parameters
}

// Array parameters automatically handled
createOrder: (userId: Int, items: Int[]): Order => {
  // items automatically inferred as [Int!]!
}

Core Implementation (packages/pylon/src/define-pylon.ts):

Lines 218-235: Gets field parameters from GraphQL Schema, automatically maps to function parameters
Lines 110-158: spreadFunctionArguments function handles parameter mapping and order
Line 144: orderedArgs automatically arranged by function parameter order

Generated GraphQL Schema (.pylon/schema.graphql):

type Query {
  user(id: Int!): User!
}

type Mutation {
  updateUser(id: Int!, name: String, email: String): User!
  createOrder(userId: Int!, items: [Int!]!): Order!
}

Analysis:

✅ Parameter types completely automatically inferred, no manual declarations needed
✅ Supports optional parameters, automatically converts to GraphQL optional parameters
✅ Supports array parameters, automatically infers as list types
✅ IDE hints complete, types automatically derived from Schema definitions

Conclusion: Parameter types completely automatically inferred, no manual declarations needed, IDE hints complete. Supports chained API or function parameter automatic inference, types automatically derived from Schema definitions.

3.4 Input Validation Mechanism

Score: 3.0

Evidence:

Decorator validation: Uses createDecorator to implement validation (lines 3-68 of packages/pylon/src/create-decorator.ts)
Validation logic separated: Validation logic separated from business logic, code is clear (lines 129-168 of typescript-graphql-schemas/pylon/src/index.ts)
Requires manual validation logic: All validation logic requires manual implementation (lines 129-168)

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Define validation decorator
const validateEmail = createDecorator(async (name: string, email: string) => {
  if (!email || !email.includes('@')) {
    throw new ServiceError('Invalid email format', {
      code: 'INVALID_EMAIL',
      statusCode: 400,
    })
  }
})

// Use validation decorator
createUser: validateEmail((name: string, email: string): User => {
  // Validation logic executed in decorator
  const id = incrementId()
  return new User(id, name, email)
})

Core Implementation (packages/pylon/src/create-decorator.ts):

Lines 3-68: createDecorator function implements validation decorator
Lines 24-27: Decorator executes validation logic before function execution
Lines 35-40: Supports function decorator pattern

Validation Example:

// Complex validation logic
const validateCreateOrder = createDecorator(async (userId: Int, items: Int[]) => {
  if (items.length === 0) {
    throw new ServiceError('At least one item is required', {
      code: 'INVALID_ORDER',
      statusCode: 400,
    })
  }
  if (!userMap.has(userId)) {
    throw new ServiceError('User not found', {
      code: 'USER_NOT_FOUND',
      statusCode: 400,
    })
  }
  for (const itemId of items) {
    if (!menuItemMap.has(itemId)) {
      throw new ServiceError('Menu item not found', {
        code: 'MENU_ITEM_NOT_FOUND',
        statusCode: 400,
      })
    }
  }
})

Shortcomings:

⚠️ No built-in validation: Does not support declarative validation (e.g., z.email()), requires manual validation logic
⚠️ Validation code duplication: Each validation logic requires manual implementation, validation code may be duplicated
⚠️ No format validation: Does not support format validation (e.g., email format, URL format, etc.), requires manual implementation

Analysis:

✅ Validation logic separated from business logic, code is clear
✅ Uses decorator pattern, easy to reuse
⚠️ Requires manual validation logic, does not support declarative validation
⚠️ Validation code may be duplicated, no built-in validation library integration

Conclusion: Supports validation, but requires manual validation logic. Requires manual validation function calls, validation code mixed with business logic. All validation logic needs to be manually written in Resolvers, validation code duplicated.

3.5 Batch Loading (DataLoader) Integration

Score: <-待评分->

Evidence:

Requires manual DataLoader creation: DataLoader requires manual creation and configuration (lines 174-213 of typescript-graphql-schemas/pylon/src/index.ts)
Requires manual Context setup: Need to manually set loaders in middleware (lines 222-225)
Requires manual calls: Need to manually call loaders in Field Resolvers (lines 96-122)

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// 1. Manually create DataLoader
export const createLoaders = () => {
  return {
    userOrders: new DataLoader<number, Order[]>(async (userIds) => {
      // Batch loading logic
      return userIds.map((id) => orderGroups.get(id) ?? [])
    }),
    users: new DataLoader<number, User>(async (userIds) => {
      return userIds.map((id) => {
        const u = userMap.get(id)
        if (!u) return new Error('User not found')
        return new User(u.id, u.name, u.email)
      })
    }),
  }
}

// 2. Manually set Context
app.use('*', async (c, next) => {
  c.set('loaders', createLoaders())
  await next()
})

// 3. Manually call DataLoader
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)
  }
}

Analysis:

⚠️ Requires manual DataLoader instance creation: Each DataLoader requires manual creation and configuration
⚠️ Requires manual Context type definition: Need to manually define Context types in pylon.d.ts (typescript-graphql-schemas/pylon/pylon.d.ts)
⚠️ Requires manual Context setup: Need to manually set loaders in middleware
⚠️ Requires manual calls: Need to manually call loaders in Field Resolvers
⚠️ Lots of boilerplate: Requires significant boilerplate to integrate DataLoader

Conclusion: Provides no built-in dataloader support, requires significant context boilerplate and dataloader boilerplate. Requires manual DataLoader instance creation, Context type definition, Context injection configuration, lots of boilerplate.

Resolvers & Validation Overall Score

Score: 2.5

Scoring Basis:

Developer experience: 4.5 (Clean code, but DataLoader requires manual integration)
Modular design: 0.0 (No modularity consideration, completely organized by operation type)
Parameter definition & type inference: 5.0 (Parameter types completely automatically inferred)
Input validation mechanism: 3.0 (Supports validation, but requires manual validation logic)
Batch loading (DataLoader) integration: 0.0 (No built-in support, requires significant boilerplate)

Advantages:

Extremely concise code: Functional definition, almost no boilerplate
Automatic type inference: Parameter types and return types completely automatically inferred
Validation decorator: Uses createDecorator to implement validation, code is clear
Field Resolver concise: Implemented through class async methods, code is intuitive

Disadvantages:

No modularity support: Completely organized by operation type, easy to write coupled giant files
Validation requires manual implementation: Does not support declarative validation, requires manual validation logic
DataLoader requires manual integration: Requires significant boilerplate to integrate DataLoader
Context requires manual configuration: Requires manual Context setup and type definitions

4. Built-in Features

Feature Support Overview

Pylon provides some built-in features through deep integration with Hono and GraphQL Yoga, while supporting extended features through Envelop plugin system. Core features include Context injection, Middleware support, custom scalars, Subscriptions, etc., but DataLoader, Directives, query complexity analysis and other features require manual implementation or implementation through plugins.

Feature Support Details

Feature	Support Status	Description
Directives	⚠️ Plugin/Extra	Not built-in, but can be implemented through Envelop plugins, requires extra configuration
Extensions	⚠️ Plugin/Extra	Not built-in, but can be implemented through Envelop plugins, requires extra configuration
DataLoader	⛔ Cannot implement	Provides no built-in dataloader support, requires manual creation and configuration
Custom Scalars	✅ Built-in	Built-in common scalar types like Date, JSON, Object, Void, Number
Subscription	✅ Built-in	Native GraphQL Subscriptions support, implemented through `experimentalCreatePubSub`
Context Injection	✅ Built-in	Native support for injecting context in Resolvers, implemented through `getContext()`
Middleware	✅ Built-in	Native Hono middleware support, can inject logic before/after Resolver execution
Query Complexity Analysis	⚠️ Plugin/Extra	Not built-in, but can be implemented through Envelop plugins, requires extra configuration
Depth Limiting	⚠️ Plugin/Extra	Not built-in, but can be implemented through Envelop plugins, requires extra configuration

Detailed Feature Analysis

4.1 Directives Support

Support Status: ⚠️ Plugin/Extra Implementation

Evidence:

No built-in support: No Directives-related implementation found in packages/pylon/src
Can be implemented through Envelop plugins: packages/pylon/src/app/handler/pylon-handler.ts (line 152) supports adding Envelop plugins through config.plugins
Requires extra configuration: Need to manually install and configure Envelop Directives plugin

Implementation Method:

// Implement Directives through Envelop plugins
import { useSchema } from '@envelop/core'
import { useDirective } from '@envelop/directives'

export const config: PylonConfig = {
  plugins: [
    useDirective({
      // Directives configuration
    })
  ]
}

Conclusion: Not built-in, but can be implemented through official plugins, community plugins, or manual implementation, requires extra configuration and boilerplate.

4.2 Extensions Support

Support Status: ⚠️ Plugin/Extra Implementation

Evidence:

No built-in support: No Extensions-related implementation found in packages/pylon/src
Can be implemented through Envelop plugins: Supports adding Envelop plugins through config.plugins (line 152 of packages/pylon/src/app/handler/pylon-handler.ts)
ServiceError supports extensions: packages/pylon/src/define-pylon.ts (lines 349-367) ServiceError class supports extensions field

Implementation Method:

// Implement Extensions through Envelop plugins
import { useExtendContext } from '@envelop/core'

export const config: PylonConfig = {
  plugins: [
    useExtendContext(async (context) => {
      return {
        // Extension information
      }
    })
  ]
}

Conclusion: Not built-in, but can be implemented through plugins or manual Context extension to achieve similar functionality, requires extra configuration.

4.3 DataLoader Integration

Support Status: ⛔ Cannot Implement

Evidence:

No built-in support: No DataLoader-related built-in implementation found in packages/pylon/src
Requires manual creation: typescript-graphql-schemas/pylon/src/index.ts (lines 174-213) requires manual DataLoader instance creation
Requires manual Context setup: Need to manually set loaders in middleware (lines 222-225)
Requires manual calls: Need to manually call loaders in Field Resolvers (lines 96-122)

Actual Usage:

// 1. Manually create DataLoader
export const createLoaders = () => {
  return {
    userOrders: new DataLoader<number, Order[]>(async (userIds) => {
      // Batch loading logic
    }),
  }
}

// 2. Manually set Context
app.use('*', async (c, next) => {
  c.set('loaders', createLoaders())
  await next()
})

// 3. Manually call DataLoader
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)
  }
}

Conclusion: Provides no built-in dataloader support, and cannot be implemented through plugins, requires significant context boilerplate and dataloader boilerplate.

4.4 Custom Scalars

Support Status: ✅ Built-in

Evidence:

Built-in common scalars: packages/pylon/src/app/handler/pylon-handler.ts (lines 68-104) built-in Date, JSON, Object, Void, Number and other scalar types
Uses graphql-scalars: Lines 2-7 import scalar types from graphql-scalars library
Custom Number scalar: Lines 73-104 define custom Number scalar, supports integers and floats

Built-in Scalar Types:

// packages/pylon/src/app/handler/pylon-handler.ts:68-104
resolvers: {
  Date: DateTimeISOResolver,      // DateTime scalar
  JSON: JSONResolver,              // JSON scalar
  Object: JSONObjectResolver,      // Object scalar
  Void: GraphQLVoid,               // Void scalar
  Number: new GraphQLScalarType({  // Custom number scalar
    name: 'Number',
    description: 'Custom scalar that handles both integers and floats',
    parseValue(value) { ... },
    parseLiteral(ast) { ... },
    serialize(value) { ... }
  })
}

Conclusion: Built-in common scalar types (such as DateTime, JSON, BigInt, Date, etc.), defining new scalar types is simple, API is intuitive and type-safe.

4.5 Subscription

Support Status: ✅ Built-in

Evidence:

Native support: packages/pylon/src/index.ts (line 19) exports experimentalCreatePubSub
Official example: examples/nodejs-subscriptions/src/index.ts demonstrates Subscription usage
GraphQL Yoga support: Uses GraphQL Yoga under the hood, natively supports Subscriptions

Actual Usage (examples/nodejs-subscriptions/src/index.ts):

import { experimentalCreatePubSub } from '@getcronit/pylon'

const pubSub = experimentalCreatePubSub<{
  [Events.postCreated]: [post: Post]
}>()

export const graphql = {
  Query: {
    posts
  },
  Mutation: {
    createPost: Post.create
  },
  Subscription: {
    postCreated: () => pubSub.subscribe(Events.postCreated)
  }
}

Core Implementation:

packages/pylon/src/index.ts (line 19): Exports experimentalCreatePubSub, from graphql-yoga
packages/pylon/src/define-pylon.ts (lines 306-320): Supports Subscription Resolver transformation

Conclusion: Native GraphQL Subscriptions support, supports real-time data push, underlying transport protocol has good compatibility (WebSocket, SSE, etc.), API is concise.

4.6 Context Injection

Support Status: ✅ Built-in

Evidence:

Native support: packages/pylon/src/context.ts (lines 29-51) implements asyncContext and getContext()
Type inference complete: packages/pylon/src/context.ts (lines 9-27) defines Context type, type inference is complete
Good IDE hints: Gets context through getContext(), type-safe

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Get Context
export class User {
  async orders(): Promise<Order[]> {
    const loaders = getContext().get('loaders')
    return loaders.userOrders.load(this.id)
  }
}

// Set Context (through Hono middleware)
app.use('*', async (c, next) => {
  c.set('loaders', createLoaders())
  await next()
})

Core Implementation (packages/pylon/src/context.ts):

Line 29: asyncContext uses AsyncLocalStorage to implement context storage
Lines 31-47: getContext() function gets current context
Lines 49-51: setContext() function sets context

Conclusion: Native support for injecting context in Resolvers, context type inference is complete, IDE hints are good, no manual type declarations needed.

4.7 Middleware

Support Status: ✅ Built-in

Evidence:

Hono middleware: packages/pylon/src/app/index.ts (line 6) app is a Hono instance, supports all Hono middleware
Built-in middleware: Line 8 uses Sentry middleware, lines 10-20 use AsyncLocalStorage middleware
Supports chained calls: Can chain multiple middleware

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Use Hono middleware
app.use('*', async (c, next) => {
  c.set('loaders', createLoaders())
  await next()
})

Core Implementation (packages/pylon/src/app/index.ts):

Line 6: app is a Hono instance
Line 8: Built-in Sentry middleware
Lines 10-20: AsyncLocalStorage middleware, for context management
Lines 22-26: Request ID middleware

Conclusion: Native support for injecting middleware logic before/after Resolver execution (such as logging, permission checks, performance monitoring), API is concise, supports chained calls.

4.8 Query Complexity Analysis

Support Status: ⚠️ Plugin/Extra Implementation

Evidence:

No built-in support: No query complexity analysis-related implementation found in packages/pylon/src
Can be implemented through Envelop plugins: Supports adding Envelop plugins through config.plugins (line 152 of packages/pylon/src/app/handler/pylon-handler.ts)

Implementation Method:

// Implement query complexity analysis through Envelop plugins
import { useQueryComplexity } from '@envelop/query-complexity'

export const config: PylonConfig = {
  plugins: [
    useQueryComplexity({
      // Complexity configuration
    })
  ]
}

Conclusion: Not built-in, but can be implemented through plugins or manual complexity analysis, requires extra configuration and custom logic.

4.9 Depth Limiting

Support Status: ⚠️ Plugin/Extra Implementation

Evidence:

No built-in support: No depth limiting-related implementation found in packages/pylon/src
Can be implemented through Envelop plugins: Supports adding Envelop plugins through config.plugins (line 152 of packages/pylon/src/app/handler/pylon-handler.ts)

Implementation Method:

// Implement depth limiting through Envelop plugins
import { useDepthLimit } from '@envelop/depth-limit'

export const config: PylonConfig = {
  plugins: [
    useDepthLimit({
      maxDepth: 10
    })
  ]
}

Conclusion: Not built-in, but can be implemented through plugins or manual depth limiting, requires extra configuration.

Built-in Features Overall Score

Score: 3.1

Scoring Basis:

Directives: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
Extensions: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
DataLoader: ⛔ Cannot implement (0 points) - Provides no built-in dataloader support
Scalars: ✅ Built-in (5 points) - Built-in Date, JSON, Object, Void, Number and other common scalar types
Subscription: ✅ Built-in (5 points) - Native support, implemented through experimentalCreatePubSub
Context: ✅ Built-in (5 points) - Native support, implemented through getContext()
Middleware: ✅ Built-in (5 points) - Native Hono middleware support, can inject logic before/after Resolver execution
Query Complexity: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
Depth Limiting: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins

Total: 28/45 = 3.1/5.0

Scoring Basis:

Directives support: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
Extensions support: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
DataLoader: ⛔ Cannot implement (0 points) - Provides no built-in dataloader support
Custom scalars: ✅ Built-in (5 points) - Built-in Date, JSON, Object, Void, Number and other common scalar types
Subscription: ✅ Built-in (5 points) - Native support, implemented through experimentalCreatePubSub
Context injection: ✅ Built-in (5 points) - Native support, implemented through getContext()
Middleware: ✅ Built-in (5 points) - Native Hono middleware support, can inject logic before/after Resolver execution
Query complexity analysis: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins
Depth limiting: ⚠️ Plugin/Extra (2 points) - Not built-in, but can be implemented through Envelop plugins

Advantages:

Context injection complete: Native context injection support, type inference complete
Middleware support: Through Hono middleware support, powerful functionality
Rich custom scalars: Built-in common scalar types
Subscriptions support: Native GraphQL Subscriptions support

Disadvantages:

No built-in DataLoader support: Requires manual creation and configuration, lots of boilerplate
No built-in Directives support: Needs to be implemented through Envelop plugins
No built-in query complexity analysis: Needs to be implemented through Envelop plugins
No built-in depth limiting: Needs to be implemented through Envelop plugins

5. Ecosystem Integration

Ecosystem Integration Overview

Pylon provides good runtime compatibility through deep integration with Hono and GraphQL Yoga, supporting multiple runtimes (Node.js, Bun, Deno, Cloudflare Workers). For ORM integration, officially recommends Prisma and provides @getcronit/prisma-extended-models package to enhance integration. But for validation library integration, requires manual validation logic implementation, does not support automatic integration with mainstream validation libraries.

Scoring Details

5.1 ORM Integration Depth

Score: <-待评分->

Evidence:

Supports Prisma: Official documentation (docs/pages/docs/integrations/databases.mdx) recommends Prisma, provides detailed integration guide
Supports Drizzle: Official example (examples/cloudflare-drizzle-d1) demonstrates Drizzle ORM integration
prisma-extended-models package: Provides @getcronit/prisma-extended-models package to enhance Prisma integration (lines 51-135 of docs/pages/docs/integrations/databases.mdx)
Requires manual integration: Requires manual Prisma Client instance creation, requires manual query logic

Actual Usage (examples/cloudflare-drizzle-d1/src/index.ts):

import {app, getContext} from '@getcronit/pylon'
import {drizzle} from 'drizzle-orm/d1'

const getDb = () => {
  const ctx = getContext()
  return drizzle(ctx.env.DB, {schema})
}

export const graphql = {
  Query: {
    async users() {
      const db = getDb()
      const users = await db.query.user.findMany()
      return users.map(user => ({
        ...user,
        roles: JSON.parse(user.roles)
      }))
    }
  }
}

Prisma Integration Example (docs/pages/docs/integrations/databases.mdx):

import {app} from '@getcronit/pylon'
import {PrismaClient} from '@prisma/client'

const prisma = new PrismaClient()

export const graphql = {
  Query: {
    getUser: async (id: number) => {
      return await prisma.user.findUnique({
        where: {id}
      })
    }
  }
}

prisma-extended-models package:

Provides bunx prisma-extended-models generate command to generate extended models
Automatically resolves relations and creates paginatable connections
Requires extra installation and configuration

Shortcomings:

⚠️ Requires manual integration: Requires manual ORM client instance creation, requires manual query logic
⚠️ Type synchronization requires manual maintenance: Although Prisma has type generation, need to manually ensure type synchronization
⚠️ Relation resolution requires extra configuration: Using prisma-extended-models requires extra installation and configuration

Analysis:

✅ Supports mainstream ORMs (Prisma, Drizzle)
✅ Official provides integration guides and examples
✅ Provides prisma-extended-models package to enhance integration
⚠️ Requires manual integration, not zero boilerplate
⚠️ Type synchronization requires manual maintenance

Conclusion: Basic integration. Supports ORM integration through plugins or manual methods, can reuse some model definitions, but requires more configuration and boilerplate.

5.2 Validation Library Integration

Score: <-待评分->

Evidence:

No validation library integration: No integration of Zod, Valibot, Yup and other validation libraries found in packages/pylon/src
Requires manual validation implementation: Validation manually implemented through createDecorator (packages/pylon/src/create-decorator.ts)
Validation logic separated from Schema definition: Validation logic requires manual writing, cannot automatically derive types from validation rules

Actual Usage (typescript-graphql-schemas/pylon/src/index.ts):

// Requires manual validation logic implementation
const validateEmail = createDecorator(async (name: string, email: string) => {
  if (!email || !email.includes('@')) {
    throw new ServiceError('Invalid email format', {
      code: 'INVALID_EMAIL',
      statusCode: 400,
    })
  }
})

// Use validation decorator
createUser: validateEmail((name: string, email: string): User => {
  // Business logic
})

Analysis:

⚠️ No validation library integration: Completely does not support mainstream validation libraries (Zod, Valibot, Yup, etc.)
⚠️ Validation logic separated from Schema definition: Validation logic requires manual writing, cannot automatically derive types from validation rules
⚠️ Requires significant boilerplate: Each validation logic requires manual implementation, validation code may be duplicated

Conclusion: No integration. Completely does not support validation library integration, must manually write all validation logic.

5.3 GraphQL Server Compatibility

Score: <-待评分->

Evidence:

Binds GraphQL Yoga: packages/pylon/src/app/handler/pylon-handler.ts (line 8) uses createYoga to create GraphQL Server
Cannot replace Server: Core implementation depends on GraphQL Yoga, cannot integrate into other GraphQL Servers (e.g., Apollo Server)
Supports Envelop plugins: Line 152 supports adding Envelop plugins through config.plugins, but underlying is still GraphQL Yoga

Core Implementation (packages/pylon/src/app/handler/pylon-handler.ts):

// Lines 131-155: Must use GraphQL Yoga
const yoga = createYoga({
  landingPage: false,
  graphqlEndpoint: '/graphql',
  ...config,
  graphiql: async () => resolveGraphiql(config),
  plugins: [
    useSentry(),
    useDisableIntrospection({ ... }),
    useViewer({ ... }),
    ...(config?.plugins || [])  // Supports Envelop plugins
  ],
  schema
})

Analysis:

⚠️ Forced binding to GraphQL Yoga: Core implementation depends on GraphQL Yoga, cannot replace
⚠️ Cannot integrate into other Servers: Although supports Envelop plugins, underlying is still GraphQL Yoga
✅ Envelop plugin support: Supports extending functionality through Envelop plugins

Conclusion: Binds to specific Server. Forced binding to specific GraphQL Server (GraphQL Yoga), cannot integrate into other Servers.

5.4 Toolchain Integration

Score: <-待评分->

TypeScript/JavaScript Support

TypeScript Support:

✅ Core language: All official templates and examples use TypeScript (.ts files)
- packages/create-pylon/templates/node/default/src/index.ts
- packages/create-pylon/templates/bun/default/src/index.ts
- packages/create-pylon/templates/cf-workers/default/src/index.ts
- packages/create-pylon/templates/deno/default/src/index.ts
✅ TypeScript configuration: Provides official TypeScript configuration template tsconfig.pylon.json
- packages/pylon/tsconfig.pylon.json (lines 1-24) contains complete TypeScript configuration
- All template projects inherit this configuration (line 2 of packages/create-pylon/templates/shared/tsconfig.json)

JavaScript Support:

⚠️ Partial support: tsconfig.pylon.json sets allowJs: true (line 13), allows importing .js files from TypeScript
⚠️ But no pure JavaScript examples:
- All official templates and examples are TypeScript files
- Build tool (pylon-builder) uses esbuild's loader: 'ts' (line 64 of packages/pylon-builder/src/bundler/bundler.ts), mainly processes TypeScript
- Documentation and examples do not provide pure JavaScript usage guide

Code Evidence:

packages/pylon/tsconfig.pylon.json (lines 12-13):

"jsx": "react-jsx", // support JSX
"allowJs": true, // allow importing `.js` from `.ts`

packages/pylon-builder/src/bundler/bundler.ts (lines 63-64):

return {
  loader: 'ts',
  contents: contents + `...`
}

Runtime Environment Support

Node.js:

✅ Explicit support: Provides official Node.js templates and examples
- packages/create-pylon/templates/node/default/ provides complete Node.js template
- examples/nodejs-subscriptions/package.json (line 13) uses @hono/node-server to adapt Node.js
- examples/nodejs-subscriptions/package.json (line 8) dev command: "dev": "pylon dev -c \"node --enable-source-maps .pylon/index.js\""

Bun:

✅ Explicit support: Provides official Bun templates and examples
- packages/create-pylon/templates/bun/default/ provides complete Bun template
- examples/bun-testing/package.json (line 8) dev command: "dev": "pylon dev -c 'bun run .pylon/index.js'"
- README.md (lines 171-173) explicitly lists Bun as supported runtime

Deno:

✅ Explicit support: Provides official Deno template
- packages/create-pylon/templates/deno/default/ provides complete Deno template
- packages/create-pylon/templates/deno/default/deno.json (line 7) dev command: "dev": "pylon dev -c 'deno run -A .pylon/index.js --config tsconfig.json'"
- packages/create-pylon/templates/deno/default/src/index.ts (lines 12-17) uses Deno.serve() to start service

Cloudflare Workers:

✅ Explicit support: Provides official Cloudflare Workers templates and examples
- packages/create-pylon/templates/cf-workers/default/ provides complete Cloudflare Workers template
- examples/cloudflare-drizzle-d1/package.json (line 6) deploy command: "deploy": "pylon build && wrangler deploy"
- README.md (line 155) explicitly states "Pylon is fully compatible with Cloudflare Workers"

Browser:

❌ Not supported: Pylon is a server-side GraphQL framework, cannot run in browser environment
- Core implementation depends on Hono (line 2 of packages/pylon/src/app/index.ts), which is a server-side Web framework
- Depends on GraphQL Yoga (line 33 of packages/pylon/package.json), which is a server-side GraphQL Server
- All examples and templates are server-side code, no browser running examples or documentation

Code Evidence:

packages/create-pylon/templates/node/default/src/index.ts (lines 1-15):

import {app} from '@getcronit/pylon'
import {serve} from '@hono/node-server'

export const graphql = {
  Query: {
    hello: () => {
      return 'Hello, world!'
    }
  },
  Mutation: {}
}

serve(app, info => {
  console.log(`Server running at ${info.port}`)
})

packages/create-pylon/templates/deno/default/src/index.ts (lines 12-17):

Deno.serve(
  {
    port: 3000
  },
  app.fetch
)

Build Tool Support

esbuild:

✅ Core build tool: Pylon's build system is completely based on esbuild
- packages/pylon-builder/src/bundler/bundler.ts (line 4) imports esbuild
- packages/pylon-builder/src/bundler/bundler.ts (lines 94-109) uses esbuild.build() for building
- packages/pylon-builder/package.json (line 25) depends on "esbuild": "^0.23.1"
- Users must use pylon build or pylon dev commands, these commands internally use esbuild

Webpack:

⚠️ No official configuration examples:
- Documentation and examples do not provide webpack configuration examples
- User projects cannot directly use webpack to build Pylon server code
- Must use pylon build command to generate build artifacts, then can manually integrate into webpack workflow

Vite:

⚠️ No official configuration examples:
- Documentation and examples do not provide vite configuration examples
- The vite project in examples/cloudflare-pages-worker-monorepo/apps/vite-project/ is a client project, not the Pylon server itself
- User projects cannot directly use vite to build Pylon server code
- Must use pylon build command to generate build artifacts

Rspack:

⚠️ No official configuration examples:
- Documentation and examples do not provide rspack configuration examples
- No rspack-related configuration files or documentation
- User projects cannot directly use rspack to build Pylon server code

Build Flow Limitations:

⚠️ Must use Pylon CLI: Users must use pylon build or pylon dev commands
- packages/pylon-dev/src/index.ts (lines 19-37) implements build command
- packages/pylon-dev/src/index.ts (lines 40-278) implements dev command
- These commands internally call @getcronit/pylon-builder for building
- Cannot bypass Pylon CLI to directly use other build tools

Code Evidence:

packages/pylon-builder/src/bundler/bundler.ts (lines 94-109):

const output = await build({
  logLevel: 'silent',
  metafile: true,
  entryPoints: [inputPath],
  outdir: dir,
  bundle: true,
  format: 'esm',
  sourcemap: 'inline',
  packages: 'external',
  plugins: [
    injectCodePlugin,
    esbuildPluginTsc({
      tsconfigPath: path.join(process.cwd(), 'tsconfig.json')
    })
  ]
})

packages/pylon-dev/src/index.ts (lines 19-37):

program
  .command('build')
  .description('Build the Pylon Schema')
  .action(async () => {
    consola.start('[Pylon]: Building schema')

    const {totalFiles, totalSize, duration} = await build({
      sfiFilePath: './src/index.ts',
      outputFilePath: './.pylon'
    })
    // ...
  })

Analysis:

✅ TypeScript support complete: All official templates and examples use TypeScript, provides complete TypeScript configuration
⚠️ JavaScript support limited: Although allows importing JavaScript files, no pure JavaScript examples, build tool mainly processes TypeScript
✅ Multi-runtime support good: Explicitly supports Node.js, Bun, Deno, Cloudflare Workers, provides official templates and examples
❌ Browser not supported: Pylon is a server-side framework, cannot run in browser environment
✅ esbuild as core build tool: Build system completely based on esbuild
⚠️ Other build tool support limited: No official configuration examples for webpack, vite, rspack, users must use Pylon CLI for building

Conclusion: Basic support. Mainly supports TypeScript, can run on some mainstream runtimes, supports some build tools, but requires specific configuration, limited flexibility.

Ecosystem Integration Overall Score

Score: 1.0

Scoring Basis:

ORM integration depth: 3.0 (Basic integration, supports Prisma and Drizzle, but requires manual integration)
Validation library integration: 1.0 (No integration, requires manual validation logic implementation)
GraphQL Server compatibility: 1.0 (Binds GraphQL Yoga, cannot replace)
Toolchain integration: 1.0 (Mainly supports TypeScript, can run on some mainstream runtimes, supports some build tools, but requires specific configuration, limited flexibility, strong Hono binding)

Advantages:

Good ORM support: Officially recommends Prisma, provides integration guides and prisma-extended-models package
Multi-runtime support: Explicitly supports Node.js, Bun, Deno, Cloudflare Workers, provides official templates and examples
Envelop plugin support: Supports extending functionality through Envelop plugins
TypeScript support complete: All official templates and examples use TypeScript, provides complete TypeScript configuration

Disadvantages:

No validation library integration: Completely does not support mainstream validation libraries, requires manual validation logic implementation
Severe framework binding: Forced binding to Hono and GraphQL Yoga, cannot replace
ORM integration requires manual configuration: Although supports ORM, requires manual integration and configuration, not zero boilerplate
Build tool flexibility limited: Must use Pylon CLI and esbuild, no official configuration examples for webpack, vite, rspack
Browser not supported: Pylon is a server-side framework, cannot run in browser environment

📝 Summary

Overall Score: 2.6/5.0

Dimension	Score	Description
Architecture	2.5	Inference mode, requires build, deeply integrated with Hono
Type Definition	3.75	Deep inference, zero-config enums, smart interface detection, powerful type inference
Resolvers & Validation	2.5	Clean code, automatic type inference, but validation and DataLoader require manual implementation
Built-in Features	3.1	Context/Middleware/Subscriptions well-implemented, no built-in DataLoader support
Ecosystem Integration	1.0	Basic ORM integration, no validation library integration, severe framework binding

Overall Evaluation

Pylon adopts Inference (automatic inference) mode, uses TypeScript Compiler API to statically analyze source code, automatically infers and generates GraphQL Schema from TypeScript type definitions and Resolver function signatures. Achieves automatic type inference, zero-config enums, smart interface detection. But requires build, cannot run directly, deeply bound to Hono and GraphQL Yoga, framework flexibility is limited. No validation library integration, DataLoader requires manual implementation.

Core Advantages

Automatic type inference: Automatically generates GraphQL Schema from TypeScript types, reduces manual definitions
Zero-config enums: String union types automatically convert to GraphQL enums, completely zero-config
Smart interface detection: Automatically detects common fields in Union types and generates interfaces
Context/Middleware/Subscriptions complete: Native support, type inference complete
Multi-runtime support: Supports Node.js, Bun, Deno, Cloudflare Workers

Main Disadvantages

Must build: Cannot run directly, must execute build command to generate Schema first
Severe framework binding: Forced binding to Hono and GraphQL Yoga, cannot replace underlying framework
No modularity support: Completely organized by operation type, easy to write coupled giant files
No validation library integration: Completely does not support mainstream validation libraries, requires manual validation logic implementation
No DataLoader support: Requires manual implementation, requires significant boilerplate
Many dependencies: Runtime dependencies include complete GraphQL Server and Web framework

Use Cases

Recommended Use

Projects using Hono as Web framework
Projects requiring automatic type inference
Projects requiring multi-runtime deployment (Node.js, Bun, Deno, Cloudflare Workers)
Projects not minding build steps

Not Recommended Use

Projects requiring write-and-run
Projects requiring modularity
Projects requiring validation or DataLoader
Projects requiring underlying framework replacement
Projects requiring minimal dependencies

Improvement Suggestions

Provide modularity support: Support organizing code by domain, enforce module boundaries
Provide validation and DataLoader support: Reduce manual implementation, improve development efficiency
Reduce framework binding: Improve flexibility, support underlying framework replacement
Support runtime build: Provide optional runtime build mode, reduce build step dependency

Pothos Evaluation Report

Mon, 05 Jan 2026 13:46:21 +0000

📋 Basic Information

Item	Content
Current Version	4.12.0
GitHub	https://github.com/hayes/pothos
Documentation	https://pothos-graphql.dev
First Commit	2019-10-10
Latest Commit	2025-12-31

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture	5.0	Builder pattern, minimal dependencies, zero magic, write and run, completely neutral
2. Type Definition	4.0	Deep inference, powerful $inferType, automatic interface inheritance, Union requires manual handling
3. Resolvers & Validation	4.1	Fully automatic parameter inference, callback pattern increases code volume, limited modular flexibility, declarative validation support
4. Built-in Features	3.3	Core features complete, powerful plugin system, rich official plugins, requires plugin installation
5. Ecosystem Integration	4.5	Deep ORM integration, seamless validation library integration, fully compatible with all GraphQL Servers, mainstream framework support

1. Architecture

Architecture Pattern Type

Builder Pattern: Pothos adopts a plugin-based Builder pattern, providing a chainable API through SchemaBuilder instances (typically named builder) to explicitly build GraphQL Schema, and finally converts the definitions to standard GraphQL Schema at runtime through builder.toSchema().

Core Implementation Mechanism

Source Code Evidence:

Core Builder class: pothos/packages/core/src/builder.ts (lines 75-727) defines the SchemaBuilder class
Schema building: The toSchema() method in pothos/packages/core/src/builder.ts (lines 681-726) uses the standard GraphQLSchema constructor to build
Plugin system: pothos/packages/core/src/plugins/plugin.ts (lines 22-196) defines the BasePlugin base class
Business code example: typescript-graphql-schemas/pothos/src/builder.ts (lines 23-32) creates SchemaBuilder instance, schema.ts (line 6) calls builder.toSchema()

Build Flow:

// 1. Create SchemaBuilder instance (optional plugins)
const builder = new SchemaBuilder<SchemaTypes>({
  plugins: [ValidationPlugin, DataloaderPlugin, SimpleObjectsPlugin],
  defaultFieldNullability: false,
})

// 2. Define types (chainable API)
builder.objectType(User, {
  name: 'User',
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
})

// 3. Build Schema at runtime
const schema = builder.toSchema()

Scoring Details

1.1 Dependency Complexity

Score: 5.0

Evidence:

Core package dependencies (pothos/packages/core/package.json lines 48-50):
- graphql: ^16.10.0 - Only as peer dependency, the only runtime dependency
No runtime dependencies: The dependencies field in package.json is empty, all dependencies are in devDependencies (only for testing)
Plugin system independence: Each plugin (such as plugin-validation, plugin-dataloader) also only depends on @pothos/core and graphql (pothos/packages/plugin-validation/package.json lines 46-49)
No decorator dependencies: No need for reflect-metadata or decorator support
No code generation tools: No need for CLI or code generation steps

Analysis:

✅ Core package only depends on standard graphql library, zero runtime overhead
✅ Plugin system adopts optional modular design, install on demand, does not increase core size
✅ Fully meets "minimal dependencies" standard: only depends on GraphQL standard library, no additional third-party dependencies

1.2 Build Flow

Score: 5.0

Evidence:

Pure runtime building: The toSchema() method in pothos/packages/core/src/builder.ts (lines 681-726) executes at runtime
No code generation: Business code (typescript-graphql-schemas/pothos/src/schema.ts) directly runs TypeScript, no pre-build steps needed
No CLI tools: pothos/packages/core/package.json has no dedicated build scripts, only contains development-time type checking and test scripts
Official example verification: pothos/examples/simple-classes/src/schema.ts (line 92) directly calls builder.toSchema(), no build steps needed

Actual Usage:

// typescript-graphql-schemas/pothos/src/schema.ts
import { builder } from './builder.ts'
import './schema/user.ts'
import './schema/menu.ts'
import './schema/order.ts'

export const schema = builder.toSchema()
// Run directly, no build steps needed

Analysis:

✅ Fully runtime building, developers can run directly after writing code
✅ Supports hot reload (such as node --watch), excellent development experience
✅ No need to learn additional CLI commands or build configuration
✅ Fully compatible with standard GraphQL.js, transparent build process

1.3 Config & Language Magic

Score: 5.0

Evidence:

No decorators: All type definitions use function calls, such as builder.objectType(), builder.interfaceRef()
No reflection metadata: No need for import 'reflect-metadata' or configure experimentalDecorators
Standard TypeScript: typescript-graphql-schemas/pothos/tsconfig.json only contains standard configuration, no special settings
Builder API design: Uses TypeScript generics and conditional types to achieve type safety, fully conforms to native TypeScript best practices

Code Example:

// Fully conforms to native TypeScript best practices
const builder = new SchemaBuilder({})

builder.objectType(User, {
  name: 'User',
  fields: (t) => ({
    id: t.exposeID('id'),
    name: t.exposeString('name'),
  }),
})

// Type inference works automatically, no additional configuration needed

Analysis:

✅ Zero magic, fully conforms to native TypeScript best practices
✅ Does not depend on experimental features or compiler plugins
✅ IDE support is complete, type hints and autocomplete work normally
✅ Code is readable, chainable API is intuitive and easy to understand
✅ Plugin system is implemented through standard class inheritance (BasePlugin), no special mechanisms needed

1.4 Ecosystem Integration

Score: 5.0

Evidence:

Standard installation: npm install @pothos/core can be used directly, no special requirements
Server compatibility: builder.toSchema() returns standard GraphQLSchema object (pothos/packages/core/src/builder.ts line 711), can integrate with any GraphQL Server
Official example diversity: pothos/examples/ directory contains various integration examples:
- graphql-yoga (examples/helix/src/server.ts)
- apollo-server (examples/nestjs-apollo-middleware/)
- nextjs (examples/nextjs/)
- fastify (examples/envelope-helix-fastify/)
Business code integration: typescript-graphql-schemas/pothos/src/schema.ts directly exports schema, can integrate with any GraphQL Server

Analysis:

✅ Standard npm package, can be freely integrated into any project
✅ Outputs standard GraphQL Schema, compatible with all GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, Hono, etc.)
✅ Not bound to specific framework, can flexibly choose underlying implementation
✅ Plugin system allows on-demand feature extension, does not affect core compatibility
✅ Official provides rich integration examples, demonstrating integration methods with various frameworks

Architecture Pattern Overall Score

Score: 5.0

Scoring Basis:

Dependency complexity: 5.0 (Minimal dependencies, only depends on graphql standard library)
Build flow: 5.0 (Write and run, zero build steps)
Config & language magic: 5.0 (Zero magic, fully native TypeScript)
Ecosystem integration: 5.0 (Completely neutral, standard compatible, rich integration examples)

Advantages:

Minimal dependencies: Core package only depends on graphql, zero runtime overhead
Plugin-based architecture: Features are modular, install on demand, core remains lightweight
Zero-config startup: No need for decorators, reflection, or code generation, works out of the box
Type safety: Achieves end-to-end type safety through TypeScript type system
Excellent development experience: Chainable API is intuitive, IDE support is complete
Runtime building: Supports hot reload, fast development iteration
Completely neutral: Not bound to any framework, can integrate with all GraphQL Servers

Disadvantages:

Explicit API calls: Compared to decorator pattern, requires more explicit code (but gains zero magic and better type safety advantages)
Learning curve: Builder API requires some learning cost, need to understand the design reasons for callback pattern (type safety, plugin system, circular reference handling, etc.), documentation is complete but design philosophy requires additional learning

2. Type Definition

Core Implementation Mechanism

Pothos uses Builder API + type inference to implement type definitions. Schema definitions are created through chainable API, TypeScript types are automatically inferred from Schema definitions through the $inferType utility type, and GraphQL Schema is generated at runtime through builder.toSchema().

Source Code Evidence:

Type inference implementation: pothos/packages/core/src/refs/enum.ts (line 17), object.ts (line 26), etc. define the $inferType property
Schema building: The toSchema() method in pothos/packages/core/src/builder.ts (lines 681-726) builds standard GraphQL Schema
Business code example: typescript-graphql-schemas/pothos/src/schema/user.ts (line 27) uses typeof User.$inferType to infer types

Scoring Details

2.1 Single Source of Truth Implementation

Score: 4.0

Evidence:

Schema definition as data source: typescript-graphql-schemas/pothos/src/schema/user.ts (lines 7-13) defines Schema through builder.simpleObject()
TypeScript type automatic inference: Line 27 uses typeof User.$inferType to infer types from Schema definition
GraphQL Schema automatic generation: schema.ts (line 6) generates standard GraphQL Schema through builder.toSchema()
Validation logic integrated through plugins: typescript-graphql-schemas/pothos/src/schema/user.ts (line 56) uses validate: z.email() for validation, but requires manual configuration of validation plugin

Code Example:

// Single source of truth: Schema definition
export const User = builder.simpleObject('User', {
  fields: (t) => ({
    id: t.int(),
    name: t.string(),
    email: t.string(),
  }),
})

// TypeScript type automatic inference
export const userMap = new Map<number, typeof User.$inferType>(
  USERS.map((u) => [u.id, u as typeof User.$inferType]),
)
// Result: { id: number, name: string, email: string }

// GraphQL Schema automatic generation
export const schema = builder.toSchema()

Analysis:

✅ Schema definition is the single source of truth, TypeScript types and GraphQL Schema are both derived from it
✅ Deep type inference: Supports nested types, optional fields, arrays, Union, Interface, and other complex scenarios
✅ $inferType provides complete type inference capability, supports all Pothos types (Enum, Object, Interface, Union, Scalar, etc.)
⚠️ Validation logic requires plugin support: Although there are plugin-validation and plugin-zod, manual installation and configuration are required
⚠️ Validation rules separated from type definitions: Cannot automatically generate types from validation rules, requires manual maintenance synchronization

2.2 Enum & String Union Type Support

Score: 4.0

Evidence:

as const array support: typescript-graphql-schemas/pothos/src/schema/menu.ts (lines 6-8) uses builder.enumType('SugarLevel', { values: ['NONE', 'LOW', 'MEDIUM', 'HIGH'] as const })
TypeScript Enum support: The valuesFromEnum function in pothos/packages/core/src/utils/enums.ts (lines 32-47) supports extracting values from TypeScript Enum
Type inference: Enum types can infer types through $inferType (typescript-graphql-schemas/pothos/src/schema/menu.ts line 18 uses typeof SugarLevel.$inferType)
Object mapping support: pothos/packages/core/src/utils/enums.ts (lines 15-26) supports object-form enum value configuration

Code Example:

// Method 1: as const array (recommended)
export const SugarLevel = builder.enumType('SugarLevel', {
  values: ['NONE', 'LOW', 'MEDIUM', 'HIGH'] as const,
})

// Type inference
type SugarLevelType = typeof SugarLevel.$inferType
// Result: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'

// Method 2: TypeScript Enum
enum OrderStatusEnum {
  PENDING = 'PENDING',
  COMPLETED = 'COMPLETED',
  CANCELLED = 'CANCELLED',
}
builder.enumType(OrderStatusEnum, {
  // Automatically extract values from Enum
})

Analysis:

✅ Supports two methods: as const array and TypeScript Enum
✅ No need to redefine member names: Directly use array or Enum, no manual mapping needed
✅ Type safe: Enum values are completely synchronized in TypeScript and GraphQL
✅ $inferType provides complete type inference, supports string literal union types
⚠️ Must use as const: Missing as const will cause type inference to fail, developers need to remember this requirement

2.3 Interface Inheritance & Union Type Experience

Score: 4.0

Evidence:

Interface fields automatic inheritance: typescript-graphql-schemas/pothos/src/schema/menu.ts (lines 30-56) demonstrates interface implementation
- Food interface defines common fields (id, name, price)
- Coffee and Dessert automatically inherit through interfaces: [Food]
- Implementation types only need to define unique fields (sugarLevel/origin and calories)
Runtime automatic merging: pothos/packages/core/src/builder.ts (lines 180-182) automatically adds interface fields to implementation types through ref.addInterfaces() when building Schema
Type system support: Merges interface fields at type level through TypeScript generics and conditional types
Union types require manual handling: typescript-graphql-schemas/pothos/src/schema/menu.ts (lines 59-67) requires manual implementation of resolveType function
Union types require typename: Lines 17, 23, 104, 146 need to explicitly specify typename field in returned objects

Code Example:

// Interface definition
export const Food = builder.interfaceRef<IFood>('Food').implement({
  fields: (t) => ({
    id: t.int(),
    name: t.string(),
    price: t.float(),
  }),
})

// Implement interface (automatic field inheritance)
export const Coffee = builder.objectRef<ICoffee>('Coffee').implement({
  interfaces: [Food],
  fields: (t) => ({
    sugarLevel: t.field({
      type: SugarLevel,
      resolve: (parent) => parent.sugarLevel,
    }),
    origin: t.string({ resolve: (parent) => parent.origin }),
  }),
})
// Coffee automatically includes id, name, price fields

// Union type definition
export const MenuItem = builder.unionType('MenuItem', {
  types: [Coffee, Dessert],
  resolveType: (item) => {
    if (item && typeof item === 'object' && '__typename' in item) {
      return item.__typename === 'Coffee' ? Coffee : Dessert
    }
    return null
  },
})

// Union types require manual __typename handling
createCoffee: (_parent, { name, price, sugarLevel, origin }) => {
  const newItem: ICoffee = {
    __typename: 'Coffee',  // Must manually specify
    id,
    name,
    price,
    sugarLevel,
    origin,
  }
  return newItem
}

Analysis:

✅ Interface fields automatic inheritance: Implementation types don't need to repeat common field declarations
✅ Type system support: TypeScript types also automatically include interface fields (through generic constraints)
✅ Supports multiple interface implementation: Can implement multiple interfaces simultaneously (interfaces: [Food, AnotherInterface])
⚠️ Union types require manual __typename: Must explicitly specify type name in returned objects
⚠️ Union types require manual resolveType: Need to implement type resolution function, although logic is simple but requires manual writing
✅ Type safe: Return value type of resolveType will be checked by TypeScript

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 4.0

Evidence:

Automatic inference of basic types: Builder API automatically handles String, Int, Float, Boolean, ID, Enum, and other basic types
Automatic inference of complex types: Supports arrays ([Type]), optional fields (through required: false), nested objects, Union types
$inferType utility: All type references (Enum, Object, Interface, Union, Scalar) provide $inferType property for type inference
Requires explicit type parameters: typescript-graphql-schemas/pothos/src/schema/menu.ts (lines 30, 39, 51) require explicit generic parameters (such as builder.interfaceRef<IFood>('Food'))
Field type inference: Types can be automatically inferred when defining fields (such as t.string(), t.int()), but complex types require explicit specification

Code Example:

// Basic types automatic inference
export const User = builder.simpleObject('User', {
  fields: (t) => ({
    id: t.int(),        // Automatically inferred as number
    name: t.string(),   // Automatically inferred as string
    email: t.string(),  // Automatically inferred as string
  }),
})

// Type inference
type UserType = typeof User.$inferType
// Result: { id: number, name: string, email: string }

// Complex types require explicit specification
export const Coffee = builder.objectRef<ICoffee>('Coffee').implement({
  // Need to explicitly specify generic parameter <ICoffee>
  interfaces: [Food],
  fields: (t) => ({
    sugarLevel: t.field({
      type: SugarLevel,  // Need to explicitly specify type
      resolve: (parent) => parent.sugarLevel,
    }),
  }),
})

// Arrays and optional fields
builder.queryFields((t) => ({
  users: t.field({
    type: [User],  // Array type needs explicit specification
    resolve: () => [...],
  }),
  user: t.field({
    type: User,
    nullable: true,  // Optional field needs explicit specification
    args: {
      id: t.arg.int({ required: true }),
    },
    resolve: (_parent, { id }) => {...},
  }),
}))

Analysis:

✅ Basic types automatic inference: String, Int, Float, Boolean, and other basic types are fully automatically inferred
✅ $inferType provides powerful type inference capability, supports all Pothos types
✅ Field definitions are concise: Chainable API is intuitive, type inference is complete
⚠️ Complex types require explicit specification: Union, Interface, nested objects, etc. require explicit type parameters
⚠️ Arrays and optional fields require explicit annotation: Although syntax is concise, need to remember usage of [Type] and nullable: true
✅ Type safe: All types have complete TypeScript type checking, errors can be found at compile time

Type Definition Overall Score

Score: 4.0

Scoring Basis:

Single source of truth: 4.0 (Deep inference, but validation logic requires plugin support)
Enum support: 4.0 (Lightweight mapping, supports as const array and TypeScript Enum)
Interface inheritance & Union: 4.0 (Smart inheritance, but Union requires manual handling of __typename and resolveType)
Type inference strength: 4.0 (Powerful inference, $inferType provides complete support, but complex types require explicit specification)

Advantages:

$inferType utility is powerful: All types provide $inferType property, type inference is complete
Interface fields automatic inheritance: No need to repeat common field declarations when implementing interfaces
Type safe: Complete TypeScript type checking, errors found at compile time
Flexible enum support: Supports both as const array and TypeScript Enum methods
Builder API is intuitive: Chainable API is clear and easy to understand, type inference is complete

Disadvantages:

Union types require manual handling: Need to manually implement resolveType and __typename fields
Validation logic requires plugins: Although validation is supported, plugins need to be installed and configured
Complex types require explicit specification: Union, Interface, etc. require explicit generic parameters

3. Resolvers & Validation

Core Implementation Mechanism

Pothos uses Builder API + plugin-based validation to implement resolver definitions. Resolvers are defined through t.field() method, parameters are defined through t.arg.*() methods, validation provides declarative validation support through plugin-validation or plugin-zod plugins, and DataLoader provides batch loading support through plugin-dataloader plugin.

Source Code Evidence:

Resolver definition: pothos/packages/core/src/fieldUtils/query.ts (lines 1-12) defines the QueryFieldBuilder class
Validation plugin: pothos/packages/plugin-validation/src/index.ts (lines 22-70) defines the validation plugin
Zod plugin: pothos/packages/plugin-zod/src/index.ts (lines 28-100) defines the Zod integration plugin
DataLoader plugin: pothos/packages/plugin-dataloader/src/index.ts (lines 20-81) defines the DataLoader plugin
Business code example: typescript-graphql-schemas/pothos/src/schema/user.ts (lines 31-47) demonstrates Query Resolver definition, lines 49-95 demonstrate Mutation Resolver definition

Scoring Details

3.1 Development Experience (Code Conciseness)

Score: 3.5

Evidence:

Field definitions are concise: typescript-graphql-schemas/pothos/src/schema/user.ts (lines 31-47) uses builder.queryFields() to define Query, code structure is clear
Parameter definitions are intuitive: Line 39 uses t.arg.int({ required: true }) to define parameters, syntax is intuitive
Resolver functions are concise: The resolve function in lines 41-45 directly writes business logic, no additional wrapping needed
Requires explicit definitions: Each field needs to be explicitly defined through t.field(), compared to decorator pattern requires more code

Code Example:

// Query definition
builder.queryFields((t) => ({
  users: t.field({
    type: [User],
    resolve: () => Array.from(userMap.values()),
  }),
  user: t.field({
    type: User,
    args: {
      id: t.arg.int({ required: true }),
    },
    resolve: (_parent, { id }) => {
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    },
  }),
}))

// Mutation definition
builder.mutationFields((t) => ({
  createUser: t.field({
    type: User,
    args: {
      name: t.arg.string({ required: true }),
      email: t.arg.string({
        required: true,
        validate: z.email(),
      }),
    },
    resolve: (_parent, { name, email }) => {
      const id = incrementId()
      const newUser = { id, name, email }
      userMap.set(id, newUser)
      return newUser
    },
  }),
}))

Analysis:

✅ Code structure is clear: Uses builder.queryFields() and builder.mutationFields() to organize code, structure is clear
✅ Chainable API is intuitive: t.field(), t.arg.*() and other APIs are intuitive and easy to understand
✅ Resolver functions are concise: Directly write business logic, no additional wrapping needed
⚠️ Requires explicit definitions: Each field needs to be explicitly defined, compared to decorator pattern requires more code
⚠️ Callback pattern increases code volume: Must use fields: (t) => ({ ... }) callback pattern, each field needs t. prefix, some developers consider the code more "cluttered" Reference GitHub Discussion #476
⚠️ Design trade-off: Callback pattern is a necessary trade-off for type safety and plugin system, but sacrifices code conciseness
✅ Type safe: All types have complete TypeScript type checking

3.2 Modular Design (Domain-Driven Development Support)

Score: 4.0

Evidence:

Organized by domain: typescript-graphql-schemas/pothos/src/schema/ directory splits files by domain (user.ts, menu.ts, order.ts)
Modular API: Uses builder.queryFields(), builder.mutationFields(), builder.objectFields() to define different operations separately
Can split by file: Each domain module can independently define Query, Mutation, and Field Resolver
Requires manual organization: Although modularity is supported, developers need to consciously follow it, framework doesn't enforce module boundaries

Code Example:

// user.ts - User domain module
export const User = builder.simpleObject('User', {
  fields: (t) => ({
    id: t.int(),
    name: t.string(),
    email: t.string(),
  }),
})

// User's Field Resolver
builder.objectFields(User, (t) => ({
  orders: t.loadableGroup({
    type: Order,
    load: async (userIds: number[]) => {
      return Array.from(orderMap.values()).filter((o) => userIds.includes(o.userId))
    },
    group: (order) => order.userId,
    resolve: (user) => user.id,
  }),
}))

// User's Query
builder.queryFields((t) => ({
  users: t.field({
    type: [User],
    resolve: () => Array.from(userMap.values()),
  }),
  user: t.field({
    type: User,
    args: { id: t.arg.int({ required: true }) },
    resolve: (_parent, { id }) => userMap.get(id),
  }),
}))

// User's Mutation
builder.mutationFields((t) => ({
  createUser: t.field({
    type: User,
    args: {
      name: t.arg.string({ required: true }),
      email: t.arg.string({ required: true, validate: z.email() }),
    },
    resolve: (_parent, { name, email }) => {
      // ...
    },
  }),
}))

Analysis:

✅ Supports domain modularity: Can split files by domain, each domain module contains type definitions, Query, Mutation, and Field Resolver
✅ Provides modular API: builder.queryFields(), builder.mutationFields(), builder.objectFields() define different operations separately
✅ Type definitions and Resolvers in the same module: Type definitions, Query, Mutation, Field Resolver are all in the same module
⚠️ Doesn't enforce modularity: Although modularity is supported, developers need to consciously follow it, framework doesn't enforce module boundaries
⚠️ Requires manual organization: If modularity is needed, need to manually split files and organize, but framework provides good support
⚠️ Cannot directly import resolver objects: Due to callback pattern design, cannot directly import and spread resolver objects, must manually call each resolver function and pass t parameter Reference GitHub Discussion #476

3.3 Parameter Definition & Type Inference

Score: 5.0

Evidence:

Parameter definitions in fields: typescript-graphql-schemas/pothos/src/schema/user.ts (lines 38-40) parameters are defined in fields through args object
Parameter types fully automatically inferred: In resolve: (_parent, { id }) on line 41, id type is automatically inferred as number through TypeScript generics
IDE hints are complete: TypeScript fully understands parameter types, IDE autocomplete works normally
No explicit type annotations needed: Resolver function parameter types are fully automatically inferred, no manual declaration needed

Code Example:

// Parameter definition
builder.queryFields((t) => ({
  user: t.field({
    type: User,
    args: {
      id: t.arg.int({ required: true }),  // Parameter definition
    },
    resolve: (_parent, { id }) => {  // id automatically inferred as number
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    },
  }),
}))

// Complex parameter types also automatically inferred
builder.mutationFields((t) => ({
  createOrder: t.field({
    type: Order,
    args: {
      userId: t.arg.int({
        required: true,
        validate: z.number().refine((id) => userMap.has(id), 'User not found'),
      }),
      items: t.arg.intList({
        required: true,
        validate: z
          .array(z.number().refine((id) => menuMap.has(id), 'Menu item not found'))
          .min(1, 'At least one item is required'),
      }),
    },
    resolve: (_parent, { userId, items }) => {  // userId: number, items: number[]
      // Parameter types fully automatically inferred
    },
  }),
}))

Analysis:

✅ Parameter types fully automatically inferred: Automatically infers parameter types through TypeScript generics and conditional types, no manual declaration needed
✅ IDE hints are complete: TypeScript fully understands parameter types, IDE autocomplete works normally
✅ Type safe: Parameter types are completely synchronized with Schema definitions, errors can be found at compile time
✅ Supports complex types: Arrays, optional parameters, nested objects, and other complex types can all be automatically inferred
✅ No explicit type annotations needed: Resolver function parameter types are fully automatically inferred, code is more concise

3.4 Input Validation Mechanism

Score: 4.0

Evidence:

Plugin supports validation: typescript-graphql-schemas/pothos/src/builder.ts (line 24) installs ValidationPlugin
Zod integration: typescript-graphql-schemas/pothos/src/schema/user.ts (line 56) uses validate: z.email() for declarative validation
Validation logic integrated with Schema definition: Validation rules are directly specified in parameter definitions, integrated with Schema definition
Requires plugin installation: Need to install @pothos/plugin-validation or @pothos/plugin-zod plugin

Code Example:

// Method 1: Use Zod validation (recommended)
builder.mutationFields((t) => ({
  createUser: t.field({
    type: User,
    args: {
      name: t.arg.string({ required: true }),
      email: t.arg.string({
        required: true,
        validate: z.email(),  // Declarative validation
      }),
    },
    resolve: (_parent, { name, email }) => {
      // Validation automatically executed, throws error if fails
    },
  }),
}))

// Method 2: Use custom validation rules
builder.mutationFields((t) => ({
  createOrder: t.field({
    type: Order,
    args: {
      userId: t.arg.int({
        required: true,
        validate: z.number().refine((id) => userMap.has(id), 'User not found'),
      }),
      items: t.arg.intList({
        required: true,
        validate: z
          .array(z.number().refine((id) => menuMap.has(id), 'Menu item not found'))
          .min(1, 'At least one item is required'),
      }),
    },
    resolve: (_parent, { userId, items }) => {
      // Validation automatically executed
    },
  }),
}))

Analysis:

✅ Supports declarative validation: Provides declarative validation API through validate option
✅ Validation logic integrated with Schema definition: Validation rules are directly specified in parameter definitions, integrated with Schema definition
✅ Zod integration is good: plugin-zod provides complete Zod support, can use all Zod validation rules
✅ Automatic validation: Validation automatically executes before Resolver execution, throws error if fails
⚠️ Requires plugin installation: Although validation is supported, need to install and configure plugin-validation or plugin-zod plugin
⚠️ Validation rules separated from type definitions: Although validation logic is integrated with Schema definition, cannot automatically generate types from validation rules

3.5 Batch Loading (DataLoader) Integration

Score: 4.0

Evidence:

Plugin support: typescript-graphql-schemas/pothos/src/builder.ts (lines 3, 24) installs DataloaderPlugin
Declarative API: typescript-graphql-schemas/pothos/src/schema/user.ts (lines 16-23) uses t.loadableGroup() to define batch loading
Requires configuration: Need to define load function and group function, requires some boilerplate code
Type safe: DataLoader types are fully type safe, IDE support is complete

Code Example:

// Use loadableGroup to implement batch loading
builder.objectFields(User, (t) => ({
  orders: t.loadableGroup({
    type: Order,
    load: async (userIds: number[]) => {
      // Batch loading logic
      return Array.from(orderMap.values()).filter((o) => userIds.includes(o.userId))
    },
    group: (order) => order.userId,  // Group by userId
    resolve: (user) => user.id,  // Return user.id as key
  }),
}))

// Use loadable to implement single object loading
builder.objectFields(Order, (t) => ({
  user: t.loadable({
    type: User,
    load: async (userIds: number[]) => {
      return userIds.map((id) => userMap.get(id)).filter(Boolean)
    },
    resolve: (order) => order.userId,
  }),
}))

Analysis:

✅ Supported through plugin: plugin-dataloader provides complete DataLoader support
✅ Declarative API: t.loadableGroup(), t.loadable() and other APIs are intuitive and easy to understand
✅ Type safe: DataLoader types are fully type safe, IDE support is complete
⚠️ Requires some boilerplate code: Need to define load function and group function, requires some configuration
⚠️ Requires plugin installation: Although DataLoader is supported, need to install and configure plugin-dataloader plugin
✅ Automatic batch processing: Framework automatically collects queries and executes in batches, no manual management needed

Resolvers & Validation Overall Score

Score: 4.1

Scoring Basis:

Development experience: 3.5 (Code is concise, but callback pattern increases code volume)
Modular design: 4.0 (Supports domain modularity, provides modular API)
Parameter definition & type inference: 5.0 (Parameter types fully automatically inferred)
Input validation mechanism: 4.0 (Supports declarative validation, but requires additional configuration)
Batch loading: 4.0 (Supports dataloader through plugin, requires some boilerplate code)

Advantages:

Parameter types fully automatically inferred: Resolver function parameter types are fully automatically inferred, no manual declaration needed
Supports domain modularity: Can split files by domain, each domain module contains type definitions, Query, Mutation, and Field Resolver
Declarative validation: Provides declarative validation API through validate option, validation logic integrated with Schema definition
DataLoader support: Provides complete DataLoader support through plugin-dataloader, automatic batch processing
Type safe: All types have complete TypeScript type checking, errors can be found at compile time

Disadvantages:

Requires plugin installation: Validation and DataLoader features require plugin installation and configuration
Requires some boilerplate code: Compared to decorator pattern, requires more explicit code (but gains zero magic and better type safety advantages)
Callback pattern increases code volume: Must use callback pattern fields: (t) => ({ ... }), each field needs t. prefix, code is relatively verbose Reference GitHub Discussion #476
Modular flexibility limited: Cannot directly import and spread resolver objects, must manually call each function, limiting code organization flexibility
Validation rules separated from type definitions: Although validation logic is integrated with Schema definition, cannot automatically generate types from validation rules

4. Built-in Features

Feature Support Overview

Pothos adopts a plugin-based architecture, core features (Context, Subscriptions, Custom Scalars) provide native support, advanced features (Directives, Middleware, DataLoader, Query Complexity, Federation, Tracing) are provided through official plugins, features are rich and type safe.

Feature Support Details Table

Feature	Support Status	Implementation Method	Evidence/Description
Directives	⚠️ Plugin/Additional Implementation	`plugin-directives`	`pothos/packages/plugin-directives/package.json` (lines 2-4) provides official plugin, supports graphql-tools style directives
Extensions	✅ Built-in Support	Native Built-in	`pothos/packages/core/src/builder.ts` (lines 168-178) supports `extensions` option, can declare query complexity, execution time, and other extension information
Batch Loading (DataLoader)	⚠️ Plugin/Additional Implementation	`plugin-dataloader`	`pothos/packages/plugin-dataloader/src/index.ts` (lines 20-81) provides official plugin, supports `t.loadableGroup()` and other declarative APIs
Custom Scalars	✅ Built-in Support	Native Built-in	`pothos/packages/core/src/builder.ts` (lines 545-569) provides `scalarType()` and `addScalarType()` methods, API is intuitive and type safe
Subscription	✅ Built-in Support	Native Built-in	`pothos/packages/core/src/builder.ts` (lines 318-364) provides `subscriptionType()` and `subscriptionFields()` methods, supports real-time data push
Context	✅ Built-in Support	Native Built-in	`pothos/packages/core/src/types/global/schema-types.ts` (lines 66, 80) supports through SchemaTypes Context type, type inference is complete, IDE hints are good
Middleware	⚠️ Plugin/Additional Implementation	Plugin `wrapResolve`	`pothos/packages/core/src/plugins/plugin.ts` (lines 104-109) provides `wrapResolve` method, plugins can implement middleware functionality (such as `plugin-tracing`)
Query Complexity	⚠️ Plugin/Additional Implementation	`plugin-complexity`	`pothos/packages/plugin-complexity/package.json` (lines 2-4) provides official plugin, supports defining and limiting query complexity
Depth Limiting	⚠️ Plugin/Additional Implementation	`plugin-complexity`	`pothos/packages/plugin-complexity/package.json` (lines 2-4) provides official plugin, supports depth limiting (usually provided together with query complexity)
Federation	⚠️ Plugin/Additional Implementation	`plugin-federation`	`pothos/packages/plugin-federation/package.json` (lines 2-4) provides official plugin, supports Apollo Federation subgraph implementation
Tracing	⚠️ Plugin/Additional Implementation	`plugin-tracing`	`pothos/packages/plugin-tracing/package.json` (lines 2-4) provides official plugin, supports OpenTelemetry, Sentry, New Relic, X-Ray, and other tracing systems

Detailed Analysis

4.1 Directive Support

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-directives/package.json (lines 2-4) provides official plugin @pothos/plugin-directives
Plugin description: "Directive plugin for Pothos, enables using graphql-tools based directives with Pothos"
Supports graphql-tools style directives

Analysis:

⚠️ Not built-in support for Directives, but provided through official plugin
✅ Plugin supports graphql-tools style directives, API is concise
✅ Type safe, deeply integrated with core API
⚠️ Requires plugin installation and configuration

4.2 Extension Support

Status: ✅ Built-in Support

Evidence:

pothos/packages/core/src/builder.ts (lines 168-178) supports extensions option in objectType method
pothos/packages/core/src/builder.ts (lines 711-719) supports extensions option in toSchema() method
Can declare query complexity, execution time, and other extension information

Code Example:

builder.objectType(User, {
  name: 'User',
  extensions: {
    complexity: 10,
    executionTime: 100,
  },
  fields: (t) => ({
    id: t.exposeID('id'),
  }),
})

const schema = builder.toSchema({
  extensions: {
    customExtension: 'value',
  },
})

Analysis:

✅ Native support for GraphQL Extensions definition and usage
✅ Can declare query complexity, execution time, and other extension information
✅ API is intuitive, type safe
✅ Supports defining extensions at type level and Schema level

4.3 Batch Loading (DataLoader) Integration

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-dataloader/src/index.ts (lines 20-81) provides official plugin @pothos/plugin-dataloader
typescript-graphql-schemas/pothos/src/schema/user.ts (lines 16-23) uses t.loadableGroup() to define batch loading
Supports t.loadable(), t.loadableList(), t.loadableGroup() and other declarative APIs

Code Example:

builder.objectFields(User, (t) => ({
  orders: t.loadableGroup({
    type: Order,
    load: async (userIds: number[]) => {
      return Array.from(orderMap.values()).filter((o) => userIds.includes(o.userId))
    },
    group: (order) => order.userId,
    resolve: (user) => user.id,
  }),
}))

Analysis:

⚠️ Not built-in support, but provided through official plugin
✅ Plugin provides declarative API (t.loadableGroup(), t.loadable(), etc.), easy to use
✅ Type safe, IDE support is complete
✅ Automatic batch processing, no need to manually manage DataLoader instances
⚠️ Requires plugin installation and configuration

4.4 Custom Scalars

Status: ✅ Built-in Support

Evidence:

pothos/packages/core/src/builder.ts (lines 545-569) provides scalarType() method
pothos/packages/core/src/builder.ts (lines 571-580) provides addScalarType() method
typescript-graphql-schemas/pothos/src/builder.ts (line 34) uses builder.addScalarType('DateTime', DateTimeResolver, {}) to add scalar

Code Example:

// Method 1: Define new scalar
builder.scalarType('DateTime', {
  serialize: (value) => value.toISOString(),
  parseValue: (value) => new Date(value),
  parseLiteral: (ast) => {
    if (ast.kind === Kind.STRING) {
      return new Date(ast.value)
    }
    return null
  },
})

// Method 2: Add existing scalar (such as graphql-scalars)
builder.addScalarType('DateTime', DateTimeResolver, {})

Analysis:

✅ Built-in support for custom scalar types, API is intuitive
✅ Type safe, supports generic parameters to specify input/output types
✅ Supports adding existing scalars (such as scalars in graphql-scalars)
⚠️ Common scalars not built-in (such as DateTime, JSON, BigInt), need to manually define or use third-party libraries

4.5 Subscription

Status: ✅ Built-in Support

Evidence:

pothos/packages/core/src/builder.ts (lines 318-364) provides subscriptionType() and subscriptionFields() methods
Supports standard GraphQL Subscriptions, implements real-time data push through subscribe function

Code Example:

builder.subscriptionType({
  fields: (t) => ({
    counter: t.field({
      type: 'Int',
      subscribe: async function* () {
        for (let i = 100; i >= 0; i--) {
          await new Promise((resolve) => setTimeout(resolve, 1000))
          yield i
        }
      },
      resolve: (value) => value,
    }),
  }),
})

Analysis:

✅ Native support for GraphQL Subscriptions
✅ Supports real-time data push, implemented through async generator
✅ Good underlying transport protocol compatibility (supports WebSocket, SSE, etc. through GraphQL Server)
✅ API is concise, type safe
⚠️ Requires GraphQL Server that supports Subscriptions (such as GraphQL Yoga, Apollo Server)

4.6 Context Injection

Status: ✅ Built-in Support

Evidence:

pothos/packages/core/src/types/global/schema-types.ts (lines 66, 80) supports through SchemaTypes Context type
typescript-graphql-schemas/pothos/src/builder.ts (lines 8-10, 19) defines Context type
Resolver functions automatically receive Context parameter, type inference is complete

Code Example:

export interface Context {
  user?: { id: number; name: string }
  db: Database
}

export interface SchemaTypes {
  Context: Context
  // ...
}

const builder = new SchemaBuilder<SchemaTypes>({
  // ...
})

builder.queryFields((t) => ({
  me: t.field({
    type: User,
    resolve: (_parent, _args, context) => {
      // context type automatically inferred as Context
      return context.user
    },
  }),
}))

Analysis:

✅ Native support for injecting context in Resolvers
✅ Context type inference is complete, specified through SchemaTypes Context type
✅ IDE hints are good, no manual type declaration needed
✅ Supports extending default Context, type safe

4.7 Middleware

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/core/src/plugins/plugin.ts (lines 104-109) provides wrapResolve method
Plugins can implement middleware functionality through wrapResolve method
pothos/examples/graphql-shield/src/schema.ts (lines 20-21) demonstrates permission checking through plugin

Code Example:

// Implement middleware through plugin (such as graphql-shield)
builder.objectType(User, {
  fields: (t) => ({
    lastName: t.exposeString('lastName', {
      shield: isAdmin,  // Permission check middleware
    }),
  }),
})

// Implement middleware through custom plugin
class LoggingPlugin extends BasePlugin {
  override wrapResolve(resolver, fieldConfig) {
    return (parent, args, context, info) => {
      console.log(`Resolving ${fieldConfig.name}`)
      return resolver(parent, args, context, info)
    }
  }
}

Analysis:

⚠️ Not built-in support for middleware, but can be implemented through plugin's wrapResolve method
✅ Plugin system is flexible, can implement various middleware functionality (logging, permissions, performance monitoring, etc.)
✅ Type safe, deeply integrated with core API
⚠️ Requires writing custom plugins or using third-party plugins (such as graphql-shield)

4.8 Query Complexity Analysis

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-complexity/package.json (lines 2-4) provides official plugin @pothos/plugin-complexity
Plugin description: "A Pothos plugin for defining and limiting complexity of queries"

Analysis:

⚠️ Not built-in support, but provided through official plugin
✅ Plugin supports defining and limiting query complexity, prevents complex query attacks
✅ Type safe, deeply integrated with core API
⚠️ Requires plugin installation and configuration

4.9 Depth Limiting

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-complexity/package.json (lines 2-4) provides official plugin @pothos/plugin-complexity
Query complexity plugin usually also supports depth limiting functionality

Analysis:

⚠️ Not built-in support, but provided through official plugin
✅ Plugin supports depth limiting, prevents deep query attacks
✅ Type safe, deeply integrated with core API
⚠️ Requires plugin installation and configuration

4.10 Federation

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-federation/package.json (lines 2-4) provides official plugin @pothos/plugin-federation
Plugin description: "A Pothos plugin for implementing apollo federation subGraphs"
pothos/examples/federation/ directory contains federation examples

Analysis:

⚠️ Not built-in support, but provided through official plugin
✅ Plugin supports Apollo Federation subgraph implementation
✅ Type safe, deeply integrated with core API
✅ Official provides complete federation examples
⚠️ Requires plugin installation and configuration

4.11 Tracing

Status: ⚠️ Plugin/Additional Implementation

Evidence:

pothos/packages/plugin-tracing/package.json (lines 2-4) provides official plugin @pothos/plugin-tracing
pothos/packages/tracing-opentelemetry/, tracing-sentry/, tracing-newrelic/, tracing-xray/ provide various tracing system integrations
pothos/examples/open-telemetry/src/schema.ts (lines 1-25) demonstrates OpenTelemetry integration

Analysis:

⚠️ Not built-in support, but provided through official plugin
✅ Plugin supports various tracing systems (OpenTelemetry, Sentry, New Relic, X-Ray)
✅ Type safe, deeply integrated with core API
✅ Official provides complete tracing examples
⚠️ Requires plugin installation and configuration

Built-in Features Overall Score

Score: 3.3

Scoring Basis:

Directives: ⚠️ Plugin/Additional Implementation (2 points) - Provided through plugin-directives official plugin
Extensions: ✅ Built-in Support (5 points) - Native support, declared through extensions option
DataLoader: ⚠️ Plugin/Additional Implementation (2 points) - Provided through plugin-dataloader official plugin
Scalars: ✅ Built-in Support (5 points) - Through scalarType() and addScalarType() methods
Subscription: ✅ Built-in Support (5 points) - Native support, through subscriptionType() and subscriptionFields()
Context: ✅ Built-in Support (5 points) - Native support, through SchemaTypes Context type support
Middleware: ⚠️ Plugin/Additional Implementation (2 points) - Implemented through plugin's wrapResolve method
Query Complexity: ⚠️ Plugin/Additional Implementation (2 points) - Provided through plugin-complexity official plugin
Depth Limiting: ⚠️ Plugin/Additional Implementation (2 points) - Provided through plugin-complexity official plugin

Total Score: 30/45 = 3.3/5.0

Scoring Basis:

Core features complete: Context, Subscriptions, Custom Scalars have native support
Advanced features rich: Provides Directives, DataLoader, Query Complexity, Federation, Tracing, and other features through official plugins
Plugin system flexible: Can extend various features through plugin system, type safe
Requires plugin installation: Although features are rich, most advanced features require plugin installation and configuration

Advantages:

Core features complete: Context, Subscriptions, Custom Scalars, and other core features have native support
Plugin system powerful: Provides rich features through plugin system, type safe, deeply integrated with core API
Official plugins rich: Provides Directives, DataLoader, Query Complexity, Federation, Tracing, and other official plugins
Type safe: All features have complete TypeScript type checking
Documentation complete: Official provides complete feature documentation and examples

Disadvantages:

Requires plugin installation: Although features are rich, most advanced features require plugin installation and configuration
Plugin dependencies: Using advanced features requires understanding the plugin system, increases learning cost
Core features lightweight: Core package remains lightweight, but need to install plugins on demand to use advanced features

5. Ecosystem Integration

Core Implementation Mechanism

Pothos uses plugin-based architecture to implement ecosystem integration. ORM integration provides deep integration through official plugins (plugin-prisma, plugin-drizzle), validation library integration provides declarative validation through official plugins (plugin-zod), GraphQL Server and web frameworks integrate through standard GraphQL Schema.

Source Code Evidence:

Prisma plugin: pothos/packages/plugin-prisma/package.json (lines 2-4) provides official plugin
Drizzle plugin: pothos/packages/plugin-drizzle/package.json (lines 2-4) provides official plugin
Zod plugin: pothos/packages/plugin-zod/package.json (lines 2-4) provides official plugin
Business code example: pothos/examples/prisma/src/schema.ts (lines 4-15) demonstrates Prisma integration

Scoring Details

5.1 ORM Integration Depth

Score: <-To Be Scored->

Evidence:

Prisma official plugin: pothos/packages/plugin-prisma/package.json (lines 2-4) provides official plugin @pothos/plugin-prisma
Drizzle official plugin: pothos/packages/plugin-drizzle/package.json (lines 2-4) provides official plugin @pothos/plugin-drizzle
Deep integration: pothos/examples/prisma/src/schema.ts (lines 4-15) demonstrates directly using builder.prismaObject() and t.prismaField() to reuse Prisma model definitions
Types fully synchronized: Prisma model types automatically synchronize to GraphQL Schema, zero boilerplate code
Automatic query generation: t.prismaField() automatically generates efficient database queries

Code Example:

// Prisma integration
builder.prismaObject('User', {
  fields: (t) => ({
    id: t.exposeID('id'),
    firstName: t.exposeString('firstName'),
    lastName: t.exposeString('lastName'),
    posts: t.relation('posts'),  // Automatically handles relation queries
  }),
})

builder.queryType({
  fields: (t) => ({
    post: t.prismaField({
      type: 'Post',
      nullable: true,
      args: {
        id: t.arg.id({ required: true }),
      },
      resolve: (query, root, args) =>
        db.post.findUnique({
          ...query,  // Automatically handles query optimization
          where: { id: Number.parseInt(String(args.id), 10) },
        }),
    }),
  }),
})

Analysis:

✅ Provides official plugins to directly reuse ORM model definitions (Prisma, Drizzle)
✅ Automatically generates efficient database queries, types fully synchronized
✅ Zero boilerplate code, directly use builder.prismaObject() and t.prismaField()
✅ Supports automatic relation query handling (t.relation())
✅ Official provides complete integration examples and documentation

5.2 Validation Library Integration

Score: <-To Be Scored->

Evidence:

Zod official plugin: pothos/packages/plugin-zod/package.json (lines 2-4) provides official plugin @pothos/plugin-zod
Declarative validation: typescript-graphql-schemas/pothos/src/schema/user.ts (line 56) uses validate: z.email() for declarative validation
Validation logic fully integrated with Schema definition: Validation rules are directly specified in parameter definitions, fully integrated with Schema definition
Type inference: Validation rules automatically infer types, no manual synchronization needed

Code Example:

// Zod integration
builder.mutationFields((t) => ({
  createUser: t.field({
    type: User,
    args: {
      name: t.arg.string({ required: true }),
      email: t.arg.string({
        required: true,
        validate: z.email(),  // Declarative validation
      }),
    },
    resolve: (_parent, { name, email }) => {
      // Validation automatically executed, throws error if fails
    },
  }),
  createOrder: t.field({
    type: Order,
    args: {
      userId: t.arg.int({
        required: true,
        validate: z.number().refine((id) => userMap.has(id), 'User not found'),
      }),
      items: t.arg.intList({
        required: true,
        validate: z
          .array(z.number().refine((id) => menuMap.has(id), 'Menu item not found'))
          .min(1, 'At least one item is required'),
      }),
    },
    resolve: (_parent, { userId, items }) => {
      // Validation automatically executed
    },
  }),
}))

Analysis:

✅ Native support for mainstream validation libraries (Zod), provided through official plugin
✅ Validation logic fully integrated with Schema definition, validation rules directly specified in parameter definitions
✅ Type inference is good, validation rules automatically infer types
✅ Supports format validation (such as z.email()) and custom validation (such as .refine())
✅ Automatic validation, validation automatically executes before Resolver execution
⚠️ Requires plugin installation: Although validation is supported, need to install and configure plugin-zod plugin

5.3 GraphQL Server Compatibility

Score: <-To Be Scored->

Evidence:

Outputs standard GraphQL Schema: The toSchema() method in pothos/packages/core/src/builder.ts (line 711) returns standard GraphQLSchema object
Official example diversity: pothos/examples/ directory contains various integration examples:
- graphql-yoga (examples/simple-classes/, examples/prisma/)
- graphql-helix (examples/helix/)
- envelop (examples/envelope-helix-fastify/)
- apollo-server (examples/nestjs-apollo-middleware/)
Fully compatible: Can integrate with all mainstream GraphQL Servers, zero configuration needed

Code Example:

// Output standard GraphQL Schema
const schema = builder.toSchema()

// Can integrate with any GraphQL Server
// GraphQL Yoga
import { createYoga } from 'graphql-yoga'
const yoga = createYoga({ schema })

// GraphQL Helix
import { processRequest } from 'graphql-helix'
const result = await processRequest({
  schema,
  // ...
})

// Envelop
import { envelop, useSchema } from '@envelop/core'
const getEnveloped = envelop({
  plugins: [useSchema(schema)],
})

// Apollo Server
import { ApolloServer } from 'apollo-server'
const server = new ApolloServer({ schema })

Analysis:

✅ Fully compatible with all mainstream GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, GraphQL Helix, etc.)
✅ Outputs standard GraphQL Schema, zero configuration needed
✅ Official provides rich integration examples, demonstrating integration methods with various Servers
✅ Not bound to specific Server, can flexibly choose underlying implementation

5.4 Toolchain Integration

Score: <-To Be Scored->

Evidence:

TypeScript/JavaScript Support:

Core package build output: packages/core/package.json (lines 5-15) provides both CommonJS (lib/index.js) and ESM (esm/index.js) formats, supports exports field for conditional exports
Framework source code: tsconfig.options.json (line 5) sets allowJs: false, framework source code is written in TypeScript
Example project support: examples/nextjs/tsconfig.json (line 6) sets allowJs: true, indicating projects can use JavaScript
Build tool: packages/core/package.json (lines 21-22) uses SWC to compile TypeScript to CommonJS and ESM

Runtime Environment Support:

Node.js: ✅ Explicitly supported. All official examples (examples/nextjs/, examples/complex-app/, examples/helix/, etc.) are Node.js environments; example package.json engines.node field specifies Node.js version requirements (such as examples/nextjs/package.json line 36 requires node >= 12.0.0)
Deno: ✅ Explicitly supported. packages/deno/ directory contains Deno-compatible type definition files; packages/plugin-zod/CHANGELOG.md (lines 467, 533, 538) and packages/plugin-sub-graph/CHANGELOG.md (line 516) record Deno compatibility fixes; pnpm-lock.yaml (line 8721) shows dependency packages support deno >= 1.30.0
Bun: ⚠️ Theoretically supported but not explicitly stated. pnpm-lock.yaml (line 8721) shows dependency packages support bun >= 1.0.0, but framework documentation and examples don't explicitly mention Bun support
Cloudflare Workers: ❓ Not explicitly stated. Framework core code has no Cloudflare Workers specific limitations, but no official examples or documentation
Browser: ⚠️ Partially supported but limited. packages/core/src/utils/base64.ts (lines 3-24) uses getGlobalThis() function to detect globalThis, self, window, global, and other global objects, indicating browser compatibility consideration; but GraphQL Schema building is usually done on server side, browser is mainly used for type definitions

Node.js Specific Dependency Analysis:

No Node.js specific API dependencies: Through grep search of packages/core/src directory, core code has no direct use of node:, fs, path, http, process, __dirname, __filename, require(), and other Node.js specific APIs
Cross-platform compatibility: packages/core/src/utils/base64.ts (lines 26-38, 41-56) supports both Node.js Buffer and browser btoa/atob APIs, reflecting cross-platform design

Build Tool Support:

Framework own build: Uses SWC for compilation (packages/core/package.json lines 21-22), outputs both CommonJS and ESM formats
Next.js (based on webpack): ✅ Explicitly supported. examples/nextjs/ provides complete Next.js integration example, uses Next.js default webpack configuration (examples/nextjs/next.config.js is default configuration)
Webpack: ⚠️ Indirectly supported. package.json (line 69) ignores webpack in pnpm.peerDependencyRules.ignoreMissing, indicating framework doesn't directly depend on webpack, but can be used indirectly through Next.js and other frameworks
Vite: ❓ Not explicitly stated. No official examples or documentation for Vite integration
Rspack: ❓ Not explicitly stated. No official examples or documentation for Rspack integration

Code Example:

// TypeScript usage (recommended)
import SchemaBuilder from '@pothos/core';

const builder = new SchemaBuilder({});

// ESM import (Node.js, Deno)
import SchemaBuilder from '@pothos/core';

// CommonJS import (Node.js)
const SchemaBuilder = require('@pothos/core').default;

// Next.js integration (using webpack)
// pages/api/graphql.ts
import { schema } from '../../graphql/schema';
import { createYoga } from 'graphql-yoga';

const yoga = createYoga({ schema });
export default yoga;

Analysis:

✅ TypeScript first: Framework designed specifically for TypeScript, fully utilizes type inference and type system, provides best type safety
✅ Dual format output: Provides both CommonJS and ESM builds, compatible with different module systems
✅ Node.js and Deno support: Explicitly supports Node.js and Deno runtimes, Deno support is officially maintained
✅ Cross-platform compatible: Core code has no Node.js specific dependencies, theoretically can run in various runtime environments
⚠️ JavaScript support limited: Although example projects allow JavaScript, framework mainly targets TypeScript, using JavaScript loses type safety advantages
⚠️ Build tool support limited: Only explicitly supports Next.js (webpack), no official examples for Vite, Rspack, and other modern build tools
⚠️ Edge environment support unclear: Cloudflare Workers, Bun, and other edge runtimes have no explicit documentation or examples

Ecosystem Integration Overall Score

Score: 4.5

Scoring Basis:

ORM integration depth: 5.0 (Deep integration, provides Prisma and Drizzle official plugins)
Validation library integration: 5.0 (Seamless integration, provides Zod official plugin, validation logic fully integrated with Schema definition)
GraphQL Server compatibility: 5.0 (Fully compatible, compatible with all mainstream GraphQL Servers)
Toolchain integration: 3.0 (TypeScript first, supports Node.js and Deno, provides both CommonJS and ESM format output, but build tool support limited)

Advantages:

ORM deep integration: Provides Prisma and Drizzle official plugins, directly reuses model definitions, types fully synchronized, zero boilerplate code
Validation library seamless integration: Provides Zod official plugin, validation logic fully integrated with Schema definition, supports format validation and custom validation
Fully compatible with all GraphQL Servers: Outputs standard GraphQL Schema, fully compatible with Apollo Server, GraphQL Yoga, Envelop, GraphQL Helix, etc.
Toolchain flexible: Supports TypeScript and JavaScript, provides both CommonJS and ESM format output, supports Node.js and Deno runtimes
Official plugins rich: Provides ORM, validation library, DataLoader, Federation, Tracing, and other official plugins

Disadvantages:

TypeScript first: Although JavaScript is supported, mainly targets TypeScript, using JavaScript loses type safety advantages
Build tool support limited: Only explicitly supports Next.js (webpack), no official examples for Vite, Rspack, and other modern build tools
Edge environment support unclear: Cloudflare Workers, Bun, and other edge runtimes have no explicit documentation or examples
Requires plugin installation: Although features are rich, need to install and configure plugins to use

📝 Summary

Overall Score: 4.2/5.0

Dimension	Score	Description
Architecture	5.0	Builder pattern, minimal dependencies, zero magic, write and run, completely neutral
Type Definition	4.0	Deep inference, powerful $inferType, automatic interface inheritance, Union requires manual handling
Resolvers & Validation	4.1	Fully automatic parameter inference, callback pattern increases code volume, limited modular flexibility, declarative validation support
Built-in Features	3.3	Core features complete, powerful plugin system, rich official plugins, requires plugin installation
Ecosystem Integration	4.5	Deep ORM integration, seamless validation library integration, fully compatible with all GraphQL Servers, mainstream framework support

Overall Evaluation

Pothos adopts a plugin-based Builder pattern, achieving the design philosophy of minimal dependencies and zero magic. Core package only depends on graphql standard library, features are extended on demand through plugin system. ORM and validation libraries are deeply integrated, types are fully synchronized, zero boilerplate code. Plugin system is powerful, official plugins are rich, but most advanced features require plugin installation.

Core Advantages

Minimal dependencies: Core package only depends on graphql standard library, zero runtime overhead
Plugin system powerful: Provides rich features through plugin system, type safe, deeply integrated with core API
ORM deep integration: Provides Prisma and Drizzle official plugins, directly reuses model definitions, types fully synchronized, zero boilerplate code
Validation library seamless integration: Provides Zod official plugin, validation logic fully integrated with Schema definition
Parameter types fully automatically inferred: Resolver function parameter types are fully automatically inferred, no manual declaration needed
Fully compatible with all GraphQL Servers: Outputs standard GraphQL Schema, fully compatible with Apollo Server, GraphQL Yoga, Envelop, etc.

Main Disadvantages

Requires plugin installation: Although features are rich, most advanced features require plugin installation and configuration
Callback pattern increases code volume: Must use callback pattern fields: (t) => ({ ... }), each field needs t. prefix, code is relatively verbose
Modular flexibility limited: Cannot directly import and spread resolver objects, must manually call each function
Validation rules separated from type definitions: Although validation logic is integrated with Schema definition, cannot automatically generate types from validation rules

Use Cases

Recommended Use

Medium to large projects requiring complete GraphQL feature support
Projects requiring deep ORM integration (Prisma, Drizzle)
Projects requiring declarative validation (Zod)
Projects requiring plugin system
Projects requiring full compatibility with all GraphQL Servers

Not Recommended Use

Projects requiring minimal code volume
Projects requiring direct import of resolver objects
Projects that don't want to install plugins

Improvement Suggestions

Reduce callback pattern code volume: Provide more concise API, reduce t. prefix requirements
Enhance modular flexibility: Support direct import and spread of resolver objects
Build some advanced features into core: Reduce plugin dependencies, improve out-of-the-box experience

Nexus Evaluation Report

Mon, 05 Jan 2026 13:45:07 +0000

📋 Basic Information

Project	Content
Current Version	1.3.0
GitHub	https://github.com/graphql-nexus/nexus
Documentation	https://nexusjs.org/
First Commit	2018-11-02
Last Commit	2023-03-16

📊 Overall Score

Dimension	Score (1-5)	Brief Comment
1. Architecture	4.0	Builder pattern + code generation, minimal configuration, fully neutral
2. Type Definition	3.0	Builder API + code generation, more explicit declarations, good type safety
3. Resolvers & Validation	3.0	Excellent modularity, good type safety, but validation and DataLoader require manual implementation
4. Built-in Features	3.2	Core features complete, advanced features via plugins, DataLoader and depth limiting not supported
5. Ecosystem Integration	3.5	Excellent GraphQL Server and Web framework compatibility, limited ORM and validation library integration

1. Architecture Pattern (Architecture)

Architecture Overview

Nexus uses the Builder pattern to build GraphQL Schema. Developers define types and fields through functional APIs (such as objectType, queryField, mutationField), and then convert the definitions into executable GraphQL Schema through makeSchema(). Nexus uses code generation (Typegen) to provide type safety by analyzing Schema definitions to generate TypeScript type definition files.

Core Implementation Locations:

src/builder.ts: SchemaBuilder class, responsible for type registration, building, and resolution
src/makeSchema.ts: makeSchema() function, Schema building entry point
src/typegenMetadata.ts: Code generation metadata management
src/typegenAutoConfig.ts: Automatic type inference configuration
src/plugin.ts: Plugin system implementation

1.1 Dependency Complexity (Dependency Complexity)

Score: 5.0

Core Dependency Analysis:

Runtime Dependencies (lines 70-72 of package.json):
- iterall: ^1.3.0 - Iterator utility library (for handling GraphQL iterators)
- tslib: ^2.0.3 - TypeScript runtime library (for helper functions)
Peer Dependency (lines 103-105 of package.json):
- graphql: 15.x || 16.x - GraphQL standard library
No Decorator Dependencies: Does not require reflect-metadata or decorator support
No Reflection Library: Does not depend on runtime reflection mechanisms

Evidence:

// nexus/package.json
"dependencies": {
  "iterall": "^1.3.0",
  "tslib": "^2.0.3"
},
"peerDependencies": {
  "graphql": "15.x || 16.x"
}

Analysis:

✅ Only 2 runtime dependencies, lighter than decorator pattern (requires reflect-metadata, class-validator, etc.)
✅ Core dependencies are only the graphql standard library and two lightweight helper libraries
✅ iterall and tslib are both very small utility libraries that don't significantly increase package size
✅ Completely no need for decorators, reflection metadata, and other "magic" dependencies

Actual Usage (typescript-graphql-schemas/nexus/package.json):

Business code only needs to install nexus and graphql as dependencies
Runtime dependencies are minimal with no additional burden

Conclusion: Minimal dependencies. Only depends on the graphql standard library and two lightweight helper libraries, zero runtime overhead, no additional third-party dependencies.

1.2 Build Flow (Build Flow)

Score: 3.5

Build Methods:

Runtime Build: makeSchema() builds GraphQL Schema at runtime (src/makeSchema.ts:21-58)
Code Generation (Typegen): Optional, used to generate TypeScript type definition files (src/typegenMetadata.ts:29-48)
Default Behavior: Automatically generates type files in development, can be disabled in production (src/builder.ts:296-301)

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema.ts
export const schema = makeSchema({
  types: { DateTime, Query, Mutation, ...allTypes },
  outputs: {
    schema: join(__dirname, '../schema.graphql'),  // Optional: generate SDL
    typegen: join(__dirname, './nexus-typegen.d.ts'),  // Optional: generate types
  },
  contextType: { module: join(__dirname, './context.ts'), export: 'Context' },
  sourceTypes: { modules: [{ module: '@coffee-shop/shared', alias: 'shared' }] },
})

Code Generation Mechanism:

Generation Timing: Asynchronously generated when makeSchema() is called (src/makeSchema.ts:26-54)
Generated Content:
- TypeScript type definition file (nexus-typegen.d.ts): Contains TypeScript types for all GraphQL types
- GraphQL SDL file (schema.graphql): Optional, for viewing or reviewing Schema
Type Inference: Automatically infers types from TypeScript source code through sourceTypes configuration (src/typegenAutoConfig.ts:92-203)

Core Implementation:

// src/makeSchema.ts:26-54
if (sdl || typegen) {
  const typegenPromise = new TypegenMetadata(typegenConfig).generateArtifacts(schema)
  if (config.shouldExitAfterGenerateArtifacts) {
    typegenPromise.then(() => {
      console.log(`Generated Artifacts:
      TypeScript Types  ==> ${typegenPath}
      GraphQL Schema    ==> ${typegenConfig.outputs.schema || '(not enabled)'}`)
      process.exit(0)
    })
  }
}

Shortcomings:

⚠️ Although Schema can be built at runtime, code generation is usually required to get complete type safety
⚠️ Need to wait for type generation to complete on first run or after Schema changes, may affect development experience
⚠️ Type generation is asynchronous, may need to handle generation delays in development environments

Conclusion: Lightweight build. Supports runtime building, but usually recommended to use with type generation step for best TypeScript experience. Code generation is optional but strongly recommended.

1.3 Config & Language Magic (Config & Language Magic)

Score: 4.0

Technical Implementation:

No Decorators: Define types through Builder API, completely functional
No Reflection Metadata: Does not depend on reflect-metadata or runtime reflection
Type Inference: Provides type safety through TypeScript's type system and code generation

Core Implementation Evidence:

// src/builder.ts:459-1878
export class SchemaBuilder {
  private pendingTypeMap: Record<string, AllNexusNamedTypeDefs | null> = {}
  private finalTypeMap: Record<string, GraphQLNamedType> = {}

  addType(typeDef: NexusAcceptedTypeDef) {
    // Directly register type definition, no reflection needed
    this.pendingTypeMap[typeDef.name] = typeDef
  }
}

Actual Usage:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const User = objectType({
  name: 'User',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
    t.nonNull.string('email')
    // Completely functional API, no decorators
  },
})

Type Safety Mechanism:

Code Generation: Generates TypeScript types by analyzing Schema definitions (src/typegenPrinter.ts)
Type Inference: Infers types from TypeScript source code through sourceTypes configuration (src/typegenAutoConfig.ts)
Global Type Extension: Extends global types through generated type files (src/nexus-typegen.d.ts)

Actual Usage Evidence:

// Almost all official examples configure typegen
export const schema = makeSchema({
  types: allTypes,
  outputs: {
    schema: path.join(__dirname, '../schema.graphql'),
    typegen: path.join(__dirname, './nexus-typegen.d.ts'),  // Strongly recommended
  },
})

// Generated type file (nexus-typegen.d.ts)
declare global {
  interface NexusGen extends NexusGenTypes {}
}

export interface NexusGenObjects {
  User: {
    id: number
    name: string
    email: string
  }
}

Official Example Statistics:

apollo-fullstack/src/index.ts: Configured typegen
githunt-api/src/index.js: Configured typegen
kitchen-sink/src/index.ts: Configured detailed typegen options
star-wars/src/schema.ts: Configured typegen
ghost/src/ghost-schema.ts: Configured typegen
with-prisma/api.ts: Configured typegen
ts-ast-reader/src/schema.ts: Configured typegen
typescript-graphql-schemas/nexus/src/schema.ts: Configured typegen
Only zeit-typescript/schema/index.ts not configured (minimal example)

Analysis:

✅ No decorators and reflection metadata, conforms to native TypeScript practices
✅ Uses standard TypeScript syntax, no experimental features
⚠️ Code generation is optional but almost required in practice: Almost all official examples configure typegen, strongly recommended for complete type safety
⚠️ Code generation requires additional configuration: Need to configure outputs.typegen path, increases configuration complexity
⚠️ Generated type files need maintenance: Generated .d.ts files need to be version controlled, synchronization issues exist
⚠️ Does not fully conform to "fully native TS best practices": Native TypeScript does not require code generation steps

Conclusion: Minimal configuration. Although no decorators and reflection metadata are used, code generation is optional but almost required in practice for complete type safety, requires additional configuration and maintenance of generated type files, does not fully conform to "fully native TS best practices" standards.

1.4 Ecosystem Integration (Ecosystem Integration)

Score: 5.0

Integration Methods:

Standard npm Installation: Can be used through npm install nexus
Plugin System: Supports feature extension through plugin() API (src/plugin.ts:209-212)
Web Framework Compatibility: Compatible with all mainstream GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, etc.)

Official Examples (examples/ directory):

apollo-fullstack: Apollo Server integration example
with-prisma: Prisma ORM integration example
kitchen-sink: Complete feature demonstration
star-wars: Basic usage example

Plugin Ecosystem:

Built-in Plugins (src/plugins/ directory):
- connectionPlugin: Relay Connection pattern support
- fieldAuthorizePlugin: Field authorization plugin
- queryComplexityPlugin: Query complexity analysis
- nullabilityGuardPlugin: Null value protection
Community Plugins: Supports creating custom plugins through plugin() API

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema.ts
export const schema = makeSchema({
  types: { DateTime, Query, Mutation, ...allTypes },
  // Standard configuration, no special framework binding needed
  outputs: { schema: '...', typegen: '...' },
  contextType: { module: '...', export: 'Context' },
})

GraphQL Server Integration:

// Can integrate with any GraphQL Server
import { createYoga } from 'graphql-yoga'
import { schema } from './schema'
const yoga = createYoga({ schema })

Conclusion: Fully neutral. Supports standard npm install, can freely combine with any Web framework and build tools. Achieves flexible ecosystem integration through plugin system.

Architecture Summary

Evaluation Item	Score	Description
Dependency Complexity	5.0	Only depends on `graphql` standard library and two lightweight helper libraries
Build Flow	3.5	Runtime build + optional code generation, recommended to use type generation
Config & Language Magic	4.0	Minimal configuration, no decorators or reflection metadata, but strongly recommended code generation
Ecosystem Integration	5.0	Fully neutral, standard npm installation, supports multiple frameworks

Overall Score: 4.0

Nexus's architecture design embodies the "Builder pattern + code generation" philosophy: defines Schema through functional Builder API, provides type safety through code generation, completely avoids decorators and runtime reflection, achieving a lightweight, type-safe GraphQL Schema building solution. Although code generation is technically optional, it's almost required in practice for complete type safety, requires additional configuration and maintenance of generated type files, does not fully conform to "fully native TS best practices" standards.

2. Type Definition (Type Definition)

Type Definition Overview

Nexus uses Builder API + code generation to define GraphQL types. Developers define types through functional APIs (such as objectType, interfaceType, unionType, enumType), then build Schema through makeSchema() and generate TypeScript type definition files. Type safety is achieved through code generation, not runtime reflection.

Core Implementation Locations:

src/definitions/objectType.ts: Object type definition
src/definitions/interfaceType.ts: Interface type definition
src/definitions/unionType.ts: Union type definition
src/definitions/enumType.ts: Enum type definition
src/typegenPrinter.ts: Type generator
src/typegenAutoConfig.ts: Automatic type inference configuration

2.1 Single Source of Truth (Single Source of Truth) Implementation

Score: 3.0

Implementation Method:

Nexus Definition as Schema Data Source: Types defined through Builder API are directly converted to GraphQL Schema
TypeScript Types via Code Generation: Generates TypeScript type files by analyzing Schema definitions (nexus-typegen.d.ts)
Source Types Support: Can infer types from TypeScript source code through sourceTypes configuration (src/typegenAutoConfig.ts:92-203)

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const User = objectType({
  name: 'User',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
    t.nonNull.string('email')
  },
})

// Generated type file (nexus-typegen.d.ts)
export interface NexusGenObjects {
  User: {
    id: number
    name: string
    email: string
  }
}

Source Types Mechanism:

// typescript-graphql-schemas/nexus/src/schema.ts
export const schema = makeSchema({
  sourceTypes: {
    modules: [
      {
        module: '@coffee-shop/shared',
        alias: 'shared',
      },
    ],
  },
})

Analysis:

✅ Nexus definition is the single source of truth for GraphQL Schema
✅ TypeScript types are automatically synchronized through code generation
⚠️ Need to run code generation to get type safety, synchronization delay exists
⚠️ Source Types is mainly used for type mapping inference, not as Schema definition source
⚠️ Type definitions and TypeScript types are separated, need manual consistency maintenance

Shortcomings:

Need to run code generation to update type definitions
Type definitions and TypeScript types are physically separated (definitions in .ts files, types in .d.ts files)
Source Types is mainly used for type mapping, cannot completely replace manual definitions

Conclusion: Logical association. Nexus type definitions are bound to TypeScript types through code generation, although there's some duplication, the type chain can be maintained. Need to run build command to update types.

2.2 Enum & String Union Support (Enum & String Union Types)

Score: 3.0

Implementation Method:

Explicit Enum Registration: Manually register enum types through enumType() API (src/definitions/enumType.ts:86-88)
Support Multiple Definition Methods: Supports string arrays, objects, TypeScript enums (src/definitions/enumType.ts:44-47)
Type Safety: Generated type definitions include enum values (nexus-typegen.d.ts:34-37)

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/menu.ts
export const SugarLevel = enumType({
  name: 'SugarLevel',
  members: ['NONE', 'LOW', 'MEDIUM', 'HIGH'],
})

// typescript-graphql-schemas/nexus/src/schema/order.ts
export const OrderStatus = enumType({
  name: 'OrderStatus',
  members: ['PENDING', 'COMPLETED'],
})

Generated Types:

// nexus-typegen.d.ts
export interface NexusGenEnums {
  OrderStatus: "COMPLETED" | "PENDING"
  SugarLevel: "HIGH" | "LOW" | "MEDIUM" | "NONE"
}

TypeScript Enum Support (src/definitions/enumType.ts:1223-1237):

// Supports TypeScript enums
enum MyEnum {
  VALUE1 = 'value1',
  VALUE2 = 'value2',
}

export const MyGraphQLEnum = enumType({
  name: 'MyGraphQLEnum',
  members: MyEnum, // Directly use TypeScript enum
})

Analysis:

✅ Supports multiple enum definition methods (string arrays, objects, TypeScript enums)
✅ Generated type definitions include enum values, type safe
⚠️ Need to explicitly call enumType() to register, cannot directly use TypeScript enums
⚠️ String union types need to be manually converted to enum definitions

Shortcomings:

Cannot directly use TypeScript string union types (like 'A' | 'B'), need manual registration
Need to explicitly call API to register enums, cannot reuse with zero configuration

Conclusion: Explicit registration. Need to call enumType() to manually register, but can maintain type safety in inference. Supports multiple definition methods, but requires explicit declarations.

2.3 Interface Inheritance & Union Type Experience (Interface & Union)

Score: 3.0

Implementation Method:

Interface Definition: Define interfaces through interfaceType() (src/definitions/interfaceType.ts:158-160)
Interface Implementation: Implement interfaces through t.implements() (src/definitions/objectType.ts:18-19)
Automatic Field Inheritance: Object types implementing interfaces automatically inherit interface fields (src/builder.ts:1368-1422)
Union Types: Define union types through unionType() (src/definitions/unionType.ts:120-122)
Type Resolution: Need to manually implement resolveType function (src/definitions/interfaceType.ts:29-31)

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/menu.ts

// Interface: Food (common fields)
export const Food = interfaceType({
  name: 'Food',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
    t.nonNull.float('price')
  },
  resolveType(item: any) {
    return item?.__typename === 'Coffee' ? 'Coffee' : 'Dessert'
  },
})

// Coffee type, implements Food interface
export const Coffee = objectType({
  name: 'Coffee',
  definition(t) {
    t.implements('Food')  // Implement interface
    t.nonNull.field('sugarLevel', { type: SugarLevel })
    t.nonNull.string('origin')
  },
})

// Union type: MenuItem = Coffee | Dessert
export const MenuItem = unionType({
  name: 'MenuItem',
  definition(t) {
    t.members('Coffee', 'Dessert')
  },
  resolveType(item: any) {
    return item?.__typename === 'Coffee' ? 'Coffee' : 'Dessert'
  },
})

Generated Types:

// nexus-typegen.d.ts
export interface NexusGenInterfaces {
  Food: NexusGenRootTypes['Coffee'] | NexusGenRootTypes['Dessert'];
}

export interface NexusGenUnions {
  MenuItem: NexusGenRootTypes['Coffee'] | NexusGenRootTypes['Dessert'];
}

export interface NexusGenTypeInterfaces {
  Coffee: "Food"
  Dessert: "Food"
}

Field Inheritance Mechanism (src/builder.ts:1368-1422):

Interface fields are automatically merged into implementing types
Supports field modification (t.modify()) to override interface field definitions
Supports adding additional parameters to interface fields

Analysis:

✅ Interface fields automatically inherited, no need to repeat declarations
✅ Supports field modification and extension
✅ Generated type definitions correctly reflect interfaces and union types
⚠️ Need to manually implement resolveType function, cannot automatically handle __typename
⚠️ Union types need to manually return type names

Shortcomings:

Need to manually implement resolveType function, cannot automatically handle __typename field
Does not support automatic type resolution, need to manually determine types based on data structure
Although supports __typename strategy (src/typegenAbstractTypes.ts:395-405), requires explicit configuration

Conclusion: Logical resolution. Supports abstract types, but requires manual implementation of resolveType function, and has specific dependencies on original data structure (requires __typename field).

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 3.0

Implementation Method:

Basic Type Inference: Builder API can automatically infer basic types (t.int(), t.string(), etc.)
Array Types: Need to explicitly use list() and nonNull() (src/definitions/list.ts)
Type References: Supports string references (type: 'User') and object references (type: User)
Code Generation Enhancement: Provides type safety through generated type files

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const User = objectType({
  name: 'User',
  definition(t) {
    t.nonNull.int('id')  // Basic types can be inferred
    t.nonNull.string('name')
    t.nonNull.string('email')
    t.nonNull.list.nonNull.field('orders', {  // Arrays need explicit declaration
      type: Order,  // Type reference
      resolve(parent) {
        return Array.from(orderMap.values()).filter((order) => order.userId === parent.id)
      },
    })
  },
})

Type Inference Capabilities:

✅ Basic types (int, string, float, boolean) can be inferred
✅ Scalar types can be referenced via strings (type: 'DateTime')
⚠️ Array types need to explicitly use list() and nonNull()
⚠️ Optional types need to explicitly use nullable() or omit nonNull()
⚠️ Type references need to be explicitly specified (string or object)

Code Generation Type Safety:

// Generated types provide complete type safety
export interface NexusGenFieldTypes {
  User: {
    id: number
    name: string
    email: string
    orders: NexusGenRootTypes['Order'][]
  }
}

export interface NexusGenArgTypes {
  Mutation: {
    createUser: {
      name: string
      email: string
    }
  }
}

Analysis:

✅ Basic types can be inferred, API is concise
✅ Generated type files provide complete type safety
⚠️ Arrays, Promises, and lazy-loaded types frequently need explicit annotations
⚠️ Type references need to be explicitly specified, cannot be completely automatically inferred
⚠️ Optional types need manual handling, cannot be automatically inferred

Shortcomings:

Array types need to explicitly use list() and nonNull(), cannot be automatically inferred
Type references need to be explicitly specified, cannot be automatically inferred from context
Optional types need manual handling, cannot be automatically inferred

Conclusion: Annotation as needed. Basic types can be inferred, but arrays, Promises, and lazy-loaded types frequently need list(), nonNull() and other syntax. Type references need to be explicitly specified.

Type Definition Summary

Evaluation Item	Score	Description
Single Source of Truth (SSOT)	3.0	Nexus definition as Schema source, TypeScript types synchronized through code generation
Enum & String Union Support	3.0	Explicit registration, supports multiple definition methods, type safe
Interface Inheritance & Union Type Experience	3.0	Fields automatically inherited, but need to manually implement `resolveType`
Type Inference Strength	3.0	Basic types can be inferred, but arrays and optional types need explicit annotations

Overall Score: 3.0

Nexus's type definition uses Builder API + code generation pattern, provides good type safety, but requires more explicit declarations of details. Interface inheritance and automatic field inheritance work well, but union types need manual type resolution implementation. Type inference performs well on basic types, but complex types (arrays, optional types) need explicit annotations.

3. Resolvers & Validation (Resolvers & Validation)

Resolvers & Validation Overview

Nexus defines resolvers through Builder API, supports modular organization through extendType(). Resolver functions receive standard GraphQL parameters (parent, args, context, info), types provide type safety through code generation. Input validation needs to be manually implemented, usually using validation libraries like Zod.

Core Implementation Locations:

src/definitions/extendType.ts: Type extension API, for modular organization
src/definitions/queryField.ts: Query field definition
src/definitions/mutationField.ts: Mutation field definition
src/definitions/args.ts: Argument definition API
src/definitions/definitionBlocks.ts: Field definition blocks

3.1 Developer Experience (Code Conciseness)

Score: 4.0

Implementation Method:

Builder API: Define fields and resolvers through extendType() and t.field()
Type Safety: Provides complete type safety through code generation
Code Organization: Supports organizing code by domain modules

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const UserQuery = extendType({
  type: 'Query',
  definition(t) {
    t.nonNull.list.nonNull.field('users', {
      type: User,
      resolve() {
        return Array.from(userMap.values())
      },
    })

    t.nonNull.field('user', {
      type: User,
      args: {
        id: nonNull(intArg()),
      },
      resolve(_parent, { id }) {
        const user = userMap.get(id)
        if (!user) {
          throw new GraphQLError('User not found')
        }
        return user
      },
    })
  },
})

Field Resolver:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const User = objectType({
  name: 'User',
  definition(t) {
    t.nonNull.int('id')
    t.nonNull.string('name')
    t.nonNull.string('email')
    t.nonNull.list.nonNull.field('orders', {
      type: Order,
      resolve(parent) {
        return Array.from(orderMap.values()).filter((order) => order.userId === parent.id)
      },
    })
  },
})

Analysis:

✅ Code structure is clear, Builder API is intuitive
✅ Type safety provided through code generation, good IDE hints
⚠️ Need to explicitly declare field types, parameter types, etc., moderate code amount
⚠️ Need to manually handle errors and validation logic

Shortcomings:

Need to explicitly declare field configuration objects, cannot completely chain calls
Error handling needs manual implementation, cannot be automatically handled

Conclusion: Code is concise, template code amount is moderate, requires minimal configuration, code structure is clear.

3.2 Modular Design (Domain-Driven Development Support)

Score: 4.0

Implementation Method:

extendType API: Supports organizing code by domain modules through extendType() (src/definitions/extendType.ts:91-93)
Domain Modularity: Each domain module can independently define types, Query, Mutation, and Field Resolver
Automatic Merging: Automatically merges all modules through makeSchema()

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/user.ts
export const User = objectType({ /* ... */ })
export const UserQuery = extendType({ type: 'Query', definition(t) { /* ... */ } })
export const UserMutation = extendType({ type: 'Mutation', definition(t) { /* ... */ } })

// typescript-graphql-schemas/nexus/src/schema/menu.ts
export const Food = interfaceType({ /* ... */ })
export const Coffee = objectType({ /* ... */ })
export const MenuQuery = extendType({ type: 'Query', definition(t) { /* ... */ } })
export const MenuMutation = extendType({ type: 'Mutation', definition(t) { /* ... */ } })

// typescript-graphql-schemas/nexus/src/schema.ts
import * as allTypes from './schema/index.ts'
export const schema = makeSchema({
  types: { DateTime, Query, Mutation, ...allTypes },
})

Module Organization:

✅ Each domain module (User, Menu, Order) is in a separate file
✅ Type definitions, Query, Mutation, Field Resolver are all in the same module
✅ Creates clear module boundaries through extendType()
✅ Automatic merging, no manual management needed

Analysis:

✅ Supports domain modularity, can organize code by domain
✅ Type definitions, Query, Mutation, Field Resolver are all in the same module
⚠️ Query and Mutation are separated (UserQuery and UserMutation are two independent extendType), not unified object or class boundaries
⚠️ Need to manually export all modules (schema/index.ts), not mandatory
✅ Supports cross-module references (e.g., Order references User and MenuItem)

Shortcomings:

Query and Mutation are separated, not unified object/class boundaries, module boundaries are not unified enough
Need to manually export modules, not mandatory

Conclusion: Supports domain modularity, provides modular API, can split files by domain, but Query and Mutation are separated, need manual export, requires developers to consciously follow modular principles.

3.3 Argument Definition & Type Inference

Score: 4.0

Implementation Method:

Argument Definition API: Define arguments through helper functions like intArg(), stringArg(), floatArg() (src/definitions/args.ts:137-327)
Type Inference: Provides argument types through code generation (nexus-typegen.d.ts:204-268)
Optional Arguments: Define optional arguments by omitting nonNull() or using nullable()

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema/user.ts
t.nonNull.field('createUser', {
  type: User,
  args: {
    name: nonNull(stringArg()),  // Required argument
    email: nonNull(stringArg()),
  },
  resolve(_parent, { name, email }) {
    // name and email types are automatically inferred as string
  },
})

t.nonNull.field('updateUser', {
  type: User,
  args: {
    id: nonNull(intArg()),
    name: stringArg(),  // Optional argument
    email: stringArg(),
  },
  resolve(_parent, { id, name, email }) {
    // name and email types are automatically inferred as string | null | undefined
  },
})

Generated Types:

// nexus-typegen.d.ts
export interface NexusGenArgTypes {
  Mutation: {
    createUser: {
      email: string
      name: string
    }
    updateUser: {
      email?: string | null
      id: number
      name?: string | null
    }
  }
}

Complex Arguments:

// typescript-graphql-schemas/nexus/src/schema/order.ts
t.nonNull.field('createOrder', {
  type: Order,
  args: {
    userId: nonNull(intArg()),
    items: nonNull(list(nonNull(intArg()))),  // Array argument
  },
  resolve(_parent, { userId, items }) {
    // items type is automatically inferred as number[]
  },
})

Analysis:

✅ Argument types are mostly automatically inferred, provides type safety through code generation
✅ Supports required and optional arguments, types are correct
✅ Supports array arguments and nested types
⚠️ Need to explicitly use nonNull() or nullable() to declare nullability
⚠️ Complex types need explicit declaration

Shortcomings:

Need to explicitly declare argument types, cannot be completely automatically inferred
Nullability needs manual handling, cannot be automatically inferred

Conclusion: Argument types are mostly automatically inferred, few need explicit declaration. Automatically inferred through Builder API or type inference tools, requires minimal type annotations.

3.4 Input Validation Mechanism

Score: 3.0

Implementation Method:

No Built-in Validation: Nexus does not provide built-in validation functionality
Manual Validation: Need to manually call validation functions in Resolver
Validation Library Integration: Usually uses validation libraries like Zod (src/utils/validate.ts)

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/utils/validate.ts
import { GraphQLError } from 'graphql'
import { z } from 'zod'

export function parse<T>(schema: z.ZodType<T>, value: unknown): T {
  const result = schema.safeParse(value)
  if (!result.success) {
    const issues = result.error.issues || []
    const firstError = issues[0]
    const errorMessage = firstError?.message || 'Validation failed'
    throw new GraphQLError(errorMessage)
  }
  return result.data
}

Validation Usage:

// typescript-graphql-schemas/nexus/src/schema/user.ts
t.nonNull.field('createUser', {
  type: User,
  args: {
    name: nonNull(stringArg()),
    email: nonNull(stringArg()),
  },
  resolve(_parent, { name, email }) {
    // Manually call validation function
    parse(z.string().email(), email)

    const id = incrementId()
    const newUser = { id, name, email }
    userMap.set(id, newUser)
    return newUser
  },
})

Complex Validation:

// typescript-graphql-schemas/nexus/src/schema/order.ts
resolve(_parent, { userId, items }) {
  // Validate userId exists
  if (!userMap.has(userId)) {
    throw new GraphQLError('User not found')
  }

  // Validate items exist and array is not empty
  const itemsSchema = z
    .array(z.number().refine((id) => menuMap.has(id), 'Menu item not found'))
    .min(1, 'At least one item is required')

  parse(itemsSchema, items)
  // ...
}

Analysis:

⚠️ No built-in validation, need manual implementation
⚠️ Validation logic and business logic are mixed
⚠️ Need to manually call validation functions, code duplication
✅ Can use validation libraries like Zod, powerful functionality
⚠️ Validation logic is separated from Schema definition

Shortcomings:

No built-in validation support, need complete manual implementation
Validation code and business logic are mixed, code duplication
Validation logic is separated from Schema definition, need manual consistency maintenance

Conclusion: Supports validation, but requires manual validation logic writing. Need to manually call validation functions, validation code and business logic are mixed.

3.5 Batch Loading (DataLoader) Integration

Score: 0.0

Implementation Method:

No Built-in Support: Nexus does not provide built-in DataLoader support
Manual Implementation: Need to manually create DataLoader instances, define Context type, configure Context injection

Actual Usage:

// typescript-graphql-schemas/nexus/src/context.ts
export interface Context {
  // Add context properties here if needed
  // Need to manually add DataLoader instances
}

Analysis:

⚠️ No built-in DataLoader support provided
⚠️ Need to manually create DataLoader instances
⚠️ Need to manually define Context type
⚠️ Need to manually configure Context injection
⚠️ Lots of boilerplate code

Shortcomings:

No built-in DataLoader support, need lots of boilerplate code
Need to manually manage DataLoader instance lifecycle
Need to manually inject DataLoader in Context

Conclusion: No built-in DataLoader support provided, requires lots of Context boilerplate code and DataLoader boilerplate code. Need to manually create DataLoader instances, define Context type, configure Context injection, lots of boilerplate code.

Resolvers & Validation Summary

Evaluation Item	Score	Description
Developer Experience	4.0	Code is concise, template code amount is moderate, requires minimal configuration, code structure is clear
Modular Design	4.0	Supports domain modularity, provides modular API, but Query and Mutation are separated, need manual export
Argument Definition & Type Inference	4.0	Argument types are mostly automatically inferred, few need explicit declaration
Input Validation Mechanism	3.0	Supports validation, but requires manual validation logic writing
Batch Loading (DataLoader)	0.0	No built-in support, requires lots of boilerplate code

Overall Score: 3.0

Nexus's resolver definition uses Builder API + code generation pattern, provides good modular support and type safety, but requires manual implementation of validation logic and DataLoader integration. Modular design is excellent, supports organizing code by domain, but validation and DataLoader require lots of manual work.

4. Built-in Features (Built-in Features)

Built-in Features Overview

Nexus provides feature extension through plugin system, core features (Context, Subscriptions, Custom Scalars, Directives) are built-in, advanced features (Middleware, Query Complexity) are implemented through plugins. DataLoader and depth limiting need to be implemented manually or through GraphQL Server plugins.

Core Implementation Locations:

src/plugin.ts: Plugin system implementation
src/plugins/: Built-in plugins directory
src/extensions.ts: Extension feature support
src/definitions/directive.ts: Directive support
src/definitions/scalarType.ts: Custom scalar support
src/definitions/subscriptionType.ts: Subscription support

Built-in Features Evaluation Table

Feature	Status	Description
Directive Support (Directives)	✅ Built-in	Define through `directive()` API, supports Schema and Request directives
Extension Support (Extensions)	✅ Built-in	Supports GraphQL Extensions through `extensions` configuration
Batch Loading (DataLoader)	⛔ Cannot implement	No built-in support, need to manually create DataLoader instances and configure Context
Custom Scalars (Scalars)	✅ Built-in	Define through `scalarType()` API, supports `asNexusMethod` to extend Builder API
Subscription (Subscription)	✅ Built-in	Supports through `subscriptionType()` and `subscriptionField()` API
Context Injection	✅ Built-in	Through `contextType` configuration, types automatically inferred through code generation
Middleware (Middleware)	⚠️ Plugin/Additional Implementation	Implemented through plugin system's `onCreateFieldResolver` hook, requires custom plugin
Query Complexity Analysis	⚠️ Plugin/Additional Implementation	Implemented through `queryComplexityPlugin` plugin, requires `graphql-query-complexity` library
Depth Limiting (Depth Limiting)	⛔ Cannot implement	No built-in support, need to implement through GraphQL Server plugins (e.g., `graphql-depth-limit`)

Detailed Feature Analysis

4.1 Directive Support (Directives)

Status: ✅ Built-in

Implementation Method:

Define Directives: Define directives through directive() API (src/definitions/directive.ts:51-90)
Use Directives: Use directives through addDirective() or directives configuration
Supported Locations: Supports Schema and Request directive locations

Actual Usage Evidence:

// src/definitions/directive.ts:51-90
export interface NexusDirectiveConfig<DirectiveName extends string = string> {
  name: DirectiveName
  description?: string
  locations: MaybeReadonlyArray<SchemaDirectiveLocationEnum | RequestDirectiveLocationEnum>
  isRepeatable?: Maybe<boolean>
  args?: ArgsRecord
  extensions?: GraphQLDirectiveConfig['extensions']
}

Conclusion: Native support for defining and using GraphQL Directives, supports Federation architecture, API is concise and type safe.

4.2 Extension Support (Extensions)

Status: ✅ Built-in

Implementation Method:

Extension Configuration: Supports GraphQL Extensions through extensions configuration (src/extensions.ts)
Field Extensions: Supports field-level extensions through NexusFieldExtension
Type Extensions: Supports type-level extensions through NexusObjectTypeExtension, NexusInterfaceTypeExtension

Actual Usage Evidence:

// src/extensions.ts:30-47
export class NexusFieldExtension<TypeName extends string = any, FieldName extends string = any> {
  readonly _type = 'NexusFieldExtension' as const
  readonly config: Omit<NexusOutputFieldConfig<TypeName, FieldName>, 'resolve'>
  readonly hasDefinedResolver: boolean
  readonly sourceType: string | FieldSourceType | NamedFieldSourceType[] | undefined
}

Conclusion: Native support for defining and using GraphQL Extensions, can declare query complexity, execution time and other extension information, API is intuitive.

4.3 Batch Loading (DataLoader) Integration

Status: ⛔ Cannot implement

Implementation Method:

No Built-in Support: Nexus does not provide built-in DataLoader support
Manual Implementation: Need to manually create DataLoader instances, define Context type, configure Context injection

Actual Usage:

// typescript-graphql-schemas/nexus/src/context.ts
export interface Context {
  // Need to manually add DataLoader instances
  // userLoader: DataLoader<number, User>
  // orderLoader: DataLoader<number, Order>
}

Conclusion: No built-in DataLoader support provided, and cannot be implemented through plugins, requires lots of Context boilerplate code and DataLoader boilerplate code.

4.4 Custom Scalars (Scalars)

Status: ✅ Built-in

Implementation Method:

Define Scalars: Define scalars through scalarType() API (src/definitions/scalarType.ts:51-53)
Extend Builder API: Add scalars as Builder methods through asNexusMethod
Type Safety: Provides type safety through code generation

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema.ts
const DateTime = scalarType({
  name: 'DateTime',
  asNexusMethod: 'dateTime',  // Extend Builder API
  description: 'DateTime scalar type',
  parseValue(value: unknown) {
    return DateTimeResolver.parseValue(value)
  },
  serialize(value: unknown) {
    return DateTimeResolver.serialize(value)
  },
  parseLiteral(ast) {
    return DateTimeResolver.parseLiteral(ast, {})
  },
})

// Usage
t.dateTime('createdAt')  // Method extended through asNexusMethod

Conclusion: Built-in support for common scalar types, defining new scalar types is simple, API is intuitive and type safe. Supports extending Builder API through asNexusMethod.

4.5 Subscription (Subscription)

Status: ✅ Built-in

Implementation Method:

Define Subscription Type: Define subscription type through subscriptionType() (src/definitions/subscriptionType.ts:178-180)
Define Subscription Fields: Define subscription fields through subscriptionField() (src/definitions/subscriptionField.ts:115-246)
Async Iterator: Supports returning async iterators (AsyncIterator)

Actual Usage Evidence:

// src/definitions/subscriptionField.ts:19-24
subscribe(
  root: object,
  args: ArgsValue<'Subscription', FieldName>,
  ctx: GetGen<'context'>,
  info: GraphQLResolveInfo
): MaybePromise<AsyncIterator<Event>> | MaybePromiseDeep<AsyncIterator<Event>>

Example:

subscriptionField('signup', {
  type: 'User',
  subscribe() {
    return pubsub.asyncIterator('signup')
  },
  async resolve(eventPromise: Promise<Event<User>>) {
    const event = await eventPromise
    return event.data
  },
})

Conclusion: Native support for GraphQL Subscriptions, supports real-time data push, underlying transport protocol compatibility is good (WebSocket, SSE, etc.), API is concise.

4.6 Context Injection

Status: ✅ Built-in

Implementation Method:

Configure Context Type: Specify Context type through contextType configuration (src/makeSchema.ts:51-54)
Automatic Type Inference: Automatically infers Context type through code generation
Resolver Parameters: Context is automatically injected as the third parameter of Resolver

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/schema.ts
export const schema = makeSchema({
  contextType: {
    module: join(__dirname, './context.ts'),
    export: 'Context',
  },
})

// typescript-graphql-schemas/nexus/src/context.ts
export interface Context {
  // Add context properties here if needed
}

// Context type automatically inferred in Resolver
resolve(_parent, { id }, ctx, info) {
  // ctx type is automatically inferred as Context
}

Generated Types:

// nexus-typegen.d.ts
export interface NexusGenTypes {
  context: Context;
}

Conclusion: Native support for injecting context in Resolver, context type inference is complete, IDE hints are good, no manual type declarations needed.

4.7 Middleware (Middleware)

Status: ⚠️ Plugin/Additional Implementation

Implementation Method:

Plugin System Support: Implement middleware through plugin system's onCreateFieldResolver hook (src/plugin.ts:113)
Middleware Functions: Define middleware functions through MiddlewareFn type (src/plugin.ts:161-167)
Compose Middleware: Compose multiple middleware through composeMiddlewareFns (src/plugin.ts:176-189)

Actual Usage Evidence:

// src/plugin.ts:161-167
export type MiddlewareFn = (
  source: any,
  args: any,
  context: any,
  info: GraphQLResolveInfo,
  next: GraphQLFieldResolver<any, any>
) => any

// Plugin implements middleware
plugin({
  name: 'myMiddleware',
  onCreateFieldResolver(config) {
    return function (root, args, ctx, info, next) {
      // Middleware logic
      return next(root, args, ctx, info)
    }
  },
})

Built-in Plugin Example:

// src/plugins/fieldAuthorizePlugin.ts:67-128
onCreateFieldResolver(config) {
  const authorize = config.fieldConfig.extensions?.nexus?.config.authorize
  if (authorize == null) {
    return
  }
  return function (root, args, ctx, info, next) {
    // Authorization middleware logic
    return plugin.completeValue(
      authorize(root, args, ctx, info),
      (authResult) => {
        if (authResult === true) {
          return next(root, args, ctx, info)
        }
        // Handle authorization failure
      }
    )
  }
}

Conclusion: Not built-in, but can implement middleware functionality through plugins or manually wrapping Resolver, requires additional configuration and boilerplate code.

4.8 Query Complexity Analysis (Query Complexity)

Status: ⚠️ Plugin/Additional Implementation

Implementation Method:

Plugin Support: Supports through queryComplexityPlugin plugin (src/plugins/queryComplexityPlugin.ts:38-74)
Field-Level Configuration: Configure field complexity through complexity configuration
Requires Third-Party Library: Requires graphql-query-complexity library

Actual Usage Evidence:

// src/plugins/queryComplexityPlugin.ts:38-74
export const queryComplexityPlugin = () => {
  return plugin({
    name: 'query-complexity',
    fieldDefTypes,
    onCreateFieldResolver(config) {
      const complexity = config.fieldConfig.extensions?.nexus?.config.complexity
      if (complexity == null) {
        return
      }
      // Add complexity to field's extensions
      config.fieldConfig.extensions = {
        ...config.fieldConfig.extensions,
        complexity,
      } as any
    },
  })
}

Usage Example:

t.field('posts', {
  type: list('Post'),
  complexity: (options) => {
    return options.childComplexity * (options.args.limit ?? 10)
  },
  resolve() {
    // ...
  },
})

Conclusion: Not built-in, but can implement complexity analysis through queryComplexityPlugin plugin, requires graphql-query-complexity library, needs additional configuration.

4.9 Depth Limiting (Depth Limiting)

Status: ⛔ Cannot implement

Implementation Method:

No Built-in Support: Nexus does not provide depth limiting functionality
Need Server Implementation: Need to implement through GraphQL Server plugins (e.g., graphql-depth-limit)

Analysis:

❌ Completely does not support depth limiting
❌ Cannot prevent depth query attacks
⚠️ Can be implemented through GraphQL Server plugins (e.g., graphql-yoga's graphql-depth-limit plugin), but requires additional configuration

Conclusion: Completely does not support depth limiting, cannot prevent depth query attacks. Need to implement through GraphQL Server plugins, requires additional configuration.

Built-in Features Summary

Evaluation Item	Status	Description
Directive Support (Directives)	✅ Built-in	Native support for defining and using GraphQL Directives
Extension Support (Extensions)	✅ Built-in	Native support for GraphQL Extensions
Batch Loading (DataLoader)	⛔ Cannot implement	No built-in support, need manual implementation
Custom Scalars (Scalars)	✅ Built-in	Native support for custom scalars, supports extending Builder API
Subscription (Subscription)	✅ Built-in	Native support for GraphQL Subscriptions
Context Injection	✅ Built-in	Native support for Context injection, types automatically inferred
Middleware (Middleware)	⚠️ Plugin/Additional Implementation	Implemented through plugin system, requires custom plugin
Query Complexity Analysis	⚠️ Plugin/Additional Implementation	Implemented through `queryComplexityPlugin` plugin
Depth Limiting (Depth Limiting)	⛔ Cannot implement	No built-in support, need to implement through GraphQL Server plugins

Overall Score: 3.2

Scoring Basis:

Directives: ✅ Built-in (5 points) - Define through directive() API, supports Schema and Request directives
Extensions: ✅ Built-in (5 points) - Supports GraphQL Extensions through extensions configuration
DataLoader: ⛔ Cannot implement (0 points) - No built-in support, need to manually create DataLoader instances
Scalars: ✅ Built-in (5 points) - Define through scalarType() API, supports asNexusMethod extension
Subscription: ✅ Built-in (5 points) - Through subscriptionType() and subscriptionField() API
Context: ✅ Built-in (5 points) - Through contextType configuration, types automatically inferred through code generation
Middleware: ⚠️ Plugin/Additional Implementation (2 points) - Implemented through plugin system's onCreateFieldResolver hook
Query Complexity: ⚠️ Plugin/Additional Implementation (2 points) - Implemented through queryComplexityPlugin plugin
Depth Limiting: ⛔ Cannot implement (0 points) - No built-in support, need to implement through GraphQL Server plugins

Total Score: 29/45 = 3.2/5.0

Scoring Basis:

Core features support well: Context, Subscriptions, Custom Scalars, Directives, Extensions all provide native support
Advanced features support limited: Middleware, Query Complexity implemented through plugins, DataLoader and depth limiting not supported
Feature completeness: Out of 9 features, 5 are built-in, 2 are plugin/additional implementation, 2 cannot be implemented

Advantages:

Core features complete: Context, Subscriptions, Custom Scalars, Directives, Extensions all provide native support
Plugin system flexible: Can extend features through plugin system (Middleware, Query Complexity)
Type safety: All supported features have complete type inference

Disadvantages:

DataLoader not supported: No built-in DataLoader support, requires lots of boilerplate code
Depth limiting not supported: No built-in depth limiting, need to implement through Server plugins
Middleware requires plugins: Middleware functionality needs to be implemented through plugins, not intuitive enough

5. Ecosystem Integration (Ecosystem Integration)

Ecosystem Integration Overview

Nexus adopts standard GraphQL Schema output + plugin system strategy. Outputs standard GraphQLSchema through makeSchema(), can integrate with any GraphQL Server. ORM integration is implemented through nexus-plugin-prisma plugin, but requires manual Resolver logic writing. Validation library integration needs manual implementation, no built-in support.

Core Integration Locations:

examples/with-prisma/: Prisma ORM integration example
examples/apollo-fullstack/: Apollo Server integration example
docs/content/030-plugins/050-prisma/: Prisma plugin documentation
src/plugin.ts: Plugin system implementation

5.1 ORM Integration Depth (ORM Integration Depth)

Score: 3.0

Implementation Method:

Plugin Support: Provides nexus-plugin-prisma plugin (docs/content/030-plugins/050-prisma/010-overview.mdx)
Manual Integration: Can also integrate Prisma manually (examples/with-prisma/api.ts)
Type Inference: Infers types from Prisma Client through sourceTypes configuration (examples/with-prisma/api.ts:12-14)
Need Manual Resolver Writing: Even with plugin, need to manually write Resolver logic

Prisma Plugin Integration:

// docs/content/030-plugins/050-prisma/010-overview.mdx
import { nexusPrisma } from 'nexus-plugin-prisma'
import { makeSchema } from 'nexus'

const schema = makeSchema({
  types,
  plugins: [nexusPrisma()],
})

Manual Prisma Integration:

// examples/with-prisma/api.ts
import { PrismaClient } from '@prisma/client'
import { makeSchema, objectType, queryType } from 'nexus'

const prisma = new PrismaClient()

const schema = makeSchema({
  sourceTypes: {
    modules: [{ module: '.prisma/client', alias: 'PrismaClient' }],
  },
  contextType: {
    module: path.join(__dirname, 'context.ts'),
    export: 'Context',
  },
  types: [
    objectType({
      name: 'User',
      definition(t) {
        t.id('id')
        t.string('name')
      },
    }),
    queryType({
      definition(t) {
        t.list.field('users', {
          type: 'User',
          resolve(_root, _args, ctx) {
            return ctx.prisma.user.findMany()  // Manually write query logic
          },
        })
      },
    }),
  ],
})

Context Definition:

// examples/with-prisma/context.ts
import { PrismaClient } from '@prisma/client'

export type Context = {
  prisma: PrismaClient
}

Analysis:

✅ Provides Prisma plugin support, but plugin is being rewritten (docs/content/030-plugins/050-prisma/040-removing-the-nexus-plugin-prisma.mdx:9)
✅ Supports inferring types from Prisma Client through sourceTypes
⚠️ Need to manually write all database query logic, even with plugin need to manually implement Resolver
⚠️ Does not support other ORMs (e.g., Drizzle, TypeORM, MikroORM)
⚠️ Type synchronization needs manual maintenance, ORM model definitions are separated from GraphQL Schema definitions

Conclusion: Basic integration. Supports integrating Prisma through plugins or manually, can reuse some model definitions, but requires more configuration and boilerplate code. Does not support other ORMs.

5.2 Validation Library Integration (Validation Library Integration)

Score: 2.0

Implementation Method:

No Built-in Validation Support: Nexus does not provide built-in validation functionality
Manual Validation: Need to manually call validation functions in Resolver
Validation Library Integration: Usually uses validation libraries like Zod, but needs manual implementation

Actual Usage Evidence:

// typescript-graphql-schemas/nexus/src/utils/validate.ts
import { GraphQLError } from 'graphql'
import { z } from 'zod'

export function parse<T>(schema: z.ZodType<T>, value: unknown): T {
  const result = schema.safeParse(value)
  if (!result.success) {
    const issues = result.error.issues || []
    const firstError = issues[0]
    const errorMessage = firstError?.message || 'Validation failed'
    throw new GraphQLError(errorMessage)
  }
  return result.data
}

Validation Usage:

// typescript-graphql-schemas/nexus/src/schema/user.ts
t.nonNull.field('createUser', {
  type: User,
  args: {
    name: nonNull(stringArg()),
    email: nonNull(stringArg()),
  },
  resolve(_parent, { name, email }) {
    // Manually call validation function
    parse(z.string().email(), email)

    const id = incrementId()
    const newUser = { id, name, email }
    userMap.set(id, newUser)
    return newUser
  },
})

Analysis:

❌ No built-in validation support: Does not provide official plugin or integration for validation libraries
❌ Need manual implementation: Must manually write validation logic and call validation functions
❌ Validation logic separated from Schema definition: Validation rules cannot be directly specified in Schema definition
⚠️ Can manually integrate: Although can manually use validation libraries like Zod, requires lots of boilerplate code
⚠️ Type synchronization needs manual maintenance: Validation rules are separated from GraphQL Schema type definitions

Conclusion: Weak integration. Can only use validation libraries manually, validation logic is separated from Schema definition, requires lots of boilerplate code.

5.3 GraphQL Server Compatibility (Server Compatibility)

Score: 5.0

Implementation Method:

Standard GraphQL Schema Output: Outputs standard GraphQLSchema instance through makeSchema()
Fully Compatible: Compatible with all mainstream GraphQL Servers (Apollo Server, GraphQL Yoga, Envelop, Hono, etc.)
No Adapter Needed: Does not need official adapter, directly uses standard GraphQL Server API

Actual Usage Evidence:

// examples/apollo-fullstack/src/index.ts
import { ApolloServer } from 'apollo-server'
import { makeSchema } from 'nexus'

const schema = makeSchema({
  types,
  outputs: {
    schema: path.join(__dirname, '../fullstack-schema.graphql'),
    typegen: path.join(__dirname, 'fullstack-typegen.ts'),
  },
  contextType: {
    module: path.join(__dirname, 'context.ts'),
    export: 'Context',
  },
})

const server = new ApolloServer({
  schema,  // Directly use standard GraphQLSchema
  context,
})

GraphQL Yoga Integration:

import { createYoga } from 'graphql-yoga'
import { schema } from './schema'

const yoga = createYoga({ schema })  // Directly use standard GraphQLSchema

Analysis:

✅ Fully compatible: Outputs standard GraphQLSchema, compatible with all GraphQL Servers
✅ No adapter needed: Does not need official adapter, directly uses standard GraphQL Server API
✅ Flexible integration: Can integrate with any GraphQL Server, including Apollo Server, GraphQL Yoga, Envelop, Hono, etc.

Conclusion: Fully compatible. Outputs standard GraphQLSchema, compatible with all mainstream GraphQL Servers, no adapter needed.

5.4 Toolchain Integration (Toolchain Integration)

Score: 3.0

TypeScript/JavaScript Support

TypeScript Support:

✅ Core Support: Nexus is completely written in TypeScript (all files in src/ directory are .ts), compiled to JavaScript, supports CommonJS and ESM dual format output
✅ Dual Format Output: package.json (lines 29-30) provides "main": "dist" (CommonJS) and "module": "dist-esm" (ESM) formats
✅ Type Definitions: package.json (line 31) provides "types": "dist/index.d.ts", complete TypeScript type support
✅ All Official Examples are TypeScript: Except githunt-api, all examples (with-prisma, kitchen-sink, star-wars, apollo-fullstack, ts-ast-reader, ghost, zeit-typescript) use TypeScript

JavaScript Support:

✅ Official Documentation Explicitly Supports: docs/content/040-adoption-guides/020-nexus-framework-users.mdx (lines 19-21) explicitly states: "If you had been using TypeScript before only because Nexus Framework forced you to, then know that you can use JavaScript with nexus if you want."
✅ Official Example Verification: examples/githunt-api/ provides complete JavaScript usage example
- src/index.js: Uses CommonJS require() to import Nexus
- src/schema.js: Uses JavaScript to define GraphQL Schema
- jsconfig.json: Configures "checkJs": true to enable JavaScript type checking
⚠️ But Primarily TypeScript-Focused: Documentation homepage (docs/content/index.mdx line 9) describes as "TypeScript/JavaScript", but all other examples and documentation are primarily TypeScript

Code Evidence:

// examples/githunt-api/src/index.js
// @ts-check
const { ApolloServer } = require('apollo-server')
const path = require('path')
const { makeSchema } = require('nexus')
const types = require('./schema')

const schema = makeSchema({
  types,
  outputs: {
    schema: path.join(__dirname, '../githunt-api-schema.graphql'),
    typegen: path.join(__dirname, './githunt-typegen.ts'),
  },
  prettierConfig: require.resolve('../../../.prettierrc'),
})

const server = new ApolloServer({
  // @ts-ignore
  schema,
})

const port = process.env.PORT || 4000

server.listen({ port }, () => console.log(`🚀 Server ready at http://localhost:${port}${server.graphqlPath}`))

// package.json
{
  "main": "dist",
  "module": "dist-esm",
  "types": "dist/index.d.ts"
}

Runtime Environment Support

Node.js:

✅ Explicitly Supported: All official examples are Node.js environment
- examples/with-prisma/api.ts: Uses Express and Apollo Server
- examples/kitchen-sink/package.json: Uses ts-node to run
- examples/star-wars/package.json: Uses ts-node-dev to run
✅ Source Code Depends on Node.js APIs: Source code extensively uses Node.js-specific APIs
- src/node.ts: Provides nodeImports() function, uses require('fs') and require('path')
- src/typegenUtils.ts (line 12): Uses process.cwd() to get current working directory
- src/makeSchema.ts (lines 43, 47): Uses process.exit() to exit process
- src/plugins/connectionPlugin.ts (lines 350, 354): Uses Buffer.from() for base64 encoding/decoding
- src/utils.ts (line 472): Uses require('../package.json') to read package info
✅ Type Generation Depends on File System: src/typegenMetadata.ts uses fs.promises.readFile() and fs.promises.writeFile() to read/write files

Bun:

⚠️ Theoretically Supported but Not Verified:
- Nexus outputs standard JavaScript code, theoretically can run in Bun
- But source code extensively uses Node.js-specific APIs (fs, path, process, Buffer, require), these may not be compatible in Bun
- No Bun-related documentation, examples, or configuration
- All example projects are Node.js environment

Deno:

⚠️ Theoretically Supported but Not Verified:
- Nexus outputs standard JavaScript code, theoretically can run in Deno
- But source code extensively uses Node.js-specific APIs, requires Deno compatibility layer support
- No Deno-related documentation, examples, or configuration
- All example projects are Node.js environment

Cloudflare Workers:

❌ Not Supported:
- Type generation functionality depends on file system (fs, path), Cloudflare Workers does not support file system access
- Uses Node.js-specific APIs like process, Buffer, Cloudflare Workers environment does not support
- No Cloudflare Workers-related documentation, examples, or configuration

Browser:

❌ Not Supported:
- Type generation functionality depends on file system, browser environment does not support file system access
- Uses Node.js-specific APIs like process, Buffer, require, browser environment does not support
- No browser runtime examples or documentation

Code Evidence:

// src/node.ts
export function nodeImports() {
  const fs = require('fs') as typeof import('fs')
  const path = require('path') as typeof import('path')
  return {
    fs,
    path,
  }
}

// src/typegenUtils.ts
function getOutputPaths() {
  const defaultSDLFilePath = nodeImports().path.join(process.cwd(), 'schema.graphql')
  // ...
}

// src/makeSchema.ts
typegenPromise
  .then(() => {
    console.log(`Generated Artifacts:
    TypeScript Types  ==> ${typegenPath}
    GraphQL Schema    ==> ${typegenConfig.outputs.schema || '(not enabled)'}`)
    process.exit(0)
  })
  .catch((e) => {
    console.error(e)
    process.exit(1)
  })

// src/plugins/connectionPlugin.ts
function base64Encode(str: string) {
  return Buffer.from(str, 'utf8').toString('base64')
}

function base64Decode(str: string) {
  return Buffer.from(str, 'base64').toString('utf8')
}

Build Tool Support

TypeScript Compiler (tsc):

✅ Core Build Method: All official examples use TypeScript compiler (tsc) for building
- examples/with-prisma/package.json (line 6): "build": "yarn build:reflection && tsc"
- examples/kitchen-sink/package.json (line 6): "build": "ts-node --log-error src/index.ts"
- Framework's own build: package.json (line 33): "build": "yarn -s clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json"
✅ Dual Format Output Configuration:
- tsconfig.cjs.json: Outputs CommonJS format ("module": "CommonJS")
- tsconfig.esm.json: Outputs ESM format ("module": "ES2015")

esbuild:

✅ Documentation Mentions Support: docs/content/040-adoption-guides/020-nexus-framework-users.mdx (lines 172-174) explicitly lists esbuild as one of the recommended bundling tools
✅ Test Verification: tests/esm/standalone.spec.ts provides esbuild integration test example
⚠️ But No Official Configuration Example: Documentation only mentions can be used, does not provide complete configuration example

Other Bundling Tools:

✅ Documentation Mentions Support: docs/content/040-adoption-guides/020-nexus-framework-users.mdx (lines 172-174) lists spack and ncc as optional bundling tools
⚠️ But No Official Configuration Example: Documentation only mentions can be used, does not provide complete configuration example

Webpack:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide webpack configuration example
- docs/package.json contains webpack dependency, but this is for documentation website build (Gatsby), not framework's own build tool integration
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Vite:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide vite configuration example
- No vite-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Rspack:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide rspack configuration example
- No rspack-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Code Evidence:

<!-- docs/content/040-adoption-guides/020-nexus-framework-users.mdx -->
3. Optional: Run a bundler yourself

   This is probably something you don't need to do. Nexus Framework took a packages-bundled approach to dependencies and this mean a large package size that bloated deployments necessitating techniques like tree-shaking (e.g. TypeScript dependency is over 50mb). This problem generally goes away when using the Nexus library directly. However bundling for serverless deployments can still be desirable especially if your non-development dependencies are heavy and not fully used at runtime. If you were relying on Nexus Framework bundling here are some tools you can try out yourself:

   - [`spack`](https://swc-project.github.io/docs/usage-spack-cli)
   - [`esbuild`](https://github.com/evanw/esbuild)
   - [`ncc`](https://github.com/vercel/ncc)

   These tools take care of TypeScript transpilation so you should be able to skip using `tsc` manually with the above tools.

   When you are bundling your app you may need to tweak your `tsconfig.json` to output ES modules rather than CJS modules. The options you will need to think about are [`module`](https://www.typescriptlang.org/tsconfig#module), [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution), and [`target`](https://www.typescriptlang.org/tsconfig#target). There are few ways to go about this, the following is one:

json
{
"compilerOptions": {
"moduleResolution": "Node",
"target": "ES2015",
"module": "ES2015"
}
}

// tests/esm/standalone.spec.ts
it('should build the esbuild', async () => {
  const out = await esbuild.build({
    bundle: true,
    format: 'esm',
    target: 'esnext',
    // minify: true,
    mainFields: ['module', 'main'],
    external: ['path', 'fs', 'prettier'],
    entryPoints: [path.join(__dirname, 'esm-entry.js')],
    outdir: path.join(__dirname, 'out'),
    outExtension: { '.js': '.mjs' },
    metafile: true,
  })
})

Analysis:

✅ TypeScript Native Support: Framework is completely written in TypeScript, compiled to JavaScript, supports ESM and CommonJS dual format output
✅ JavaScript Support: Official documentation explicitly supports, provides complete JavaScript usage example (githunt-api)
✅ Node.js Explicitly Supported: All official examples are Node.js environment, source code extensively uses Node.js-specific APIs
⚠️ Other Runtime Environments Limited: Bun, Deno theoretically supported but not verified; browser, Cloudflare Workers not supported (depends on file system)
✅ TypeScript Compiler Core Support: All examples use tsc for building, framework itself also uses tsc for building
✅ esbuild Documentation Support: Documentation explicitly mentions support, provides test example
⚠️ Other Build Tools No Official Configuration: webpack, vite, rspack, etc. have no official configuration examples, requires users to configure themselves

Ecosystem Integration Summary

Evaluation Item	Score	Description
ORM Integration Depth	3.0	Supports integrating Prisma through plugins or manually, requires more configuration and boilerplate code
Validation Library Integration	2.0	Can only use validation libraries manually, requires lots of boilerplate code
GraphQL Server Compatibility	5.0	Fully compatible, outputs standard GraphQLSchema, no adapter needed
Toolchain Integration	3.0	Supports TypeScript and JavaScript, primarily supports Node.js, supports tsc and esbuild, other build tools need self-configuration

Overall Score: 3.5

Scoring Basis:

GraphQL Server compatibility excellent: Outputs standard GraphQLSchema, compatible with all mainstream GraphQL Servers (5.0)
Toolchain integration basic: Supports TypeScript and JavaScript, but primarily Node.js environment, other runtime environments have limited support (3.0)
ORM integration basic: Supports Prisma plugin, but requires manual Resolver logic writing, does not support other ORMs (3.0)
Validation library integration weak: No built-in validation support, requires manual implementation, validation logic separated from Schema definition (2.0)

Advantages:

Fully Compatible GraphQL Server: Outputs standard GraphQLSchema, compatible with all mainstream GraphQL Servers
TypeScript/JavaScript Dual Support: Official documentation explicitly supports JavaScript, provides complete examples
Plugin System: Can extend features through plugin system (e.g., Prisma integration)

Disadvantages:

Runtime Environment Limited: Primarily supports Node.js, browser and Cloudflare Workers not supported, Bun/Deno not verified
ORM Integration Limited: Only supports Prisma, does not support other ORMs (e.g., Drizzle, TypeORM, MikroORM)
Validation Library Integration Weak: No built-in validation support, requires manual implementation, validation logic separated from Schema definition
Build Tool Configuration Limited: Except tsc and esbuild, other build tools (webpack, vite, rspack) have no official configuration examples

📝 Summary

Overall Score: 3.4/5.0

Dimension	Score	Description
Architecture	4.0	Builder pattern + code generation, minimal configuration, fully neutral
Type Definition	3.0	Builder API + code generation, more explicit declarations, good type safety
Resolvers & Validation	3.0	Excellent modularity, good type safety, but validation and DataLoader require manual implementation
Built-in Features	3.2	Core features complete, advanced features via plugins, DataLoader and depth limiting not supported
Ecosystem Integration	3.5	Excellent GraphQL Server and Web framework compatibility, limited ORM and validation library integration

Overall Evaluation

Nexus uses Builder pattern + code generation approach, defines Schema through functional Builder API, provides type safety through code generation, completely avoids decorators and runtime reflection, achieving a lightweight, type-safe GraphQL Schema building solution. Modular design is excellent, supports organizing code by domain. Although code generation is technically optional, it's almost required in practice for complete type safety.

Core Advantages

Minimal Dependencies: Only depends on graphql standard library and two lightweight helper libraries
Excellent Modularity: extendType() API supports organizing code by domain modules, type definitions, Query, Mutation, Field Resolver are all in the same module
Plugin System: Can extend features through plugin system (Middleware, Query Complexity)
Excellent GraphQL Server Compatibility: Outputs standard GraphQLSchema, compatible with all mainstream GraphQL Servers
Type Safety: Provides complete type safety through code generation

Main Disadvantages

Requires Code Generation: Although technically optional, almost required in practice for complete type safety
Validation Requires Manual Implementation: No built-in validation support, requires manual validation logic writing
No DataLoader Support: Requires manual implementation, lots of boilerplate code
Type Definitions Require More Explicit Declarations: Compared to auto-inference frameworks, requires more explicit code

Use Cases

Recommended Use

Medium to large projects requiring modular organization
Projects requiring plugin system
Projects requiring GraphQL Server compatibility
Projects not minding code generation step

Not Recommended Use

Projects requiring write-and-use (without running code generation)
Projects requiring validation or DataLoader
Projects requiring reduced explicit type declarations

Improvement Suggestions

Provide Validation and DataLoader Support: Reduce manual implementation, improve development efficiency
Reduce Code Generation Dependency: Reduce code generation requirements through better type inference
Enhance Type Inference Capabilities: Reduce explicit type declarations, improve development experience

Grats Evaluation Report

Mon, 05 Jan 2026 13:01:38 +0000

📋 Basic Information

Item	Content
Current Version	0.0.34
GitHub	https://github.com/captbaritone/grats
Documentation	https://grats.capt.dev
First Commit	2023-03-05
Latest Commit	2025-12-21

📊 Overall Score

Dimension	Score (1-5)	Brief Comment
1. Architecture	3.5	Lightweight dependencies, uses standard JSDoc comments, but requires build step, configuration is slightly complex
2. Type Definition	4.5	Fully supports native TypeScript syntax, powerful type inference, automatic interface field inheritance
3. Resolvers & Validation	2.8	Functional API is concise, parameter types are automatically inferred, but no built-in validation and DataLoader
4. Built-in Features	2.4	Core features are complete (Directives, Scalars, Subscriptions), but advanced features are missing
5. Ecosystem Integration	3.0	Excellent GraphQL Server compatibility, but ORM and validation libraries require manual integration

1. Architecture

Grats adopts the Static Analysis architecture pattern, analyzing JSDoc comments and type definitions in source code through the TypeScript compiler API to generate GraphQL Schema at compile time. This is an Implementation-First approach, using TypeScript code as the single source of truth.

Architecture Overview

Core Mechanisms:

Static Analysis: Uses TypeScript compiler API (ts.Program) to analyze source code (src/Extractor.ts)
JSDoc-driven: Marks GraphQL entities through JSDoc comments (@gqlType, @gqlField, etc.)
Code Generation: CLI tool generates executable TypeScript Schema files and GraphQL SDL files
Compiler Plugin: Provides optional TypeScript language service plugin for IDE real-time diagnostics

Workflow (src/lib.ts:90-146):

Create Program using TypeScript compiler API
Extract all definitions with JSDoc tags (extractSnapshotsFromProgram)
Resolve type references, validate interface merging, handle default nullability
Generate GraphQL AST (DocumentNode)
Validate Schema and generate executable code (src/codegen/schemaCodegen.ts)

1.1 Dependency Complexity

Score: 4.0

Evidence:

Runtime Dependencies (grats/package.json lines 20-24):
- commander: ^14.0.1 - CLI command-line tool
- graphql: ^16.11.0 - GraphQL standard library
- semver: ^7.7.2 - Version comparison tool
- typescript: 5.9.2 - TypeScript compiler (fixed version)
No Decorator Dependencies: Does not require reflect-metadata or decorator support
No Reflection Library: Does not depend on runtime reflection mechanisms
Compiler Plugin (grats-ts-plugin/package.json): Independent optional package for IDE support

Analysis:

✅ Only 4 runtime dependencies, lighter than decorator pattern (requires reflect-metadata, class-validator, etc.)
✅ Core dependencies are only graphql and typescript, following minimal dependency principle
⚠️ typescript is a runtime dependency (not devDependency), because compiler API is needed for static analysis
✅ Compiler plugin (grats-ts-plugin) is optional dependency, does not affect core functionality

Actual Usage (typescript-graphql-schemas/grats/package.json):

Business code only needs to install grats as devDependency
Runtime only depends on graphql and generated Schema files

1.2 Build Flow

Score: 3.0

Evidence:

Must Run CLI: Must execute npx grats or grats command to generate Schema (src/cli.ts:47-53)
Generates Two Files:
- .graphql file: GraphQL SDL definition (src/cli.ts:187-191)
- .ts file: Executable TypeScript Schema (src/cli.ts:182-185)
Supports Watch Mode: --watch option supports automatic regeneration on file changes (src/cli.ts:48-49)
Transparent Build Process: Uses TypeScript compiler API, build logic is traceable (src/lib.ts:72-77)

Actual Usage Example (typescript-graphql-schemas/grats/package.json lines 7-8):

{
  "scripts": {
    "print": "grats && node src/print.ts",
    "test": "grats && node src/schema.test.ts"
  }
}

Generated Schema File (typescript-graphql-schemas/grats/src/schema.ts):

Contains complete GraphQLSchema instance generation code
Automatically imports all Resolver functions
Type-safe Schema configuration interface (SchemaConfig)

Build Flow Details (src/cli.ts:173-211):

Read tsconfig.json and parse Grats configuration (getTsConfig)
Use TypeScript compiler API to analyze source code (extractSchemaAndDoc)
Generate TypeScript Schema code (printExecutableSchema)
Generate GraphQL SDL (printGratsSDL)
Optional: Generate enums module (printEnumsModule)

Analysis:

⚠️ Must run build command, cannot "write and use immediately"
✅ Supports Watch mode, good development experience
✅ Generated code is readable, easy to debug
⚠️ Need to integrate build step into development workflow (e.g., package.json scripts)

1.3 Config & Language Magic

Score: 4.0

Evidence:

JSDoc Comment-driven: Uses standard JSDoc comments to mark GraphQL entities (src/Extractor.ts:60-73):
- @gqlType - Object type
- @gqlField - Field
- @gqlQueryField - Query field
- @gqlMutationField - Mutation field
- @gqlEnum - Enum type
- @gqlUnion - Union type
- @gqlInterface - Interface type
TypeScript Compiler Plugin (optional): Provides IDE real-time diagnostics (src/tsPlugin/initTsPlugin.ts)
Configuration in tsconfig.json: Grats configuration is in the grats field of tsconfig.json (src/gratsConfig.ts:33)

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/**
 * User information
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  email: string
}

/** @gqlQueryField */
export function users(): User[] {
  return Array.from(userMap.values())
}

Configuration Example (typescript-graphql-schemas/grats/tsconfig.json):

{
  "grats": {
    "importModuleSpecifierEnding": ".ts",
    "tsSchema": "./src/schema.ts"
  },
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true
  }
}

Compiler Plugin Configuration (examples/apollo-server/tsconfig.json):

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "grats-ts-plugin"
      }
    ]
  }
}

Analysis:

✅ Uses standard JSDoc comments, conforms to TypeScript best practices
✅ Does not depend on decorators or reflection metadata, no special compilation options needed
⚠️ Requires many JSDoc comments, code is slightly verbose
✅ Compiler plugin is optional, but provides better development experience
⚠️ Configuration needs to be declared in tsconfig.json, increases configuration complexity

1.4 Ecosystem Integration

Score: 4.0

Evidence:

Standard npm Installation: Install via npm install grats or pnpm add grats (grats/package.json)
TypeScript Compiler Plugin: Provides grats-ts-plugin package, supports IDE real-time diagnostics (grats-ts-plugin/package.json)
Multiple GraphQL Server Support: Official examples include (grats/examples/):
- Apollo Server (examples/apollo-server/)
- GraphQL Yoga (examples/yoga/)
- Express GraphQL HTTP (examples/express-graphql-http/)
- Next.js (examples/next-js/)
Standard GraphQL Schema: Generated Schema is a standard GraphQLSchema instance, compatible with all GraphQL Servers

Actual Integration Example (typescript-graphql-schemas/grats/src/server.ts):

import { getSchema } from './schema.ts'
import { createYoga } from 'graphql-yoga'

const schema = getSchema({
  scalars: {
    DateTime: {
      // Custom scalar configuration
    }
  }
})

const yoga = createYoga({ schema })

Apollo Server Integration (examples/apollo-server/server.ts):

import { getSchema } from './schema'

const server = new ApolloServer({
  schema: getSchema(),
})

Next.js Integration (examples/next-js/app/api/graphql/route.ts):

Supports Next.js App Router
Uses standard GraphQL HTTP endpoint

Analysis:

✅ Standard npm package, simple installation
✅ Generated Schema is a standard GraphQL.js instance, excellent compatibility
✅ Provides multiple Server integration examples, covering mainstream scenarios
✅ Compiler plugin enhances IDE experience, but is optional
⚠️ Need to manually configure grats field in tsconfig.json

Score Details

1.1 Dependency Complexity

Score: 4.0

Reasons:

Only 4 runtime dependencies (commander, graphql, semver, typescript)
No decorators, no reflection metadata dependencies
Compiler plugin is optional dependency
Lighter than decorator pattern (requires reflect-metadata, class-validator, etc.)

1.2 Build Flow

Score: 3.0

Reasons:

Must run CLI command to generate Schema, cannot "write and use immediately"
Supports Watch mode, good development experience
Generated code is readable, easy to debug
Need to integrate build step into development workflow

1.3 Config & Language Magic

Score: 4.0

Reasons:

Uses standard JSDoc comments, conforms to TypeScript best practices
Does not depend on decorators or reflection metadata
Requires many JSDoc comments, code is slightly verbose
Configuration needs to be declared in tsconfig.json

1.4 Ecosystem Integration

Score: 4.0

Reasons:

Standard npm installation, simple process
Generated Schema is a standard GraphQL.js instance, excellent compatibility
Provides multiple Server integration examples
Compiler plugin enhances IDE experience (optional)

Overall Score

Architecture Total Score: 3.5

Advantages:

Lightweight dependencies, no runtime overhead
Uses standard JSDoc comments, conforms to TypeScript best practices
Generated code is readable, easy to debug
Compatible with all standard GraphQL Servers

Disadvantages:

Must run build command, cannot "write and use immediately"
Requires many JSDoc comments, code is slightly verbose
Configuration needs to be declared in tsconfig.json, increases configuration complexity

2. Type Definition

Grats adopts the Implementation-First approach, with TypeScript code as the single source of truth. Through static analysis of TypeScript type definitions and JSDoc comments, it automatically generates GraphQL Schema. Type inference is based on the TypeScript compiler API, capable of deep analysis of type structures.

2.1 Single Source of Truth Implementation

Score: 4.5

Evidence:

TypeScript Code is Schema: TypeScript type definitions in typescript-graphql-schemas/grats/src/models/user.ts directly generate GraphQL Schema
Automatic Type Extraction: Analyzes source code through TypeScript compiler API (src/Extractor.ts) to extract type information
Bidirectional Sync: Both TypeScript types and GraphQL Schema are generated from the same code, no need to manually maintain two sets of definitions
Requires Build Step: Must run grats CLI command to generate Schema (src/cli.ts:182-191)

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/**
 * User information
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  email: string
}

Generated GraphQL Schema (schema.graphql lines 83-89):

"""User information"""
type User {
  email: String
  id: Int
  name: String
  orders: [Order!]
}

Generated TypeScript Schema (src/schema.ts lines 140-166):

Automatically generates executable GraphQLSchema instance
Automatically imports all Resolver functions
Type-safe Schema configuration interface

Analysis:

✅ TypeScript code is the single source of truth, GraphQL Schema is automatically extracted from it
✅ Type definitions and Schema definitions are completely synchronized, no need to manually maintain
⚠️ Need to run build command to generate Schema, cannot "write and use immediately"
✅ Generated code is readable, easy to debug and verify

2.2 Enum & String Union Support

Score: 5.0

Evidence:

Supports TypeScript Enum: src/Extractor.ts:2032-2082 enumEnumDeclaration method supports TypeScript enum declarations
Supports String Union Types: src/Extractor.ts:2084-2117 enumTypeAliasDeclaration method supports type Enum = 'A' | 'B' syntax
Zero Configuration: Directly uses native TypeScript syntax, no manual registration or mapping needed

Actual Usage Example (typescript-graphql-schemas/grats/src/models/menu.ts lines 6-10):

/**
 * Sugar level for coffee
 * @gqlEnum
 */
export type SugarLevel = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'

Generated GraphQL Schema (schema.graphql lines 13-19):

"""Sugar level for coffee"""
enum SugarLevel {
  HIGH
  LOW
  MEDIUM
  NONE
}

TypeScript Enum Support (src/Extractor.ts:2032-2082):

Supports standard TypeScript enum declarations
Requires enum members to use string literal initialization (src/Extractor.ts:2186-2194)
If tsClientEnums is configured, requires enum to be exported (src/Extractor.ts:2045-2052)

String Union Type Support (src/Extractor.ts:2119-2177):

Supports type Enum = 'A' | 'B' | 'C' syntax
Automatically extracts all string literals as enum values
If tsClientEnums is configured, does not support type alias enums (src/Extractor.ts:2094-2097)

Analysis:

✅ Fully supports native TypeScript enum syntax, zero configuration
✅ Supports two approaches: TypeScript Enum and string union types
✅ Type-safe: Enum values are completely synchronized in TypeScript and GraphQL
✅ No manual mapping or registration needed, can be used directly

2.3 Interface Inheritance & Union Type Experience

Score: 4.5

Evidence:

Automatic Interface Field Inheritance: src/transforms/addInterfaceFields.ts automatically adds interface fields to implementing types
TypeScript implements Support: typescript-graphql-schemas/grats/src/models/menu.ts uses implements Food syntax
Union Type Support: src/Extractor.ts:666-702 unionTypeAliasDeclaration supports type Union = A | B syntax
Requires Manual __typename: Union types require manual definition of __typename field in classes (typescript-graphql-schemas/grats/src/models/menu.ts lines 17, 43)

Interface Inheritance Example (typescript-graphql-schemas/grats/src/interfaces/Food.ts):

/**
 * Food interface with common fields
 * @gqlInterface
 */
export interface Food {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  price: Float
}

Implementing Interface (typescript-graphql-schemas/grats/src/models/menu.ts lines 16-36):

/**
 * Coffee menu item
 * @gqlType
 */
export class Coffee implements Food {
  __typename = 'Coffee' as const
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  price: Float
  /** @gqlField */
  sugarLevel: SugarLevel
  /** @gqlField */
  origin: string
  // ... Interface fields are automatically inherited, no need to redeclare
}

Generated GraphQL Schema (schema.graphql lines 31-38):

"""Coffee menu item"""
type Coffee implements Food {
  id: Int
  name: String
  origin: String
  price: Float
  sugarLevel: SugarLevel
}

Interface Field Auto-Add Mechanism (src/transforms/addInterfaceFields.ts:24-53):

If functional fields are defined on the interface (using @gqlField), they are automatically added to all implementing types
Calculates interface implementation relationships through computeInterfaceMap (src/InterfaceGraph.ts:11-59)
Automatically merges interface fields when building Schema

Union Type Example (typescript-graphql-schemas/grats/src/models/menu.ts lines 61-65):

/**
 * Menu item union type
 * @gqlUnion
 */
export type MenuItem = Coffee | Dessert

Generated GraphQL Schema (schema.graphql lines 21-22):

"""Menu item union type"""
union MenuItem = Coffee | Dessert

Union Type Resolution (src/validations/validateTypenames.ts:22-68):

Requires all Union member types to have __typename field
Tracks which types have __typename field through hasTypename Set
If a type does not have __typename field, an error is reported (src/validations/validateTypenames.ts:42-60)

Analysis:

✅ Interface fields are automatically inherited, implementing types don't need to redeclare common fields
✅ Supports TypeScript implements syntax, conforms to native TypeScript practices
✅ Supports defining functional fields on interfaces, automatically added to all implementing types
⚠️ Union types require manual definition of __typename field, adds some boilerplate code
✅ Union types support native TypeScript Union syntax, zero configuration

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 4.0

Evidence:

Automatic Basic Type Inference: src/Extractor.ts automatically infers basic types like string, number, boolean through TypeScript compiler API
Automatic Array Type Inference: Supports Type[] and Array<Type> syntax, automatically infers as GraphQL List type
Automatic Optional Type Inference: Supports Type | null and Type? syntax, automatically infers nullability
Requires Explicit Type Aliases: For GraphQL-specific types (like Int, Float), need to use type aliases provided by grats package (typescript-graphql-schemas/grats/src/models/user.ts line 5)

Type Inference Example (typescript-graphql-schemas/grats/src/models/user.ts):

import type { Int } from 'grats'

/**
 * User information
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int              // Explicitly use Int type alias
  /** @gqlField */
  name: string         // Automatically inferred as String
  /** @gqlField */
  email: string        // Automatically inferred as String
}

Array Type Inference (typescript-graphql-schemas/grats/src/models/order.ts line 26):

/** @gqlField */
itemIds: Int[]        // Automatically inferred as [Int!]

Optional Type Inference (typescript-graphql-schemas/grats/src/models/menu.ts line 83):

/** @gqlQueryField */
export function menuItem(id: Int): MenuItem | null {
  // Return type automatically inferred as MenuItem (nullable)
}

Type Resolution Mechanism (src/transforms/resolveTypes.ts:41-47):

Uses two-phase resolution: first extract all declarations, then resolve type references
Supports generic type parameters (src/transforms/resolveTypes.ts:73-98)
Tracks type declarations and references through TypeContext (src/TypeContext.ts:62-298)

Default Nullability Handling (src/transforms/applyDefaultNullability.ts):

If nullableByDefault: true is configured, all fields default to nullable
Can mark fields as non-nullable through @killsParentOnException
Supports strict semantic nullability (strictSemanticNullability)

Analysis:

✅ Powerful type inference: automatically infers basic types, arrays, optional types
✅ Deep type analysis: semantic analysis through TypeScript compiler API
⚠️ Requires explicit type aliases: for GraphQL-specific types (Int, Float), need to use type aliases
✅ Supports complex types: generics, union types, interfaces can all be correctly inferred
✅ Type-safe: all type inference is type-safe, compile-time checked

Score Details

2.1 Single Source of Truth Implementation

Score: 4.5

Reasons:

TypeScript code is the single source of truth, GraphQL Schema is automatically extracted from it
Type definitions and Schema definitions are completely synchronized, no need to manually maintain
Need to run build command to generate Schema, cannot "write and use immediately"
Generated code is readable, easy to debug and verify

2.2 Enum & String Union Support

Score: 5.0

Reasons:

Fully supports native TypeScript enum syntax, zero configuration
Supports two approaches: TypeScript Enum and string union types
Type-safe: Enum values are completely synchronized in TypeScript and GraphQL
No manual mapping or registration needed, can be used directly

2.3 Interface Inheritance & Union Type Experience

Score: 4.5

Reasons:

Interface fields are automatically inherited, implementing types don't need to redeclare common fields
Supports TypeScript implements syntax, conforms to native TypeScript practices
Supports defining functional fields on interfaces, automatically added to all implementing types
Union types require manual definition of __typename field, adds some boilerplate code

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 4.0

Reasons:

Powerful type inference: automatically infers basic types, arrays, optional types
Deep type analysis: semantic analysis through TypeScript compiler API
Requires explicit type aliases: for GraphQL-specific types (Int, Float), need to use type aliases
Supports complex types: generics, union types, interfaces can all be correctly inferred

Overall Score

Type Definition Total Score: 4.5

Advantages:

Fully supports native TypeScript syntax, zero configuration
Powerful type inference capability, automatically analyzes complex type structures
Interface fields are automatically inherited, reduces duplicate code
Type definitions and Schema definitions are completely synchronized

Disadvantages:

Need to run build command to generate Schema
Union types require manual definition of __typename field
Need to use type aliases for GraphQL-specific types

3. Resolvers & Validation

Grats Resolver definitions use a Functional API + JSDoc Comments approach. All Resolvers are ordinary TypeScript functions, marked as GraphQL fields through JSDoc comments. Parameter types are automatically inferred through the TypeScript type system, but parameters need to be explicitly declared.

Core Implementation Mechanism

Source Code Evidence:

Resolver signature handling: src/resolverSignature.ts defines the Resolver parameter type system
Parameter resolution: src/transforms/resolveResolverParams.ts resolves Resolver parameters, distinguishes GraphQL parameters, Context, Info
Context injection: Marks Context type through @gqlContext (src/Extractor.ts:74)

3.1 Development Experience (Code Conciseness)

Score: 4.0

Evidence:

Functional API: Resolvers in typescript-graphql-schemas/grats/src/models/user.ts are all ordinary functions
JSDoc Comment Marking: Marked through @gqlQueryField, @gqlMutationField, @gqlField
Automatic Parameter Type Inference: Function parameter types are automatically inferred through TypeScript
Requires JSDoc Comments: Each Resolver requires JSDoc comments, code is slightly verbose

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/** @gqlQueryField */
export function users(): User[] {
  return Array.from(userMap.values())
}

/** @gqlQueryField */
export function user(id: Int): User {
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  return user
}

/** @gqlField */
export function orders(user: User): Order[] {
  return getOrdersByUserId(user.id)
}

/** @gqlMutationField */
export function createUser(name: string, email: string): User {
  if (!email.includes('@')) {
    throw new GraphQLError('Invalid email format')
  }
  const id = incrementId()
  const newUser = { id, name, email } as unknown as User
  userMap.set(id, newUser)
  return newUser
}

Code Volume Analysis:

Query Resolver: Each function about 3-5 lines of code + 1 line JSDoc comment
Mutation Resolver: Each function about 5-10 lines of code + 1 line JSDoc comment
Field Resolver: Each function about 2-4 lines of code + 1 line JSDoc comment

Analysis:

✅ Functional API is concise and intuitive, conforms to TypeScript best practices
✅ Parameter types are automatically inferred, no manual declaration needed
⚠️ Requires JSDoc comments, each Resolver needs to be marked
✅ Code structure is clear, easy to understand and maintain

3.2 Modular Design (Domain-Driven Development Support)

Score: 4.0

Evidence:

Organized by Domain: typescript-graphql-schemas/grats/src/models/ directory is organized by domain modules (user.ts, menu.ts, order.ts)
Type Definition and Resolver Combined: Each module contains type definitions, Query, Mutation, and Field Resolver
No Forced Modularization: Can split files by domain, or put all Resolvers in one file
No Module Boundaries: No forced module boundaries, developers need to consciously follow

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

// User module: contains type definitions, Query, Mutation, Field Resolver
/**
 * User information
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  email: string
}

/** @gqlQueryField */
export function users(): User[] { ... }

/** @gqlQueryField */
export function user(id: Int): User { ... }

/** @gqlField */
export function orders(user: User): Order[] { ... }

/** @gqlMutationField */
export function createUser(name: string, email: string): User { ... }

Module Organization:

Each module file contains:
- Type definitions (@gqlType, @gqlInterface, @gqlUnion, @gqlEnum)
- Query Resolver (@gqlQueryField)
- Mutation Resolver (@gqlMutationField)
- Field Resolver (@gqlField)

Analysis:

✅ Supports organizing code by domain modules, type definitions and Resolvers are in the same module
✅ Provides modular API, can split files by domain
⚠️ Does not force modularization, can write coupled giant files (but can be avoided through design)
✅ Code organization is clear, easy to maintain and test

3.3 Parameter Definition & Type Inference

Score: 4.0

Evidence:

Automatic Parameter Type Inference: In typescript-graphql-schemas/grats/src/models/user.ts line 28 user(id: Int), id type is automatically inferred as Int
Parameter Resolution Mechanism: src/transforms/resolveResolverParams.ts:33-68 automatically resolves Resolver parameters, distinguishes GraphQL parameters, Context, Info
Complete IDE Hints: TypeScript fully understands parameter types, IDE autocomplete works normally
Requires Explicit Parameter Declaration: Function parameters need explicit type declaration (e.g., id: Int)

Parameter Type System (src/resolverSignature.ts:48-97):

SourceResolverArgument: Parent object (source)
ArgumentsObjectResolverArgument: Arguments object (args: { id: Int })
ContextResolverArgument: Context parameter (ctx: Ctx)
DerivedContextResolverArgument: Derived Context (through @gqlContext function)
InformationResolverArgument: Info parameter (info: GraphQLResolveInfo)
NamedResolverArgument: Named parameter (id: Int)

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/** @gqlQueryField */
export function user(id: Int): User {
  // id type automatically inferred as Int, IDE hints complete
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  return user
}

/** @gqlMutationField */
export function updateUser(
  id: Int,
  name?: string | null,
  email?: string | null
): User {
  // All parameter types automatically inferred, optional parameters automatically handled
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  if (name != null) user.name = name
  if (email != null) {
    if (!email.includes('@')) {
      throw new GraphQLError('Invalid email format')
    }
    user.email = email
  }
  return user
}

Context Injection Example (examples/production-app/ViewerContext.ts lines 48-54):

/** @gqlContext */
export type Ctx = YogaInitialContext & { vc: VC; credits: number }

/** @gqlContext */
export function getVc(ctx: Ctx): VC {
  return ctx.vc
}

// Used in Resolver
/** @gqlQueryField */
export function currentUser(vc: VC): User {
  // vc type automatically inferred as VC, injected through derived Context
  return vc.getUserById(vc.userId())
}

Parameter Resolution Mechanism (src/transforms/resolveResolverParams.ts:123-294):

Automatically identifies parameter types: identifies whether parameters are GraphQL parameters, Context, or Info through TypeScript type system
Supports derived Context: automatically injects derived Context defined through @gqlContext function
Validates parameter combinations: ensures parameter combinations are valid (e.g., cannot use positional parameters and arguments object simultaneously)

Analysis:

✅ Parameter types are mostly automatically inferred: automatically infers parameter types through TypeScript type system
✅ Complete IDE hints: TypeScript fully understands parameter types, IDE autocomplete works normally
⚠️ Requires explicit parameter declaration: function parameters need explicit type declaration (although this is a TypeScript requirement, it increases code volume)
✅ Type-safe: parameter types are completely synchronized with Schema definitions

3.4 Input Validation Mechanism

Score: 2.0

Evidence:

No Built-in Validation: All validation logic in typescript-graphql-schemas/grats/src/models/user.ts (lines 43-44, 58-60) needs to be manually written
Manual Error Throwing: Uses GraphQLError to manually throw validation errors
Validation Logic Scattered: Validation code is scattered across various Resolvers, difficult to reuse
No Declarative Validation API: Does not provide declarative validation API like .refine()

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/** @gqlMutationField */
export function createUser(name: string, email: string): User {
  // Manually write validation logic
  if (!email.includes('@')) {
    throw new GraphQLError('Invalid email format')
  }
  const id = incrementId()
  const newUser = { id, name, email } as unknown as User
  userMap.set(id, newUser)
  return newUser
}

/** @gqlMutationField */
export function updateUser(
  id: Int,
  name?: string | null,
  email?: string | null
): User {
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  if (name != null) user.name = name
  if (email != null) {
    // Validation logic repeated
    if (!email.includes('@')) {
      throw new GraphQLError('Invalid email format')
    }
    user.email = email
  }
  return user
}

Complex Validation Example (typescript-graphql-schemas/grats/src/models/order.ts lines 77-82):

/** @gqlMutationField */
export function createOrder(userId: Int, items: Int[]): Order {
  // Multiple validation conditions need to be manually written
  if (!userMap.has(userId)) throw new GraphQLError('User not found')
  if (items.length === 0) throw new GraphQLError('At least one item is required')
  for (const id of items) {
    if (!menuMap.has(id)) throw new GraphQLError(`Menu item not found`)
  }
  // ...
}

Analysis:

❌ No built-in validation: all validation logic needs to be manually written
❌ Validation logic scattered: validation code is scattered across various Resolvers, difficult to reuse
❌ No declarative validation API: does not provide declarative validation API like .refine()
⚠️ Can be implemented through helper functions: can create validation helper functions, but need to manually call them

3.5 Batch Loading (DataLoader) Integration

Score: 0.0

Evidence:

No Built-in DataLoader Support: No DataLoader-related implementation found in framework source code
Requires Manual Implementation: examples/production-app/ViewerContext.ts shows need to manually create DataLoader instances
Requires Manual Context Configuration: Need to manually add DataLoader instances to Context

Actual Usage Example (examples/production-app/ViewerContext.ts lines 18-36):

import DataLoader from "dataloader";
import { getPostsByIds, getUsersByIds, getLikesByIds } from "./Database";

export class VC {
  _postLoader: DataLoader<string, Post>;
  _userLoader: DataLoader<string, User>;
  _likeLoader: DataLoader<string, Like>;

  constructor() {
    // Need to manually create DataLoader instances
    this._postLoader = new DataLoader((ids) => getPostsByIds(this, ids));
    this._userLoader = new DataLoader((ids) => getUsersByIds(this, ids));
    this._likeLoader = new DataLoader((ids) => getLikesByIds(this, ids));
  }

  async getPostById(id: string): Promise<Post> {
    return this._postLoader.load(id);
  }
  // ...
}

/** @gqlContext */
export type Ctx = YogaInitialContext & { vc: VC; credits: number };

Usage in Resolver (requires manual call):

/** @gqlField */
export function user(post: Post, vc: VC): User {
  // Need to manually call DataLoader
  return vc.getUserById(post.userId);
}

Analysis:

❌ No built-in support: framework does not provide any DataLoader-related API or tools
❌ Requires lots of boilerplate code: need to manually create DataLoader instances, define Context types, configure Context injection
❌ No automatic batching: need to manually implement batching logic
❌ No cache control: need to manually implement cache logic

Score Details

3.1 Development Experience (Code Conciseness)

Score: 4.0

Reasons:

Functional API is concise and intuitive, conforms to TypeScript best practices
Parameter types are automatically inferred, no manual declaration needed
Requires JSDoc comments, each Resolver needs to be marked
Code structure is clear, easy to understand and maintain

3.2 Modular Design (Domain-Driven Development Support)

Score: 4.0

Reasons:

Supports organizing code by domain modules, type definitions and Resolvers are in the same module
Provides modular API, can split files by domain
Does not force modularization, can write coupled giant files (but can be avoided through design)
Code organization is clear, easy to maintain and test

3.3 Parameter Definition & Type Inference

Score: 4.0

Reasons:

Parameter types are mostly automatically inferred: automatically infers parameter types through TypeScript type system
Complete IDE hints: TypeScript fully understands parameter types, IDE autocomplete works normally
Requires explicit parameter declaration: function parameters need explicit type declaration (although this is a TypeScript requirement, it increases code volume)
Type-safe: parameter types are completely synchronized with Schema definitions

3.4 Input Validation Mechanism

Score: 2.0

Reasons:

No built-in validation: all validation logic needs to be manually written
Validation logic scattered: validation code is scattered across various Resolvers, difficult to reuse
No declarative validation API: does not provide declarative validation API like .refine()
Can be implemented through helper functions: can create validation helper functions, but need to manually call them

3.5 Batch Loading (DataLoader) Integration

Score: 0.0

Reasons:

No built-in support: framework does not provide any DataLoader-related API or tools
Requires lots of boilerplate code: need to manually create DataLoader instances, define Context types, configure Context injection
No automatic batching: need to manually implement batching logic
No cache control: need to manually implement cache logic

Overall Score

Resolvers & Validation Total Score: 2.8

Advantages:

Functional API is concise and intuitive, conforms to TypeScript best practices
Parameter types are automatically inferred, complete IDE hints
Supports organizing code by domain modules
Type-safe, parameter types are completely synchronized with Schema definitions

Disadvantages:

Requires JSDoc comments, code is slightly verbose
No built-in validation, need to manually implement all validation logic
No DataLoader support, need to manually implement batching
Validation logic scattered, difficult to reuse

4. Built-in Features

Grats provides some core built-in features, but advanced feature support is limited. Core features (Directives, Scalars, Subscriptions, Context) all have native support, but middleware, query complexity analysis, and other advanced features need to be manually implemented or through third-party libraries.

Feature Overview Table

Feature	Status	Description
Directive Support	✅ Built-in	Define directives through `@gqlDirective`, use directives through `@gqlAnnotate`, supports all GraphQL directive locations, API is concise and type-safe
Extension Support	⚠️ Plugin/Additional Implementation	Not built-in, but can be implemented through `GraphQLError`'s `extensions` parameter, requires manual handling
Custom Scalars	✅ Built-in	Mark custom scalar types through `@gqlScalar`, API is intuitive and type-safe
Subscription	✅ Built-in	Native GraphQL Subscriptions support, implemented through `@gqlSubscriptionField` and `AsyncIterable`, supports real-time data push, underlying transport protocol has good compatibility (WebSocket, SSE, etc.), API is concise
Context Injection	✅ Built-in	Native support for injecting context in Resolvers, mark Context type through `@gqlContext`, supports derived Context, type inference is complete, IDE hints are good
Middleware	⛔ Cannot Implement	Completely does not support middleware mechanism, cannot inject logic before/after Resolver execution (such as logging, permission checks, performance monitoring)
Query Complexity Analysis	⛔ Cannot Implement	Completely does not support query complexity analysis, cannot prevent complex query attacks
Depth Limiting	⛔ Cannot Implement	Completely does not support depth limiting, cannot prevent deep query attacks
Batch Loading (DataLoader)	⛔ Cannot Implement	No built-in support, need to manually create DataLoader instances (already evaluated in Phase 3)

Detailed Analysis

4.1 Directive Support

Status: ✅ Built-in

Evidence:

Directive Definition: src/Extractor.ts:67 defines DIRECTIVE_TAG = "gqlDirective"
Directive Usage: Mark directive usage through @gqlAnnotate (src/Extractor.ts:68)
Supports All Directive Locations: Supports FIELD_DEFINITION, ARGUMENT_DEFINITION, OBJECT, INTERFACE, ENUM, SCALAR, INPUT_OBJECT, INPUT_FIELD_DEFINITION, ENUM_VALUE, FRAGMENT_SPREAD, INLINE_FRAGMENT and all other GraphQL directive locations
Directive Argument Validation: src/validations/validateDirectiveArguments.ts validates directive argument types

Actual Usage Example (src/tests/fixtures/directives/directiveOnFieldDefinition.ts):

/**
 * This is my custom directive.
 * @gqlDirective on FIELD_DEFINITION
 */
export function max(args: { foo: Int }) {}

/**
 * All likes in the system. Note that there is no guarantee of order.
 * @gqlQueryField
 * @gqlAnnotate max(foo: 10)
 */
export function likes(args: { first?: Int | null }): string {
  return "hello";
}

Generated GraphQL Schema:

"""This is my custom directive."""
directive @max(foo: Int!) on FIELD_DEFINITION

type Query {
  """All likes in the system. Note that there is no guarantee of order."""
  likes(first: Int): String @max(foo: 10)
}

Directive Implementation Example (examples/production-app/graphql/directives.ts lines 6-20):

/**
 * Some fields cost credits to access. This directive specifies how many credits
 * a given field costs.
 *
 * @gqlDirective cost on FIELD_DEFINITION
 */
export function debitCredits(args: { credits: Int }, context: Ctx): void {
  if (context.credits < args.credits) {
    throw new GraphQLError(
      `Insufficient credits remaining. This field cost ${args.credits} credits.`,
    );
  }
  context.credits -= args.credits;
}

Analysis:

✅ Native support for defining and using GraphQL Directives
✅ Supports all GraphQL directive locations
✅ API is concise, defined and used through JSDoc comments
✅ Directive arguments are type-safe, automatically validated
⚠️ Directive implementation needs to be manually written (like debitCredits function), needs to be used with @graphql-tools/utils's mapSchema

4.2 Extension Support

Status: ⚠️ Plugin/Additional Implementation

Evidence:

Not Built-in: No native API related to Extensions found in framework source code
Can be Implemented through GraphQLError: Can implement error extensions through GraphQLError's extensions parameter
Cannot Declare Query Complexity: Cannot declare query complexity, execution time, and other extension information

Code Example (requires manual implementation):

import { GraphQLError } from 'graphql'

// Can be implemented through GraphQLError's extensions parameter
throw new GraphQLError('Expected error with extensions', {
  extensions: { code: 'EXPECTED_ERROR' }
})

Analysis:

⚠️ Not built-in support for Extensions native API
⚠️ Can be implemented through GraphQLError's extensions parameter, but requires manual handling
⚠️ Cannot declare query complexity, execution time, and other extension information
⚠️ Needs to be used with GraphQL Server's middleware or plugins

4.3 Custom Scalars

Status: ✅ Built-in

Evidence:

Scalar Definition: src/Extractor.ts:62 defines SCALAR_TAG = "gqlScalar"
Actual Usage: typescript-graphql-schemas/grats/src/graphql/CustomScalars.ts shows custom scalar definition
Type-safe: Scalar types are completely synchronized with TypeScript types

Actual Usage Example (typescript-graphql-schemas/grats/src/graphql/CustomScalars.ts):

/** @gqlScalar */
export type DateTime = Date

Generated GraphQL Schema (schema.graphql line 4):

scalar DateTime

Generated TypeScript Schema (src/schema.ts lines 121-124):

const DateTimeType: GraphQLScalarType = new GraphQLScalarType({
  name: "DateTime",
  ...config.scalars.DateTime
});

Analysis:

✅ Easy to define new scalar types, just mark with @gqlScalar
✅ API is intuitive, type-safe
⚠️ Does not include common scalars (like DateTime, JSON, BigInt), need to manually define or use third-party libraries (like graphql-scalars)
⚠️ Scalar serialization/deserialization logic needs to be manually provided in Schema configuration

4.4 Subscription

Status: ✅ Built-in

Evidence:

Subscription Field Marking: src/Extractor.ts:72 defines SUBSCRIPTION_FIELD_TAG = "gqlSubscriptionField"
AsyncIterable Support: src/validations/validateAsyncIterable.ts validates that subscription fields must return AsyncIterable
Actual Usage: examples/strict-semantic-nullability/Subscription.ts shows subscription usage

Actual Usage Example (examples/strict-semantic-nullability/Subscription.ts lines 3-9):

/** @gqlSubscriptionField */
export async function* countdown(args: { from: Int }): AsyncIterable<Int> {
  for (let i = args.from; i >= 0; i--) {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    yield i;
  }
}

Generated GraphQL Schema:

type Subscription {
  countdown(from: Int!): Int!
}

AsyncIterable Validation (src/validations/validateAsyncIterable.ts):

Requires all Subscription fields to return AsyncIterable
Automatically validated when building Schema

Analysis:

✅ Native support for GraphQL Subscriptions
✅ Supports real-time data push, implemented through async generator
✅ Underlying transport protocol has good compatibility (supports WebSocket, SSE, etc. through graphql-yoga)
✅ API is concise, type-safe
✅ Automatically validates subscription field return types

4.5 Context Injection

Status: ✅ Built-in

Evidence:

Context Marking: src/Extractor.ts:74 defines CONTEXT_TAG = "gqlContext"
Derived Context: Supports defining derived Context through @gqlContext function
Parameter Resolution: src/transforms/resolveResolverParams.ts automatically identifies and injects Context parameters

Actual Usage Example (examples/production-app/ViewerContext.ts lines 48-54):

/** @gqlContext */
export type Ctx = YogaInitialContext & { vc: VC; credits: number }

/** @gqlContext */
export function getVc(ctx: Ctx): VC {
  return ctx.vc
}

// Used in Resolver
/** @gqlQueryField */
export function currentUser(vc: VC): User {
  // vc type automatically inferred as VC, injected through derived Context
  return vc.getUserById(vc.userId())
}

Analysis:

✅ Native support for injecting context in Resolvers
✅ Supports derived Context, defined through @gqlContext function
✅ Context type inference is complete, IDE hints are good
✅ Automatically identifies Context parameters, no manual configuration needed

4.6 Middleware

Status: ⛔ Cannot Implement

Evidence:

No Related Support Found: No middleware-related code found in framework source code
No Middleware API: Does not provide API for injecting logic before/after Resolver execution

Analysis:

❌ Completely does not support middleware mechanism
❌ Cannot inject logic before/after Resolver execution (such as logging, permission checks, performance monitoring)
⚠️ Can implement similar functionality by manually wrapping Resolvers, but requires additional boilerplate code
⚠️ Can be implemented through GraphQL Server's middleware (like graphql-yoga's plugin system)

4.7 Query Complexity Analysis

Status: ⛔ Cannot Implement

Evidence:

No Related Support Found: No query complexity-related code found in framework source code
No Complexity Calculation API: Does not provide query complexity calculation and analysis API

Analysis:

❌ Completely does not support query complexity analysis
❌ Cannot prevent complex query attacks
⚠️ Can be implemented through graphql-yoga's plugins (like graphql-query-complexity), but requires additional configuration

4.8 Depth Limiting

Status: ⛔ Cannot Implement

Evidence:

No Related Support Found: No depth limiting-related code found in framework source code
No Depth Limiting API: Does not provide query depth limiting API

Analysis:

❌ Completely does not support depth limiting
❌ Cannot prevent deep query attacks
⚠️ Can be implemented through graphql-yoga's plugins (like graphql-depth-limit), but requires additional configuration

Built-in Features Overall Score

Score: 2.4

Scoring Basis:

Directives: ✅ Built-in (5 points) - Define through @gqlDirective, supports all GraphQL directive locations
Extensions: ⚠️ Plugin/Additional Implementation (2 points) - Can be implemented through GraphQLError's extensions parameter
DataLoader: ⛔ Cannot Implement (0 points) - No built-in support, need to manually create DataLoader instances
Scalars: ✅ Built-in (5 points) - Mark custom scalar types through @gqlScalar
Subscription: ✅ Built-in (5 points) - Native support, through @gqlSubscriptionField and AsyncIterable
Context: ✅ Built-in (5 points) - Native support, mark Context type through @gqlContext
Middleware: ⛔ Cannot Implement (0 points) - Completely does not support middleware mechanism
Query Complexity: ⛔ Cannot Implement (0 points) - Completely does not support query complexity analysis
Depth Limiting: ⛔ Cannot Implement (0 points) - Completely does not support depth limiting

Total Score: 22/45 = 2.4/5.0

Scoring Basis:

Core features are well supported: Directives, Scalars, Subscriptions, Context all provide native support
Advanced features have limited support: Middleware, Query Complexity, Depth Limiting are not supported
Feature completeness: Out of 9 features, 5 are built-in, 1 is plugin/additional implementation, 3 cannot be implemented

Advantages:

Core Features Complete: Directives, Scalars, Subscriptions, Context all provide native support
Type-safe: All supported features have complete type inference
API is Concise: Supported features have intuitive and easy-to-use APIs

Disadvantages:

Advanced Features Missing: Middleware, Query Complexity, Depth Limiting are not supported
Requires Manual Implementation: Some features (like directive implementation) need to be manually written
Depends on Third-party Libraries: Some features need to be used with GraphQL Server's plugins

5. Ecosystem Integration

Grats adopts a Standard GraphQL Schema Output + Manual Integration strategy. Outputs standard GraphQLSchema through getSchema(), can integrate with any GraphQL Server, but ORM and validation libraries require manual integration.

Core Integration Strategy

Source Code Evidence:

Schema output: typescript-graphql-schemas/grats/src/schema.ts's getSchema() function outputs standard GraphQLSchema instance
Standard compatibility: Generated Schema is a standard GraphQL.js instance, compatible with all GraphQL Servers
Official examples: examples/ directory contains multiple integration examples (Apollo Server, Yoga, Express GraphQL HTTP, Next.js)

5.1 ORM Integration Depth

Score: <-To Be Scored->

Evidence:

No Official Plugins: No official plugins found for Prisma, Drizzle, TypeORM, and other ORMs
Requires Manual Integration: All database operations in typescript-graphql-schemas/grats/src/models/user.ts are manually implemented (using in-memory Map)
Type Sync Requires Manual Maintenance: ORM model definitions are separated from GraphQL Schema definitions, need to manually maintain synchronization
Official Example: examples/production-app/Database.ts shows manually written database functions

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

// Need to manually define GraphQL types
/**
 * User information
 * @gqlType
 */
export type User = {
  /** @gqlField */
  id: Int
  /** @gqlField */
  name: string
  /** @gqlField */
  email: string
}

// Need to manually implement database queries
export const userMap = new Map<number, User>(USERS.map((u) => [u.id, { ...u } as unknown as User]))

/** @gqlQueryField */
export function users(): User[] {
  return Array.from(userMap.values())  // Manual query
}

/** @gqlQueryField */
export function user(id: Int): User {
  const user = userMap.get(id)  // Manual query
  if (!user) throw new GraphQLError('User not found')
  return user
}

Official Example (examples/production-app/Database.ts):

All database operations are manually written functions
Uses in-memory arrays to simulate database
Need to manually implement all CRUD operations

Analysis:

❌ No official plugins: Does not provide official plugins for Prisma, Drizzle, TypeORM, and other ORMs
❌ Requires lots of glue code: Must manually write all database query logic
❌ Type sync requires manual maintenance: ORM model definitions are separated from GraphQL Schema definitions, need to manually maintain synchronization
⚠️ Can manually integrate: Although can manually integrate ORM, requires lots of boilerplate code, and type sync needs to be manually maintained

5.2 Validation Library Integration

Score: <-To Be Scored->

Evidence:

No Official Plugins: No official plugins found for Zod, Yup, Valibot, and other validation libraries
Requires Manual Integration: All validation logic needs to be manually written in Resolvers (typescript-graphql-schemas/grats/src/models/user.ts lines 43-44, 58-60)
Validation Logic Separated from Schema Definition: Validation code is scattered across various Resolvers, difficult to reuse

Actual Usage Example (typescript-graphql-schemas/grats/src/models/user.ts):

/** @gqlMutationField */
export function createUser(name: string, email: string): User {
  // Need to manually write validation logic
  if (!email.includes('@')) {
    throw new GraphQLError('Invalid email format')
  }
  const id = incrementId()
  const newUser = { id, name, email } as unknown as User
  userMap.set(id, newUser)
  return newUser
}

/** @gqlMutationField */
export function updateUser(
  id: Int,
  name?: string | null,
  email?: string | null
): User {
  const user = userMap.get(id)
  if (!user) throw new GraphQLError('User not found')
  if (name != null) user.name = name
  if (email != null) {
    // Validation logic repeated
    if (!email.includes('@')) {
      throw new GraphQLError('Invalid email format')
    }
    user.email = email
  }
  return user
}

Complex Validation Example (typescript-graphql-schemas/grats/src/models/order.ts lines 77-82):

/** @gqlMutationField */
export function createOrder(userId: Int, items: Int[]): Order {
  // Multiple validation conditions need to be manually written
  if (!userMap.has(userId)) throw new GraphQLError('User not found')
  if (items.length === 0) throw new GraphQLError('At least one item is required')
  for (const id of items) {
    if (!menuMap.has(id)) throw new GraphQLError(`Menu item not found`)
  }
  // ...
}

Analysis:

❌ No official plugins: Does not provide official plugins for Zod, Yup, Valibot, and other validation libraries
❌ Requires manual integration: All validation logic needs to be manually written in Resolvers
❌ Validation logic separated from Schema definition: Validation code is scattered across various Resolvers, difficult to reuse
❌ Requires lots of boilerplate code: Each validation scenario needs to be manually written
⚠️ Can manually integrate: Although can manually integrate validation libraries (like calling Zod in Resolvers), requires lots of boilerplate code

5.3 GraphQL Server Compatibility

Score: <-To Be Scored->

Evidence:

Outputs Standard GraphQL Schema: typescript-graphql-schemas/grats/src/schema.ts's getSchema() function outputs standard GraphQLSchema instance
Compatible with Standard GraphQL.js: Generated Schema is a standard GraphQL.js instance, compatible with all GraphQL Servers
Official Examples Cover Mainstream Servers: examples/ directory contains multiple integration examples:
- Apollo Server (examples/apollo-server/)
- GraphQL Yoga (examples/yoga/)
- Express GraphQL HTTP (examples/express-graphql-http/)

Apollo Server Integration (examples/apollo-server/server.ts):

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { getSchema } from "./schema";

async function main() {
  const server = new ApolloServer({ schema: getSchema() });
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
  });
  console.log(`Running a GraphQL API server at ${url}`);
}

GraphQL Yoga Integration (examples/yoga/server.ts):

import { createServer } from "node:http";
import { createYoga } from "graphql-yoga";
import { getSchema } from "./schema";

const yoga = createYoga({
  schema: getSchema(),
});

const server = createServer(yoga);
server.listen(4000, () => {
  console.log("Running a GraphQL API server at http://localhost:4000/graphql");
});

Express GraphQL HTTP Integration (examples/express-graphql-http/server.ts):

import * as express from "express";
import { createHandler } from "graphql-http/lib/use/express";
import { getSchema } from "./schema";

const app = express();
app.post(
  "/graphql",
  createHandler({
    schema: getSchema(),
  }),
);
app.listen(4000);

Analysis:

✅ Fully compatible: Fully compatible with all mainstream GraphQL Servers
✅ Zero configuration: Just pass the generated Schema to the Server
✅ Official examples are complete: Provides multiple mainstream Server integration examples
✅ Type-safe: Schema configuration interface is type-safe (SchemaConfig)

5.4 Toolchain Integration

Score: <-To Be Scored->

Evidence:

TypeScript/JavaScript Support

TypeScript Support:

Core Mechanism: Grats is a TypeScript compiler plugin, generates GraphQL Schema through static analysis of TypeScript code
TypeScript Compiler Dependency: grats/src/cli.ts uses typescript package and TypeScript compiler API (ts.createProgram, ts.createCompilerHost)
TypeScript Plugin: grats/src/tsPlugin/initTsPlugin.ts provides TypeScript Language Service plugin, supports IDE real-time diagnostics
All Examples are TypeScript: All official examples (examples/apollo-server/, examples/yoga/, examples/next-js/, etc.) use TypeScript

JavaScript Support:

allowJs Option Support: examples/next-js/tsconfig.json line 8 configures "allowJs": true, indicating JavaScript files can be processed
But Requires TypeScript Compiler: Grats itself needs TypeScript compiler to run, even processing JavaScript files requires tsconfig.json configuration
Generated Code is TypeScript: examples/next-js/schema.ts shows generated Schema file is TypeScript format

Code Evidence:

grats/src/cli.ts (lines 1-50):

#!/usr/bin/env node

import * as E from "./Errors";
import { Location } from "graphql";
import { getParsedTsConfig } from "./";
import {
  SchemaAndDoc,
  buildSchemaAndDocResult,
  extractSchemaAndDoc,
} from "./lib";
import { Command } from "commander";
import { writeFileSync } from "fs";
import { resolve, dirname } from "path";
import { version } from "../package.json";
import { locate } from "./Locate";
import {
  printGratsSDL,
  printExecutableSchema,
  printEnumsModule,
} from "./printSchema";
import * as ts from "typescript";

grats/examples/next-js/tsconfig.json (line 8):

    "allowJs": true,

Runtime Environment Support

Node.js:

✅ Explicitly Supported: All official examples are Node.js environment
- examples/apollo-server/server.ts uses @apollo/server
- examples/yoga/server.ts uses graphql-yoga and Node.js HTTP server
- examples/express-graphql-http/server.ts uses Express
- examples/production-app/server.ts uses graphql-yoga
Official Documentation Explicitly States: website/docs/01-getting-started/01-quick-start.mdx line 51 uses import { createServer } from "node:http"
package.json Engine Requirements: grats/package.json lines 46-48 specify "engines": { "node": ">=20 <=24" }

Bun:

⚠️ Theoretically Supported but Not Verified:
- Generated Schema code is standard TypeScript/JavaScript, theoretically can run in Bun
- But no Bun-related documentation, examples, or configuration
- All examples use Node.js runtime

Deno:

⚠️ Theoretically Supported but Not Verified:
- Generated Schema code is standard TypeScript/JavaScript, theoretically can run in Deno
- But no Deno-related documentation, examples, or configuration
- Grats CLI uses Node.js-specific APIs (fs, path), needs Node.js environment to run

Cloudflare Workers:

⚠️ Theoretically Supported but Not Verified:
- Generated Schema code is standard TypeScript/JavaScript, theoretically can run in Cloudflare Workers
- But no Cloudflare Workers-related documentation, examples, or configuration
- All examples are Node.js server-side code

Browser:

⚠️ Only for Playground:
- website/src/pages/exec/index.tsx uses @typescript/vfs to run TypeScript compiler in browser, but this is for online Playground, not actual usage scenario
- website/src/pages/exec/index.tsx lines 15-24 simulate process.cwd(), indicating special handling is needed to run in browser
- All actual usage examples are server-side code

Code Evidence:

grats/website/docs/01-getting-started/01-quick-start.mdx (lines 50-66):

import { createServer } from "node:http";
import { createYoga } from "graphql-yoga";
import { getSchema } from "./schema.js"; // Will be generated by Grats

/** @gqlQueryField */
export function hello(): string {
  return "Hello world!";
}

const yoga = createYoga({ schema: getSchema() });
const server = createServer(yoga);

server.listen(4000, () => {
  console.log("Running a GraphQL API server at http://localhost:4000/graphql");
});

grats/package.json (lines 46-48):

  "engines": {
    "node": ">=20 <=24"
  },

Build Tool Support

Next.js:

✅ Official Example: examples/next-js/ provides complete Next.js App Router integration example
Next.js Configuration: examples/next-js/next.config.js uses default configuration, no special build tool configuration needed
TypeScript Configuration: examples/next-js/tsconfig.json uses Next.js recommended TypeScript configuration (moduleResolution: "bundler", allowJs: true)
Official Documentation: website/docs/05-examples/08-next-js.md provides Next.js integration documentation

TypeScript Compiler (tsc):

✅ Core Dependency: All examples use tsc to compile TypeScript code
Build Scripts:
- examples/apollo-server/package.json line 7: "start": "tsc && node dist/server.js"
- examples/yoga/package.json line 7: "start": "tsc && node dist/server.js"
- examples/express-graphql-http/package.json line 7: "start": "tsc && node dist/server.js"
TypeScript Configuration Examples:
- examples/apollo-server/tsconfig.json uses module: "NodeNext", moduleResolution: "NodeNext"
- examples/yoga/tsconfig.json uses module: "NodeNext", moduleResolution: "NodeNext"
- examples/production-app/tsconfig.json uses module: "NodeNext", moduleResolution: "NodeNext"

Webpack:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide webpack configuration examples
- website/package.json line 45 contains "webpack": "^5.78.0", but this is for website build, not framework's build tool integration
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Vite:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide vite configuration examples
- No vite-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Rspack:

⚠️ No Official Configuration Example:
- Documentation and examples do not provide rspack configuration examples
- No rspack-related configuration files or documentation
- Theoretically can integrate through TypeScript compiler, but requires user to configure themselves

Grats CLI as Build Step:

✅ Independent CLI Tool: grats/src/cli.ts implements independent command-line tool, does not depend on specific build tools
Workflow: website/docs/05-guides/01-workflows.md recommends running Grats as build step (npm run grats), then using TypeScript compiler to compile
Watch Mode: Supports --watch option, can automatically regenerate Schema during development

Code Evidence:

grats/examples/next-js/next.config.js (lines 1-5):

/** @type {import('next').NextConfig} */
const nextConfig = {};

module.exports = nextConfig;

grats/examples/apollo-server/tsconfig.json (lines 6-14):

  "compilerOptions": {
    "outDir": "dist",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "esnext",
    "lib": ["esnext"],
    "strict": true
  }

grats/examples/yoga/tsconfig.json (lines 6-15):

  "compilerOptions": {
    "outDir": "dist",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "esnext",
    "lib": ["esnext"],
    "strict": true,
    "skipLibCheck": true
  }

Analysis:

✅ Native TypeScript Support: Completely based on TypeScript compiler, provides complete TypeScript support
✅ Node.js Explicitly Supported: All official examples are Node.js environment, documentation explicitly states
⚠️ JavaScript Support Limited: Although supports allowJs, requires TypeScript compiler, not true native JavaScript support
⚠️ Other Runtime Environments Not Verified: Bun, Deno, Cloudflare Workers theoretically supported, but no documentation or examples
⚠️ Browser Not Supported: Only for Playground, not actual usage scenario
✅ Next.js Official Example: Provides complete Next.js integration example
✅ TypeScript Compiler Integration: All examples use tsc, integration is simple
⚠️ Other Build Tools No Official Support: webpack, vite, rspack have no official configuration examples, requires user to configure themselves
✅ Independent CLI Tool: Does not depend on specific build tools, can be flexibly integrated as build step

Score Details

5.1 ORM Integration Depth

Score: <-To Be Scored->

Reasons:

No official plugins: Does not provide official plugins for Prisma, Drizzle, TypeORM, and other ORMs
Requires lots of glue code: Must manually write all database query logic
Type sync requires manual maintenance: ORM model definitions are separated from GraphQL Schema definitions, need to manually maintain synchronization
Can manually integrate: Although can manually integrate ORM, requires lots of boilerplate code

5.2 Validation Library Integration

Score: <-To Be Scored->

Reasons:

No official plugins: Does not provide official plugins for Zod, Yup, Valibot, and other validation libraries
Requires manual integration: All validation logic needs to be manually written in Resolvers
Validation logic separated from Schema definition: Validation code is scattered across various Resolvers, difficult to reuse
Requires lots of boilerplate code: Each validation scenario needs to be manually written

5.3 GraphQL Server Compatibility

Score: <-To Be Scored->

Reasons:

Fully compatible: Fully compatible with all mainstream GraphQL Servers
Zero configuration: Just pass the generated Schema to the Server
Official examples are complete: Provides multiple mainstream Server integration examples
Type-safe: Schema configuration interface is type-safe

5.4 Toolchain Integration

Score: <-To Be Scored->

Reasons:

Native TypeScript Support: Completely based on TypeScript compiler, provides complete TypeScript support, all examples are TypeScript
JavaScript Support Limited: Although supports allowJs, requires TypeScript compiler, not true native JavaScript support
Node.js Explicitly Supported: All official examples are Node.js environment, documentation explicitly states, package.json specifies Node.js engine requirements
Other Runtime Environments Not Verified: Bun, Deno, Cloudflare Workers theoretically supported (generated code is standard TypeScript/JavaScript), but no documentation, examples, or configuration
Browser Not Supported: Only for Playground (through @typescript/vfs), not actual usage scenario
Next.js Official Example: Provides complete Next.js App Router integration example and documentation
TypeScript Compiler Integration: All examples use tsc, integration is simple, runs as build step
Other Build Tools No Official Support: webpack, vite, rspack have no official configuration examples, requires user to configure themselves
Independent CLI Tool: Does not depend on specific build tools, can be flexibly integrated as build step, supports watch mode

Overall Score

Ecosystem Integration Total Score: 3.0

Advantages:

Excellent GraphQL Server compatibility, fully compatible with all mainstream Servers
Next.js official examples are complete
Standard GraphQL Schema output, integration is simple

Disadvantages:

ORM integration requires manual implementation, no official plugins
Validation library integration requires manual implementation, no official plugins
Requires lots of boilerplate code, type sync needs to be manually maintained

📝 Summary

Overall Score: 3.1/5.0

Dimension	Score	Description
Architecture	3.5	Lightweight dependencies, uses standard JSDoc comments, but requires build step, configuration is slightly complex
Type Definition	4.5	Fully supports native TypeScript syntax, powerful type inference, automatic interface field inheritance
Resolvers & Validation	2.8	Functional API is concise, parameter types are automatically inferred, but no built-in validation and DataLoader
Built-in Features	2.4	Core features are complete (Directives, Scalars, Subscriptions), but advanced features are missing
Ecosystem Integration	3.0	Excellent GraphQL Server compatibility, but ORM and validation libraries require manual integration

Overall Evaluation

Grats adopts the Static Analysis architecture pattern, analyzing JSDoc comments and type definitions in source code through the TypeScript compiler API to generate GraphQL Schema at compile time. This is an Implementation-First approach, using TypeScript code as the single source of truth. Type inference is strong, fully supports native TypeScript syntax, interface fields are automatically inherited. But requires build step, validation and DataLoader need to be manually implemented, advanced feature support is limited.

Core Advantages

Uses Standard JSDoc: Conforms to TypeScript best practices, does not depend on decorators or reflection metadata
Powerful Type Inference: Fully supports native TypeScript syntax, automatically analyzes complex type structures
Automatic Interface Field Inheritance: No need to redeclare common fields when implementing interfaces
Zero Configuration Enums: Supports TypeScript Enum and string union types, completely zero configuration
Type Definitions and Schema Definitions Completely Synchronized: TypeScript code is the single source of truth

Main Disadvantages

Requires Build Step: Must run grats CLI command to generate Schema, cannot "write and use immediately"
Requires Many JSDoc Comments: Each Resolver requires JSDoc comments, code is slightly verbose
No Built-in Validation: All validation logic needs to be manually written, validation code is repeated
No DataLoader Support: Need to manually implement, requires lots of boilerplate code
Advanced Features Missing: Middleware, Query Complexity, Depth Limiting are not supported

Use Cases

Recommended For

Teams that prefer Implementation-First approach
Projects that need powerful type inference
Projects that don't mind build steps
Projects that need automatic interface field inheritance

Not Recommended For

Projects that need "write and use immediately"
Projects that need validation or DataLoader
Projects that need advanced features (Middleware, query complexity)
Projects that want to reduce JSDoc comments

Improvement Suggestions

Provide Validation and DataLoader Support: Reduce manual implementation, improve development efficiency
Reduce JSDoc Comment Requirements: Reduce comments through better type inference
Provide Middleware and Query Complexity Support: Meet advanced feature needs
Support Runtime Build: Provide optional runtime build mode, reduce build step dependency

gqtx Evaluation Report

Mon, 05 Jan 2026 13:00:36 +0000

📋 Basic Information

Item	Content
Current Version	0.9.3
GitHub	https://github.com/sikanhe/gqtx
Documentation	GitHub README
First Commit	2019-10-12
Latest Commit	2024-01-05

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture	5.0	Minimal dependencies, pure runtime build, zero magic, fully neutral
2. Type Definition	1.5	Logical association, explicit registration, requires manual synchronization
3. Resolvers & Validation	1.8	Parameter types can be inferred, but no modularity, no validation, no DataLoader
4. Built-in Features	2.8	Core features are complete, but advanced features are missing
5. Ecosystem Integration	2.5	GraphQL Server compatibility is good, but ORM and validation library integration is missing

1. Architecture

1.1 Architecture Overview

gqtx adopts the Builder pattern, explicitly constructing an intermediate representation (IR) of the GraphQL Schema through a functional API, then converting it to a standard graphql-js Schema at runtime via buildGraphQLSchema().

Core Design Philosophy (from WHY.md):

Avoid errors from manual type conversion
No code generation tools or SDL files needed
No dependency on decorators, reflection metadata, or other "magic"

1.2 Dependency Complexity

Score: 5.0

Evidence:

Runtime dependencies: Only graphql as a peerDependency (package.json:58-60)
Zero runtime overhead: No decorators, no reflect-metadata, no third-party runtime dependencies
Build dependencies: Only used for packaging (Rollup + TypeScript), does not affect runtime

// package.json
"peerDependencies": {
  "graphql": "^16.7.0"
}

Comparison with actual business code (typescript-graphql-schemas/gqtx/src/schema.ts):

Business code only imports gqtx and graphql, no additional dependencies
Uses graphql-scalars as an optional enhancement (not a framework requirement)

1.3 Build Flow

Score: 5.0

Evidence:

Pure runtime build: Built via buildGraphQLSchema() at server startup (src/build.ts:16-44)
No code generation: No CLI tools needed, no type file generation
No build step: Can directly run TypeScript code during development

Actual usage example (typescript-graphql-schemas/gqtx/src/schema.ts:450):

export const schema = buildGraphQLSchema({ query, mutation })

Build process (src/build.ts):

Receives intermediate representation (Schema<RootSrc>)
Recursively converts types via toGraphQLOutputType()
Uses Map to cache converted types, avoiding duplicate builds
Returns standard graphql.GraphQLSchema instance

Framework's own build (rollup.config.js):

Only used for packaging during release (ESM + CJS dual format)
Does not affect user usage, users don't need to care about the framework's build process

1.4 Config & Language Magic

Score: 5.0

Evidence:

Zero magic: No decorators, reflection metadata, or non-standard TS syntax
Functional API: Explicitly defined through functions like Gql.Object(), Gql.Field(), Gql.Enum()
Type inference: Achieves type safety using TypeScript generics and conditional types (src/define.ts:158-185)

Type safety implementation (src/define.ts:158-185):

export function Field<Key extends string, Src, Out, Arg extends object = {}>({
  name,
  type,
  resolve,
  args,
  ...options
}: {
  name: Key;
  type: OutputType<Out>;
  args?: ArgMap<Arg>;
  // Conditional types ensure resolve function signature matches type definition
} & (Key extends keyof Src
  ? Src[Key] extends Out
    ? ResolvePartialOptional<Src, Arg, Out>
    : ResolvePartialMandatory<Src, Arg, Out>
  : ResolvePartialMandatory<Src, Arg, Out>))

Context type extension (src/types.ts:6):

Implements global Context type through TypeScript module augmentation
No configuration needed, conforms to TypeScript standard practices

Actual usage (typescript-graphql-schemas/gqtx/src/schema.ts):

All type definitions are explicit function calls
No configuration files or special compilation options needed

1.5 Ecosystem Integration

Score: 5.0

Evidence:

Fully neutral: Generates standard graphql-js Schema, can integrate with any GraphQL Server
Standard installation: Can be used via npm install gqtx, no special requirements
Flexible integration: Supports Express, GraphQL Yoga, Apollo Server, etc.

Official example integration (examples/starwars.ts:365-378):

import express from 'express';
import graphqlHTTP from 'express-graphql';

app.use(
  '/graphql',
  graphqlHTTP({
    schema: buildGraphQLSchema(schema),
    graphiql: true,
  })
);

Actual business integration (typescript-graphql-schemas/gqtx/src/server.ts):

import { createYoga } from 'graphql-yoga'
import { schema } from './schema.ts'

const yoga = createYoga({ schema })

Framework source code verification (src/build.ts:16-44):

buildGraphQLSchema() returns standard graphql.GraphQLSchema
Fully compatible with graphql-js ecosystem

1.6 Architecture Summary

Evaluation Item	Score	Description
Dependency Complexity	5.0	Only depends on `graphql`, zero runtime overhead
Build Flow	5.0	Pure runtime build, no code generation
Config & Magic	5.0	Zero magic, fully conforms to native TS practices
Ecosystem Integration	5.0	Fully neutral, can integrate with any GraphQL Server

Overall Score: 5.0

Advantages:

Minimal dependencies, no runtime overhead
Write and use immediately, no build steps
Zero magic, conforms to TypeScript best practices
Fully neutral, excellent ecosystem compatibility

Disadvantages:

Need to explicitly define all types (slightly more code compared to auto-inference frameworks)
Does not support SDL-first development mode (not friendly to teams preferring SDL)

2. Type Definition

2.1 Single Source of Truth Implementation

Score: 2.0 - Logical Association

Evidence:

TypeScript types and GraphQL types are defined separately: Need to define TypeScript types first, then define GraphQL types (typescript-graphql-schemas/gqtx/src/schema.ts:10-41, 106-187)
Fields need to be manually repeated: When implementing interfaces, must manually repeat all common fields (schema.ts:123-146)

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Step 1: Define TypeScript type
type Coffee = {
  __typename: 'Coffee'
  id: number
  name: string
  price: number
  sugarLevel: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'
  origin: string
}

// Step 2: Define GraphQL Interface
const FoodInterface = Gql.InterfaceType({
  name: 'Food',
  fields: () => [
    Gql.AbstractField({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.AbstractField({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.AbstractField({ name: 'price', type: Gql.NonNull(Gql.Float) }),
  ],
})

// Step 3: Define GraphQL Object (need to manually repeat interface fields)
const CoffeeType = Gql.Object<Coffee>({
  name: 'Coffee',
  interfaces: [FoodInterface],
  fields: () => [
    // ⚠️ Must manually repeat interface fields
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.Field({ name: 'price', type: Gql.NonNull(Gql.Float) }),
    // Specific fields
    Gql.Field({ name: 'sugarLevel', type: Gql.NonNull(SugarLevelEnum) }),
    Gql.Field({ name: 'origin', type: Gql.NonNull(Gql.String) }),
  ],
})

Analysis:

✅ Type safe: Binds TypeScript type through generic <Coffee>, ensuring type consistency
✅ Logical association: TypeScript types and GraphQL types are bound through generic parameters, type system can check consistency
❌ Field repetition: When implementing interfaces, must manually repeat all interface fields, cannot auto-inherit
❌ No auto-sync: After modifying TypeScript types, need to manually sync GraphQL type definitions
❌ No validation integration: Cannot auto-generate type definitions from validation rules (e.g., Zod)

Comparison with framework source code (gqtx/src/build.ts:182-213):

Framework merges interface fields into implementation types during build (interfaces: (typeof t.interfaces === 'function' ? t.interfaces() : t.interfaces).map(...))
But still need to manually declare during definition, only merged at runtime

2.2 Enum & String Union Support

Score: 2.0 - Explicit Registration

Evidence:

Need manual mapping: Must explicitly register each enum value via Gql.Enum() (schema.ts:64-83)
Does not support direct use of TypeScript Enum: Need to manually map each value
String union types need manual mapping: Cannot directly use 'A' | 'B' type

Code example (typescript-graphql-schemas/gqtx/src/schema.ts:64-83):

// TypeScript type definition
type Coffee = {
  sugarLevel: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'  // String union type
  // ...
}

// Must manually map each value
const SugarLevelEnum = Gql.Enum({
  name: 'SugarLevel',
  description: 'Sugar level for coffee',
  values: [
    { name: 'NONE', value: 'NONE' },
    { name: 'LOW', value: 'LOW' },
    { name: 'MEDIUM', value: 'MEDIUM' },
    { name: 'HIGH', value: 'HIGH' },
  ],
})

// Using TypeScript Enum also requires manual mapping (examples/starwars.ts:147-155)
enum Episode {
  NEWHOPE = 4,
  EMPIRE = 5,
  JEDI = 6,
}

const episodeEnum = Gql.Enum({
  name: 'Episode',
  values: [
    { name: 'NEWHOPE', value: Episode.NEWHOPE },
    { name: 'EMPIRE', value: Episode.EMPIRE },
    { name: 'JEDI', value: Episode.JEDI },
  ],
})

Analysis:

✅ Type safe: Enum values are fully synchronized in TypeScript and GraphQL
✅ Explicit control: Can precisely control the name and value of each enum value
❌ Manual mapping: Need to manually write mapping code for each enum value
❌ No auto-inference: Cannot auto-generate GraphQL Enum from TypeScript Enum or string union types
❌ Maintenance cost: Adding new enum values requires modifying both TypeScript types and GraphQL definitions

Comparison with test cases (gqtx/test/simple.spec.ts:146-154):

Test cases also require manual enum value mapping
Framework does not provide auto-inference mechanism

2.3 Interface Inheritance & Union Type Experience

Score: 2.0 - Logical Resolution

Evidence:

Interface fields need to be manually repeated: When implementing interfaces, must manually repeat all common fields (schema.ts:123-146)
Union types need manual resolveType implementation: Must manually write type resolution logic (schema.ts:148-155)
Need to manually add __typename: Union type data must include __typename field (schema.ts:16-17, 26-27)

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Interface definition
const FoodInterface = Gql.InterfaceType({
  name: 'Food',
  fields: () => [
    Gql.AbstractField({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.AbstractField({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.AbstractField({ name: 'price', type: Gql.NonNull(Gql.Float) }),
  ],
})

// Implementing interface (need to manually repeat fields)
const CoffeeType = Gql.Object<Coffee>({
  name: 'Coffee',
  interfaces: [FoodInterface],
  fields: () => [
    // ⚠️ Must manually repeat interface fields
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.Field({ name: 'price', type: Gql.NonNull(Gql.Float) }),
    Gql.Field({ name: 'sugarLevel', type: Gql.NonNull(SugarLevelEnum) }),
    Gql.Field({ name: 'origin', type: Gql.NonNull(Gql.String) }),
  ],
})

// Union type definition (need to manually implement resolveType)
const MenuItemType = Gql.Union({
  name: 'MenuItem',
  types: [CoffeeType, DessertType],
  resolveType: (value: MenuItem) => {
    // ⚠️ Must manually implement type resolution logic
    return value.__typename === 'Coffee' ? 'Coffee' : 'Dessert'
  },
})

// TypeScript type must include __typename (schema.ts:16-17, 26-27)
type Coffee = {
  __typename: 'Coffee'  // ⚠️ Must manually add
  // ...
}

Analysis:

✅ Supports abstract types: Supports Interface and Union types
✅ Type safe: Ensures type consistency through generics
❌ Manual field repetition: When implementing interfaces, must manually repeat all common fields
❌ Manual type resolution: Union types need manual resolveType function implementation
❌ Need __typename: Data must include __typename field, requires manual maintenance

Comparison with framework source code (gqtx/src/build.ts:186-189):

Framework merges interface fields during build (interfaces: ...map((intf) => toGraphQLOutputType(intf, typeMap)))
But still need to manually declare during definition, only merged at runtime

Comparison with official examples (gqtx/examples/starwars.ts:157-170, 239-282):

Official examples also require manual interface field repetition
Union types also require manual resolveType implementation

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 2.0 - On-demand Annotation

Evidence:

Base types can be inferred: Can infer base types through generic parameter <User>
Field types need explicit declaration: Each field's type must be explicitly declared (schema.ts:110-112)
Parameter types can be inferred: Resolver parameter types can be auto-inferred (src/define.ts:158-185)
Arrays and nullability need explicit declaration: Need to explicitly declare using Gql.List(), Gql.NonNull()

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Base type inference (through generic parameter)
const UserType = Gql.Object<User>({  // ✅ User type auto-inferred
  name: 'User',
  fields: () => [
    // ⚠️ Field types need explicit declaration
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.Field({ name: 'email', type: Gql.NonNull(Gql.String) }),
  ],
})

// Parameter type auto-inference (src/define.ts:158-185)
Gql.Field({
  name: 'user',
  type: UserType,
  args: {
    id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
  },
  resolve: (_, { id }) => {  // ✅ id type auto-inferred as number
    // ...
  },
})

// Arrays and nullability need explicit declaration
Gql.Field({
  name: 'users',
  type: Gql.NonNull(Gql.List(Gql.NonNull(UserType))),  // ⚠️ Need explicit declaration
  resolve: () => Array.from(userMap.values()),
})

Type safety implementation (gqtx/src/define.ts:158-185):

export function Field<Key extends string, Src, Out, Arg extends object = {}>({
  name,
  type,
  resolve,
  args,
  ...options
}: {
  name: Key;
  type: OutputType<Out>;
  args?: ArgMap<Arg>;
  // Conditional types ensure resolve function signature matches type definition
} & (Key extends keyof Src
  ? Src[Key] extends Out
    ? ResolvePartialOptional<Src, Arg, Out>  // Field exists and type matches, resolve optional
    : ResolvePartialMandatory<Src, Arg, Out>  // Field doesn't exist or type doesn't match, resolve required
  : ResolvePartialMandatory<Src, Arg, Out>))

Analysis:

✅ Parameter type auto-inference: Resolver parameter types can be auto-inferred, no manual declaration needed
✅ Return value type checking: Ensures resolve function return value type matches field type through conditional types
✅ Field existence checking: If field name exists in source type, resolve function is optional
⚠️ Field types need explicit declaration: Each field's type must be explicitly declared, cannot auto-infer from TypeScript types
⚠️ Arrays and nullability need explicit declaration: Need to explicitly declare using Gql.List(), Gql.NonNull()

2.5 Type Definition Summary

Evaluation Item	Score	Description
Single Source of Truth	2.0	TypeScript types and GraphQL types are logically associated, but require manual synchronization
Enum Support	2.0	Requires explicit registration, no auto-inference
Interface Inheritance	2.0	Supports interfaces, but requires manual field repetition
Union Types	2.0	Supports Union, but requires manual resolveType implementation
Type Inference	2.0	Parameter types can be inferred, field types need explicit declaration

Overall Score: 1.5

Advantages:

Type safe: Ensures type consistency through generics and conditional types
Parameter type auto-inference: Resolver parameter types can be auto-inferred
Explicit control: All type definitions are explicit, easy to understand and debug

Disadvantages:

Field repetition: When implementing interfaces, must manually repeat all common fields
Manual mapping: Enums and Union types require manual mapping and implementation
No auto-sync: After modifying TypeScript types, need to manually sync GraphQL type definitions
Maintenance cost: Need to maintain both TypeScript types and GraphQL definitions

3. Resolvers & Validation

3.1 Developer Experience (Code Conciseness)

Score: 3.0 - Moderate Code Volume

Evidence:

Need to explicitly define all fields: Each field needs to be explicitly defined via Gql.Field() (typescript-graphql-schemas/gqtx/src/schema.ts:195-246)
Parameter type auto-inference: Resolver parameter types can be auto-inferred (schema.ts:206, 258)
Validation logic manually written: All validation logic needs to be manually written in Resolvers (schema.ts:259, 400-404)

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Query definition (need to explicitly define each field)
const query = Gql.Query({
  fields: () => [
    Gql.Field({
      name: 'users',
      type: Gql.NonNull(Gql.List(Gql.NonNull(UserType))),
      resolve: () => Array.from(userMap.values()),
    }),
    Gql.Field({
      name: 'user',
      type: UserType,
      args: {
        id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
      },
      resolve: (_, { id }) => {  // ✅ id type auto-inferred as number
        const user = userMap.get(id)
        if (!user) throw new GraphQLError('User not found')
        return user
      },
    }),
  ],
})

// Mutation definition (validation logic needs to be manually written)
const mutation = Gql.Mutation({
  fields: () => [
    Gql.Field({
      name: 'createUser',
      type: Gql.NonNull(UserType),
      args: {
        name: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
        email: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
      },
      resolve: (_, { name, email }) => {
        // ⚠️ Validation logic needs to be manually written
        if (!email.includes('@')) throw new GraphQLError('Invalid email format')
        const id = incrementId()
        const newUser: User = { id, name, email }
        userMap.set(id, newUser)
        return newUser
      },
    }),
  ],
})

Code volume analysis:

Complete User module (Query + Mutation + Field Resolver) requires approximately 150+ lines of code
Each field needs explicit type and resolver definition
Validation logic is scattered across various Resolvers

Analysis:

✅ Parameter type auto-inference: Resolver parameter types can be auto-inferred, no manual declaration needed
✅ Type safe: Ensures resolve function signature matches type definition through conditional types (src/define.ts:158-185)
⚠️ Need to explicitly define fields: Each field needs to be explicitly defined via Gql.Field(), more code volume
⚠️ Validation logic manually written: All validation logic needs to be manually written in Resolvers, cannot define declaratively

3.2 Modular Design (Domain-Driven Development Support)

Score: 0.0 - No Modularity Consideration

Evidence:

Organized by operation type: All Queries and Mutations are in one object, organized by operation type (schema.ts:193-247, 249-444)
No enforced module boundaries: No enforced module boundaries, all Resolvers are in the same file
Easy to write coupled code: If not careful, easy to write all domain Query/Mutation/Field Resolvers in one file

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// All Queries are in one object, organized by operation type
const query = Gql.Query({
  fields: () => [
    // User related
    Gql.Field({ name: 'users', /* ... */ }),
    Gql.Field({ name: 'user', /* ... */ }),
    // Menu related
    Gql.Field({ name: 'menu', /* ... */ }),
    Gql.Field({ name: 'menuItem', /* ... */ }),
    // Order related
    Gql.Field({ name: 'orders', /* ... */ }),
    Gql.Field({ name: 'order', /* ... */ }),
  ],
})

// All Mutations are in one object
const mutation = Gql.Mutation({
  fields: () => [
    // User related
    Gql.Field({ name: 'createUser', /* ... */ }),
    Gql.Field({ name: 'updateUser', /* ... */ }),
    // Menu related
    Gql.Field({ name: 'createCoffee', /* ... */ }),
    // Order related
    Gql.Field({ name: 'createOrder', /* ... */ }),
    // ... All Mutations mixed together
  ],
})

File structure (typescript-graphql-schemas/gqtx/src/):

All code is in one file schema.ts (451 lines)
Not split by domain
Can manually split, but framework doesn't enforce module boundaries

Analysis:

❌ Completely isolated by operation type: Query, Mutation are organized separately, not by domain
❌ No enforced module boundaries: No enforced module boundaries, easy to write coupled giant files
⚠️ Can manually split: Although can split by domain and manually combine, framework doesn't provide modular API
❌ No DDD support: Lacks enforced module boundaries, easy to write coupled code

3.3 Parameter Definition & Type Inference

Score: 4.0 - Parameter Types Mostly Auto-inferred

Evidence:

Parameters defined in fields: Parameters are defined in fields via args object (schema.ts:203-205, 254-257)
Parameter type auto-inference: Resolver parameter types can be auto-inferred (schema.ts:206, 258)
IDE hints complete: TypeScript fully understands parameter types, IDE autocomplete works normally

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Parameters defined in fields
Gql.Field({
  name: 'user',
  type: UserType,
  args: {
    id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
  },
  resolve: (_, { id }) => {  // ✅ id type auto-inferred as number
    const user = userMap.get(id)
    if (!user) throw new GraphQLError('User not found')
    return user
  },
})

// Multiple parameters auto-inferred
Gql.Field({
  name: 'createUser',
  type: Gql.NonNull(UserType),
  args: {
    name: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
    email: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
  },
  resolve: (_, { name, email }) => {  // ✅ name and email types auto-inferred
    // name: string, email: string
  },
})

Type safety implementation (gqtx/src/define.ts:121-143):

export function Arg<
  Src,
  TDefault extends Exclude<Src, null | undefined> | undefined
>({
  type,
  description,
  default: defaultArg,
}: {
  type: InputType<Src>;
  description?: string;
  default?: TDefault;
}): Argument<
  TDefault extends undefined
    ? Exclude<Src, undefined>
    : Exclude<Src, null | undefined>
> {
  // Ensures parameter type correctness through conditional types
}

Analysis:

✅ Parameter types mostly auto-inferred: Auto-infers parameter types through ArgMap and conditional types, no manual declaration needed
✅ IDE hints complete: TypeScript fully understands parameter types, IDE autocomplete works normally
✅ Type safe: Parameter types are fully synchronized with Schema definition
⚠️ Need to explicitly define args: Although types can be inferred, need to explicitly define args object in fields

3.4 Input Validation Mechanism

Score: 2.0 - No Built-in Validation, Requires Complete Manual Implementation

Evidence:

No built-in validation: typescript-graphql-schemas/gqtx/src/schema.ts (lines 259, 400-404) all validation logic needs to be manually written
Validation logic scattered: Validation code is scattered across various Resolvers, hard to reuse
No declarative API: Does not provide declarative validation API like .refine()

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Method 1: Manual validation in Resolver (schema.ts:258-264)
Gql.Field({
  name: 'createUser',
  type: Gql.NonNull(UserType),
  args: {
    name: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
    email: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
  },
  resolve: (_, { name, email }) => {
    // ⚠️ Validation logic needs to be manually written
    if (!email.includes('@')) throw new GraphQLError('Invalid email format')
    const id = incrementId()
    const newUser: User = { id, name, email }
    userMap.set(id, newUser)
    return newUser
  },
})

// Method 2: Complex validation logic (schema.ts:399-415)
Gql.Field({
  name: 'createOrder',
  type: Gql.NonNull(OrderType),
  args: {
    userId: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
    items: Gql.Arg({ type: Gql.NonNullInput(Gql.ListInput(Gql.NonNullInput(Gql.Int))) }),
  },
  resolve: (_, { userId, items }) => {
    // ⚠️ All validation logic needs to be manually written
    if (items.length === 0) throw new GraphQLError('At least one item is required')
    if (!userMap.has(userId)) throw new GraphQLError('User not found')
    for (const itemId of items) {
      if (!menuItemMap.has(itemId)) throw new GraphQLError(`Menu item not found`)
    }
    // ...
  },
})

Validation logic duplication:

Email validation is duplicated in createUser and updateUser (schema.ts:259, 279)
Need to manually maintain validation logic consistency

Analysis:

❌ No built-in validation: Does not provide declarative validation API (like .refine() or @IsEmail())
❌ Validation logic duplication: Need to manually write validation code in each place that needs validation
❌ Validation logic scattered: Validation code is scattered across various Resolvers, hard to reuse
❌ No declarative API: Does not provide declarative validation API like .refine()
⚠️ Can be implemented via Scalar: Theoretically can implement validation via custom Scalar's parseValue, but need to create independent Scalar types for each validation scenario, increasing code volume

3.5 DataLoader Integration

Score: 0.0 - No Built-in Support

Evidence:

No built-in DataLoader support: No DataLoader-related implementation found in framework source code (no DataLoader-related code in gqtx/src/ directory)
Need manual implementation: Need to manually create DataLoader instances, define Context types, configure Context injection

Code example (requires manual implementation):

// Need to manually install and configure DataLoader
import DataLoader from 'dataloader'
import { GqlContext } from 'gqtx'

// Extend Context type
declare module 'gqtx' {
  interface GqlContext {
    userLoader: DataLoader<number, User>
    orderLoader: DataLoader<number, Order>
  }
}

// Create DataLoader instance
const userLoader = new DataLoader<number, User>(async (ids) => {
  return ids.map(id => userMap.get(id))
})

// Use in Resolver
Gql.Field({
  name: 'user',
  type: UserType,
  args: {
    id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
  },
  resolve: (_, { id }, ctx) => {
    return ctx.userLoader.load(id)  // Need to manually configure Context
  },
})

Analysis:

❌ No built-in support: Framework does not provide any DataLoader-related API or tools
❌ Requires lots of boilerplate: Need to manually create DataLoader instances, define Context types, configure Context injection
❌ No auto batching: Need to manually implement batching logic
❌ No cache control: Need to manually implement cache logic

3.6 Resolvers & Validation Summary

Evaluation Item	Score	Description
Developer Experience	<-待评分->	Moderate code volume, parameter types can be inferred, but need explicit field definition
Modular Design	<-待评分->	No modularity consideration, completely organized by operation type, no enforced module boundaries
Parameter Definition	<-待评分->	Parameter types mostly auto-inferred, IDE hints complete
Input Validation	<-待评分->	No built-in validation, requires complete manual implementation, validation logic scattered
DataLoader Integration	<-待评分->	No built-in support, requires lots of boilerplate

Overall Score: <-待评分->

Advantages:

Parameter type auto-inference: Resolver parameter types can be auto-inferred, IDE hints complete
Type safe: Ensures type consistency through conditional types
Explicit control: All definitions are explicit, easy to understand and debug

Disadvantages:

No modularity support: Completely organized by operation type, no enforced module boundaries
No built-in validation: All validation logic needs to be manually written, validation logic scattered
No DataLoader support: Requires manual implementation, requires lots of boilerplate
More code volume: Need to explicitly define all fields, more code compared to other frameworks

4. Built-in Features

Feature Support Overview

gqtx provides native support for core features (Context, Subscriptions, Custom Scalars, Directives, Extensions), but has limited support for advanced features (DataLoader, Middleware, Query Complexity, Depth Limiting).

Feature Support Details Table

Feature	Support Status	Implementation Method	Evidence/Description
Directives	✅ Built-in Support	Native Built-in	`gqtx/src/types.ts` (line 219) and `src/build.ts` (line 43) support passing `GraphQLDirective[]` via `directives` parameter
Extensions	✅ Built-in Support	Native Built-in	`gqtx/src/define.ts` (lines 25-32) and `src/build.ts` (lines 203, 209) support defining extensions on Field and ObjectType
DataLoader	⛔ Cannot Implement	Not Supported	Already evaluated in Phase 4, no built-in support, requires manual implementation
Custom Scalars	✅ Built-in Support	Native Built-in	`gqtx/src/define.ts` (lines 79-102) defined via `Gql.Scalar()`, API is intuitive and type-safe
Subscription	✅ Built-in Support	Native Built-in	`gqtx/src/define.ts` (lines 377-424) and `test/simple.spec.ts` (lines 604-668) native support, implemented via async generator
Context	✅ Built-in Support	Native Built-in	`gqtx/src/types.ts` (line 6) implements global Context type via module augmentation of `GqlContext` interface, type inference is complete
Middleware	⛔ Cannot Implement	Not Supported	No related support found, cannot inject middleware logic before/after Resolver execution
Query Complexity	⛔ Cannot Implement	Not Supported	No related support found, cannot prevent complex query attacks
Depth Limiting	⛔ Cannot Implement	Not Supported	No related support found, needs to be implemented via GraphQL Server middleware or plugins

Detailed Analysis

4.1 Directive Support

Status: ✅ Built-in Support

Evidence:

gqtx/src/types.ts (line 219) Schema type supports directives?: graphql.GraphQLDirective[]
gqtx/src/build.ts (line 43) passes directives: schema.directives when building Schema
gqtx/CHANGELOG.md (lines 49, 54) records support for passing directives

Code example:

import { GraphQLDirective, DirectiveLocation } from 'graphql'

// Manually create GraphQLDirective instance
const deprecatedDirective = new GraphQLDirective({
  name: 'deprecated',
  description: 'Marks an element as deprecated',
  locations: [DirectiveLocation.FIELD_DEFINITION],
  args: {
    reason: {
      type: graphql.GraphQLString,
      defaultValue: 'No longer supported',
    },
  },
})

// Pass to buildGraphQLSchema
const schema = buildGraphQLSchema({
  query: Query,
  mutation: Mutation,
  directives: [deprecatedDirective],  // ✅ Supports passing directives
})

Analysis:

✅ Native support for Directives definition and usage
✅ Supports Federation Directives (via manually creating GraphQLDirective instances)
⚠️ Need to manually create GraphQLDirective instances, no declarative API
✅ API is type-safe, fully compatible with graphql-js

4.2 Extension Support

Status: ✅ Built-in Support

Evidence:

gqtx/src/define.ts (lines 25-32) defines ExtensionsMap type
gqtx/src/build.ts (lines 203, 209) passes extensions field during build
gqtx/src/types.ts (lines 119, 143) Field and ObjectType support extensions?: Record<string, any>

Code example:

// Field extension
Gql.Field({
  name: 'user',
  type: UserType,
  extensions: {
    complexity: 10,  // ✅ Supports extension information
    rateLimit: { max: 100, window: '1m' },
  },
  resolve: (_, { id }) => { /* ... */ },
})

// ObjectType extension
const UserType = Gql.Object<User>({
  name: 'User',
  extensions: {
    cacheControl: { maxAge: 3600 },
  },
  fields: () => [/* ... */],
})

Analysis:

✅ Native support for GraphQL Extensions definition and usage
✅ Can declare query complexity (complexity), execution time and other extension information
✅ API is intuitive, supports defining extensions on Field and ObjectType
⚠️ Needs to be used with GraphQL Server middleware or plugins (like graphql-query-complexity)

4.3 DataLoader Integration

Status: ⛔ Cannot Implement

Evidence:

Already evaluated in Phase 4, framework does not provide any DataLoader-related API or tools
Need to manually create DataLoader instances, define Context types, configure Context injection

Analysis:

❌ No built-in support: Framework does not provide any DataLoader-related API
❌ Requires lots of boilerplate: Need to manually create DataLoader instances, define Context types, configure Context injection
❌ No auto batching: Need to manually implement batching logic
❌ No cache control: Need to manually implement cache logic

4.4 Custom Scalars

Status: ✅ Built-in Support

Evidence:

gqtx/src/define.ts (lines 79-102) defines custom scalars via Gql.Scalar()
typescript-graphql-schemas/gqtx/src/schema.ts (lines 57-62) shows DateTime scalar definition
gqtx/src/build.ts (lines 151-162) handles custom scalars during build

Code example (typescript-graphql-schemas/gqtx/src/schema.ts:57-62):

import { GraphQLDateTime } from 'graphql-scalars'

const DateTime = Gql.Scalar({
  name: 'DateTime',
  serialize: GraphQLDateTime.serialize,
  parseValue: GraphQLDateTime.parseValue,
  parseLiteral: GraphQLDateTime.parseLiteral,
})

Analysis:

✅ Easy to define new scalar types, API is intuitive
✅ Type-safe, supports generic parameters to specify input/output types
✅ Can integrate with libraries like graphql-scalars
⚠️ Does not include common scalars (like DateTime, JSON, BigInt), need to manually define or use third-party libraries

4.5 Subscription

Status: ✅ Built-in Support

Evidence:

gqtx/src/define.ts (lines 377-424) provides Gql.Subscription() and Gql.SubscriptionField() API
gqtx/test/simple.spec.ts (lines 604-668) shows complete Subscription test cases
gqtx/src/build.ts (lines 31-33, 66-90) handles Subscription during build

Code example (gqtx/test/simple.spec.ts:604-628):

const GraphQLSubscriptionObject = Gql.Subscription({
  name: 'Subscription',
  fields: () => [
    Gql.SubscriptionField({
      name: 'greetings',
      type: Gql.NonNull(Gql.String),
      subscribe: async function* () {
        for (const greeting of ['hi', 'ola', 'sup', 'hello']) {
          yield greeting
        }
      },
    }),
  ],
})

const schema = buildGraphQLSchema({
  query: Query,
  subscription: GraphQLSubscriptionObject,  // ✅ Supports Subscription
})

Analysis:

✅ Native support for GraphQL Subscriptions
✅ Supports real-time data push, implemented via async generator
✅ Good underlying transport protocol compatibility (supports WebSocket, SSE, etc. through graphql-js)
✅ API is concise, type-safe

4.6 Context Injection

Status: ✅ Built-in Support

Evidence:

gqtx/src/types.ts (line 6) defines GqlContext interface
gqtx/examples/starwars.ts (lines 12-16) shows defining Context via module augmentation
gqtx/src/define.ts (lines 158-185) Field's resolve function automatically receives Context parameter

Code example (gqtx/examples/starwars.ts:12-16):

// Define Context via module augmentation
declare module '../src/types.js' {
  interface GqlContext {
    contextContent: string
  }
}

// Use in Resolver
Gql.Field({
  name: 'contextContent',
  type: Gql.String,
  resolve: (_, _args, ctx) => ctx.contextContent,  // ✅ Context auto-injected
})

Analysis:

✅ Native support for injecting context in Resolvers
✅ Context type inference is complete, implements global types via module augmentation
✅ Good IDE hints, no manual type declaration needed
✅ Type-safe, all Resolvers' Context types are automatically unified

4.7 Middleware

Status: ⛔ Cannot Implement

Evidence:

No related support found, cannot inject middleware logic before/after Resolver execution
Framework does not provide middleware API

Analysis:

❌ Completely does not support middleware mechanism
❌ Cannot inject logic before/after Resolver execution (like logging, permission checks, performance monitoring)
⚠️ Can implement similar functionality by manually wrapping Resolver functions, but requires lots of boilerplate

4.8 Query Complexity Analysis

Status: ⛔ Cannot Implement

Evidence:

No related support found, cannot prevent complex query attacks
Although can declare complexity via Extensions, needs to be used with external libraries

Analysis:

❌ Does not built-in support query complexity calculation and analysis
⚠️ Can declare complexity via Extensions, but needs to be used with libraries like graphql-query-complexity
❌ Cannot automatically or declaratively calculate query complexity

4.9 Depth Limiting

Status: ⛔ Cannot Implement

Evidence:

No related support found, cannot prevent depth query attacks
Needs to be implemented via GraphQL Server middleware or plugins

Analysis:

❌ Completely does not support depth limiting
⚠️ Needs to be implemented via GraphQL Server middleware or plugins (like graphql-depth-limit)
❌ Cannot automatically limit query nesting depth

4.10 Built-in Features Summary

Feature	Support Status	Description
Directives	✅ Built-in Support	Native support, but need to manually create `GraphQLDirective` instances
Extensions	✅ Built-in Support	Native support, can define extension information on Field and ObjectType
DataLoader	⛔ Cannot Implement	No built-in support, requires manual implementation
Custom Scalars	✅ Built-in Support	Native support, API is intuitive and type-safe
Subscription	✅ Built-in Support	Native support, implements real-time data push via async generator
Context	✅ Built-in Support	Native support, implements global types via module augmentation, type inference is complete
Middleware	⛔ Cannot Implement	No built-in support, cannot inject logic before/after Resolver execution
Query Complexity	⛔ Cannot Implement	No built-in support, needs to be implemented via external libraries
Depth Limiting	⛔ Cannot Implement	No built-in support, needs to be implemented via GraphQL Server middleware or plugins

Comprehensive Assessment:

✅ Core features complete: Context, Subscriptions, Custom Scalars, Directives, Extensions all have native support
❌ Advanced features missing: DataLoader, Middleware, Query Complexity, Depth Limiting have no built-in support
⚠️ Needs external library support: Some features (like query complexity, depth limiting) need to be implemented via external libraries or GraphQL Server middleware

5. Ecosystem Integration

Core Integration Strategy

gqtx adopts a standard GraphQL Schema output + manual integration strategy. Outputs standard GraphQLSchema via buildGraphQLSchema(), can integrate with any GraphQL Server, but requires manual adaptation. Mainly demonstrates integration with express-graphql and graphql-yoga, other Servers and frameworks need to integrate via standard GraphQL Server.

Scoring Details

5.1 ORM Integration Depth

Score: <-待评分-> - Weak Integration

Evidence:

No official plugins: No official plugins found for Prisma, Drizzle, TypeORM, etc.
Requires manual integration: All database operations in typescript-graphql-schemas/gqtx/src/schema.ts are manually implemented (using in-memory Map)
Type synchronization requires manual maintenance: ORM model definitions and GraphQL Schema definitions are separated, require manual synchronization

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Need to manually define TypeScript type
type User = {
  id: number
  name: string
  email: string
}

// Need to manually define GraphQL type
const UserType = Gql.Object<User>({
  name: 'User',
  fields: () => [
    Gql.Field({ name: 'id', type: Gql.NonNull(Gql.Int) }),
    Gql.Field({ name: 'name', type: Gql.NonNull(Gql.String) }),
    Gql.Field({ name: 'email', type: Gql.NonNull(Gql.String) }),
  ],
})

// Need to manually implement database queries
const query = Gql.Query({
  fields: () => [
    Gql.Field({
      name: 'users',
      type: Gql.NonNull(Gql.List(Gql.NonNull(UserType))),
      resolve: () => Array.from(userMap.values()),  // Manual query
    }),
    Gql.Field({
      name: 'user',
      type: UserType,
      args: {
        id: Gql.Arg({ type: Gql.NonNullInput(Gql.Int) }),
      },
      resolve: (_, { id }) => userMap.get(id),  // Manual query
    }),
  ],
})

Analysis:

❌ No official plugins: Does not provide official plugins for Prisma, Drizzle, TypeORM, etc.
❌ Requires lots of glue code: Must manually write all database query logic
❌ Type synchronization requires manual maintenance: ORM model definitions and GraphQL Schema definitions are separated, require manual synchronization
⚠️ Can manually integrate: Although can manually integrate ORM, requires lots of boilerplate, and type synchronization needs manual maintenance

5.2 Validation Library Integration

Score: <-待评分-> - Weak Integration

Evidence:

No official plugins: No official plugins found for Zod, Yup, Valibot, etc.
Requires manual integration: All validation logic needs to be manually written in Resolvers (schema.ts:259, 400-404)
Validation logic separated from Schema definition: Validation code is scattered across various Resolvers, hard to reuse

Code example (typescript-graphql-schemas/gqtx/src/schema.ts):

// Method 1: Manual validation in Resolver
Gql.Field({
  name: 'createUser',
  type: Gql.NonNull(UserType),
  args: {
    name: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
    email: Gql.Arg({ type: Gql.NonNullInput(Gql.String) }),
  },
  resolve: (_, { name, email }) => {
    // ⚠️ Validation logic needs to be manually written
    if (!email.includes('@')) throw new GraphQLError('Invalid email format')
    // ...
  },
})

// Method 2: Implement validation via Scalar (need to manually create Scalar)
const EmailScalar = Gql.Scalar({
  name: 'Email',
  serialize: (value) => value,
  parseValue: (value) => {
    // ⚠️ Need to manually call validation library
    if (!z.string().email().safeParse(value).success) {
      throw new GraphQLError('Invalid email format')
    }
    return value
  },
  parseLiteral: (ast) => {
    // ⚠️ Need to manually call validation library
    if (ast.kind !== 'StringValue') throw new GraphQLError('Invalid email')
    if (!z.string().email().safeParse(ast.value).success) {
      throw new GraphQLError('Invalid email format')
    }
    return ast.value
  },
})

Analysis:

❌ No official plugins: Does not provide official plugins for Zod, Yup, Valibot, etc.
❌ Validation logic duplication: Need to manually write validation code in each place that needs validation
❌ Validation logic scattered: Validation code is scattered across various Resolvers, hard to reuse
⚠️ Can be implemented via Scalar: Theoretically can implement validation via custom Scalar's parseValue, but need to create independent Scalar types for each validation scenario, increasing code volume
❌ Validation logic separated from Schema definition: Validation rules are separated from Schema definition, require manual synchronization

5.3 GraphQL Server Compatibility

Score: <-待评分-> - Standard Compatible

Evidence:

Fully compatible with standard GraphQL.js: gqtx/src/build.ts (lines 16-44) returns standard graphql.GraphQLSchema
Official example shows integration: gqtx/examples/starwars.ts (lines 365-378) shows integration with express-graphql
Actual business integration: typescript-graphql-schemas/gqtx/src/server.ts shows integration with graphql-yoga

Code example:

// Method 1: Integration with express-graphql (gqtx/examples/starwars.ts:365-378)
import express from 'express'
import graphqlHTTP from 'express-graphql'

const app = express()
app.use(
  '/graphql',
  graphqlHTTP({
    schema: buildGraphQLSchema(schema),  // ✅ Standard GraphQLSchema
    graphiql: true,
  })
)

// Method 2: Integration with graphql-yoga (typescript-graphql-schemas/gqtx/src/server.ts)
import { createYoga } from 'graphql-yoga'

const yoga = createYoga({ schema })  // ✅ Standard GraphQLSchema
const server = createServer(yoga)
server.listen(4000)

Analysis:

✅ Compatible with standard GraphQL.js: Outputs standard GraphQLSchema, can integrate with any GraphQL Server
✅ Not bound to specific Server: Can integrate with Apollo Server, GraphQL Yoga, express-graphql, Envelop, Hono, etc.
⚠️ Requires manual adaptation: Although compatible, requires manual adaptation, no official adapters provided
⚠️ Documentation mainly shows express-graphql: Integration documentation for other Servers is incomplete, need to refer to official examples

5.4 Toolchain Integration

Score: <-待评分->

TypeScript/JavaScript Support:

Source code completely uses TypeScript: All files in gqtx/src/ directory are .ts files (index.ts, build.ts, define.ts, types.ts, relay.ts)
Build output supports ESM and CommonJS: gqtx/package.json (lines 5-7) provides both main: "cjs/index.cjs" and module: "index.js", exports field (lines 8-30) supports both import and require
Uses standard TypeScript syntax: gqtx/tsconfig.json (lines 1-19) shows using TypeScript 5.1.6, target ES2019, no special compiler features (like decorators, reflect-metadata)
JavaScript usage not explicitly stated: Documentation and examples are all TypeScript, not explicitly stated whether JavaScript can be used directly

Runtime Environment Support:

Node.js: ✅ Explicitly supported. Official example gqtx/examples/starwars.ts (lines 365-378) shows integration with Express; gqtx/package.json (line 45) includes @types/node as dev dependency
Bun: ⚠️ Theoretically supported but not verified. Source code has no Node.js-specific APIs (no fs, path, http, process imports in gqtx/src/ directory), only depends on graphql package, but no Bun-related documentation or examples
Deno: ⚠️ Theoretically supported but not verified. Source code has no Node.js-specific APIs, but no Deno-related documentation, examples or configuration
Cloudflare Workers: ⚠️ Theoretically supported but not verified. Source code has no Node.js-specific APIs, but no Cloudflare Workers-related documentation, examples or configuration
Browser: ⚠️ Theoretically supported but not verified. Source code has no Node.js-specific APIs, but no browser runtime examples or documentation; gqtx/README.md explicitly states it's a "GraphQL server" library, mainly for server-side

Build Tool Support:

Framework itself uses Rollup: gqtx/rollup.config.js (lines 25-39) uses Rollup and @rollup/plugin-typescript for building, outputs ESM and CommonJS formats
User project build tools: ⚠️ No official configuration examples. Documentation and examples do not provide configuration examples for webpack, vite, rspack, etc.; user projects can use any build tool, but need to configure themselves
TypeScript configuration: gqtx/tsconfig.json (lines 1-19) shows using target: "ES2019", module: "ESNext", moduleResolution: "NodeNext", user projects need to adjust configuration according to target environment

Code Evidence:

// gqtx/src/index.ts - Source code only depends on graphql, no Node.js-specific APIs
export * from './types.js';
export * from './define.js';
export {
  buildGraphQLSchema,
  toGraphQLInputType,
  toGraphQLOutputType,
} from './build.js';

// gqtx/package.json - Supports both ESM and CommonJS
{
  "type": "module",
  "main": "cjs/index.cjs",
  "module": "index.js",
  "exports": {
    ".": {
      "import": { "default": "./index.js" },
      "require": { "default": "./cjs/index.cjs" }
    }
  }
}

// gqtx/examples/starwars.ts - Only shows Node.js + Express example
import express = require('express');
import graphqlHTTP = require('express-graphql');
const app = express();
app.use('/graphql', graphqlHTTP({ schema: buildGraphQLSchema(schema) }));
app.listen(5000);

Analysis:

✅ TypeScript native support: Framework is completely written in TypeScript, compiled to JavaScript, supports ESM and CommonJS
✅ Node.js explicitly supported: Official examples and documentation explicitly show Node.js environment usage
✅ Source code has no runtime binding: Source code only depends on graphql package, no Node.js-specific APIs, theoretically can run in any JavaScript environment
⚠️ Other runtimes not verified: Bun, Deno, Cloudflare Workers, browser, etc. have no documentation, examples or configuration, users need to verify and adapt themselves
⚠️ Build tool integration missing: No official configuration examples for webpack, vite, rspack, etc., users need to configure themselves
⚠️ Mainly for server-side: Documentation and examples are all server-side usage scenarios, no browser or edge environment usage guides

5.5 Ecosystem Integration Summary

Evaluation Item	Score	Description
ORM Integration Depth	<-待评分->	Weak integration, no official plugins, requires lots of glue code, type synchronization requires manual maintenance
Validation Library Integration	<-待评分->	Weak integration, no official plugins, validation logic separated from Schema definition, requires lots of boilerplate
GraphQL Server Compatibility	<-待评分->	Standard compatible, fully compatible with standard GraphQL.js, can integrate with any GraphQL Server
Toolchain Integration	<-待评分->	TypeScript native support, Node.js explicitly supported, other runtimes not verified, build tool integration missing

Overall Score: 2.5

Advantages:

Excellent GraphQL Server compatibility: Fully compatible with standard GraphQL.js, can integrate with any GraphQL Server
TypeScript native support: Framework is completely written in TypeScript, compiled to JavaScript, supports ESM and CommonJS
Source code has no runtime binding: Source code only depends on graphql package, no Node.js-specific APIs, theoretically can run in any JavaScript environment
Fully neutral: Not bound to specific Server or framework, highly flexible

Disadvantages:

ORM integration missing: No official plugins, requires lots of glue code, type synchronization requires manual maintenance
Validation library integration missing: No official plugins, validation logic separated from Schema definition, requires lots of boilerplate
Other runtimes not verified: Bun, Deno, Cloudflare Workers, browser, etc. have no documentation, examples or configuration
Build tool integration missing: No official configuration examples for webpack, vite, rspack, etc.
Limited integration documentation: Mainly provides express-graphql examples, other environments need to adapt themselves

📝 Summary

Overall Score: 2.3/5.0

Dimension	Score	Description
Architecture	5.0	Minimal dependencies, pure runtime build, zero magic, fully neutral
Type Definition	1.5	Logical association, explicit registration, requires manual synchronization
Resolvers & Validation	1.8	Parameter types can be inferred, but no modularity, no validation, no DataLoader
Built-in Features	2.8	Core features are complete, but advanced features are missing
Ecosystem Integration	2.5	GraphQL Server compatibility is good, but ORM and validation library integration is missing

Overall Evaluation

gqtx adopts the Builder pattern, achieving a design philosophy of minimal dependencies and zero magic. Only depends on graphql standard library, completely runtime build, no code generation, fully conforms to native TypeScript best practices. However, support is limited in type definition, modularity, validation, and DataLoader, requiring lots of manual work.

Core Advantages

Minimal dependencies: Only depends on graphql standard library, zero runtime overhead
Zero magic: Fully conforms to native TypeScript best practices, does not use decorators, reflection metadata
Write and use immediately: Pure runtime build, no code generation, supports hot reload
Parameter type auto-inference: Resolver parameter types can be auto-inferred, IDE hints complete
Fully neutral: Not bound to any framework, can integrate with all GraphQL Servers

Main Disadvantages

Type definition requires manual maintenance: TypeScript types and GraphQL types are defined separately, require manual synchronization
No modularity support: Completely organized by operation type, no enforced module boundaries, easy to write coupled code
No built-in validation: All validation logic needs to be manually written, validation code duplication
No DataLoader support: Requires manual implementation, requires lots of boilerplate
Interface fields need to be repeated: When implementing interfaces, must manually repeat all common fields

Use Cases

Recommended Use

Small projects requiring minimal dependencies and zero magic
Projects with low type synchronization requirements
Projects that don't need modularity, validation, or DataLoader

Not Recommended Use

Medium to large projects requiring modularity and type synchronization
Projects requiring validation or DataLoader
Projects requiring automatic interface field inheritance

Improvement Suggestions

Provide type auto-sync mechanism: Auto-generate GraphQL types from TypeScript types, reduce manual maintenance
Enhance modularity support: Provide domain-organized API, enforce module boundaries
Provide validation and DataLoader support: Reduce boilerplate, improve development efficiency
Support automatic interface field inheritance: Reduce field repetition

GQLoom Evaluation Report

Mon, 05 Jan 2026 09:24:14 +0000

📋 Basic Information

Item	Content
Version	0.15.0
GitHub	https://github.com/modevol-com/gqloom
Docs	https://gqloom.dev
First Commit	2024-03-14
Latest Commit	2026-01-02

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture	5.0	Minimal dependencies, pure runtime build, zero magic, fully neutral
2. Type Definition	5.0	Deep inference, zero-config enums, smart inheritance, powerful type inference
3. Resolvers & Validation	5.0	Minimal code, chainable API, declarative validation, native DataLoader
4. Built-in Features	4.0	Core features complete, native Context/Middleware/DataLoader support
5. Ecosystem Integration	5.0	Deep ORM integration, seamless validation library integration, full Server compatibility, framework support

1. Architecture

Architecture Overview

GQLoom adopts the Weaving pattern, combining Resolver definitions and runtime types (such as Zod Schema) into a GraphQL Schema at runtime through the weave() function. The core design philosophy is "zero magic": no decorators, reflection metadata, or code generation, running entirely on native TypeScript and JavaScript.

Core Implementation Locations:

packages/core/src/schema/schema-loom.ts: GraphQLSchemaLoom class and weave() function
packages/core/src/resolver/resolver.ts: Resolver factory functions and chainable API
packages/zod/src/index.ts: Zod Weaver implementation, converting Zod Schema to GraphQL types

1.1 Dependency Complexity

Score: 5.0

Core Dependency Analysis:

@gqloom/core's package.json shows:
- Peer Dependency: Only graphql >= 16.8.0 (standard GraphQL library)
- Dev Dependency: @standard-schema/spec (only for type definitions, not used at runtime)
- Runtime Dependencies: Zero additional dependencies

Evidence:

// packages/core/package.json
"peerDependencies": {
  "graphql": ">= 16.8.0"
},
"devDependencies": {
  "@standard-schema/spec": "1.1.0"
}

Conclusion: GQLoom achieves minimal dependency design, depending only on the GraphQL standard library, with zero runtime overhead and no additional third-party dependencies.

1.2 Build Flow

Score: 5.0

Build Method:

Uses tsdown for compilation (packages/core/tsdown.config.ts), supporting both ESM and CJS format output
Pure Runtime Build: No code generation (CodeGen) or dedicated CLI build steps required
Schema generation is completed entirely at runtime, directly generating GraphQLSchema instances through the weave() function

Actual Usage Evidence:

// src/schema.ts
export const schema = weave(ZodWeaver, zodWeaverConfig, userResolver, menuResolver, orderResolver)

// src/print.ts - Only for printing Schema, not a required step
const sdl = printSchema(lexicographicSortSchema(schema))

Conclusion: Write and use immediately, pure runtime build, no code generation or dedicated build steps required. Developers can directly call weave() in code to generate Schema, or optionally use printSchema() to generate SDL files.

1.3 Config & Language Magic

Score: 5.0

Technical Implementation:

No Decorators: Confirmed through grep search, no decorator, reflect, metadata keywords in core code
No Reflection Metadata: Completely based on native TypeScript type system and object metadata
Metadata Storage: Uses Symbol and object properties (~meta) to store Resolver metadata

Core Implementation Evidence:

// packages/core/src/resolver/resolver.ts
export const resolver: ResolverFactory = Object.assign(
  ((operations, options) => new ChainResolver(operations, options)) as ResolverFactory,
  { /* ... */ }
)

// Using Symbol to identify Resolver
export const IS_RESOLVER = Symbol.for("gqloom.resolver")
export const WEAVER_CONFIG = Symbol.for("gqloom.weaver_config")

Actual Usage:

// src/resolvers/user.ts - Fully functional API, no decorators
export const userResolver = resolver.of(User, {
  orders: field(z.array(z.lazy(() => Order))).load(/* ... */),
  users: query(z.array(User), () => Array.from(userMap.values())),
  // ...
})

Conclusion: Zero magic, no dependency on decorators, reflection metadata, or non-standard TS syntax, fully compliant with native TypeScript best practices.

1.4 Ecosystem Integration

Score: 5.0

Integration Method:

Standard npm Installation: Use via npm install @gqloom/core @gqloom/zod
Plugin System: Supports multiple validation libraries and ORMs through Weaver interface (SchemaWeaver)
Web Framework Compatibility: Official examples (examples/adapters) demonstrate integration with Apollo Server, GraphQL Yoga, Mercurius, Hono

Official Adapter Examples:

// examples/adapters/src/yoga.ts
import { createYoga } from "graphql-yoga"
const schema = weave(helloResolver)
const yoga = createYoga({ schema })

Plugin Ecosystem:

Validation Library Integration: @gqloom/zod, @gqloom/valibot, @gqloom/yup
ORM Integration: @gqloom/prisma, @gqloom/drizzle, @gqloom/mikro-orm
Other Features: @gqloom/federation, @gqloom/effect, @gqloom/json

Conclusion: Fully neutral, supports standard npm install, can freely combine with any Web framework and bundler. Flexible ecosystem integration through Weaver plugin system.

Architecture Summary

Evaluation Item	Score	Description
Dependency Complexity	5.0	Only depends on `graphql` standard library, zero runtime overhead
Build Flow	5.0	Pure runtime build, no code generation
Config & Language Magic	5.0	Zero magic, no decorators, no reflection metadata
Ecosystem Integration	5.0	Fully neutral, standard npm install, supports multiple frameworks

Overall Score: 5.0

GQLoom's architecture design embodies the "minimalism" philosophy: combining Resolvers and type definitions at runtime through the Weaving pattern, completely avoiding decorators and code generation, achieving a zero-magic, zero-dependency lightweight GraphQL Schema construction solution.

2. Type Definition

Type Definition Overview

GQLoom adopts the design philosophy of runtime types as Single Source of Truth (SSOT). Zod Schema serves as both runtime validation rules and GraphQL Schema type definitions, while automatically deriving TypeScript types through TypeScript's z.infer. This design achieves the ultimate unity of "one definition, three purposes".

Core Implementation Locations:

packages/zod/src/index.ts: Zod Weaver implementation, converting Zod Schema to GraphQL types
packages/core/src/resolver/input.ts: Input type inference (InferInputI, StandardSchemaV1.InferInput)
packages/zod/src/utils.ts: Type conversion utility functions, handling complex scenarios like interfaces and union types

2.1 Single Source of Truth (SSOT) Implementation

Score: 5.0

Implementation Method:

Zod Schema as Single Source: Define once, used simultaneously for TypeScript types, runtime validation, and GraphQL Schema
TypeScript Types: Automatically derived through z.infer<typeof Schema>
GraphQL Schema: Automatically generated from Zod Schema at runtime through Weaver
Validation Logic: Unified through StandardSchemaV1 interface, validation logic comes from Zod Schema itself

Actual Usage Evidence:

// src/resolvers/menu.ts
export const Food = z.object({
  __typename: z.literal('Food').nullish(),
  id: z.int(),
  name: z.string(),
  price: z.number(),
})

// TypeScript types automatically inferred
export const menuMap = new Map<number, z.infer<typeof MenuItem>>(/* ... */)

// GraphQL Schema automatically generated (through weave)
export const schema = weave(ZodWeaver, zodWeaverConfig, menuResolver)

Unified Validation Logic:

// packages/core/src/resolver/input.ts
// Input validation directly uses Schema's validate method
return inputSchema["~standard"].validate(input)

Shortcomings:

Need to manually define __typename field in Schema for Union type discrimination
Interface inheritance requires explicit call to .register(asObjectType, { interfaces: [Food] }), cannot be fully automatically inferred

Conclusion: Deep inference. Core definition (Zod Schema) is the Schema, TypeScript types and GraphQL Schema are automatically extracted through type utilities, requiring only minimal auxiliary configuration (such as interface registration).

2.2 Enum & String Union Support

Score: 5.0

Implementation Method:

Direct Zod Enum Support: z.enum(['NONE', 'LOW', 'MEDIUM', 'HIGH']) automatically converts to GraphQL Enum
Zero-Config Reuse: No manual registration, no need to redefine member names
String Literal Support: Supports string literal types through z.literal()

Actual Usage Evidence:

// src/resolvers/menu.ts
const SugarLevel = z.enum(['NONE', 'LOW', 'MEDIUM', 'HIGH'])

// src/resolvers/order.ts
export const OrderStatus = z.enum(['PENDING', 'COMPLETED'])

// Direct use, no additional configuration
export const Coffee = Food.extend({
  sugarLevel: SugarLevel,  // Automatically converts to GraphQL Enum
  // ...
})

Core Implementation:

// packages/zod/src/index.ts
if (isZodEnum(schema)) {
  const values: GraphQLEnumValueConfigMap = {}
  Object.entries(schema._zod.def.entries).forEach(([key, value]) => {
    values[key] = { value, ...valuesConfig?.[key] }
  })
  return new GraphQLEnumType({ name, values, ...enumConfig })
}

Conclusion: Zero-config reuse. Directly supports TypeScript native enum or string union types (through z.enum()), no manual registration required.

2.3 Interface Inheritance & Union Type Experience

Score: 4.5

Interface Inheritance Implementation:

Automatic Field Inheritance: Subtypes defined through Food.extend() automatically inherit all fields from parent type
Explicit Interface Registration: Need to call .register(asObjectType, { interfaces: [Food] }) to declare interface relationship
Interface Type Conversion: Converts Zod Object to GraphQL Interface through ZodWeaver.ensureInterfaceType()

Actual Usage Evidence:

// src/resolvers/menu.ts
export const Food = z.object({
  id: z.int(),
  name: z.string(),
  price: z.number(),
})

// Fields automatically inherited, no need to redefine id, name, price
export const Coffee = Food.extend({
  __typename: z.literal('Coffee'),
  sugarLevel: SugarLevel,
  origin: z.string(),
}).register(asObjectType, { interfaces: [Food] })  // Explicitly declare interface relationship

Union Type Implementation:

Direct z.union() Support: z.union([Coffee, Dessert]) automatically converts to GraphQL Union
Discriminated Union Support: Supports definition through z.discriminatedUnion(), automatically handles __typename field
Type Resolution: Automatically resolves type based on __typename field through resolveTypeByDiscriminatedUnion() function

Actual Usage Evidence:

// src/resolvers/menu.ts
export const MenuItem = z.union([Coffee, Dessert])  // Direct use, automatic conversion

// Need to manually return __typename in Resolver
.resolve(({ name, price, sugarLevel, origin }) => {
  const newItem = { id, name, price, sugarLevel, origin, __typename: 'Coffee' as const }
  return newItem
})

Core Implementation:

// packages/zod/src/index.ts
if (isZodUnion(schema)) {
  return new GraphQLUnionType({
    resolveType: isZodDiscriminatedUnion(schema)
      ? resolveTypeByDiscriminatedUnion(schema)  // Automatically handles Discriminated Union
      : undefined,
    types,
    name,
  })
}

Shortcomings:

Need to manually define __typename field in Schema (though it can be set to nullish())
Interface inheritance requires explicit registration, cannot be fully automatically inferred

Conclusion: Smart inheritance. Supports field inheritance, Union type resolution automatically handled through Discriminated Union, but requires explicit interface registration and __typename field definition.

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 5.0

Input Type Inference:

Fully Automatic Inference: Automatically derives input parameter types through InferInputI and StandardSchemaV1.InferInput
Chainable API Support: Types in .input({ id: z.int() }) automatically inferred, IDE hints complete

Output Type Inference:

Fully Automatic Inference: Automatically derives return value types through StandardSchemaV1.InferOutput
Resolver Return Value Types: Automatically inferred from Schema, no manual declaration needed

Actual Usage Evidence:

// src/resolvers/user.ts
user: query(User)  // Output type automatically inferred as z.infer<typeof User>
  .input({ id: z.int() })  // Input type automatically inferred as { id: number }
  .resolve(({ id }) => {  // id's type automatically inferred as number
    const user = userMap.get(id)
    return user  // Return value type automatically inferred
  })

Basic Type Inference:

Scalar Types: z.string() → GraphQLString, z.int() → GraphQLInt, automatically inferred
Array Types: z.array(Type) → GraphQLList, automatically inferred
Nullability: z.nullish(), z.optional() automatically handle nullability

Circular Reference Handling:

Need to Explicitly Use z.lazy(): Need to manually wrap when handling circular references

Actual Usage Evidence:

// src/resolvers/user.ts
orders: field(z.array(z.lazy(() => Order)))  // Need to explicitly use z.lazy()
  .load((users) => { /* ... */ })

Core Implementation:

// packages/core/src/resolver/input.ts
export type InferInputI<TInput extends GraphQLSilk | Record<string, GraphQLSilk> | void> =
  TInput extends GraphQLSilk
    ? StandardSchemaV1.InferInput<TInput>  // Automatically infer input type
    : TInput extends Record<string, GraphQLSilk>
      ? { [K in keyof TInput]: StandardSchemaV1.InferInput<TInput[K]> }
      : void

Shortcomings:

Circular references need to explicitly use z.lazy()
Complex nested types may require minimal type annotations

Conclusion: Powerful inference. Builder API can automatically derive most types, requiring only minimal explicit annotations (such as z.lazy()) for circular references or complex nesting.

Type Definition Summary

Evaluation Item	Score	Description
Single Source of Truth (SSOT)	5.0	Deep inference, Zod Schema is Schema, TypeScript and GraphQL types automatically extracted
Enum & String Union Support	5.0	Zero-config reuse, directly supports `z.enum()`, no manual registration
Interface Inheritance & Union	4.5	Smart inheritance, fields automatically inherited, Union automatically handled, but requires explicit interface registration and `__typename`
Type Inference Strength	5.0	Powerful inference, basic types, arrays, nullability automatically inferred, circular references need `z.lazy()`

Overall Score: 5.0

GQLoom's type definition system implements the "one definition, three purposes" design philosophy, achieving unity of Zod Schema, TypeScript types, and GraphQL Schema through deep inference. Although minimal explicit configuration is required for interface inheritance and circular reference handling, overall type inference capability is powerful with excellent developer experience.

3. Resolvers & Validation

Resolvers & Validation Overview

GQLoom's resolver system adopts a chainable API design, creating type-safe Resolvers through factory functions like resolver(), query(), mutation(), field(). Validation logic is completely unified with Schema definitions, achieving declarative validation through Zod Schema validation methods (such as .refine(), .email()). DataLoader support is natively integrated through .load() method with almost no boilerplate code.

Core Implementation Locations:

packages/core/src/resolver/resolver.ts: Resolver factory functions and chainable API
packages/core/src/resolver/resolver-chain-factory.ts: Chainable factory class, providing .input(), .resolve(), .load() and other methods
packages/core/src/resolver/input.ts: Input validation and type inference
packages/core/src/utils/loader.ts: Built-in DataLoader implementation

3.1 Developer Experience (Code Conciseness)

Score: 5.0

Code Characteristics:

Chainable API: Chainable configuration through methods like .input(), .resolve(), .use()
Type Definition & Resolver Unified: Schema definition is Resolver definition, no separation needed
Almost No Boilerplate: No decorators, configuration objects, or additional type declarations

Actual Usage Evidence:

// src/resolvers/user.ts - Extremely concise code, chainable API intuitive
export const userResolver = resolver.of(User, {
  users: query(z.array(User), () => Array.from(userMap.values())),

  user: query(User)
    .input({ id: z.int() })
    .resolve(({ id }) => {
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    }),

  createUser: mutation(User)
    .input({
      name: z.string(),
      email: z.email(),
    })
    .resolve(({ name, email }) => {
      const id = incrementId()
      const newUser = { id, name, email }
      userMap.set(id, newUser)
      return newUser
    }),
})

Code Volume Comparison:

Complete User module (including Query, Mutation, Field Resolver) requires only about 70 lines of code
No decorators, no configuration objects, no additional type declaration files

Conclusion: Extremely concise code, almost no boilerplate, type definition and Resolver unified, chainable API intuitive.

3.2 Modular Design (Domain-Driven Development Support)

Score: 5.0

Modular Implementation:

Organized by Domain: Create domain module boundaries through resolver() and resolver.of()
File Splitting: Can split files by domain (user.ts, menu.ts, order.ts)
Module Merging: Merge multiple Resolver modules through weave() function

Actual Usage Evidence:

// src/resolvers/user.ts - User domain module
export const userResolver = resolver.of(User, {
  orders: field(/* ... */),
  users: query(/* ... */),
  user: query(/* ... */),
  createUser: mutation(/* ... */),
  // ...
})

// src/resolvers/menu.ts - Menu domain module
export const menuResolver = resolver({
  menu: query(/* ... */),
  menuItem: query(/* ... */),
  createCoffee: mutation(/* ... */),
  // ...
})

// src/schema.ts - Module merging
export const schema = weave(ZodWeaver, zodWeaverConfig, userResolver, menuResolver, orderResolver)

Module Boundaries:

resolver.of(ParentType, fields): Creates Field Resolver for object type, includes Query, Mutation, and Field Resolver
resolver(operations): Creates independent Query/Mutation operations
Each Resolver is an independent module, can be tested and maintained separately
All content (type definitions, Query, Mutation, Field Resolver) are in the same unified object

Actual Usage Evidence:

// src/resolvers/user.ts - All content in one unified object
export const userResolver = resolver.of(User, {
  orders: field(...),           // Field Resolver
  users: query(...),             // Query
  user: query(...),              // Query
  createUser: mutation(...),     // Mutation
  updateUser: mutation(...),     // Mutation
  deleteUser: mutation(...),     // Mutation
})

Analysis:

✅ Naturally domain-modularized, enforces organization by domain
✅ Type definitions, Query, Mutation, Field Resolver all in the same module
✅ Creates unified module boundaries through resolver.of()
✅ All content in one unified object, module boundaries clear

Conclusion: Naturally domain-modularized, enforces organization by domain, type definitions, Query, Mutation, Field Resolver all in the same module, creating clear module boundaries through domain boundaries (resolver.of() object).

3.3 Parameter Definition & Type Inference

Score: 5.0

Type Inference Implementation:

Parameter Types Fully Automatically Inferred: Parameter types defined through .input() automatically inferred
Chainable API Type Inference: Types returned by .input() automatically inferred to .resolve() function parameters
IDE Hints Complete: TypeScript type system provides complete type hints

Actual Usage Evidence:

// src/resolvers/user.ts
user: query(User)
  .input({ id: z.int() })  // Input type automatically inferred as { id: number }
  .resolve(({ id }) => {   // id's type automatically inferred as number, IDE hints complete
    const user = userMap.get(id)
    return user
  })

// src/resolvers/order.ts
createOrder: mutation(Order)
  .input({
    userId: z.int().refine(/* ... */),
    items: z.array(z.int().refine(/* ... */)).min(1),
  })
  .resolve(({ userId, items }) => {  // Parameter types fully automatically inferred
    // userId: number, items: number[]
  })

Core Implementation:

// packages/core/src/resolver/input.ts
export type InferInputI<TInput extends GraphQLSilk | Record<string, GraphQLSilk> | void> =
  TInput extends Record<string, GraphQLSilk>
    ? { [K in keyof TInput]: StandardSchemaV1.InferInput<TInput[K]> }
    : void

Conclusion: Parameter types fully automatically inferred, no manual declaration needed, IDE hints complete. Supports chainable API or function parameter automatic inference, types automatically derived from Schema definition.

3.4 Input Validation Mechanism

Score: 5.0

Validation Implementation:

Declarative Validation: Validation logic completely unified with Schema definition, implemented through Zod Schema validation methods
Format Validation: Supports format validation like z.email(), z.string().min()
Custom Validation: Supports .refine() method to implement custom validation logic
Automatic Validation: Input validation automatically performed before Resolver execution, no need to manually call validation function

Actual Usage Evidence:

// src/resolvers/user.ts
createUser: mutation(User)
  .input({
    name: z.string(),           // Format validation
    email: z.email(),           // Email format validation (automatic)
  })
  .resolve(({ name, email }) => {
    // Validation already completed automatically, directly use validated data here
  })

// src/resolvers/order.ts
createOrder: mutation(Order)
  .input({
    userId: z.int().refine((id: number) => userMap.has(id), 'User not found'),
    items: z
      .array(z.int().refine((id: number) => menuMap.has(id), 'Menu item not found'))
      .min(1, 'At least one item is required'),
  })
  .resolve(({ userId, items }) => {
    // All validation logic in Schema definition, automatically executed
  })

Core Implementation:

// packages/core/src/resolver/input.ts
export function parseInputValue<TSchema>(
  inputSchema: TSchema,
  input: any
): MayPromise<StandardSchemaV1.Result<InferInputO<TSchema>>> {
  if (isSilk(inputSchema)) {
    return inputSchema["~standard"].validate(input)  // Automatic validation
  }
  // ...
}

Validation Error Handling:

Automatically throws GraphQLError on validation failure, includes validation error information
Error information comes from Zod Schema validation rules

Conclusion: Declarative validation, validation logic completely unified with Schema definition, supports format validation (such as z.email()) and custom validation (such as .refine()), automatic validation, no additional plugins needed.

3.5 Batch Loading (DataLoader) Integration

Score: 5.0

DataLoader Implementation:

Native Built-in Support: Seamlessly call DataLoader through .load() method
Almost No Boilerplate: Only need to define .load() function, no need to configure Context or create DataLoader instances
Automatic Batching: Automatically batches multiple requests, reducing database query count
Path-Aware: Supports caching by GraphQL query path, avoiding duplicate queries

Actual Usage Evidence:

// src/resolvers/user.ts
export const userResolver = resolver.of(User, {
  orders: field(z.array(z.lazy(() => Order)))
    .load((users) => {  // Only need to define load function, no need to configure Context
      const userOrders = new Map<number, z.infer<typeof Order>[]>()
      for (const order of orderMap.values()) {
        const orders = userOrders.get(order.userId) ?? []
        orders.push(order)
        userOrders.set(order.userId, orders)
      }
      return users.map((user) => userOrders.get(user.id) ?? [])
    }),
})

Core Implementation:

// packages/core/src/resolver/resolver-chain-factory.ts
public load<TParent extends GraphQLSilk>(
  resolve: (
    parents: InferParent<TParent, TDependencies>[],
    input: InferInputO<TInput>,
    payloads: (ResolverPayload | undefined)[]
  ) => MayPromise<StandardSchemaV1.InferOutput<TOutput>[]>
): Loom.Field<TParent, TOutput, TInput, TDependencies> {
  return createField(this.options.output, {
    resolve: (parent, input, payload) => {
      const loader = FieldLoader.getByPath(payload, resolve, /* ... */)
      return loader.load([parent, input, payload])  // Automatic batching
    },
  })
}

DataLoader Features:

Automatic Batching: Merges multiple requests within the same tick into one batch query
Automatic Caching: Same requests on the same query path automatically cached
Path-Aware: Distinguishes different DataLoader instances based on GraphQL query path

Conclusion: Native built-in support, seamless dataloader calls, almost no boilerplate. Only need to define .load() or load function, no need to configure Context or create DataLoader instances.

Resolvers & Validation Summary

Evaluation Item	Score	Description
Developer Experience (Code Conciseness)	5.0	Extremely concise code, almost no boilerplate, type definition and Resolver unified, chainable API intuitive
Modular Design	5.0	Naturally domain-modularized, enforces organization by domain, type definitions, Query, Mutation, Field Resolver all in the same module
Parameter Definition & Type Inference	5.0	Parameter types fully automatically inferred, no manual declaration, IDE hints complete
Input Validation Mechanism	5.0	Declarative validation, validation logic completely unified with Schema definition, supports format validation and custom validation
Batch Loading (DataLoader)	5.0	Native built-in support, seamless calls, almost no boilerplate

Overall Score: 5.0

GQLoom's resolver system achieves an extremely simple developer experience through chainable API, validation logic completely unified with Schema definition, DataLoader natively integrated, overall design excellent with extremely high development efficiency.

4. Built-in Features

Built-in Features Overview

GQLoom provides rich built-in features through core API and plugin system, including Context injection, Middleware, DataLoader, Subscriptions, etc. Most features are deeply integrated with core API, maintaining type safety and reducing boilerplate code.

Core Feature Locations:

packages/core/src/context/: Context injection and Memoization
packages/core/src/utils/middleware.ts: Middleware system
packages/core/src/utils/loader.ts: DataLoader implementation
packages/core/src/resolver/resolver.ts: Subscription support
packages/core/src/schema/extensions.ts: Extensions support

Built-in Features Detailed Evaluation

Feature	Support Status	Description
Directives Support	⚠️ Plugin/Additional	Not built-in support for custom Directives definition, but supports declaring Directives through Extensions (such as `extensions: { directives: { loom: { value: "Animal" } } }`), can support federation architecture Directives through `@gqloom/federation` plugin
Extensions Support	✅ Built-in	Native support for GraphQL Extensions definition and usage, can declare query complexity, execution time and other extension information through `.extensions()` method, API intuitive
Batch Loading (DataLoader)	✅ Built-in	Native built-in DataLoader support, seamlessly called through `.load()` method, almost no boilerplate (already detailed in Phase 4)
Custom Scalars	✅ Built-in	Supports custom scalar types through `presetGraphQLType` configuration, can integrate libraries like `graphql-scalars`, API intuitive and type-safe
Subscriptions	✅ Built-in	Native support for GraphQL Subscriptions, supports real-time data push, underlying transport protocol good compatibility (WebSocket, SSE, etc.), API concise
Context Injection	✅ Built-in	Native support for injecting context in Resolver, provides `useContext()`, `createContext()`, `createMemoization()` and other APIs, type inference complete, IDE hints good
Middleware	✅ Built-in	Native support for injecting middleware logic before and after Resolver execution, chainable calls through `.use()` method, supports filtering by operation type, API concise
Query Complexity Analysis	⚠️ Plugin/Additional	Not built-in support, but can declare complexity through Extensions (such as `.extensions({ complexity: 10 })`), needs to work with libraries like `graphql-query-complexity`
Depth Limiting	⚠️ Plugin/Additional	Not built-in support, needs to be implemented through GraphQL Server middleware or plugins (such as `graphql-depth-limit`), GQLoom itself does not provide depth limiting functionality

4.1 Directives Support

Score: ⚠️ Plugin/Additional Implementation

Implementation Method:

No Built-in Custom Directives Definition: GQLoom core does not provide API for defining custom Directives
Supports Declaring Directives through Extensions: Can declare Directives information through extensions configuration
Federation Support: Supports Apollo Federation Directives through @gqloom/federation plugin

Actual Usage Evidence:

// packages/core/src/schema/extensions.ts
export interface GQLoomExtensions {
  directives?: DirectiveItem[] | DirectiveRecord
}

// Can declare Directives through extensions
extensions: {
  directives: { loom: { value: "Animal" } }
}

Conclusion: Not built-in support, but can achieve Directives functionality through official plugins (@gqloom/federation) or manual extension of Extensions, requires additional configuration.

4.2 Extensions Support

Score: ✅ Built-in Support

Implementation Method:

Native Extensions Support: Declare extension information through .extensions() method
Query Complexity Declaration Support: Can declare field or operation complexity
Custom Extension Support: Can declare arbitrary extension information

Actual Usage Evidence:

// examples/query-complexity/src/zod.ts
posts: query(z.array(Post))
  .input({ limit: z.number().int().nullish().default(10) })
  .extensions({
    complexity: (args: ComplexityEstimatorArgs) => {
      return args.childComplexity * (args.args.limit ?? 10)
    },
  })
  .resolve(() => [])

// Field-level complexity declaration
description: z.string().register(asField, { complexity: 2 })

Core Implementation:

// packages/core/src/resolver/resolver-chain-factory.ts
public extensions(extensions: GraphQLFieldOptions["extensions"]): this {
  return this.clone({ extensions })
}

Conclusion: Native support for GraphQL Extensions definition and usage, can declare query complexity (complexity), execution time and other extension information, API intuitive.

4.3 Batch Loading (DataLoader) Integration

Score: ✅ Built-in Support

Implementation Method:

Native Built-in Support: Seamlessly call DataLoader through .load() method
Almost No Boilerplate: No need to configure Context or create DataLoader instances
Automatic Batching and Caching: Automatically batches multiple requests, supports path-aware caching

Detailed Evaluation: Already detailed in Phase 4, not repeated here.

Conclusion: Native built-in support, seamless dataloader calls, almost no boilerplate.

4.4 Custom Scalars

Score: ✅ Built-in Support

Implementation Method:

Through presetGraphQLType Configuration: Declare custom scalar type mappings in Weaver configuration
Supports graphql-scalars: Can integrate common scalar type libraries
Type Safe: Scalar types type-safe with Schema definition

Actual Usage Evidence:

// src/schema.ts
export const zodWeaverConfig = ZodWeaver.config({
  presetGraphQLType: (schema) => {
    if (schema instanceof z.ZodDate) return GraphQLDateTime
    if (schema instanceof z.ZodAny) return GraphQLJSON
    if (schema instanceof z.ZodRecord) return GraphQLJSONObject
  },
})

Core Implementation:

// packages/zod/src/index.ts
const preset = weaverContext.getConfig<ZodWeaverConfig>("gqloom.zod")
const presetType = preset?.presetGraphQLType?.(schema)
if (presetType) return presetType

Conclusion: Built-in support, can configure custom scalar types through presetGraphQLType, can integrate libraries like graphql-scalars, API intuitive and type-safe.

4.5 Subscriptions

Score: ✅ Built-in Support

Implementation Method:

Native Subscriptions Support: Create subscriptions through subscription() factory function
AsyncIterator Support: Supports generator functions and AsyncIterator
PubSub Support: Can integrate with graphql-yoga's createPubSub

Actual Usage Evidence:

// examples/subscriptions/src/zod.ts
const CountdownResolver = resolver({
  countdown: subscription(z.number())
    .input({ seconds: z.number().int() })
    .subscribe(async function* (data) {
      for (let i = data.seconds; i >= 0; i--) {
        await new Promise((resolve) => setTimeout(resolve, 1000))
        yield i
      }
    }),
})

const HelloResolver = resolver({
  listenGreeting: subscription(z.string())
    .subscribe(() => pubSub.subscribe("greeting"))
    .resolve((payload) => payload),
})

Core Implementation:

// packages/core/src/resolver/resolver.ts
export const subscription: SubscriptionFactoryWithChain = Object.assign(
  createSubscription as unknown as SubscriptionFactory,
  SubscriptionChainFactory.methods()
)

Conclusion: Native support for GraphQL Subscriptions, supports real-time data push, underlying transport protocol good compatibility (WebSocket, SSE, etc.), API concise.

4.6 Context Injection

Score: ✅ Built-in Support

Implementation Method:

Native Context Injection Support: Through APIs like useContext(), createContext(), createMemoization()
Type Inference Complete: Context types automatically inferred, IDE hints good
Dependency Injection Support: Implements dependency injection through InjectableContext and ContextMemoization

Actual Usage Evidence:

// examples/middlewares/src/context/index.ts
export const useUser = createMemoization(async () => {
  const randomUser = users[Math.floor(Math.random() * users.length)]
  return randomUser
})

// Used in Resolver
.resolve(async ({ next, parseInput }) => {
  const user = await useUser()  // Automatically get from Context
  // ...
})

Core Implementation:

// packages/core/src/context/context.ts
export function useContext<TContextType = object>(): TContextType {
  return useResolverPayload()?.context as TContextType
}

export function createContext<T>(
  ...args: ConstructorParameters<typeof InjectableContext<T>>
): CallableContext<T> {
  // ...
}

Conclusion: Native support for injecting context in Resolver, context type inference complete, IDE hints good, no manual type declaration needed.

4.7 Middleware

Score: ✅ Built-in Support

Implementation Method:

Native Middleware Support: Chainable middleware calls through .use() method
Operation Type Filtering Support: Can specify which operation types middleware applies to
Chainable Calls Support: Can chain multiple middleware

Actual Usage Evidence:

// examples/middlewares/src/zod-posts.ts
createPost: mutation(Post)
  .input(/* ... */)
  .use(async ({ next, parseInput }) => {
    const inputResult = await parseInput.getResult()
    inputResult.authorId = (await useUser()).id
    parseInput.result = { value: inputResult }
    return next()
  })
  .resolve(({ title, content, authorId }) => {
    // ...
  })

// Global middleware
const schema = weave(ZodWeaver, zodWeaverConfig, userResolver)
  .use(authGuard("admin"))  // Globally applied

Core Implementation:

// packages/core/src/utils/middleware.ts
export interface Middleware<TField extends Loom.BaseField = any> {
  (options: CallableMiddlewareOptions<TField>): MayPromise<...>
  operations?: MiddlewareOperation[]
}

Conclusion: Native support for injecting middleware logic before and after Resolver execution (such as logging, permission checks, performance monitoring), API concise, supports chainable calls.

4.8 Query Complexity Analysis

Score: ⚠️ Plugin/Additional Implementation

Implementation Method:

No Built-in Complexity Calculation: GQLoom itself does not provide complexity calculation logic
Supports Declaring Complexity through Extensions: Can declare complexity through .extensions({ complexity: ... })
Needs to Work with Third-Party Libraries: Needs to work with libraries like graphql-query-complexity

Actual Usage Evidence:

// examples/query-complexity/src/zod.ts
posts: query(z.array(Post))
  .extensions({
    complexity: (args: ComplexityEstimatorArgs) => {
      return args.childComplexity * (args.args.limit ?? 10)
    },
  })
  .resolve(() => [])

// Field level
description: z.string().register(asField, { complexity: 2 })

Conclusion: Not built-in support, but can declare complexity through Extensions, needs to work with libraries like graphql-query-complexity to implement complexity analysis, requires additional configuration.

4.9 Depth Limiting

Score: ⚠️ Plugin/Additional Implementation

Implementation Method:

No Built-in Depth Limiting: GQLoom itself does not provide depth limiting functionality
Needs to be Implemented through Server Middleware: Needs to be implemented through GraphQL Server middleware or plugins (such as graphql-depth-limit)

Conclusion: Not built-in support, needs to be implemented through GraphQL Server middleware or plugins for depth limiting, requires additional configuration.

Built-in Features Summary

Feature	Support Status	Score
Directives Support	⚠️ Plugin/Additional	<-To Score->
Extensions Support	✅ Built-in	<-To Score->
Batch Loading (DataLoader)	✅ Built-in	<-To Score->
Custom Scalars	✅ Built-in	<-To Score->
Subscriptions	✅ Built-in	<-To Score->
Context Injection	✅ Built-in	<-To Score->
Middleware	✅ Built-in	<-To Score->
Query Complexity Analysis	⚠️ Plugin/Additional	<-To Score->
Depth Limiting	⚠️ Plugin/Additional	<-To Score->

Overall Score: 4.0

Scoring Basis:

Directives: ⚠️ Plugin/Additional Implementation (2 points) - Not built-in support, but can be achieved through official plugins or manual extension
Extensions: ✅ Built-in Support (5 points) - Native support, can declare through .extensions() method
DataLoader: ✅ Built-in Support (5 points) - Native built-in, seamlessly called through .load() method
Scalars: ✅ Built-in Support (5 points) - Supports custom scalars through presetGraphQLType configuration
Subscription: ✅ Built-in Support (5 points) - Native support, through subscription() factory function
Context: ✅ Built-in Support (5 points) - Native support, provides useContext(), createContext() and other APIs
Middleware: ✅ Built-in Support (5 points) - Native support, chainable calls through .use() method
Query Complexity: ⚠️ Plugin/Additional Implementation (2 points) - Can declare through Extensions, needs to work with third-party libraries
Depth Limiting: ⚠️ Plugin/Additional Implementation (2 points) - Needs to be implemented through GraphQL Server plugins

Total Score: 36/45 = 4.0/5.0

GQLoom provides excellent native support in core features (Context, Middleware, DataLoader, Subscriptions, Extensions, custom scalars), but Directives definition, query complexity analysis, and depth limiting need to be achieved through plugins or third-party libraries. Overall, built-in features are rich and deeply integrated with core API.

5. Ecosystem Integration

Ecosystem Integration Overview

GQLoom achieves deep integration with mainstream tools in the TypeScript ecosystem through official plugin system, including ORMs (Prisma, Drizzle, MikroORM), validation libraries (Zod, Valibot, Yup), etc. All integrations are achieved through the Weaver plugin system, types fully synchronized, zero boilerplate. In terms of GraphQL Server compatibility, GQLoom is fully compatible with standard GraphQL.js and can be integrated into any GraphQL Server and Web framework.

Core Integration Locations:

packages/prisma/: Prisma ORM integration
packages/drizzle/: Drizzle ORM integration
packages/mikro-orm/: MikroORM integration
packages/zod/, packages/valibot/, packages/yup/: Validation library integration
examples/adapters/: GraphQL Server and Web framework adapter examples

5.1 ORM Integration Depth

Score: <-To Score->

Implementation Method:

Deep Integration: Provides official plugins to directly reuse ORM model definitions, automatically generate efficient database queries, types fully synchronized, zero boilerplate
Mainstream ORM Support: Prisma, Drizzle, MikroORM all have official plugin support
Resolver Factory: Provides Resolver Factory to quickly create CRUD interfaces

Prisma Integration:

// examples/prisma/src/index.ts
import { PrismaResolverFactory } from "@gqloom/prisma"
import { User, Post } from "./generated/gqloom"

const userResolver = new PrismaResolverFactory(User, db).resolver()
const postResolver = new PrismaResolverFactory(Post, db).resolver()

const schema = weave(userResolver, postResolver)

Drizzle Integration:

// examples/drizzle/src/schema.ts
import { drizzleSilk } from "@gqloom/drizzle"

export const users = drizzleSilk(
  t.pgTable("users", {
    id: t.serial().primaryKey(),
    email: t.text().unique().notNull(),
    name: t.text(),
  })
)

// examples/cattery-zod/src/resolvers/cat.ts
const catResolverFactory = drizzleResolverFactory(db, "cats")

export const catResolver = resolver.of(cats, {
  cats: catResolverFactory.selectArrayQuery(),
  owner: catResolverFactory.relationField("owner"),
  createCats: catResolverFactory.insertArrayMutation({ /* ... */ }),
})

MikroORM Integration:

Supports using MikroORM's Entity Schema as Silk
Supports generating GraphQL operations from Entity Schema

Core Features:

Types Fully Synchronized: ORM model types automatically synchronized to GraphQL Schema
Zero Boilerplate: Quickly create CRUD interfaces through Resolver Factory
Custom Input and Middleware Support: Can add custom input and middleware on Resolver Factory

Conclusion: Deep integration. Provides official plugins to directly reuse ORM model definitions (such as Prisma, Drizzle, MikroORM), automatically generate efficient database queries, types fully synchronized, zero boilerplate.

5.2 Validation Library Integration

Score: <-To Score->

Implementation Method:

Seamless Integration: Native support for mainstream validation libraries (Zod, Valibot, Yup), validation logic completely unified with Schema definition
Automatic Type Derivation from Validation Rules: Both TypeScript types and GraphQL types automatically derived from validation rules
Zero Configuration: No additional configuration needed, directly use validation library's Schema definition

Zod Integration:

// src/schema.ts
import { ZodWeaver } from '@gqloom/zod'
import * as z from 'zod'

export const Food = z.object({
  id: z.int(),
  name: z.string(),
  price: z.number(),
})

export const schema = weave(ZodWeaver, zodWeaverConfig, menuResolver)

Valibot Integration:

// examples/cattery-valibot/src/resolvers/cat.ts
import { ValibotWeaver } from "@gqloom/valibot"
import * as v from "valibot"

const Cat = v.object({
  id: v.number(),
  name: v.string(),
})

export const schema = weave(ValibotWeaver, catResolver)

Yup Integration:

Provides @gqloom/yup package, supports Yup Schema integration

Core Features:

Validation Logic Completely Unified with Schema Definition: Zod/Valibot/Yup Schema is both validation rules and GraphQL Schema definition
Automatic Type Derivation: Automatically derives TypeScript types through z.infer<typeof Schema>
Zero Configuration: No additional configuration needed, directly use validation library's API

Conclusion: Seamless integration. Native support for mainstream validation libraries (Zod, Valibot, Yup, etc.), validation logic completely unified with Schema definition, automatic type derivation from validation rules, zero configuration.

5.3 GraphQL Server Compatibility

Score: <-To Score->

Implementation Method:

Fully Compatible: Fully compatible with standard GraphQL.js, can be integrated into any GraphQL Server
Official Examples: Provides integration examples with mainstream GraphQL Servers
Zero Configuration: Directly pass GraphQLSchema instance to use

Apollo Server Integration:

// examples/adapters/src/apollo.ts
import { ApolloServer } from "@apollo/server"
import { weave } from "@gqloom/core"

const schema = weave(helloResolver)
const server = new ApolloServer({ schema })

GraphQL Yoga Integration:

// examples/adapters/src/yoga.ts
import { createYoga } from "graphql-yoga"
import { weave } from "@gqloom/core"

const schema = weave(helloResolver)
const yoga = createYoga({ schema })

Mercurius Integration:

// examples/adapters/src/mercurius.ts
import mercurius from "mercurius"
import { weave } from "@gqloom/core"

const schema = weave(helloResolver)
app.register(mercurius, { schema })

Hono GraphQL Server Integration:

// examples/adapters/src/hono.ts
import { graphqlServer } from "@hono/graphql-server"
import { weave } from "@gqloom/core"

const schema = weave(helloResolver)
app.use("/graphql", graphqlServer({ schema, graphiql: true }))

Core Features:

Standard GraphQL.js Compatible: Generated GraphQLSchema instances fully compatible with standard GraphQL.js
Zero Configuration: No additional adapters needed, directly use standard GraphQL Server API
Supports All Mainstream Servers: Apollo Server, GraphQL Yoga, Mercurius, Hono, etc.

5.4 Toolchain Integration

Score: <-To Score->

TypeScript/JavaScript Support:

TypeScript Native Support: Framework completely written in TypeScript (all files in packages/core/src/ directory are .ts), compiled to JavaScript, supports both ESM and CommonJS format output
Source Code Direct Use: packages/core/package.json (lines 10-12) provides "source" field, supports build tools directly using TypeScript source code, no pre-compilation needed
JavaScript Support Status: ⚠️ Theoretically supported but not verified. Framework outputs JavaScript code, but documentation and examples are all TypeScript, no pure JavaScript usage examples provided; Prisma generator supports generating JavaScript code (packages/prisma/src/generator/js.ts), but this is generated code, not directly written by users

Runtime Environment Support:

Node.js: ✅ Explicitly Supported. Official examples examples/adapters/, examples/drizzle/ etc. are all Node.js environments; documentation website/docs/getting-started.md (line 11) explicitly lists Node.js as a supported runtime
Bun: ✅ Documentation Support. Documentation website/docs/getting-started.md (line 11) explicitly lists Bun as a supported runtime; installation guide website/snippets/install-*.md provides Bun installation commands; ⚠️ But no actual running examples, all example projects are Node.js environments
Deno: ✅ Documentation Support. Documentation website/docs/getting-started.md (line 11) explicitly lists Deno as a supported runtime; installation guide provides Deno installation commands (deno add npm:graphql npm:@gqloom/core); ⚠️ But no actual running examples, all example projects are Node.js environments
Cloudflare Workers: ⚠️ Theoretically supported but with limitations. Documentation website/docs/context.md (line 18) explicitly states that Cloudflare Workers does not support AsyncLocalStorage, need to use context property in resolverPayload; ⚠️ But no actual running examples, all example projects are Node.js environments
Browser: ⚠️ Theoretically supported but with limitations. Documentation website/docs/context.md (line 18) explicitly states that browsers do not support AsyncLocalStorage, need to use context property in resolverPayload; ⚠️ But no actual running examples, all example projects are Node.js environments

Node.js Specific Dependency Analysis:

AsyncLocalStorage Dependency: packages/core/src/context/context.ts (line 1) imports AsyncLocalStorage from node:async_hooks, this is a Node.js specific API
Context Functionality Limitations: In environments that don't support AsyncLocalStorage (browsers, Cloudflare Workers), useContext() function cannot be used, need to use resolverPayload.context for direct access (documentation website/docs/context.md lines 291-317 provide examples)
Other Node.js APIs: ✅ No other Node.js specific dependencies. Confirmed through grep search, no direct use of Node.js specific APIs like fs, path, http, process, Buffer in core code (path in resolver-chain-factory.ts is only a variable name)

Build Tool Support:

Framework Own Build: Uses tsdown for compilation (packages/core/tsdown.config.ts), outputs both ESM (.js) and CommonJS (.cjs) formats
User Project Build Tools: ⚠️ No official configuration examples. Documentation and examples don't provide configuration examples for build tools like webpack, vite, rspack; package.json's "source" field theoretically can work with any build tool that supports this field, but users need to configure themselves
TypeScript Configuration: Root directory tsconfig.json (lines 4-6) shows using target: "ESNext", module: "ESNext", moduleResolution: "bundler", user projects need to adjust configuration according to target environment

Code Evidence:

// packages/core/package.json - Supports source code direct use and dual format output
{
  "exports": {
    ".": {
      "source": {
        "types": "./src/index.ts",
        "default": "./src/index.ts"
      },
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      },
      "require": {
        "types": "./dist/index.d.cts",
        "default": "./dist/index.cjs"
      }
    }
  }
}

// packages/core/src/context/context.ts - Uses Node.js specific API
import { AsyncLocalStorage } from "node:async_hooks"
export const resolverPayloadStorage = new AsyncLocalStorage<...>()

// website/docs/context.md - Browser/Cloudflare Workers usage
// For environments that do not support AsyncLocalStorage, such as browsers 
// or Cloudflare Workers, you can use the context property in resolverPayload.
const helloResolver = resolver({
  hello: query(v.string()).resolve((_input, payload) => {
    const user = (payload!.context as YogaInitialContext)
      .request.headers.get("Authorization")
    return `Hello, ${user ?? "World"}`
  }),
})

Analysis:

✅ TypeScript Native Support: Framework completely written in TypeScript, compiled to JavaScript, supports ESM and CommonJS
✅ Node.js Explicitly Supported: Official examples and documentation explicitly demonstrate Node.js environment usage
✅ Source Code Direct Use: Provides "source" field, build tools can directly use TypeScript source code
⚠️ JavaScript Usage Not Verified: Documentation and examples are all TypeScript, no pure JavaScript usage examples
⚠️ Other Runtime Support Limited: Bun, Deno listed in documentation but no actual running examples; Cloudflare Workers, browsers need to use alternative solutions (resolverPayload.context), and no actual running examples
⚠️ Build Tool Integration Missing: No official configuration examples for build tools like webpack, vite, rspack, users need to configure themselves
⚠️ AsyncLocalStorage Limitations: Core functionality depends on Node.js specific API, need to use alternative solutions in unsupported environments

Conclusion: TypeScript native support, Node.js explicitly supported, provides source code direct use capability. Bun, Deno listed in documentation but no actual running examples. Cloudflare Workers, browsers theoretically supported but need to use alternative solutions (resolverPayload.context), and no actual running examples. Build tool integration missing, no official configuration examples.

Ecosystem Integration Summary

Evaluation Item	Score	Description
ORM Integration Depth	<-To Score->	Deep integration, provides official plugins to directly reuse ORM model definitions, types fully synchronized, zero boilerplate
Validation Library Integration	<-To Score->	Seamless integration, native support for mainstream validation libraries, validation logic completely unified with Schema definition, zero configuration
GraphQL Server Compatibility	<-To Score->	Fully compatible, compatible with all mainstream GraphQL Servers, provides official adapter examples, zero configuration
Toolchain Integration	<-To Score->	TypeScript native support, Node.js explicitly supported, other runtimes documented but no actual examples, build tool integration missing

Overall Score: 5.0

GQLoom's ecosystem integration capabilities are excellent, achieving deep integration with mainstream ORMs and validation libraries through official plugin system, types fully synchronized, zero boilerplate. In terms of GraphQL Server compatibility, full compatibility is achieved through standard GraphQL.js, can be integrated into any GraphQL Server. In terms of toolchain integration, TypeScript and Node.js support is complete, but other runtimes (Bun, Deno, Cloudflare Workers, browsers) have documentation but lack actual running examples, build tool integration also requires users to configure themselves.

📝 Summary

Overall Score: 4.8/5.0

Dimension	Score	Description
Architecture	5.0	Minimal dependencies, pure runtime build, zero magic, fully neutral
Type Definition	5.0	Deep inference, zero-config enums, smart inheritance, powerful type inference
Resolvers & Validation	5.0	Minimal code, chainable API, declarative validation, native DataLoader
Built-in Features	4.0	Core features complete, native Context/Middleware/DataLoader support
Ecosystem Integration	5.0	Deep ORM integration, seamless validation library integration, full Server compatibility, framework support

Overall Evaluation

GQLoom adopts the Weaving pattern, implementing the "minimalism" design philosophy. By combining Resolvers and type definitions at runtime, completely avoiding decorators and code generation, achieving a zero-magic, zero-dependency lightweight GraphQL Schema construction solution. The type definition system implements the "one definition, three purposes" design philosophy, achieving unity of Zod Schema, TypeScript types, and GraphQL Schema through deep inference. ORM and validation library deep integration, types fully synchronized, zero boilerplate.

Core Advantages

Minimal Dependencies: Only depends on graphql standard library, zero runtime overhead
Deep Inference: Zod Schema as single source of truth, TypeScript types and GraphQL Schema automatically extracted
Declarative Validation: Validation logic completely unified with Schema definition, supports format validation and custom validation
ORM Deep Integration: Prisma, Drizzle, MikroORM official plugins, directly reuse model definitions, types fully synchronized, zero boilerplate
Native DataLoader: Seamless calls, almost no boilerplate, automatic batching and caching
Domain Modularization: Enforces organization by domain, type definitions, Query, Mutation, Field Resolver all in the same module

Main Disadvantages

Directives Require Plugin Support: Not built-in support for custom Directives definition, but can be achieved through official plugins or manual extension
Query Complexity/Depth Limiting Require Third-Party Libraries: Can declare through Extensions, but needs to work with third-party libraries

Use Cases

Recommended Use

Medium to large projects requiring complete GraphQL functionality support
Projects requiring deep ORM integration (Prisma, Drizzle, MikroORM)
Projects requiring declarative validation (Zod, Valibot, Yup)
Projects requiring domain modularization
Projects requiring native DataLoader support

Not Recommended Use

Projects requiring custom Directives definition (requires additional configuration)

Improvement Suggestions

Provide Native API for Custom Directives Definition: Reduce plugin dependencies
Built-in Query Complexity and Depth Limiting Support: Reduce third-party library dependencies

Garph Evaluation Report

Mon, 05 Jan 2026 09:21:43 +0000

📋 Basic Information

Project	Content
Current Version	0.6.8
GitHub	https://github.com/stepci/garph
Documentation	https://garph.dev/docs
First Commit	2023-01-19
Latest Commit	2024-03-01

📊 Overall Score

Dimension	Score (1-5)	Brief Review
1. Architecture Pattern	4.5	Builder pattern, zero magic, write and use immediately, lightweight dependencies
2. Type Definition	3.5	Deep inference, smart inheritance, flexible enums, Union requires manual handling
3. Resolvers & Validation	2.9	Automatic parameter inference, native DataLoader, no built-in validation
4. Built-in Features	3.0	Core features complete, advanced features missing, security features insufficient
5. Ecosystem Integration	2.0	Standard compatible, weak ORM/validation integration, no official adapters

1. Architecture Pattern (Architecture)

Architecture Pattern Type

Builder Pattern: Garph uses a functional chained API to explicitly build GraphQL Schema, provides type definition methods through GarphSchema instances (usually named g), and finally converts definitions to standard GraphQL Schema at runtime through the buildSchema() function.

Core Implementation Mechanism

Source Code Evidence:

Core API definition: garph/src/index.ts (lines 598-727) defines the GarphSchema class and its methods
Schema building: The buildSchema() function in garph/src/schema.ts (lines 17-21) uses graphql-compose's SchemaComposer for conversion
Business code example: typescript-graphql-schemas/garph/src/schema.ts (line 7) creates a GarphSchema instance, line 306 calls buildSchema({ g, resolvers })

Build Flow:

// 1. Create Schema instance
const g = new GarphSchema()

// 2. Define types (chained API)
const UserType = g.type('User', {
  id: g.int(),
  name: g.string(),
})

// 3. Build Schema at runtime
const schema = buildSchema({ g, resolvers })

Scoring Details

1.1 Dependency Complexity (Dependency Complexity)

Score: 4.0

Evidence:

Runtime dependencies (garph/package.json lines 30-33):
- graphql-compose: ^9.0.10 - GraphQL Schema building tool
- single-user-cache: ^0.6.0 - DataLoader cache implementation
No decorator dependencies: No need for reflect-metadata or decorator support
No code generation tools: No need for CLI or code generation steps

Analysis:

✅ Only 2 runtime dependencies, lighter than decorator pattern (requires reflect-metadata, class-validator, etc.)
⚠️ graphql-compose is a feature-complete Schema building library, increases dependency size but provides powerful underlying capabilities
✅ single-user-cache is used for built-in DataLoader support, a feature enhancement rather than a core dependency

1.2 Build Flow (Build Flow)

Score: 5.0

Evidence:

Pure runtime building: The buildSchema() function in garph/src/schema.ts (lines 17-21) executes at runtime
No code generation: Business code (typescript-graphql-schemas/garph/src/server.ts) runs TypeScript directly, no pre-build steps required
No CLI tools: garph/package.json has no dedicated build scripts, only documentation and test scripts

Actual Usage:

// typescript-graphql-schemas/garph/src/server.ts
import { schema } from './schema.ts'
const yoga = createYoga({ schema })
// Run directly, no build steps required

Analysis:

✅ Complete runtime building, developers can run code directly after writing
✅ Supports hot reload (e.g., node --watch), excellent development experience
✅ No need to learn additional CLI commands or build configurations

1.3 Config & Language Magic (Config & Language Magic)

Score: 5.0

Evidence:

No decorators: All type definitions use function calls, such as g.type(), g.string()
No reflection metadata: No need for import 'reflect-metadata' or experimentalDecorators configuration
Standard TypeScript: typescript-graphql-schemas/garph/tsconfig.json only contains standard configuration, no special settings
Type inference: Uses TypeScript generics and conditional types to achieve type safety (Infer, InferResolvers)

Code Example:

// Fully compliant with native TypeScript best practices
const UserType = g.type('User', {
  id: g.int(),
  name: g.string(),
})

// Type inference works automatically
type User = Infer<typeof UserType>

Analysis:

✅ Zero magic, fully compliant with native TypeScript best practices
✅ No dependency on experimental features or compiler plugins
✅ Excellent IDE support, type hints and autocomplete work normally
✅ Strong code readability, chained API is intuitive and easy to understand

1.4 Ecosystem Integration (Ecosystem Integration)

Score: 4.0

Evidence:

Standard installation: npm install garph can be used immediately, no special requirements
Server compatibility: Official examples (garph/examples/demo.ts) use graphql-yoga, but can integrate with any GraphQL Server
Uses graphql-compose under the hood: garph/src/schema.ts (line 2) imports SchemaComposer, ultimately outputs standard GraphQLSchema
Business code integration: typescript-graphql-schemas/garph/src/server.ts directly uses graphql-yoga, simple integration

Analysis:

✅ Standard npm package, can be freely integrated into any project
✅ Outputs standard GraphQL Schema, compatible with all GraphQL Servers
✅ Not bound to specific frameworks, flexible choice of underlying implementation
⚠️ Although not mandatory, official examples and documentation mainly showcase graphql-yoga integration

Architecture Pattern Overall Score

Score: 4.5

Scoring Basis:

Dependency complexity: 4.0 (lightweight dependencies, but graphql-compose increases size)
Build flow: 5.0 (write and use immediately, zero build steps)
Config & language magic: 5.0 (zero magic, completely native TypeScript)
Ecosystem integration: 4.0 (good integration, standard compatible)

Advantages:

Zero-config startup: No need for decorators, reflection, or code generation, works out of the box
Type safety: Achieves end-to-end type safety through TypeScript type system
Excellent development experience: Chained API is intuitive, IDE support is complete
Runtime building: Supports hot reload, fast development iteration

Disadvantages:

Dependency on graphql-compose: Although powerful, increases package size
Explicit API calls: Compared to decorator pattern, requires more explicit code (but gains zero magic advantage)

2. Type Definition (Type Definition)

Core Implementation Mechanism

Garph uses Builder API + type inference to implement type definitions. Schema definitions are created through chained API, TypeScript types are automatically inferred from Schema definitions through the Infer utility type, and GraphQL Schema is generated at runtime through buildSchema().

Source Code Evidence:

Type inference implementation: garph/src/index.ts (lines 93-118) defines the Infer type utility
Schema building: garph/src/schema.ts (lines 85-170) converts Garph types to GraphQL Schema
Business code example: typescript-graphql-schemas/garph/src/schema.ts (lines 68-70) uses Infer to infer types

Scoring Details

2.1 Single Source of Truth (SSOT) Implementation

Score: 4.0

Evidence:

Schema definition as data source: typescript-graphql-schemas/garph/src/schema.ts (lines 23-66) defines Schema through methods like g.type()
TypeScript type automatic inference: Lines 68-70 use Infer<typeof UserType> to infer types from Schema definition
GraphQL Schema automatic generation: Line 306 generates standard GraphQL Schema through buildSchema({ g, resolvers })
Validation logic separation: Validation needs to be manually implemented in Scalar or Resolver (line 181), does not support automatic type generation from validation rules

Code Example:

// Single source of truth: Schema definition
const UserType = g.type('User', {
  id: g.int(),
  name: g.string(),
  email: g.string(),
})

// TypeScript type automatic inference
type User = Infer<typeof UserType>
// Result: { id: number, name: string, email: string }

// GraphQL Schema automatic generation
const schema = buildSchema({ g, resolvers })

Analysis:

✅ Schema definition is the single source of truth, both TypeScript types and GraphQL Schema are derived from it
✅ Deep type inference: Supports nested types, optional fields, arrays, and other complex scenarios
⚠️ Validation logic needs manual integration: Although there are Zod examples (garph/www/docs/advanced/validation.md lines 35-70), it's not native support, needs manual validation calls in Scalar's parseValue
⚠️ Validation rules separated from type definitions: Cannot automatically generate types from validation rules, needs manual synchronization

2.2 Enum & String Union Support (Enum & String Union Types)

Score: 4.0

Evidence:

as const array support: typescript-graphql-schemas/garph/src/schema.ts (lines 15-19) uses g.enumType('OrderStatus', ['PENDING', 'COMPLETED', 'CANCELLED'] as const)
TypeScript Enum support: Official documentation (garph/www/docs/guide/schemas.md lines 129-138) shows support for TypeScript Enum
Type inference requirement: Must use as const to correctly infer types (documentation line 127 explicitly states)

Code Example:

// Method 1: as const array (recommended)
const OrderStatusEnum = g.enumType('OrderStatus', [
  'PENDING',
  'COMPLETED',
  'CANCELLED',
] as const)

// Method 2: TypeScript Enum
enum Fruits {
  Apples,
  Oranges
}
g.enumType('Fruits', Fruits)

Analysis:

✅ Supports two methods: as const array and TypeScript Enum
✅ No need to redefine member names: Directly use array or Enum, no manual mapping required
⚠️ Must use as const: Missing as const will cause type inference to fail, developers need to remember this requirement
✅ Type safe: Enum values are completely synchronized in TypeScript and GraphQL

2.3 Interface Inheritance & Union Type Experience (Interface & Union)

Score: 4.0

Evidence:

Interface fields automatic inheritance: typescript-graphql-schemas/garph/src/schema.ts (lines 34-51) demonstrates interface implementation
- FoodInterface defines common fields (id, name, price)
- CoffeeType and DessertType automatically inherit through .implements(FoodInterface)
- Implementation types only need to define unique fields (sugarLevel/origin and calories)
Runtime automatic merging: garph/src/schema.ts (lines 94-98) automatically adds interface fields to implementation types when building Schema
Type system support: garph/src/index.ts (line 195) uses UnionToIntersection to merge interface fields at the type level
Union types require manual handling: typescript-graphql-schemas/garph/src/schema.ts (lines 202-211) needs to manually return typename in Resolver
Union type resolution: garph/examples/union.ts (lines 36-39) needs to manually implement resolveType

Code Example:

// Interface definition
const FoodInterface = g.interface('Food', {
  id: g.int(),
  name: g.string(),
  price: g.float(),
})

// Implement interface (automatic field inheritance)
const CoffeeType = g
  .type('Coffee', {
    sugarLevel: g.ref(SugarLevelEnum),
    origin: g.string(),
  })
  .implements(FoodInterface)
// CoffeeType automatically includes id, name, price fields

// Union type definition
const MenuItemType = g.unionType('MenuItem', {
  Coffee: CoffeeType,
  Dessert: DessertType,
})

// Union types require manual __typename handling
createCoffee: (_, { name, price, sugarLevel, origin }) => {
  return {
    __typename: 'Coffee' as const,  // Must manually specify
    id,
    name,
    price,
    sugarLevel,
    origin,
  }
}

Analysis:

✅ Interface fields automatic inheritance: Implementation types don't need to repeat common field declarations
✅ Type system support: TypeScript types also automatically include interface fields
⚠️ Union types require manual __typename: Must explicitly specify type name in return object
⚠️ Union types require manual __resolveType: Need to implement type resolution function (optional but usually needed)
✅ Supports multiple interface implementation: Can implement multiple interfaces simultaneously (garph/examples/implements.ts line 13)

2.4 Type Inference Strength & Explicit Declaration Balance

Score: 3.0

Evidence:

Automatic inference of basic types: garph/src/index.ts (lines 108-118) InferShallow automatically handles String, Int, Float, Boolean, ID, Enum and other basic types
Automatic inference of complex types: Supports arrays (AnyList), optional (AnyOptional), nested objects (recursive InferRaw), Union types
Resolver type inference: InferResolvers (lines 134-154) automatically infers Resolver parameter types and return value types
Requires explicit type annotations: typescript-graphql-schemas/garph/src/schema.ts (lines 152-160) needs to add InferResolvers type annotation to Resolver object

Code Example:

// Basic type automatic inference
const UserType = g.type('User', {
  id: g.int(),           // Inferred as number
  name: g.string(),      // Inferred as string
  email: g.string(),     // Inferred as string
})

type User = Infer<typeof UserType>
// Automatically inferred as: { id: number, name: string, email: string }

// Complex type automatic inference
const OrderType = g.type('Order', {
  userId: g.int(),
  itemIds: g.int().list(),              // Inferred as number[]
  status: g.ref(OrderStatusEnum),        // Inferred as enum value
  createdAt: g.ref(DateTime),            // Inferred as Date
  items: g.ref(MenuItemType).list(),    // Inferred as MenuItem[]
})

// Resolver type automatic inference
const resolvers: InferResolvers<
  { Query: typeof queryType },
  {}
> = {
  Query: {
    user: (_, { id }) => {  // id automatically inferred as number
      // ...
    }
  }
}

Analysis:

✅ Powerful type inference: Supports all GraphQL types including basic types, arrays, optional, nested, Union
✅ Resolver parameter type automatic inference: Automatically infers parameter types through InferResolvers, no manual declaration needed
✅ Recursive type inference: Supports deeply nested object types
⚠️ Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation (although this is for type safety, it increases code volume)
✅ Excellent IDE support: Type hints and autocomplete work normally

Type Definition Overall Score

Score: 3.5

Scoring Basis:

SSOT implementation: 4.0 (deep inference, but validation logic separated)
Enum support: 4.0 (lightweight mapping, but requires as const)
Interface inheritance: 4.0 (smart inheritance, but Union requires manual handling)
Type inference strength: 3.0 (powerful inference, but requires explicit type annotations)

Advantages:

Powerful type inference: Automatically infers TypeScript types from Schema definitions, supports complex scenarios
Interface automatic inheritance: No need to repeat common field declarations when implementing interfaces
Flexible enum support: Supports as const arrays and TypeScript Enum
Complete type safety: End-to-end type safety, from Schema to Resolver

Disadvantages:

Union types require manual handling: Must manually return __typename and implement __resolveType
Validation logic separated: Validation rules separated from type definitions, needs manual synchronization
Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation

3. Resolvers & Validation (Resolvers & Validation)

Core Implementation Mechanism

Garph's Resolver definition uses explicit type annotations + automatic type inference. All Resolvers are centralized in one object, organized by Query, Mutation, and type names. Parameter types are automatically inferred through the InferResolvers utility type, but explicit type annotations need to be added to the Resolver object.

Source Code Evidence:

Resolver type inference: garph/src/index.ts (lines 134-154) defines the InferResolvers type utility
Business code example: typescript-graphql-schemas/garph/src/schema.ts (lines 152-304) demonstrates complete Resolver definition

Scoring Details

3.1 Development Experience (Code Conciseness)

Score: 3.5

Evidence:

Resolver definition concise: typescript-graphql-schemas/garph/src/schema.ts (lines 161-178) Query Resolver definition is intuitive
Parameter type automatic inference: In line 163's user: (_, { id }), id type is automatically inferred as number
Requires explicit type annotations: Lines 152-160 need to add InferResolvers type annotation to Resolver object
Validation logic manually written: Lines 181, 192, 250-260 need to manually write validation logic

Code Example:

// Resolver definition (concise but requires type annotation)
const resolvers: InferResolvers<
  {
    Query: typeof queryType
    Mutation: typeof mutationType
    User: typeof UserType
    Order: typeof OrderType
  },
  {}
> = {
  Query: {
    users: () => Array.from(userMap.values()),
    user: (_, { id }) => {  // id automatically inferred as number
      const user = userMap.get(id)
      if (!user) throw new GraphQLError('User not found')
      return user
    },
  },
  Mutation: {
    createUser: (_, { name, email }) => {
      // Need to manually write validation logic
      if (!email.includes('@')) {
        throw new GraphQLError('Invalid email format')
      }
      // ...
    },
  },
}

Analysis:

✅ Resolver function definition concise, parameter types automatically inferred
✅ Excellent IDE support, type hints and autocomplete work normally
⚠️ Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation (although this is for type safety, it increases code volume)
⚠️ Validation logic needs manual writing: Each place that needs validation must manually write validation code

3.2 Modular Design (Domain-Driven Development Support)

Score: 0.0

Evidence:

Organized by operation type: typescript-graphql-schemas/garph/src/schema.ts (lines 152-304) all Resolvers are in one object, organized by Query, Mutation, User, Order
No enforced module boundaries: No enforced module boundaries, all Resolvers are in the same file
Easy to write coupled code: If not careful, easy to write all domain Query/Mutation/Field Resolvers in one file
Can manually split: Although can split files by domain modules, needs manual combination, and no enforced module boundaries

Code Example:

// All Resolvers in one object, organized by operation type
const resolvers: InferResolvers<...> = {
  Query: {
    users: ...,
    user: ...,
    menu: ...,
    menuItem: ...,
    orders: ...,
    order: ...,
  },
  Mutation: {
    createUser: ...,
    updateUser: ...,
    deleteUser: ...,
    createCoffee: ...,
    // ... All Mutations mixed together
  },
  User: {
    orders: ...,
  },
  Order: {
    user: ...,
    items: ...,
  },
}

Analysis:

❌ Completely isolated by operation type: Query, Mutation, Type organized separately, not by domain
❌ No enforced module boundaries: No enforced module boundaries, easy to write coupled giant files
⚠️ Needs manual combination: If modularizing, needs to manually split files and combine, but framework doesn't enforce
⚠️ Limited DDD support: Although can organize by files, lacks enforced module boundaries, easy to write coupled code

3.3 Parameter Definition & Type Inference

Score: 4.0

Evidence:

Parameter definition in fields: typescript-graphql-schemas/garph/src/schema.ts (lines 80-82) parameters defined in fields through .args()
Parameter type automatic inference: In line 163's user: (_, { id }), id type automatically inferred as number through InferResolvers
Excellent IDE hints: TypeScript fully understands parameter types, IDE autocomplete works normally
Requires explicit type annotations: Lines 152-160 need to add InferResolvers type annotation to Resolver object

Code Example:

// Parameter definition in fields
const queryType = g.type('Query', {
  user: g.ref(UserType).optional().args({
    id: g.int(),  // Parameter definition
  }),
})

// Parameter type automatic inference
const resolvers: InferResolvers<{ Query: typeof queryType }, {}> = {
  Query: {
    user: (_, { id }) => {  // id automatically inferred as number
      // ...
    },
  },
}

Analysis:

✅ Parameter types mostly automatically inferred: Automatically infers parameter types through InferResolvers, no manual declaration needed
✅ Excellent IDE hints: TypeScript fully understands parameter types, IDE autocomplete works normally
⚠️ Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation (although this is for type safety, it increases code volume)
✅ Type safe: Parameter types completely synchronized with Schema definition

3.4 Input Validation Mechanism

Score: 2.0

Evidence:

No built-in validation: typescript-graphql-schemas/garph/src/schema.ts (lines 181, 192, 250-260) all validation logic needs to be manually written
Can implement through Scalar: garph/examples/validation.ts (lines 6-15) demonstrates validation through Scalar's parseValue
Supports Zod integration: garph/www/docs/advanced/validation.md (lines 35-70) shows using Zod validation, but needs manual calls in Scalar
Validation logic scattered: Validation code scattered across various Resolvers, difficult to reuse

Code Example:

// Method 1: Manual validation in Resolver
createUser: (_, { name, email }) => {
  if (!email.includes('@')) {
    throw new GraphQLError('Invalid email format')
  }
  // ...
}

// Method 2: Validation through Scalar
const username = g.scalarType<string, string>('Username', {
  serialize: (username) => username,
  parseValue: (username) => {
    if (username.length < 3) {
      throw new GraphQLError('Username must be at least 3 characters long')
    }
    return username
  }
})

// Method 3: Using Zod (needs manual call)
const usernameValidator = z.string().min(3)
const username = g.scalarType<string, string>('Username', {
  parseValue: (username) => {
    if (!usernameValidator.safeParse(username).success) {
      throw new GraphQLError('Username must be at least 3 characters long')
    }
    return username
  }
})

Analysis:

❌ No built-in validation: Does not provide declarative validation API (like .refine() or @IsEmail())
❌ Validation logic repetitive: Needs to manually write validation code in each place that needs validation
⚠️ Can implement through Scalar: But needs to create independent Scalar types for each validation scenario, increases code volume
⚠️ Supports Zod integration: But needs manual calls in Scalar's parseValue, validation logic separated from Schema definition
❌ No declarative API: Does not provide declarative validation API like .refine()

3.5 Batch Loading (DataLoader) Integration

Score: 5.0

Evidence:

Native built-in support: The addResolver function in garph/src/schema.ts (lines 193-220) automatically handles load and loadBatch methods
Uses single-user-cache: Lines 4-5 use single-user-cache to implement DataLoader functionality
Almost no boilerplate: garph/examples/loader.ts (lines 34-44) shows only need to define load function, no need to configure Context or create DataLoader instances
Supports cache control: load method supports caching, loadBatch method does not support caching

Code Example:

// Use .omitResolver() when defining fields
const Dog = g.type('Dog', {
  name: g.string(),
  owner: g.string().omitResolver()  // Mark as requiring Resolver
})

// Define load function in Resolver
const resolvers: InferResolvers<{ Query: typeof queryType, Dog: typeof Dog }, {}> = {
  Query: {
    dogs: (parent, args, context, info) => {
      return [{ name: 'Apollo' }, { name: 'Buddy' }]
    }
  },
  Dog: {
    owner: {
      load(queries) {  // Automatic batch loading, supports caching
        return Promise.resolve(
          queries.map(q => owners[q.parent.name])
        )
      }
    }
  }
}

Analysis:

✅ Native built-in support: No need to install additional plugins or configuration, directly use load or loadBatch methods
✅ Almost no boilerplate: Only need to define load function, no need to configure Context or create DataLoader instances
✅ Automatic batch processing: Framework automatically collects queries and executes in batches
✅ Supports cache control: load supports caching, loadBatch does not support caching
✅ Type safe: load function parameter and return value types automatically inferred

Resolvers & Validation Overall Score

Score: 2.9

Scoring Basis:

Development experience: 3.5 (code concise, but requires explicit type annotations)
Modular design: 0.0 (no modular consideration, organized by operation type)
Parameter definition & type inference: 4.0 (parameter types mostly automatically inferred)
Input validation mechanism: 2.0 (no built-in validation, needs complete manual implementation)
DataLoader integration: 5.0 (native built-in support, seamless usage)

Advantages:

Parameter type automatic inference: Automatically infers parameter types through InferResolvers, excellent IDE support
DataLoader native support: Built-in DataLoader support, almost no boilerplate
Code concise: Resolver function definitions intuitive, easy to understand

Disadvantages:

No built-in validation: Needs to manually write all validation logic, validation code repetitive
Limited modular support: Organized by operation type, doesn't enforce modularization, easy to write coupled code
Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation

4. Built-in Features (Built-in Features)

Feature Support Overview

Garph provides native support for core features (Context, DataLoader, Subscriptions, Custom Scalars), but has limited support for advanced features (Directives, Middleware, Query Complexity, Depth Limiting).

Feature Support Details Table

Feature	Support Status	Implementation	Evidence/Explanation
Directives	⛔ Not Implementable	Not Supported	Official documentation (`garph/www/docs/guide/schemas.md` line 252) explicitly states "Currently not supported", refer to GitHub issue #40
Extensions	⚠️ Plugin/Additional Implementation	Via GraphQLError	`garph/examples/errors.ts` (line 17) demonstrates implementation through `GraphQLError`'s `extensions` parameter, but not a native API
Batch Loading (DataLoader)	✅ Built-in Support	Native Built-in	`garph/src/schema.ts` (lines 193-220) native support for `load` and `loadBatch` methods, almost no boilerplate
Custom Scalars	✅ Built-in Support	Native Built-in	`garph/examples/scalars.ts` (line 5) defined through `g.scalarType()`, API intuitive and type safe
Subscriptions	✅ Built-in Support	Native Built-in	`garph/examples/subscriptions.ts` (lines 9-33) native support, implemented through async generator
Context	✅ Built-in Support	Native Built-in	`garph/examples/context.ts` (lines 15-17) native support, excellent type inference, good IDE hints
Middleware	⛔ Not Implementable	Not Supported	No related support found, cannot inject middleware logic before/after Resolver execution
Query Complexity	⛔ Not Implementable	Not Supported	No related support found, cannot prevent complex query attacks
Depth Limiting	⛔ Not Implementable	Not Supported	No related support found, cannot prevent deep query attacks

Detailed Analysis

4.1 Directive Support (Directives)

Status: ⛔ Not Implementable

Evidence:

Official documentation (garph/www/docs/guide/schemas.md line 252) explicitly states "Currently not supported"
Refer to GitHub issue #40: https://github.com/stepci/garph/issues/40

Analysis:

❌ Completely does not support Directives definition
❌ Cannot implement Directives functionality through any means
⚠️ This is a known limitation, may be supported in future versions

4.2 Extension Support (Extensions)

Status: ⚠️ Plugin/Additional Implementation

Evidence:

garph/examples/errors.ts (line 17) demonstrates implementation through GraphQLError's extensions parameter
garph/www/docs/advanced/errors.md (lines 28-43) shows error extension usage

Code Example:

throw new GraphQLError('Expected error with extensions', {
  extensions: { code: 'EXPECTED_ERROR' }
})

Analysis:

⚠️ Does not natively support Extensions API
⚠️ Can implement through GraphQLError's extensions parameter, but needs manual handling
⚠️ Cannot declare query complexity, execution time and other extension information

4.3 Batch Loading (DataLoader) Integration

Status: ✅ Built-in Support

Evidence:

The addResolver function in garph/src/schema.ts (lines 193-220) automatically handles load and loadBatch methods
garph/examples/loader.ts (lines 34-44) shows only need to define load function, no need to configure Context or create DataLoader instances
Uses single-user-cache to implement DataLoader functionality

Code Example:

Dog: {
  owner: {
    load(queries) {  // Automatic batch loading, supports caching
      return Promise.resolve(
        queries.map(q => owners[q.parent.name])
      )
    }
  }
}

Analysis:

✅ Native built-in support, no need to install additional plugins
✅ Almost no boilerplate, only need to define load function
✅ Automatic batch processing, supports cache control (load supports caching, loadBatch does not)

4.4 Custom Scalars (Scalars)

Status: ✅ Built-in Support

Evidence:

garph/examples/scalars.ts (line 5) demonstrates defining custom scalars through g.scalarType()
typescript-graphql-schemas/garph/src/schema.ts (lines 9-13) demonstrates DateTime scalar definition
garph/src/index.ts (lines 435-451) defines GScalar class and scalarType method

Code Example:

const DateTime = g.scalarType<Date, Date>('DateTime', {
  serialize: (value) => GraphQLDateTime.serialize(value),
  parseValue: (value) => GraphQLDateTime.parseValue(value) as Date,
  parseLiteral: (ast) => GraphQLDateTime.parseLiteral(ast, {}) as Date,
})

Analysis:

✅ Easy to define new scalar types, API intuitive
✅ Type safe, supports generic parameters to specify input/output types
⚠️ Does not include built-in common scalars (like DateTime, JSON, BigInt), needs manual definition or use third-party libraries (like graphql-scalars)

4.5 Subscriptions (Subscription)

Status: ✅ Built-in Support

Evidence:

garph/examples/subscriptions.ts (lines 9-33) demonstrates native Subscriptions support
garph/src/index.ts (lines 135-139) InferResolvers type supports Subscription type
Implements real-time data push through async generator

Code Example:

const subscriptionType = g.type('Subscription', {
  counter: g.int(),
})

const resolvers: InferResolvers<{ Subscription: typeof subscriptionType }, {}> = {
  Subscription: {
    counter: {
      subscribe: async function* (parent, args, context, info) {
        for (let i = 100; i >= 0; i--) {
          await new Promise((resolve) => setTimeout(resolve, 1000))
          yield { counter: i }
        }
      }
    }
  }
}

Analysis:

✅ Native support for GraphQL Subscriptions
✅ Supports real-time data push, implemented through async generator
✅ Good underlying transport protocol compatibility (supports WebSocket, SSE, etc. through graphql-yoga)
✅ API concise, type safe

4.6 Context Injection (Context)

Status: ✅ Built-in Support

Evidence:

garph/examples/context.ts (lines 9-26) demonstrates Context usage
garph/src/index.ts (lines 134-154) InferResolvers type supports Context type parameter
garph/www/docs/advanced/context.md provides complete Context usage documentation

Code Example:

const context = () => {
  return {
    hello: 'world'
  }
}

const resolvers: InferResolvers<
  { Query: typeof queryType },
  { context: YogaInitialContext & ReturnType<typeof context> }
> = {
  Query: {
    context: (parent, args, context, info) => `Context: ${context.hello}`
  }
}

const yoga = createYoga({ schema, context })

Analysis:

✅ Native support for injecting context in Resolver
✅ Excellent context type inference, specified through InferResolvers's second type parameter
✅ Good IDE hints, no need for manual type declarations
✅ Supports extending default Context (like YogaInitialContext)

4.7 Middleware (Middleware)

Status: ⛔ Not Implementable

Evidence:

No related support documentation or examples found
No middleware-related code found in garph/src/schema.ts and garph/src/index.ts

Analysis:

❌ Completely does not support middleware mechanism
❌ Cannot inject logic before/after Resolver execution (like logging, permission checks, performance monitoring)
⚠️ Can implement similar functionality by manually wrapping Resolvers, but needs additional boilerplate

4.8 Query Complexity Analysis (Query Complexity)

Status: ⛔ Not Implementable

Evidence:

No related support documentation or examples found
No query complexity calculation and analysis related code found

Analysis:

❌ Completely does not support query complexity analysis
❌ Cannot prevent complex query attacks
⚠️ Can implement through graphql-yoga plugins, but needs additional configuration

4.9 Depth Limiting (Depth Limiting)

Status: ⛔ Not Implementable

Evidence:

No related support documentation or examples found
No depth limiting related code found

Analysis:

❌ Completely does not support depth limiting
❌ Cannot prevent deep query attacks
⚠️ Can implement through graphql-yoga plugins, but needs additional configuration

Built-in Features Overall Score

Score: 3.0

Scoring Basis:

Directives: ⛔ Not Implementable (0 points) - Official documentation explicitly states not supported
Extensions: ⚠️ Plugin/Additional Implementation (2 points) - Can implement through GraphQLError's extensions parameter
DataLoader: ✅ Built-in Support (5 points) - Native built-in, through load and loadBatch methods
Scalars: ✅ Built-in Support (5 points) - Defined through g.scalarType(), API intuitive
Subscription: ✅ Built-in Support (5 points) - Native support, implemented through async generator
Context: ✅ Built-in Support (5 points) - Native support, excellent type inference
Middleware: ⛔ Not Implementable (0 points) - Completely does not support middleware mechanism
Query Complexity: ⛔ Not Implementable (0 points) - Completely does not support query complexity analysis
Depth Limiting: ⛔ Not Implementable (0 points) - Completely does not support depth limiting

Total Score: 27/45 = 3.0/5.0

Scoring Basis:

Core features well supported: Context, DataLoader, Subscriptions, Custom Scalars all provide native support
Advanced features limited support: Directives, Middleware, Query Complexity, Depth Limiting all not supported
Feature completeness: Out of 9 features, 4 built-in support, 1 plugin/additional implementation, 4 not implementable

Advantages:

Core features complete: Context, DataLoader, Subscriptions, Custom Scalars all provide native support
Type safe: All supported features have excellent type inference
API concise: Supported features have intuitive and easy-to-use APIs

Disadvantages:

Advanced features missing: Directives, Middleware, Query Complexity, Depth Limiting all not supported
Security features insufficient: Cannot prevent complex query attacks and deep query attacks
Limited extensibility: Lacks middleware mechanism, difficult to implement cross-cutting concerns

5. Ecosystem Integration (Ecosystem Integration)

Core Integration Strategy

Garph adopts standard GraphQL Schema output + manual integration strategy. Outputs standard GraphQLSchema through buildSchema(), can integrate with any GraphQL Server, but needs manual adaptation. Mainly showcases integration with graphql-yoga, other Servers and frameworks need to integrate through standard GraphQL Server.

Scoring Details

5.1 ORM Integration Depth (ORM Integration Depth)

Score: <-To Be Scored->

Evidence:

No official plugins: No official plugins found for Prisma, Drizzle, TypeORM and other ORMs
Needs manual integration: All database operations in typescript-graphql-schemas/garph/src/schema.ts are manually implemented (using in-memory Map)
Type synchronization needs manual maintenance: ORM model definitions separated from GraphQL Schema definitions, needs manual synchronization

Code Example:

// Need to manually define GraphQL types
const UserType = g.type('User', {
  id: g.int(),
  name: g.string(),
  email: g.string(),
})

// Need to manually implement database queries
const resolvers: InferResolvers<...> = {
  Query: {
    users: () => Array.from(userMap.values()),  // Manual query
    user: (_, { id }) => userMap.get(id),      // Manual query
  },
}

Analysis:

❌ No official plugins: Does not provide official plugins for Prisma, Drizzle, TypeORM and other ORMs
❌ Needs lots of glue code: Must manually write all database query logic
❌ Type synchronization needs manual maintenance: ORM model definitions separated from GraphQL Schema definitions
⚠️ Can manually integrate: Although can manually integrate ORM, needs lots of boilerplate

5.2 Validation Library Integration (Validation Library Integration)

Score: <-To Be Scored->

Evidence:

Supports Zod, but needs manual integration: garph/www/docs/advanced/validation.md (lines 35-70) shows using Zod validation, but needs manual calls in Scalar's parseValue
Validation logic separated from Schema definition: Validation rules cannot be directly declared in Schema definition, needs to create independent Scalar types
Needs manual type synchronization: Validation rules separated from type definitions, needs manual synchronization

Code Example:

// Need to manually create Scalar and call Zod
const usernameValidator = z.string().min(3)

const username = g.scalarType<string, string>('Username', {
  serialize: (username) => username,
  parseValue: (username) => {
    if (!usernameValidator.safeParse(username).success) {
      throw new GraphQLError('Username must be at least 3 characters long')
    }
    return username
  }
})

Analysis:

❌ No native support: Does not provide declarative validation API (like .refine() or validate option)
❌ Validation logic separated from Schema definition: Needs to manually call validation library in Scalar
❌ Needs lots of boilerplate: Each validation scenario needs to create independent Scalar types
⚠️ Can manually integrate: Although can manually integrate Zod, needs lots of boilerplate

5.3 GraphQL Server Compatibility (Server Compatibility)

Score: <-To Be Scored->

Evidence:

Outputs standard GraphQL Schema: The buildSchema() function in garph/src/schema.ts (lines 17-21) outputs standard GraphQLSchema
Compatible with standard GraphQL.js: Uses graphql-compose to build Schema, ultimately outputs standard GraphQL Schema
Mainly showcases graphql-yoga: garph/www/docs/integration/server/graphql-yoga.md provides detailed integration documentation
Supports other Servers: garph/www/docs/integration/server/apollo-server.md and mercurius.md exist (although content incomplete)

Code Example:

// Output standard GraphQL Schema
const schema = buildSchema({ g, resolvers })

// Can integrate with any GraphQL Server
const yoga = createYoga({ schema })  // graphql-yoga
// or
const server = new ApolloServer({ schema })  // Apollo Server

Analysis:

✅ Compatible with standard GraphQL.js: Outputs standard GraphQLSchema, can integrate into any GraphQL Server
✅ Not bound to specific Server: Can integrate with Apollo Server, GraphQL Yoga, Envelop, Hono, etc.
⚠️ Needs manual adaptation: Although compatible, needs manual adaptation, no official adapters provided
⚠️ Documentation mainly showcases graphql-yoga: Other Servers' integration documentation incomplete

5.4 Toolchain Integration (Toolchain Integration)

Score: <-To Be Scored->

Evidence:

TypeScript/JavaScript Support:

TypeScript native: Core files like garph/src/index.ts, garph/src/schema.ts are all written in TypeScript
Compiled to JavaScript: garph/package.json line 10 "main": "dist/index.js" indicates compiled JavaScript output
TypeScript configuration: garph/tsconfig.json shows target: "ESNext", module: "NodeNext", uses modern ES modules
All examples are TypeScript: All example files in garph/examples/ directory are .ts files, no pure JavaScript examples

Runtime Environment Support:

Node.js: Explicitly supported. All official examples (garph/examples/demo.ts, garph/examples/context.ts, etc.) use Node.js's createServer and http modules
Bun: Documentation mentions support. garph/www/docs/integration/server/graphql-yoga.md lines 26-28 provide bun i graphql-yoga installation method, garph/www/docs/index.md lines 41-43 also provide bun installation example
Deno/Cloudflare Workers: No explicit evidence. No Deno or Cloudflare Workers examples or configurations found in source code and documentation
Browser: Not supported. Core code garph/src/schema.ts depends on graphql-compose and single-user-cache, these dependencies may contain Node.js-specific APIs; all examples are server-side code; no browser runtime examples or documentation

Build Tool Support:

No explicit configuration: No webpack, vite, rspack and other build tool configuration examples found in source code and documentation
Uses TypeScript compiler: garph/package.json line 15 build script is "build": "tsc -p tsconfig.json", only uses TypeScript compiler
Documentation uses VitePress: garph/package.json lines 12-14 show documentation uses VitePress (based on Vite), but this is documentation build tool, not framework's own build tool integration

Code Example:

// garph/examples/demo.ts - Node.js environment
import { g, InferResolvers, buildSchema } from '../src/index'
import { createYoga } from 'graphql-yoga'
import { createServer } from 'http'  // Node.js specific API

const schema = buildSchema({ g, resolvers })
const yoga = createYoga({ schema })
const server = createServer(yoga)  // Requires Node.js http module
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Analysis:

✅ TypeScript native support: Framework completely written in TypeScript, compiled to JavaScript
✅ Supports Node.js and Bun: Explicitly supports Node.js, documentation mentions Bun support
⚠️ Does not support browser: Core dependencies may contain Node.js-specific APIs, no browser runtime evidence
⚠️ Deno/Cloudflare Workers support unclear: No related examples or documentation
⚠️ Build tool integration missing: No webpack, vite, rspack and other build tool configuration examples or documentation
⚠️ Mainly server-side oriented: All examples and documentation are server-side usage scenarios

Ecosystem Integration Overall Score

Score: 2.0

Scoring Basis:

ORM integration depth: 2.0 (weak integration, needs lots of glue code)
Validation library integration: 2.0 (weak integration, needs lots of boilerplate)
GraphQL Server compatibility: 3.0 (standard compatible, but needs manual adaptation)
Toolchain integration: 2.0 (mainly supports TypeScript and Node.js/Bun, does not support browser, build tool integration missing)

Advantages:

Standard compatible: Outputs standard GraphQL Schema, can integrate with any GraphQL Server
Not bound to specific Server: Can integrate with Apollo Server, GraphQL Yoga, Envelop, etc.
Has example references: Provides Next.js, Nuxt, Remix integration examples

Disadvantages:

Weak ORM integration: No official plugins, needs lots of glue code
Weak validation library integration: Needs manual integration, validation logic separated from Schema definition
Limited toolchain support: Does not support browser environment, Deno/Cloudflare Workers support unclear, no build tool integration examples
Mainly server-side oriented: All examples and documentation are server-side usage scenarios, client-side usage limited
Limited integration documentation: Mainly showcases graphql-yoga, other Servers and frameworks' documentation incomplete

📝 Summary

Overall Score: 2.7/5.0

Dimension	Score	Description
Architecture Pattern	4.5	Builder pattern, zero magic, write and use immediately, lightweight dependencies
Type Definition	3.5	Deep inference, smart inheritance, flexible enums, Union requires manual handling
Resolvers & Validation	2.9	Automatic parameter inference, native DataLoader, no built-in validation
Built-in Features	3.0	Core features complete, advanced features missing, security features insufficient
Ecosystem Integration	2.0	Standard compatible, weak ORM/validation integration, no official adapters

Overall Evaluation

Garph adopts the Builder pattern, achieving a zero magic, write-and-use-immediately design philosophy. Lightweight dependencies, pure runtime building, supports hot reload, excellent development experience. Native DataLoader support is a highlight, almost no boilerplate. But has limited support in validation, modularization, advanced features (Directives, Middleware, query complexity, depth limiting), and weak ORM and validation library integration.

Core Advantages

Zero magic design: No need for decorators, reflection metadata, or code generation, fully compliant with native TypeScript best practices
Write and use immediately: Pure runtime building, supports hot reload, fast development iteration
DataLoader native support: Built-in batch loading, almost no boilerplate, automatic batch processing and caching
Type safety: End-to-end type safety, excellent type inference from Schema to Resolver
Lightweight dependencies: Only depends on graphql-compose and single-user-cache, lighter than decorator pattern

Main Disadvantages

No built-in validation: Needs to manually write all validation logic, validation code repetitive, validation logic scattered
Limited modular support: Organized by operation type (Query, Mutation, Type), doesn't enforce modularization, easy to write coupled code
Advanced features missing: Directives, Middleware, Query Complexity, Depth Limiting all not supported
Weak ORM/validation library integration: No official plugins, needs lots of glue code, type synchronization needs manual maintenance
Requires explicit type annotations: Resolver object needs to add InferResolvers type annotation

Use Cases

Recommended For

Small to medium projects, need quick startup and iteration
Teams that need zero magic, write-and-use-immediately, prefer native TypeScript practices
Projects with strong DataLoader requirements
Projects that don't need Directives or Middleware

Not Recommended For

Projects that need Directives or Middleware
Projects that need deep ORM integration
Projects that need declarative validation
Projects that need query complexity analysis or depth limiting

Improvement Suggestions

Provide declarative validation API: Support declarative validation like .refine(), reduce manual validation code
Enhance modular support: Provide domain-organized API, enforce module boundaries, avoid coupling
Provide Directives and Middleware support: Meet advanced feature requirements
Provide official plugins for ORM and validation libraries: Reduce glue code, improve integration
Reduce explicit type annotation requirements: Reduce InferResolvers annotations through better type inference

Getting Started with GQLoom - Building GraphQL Server Applications with Zod + Drizzle

Fri, 17 Oct 2025 12:43:03 +0000

Introduction

In the Node.js ecosystem, building GraphQL APIs typically requires writing a lot of boilerplate code manually: defining schemas, writing resolvers, handling type validation, database operations, and more. Today, I'd like to introduce you to a brand new solution — GQLoom — that allows you to build type-safe GraphQL APIs using your favorite TypeScript type libraries (like Valibot or Zod), significantly boosting development efficiency.

What is GQLoom?

GQLoom is a Code First GraphQL Schema framework that weaves runtime types from the TypeScript/JavaScript ecosystem into GraphQL schemas. Simply put, you can use types defined with Valibot or Zod to directly generate GraphQL APIs without duplicating schema definitions.

Hands-on Project: Cattery Management System

To help you better understand the power of GQLoom, we'll build a complete cattery management system together. This project will cover:

🐱 Cat Information Management: Enter, query, and update basic cat information (name, birthday, etc.)
👤 User (Cat Owner) Management: User registration, login authentication, and viewing their own cats
🔗 Relationship Queries: Query cat owner information and view all cats belonging to a user
🛡️ Access Control: Only logged-in users can add cats, ensuring data security

Technology Stack

We'll use the following modern technology stack:

🚀 TypeScript - Type-safe JavaScript superset
🟢 Node.js - JavaScript runtime environment
📊 GraphQL - Powerful API query language
🧘 GraphQL Yoga - Modern GraphQL server
🗄️ Drizzle ORM - Lightweight, type-safe ORM
⚡ Zod - Powerful TypeScript-first validation library
🧵 GQLoom - Framework for weaving runtime types into GraphQL schemas

Prerequisites

Before we begin, make sure your development environment meets the following requirements:

Node.js 20+ - Recommended to use the latest LTS version
npm/yarn/pnpm - Package manager (this article uses npm)
Code Editor - VS Code or other TypeScript-supporting editor

Creating the Application

Project Structure

Our application will have the following structure:

cattery/
├── src/
│   ├── contexts/
│   │   └── index.ts
│   ├── providers/
│   │   └── index.ts
│   ├── resolvers/
│   │   ├── cat.ts
│   │   ├── index.ts
│   │   └── user.ts
│   ├── schema/
│   │   └── index.ts
│   └── index.ts
├── drizzle.config.ts
├── package.json
└── tsconfig.json

The functions of each folder or file under the src directory are as follows:

contexts: Store contexts, such as the current user
providers: Store functions that need to interact with external services, such as database connections and Redis connections
resolvers: Store GraphQL resolvers
schema: Store schemas, mainly database table structures
index.ts: Used to run the GraphQL application as an HTTP service

Initialize the Project

First, let's create a new folder and initialize the project:

mkdir cattery
cd ./cattery
npm init -y

Then, we'll install some necessary dependencies to run a TypeScript application in Node.js:

npm i -D typescript @types/node tsx
npx tsc --init

Next, we'll install GQLoom and Zod-related dependencies:

npm i graphql graphql-yoga @gqloom/core zod @gqloom/zod

Hello World

Let's write our first resolver:

// src/resolvers/index.ts
import { query, resolver } from "@gqloom/core"
import * as z from "zod"

const helloResolver = resolver({
  hello: query(z.string())
    .input({
      name: z
        .string()
        .nullish()
        .transform((x) => x ?? "World"),
    })
    .resolve(({ name }) => `Hello ${name}!`),
})

export const resolvers = [helloResolver]

We need to weave this resolver into a GraphQL schema and run it as an HTTP server:

// src/index.ts
import { createServer } from "node:http"
import { weave } from "@gqloom/core"
import { ZodWeaver } from "@gqloom/zod"
import { createYoga } from "graphql-yoga"
import { resolvers } from "src/resolvers"

const schema = weave(ZodWeaver, ...resolvers)

const yoga = createYoga({ schema })
createServer(yoga).listen(4000, () => {
  console.info("Server is running on http://localhost:4000/graphql")
})

Great! We've created a simple GraphQL application.

Next, let's try running this application. Add the dev script to package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts"
  }
}

Now let's run it:

npm run dev

Open http://localhost:4000/graphql in your browser to see the GraphQL playground.

Let's try sending a GraphQL query. Enter the following in the playground:

{
  hello(name: "GQLoom")
}

Click the query button, and you can see the result:

{
  "data": {
    "hello": "Hello GQLoom!"
  }
}

So far, we've created the simplest GraphQL application.

Next, we'll use Drizzle ORM to interact with the database and add complete functionality.

Initialize Database and Tables

First, let's install Drizzle ORM. We'll use it to operate the SQLite database.

npm i @gqloom/drizzle drizzle-orm @libsql/client dotenv
npm i -D drizzle-kit

Define Database Tables

Next, define the database tables in the src/schema/index.ts file. We'll define two tables, users and cats, and establish the relationship between them:

// src/schema/index.ts
import { drizzleSilk } from "@gqloom/drizzle"
import { relations } from "drizzle-orm"
import * as t from "drizzle-orm/sqlite-core"

export const users = drizzleSilk(
  t.sqliteTable("users", {
    id: t.int().primaryKey({ autoIncrement: true }),
    name: t.text().notNull(),
    phone: t.text().notNull().unique(),
  })
)

export const usersRelations = relations(users, ({ many }) => ({
  cats: many(cats),
}))

export const cats = drizzleSilk(
  t.sqliteTable("cats", {
    id: t.integer().primaryKey({ autoIncrement: true }),
    name: t.text().notNull(),
    birthday: t.integer({ mode: "timestamp" }).notNull(),
    ownerId: t
      .integer()
      .notNull()
      .references(() => users.id),
  })
)

export const catsRelations = relations(cats, ({ one }) => ({
  owner: one(users, {
    fields: [cats.ownerId],
    references: [users.id],
  }),
}))

Initialize the Database

We need to create a configuration file:

// drizzle.config.ts
import "dotenv/config"
import { defineConfig } from "drizzle-kit"

export default defineConfig({
  out: "./drizzle",
  schema: "./src/schema/index.ts",
  dialect: "sqlite",
  dbCredentials: {
    url: process.env.DB_FILE_NAME ?? "file:local.db",
  },
})

Then we run the drizzle-kit push command to create the defined tables in the database:

npx drizzle-kit push

Use the Database

To use the database in the application, we need to create a database instance:

// src/providers/index.ts
import { drizzle } from "drizzle-orm/libsql"
import * as schema from "src/schema"

export const db = drizzle(process.env.DB_FILE_NAME ?? "file:local.db", {
  schema,
})

Resolvers

Now, we can use the database in resolvers. We'll create a user resolver and add the following operations:

usersByName: Find users by name
userByPhone: Find users by phone number
createUser: Create a user

After completing the user resolver, we also need to add it to the resolvers in the src/resolvers/index.ts file:

// src/resolvers/user.ts
import { mutation, query, resolver } from "@gqloom/core"
import { eq } from "drizzle-orm"
import { db } from "src/providers"
import { users } from "src/schema"
import * as z from "zod"

export const userResolver = resolver.of(users, {
  usersByName: query(users.$list())
    .input({ name: z.string() })
    .resolve(({ name }) => {
      return db.query.users.findMany({
        where: eq(users.name, name),
      })
    }),

  userByPhone: query(users.$nullable())
    .input({ phone: z.string() })
    .resolve(({ phone }) => {
      return db.query.users.findFirst({
        where: eq(users.phone, phone),
      })
    }),

  createUser: mutation(users)
    .input({
      data: z.object({
        name: z.string(),
        phone: z.string(),
      }),
    })
    .resolve(async ({ data }) => {
      const [user] = await db.insert(users).values(data).returning()
      return user
    }),
})

// src/resolvers/index.ts
import { query, resolver } from "@gqloom/core"
import { userResolver } from "src/resolvers/user"
import * as z from "zod"

const helloResolver = resolver({
  hello: query(z.string())
    .input({
      name: z
        .string()
        .nullish()
        .transform((x) => x ?? "World"),
    })
    .resolve(({ name }) => `Hello ${name}!`),
})

export const resolvers = [helloResolver, userResolver]

Great! Now let's try it in the playground:

GraphQL Mutation:

mutation {
  createUser(data: {name: "Bob", phone: "001"}) {
    id
    name
    phone
  }
}

Response:

{
  "data": {
    "createUser": {
      "id": 1,
      "name": "Bob",
      "phone": "001"
    }
  }
}

Let's continue to try retrieving the user we just created:

GraphQL Query:

{
  usersByName(name: "Bob") {
    id
    name
    phone
  }
}

Response:

{
  "data": {
    "usersByName": [
      {
        "id": 1,
        "name": "Bob",
        "phone": "001"
      }
    ]
  }
}

Current User Context

First, let's add the asyncContextProvider middleware to enable asynchronous context:

// src/index.ts
import { createServer } from "node:http"
import { weave } from "@gqloom/core"
import { asyncContextProvider } from "@gqloom/core/context"
import { ZodWeaver } from "@gqloom/zod"
import { createYoga } from "graphql-yoga"
import { resolvers } from "src/resolvers"

const schema = weave(asyncContextProvider, ZodWeaver, ...resolvers)

const yoga = createYoga({ schema })
createServer(yoga).listen(4000, () => {
  console.info("Server is running on http://localhost:4000/graphql")
})

Next, let's try adding a simple login function and add a query operation to the user resolver:

mine: Return current user information

To implement this query, we first need to have a login function. Let's write a simple one:

// src/contexts/index.ts
import { createMemoization, useContext } from "@gqloom/core/context"
import { eq } from "drizzle-orm"
import { GraphQLError } from "graphql"
import type { YogaInitialContext } from "graphql-yoga"
import { db } from "src/providers"
import { users } from "src/schema"

export const useCurrentUser = createMemoization(async () => {
  const phone =
    useContext<YogaInitialContext>().request.headers.get("authorization")
  if (phone == null) throw new GraphQLError("Unauthorized")

  const user = await db.query.users.findFirst({ where: eq(users.phone, phone) })
  if (user == null) throw new GraphQLError("Unauthorized")
  return user
})

In the above code, we created a context function for getting the current user, which will return the information of the current user. We use createMemoization() to memoize this function, which ensures that this function is only executed once within the same request to avoid unnecessary database queries.

We used useContext() to get the context provided by Yoga, and obtained the user's phone number from the request header, and found the user according to the phone number. If the user does not exist, a GraphQLError will be thrown.

Now, we add the new query operation in the resolver:

// src/resolvers/user.ts
import { mutation, query, resolver } from "@gqloom/core"
import { eq } from "drizzle-orm"
import { useCurrentUser } from "src/contexts"
import { db } from "src/providers"
import { users } from "src/schema"
import * as z from "zod"

export const userResolver = resolver.of(users, {
  mine: query(users).resolve(() => useCurrentUser()),

  usersByName: query(users.$list())
    .input({ name: z.string() })
    .resolve(({ name }) => {
      return db.query.users.findMany({
        where: eq(users.name, name),
      })
    }),

  userByPhone: query(users.$nullable())
    .input({ phone: z.string() })
    .resolve(({ phone }) => {
      return db.query.users.findFirst({
        where: eq(users.phone, phone),
      })
    }),

  createUser: mutation(users)
    .input({
      data: z.object({
        name: z.string(),
        phone: z.string(),
      }),
    })
    .resolve(async ({ data }) => {
      const [user] = await db.insert(users).values(data).returning()
      return user
    }),
})

If we directly call this new query in the playground, the application will give us an unauthorized error:

GraphQL Query:

{
  mine {
    id
    name
    phone
  }
}

Response:

{
  "errors": [
    {
      "message": "Unauthorized",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "mine"
      ]
    }
  ],
  "data": null
}

Open the Headers at the bottom of the playground and add the authorization field to the request header. Here we use the phone number of Bob created in the previous step, so we are logged in as Bob:

Headers:

{
  "authorization": "001"
}

GraphQL Query:

{
  mine {
    id
    name
    phone
  }
}

Response:

{
  "data": {
    "mine": {
      "id": 1,
      "name": "Bob",
      "phone": "001"
    }
  }
}

Resolver Factory

Next, we'll add business logic related to cats.

We use the resolver factory to quickly create interfaces:

// src/resolvers/cat.ts
import { field, resolver } from "@gqloom/core"
import { drizzleResolverFactory } from "@gqloom/drizzle"
import { db } from "src/providers"
import { cats } from "src/schema"
import * as z from "zod"

const catResolverFactory = drizzleResolverFactory(db, cats)

export const catResolver = resolver.of(cats, {
  cats: catResolverFactory.selectArrayQuery(),

  age: field(z.number())
    .derivedFrom("birthday")
    .input({
      currentYear: z.number().int().nullish().transform((x) => x ?? new Date().getFullYear()),
    })
    .resolve((cat, { currentYear }) => {
      return currentYear - cat.birthday.getFullYear()
    }),
})

// src/resolvers/index.ts
import { query, resolver } from "@gqloom/core"
import { catResolver } from "src/resolvers/cat"
import { userResolver } from "src/resolvers/user"
import * as z from "zod"

const helloResolver = resolver({
  hello: query(z.string())
    .input({
      name: z
        .string()
        .nullish()
        .transform((x) => x ?? "World"),
    })
    .resolve(({ name }) => `Hello ${name}!`),
})

export const resolvers = [helloResolver, userResolver, catResolver]

In the above code, we used drizzleResolverFactory() to create catResolverFactory for quickly building resolvers.

We added a query that uses catResolverFactory to select data and named it cats. This query will provide full query operations on the cats table.

In addition, we also added an additional age field for cats to get the age of the cats.

Next, let's try adding a createCat mutation. We want only logged-in users to access this interface, and the created cats will belong to the current user:

// src/resolvers/cat.ts (partial code)
createCats: catResolverFactory.insertArrayMutation().input(
  z.object({
    values: z.array(
      z.object({
        name: z.string(),
        birthday: z.string().transform((x) => new Date(x)),
      }).transform(async ({ name, birthday }) => ({
        name,
        birthday,
        ownerId: (await useCurrentUser()).id,
      }))
    ),
  })
),

In the above code, we used catResolverFactory to create a mutation that adds more data to the cats table, and we overwrote the input of this mutation. When validating the input, we used useCurrentUser() to get the ID of the currently logged-in user and pass it as the value of ownerId to the cats table.

Now let's try adding a few cats in the playground:

GraphQL Mutation:

mutation {
  createCats(data: {values: [{name: "Whiskers", birthday: "2020-01-01"}, {name: "Whiskers", birthday: "2020-01-01"}]}) {
    id
    name
    age
  }
}

Headers:

{
  "authorization": "001"
}

Response:

{
  "data": {
    "createCats": [
      {
        "id": 1,
        "name": "Mittens",
        "age": 4
      },
      {
        "id": 2,
        "name": "Fluffy",
        "age": 3
      }
    ]
  }
}

Let's use the cats query to confirm the data in the database again:

GraphQL Query:

{
  cats {
    id
    name   
    age
  }
}

Response:

{
  "data": {
    "cats": [
      {
        "id": 1,
        "name": "Mittens",
        "age": 4
      },
      {
        "id": 2,
        "name": "Fluffy",
        "age": 3
      }
    ]
  }
}

Associated Objects

We want to be able to get the owner of a cat when querying the cat, and also be able to get all the cats of a user when querying the user.

This is very easy to achieve in GraphQL.

Let's add an additional owner field to cats and an additional cats field to users:

// src/resolvers/cat.ts
import { field, resolver } from "@gqloom/core"
import { drizzleResolverFactory } from "@gqloom/drizzle"
import { useCurrentUser } from "src/contexts"
import { db } from "src/providers"
import { cats } from "src/schema"
import * as z from "zod"

const catResolverFactory = drizzleResolverFactory(db, cats)

export const catResolver = resolver.of(cats, {
  cats: catResolverFactory.selectArrayQuery(),

  age: field(z.number())
    .derivedFrom("birthday")
    .input({
      currentYear: z.number().int().nullish().transform((x) => x ?? new Date().getFullYear()),
    })
    .resolve((cat, { currentYear }) => {
      return currentYear - cat.birthday.getFullYear()
    }),

  owner: catResolverFactory.relationField("owner"),

  createCats: catResolverFactory.insertArrayMutation().input(
    z.object({
      values: z.array(
        z.object({
          name: z.string(),
          birthday: z.string().transform((x) => new Date(x)),
        }).transform(async ({ name, birthday }) => ({
          name,
          birthday,
          ownerId: (await useCurrentUser()).id,
        }))
      ),
    })
  ),
})

// src/resolvers/user.ts
import { mutation, query, resolver } from "@gqloom/core"
import { drizzleResolverFactory } from "@gqloom/drizzle"
import { eq } from "drizzle-orm"
import { useCurrentUser } from "src/contexts"
import { db } from "src/providers"
import { users } from "src/schema"
import * as z from "zod"

const userResolverFactory = drizzleResolverFactory(db, users)

export const userResolver = resolver.of(users, {
  cats: userResolverFactory.relationField("cats"),

  mine: query(users).resolve(() => useCurrentUser()),

  usersByName: query(users.$list())
    .input({ name: z.string() })
    .resolve(({ name }) => {
      return db.query.users.findMany({
        where: eq(users.name, name),
      })
    }),

  userByPhone: query(users.$nullable())
    .input({ phone: z.string() })
    .resolve(({ phone }) => {
      return db.query.users.findFirst({
        where: eq(users.phone, phone),
      })
    }),

  createUser: mutation(users)
    .input({
      data: z.object({
        name: z.string(),
        phone: z.string(),
      }),
    })
    .resolve(async ({ data }) => {
      const [user] = await db.insert(users).values(data).returning()
      return user
    }),
})

In the above code, we used the resolver factory to create the owner field for cats; similarly, we also created the cats field for users.

Behind the scenes, the relationship fields created by the resolver factory will use DataLoader to query from the database to avoid the N+1 problem.

Let's try querying the owner of a cat in the playground:

GraphQL Query:

{
  cats {
    id
    name
    age
    owner {
      id
      name
      phone
    }
  }
}

Response:

{
  "data": {
    "cats": [
      {
        "id": 1,
        "name": "Mittens",
        "age": 4,
        "owner": {
          "id": 1,
          "name": "Bob",
          "phone": "001"
        }
      },
      {
        "id": 2,
        "name": "Fluffy",
        "age": 3,
        "owner": {
          "id": 1,
          "name": "Bob",
          "phone": "001"
        }
      }
    ]
  }
}

Let's try querying the cats of the current user:

GraphQL Query:

{
  mine {
    name
    cats {
      id
      name
      age
    }
  }
}

Headers:

{
  "authorization": "001"
}

Response:

{
  "data": {
    "mine": {
      "name": "Bob",
      "cats": [
        {
          "id": 1,
          "name": "Mittens",
          "age": 4
        },
        {
          "id": 2,
          "name": "Fluffy",
          "age": 3
        }
      ]
    }
  }
}

Conclusion

In this article, we created a simple GraphQL server-side application. We used the following tools:

Zod: Used to define and validate inputs
Drizzle: Used to operate the database, and directly use the Drizzle table as the GraphQL output type
Context: Used to share data between different parts of the program, which is very useful for scenarios such as implementing login and tracking logs
Resolver factory: Used to quickly create resolvers and operations
GraphQL Yoga: Used to create a GraphQL HTTP service and provides a GraphiQL playground

Our application has implemented the functions of adding and querying users and cats, but due to space limitations, the update and delete functions have not been implemented. They can be quickly added through the resolver factory.

Next Steps

Check out the core concepts of GQLoom: Silk, Resolver, Weave
Learn about common functions: Context, DataLoader, Middleware
Add a GraphQL client to the front-end project: gql.tada, Urql, Apollo Client, TanStack Query, Graffle