Input Object Types

Input objects are used to represent the input arguments of a field. They are similar to object types, but they are used to represent inputs instead of output fields. Input object types use g.arg similar to how args are defined on output fields rather than using the g.field function like on output object types.

schema.ts

const UserCreateInput = g.inputObject({
  name: "UserCreateInput",
  fields: {
    name: g.arg({ type: g.nonNull(g.String) }),
    email: g.arg({ type: g.nonNull(g.String) }),
  },
});

const Mutation = g.object()({
  name: "Mutation",
  fields: {
    createUser: g.field({
      type: User,
      args: {
        input: g.arg({ type: g.nonNull(UserCreateInput) }),
      },
      resolve: (source, args, context) => {
        return context.createUser(args.input);
input: {
    readonly name: string;
    readonly email: string;
}
      },
    }),
  },
});

schema.graphql

type Mutation {
  createUser(input: UserCreateInput!): User
}

type User {
  id: ID!
  name: String!
  email: String!
}

input UserCreateInput {
  name: String!
  email: String!
}

Circular Types

While circular input object types are less common than circular Object Types, they can still occur. Just like with circular object types, we need to start by making fields a function:

schema.ts

const UserCreateInput = g.inputObject({
Error ts(7022)  ― 'UserCreateInput' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
  name: "UserCreateInput",
  fields: () => ({
Error ts(7023)  ― 'fields' implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.
    name: g.arg({ type: g.nonNull(g.String) }),
    email: g.arg({ type: g.nonNull(g.String) }),
    friends: g.arg({ type: g.list(g.nonNull(UserCreateInput)) }),
  }),
});

schema.graphql

input UserCreateInput {
  name: String!
  email: String!
  friends: [UserCreateInput!]
}

To resolve TypeScript’s errors about circularity though, we unfortunately can’t use the g type like we did with object types. Instead, we need to use the GInputObjectType type and we also need to essentially duplicate the fields definition in the types

schema.ts

import type {
  GArg,
  GNonNull,
  GList,
  GInputObjectType,
} from "@graphql-ts/schema";

type UserCreateInput = GInputObjectType<{
  // you can use the G* types from @graphql-ts/schema to define the fields
  name: GArg<GNonNull<typeof g.String>>;
  // or you can use the g type and g.* functions
  email: g<typeof g.arg<g<typeof g.nonNull<typeof g.String>>>>;
  friends: GArg<GList<GNonNull<UserCreateInput>>>;
}>;

const UserCreateInput: UserCreateInput = g.inputObject({
  name: "UserCreateInput",
  fields: () => ({
    name: g.arg({ type: g.nonNull(g.String) }),
    email: g.arg({ type: g.nonNull(g.String) }),
    friends: g.arg({ type: g.list(g.nonNull(UserCreateInput)) }),
  }),
});

schema.graphql

input UserCreateInput {
  name: String!
  email: String!
  friends: [UserCreateInput!]
}

Since most fields in input objects won’t be circular, you can also extract out the non-circular fields and use typeof instead of duplicating the fields:

schema.ts

import type {
  GArg,
  GNonNull,
  GList,
  GInputObjectType,
} from "@graphql-ts/schema";

const userCreateInputFields = {
  name: g.arg({ type: g.nonNull(g.String) }),
  email: g.arg({ type: g.nonNull(g.String) }),
};

type UserCreateInput = GInputObjectType<
  typeof userCreateInputFields & {
    friends: GArg<GList<GNonNull<UserCreateInput>>>;
  }
>;

const UserCreateInput: UserCreateInput = g.inputObject({
  name: "UserCreateInput",
  fields: () => ({
    ...userCreateInputFields,
    friends: g.arg({ type: g.list(g.nonNull(UserCreateInput)) }),
  }),
});

schema.graphql

input UserCreateInput {
  name: String!
  email: String!
  friends: [UserCreateInput!]
}

Nullability & Default Values

Input objects can also have default values for their arguments. Default values are used when the argument is not provided in the input object. Default values can be provided using the defaultValue property in the g.arg function. We’re going to demonstrate by using args on a field rather than on an input object type but the same concept applies to input object types.

To start with, since all types are nullable in GraphQL by default, let’s look at what the type of a nullable type is:

schema.ts

const field = g.field({
  type: g.String,
  args: {
    name: g.arg({ type: g.String }),
  },
  resolve(_, args) {
args: {
    readonly name: string | null | undefined;
}
    return args.name;
  },
});

schema.graphql

type Query {
  field(name: String): String
}

For the String scalar, the type is string | null | undefined.

This is because for a nullable input type, there are three possible options for a consumer of a GraphQL API:

query {
  withoutName: field # represented as `undefined` in resolvers
  withNull: field(name: null)
  withValue: field(name: "string")
}

For a nullable input type, adding a defaultValue will remove the undefined option but note that it will not remove null.

g.field({
  type: g.String,
  args: {
    name: g.arg({ type: g.String, defaultValue: "name" }),
  },
  resolve(_, args) {
args: {
    readonly name: string | null;
}
    return args.name;
  },
});

For non-nullable input types, adding a defaultValue doesn’t affect the type received by the resolve function, it just allows the consumer to not provide the argument in which case the default value will be used:

g.field({
  type: g.String,
  args: {
    name: g.arg({ type: g.nonNull(g.String), defaultValue: "name" }),
  },
  resolve(_, args) {
args: {
    readonly name: string;
}
    return args.name;
  },
});

One Of

To express an input object where a consumer must provide exactly one of the keys, you can use isOneOf. Note all the fields must be nullable when defining the type but in your resolver, exactly one key will be provided and it will be non-null and no other keys will be provided.

const UserCreateInput = g.inputObject({
  name: "UserSearchInput",
  isOneOf: true,
  fields: {
    id: g.arg({ type: g.ID }),
    email: g.arg({ type: g.String }),
    name: g.arg({ type: g.String }),
  },
});

const search = g.field({
  type: User,
  args: {
    input: g.arg({ type: g.nonNull(UserCreateInput) }),
  },
  resolve(_, args) {
    console.log(args.input);
input: {
    readonly name: string;
    readonly id?: never;
    readonly email?: never;
} | {
    readonly id: string;
    readonly name?: never;
    readonly email?: never;
} | {
    readonly email: string;
    readonly name?: never;
    readonly id?: never;
}
    return null;
  },
});