typegql - GitLite

KO | EN

gitlite — search

#python #typescript #llm #golang #rust #docker #java #awesome #cli #awesome-list #vue #pytorch #security #open-source

typegql

(★ 427)

Create GraphQL schema with TypeScript classes.

File Explorer

Download Latest Version (.zip)

- demo.gif
- - arg.md
  - input-type-and-input-field.md
  - object-type-and-field.md
  - union.md
- - minimal-demo.md
  - setup.md
  - what-is-typegql.md
- - index.md
- README.md
- SUMMARY.md
- - index.ts
  - package.json
  - README.md
  - schema.ts
  - tsconfig.json
  - yarn.lock
- - index.ts
  - package.json
  - README.md
  - schema.ts
  - tsconfig.json
  - yarn.lock
- - index.ts
  - package.json
  - README.md
  - tsconfig.json
  - yarn.lock
- - index.ts
  - package.json
  - README.md
  - schemaA.ts
  - schemaB.ts
  - tsconfig.json
  - yarn.lock
- - index.ts
  - package.json
  - README.md
  - schema.ts
  - tsconfig.json
  - yarn.lock
- - .gitignore
  - handler.ts
  - package.json
  - README.md
  - serverless.yml
  - tsconfig.json
  - yarn.lock
- - index.ts
  - package.json
  - README.md
  - tsconfig.json
  - yarn.lock
- - index.ts
- - error.ts
- - setup.ts
- index.ts
.gitignore
.npmignore
.prettierrc
.travis.yml
book.json
CODE_OF_CONDUCT.md
jest.config.js
LICENSE
package.json
preprocessor.js
publish-docs.js
README.md
rollup.config.js
tsconfig.json
ttsconfig.json
yarn.lock

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![npm version](https://badge.fury.io/js/typegql.svg)](https://badge.fury.io/js/typegql)
[![npm version](https://david-dm.org/prismake/typegql.svg)](https://david-dm.org/prismake/typegql)
[![codecov](https://codecov.io/gh/prismake/typegql/branch/master/graph/badge.svg)](https://codecov.io/gh/prismake/typegql)
[![Build Status](https://api.travis-ci.org/prismake/typegql.svg?branch=master)](https://travis-ci.org/prismake/typegql)

### What is `typegql`?

![demo](https://raw.githubusercontent.com/prismake/typegql/master/assets/demo.gif)

typegql is set of decorators allowing creating GraphQL APIs quickly and in type-safe way.

* [Documentation](https://prismake.github.io/typegql/)

### Examples:

* [Basic Express example](examples/basic-express-server)
* [Typeorm integration example](examples/typeorm-basic-integration)
* [Forward resolution - eg. query only needed db fields](examples/forward-resolution)
* [Nested mutations or queries](examples/nested-mutation-or-query)
* [Custom decorators / Higher order decorators](examples/custom-decorators)
* [Serverless eg. AWS Lambda](examples/serverless)
* [Merge schemas](examples/merge-schemas)

## Basic example

Example below is able to resolve such query

```graphql
query {
  hello(name: "Bob") # will resolve to 'Hello, Bob!'
}
```

```typescript
import { compileSchema, SchemaRoot, Query } from 'typegql';

@SchemaRoot()
class SuperSchema {
  @Query()
  hello(name: string): string {
    return `Hello, ${name}!`;
  }
}

const compiledSchema = compileSchema({ roots: [SuperSchema] });
```

`compiledSchema` is regular executable schema compatible with `graphql-js` library.

To use it with `express`, you'd have to simply:

```typescript
import * as express from 'express';
import * as graphqlHTTP from 'express-graphql';

const app = express();

app.use(
  '/graphql',
  graphqlHTTP({
    schema: compiledSchema,
    graphiql: true,
  }),
);
app.listen(3000, () => console.log('Graphql API ready on http://localhost:3000/graphql'));
```

## Adding nested types

For now, our query field returned scalar (string). Let's return something more complex. Schema will look like:

```graphql
mutation {
  createProduct(name: "Chair", price: 99.99) {
    name
    price
    isExpensive
  }
}
```

Such query will have a bit more code and here it is:

```typescript
import { Schema, Query, ObjectType, Field, Mutation, compileSchema } from 'typegql';

@ObjectType({ description: 'Simple product object type' })
class Product {
  @Field() name: string;

@Field() price: number;

@Field()
  isExpensive() {
    return this.price > 50;
  }
}

@Schema()
class SuperSchema {
  @Mutation()
  createProduct(name: string, price: number): Product {
    const product = new Product();
    product.name = name;
    product.price = price;
    return product;
  }
}

const compiledSchema = compileSchema(SuperSchema);
```

## Forcing field type.

Until now, `typegql` was able to guess type of every field from typescript type definitions.

There are, however, some cases where we'd have to define them explicitly.

* We want to strictly tell if field is nullable or not
* We want to be explicit about if some `number` type is `Float` or `Int` (`GraphQLFloat` or `GraphQLInt`) etc
* Function we use returns type of `Promise<SomeType>` while field itself is typed as `SomeType`
* List (Array) type is used. (For now, typescript `Reflect` api is not able to guess type of single array item. This might change in the future)

Let's modify our `Product` so it has additional `categories` field that will return array of strings. For sake of readibility, I'll ommit all fields we've defined previously.

```typescript
@ObjectType()
class Product {
  @Field({ type: [String] }) // note we can use any native type like GraphQLString!
  categories(): string[] {
    return ['Tables', 'Furniture'];
  }
}
```

We've added `{ type: [String] }` as `@Field` options. Type can be anything that is resolvable to `GraphQL` type

* Native JS scalars: `String`, `Number`, `Boolean`.
* Any type that is already compiled to `graphql` eg. `GraphQLFloat` or any type from external graphql library etc
* Every class decorated with `@ObjectType`
* One element array of any of above for list types eg. `[String]` or `[GraphQLFloat]`

## Writing Asynchronously

Every field function we write can be `async` and return `Promise`. Let's say, instead of hard-coding our categories, we want to fetch it from some external API:

```typescript
@ObjectType()
class Product {
  @Field({ type: [String] }) // note we can use any native type like GraphQLString!
  async categories(): Promise<string[]> {
    const categories = await api.fetchCategories();
    return categories.map(cat => cat.name);
  }
}
```

## Before `1.0.0`

Before version `1.0.0` consider APIs of `typegql` to be subject to change. We encourage you to try this library out and provide us feedback so we can polish it to be as usable and efficent as possible.