Skip to content
GraphQL API Framework with strong conventions and auto-generated schema
TypeScript HTML JavaScript Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci feat(codegen): codegen without db connection (#247) Nov 17, 2019
.vscode fix(examples): clean up examples, some got stale (#240) Nov 16, 2019
bin fix(cli): load ts-node if possible (#248) Nov 17, 2019
examples feat(codegen): codegen without db connection (#247) Nov 17, 2019
img Update README.md (#83) Apr 22, 2019
src fix(cli): load ts-node if possible (#248) Nov 17, 2019
tools feat(codegen): codegen without db connection (#247) Nov 17, 2019
typings feat(cli): adds db:create and db:drop (#133) Jun 23, 2019
.editorconfig chore(line-length): set max line length to 100 (#33) Jan 20, 2019
.eslintignore feat(config): allows all apollo config settings (#159) Jul 3, 2019
.eslintrc.js feat(codegen): codegen without db connection (#247) Nov 17, 2019
.gitignore feat(semantic-release): upgrades to version 16 beta (#233) Nov 9, 2019
.markdownlint.json feat(codegen): codegen without db connection (#247) Nov 17, 2019
.nvmrc Initial commit Jan 8, 2019
.prettierignore chore(prettier): change to 100 length and prettify existing files (#118) Jun 13, 2019
.yarnrc feat(codegen): codegen without db connection (#247) Nov 17, 2019
LICENSE Initial commit Jan 8, 2019
README.md feat(codegen): codegen without db connection (#247) Nov 17, 2019
package.json feat(codegen): codegen without db connection (#247) Nov 17, 2019
tsconfig.eslint.json feat(codegen): codegen without db connection (#247) Nov 17, 2019
tsconfig.json fix(packaging): fixes packaging issue (#179) Jul 30, 2019
tsconfig.test.json feat(config): allows all apollo config settings (#159) Jul 3, 2019
yarn.lock feat(codegen): codegen without db connection (#247) Nov 17, 2019

README.md

Warthog Logo

Node.js GraphQL Framework for building APIs with strong conventions through auto-generated code. With Warthog, set up your data models and resolvers, and it does the rest.

npm version CircleCI styled with prettier styled with prettier semantic-release Join the chat at https://gitter.im/warthog-graphql/community

Summary

Warthog is a Node.js GraphQL API framework for quickly building consistent GraphQL APIs that have sorting, filtering and pagination out of the box. It is written in TypeScript and makes heavy use of decorators for concise, declarative code.

Philosophy

This library is intentionally opinionated and generates as much code as possible. When teams build products quickly, even if they have strong conventions and good linters, the GraphQL can quickly become inconsistent, making it difficult for clients to consume the APIs in a reusable way.

To do this, Warthog automatically generates the following:

  • Database schema - generated by TypeORM
  • Your entire GraphQL Schema including:
    • types to match your entities - generated by TypeGraphQL
    • GraphQL inputs for consistent creates, updates, filtering, and pagination inspired by Prisma's conventions
  • A graphql-binding for type-safe programmatic access to your APIs.
  • TypeScript classes for the generated GraphQL schema for type-safety while developing.

Further, it covers the following concerns by hooking into best-in-class open source libraries:

  • Validation: Automatic validation before data is saved using any of the decorators available in the class-validator library.

Prerequisites

You must have Postgresql installed to use Warthog. If you already have it installed, you can skip this step, otherwise there are 3 options:

Docker

See the warthog-starter project for how to use Docker to run Postgres.

Homebrew

If you're on OSX and have Homebrew installed, you can simply run:

brew install postgresql
`brew --prefix`/opt/postgres/bin/createuser -s postgres

Postgres.app

Otherwise, you can install Postgres.app or use the Google machine to figure out how to install on your OS.

Usage

The easiest way to start using Warthog for a fresh project is to clone the warthog-starter repo. This has a simple example in place to get you started. There are also a bunch of examples in the examples folder for more advanced use cases.

Note that the examples in the examples folder use relative import paths to call into Warthog. In your projects, you won't need to set this config value as it's only set to deal with the fact that it's using the Warthog core files without consuming the package from NPM. In your projects, you can omit this as I do in warthog-starter.

Installing in Existing Project

yarn add warthog

1. Create a Model

The model will auto-generate your database table and graphql types. Warthog will find all models that match the following glob - '/**/*.model.ts'. So for this file, you would name it user.model.ts

import { BaseModel, Model, StringField } from "warthog";

@Model()
export class User extends BaseModel {
  @StringField()
  name?: string;
}

2. Create a Resolver

The resolver auto-generates queries and mutations in your GraphQL schema. Warthog will find all resolvers that match the following glob - '/**/*.resolver.ts'. So for this file, you would name it user.resolver.ts

import { User } from "./user.model";
import { UserService } from "./user.service";

@Resolver(User)
export class UserResolver {
  constructor(@Inject("UserService") readonly service: UserService) {}

  @Query(() => [User])
  async users(
    @Args() { where, orderBy, limit, offset }: UserWhereArgs
  ): Promise<User[]> {
    return this.service.find<UserWhereInput>(where, orderBy, limit, offset);
  }

  @Mutation(() => User)
  async createUser(
    @Arg("data") data: UserCreateInput,
    @Ctx() ctx: BaseContext
  ): Promise<User> {
    return this.service.create(data, ctx.user.id);
  }
}

3. Create a Service

import { User } from "./user.model";

@Service("UserService")
export class UserService extends BaseService<User> {
  constructor(
    @InjectRepository(User) protected readonly repository: Repository<User>
  ) {
    super(User, repository);
  }
}

4. Add config to .env file

WARTHOG_APP_HOST=localhost
WARTHOG_APP_PORT=4100
WARTHOG_DB_DATABASE=warthog
WARTHOG_DB_USERNAME=postgres
WARTHOG_DB_PASSWORD=

5. Run your server

import "reflect-metadata";
import { Server } from "warthog";

async function bootstrap() {
  const server = new Server();
  return server.start();
}

bootstrap();

When you start your server, there will be a new generated folder that has your GraphQL schema in schema.graphql. This contains:

type User implements BaseGraphQLObject {
  id: String!
  createdAt: DateTime!
  createdById: String!
  updatedAt: DateTime
  updatedById: String
  deletedAt: DateTime
  deletedById: String
  version: Int!
  name: String!
}

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

type Query {
  users(
    offset: Int
    limit: Int = 50
    where: UserWhereInput
    orderBy: UserOrderByInput
  ): [User!]!
}

input UserCreateInput {
  name: String!
}

enum UserOrderByInput {
  createdAt_ASC
  createdAt_DESC
  updatedAt_ASC
  updatedAt_DESC
  deletedAt_ASC
  deletedAt_DESC
  name_ASC
  name_DESC
}

input UserUpdateInput {
  name: String
}

input UserWhereInput {
  id_eq: String
  id_in: [String!]
  createdAt_eq: String
  createdAt_lt: String
  createdAt_lte: String
  createdAt_gt: String
  createdAt_gte: String
  createdById_eq: String
  updatedAt_eq: String
  updatedAt_lt: String
  updatedAt_lte: String
  updatedAt_gt: String
  updatedAt_gte: String
  updatedById_eq: String
  deletedAt_all: Boolean
  deletedAt_eq: String
  deletedAt_lt: String
  deletedAt_lte: String
  deletedAt_gt: String
  deletedAt_gte: String
  deletedById_eq: String
  name_eq: String
  name_contains: String
  name_startsWith: String
  name_endsWith: String
  name_in: [String!]
}

input UserWhereUniqueInput {
  id: String!
}

# ...

Notice how we've only added a single field on the model and you get pagination, filtering and tracking of who created, updated and deleted records automatically.

Server API (appOptions)

Most of the config in Warthog is done via environment variables (see Config - Environment Variables below). However, more complex/dynamic objects should be passed via the server config.

attribute description default
container TypeDI container. Warthog uses dependency injection under the hood. empty container
authChecker An instance of an AuthChecker to secure your resolvers.
context Context getter of form (request: Request) => object empty
logger Logger debug
middlewares TypeGraphQL middlewares to add to your server none
onBeforeGraphQLMiddleware Callback executed just before the Graphql server is started. The Express app is passed. none
onAfterGraphQLMiddleware Callback executed just after the Graphql server is started. The Express app is passed. none

Config - Environment Variables

Almost all config in Warthog is driven by environment variables. The following items are available:

variable value default
WARTHOG_APP_HOST App server host none
WARTHOG_APP_PORT App server port 4000
WARTHOG_APP_PROTOCOL App server protocol http
WARTHOG_AUTO_GENERATE_FILES Auto-generate files false (true in development)
WARTHOG_AUTO_OPEN_PLAYGROUND Open playground on server start false (true in development)
WARTHOG_CLI_GENERATE_PATH Where should CLI generate files ./src
WARTHOG_DB_CONNECTION DB connection type postgres
WARTHOG_DB_DATABASE DB name none
WARTHOG_DB_ENTITIES Where should warthog look for models src/**/*.model.ts
WARTHOG_DB_MIGRATIONS What DB migrations should TypeORM run db/migrations/**/*.ts
WARTHOG_DB_MIGRATIONS_DIR Where should generated migrations be placed db/migrations
WARTHOG_DB_PORT DB port 5432
WARTHOG_DB_USERNAME DB username none
WARTHOG_DB_LOGGER TypeORM logger advanced-console
WARTHOG_DB_PASSWORD DB password none
WARTHOG_DB_SYNCHRONIZE DB automatically migrated false
WARTHOG_GENERATED_FOLDER Where should generated code be placed ./generated
WARTHOG_INTROSPECTION Allow server to be introspected true
WARTHOG_MOCK_DATABASE Should we use mock sqlite DB? false
WARTHOG_RESOLVERS_PATH Where should Warthog look for resolvers src/**/*.resolver.ts

Field/Column Decorators

All of the auto-generation magic comes from the decorators added to the attributes on your models. Warthog decorators are convenient wrappers around TypeORM decorators (to create DB schema) and TypeGraphQL (to create GraphQL schema). You can find a list of decorators available in the src/decorators folder. Most of these are also used in the examples folder in this project.

Complex use cases/ejecting

Warthog makes building simple CRUD endpoints incredibly easy. However, since it is built on top of TypeORM and TypeGraphQL it is flexible enough to handle complex use cases as well.

DB-only

If you need to add a column to the DB that does not need to be exposed via the API, you should just use the TypeORM decorators

API-only

If you need to add a field that is only exposed via the API that is not DB-backed, you should just use the TypeGraphQL Field Decorator

Custom Query

See the feature-flag example for an example of where we'd want to build something beyond the standard CRUD actions. In this example we want to add a custom query that makes a complex DB call.

  • First add the query to the resolver - link to code
  • Then add the custom query input in the resolver - link to code
  • Then add the custom service method that fetches the data link to code

Warthog will generate the correct GraphQL query and InputType automatically.

CLI

Warthog ships with the following commands that can be accessed by running yarn warthog <command>.

See the warthog-starter project's package.json for example usage.

Command Args Description
codegen none autogenerates code from decorated models and resolvers and places in generated folder
db:create none creates DB based on DB specified in config file
db:drop none drops DB based on DB specified in config file
generate See below generates a model, service and resolver
db:migrate none migrates DB (proxies through TypeORM CLI)
db:migrate:create none auto-generates DB migration based on new code additions (proxies through TypeORM CLI)

generate Command in depth

The generate command will create a new resolver, service and model for a given resource. Let's start with a complex example and we'll break it down:

yarn warthog generate user name! nickname numLogins:int! verified:bool! registeredAt:date balance:float! --folder my_generated_folder
  • user - this is the name of the new resource (required)
  • ...args - each of the remaining args until --folder is a field on the resource
  • name! - the name field is of type string by default since no data type is specified. The ! states that it's required
  • numLogins:int! - numLogins states that it is of type int - also required
  • registeredAt:date - registeredAt is of type date (which correlates to an ISO8601 datetime). The absence of the ! means it is optional.
  • ...the rest of the args are self-explanatory. Possible types are bool, date, int, float and string. If you need to use other types, just add them as strings and update the models manually.
  • --folder - this allows you to explicitly set the folder where the generated files should go. This is not recommended and instead you should use the .rc file (see below)

warthogrc config file

Warthog uses cosmiconfig for config that shouldn't change between environments (so typically file paths). This means you can put any of the following config files in your project root:

  • .warthogrc.json
  • .warthogrc.yaml
  • .warthogrc.js
  • warthog.config.js file (exporting a JS object)

The following config options are currently available:

Config Key Description Equivalent Environment Variable
generatedFolder Relative location to generated folder (relative path from the config file) WARTHOG_GENERATED_FOLDER
cliGeneratePath Where should CLI place generated files? (relative path from the config file) WARTHOG_CLI_GENERATE_PATH
resolversPath Where should Warthog look for resolvers? (comma-delimited list of regexes) WARTHOG_RESOLVERS_PATH

Note that for cliGeneratePath, you can interpolate in the following strings to generate dynamic paths:

  • className (pascal case)
  • camelName (camel case)
  • kebabName (kebab case)

Example:

{
  "cliGeneratePath": "./src/${kebabName}"
}

Running yarn warthog generate featureFlag would create 3 files in the ./src/feature-flag/ folder. See feature-flag example for a live example.

Usage in Production

It is recommended that you not run Warthog's TypeScript files via ts-node in Production as we do in development as ts-node has been known to cause issues in some smaller AWS instances. Instead, compile down to JS and run in node. For a full project example (using dotenvi for config management), see warthog-starter

Contributing

PRs accepted, fire away! Or add issues if you have use cases Warthog doesn't cover.

Before contributing, make sure you have Postgres installed and running with a user named postgres with an empty password. If you don't have this local Postgres user, you'll need to update the .env files in the examples folders to point to a user that can run DB migrations.

Once you have this user set up, you can build a specific example by navigating to that folder and running yarn bootstrap.

If you want to build all examples, you can run yarn bootstrap from the Warthog root folder.

It's helpful to add a new feature to the Warthog and make use of it in one of the examples folders until you've determined how it's going to work. Once you have it working, you can add tests.

Intentionally Opinionated

Warthog is intentionally opinionated to accelerate development and make use of technology-specific features:

  • Postgres - currently the only database supported. This could be changed, but choosing Postgres allows adding a docker container and other goodies easily.
  • Jest - other harnesses will work, but if you use Jest, we will not open the GraphQL playground when the server starts, for example.
  • Soft deletes - no records are ever deleted, only "soft deleted". The base service used in resolvers filters out the deleted records by default.

Thanks

Special thanks to:

Warthog is essentially a really opinionated composition of TypeORM and TypeGraphQL that uses similar GraphQL conventions to the Prisma project.

License

MIT © Dan Caddigan

You can’t perform that action at this time.