Object types and input types in NestJS - Deep Dive

Overview - Object types and input types

What is it?

In NestJS, object types and input types are special classes used to define the shape of data for GraphQL APIs. Object types describe the structure of data that the API sends back to clients, while input types define the shape of data that clients send to the API. They help NestJS understand what fields exist, their types, and how to validate and transform data automatically.

Why it matters

Without object and input types, APIs would not have clear rules about what data they accept or return, leading to confusion and errors. These types ensure data is consistent, validated, and easy to work with, making APIs reliable and easier to maintain. They also enable powerful developer tools like auto-generated documentation and type checking.

Where it fits

Before learning object and input types, you should understand basic TypeScript classes and decorators, and have a basic grasp of GraphQL concepts. After mastering these types, you can learn advanced GraphQL features in NestJS like resolvers, middleware, and schema stitching.

Mental Model

Core Idea

Object types define the data shape sent out, input types define the data shape accepted in, both using classes to describe and validate GraphQL data.

Think of it like...

Think of object types as the menu a restaurant offers to customers (what they get), and input types as the order form customers fill out to request their meal (what they send). Both need clear formats so the kitchen and customers understand each other perfectly.

┌───────────────┐       ┌───────────────┐
│  Input Types  │──────▶│  Resolver     │
│ (Client Data) │       │ (Handles Data)│
└───────────────┘       └───────────────┘
                             │
                             ▼
                      ┌───────────────┐
                      │ Object Types  │
                      │ (API Output)  │
                      └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Object Types Basics

Concept: Object types define the structure of data returned by GraphQL queries or mutations.

In NestJS, you create an object type by defining a class and decorating it with @ObjectType(). Each property you want to expose is decorated with @Field() specifying its type. This tells GraphQL what fields are available and their types. Example: import { ObjectType, Field, Int } from '@nestjs/graphql'; @ObjectType() export class User { @Field(type => Int) id: number; @Field() name: string; } This defines a User object with an id and name that GraphQL can return.

Result

GraphQL knows the User type has an id (number) and name (string) fields to send back to clients.

Understanding object types is key because they form the blueprint of data your API sends, ensuring clients know exactly what to expect.

2

Foundation

Introduction to Input Types

Concept: Input types define the shape of data clients send to the API, such as arguments for mutations.

Input types are similar to object types but are used for incoming data. You create them by defining a class and decorating it with @InputType(). Fields are decorated with @Field() to specify their types. Example: import { InputType, Field } from '@nestjs/graphql'; @InputType() export class CreateUserInput { @Field() name: string; } This input type tells GraphQL what data is expected when creating a user.

Result

GraphQL expects clients to send a name field when calling a mutation that uses CreateUserInput.

Input types help validate and structure incoming data, preventing errors and making APIs safer and clearer.

3

Intermediate

Using Object and Input Types Together

🤔Before reading on: Do you think object types and input types can be the same class or must they always be separate? Commit to your answer.

Concept: Object types and input types often look similar but serve different roles and usually require separate classes.

While object and input types may share fields, they are distinct because input types can have different validation rules or omit fields like IDs. NestJS requires separate classes decorated with @ObjectType() and @InputType() respectively. Example: @ObjectType() class User { id: number; name: string; } @InputType() class CreateUserInput { name: string; } This separation ensures clear API contracts for input and output.

Result

Clear separation prevents confusion and errors when handling data in resolvers.

Knowing that input and object types are separate helps avoid bugs and clarifies API design.

4

Intermediate

Field Types and Nullable Fields

🤔Before reading on: Do you think all fields in object and input types must always have values? Commit to yes or no.

Concept: Fields can be marked as nullable to indicate they are optional in input or output data.

By default, fields are required. You can make a field optional by passing { nullable: true } to the @Field() decorator. Example: @Field({ nullable: true }) email?: string; This means the email field can be missing or null in the data. Nullable fields are useful for partial updates or optional inputs.

Result

GraphQL schema reflects which fields are optional, improving flexibility and clarity.

