@autographcraft/core NPM

Description

AutoGraphCraft can generate an entire GraphQL API from GraphQL schema files, including the resolver functions, authorisation logic, entity relationships, database schema and typescript types.

Features

Best Practices: AutoGraphCraft follows best practices for GraphQL and database design
Type Generation: AutoGraphCraft will generate the typescript types for the schema files, including the types for the resolvers and context
Resolver Generation: AutoGraphCraft will generate the entire GraphQL API from the schema files, including the resolvers, types, and context.
Customisable: The generated output can be customised by adding additional custom resolver
Database Agnostic: The resolvers can be generated for the database you are using by installing the appropriate resolver package
Type Safe: The generated types are fully typed and can be used in your application to ensure type safety
Relationships: The resolvers can be generated to include relationships between entities
Authentication: Allow/Disallow access to data/entites based on the caller's permissions

Install

The AutoGraphCraft requires two packages to be installed; the generation package and a resolver package.

The generate package is only required as part of your build process, so should be installed as a dev dependency:

npm install @autographcraft/generate --save-dev

Then you will need to install a resolver package. This package will be used to resolve the data from your database. The resolver package should be installed as a regular dependency:

npm install @autographcraft/[package-name]

For instance, if you wanted to use MongoDB as your database, you would install the MongoDB package by running:

npm install @autographcraft/mongodb

Setup

Initialise the Package

The package needs to be initalised before it is first run, otherwise it will not be able to generate any output. The initialisation will perform two steps:

Add the autographcraft.config.js file to the root of your project
Add additional configuration to your gitignore file

The configuration file will specify where the source and target directories are for the generation process. Each of these options is detailed in the Configuration Readme.

The initialisation is a guided process to create the configuration which can be called with:

npx autographcraft init

If you wish to initialise with the default settings, use the --default flag:

npx autographcraft init --default

# OR

npx autographcraft init -d

Running the Package

NOTE:
If you are following these steps in order, you will not currently have a defined schema. The generation process will warn you that there is no schema and will not generate any files. This is expected behaviour. To add a schema, see the Specifying the Schema section.

The package can be run using the generate command:

npx autographcraft generate

This will collect all the generation information and call the AutoGraphCraft API to generate the required files. If you are not signed in, you will be directed to sign in or sign up to the AutoGraphCraft platform in your browser.

The generation process will only request the generation of the files if the schema or configuration has changed since it was last run. This is to prevent unnecessary generation of files and delays in the build process. If you wish to generate the files again without making any changes, you can use the --force flag:

npx autographcraft generate --force

# OR

npx autographcraft generate -f

If you wish to turn off the logging output when running the generate command, add the --quiet flag to the end of the command.

npx autographcraft generate --quiet

# OR

npx autographcraft generate -q

If you remove a model from the schema, you may also wish to remove the generated files from your project. This can be done by running the --clean-models flag:

npx autographcraft generate --clean-models

# OR

npx autographcraft generate -m

NOTE:
The --clean-models flag will remove the entire model directory, including any committed files in the hookIns directory.

If you need help at any time, run the command npx autographcraft help to open the full documentation.

Running the Package in CI/CD

If you are running the package in a CI/CD pipeline, you will want to run the package without the requirement to sign-in via the AutoGraphCraft website. This can be done by setting providing the --username and --password flags to the generate command:

npx autographcraft generate --username 'your-username' --password 'your-password'

The generate command must be run before the build process to ensure the resolvers and types are generated before the build process starts.

NOTE:
The --username and --password can be wrapped in quotes if they contain special characters. For instance, passwords containing ! or & should always be wrapped in quotes.

Implement the Package

Add the following script to your package.json file:

"scripts": {
  "generate": "npx autographcraft generate"
}

If you wish to have the types generated on every build (recommended), add generate to the prebuild script:

"scripts": {
  "prebuild": "npm run generate",
  "generate": "npx autographcraft generate"
}

Update Configuration

The configuration should be updated via the config set command. Further details can be found in the Configuration Readme.

Usage

