Schemas ​

In GraphQL, a schema is a collection of types that define the structure of data that can be queried or mutated in a GraphQL API. The schema acts as a contract between the client and server, specifying what types of data can be queried, what types of mutations can be performed, and how the data will be structured and returned.

Constructors ​

Create new Garph schema

import { GarphSchema } from 'garph'

const g = new GarphSchema()

import { GarphSchema } from 'garph'

const g = new GarphSchema()

Create new Garph schema with types

import { GarphSchema } from 'garph'

const g = new GarphSchema({ types: [type1, type2, type3] })

import { GarphSchema } from 'garph'

const g = new GarphSchema({ types: [type1, type2, type3] })

Types ​

Object Type ​

An object type is a type in GraphQL that represents an object with a set of named fields and their corresponding values. Object types are used to define the structure and shape of data that can be queried and retrieved from a GraphQL API. They can also be used as inputs for mutations.

g.type('User', {
  name: g.string()
})

g.type('User', {
  name: g.string()
})

GraphQL Type:

type User {
  name: String!
}

type User {
  name: String!
}

String ​

A string is a type in GraphQL that represents a sequence of characters, such as text or a message. It is used to represent textual data.

g.string()

g.string()

GraphQL Type:

String!

String!

Int ​

An integer is a type in GraphQL that represents a whole number without any decimal points. It is used to represent numeric data.

g.int()

g.int()

GraphQL Type:

Int!

Int!

Float ​

A float is a type in GraphQL that represents a floating-point number with decimal points. It is used to represent numeric data that may have decimal points.

g.float()

g.float()

GraphQL Type:

Float!

Float!

Boolean ​

A boolean is a type in GraphQL that represents a value of either true or false. It is used to represent logical data.

g.boolean()

g.boolean()

GraphQL Type:

Boolean!

Boolean!

ID ​

An ID is a type in GraphQL that represents a unique identifier, typically used to identify a specific object or record in a database. It is a string that can be serialized and deserialized.

g.id()

g.id()

GraphQL Type:

ID!

ID!

Enum ​

An enum is a type in GraphQL that represents a set of predefined values. It is used to restrict the possible values of a field or an argument to a specific set of values.

Plain:

g.enumType('Fruits', ['Apples', 'Oranges'] as const)

g.enumType('Fruits', ['Apples', 'Oranges'] as const)

(We need as const for proper type inference)

From TypeScript Enum:

enum Fruits {
  Apples,
  Oranges
}

g.enumType('Fruits', Fruits)

enum Fruits {
  Apples,
  Oranges
}

g.enumType('Fruits', Fruits)

GraphQL Type:

enum Fruits {
  Apples
  Oranges
}

enum Fruits {
  Apples
  Oranges
}

Union ​

A union is a type in GraphQL that represents a set of types. It is used to represent a type that can be one of several possible types.

g.unionType('Name', { a, b })

g.unionType('Name', { a, b })

GraphQL Type:

union Name = A | B

union Name = A | B

Ref ​

Reference:

const name = g.type('Name', {
  greet: g.ref(otherType)
})

const name = g.type('Name', {
  greet: g.ref(otherType)
})

Circular Reference:

const name = g.type('Name', {
  greet: g.ref(() => name)
})

const name = g.type('Name', {
  greet: g.ref(() => name)
})

Interface ​

An interface is a type in GraphQL that defines a set of fields that can be implemented by other object types. It is used to define a common set of fields and their corresponding types that can be used by multiple object types.

g.interface('Name', {
  greet: g.string()
})

g.interface('Name', {
  greet: g.string()
})

GraphQL Type:

interface Name {
  greet: String!
}

interface Name {
  greet: String!
}

Implementing an interface

const test = g.type('Test', {}).implements(interface)

const test = g.type('Test', {}).implements(interface)

Or a set of interfaces:

const test = g.type('Test', {}).implements([interface, interface])

const test = g.type('Test', {}).implements([interface, interface])

Note: Inherited fields will be added to the schema automatically, you don't need to re-specify them

Input ​

An input type is a type in GraphQL that represents the input data for a mutation or a query argument. It is used to define the shape and structure of the data that can be passed as input to a GraphQL API.

g.inputType('Name', {
  greet: g.string()
})

g.inputType('Name', {
  greet: g.string()
})

GraphQL Type:

input Name {
  greet: String!
}

input Name {
  greet: String!
}