Understanding nullable fields prevents errors when clients omit optional data and helps design flexible APIs.

5

Intermediate

Nested Object and Input Types

Concept: Object and input types can contain other object or input types as fields to model complex data.

You can nest types by referencing other classes in @Field() decorators. Example: @ObjectType() class Profile { @Field() bio: string; } @ObjectType() class User { @Field() name: string; @Field(type => Profile) profile: Profile; } This models a user with a nested profile object.

Result

GraphQL schema supports complex data structures with nested types.

Knowing how to nest types allows modeling real-world data accurately and cleanly.

6

Advanced

Validation and Transformation with Input Types

🤔Before reading on: Do you think input types automatically validate data or do you need extra setup? Commit to your answer.

Concept: Input types can integrate with validation libraries to automatically check incoming data correctness.

NestJS supports class-validator and class-transformer libraries to validate input types. Example: import { IsEmail, Length } from 'class-validator'; @InputType() class RegisterUserInput { @Field() @Length(3, 20) username: string; @Field() @IsEmail() email: string; } When a mutation receives this input, NestJS validates fields automatically and returns errors if invalid.

Result

Invalid input data is caught early, improving API robustness and user experience.

Integrating validation with input types prevents bad data from reaching business logic, reducing bugs and security risks.

7

Expert

Custom Scalars and Advanced Type Mapping

🤔Before reading on: Can you use any TypeScript type directly in GraphQL fields without extra work? Commit to yes or no.

Concept: GraphQL supports custom scalar types for special data like dates or JSON, which require custom mapping in NestJS object and input types.

By default, GraphQL supports basic types like String, Int, Boolean. For others like Date, you define custom scalars. Example: import { Scalar, CustomScalar } from '@nestjs/graphql'; import { Kind } from 'graphql'; @Scalar('Date') export class DateScalar implements CustomScalar { parseValue(value: string): Date { return new Date(value); } serialize(value: Date): string { return value.toISOString(); } parseLiteral(ast: any): Date { if (ast.kind === Kind.STRING) { return new Date(ast.value); } return null; } } Then use @Field(type => DateScalar) in your types. This allows precise control over complex data types.

Result

Your API can handle complex data types correctly and consistently.

Understanding custom scalars unlocks powerful data handling beyond basic types, essential for real-world APIs.

Under the Hood

NestJS uses TypeScript classes decorated with special decorators to generate GraphQL schema definitions automatically. At runtime, these decorators add metadata about fields and types. The GraphQL module reads this metadata to build the schema, which defines what queries and mutations exist and their input/output types. Input types are used to validate and transform incoming data before it reaches resolver functions. Object types define the shape of data sent back to clients, ensuring type safety and consistency.

Why designed this way?

This design leverages TypeScript's strong typing and decorators to keep schema definitions close to code, reducing duplication and errors. It avoids manual schema writing, which is error-prone and hard to maintain. Using classes aligns with object-oriented programming familiar to many developers, making the learning curve gentler. Alternatives like schema-first require writing GraphQL schema language separately, which can cause mismatches and extra maintenance.

┌───────────────┐  Decorators add metadata  ┌───────────────┐
│ TypeScript    │──────────────────────────▶│ GraphQL       │
│ Classes       │                           │ Schema Builder│
└───────────────┘                           └───────────────┘
        │                                            │
        │ Incoming data validated by input types     │
        │                                            │
        ▼                                            ▼
┌───────────────┐                           ┌───────────────┐
│ Resolver      │◀──────────────────────────│ Client       │
│ Functions     │     Data shaped by object │ (Query/Mutation)
└───────────────┘     types sent back       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can you use the same class for both input and object types without issues? Commit to yes or no.

Common Belief: Many believe you can use one class decorated with @ObjectType() for both input and output data.

Reality: Input and object types must be separate classes decorated with @InputType() and @ObjectType() respectively to avoid schema conflicts and validation issues.

Why it matters: Using the same class causes schema errors and runtime bugs, making APIs unreliable and hard to debug.

