Skip to content
Create a GraphQL API for your database, using the GraphQL SDL to model your schema.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
arangodb Provide secondary endpoints for core and different dbs Jul 18, 2018
core
docs Add information about empty object filters Dec 13, 2018
inmemory Provide secondary endpoints for core and different dbs Jul 18, 2018
spec
src
.gitignore Add coverage data to git ignore Nov 6, 2017
.npmignore Do not include arangodb in npm package Dec 3, 2018
.npmrc Change registry to public registry May 15, 2018
.travis.yml
CHANGES.md Clean up after refactoring of schema generation Jun 6, 2018
LICENSE Create LICENSE Mar 1, 2018
README.md
core-exports.ts
cruddl-bench.js Rename momo to cruddl in code occurrences Feb 28, 2018
cruddl-dev.js Rename momo to cruddl in code occurrences Feb 28, 2018
graphql.config.json Add graphql.config.json with default development URL May 15, 2018
index.ts Provide secondary endpoints for core and different dbs Jul 18, 2018
package-lock.json 0.8.0 Apr 2, 2019
package.json 0.8.0 Apr 2, 2019
tsconfig.json Change emit to es6 Apr 2, 2019

README.md

cruddl

npm version Build Status Package Quality

cruddl - create a cuddly GraphQL API for your database, using the GraphQL SDL to model your schema.

This TypeScript library creates an executable GraphQL schema from a model definition and provides queries and mutations to access a database. Currently, it supports the multi-model database ArangoDB. The concept being inspired by existing projects like prisma and join-monster, cruddl exploits the expressiveness of the Arango Query Language (AQL) to generate one tailored query for each GraphQL request.

Try it online

Features

  • Schema definition using GraphQL types, fields and directives
  • Modelling features like relations, embedded lists and objects
  • Query features include filtering, sorting, cursor-based pagination and arbitrary nesting
  • Schema validation
  • Role-based authorization (field and type-based; static and data-dependent)
  • Pluggable database backends (currently supports ArangoDB and an in-memory implementation)

Usage

npm install --save cruddl

Install ArangoDB and create a new database.

import { ArangoDBAdapter } from 'cruddl';
const db = new ArangoDBAdapter({
    databaseName: 'databaseName',
    url: 'http://root:@localhost:8529',
    user: 'root',
    password: ''
});

If you just want to explore the features, you can also use an in-memory database implementation - but don't use this for anything else.

import { InMemoryAdapter } from 'cruddl';
const db = new InMemoryAdapter();

Define your data model and create a project:

import { Project } from 'cruddl';
const project = new Project({
    sources: [ {
        name: 'schema.graphqls',
        body: `
            type Movie @rootEntity {
              title: String
              actors: Actor @relation
            }
            
            type Actor @rootEntity {
              name: String
              movies: Movie @relation(inverseOf: "actors")
            }`
    }, {
        name: 'permission-profiles.json',
        body: JSON.stringify({
            permissionProfiles: {
                default: {
                    permissions: [{
                      roles: ['users'],
                      access: 'readWrite'
                    }]
                }
            }
        })
    } ],
    getExecutionOptions: ({context}) => ({ authRoles: ['users'] })
});

Then, create the GraphQL schema and serve it:

import { GraphQLServer } from 'graphql-yoga';
const schema = project.createSchema(db);
db.updateSchema(project.getModel()); // create missing collections
const server = new GraphQLServer({ schema });
server.start(() => console.log('Server is running on http://localhost:4000/'));

See the modelling guide and the api documentation for details.

Usage in a browser environment

The core of cruddl perfectly works in a browser (e.g., using webpack), and this can be useful to generate a mock GraphQL schema on the fly or to validate a cruddl project. However, the ArangoDB adapter only works with node imports like path. Unless you configure webpack to provide mock modules for them, you will get an error when you import cruddl in a webpack environment. To solve this, you can import the core symbols from cruddl/core and the InMemoryAdapter from cruddl/inmemory.

Status

Although the feature set is already quite extensive, this project is still in active development. A number of regression tests helps to avoid unexpected changes in behavior, but they do not yet cover all cases. Documentation is relatively sparse and will be extended in the future. We aim to contribute to the ongoing developments regarding GraphQL database interfaces and might change our API to more closely match these of other implementations in the future.

Documentation

You can’t perform that action at this time.