Scalar ​

Custom scalars can be useful for handling specific data types that are not natively supported by GraphQL or you want a version of an existing type that does some validation. For example, you might define a custom scalar for handling dates:

g.scalarType<Date, number>('Date', {
  serialize: (value) => value.getTime(),
  parseValue: (value) => new Date(value)
})

g.scalarType<Date, number>('Date', {
  serialize: (value) => value.getTime(),
  parseValue: (value) => new Date(value)
})

GraphQL Type:

scalar Date

scalar Date

Directive ​

A directive is a special kind of declaration in GraphQL that can be used to modify the behavior of a query or a schema. It is used to annotate parts of a query with metadata or to specify additional constraints on the execution of a query.

Currently not supported.

See: https://github.com/stepci/garph/issues/40

Relay Types ​

Node ​

g.node('User', {
  name: g.string()
})

g.node('User', {
  name: g.string()
})

GraphQL Type:

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

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

Edge ​

g.edge('UserEdge', g.ref(userNode))

g.edge('UserEdge', g.ref(userNode))

GraphQL Type:

type UserEdge {
  cursor: String!
  node: User
}

type UserEdge {
  cursor: String!
  node: User
}

Connection ​

g.connection('UserConnection', g.ref(userEdge))

g.connection('UserConnection', g.ref(userEdge))

GraphQL Type:

type UserConnection {
  edges: [UserEdge]
  pageInfo: PageInfo!
}

type UserConnection {
  edges: [UserEdge]
  pageInfo: PageInfo!
}

PageInfo ​

g.pageInfoType

g.pageInfoType

GraphQL Type:

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

PageInfoArgs ​

g.pageInfoArgs

g.pageInfoArgs

GraphQL Type:

(first: Int, last: Int, before: ID, after: ID)

(first: Int, last: Int, before: ID, after: ID)

Modifiers ​

Modifiers can be chained together to produce desired type

Args ​

Used to pass additional parameters to a query or a mutation. They can be used to filter, sort, or modify the data returned by a query

g.type('Query', {
  greet: g.string().args({ name: g.string() })
})

g.type('Query', {
  greet: g.string().args({ name: g.string() })
})

GraphQL Type:

type Query {
  greet(name: String!): String!
}

type Query {
  greet(name: String!): String!
}

Implements ​

Define a set of interfaces that an object type implements

const test = g.type('Test', {}).implements(interface)

const test = g.type('Test', {}).implements(interface)

Or array of interfaces:

const test = g.type('Test', {}).implements([interface, interface])

const test = g.type('Test', {}).implements([interface, interface])

GraphQL Type:

type Test implements interface {
  ...
}

type Test implements interface {
  ...
}

Extend ​

Define a set of properties that extends an input, interface or object type

const name = {
  name: g.string()
}

const test = g.type('Test', {}).extend(name)

const name = {
  name: g.string()
}

const test = g.type('Test', {}).extend(name)

Or array of properties:

const test = g.type('Test', {}).extend([firstname, lastname])

const test = g.type('Test', {}).extend([firstname, lastname])

GraphQL Type:

type Test {
  name: String!
}

type Test {
  name: String!
}

List ​

Turns a particular type into a list

g.string().list()

g.string().list()

Paginated List ​

Turns a particular type into a cursor-paginated list

g.ref(user).paginatedList()

g.ref(user).paginatedList()

Optional (nullable) ​

Specifies whether a field can return a null value if the requested data is not available

g.string().optional()

g.string().optional()

Required ​

Specifies whether a field must return a value

g.string().required()

g.string().required()

Default ​

Default values can be used to provide a fallback value if a requested value is not available. They can be specified for arguments, query variables, and input objects

g.string().default("Default string")

g.string().default("Default string")

Description ​

A string that can be used to describe a schema element such as a field or an argument

g.string().description("Description")

g.string().description("Description")

Deprecated ​

Mark a field as deprecated. It is used to indicate that a schema element is no longer supported or recommended and should not be used in new code. When a deprecated schema element is used, a warning is generated to alert developers

g.string().deprecated("Deprecation reason")

g.string().deprecated("Deprecation reason")

Omit Resolver ​

Omit returning a field in the resolver. Used when you want to skip returning a value in case the value is resolved elsewhere

g.string().omitResolver()

g.string().omitResolver()

Utilities ​

→ buildSchema

→ printSchema