Quick: Do you think all fields in input types are optional by default? Commit to yes or no.

Common Belief: Some think input type fields are optional unless explicitly marked required.

Reality: By default, fields are required unless marked with { nullable: true } in @Field().

Why it matters: Assuming fields are optional can cause unexpected validation errors and client confusion.

Quick: Is it true that NestJS automatically validates input types without any extra setup? Commit to yes or no.

Common Belief: Many believe input types validate data automatically without additional libraries.

Reality: Validation requires integrating class-validator and enabling validation pipes explicitly.

Why it matters: Without proper setup, invalid data can reach business logic, causing bugs or security issues.

Quick: Can you use any TypeScript type directly in GraphQL fields without custom scalars? Commit to yes or no.

Common Belief: Some think all TypeScript types map automatically to GraphQL types.

Reality: Only basic types map automatically; complex types like Date need custom scalars.

Why it matters: Ignoring this leads to schema errors or incorrect data serialization.

Expert Zone

1

Input types can extend other input types to reuse fields, but care is needed to avoid circular dependencies.

2

Using partial types with @InputType({ isAbstract: true }) allows creating flexible input shapes for updates.

3

Custom scalars require careful implementation of parse and serialize methods to avoid subtle bugs in data handling.

When NOT to use

Avoid using object and input types for non-GraphQL data handling or REST APIs; use DTOs or plain classes instead. For very dynamic schemas, schema-first approach might be better. Also, if you need runtime schema changes, code-first types are less flexible.

Production Patterns

In production, teams separate input and object types clearly, use validation pipes globally, and implement custom scalars for dates and JSON. They also use abstract input types for partial updates and compose types with inheritance to reduce duplication.

Connections

TypeScript Decorators

Object and input types rely on decorators to add metadata for schema generation.

Understanding decorators helps grasp how NestJS links class definitions to GraphQL schema automatically.

Data Validation

Input types integrate with validation libraries to ensure data correctness before processing.

Knowing validation principles clarifies why input types are crucial for safe API design.

Database Schema Design

Object types often mirror database entities, connecting API data shapes to stored data.

Understanding database schemas helps design object types that align well with backend data models.

Common Pitfalls

#1 Using the same class for both input and output types.

Wrong approach:

import { ObjectType, Field } from '@nestjs/graphql';

@ObjectType()
export class User {
@Field()
id: number;

@Field()
name: string;
}

// Used as input type too, causing schema conflicts

Correct approach:

import { ObjectType, Field, InputType } from '@nestjs/graphql';

@ObjectType()
export class User {
@Field()
id: number;

@Field()
name: string;
}

@InputType()
export class CreateUserInput {
@Field()
name: string;
}

Root cause:

Confusing input and output roles leads to schema errors and validation problems.

#2 Not marking optional fields as nullable in input types.

Wrong approach:

@InputType()
class UpdateUserInput {
@Field()
name?: string; // Missing nullable: true
}

Correct approach:

@InputType()
class UpdateUserInput {
@Field({ nullable: true })
name?: string;
}

Root cause:

Assuming optional TypeScript fields are automatically nullable in GraphQL schema.

#3 Skipping validation setup for input types.

Wrong approach:

@InputType()
class RegisterInput {
@Field()
email: string;
}
// No validation decorators or pipes

Correct approach:

import { IsEmail } from 'class-validator';

@InputType()
class RegisterInput {
@Field()
@IsEmail()
email: string;
}
// Validation pipe enabled in main.ts

Root cause:

Believing NestJS validates inputs automatically without explicit validation integration.

Key Takeaways

Object types define the shape of data your API sends back, while input types define the shape of data your API accepts.

You must use separate classes for object and input types, each decorated appropriately, to avoid schema conflicts.

Nullable fields allow optional data and must be explicitly marked to prevent validation errors.

Input types can integrate with validation libraries to automatically check incoming data, improving API safety.

Custom scalars extend GraphQL's basic types to handle complex data like dates, requiring careful implementation.