graphql-schema-decorator
v1.0.0
Published
Creates GraphQL Schema from decorated TypeScript Class
Downloads
130
Readme
This project is not being supported anymore
This project was discontinued and will not be updated anymore. We recommend using type-graphql, that covers most of this project's features and is being constantly updated and maintained.
Graphql-Schema-Decorator
Differences from graphql-decorator
This package makes possible the use of decorators to define a GraphQL schema. Note that this package is a fork, we have added some new features to the original package.
Apart from the decorators listed on the original documentation, we have added six new and changed the behavior for two others.
- @Ctx: Injects GraphQL context object into annotated method parameter.
- @Root: Injects GraphQL root object into annotated method parameter.
- @Pagination: Wraps the type into a pagination model (http://graphql.org/learn/pagination/). For clarification, see examples below.
- @OrderBy: It creates an
orderBy
input object to the related @Connection query. The available fields for ordering, comes the the type declared on the related @Field. Examples should make this clearer. - @EnumType: It can be used just like @ObjectType in order to create
GraphQLEnumType
objects. - @Value: Should be used on classes decorated with @EnumType. It creates values for enums. Accepts an object of type
any
as parameter. This paremeter will be the enum value. If none is passed, the enum value is the enum itself. See example below. - @Query: It can be used multiple times on the same file. This way we make it possible to break queries into different folders.
- @Mutation: It can be used multiple times on the same file. This way we make it possible to break queries into different folders.
- @UnionType: It can be used to create
GraphQLUnionType
objects. - @InterfaceType: It can be used to create
GraphQLInterfaceType
objects.
GraphQL Decorator Examples
Use of modified @Query and @Mutation. @Schema stayed the same as on the original repo.
import { Schema, Query, Mutation } from "graphql-schema-decorator";
import * as AnswerMutations from 'graphql/answer/mutations/index';
import * as AnswerQueries from 'graphql/answer/queries/index';
import * as UserQueries from 'graphql/user/queries/index';
import * as UserMutations from 'graphql/user/mutations/index';
@Schema()
export class RootSchema {
@Query()
answerQuery: AnswerQueries.AnswerQuery;
@Query()
answersQuery: AnswerQueries.AnswersQuery;
@Mutation()
answerCreateMutation: AnswerMutations.AnswerCreateMutation;
@Mutation()
answerUpvoteMutation: AnswerMutations.AnswerUpvoteMutation;
}
Example usage of @Ctx and @Root.
import { ObjectType, Ctx, Field, Root } from 'graphql-schema-decorator';
import { GraphQLID, GraphQLString, GraphQLList } from 'graphql';
import * as AnswerTypes from 'graphql/answer/types/index';
@ObjectType({description: 'An user'})
export class UserType {
@Field({type: GraphQLID, nonNull: true})
id: number;
@Field({type: GraphQLString, })
name: string;
@Field({type: GraphQLString, nonNull: true})
avatarUrl: string;
@Field({type: GraphQLString, nonNull: true})
email: string;
@Field({type: AnswerTypes.AnswerType, isList: true})
answers(@Ctx() context: any, @Root() root: any) {
// Get answers using ctx and root.
}
}
Use of @Pagination with @OrderBy
import { ObjectType, Arg, Ctx, List, Field } from 'graphql-schema-decorator';
@ObjectType({description: 'Get all users query.'})
export class UsersQuery {
@Field({type: UserType, pagination: true})
users(
@Ctx() context: any,
@Arg({name: "offset"}) offset: number,
@Arg({name: "limit"}) limit: number,
@OrderBy() orderBy: orderByItem[]
) {
// Get users
}
@ObjectType({description: 'An user.'})
export class UserType {
@Field({type: GraphQLID, description: 'User id', nonNull: true})
id: number;
@Field({type: GraphQLString, description: 'User name', nonNull: true})
name: string;
}
}
The orderByType
interface
export interface orderByItem {
sort: string;
direction: string;
}
nodes
, count
and pageInfo
comes with the @Pagination decorator. @OrderBy accepts an array of orderByItem
{
users(orderBy: [{sort: id, direction: DESC}, {sort: title, direction: ASC}]) {
nodes {
id,
name
},
count,
pageInfo {
hasNextPage
}
}
}
Use of @EnumType and @Value
import { EnumType, Description, Value } from 'graphql-schema-decorator';
@EnumType({description: 'An user role. Either ADMIN or DEFAULT'})
export class UserRoleType {
@Value(0, {description: 'Admin role'})
ADMIN: string;
@Value('value', {description: 'Default role'})
DEFAULT: string;
@Value()
GOD: string;
}
And you can use the just declared enum like this.
import { ObjectType, Arg, Pagination, Field, Description } from 'graphql-schema-decorator';
import * as UserTypes from 'graphql-schema/user/type';
@ObjectType({description: 'Get all users query.'})
export class UsersQuery {
@Field({type: UserTypes.UserType, pagination: true})
users(@Arg({name: "role", type: UserTypes.UserRoleType }) role: any) {
// The role value will either be 0, "value" or GOD.
// Get users by role.
}
}
How to use this project with a dependency injection tool?
You can use service containers, which allow you to inject custom services in some places, like in subscribers or custom naming strategies. Or for example, you can get access to any dependency inside your schema classes using a service container.
Here is a example for how you can setup typedi
service containers. But note, that you can setup any service container you choose to.
import {useContainer} from 'graphql-schema-decorator';
// its important to setup container before you start to work with graphql-schema-decorator
useContainer(Container);
Use of useContainer
along with typedi
container. Note that bannerRepository
will be injected through the constructor.
import { ObjectType, Field } from 'graphql-schema-decorator';
import { Service } from 'typedi';
@Service()
export class BannerRepository {
getBanners(): any[] {
// getBanners implementation
}
}
@ObjectType({description: 'Get a list of banners.'})
@Service()
export class BannersQuery {
constructor(
private readonly bannerRepository: BannerRepository
) { }
@Field({type: BannerTypes.BannerType, isList: true})
banners() {
return this.bannerRepository.getBanners();
}
}
Getting started
This tool requires Node.js v6.10.0 or later.
npm i graphql-schema-decorator typescript
This tool uses ES.next Decorators and Reflect, so create tsconfig.json :
{
"compilerOptions": {
"module": "commonjs",
"target": "es6",
"noImplicitAny": false,
"sourceMap": false,
"moduleResolution": "node",
"experimentalDecorators": true,
"emitDecoratorMetadata": true
},
"exclude": [
"node_modules"
]
}
And write .ts code such as:
/* main.ts */
import { Schema, Query, ObjectType, Field, schemaFactory } from "graphql-schema-decorator";
const graphql = require("graphql").graphql;
// @ObjectType creates GraphQLObjectType from a class
@ObjectType()
class QueryType {
@Field() greeting(): string {
return "Hello, world!";
}
}
// @Schema creates GraphQLSchema from a class.
// The class should have a field annotated by @Query decorator.
@Schema()
class SchemaType {
@Query() query: QueryType;
}
async function main() {
// create schema from annotated class
const schema = schemaFactory(SchemaType);
const result = await graphql(schema, `query { greeting } `);
console.log(result.data.greeting);
}
main();
Finally, execute the above schema:
tsc main.ts && node main.js
# -> Hello, world!
Guide
Schema
You can declare a GraphQL schema class with @Schema
, @Query
and @Mutation
decorators.
For example:
import { Schema, Query, Mutation } from "graphql-schema-decorator";
@Schema()
class MySchema {
@Query() query: RootQuery;
@Mutation() mutation: Mutations;
}
A schema class should a field annotated by @Query
, which represents that the type of this filed will be a root query of GraphQL. And the type of this field should be annotated by @ObjectType
.
The field annotated by @Mutation
also represents mutation of your GraphQL schema.
Object Type
You can annotate your class with @ObjectType()
For example:
@ObjectType()
class SomeObject {
@Field() title: string;
@Field() greeting(): string {
return "Hello";
}
}
The above example has 2 fields, the one is title
and the another is greeting
.
You can set the @Field
decorator to your class's properties and methods. The fields annotated by @Field
will be exposed as fields of this object in GraphQL schema. And when you set @Field
to methods, the methods will work as the resolver function in schema.
Type of field
By the default, @Field
detects GraphQLScalarType corresponding to the field type.
You can explicitly configure the type of the fields using type
option.
@ObjectType() class User {
@Field() name: string;
}
@ObjectType() class SomeObject {
@Field({type: User}) user: User;
}
NonNull, List
You can use @NonNull
and @List
decorator. For example:
@ObjectType()
class User {
@Field({type: graphql.GraphQLID, nonNull: true})
id: string;
}
@ObjectType()
class Query {
@Field({type: User, isList: true}) getAllUsers(): Promise<User[]> {
/* implementation for fetch all users */
}
}
Resolver's arguments
You can use @Arg
for declare arguments of resolver function. For example:
@ObjectType()
class MutationType {
@Field({type: User}) deleteUser(
@Arg({name: "id"}) id: string
) {
/* implementation for delete user */
}
}
And you can declare GraphQL InputObjectType with @InputObjectType
decorator.
@InputObjectType()
class UserForUpdate {
@Field() name: string;
@Field() emal: string;
}
@ObjectType()
class MutationType {
@Field({type: User}) updateUser(
@Arg({name: "id"}) id: string,
@Arg({name: "input"}) input: UserForUpdate
) {
/* implementation for delete user */
}
}
API Usage
T.B.D.
Examples
Please checkout examples folder in this repository.
License
This software is released under the MIT License, see LICENSE.txt.