npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

graphql-schema-decorator

v1.0.0

Published

Creates GraphQL Schema from decorated TypeScript Class

Downloads

192

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

Build Status npm version Help Contribute to Open Source

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.