README

AutoCRUD (@vizworx/autocrud)

Tools for generating resolvers and Knex queries from a GraphQL schema

AutoCRUD is intended to simplify the process of connecting a GraphQL API and database - in many cases eliminating the need to write resolvers at all.

Documentation
Usage
- Minimal example
Assumptions
Limitations
Development
- Testing
- Running with local projects
  - Yarn-based projects
  - NPM-based projects
License

Documentation

Usage

yarn add @vizworx/autocrud graphql@^14.0.0 || ^15.0.0 knex@^0.20.11 || ^0.21.0

Minimal example

This example uses apollo-server-express, but Autocrud should be expected to work with any library following the GraphQL spec.

import { ApolloServer, makeExecutableSchema, gql } from 'apollo-server-express';
import {
  initialize as initializeAutoCRUD,
  typeDefs as AutoCRUDTypeDefs,
} from '@vizworx/autocrud';

import knex from './setupKnexInstance';
import typeDefs from './typeDefs';

const schema = makeExecutableSchema({
  typeDefs: [
    ...AutoCRUDTypeDefs,
    gql`
      type User @autocrud(table: "users") {
        id: ID!
        createdAt: DateTime!
        updatedAt: DateTime!
        email: String!
        name: String!
        avatarURL: String!
      }
    `,
  ],
});

const { getContext: getAutoCRUDContext } = initializeAutoCRUD(schema);

return new ApolloServer({
  schema,
  context: () => ({
    ...getAutoCRUDContext({ knex }),
  }),
});

Assumptions

All database tables referenced from an @autocrud(table: ___) declaration must have an id column. This does not apply to pivot relationships, as { leftId, rightId } are sufficient, unless the schema exposes that table directly:
```
type AllRelationships @autocrud(table: "relationships") {
  leftId
  rightId
}
```

Limitations

MySQL and PostgreSQL are the only officially supported databases at this time. Our tests are also run against SQLite (minimum version of 3.30.0), and it is "unsupported" only because its flexibility means we can't guarantee everything will behave correctly. Contributions providing support for other databases are more than welcome.
Microsoft SQL Server is explicitly not supported; node-mssql has dropped support for running database transactions in a Promise.all (https://github.com/tediousjs/node-mssql/issues/491).
!11 - AutoCRUD does not currently support union types. Fields with a union type will be omitted when generating Filter and OrderBy inputs, and queries with union fields will probably throw an error.
Interface fields do not currently support the through argument for relationships.

Development

Testing

yarn test: Run the test suite using an in-memory SQLite instance. This is faster than using the Docker scripts but also prone to error, as SQLite has fewer constraints than other database clients.
yarn test:start-mysql
yarn test:start-postgres: Start a database using Docker. (Will block the current terminal until it is stopped)
yarn test:mysql
yarn test:postgres: Run the test suite.
yarn test:stop-mysql
yarn test:stop-postgres: Stop the Docker container.

Running with local projects

Because AutoCRUD relies on peer dependencies, linking it to a local project requires a few extra steps.

When developing locally yarn will install everything, allowing AutoCRUD's tests, linting, etc. to be run.

Peer dependencies need to be removed when using AutoCRUD from another package, however, so we've added a script to take care of building, installing, and linking the project for you.

Yarn-based projects

# /autocrud
yarn run deploy-local

# /other-project
yarn link ../path/to/autocrud
yarn run start --preserve-symlinks

NPM-based projects

# /autocrud
npm run deploy-local

# /other-project
npm link @vizworx/autocrud
npm run start -- --preserve-symlinks

In either case, depending on your project's configuration you may have to experiment with adding/removing the extra -- when starting to have --preserve-symlinks passed correctly to the runtime.

Usage no npm install needed!