Specifying the Schema

In order to generate the types, you will need to specify the schema. This is done by creating .graphql files in the schemaSourceDirectory directory specified in the autographcraft.config.js file. For instance, the User schema might be defined in a file called User.graphql in the src/schemas directory:

A standard schema file for a user might look like:

# src/schemas/User.graphql

type User @model {
  id: ID!
  name: String!
  email: String!
}

The @model directive on the User type is used to specify that this type should be used to generate resolvers. The id field is required and should be of type ID!. All other fields are optional.

Models can be connected to other models by specifying a field as a type of another model. In the example below, a User can have many Posts and a Post can have one User:

type User @model {
  id: ID!
  name: String!
  email: String!
  posts: [Post] @hasMany(targetIndexName: "byCreatedByUserId")
}

type Post @model {
  id: ID!
  createdByUserId: ID! @index(name: "byCreatedByUserId")
  user: User @hasOne(idField: "createdByUserId")
  title: String!
  content: String!
}

Further information on how to define schemas can be found in the Schema Readme.

Implementing the Generated Output

The generated files includes the resolvers, typedefs, and context generation for a GraphQL server. The resolvers have been tested with Apollo Server and GraphQL Yoga, but should work with most GraphQL servers.

The resolvers can be found in the directory specified by the generatedTypesDirectory in the autographcraft.config.js file and can be imported using the default export:

import resolvers from './generatedTypes/resolvers'

The typedefs can be found in the directory specified by the generatedTypesDirectory in the autographcraft.config.js file and can be imported using the loadFiles utility from @graphql-tools/load-files:

import { loadFiles } from "@graphql-tools/load-files";
const typeDefs = await loadFiles("src/generatedTypes/typeDefs.graphql");

These can then be combined to create the the GraphQL server:

import { ApolloServer } from 'apollo-server';
import { loadFiles } from '@graphql-tools/load-files';
import resolvers from './generatedTypes/resolvers';

const typeDefs = await loadFiles('src/generatedTypes/typeDefs.graphql');

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

The context can be generated using the createAutoGraphCraftContext function from the generatedUtilsDirectory in the autographcraft.config.js file:

import { config } from "../autographcraft.config.js";
import {
  type AutoGraphCraftContextParams,
  createAutoGraphCraftContext,
} from "./generatedUtils";

const autoGraphCraftContextParams: AutoGraphCraftContextParams = {
  mongooseConnection: yourMongooseConnection,
  config,
  authInitialisationData: {},
};

const context = async (initialContext) => {
  // Create the context required for the resolvers
  const autographcraftContext = await createAutoGraphCraftContext(
    autoGraphCraftContextParams,
  );
  
  // Combine the initial context with the autographcraft context
  const combinedContext = {
    ...initialContext,
    ...autographcraftContext,
  };
  return combinedContext;
};

Then you can start the Apollo Server:

const { url } = await startStandaloneServer(server, {
  listen: { port: 3000 },
  context,
});

console.log(`🚀  Server ready at: ${url}`);

Full examples of how to implement the generated files can be found in the Examples directory.

Custom Resolvers

Some queries and mutations may require custom resolvers because a functionality is required that does not fit within the CRUDL architecture; using the example from the previous section, there may be a requirement to count the number of posts that a user has made.

To create a new custom query or custom mutation, create a new .graphql file in the schemaSourceDirectory directory. The file should contain the Query or Mutation type:

type Query {
  countPostsByUser(userId: ID!): Int!
}

type Mutation {
  deleteAllPostsByUser(userId: ID!): [Post]
}

Multiple type Query and type Mutation types can be defined in the schemaSourceDirectory directory files and will be combined into the final schema.

The custom resolvers will be created based on each query and mutation, and will be placed in the queriesDirectory directory or the mutationsDirectory directory from the autographcraft.config.js file. The custom queries and mutations will already be imported into the resolvers file, so they can be used without any modification to the GraphQL server.

Each of the custom resolvers will be typed based on the schema. You can then implement the required logic in the custom resolver.