Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aeb-labs/cruddl
Create a GraphQL API for your database, using the GraphQL SDL to model your schema.
https://github.com/aeb-labs/cruddl
arangodb graphql graphql-js hacktoberfest typescript
Last synced: about 7 hours ago
JSON representation
Create a GraphQL API for your database, using the GraphQL SDL to model your schema.
- Host: GitHub
- URL: https://github.com/aeb-labs/cruddl
- Owner: AEB-labs
- License: mit
- Created: 2018-02-28T19:22:50.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-21T12:02:48.000Z (2 months ago)
- Last Synced: 2025-01-01T00:07:55.094Z (about 7 hours ago)
- Topics: arangodb, graphql, graphql-js, hacktoberfest, typescript
- Language: TypeScript
- Homepage: https://aeb-labs.github.io/cruddl/
- Size: 14.3 MB
- Stars: 131
- Watchers: 14
- Forks: 17
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# cruddl
[](https://npmjs.org/cruddl)
[](https://github.com/AEB-labs/cruddl/actions?query=branch%3Amain)
[](https://packagequality.com/#?package=cruddl)
**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](https://www.arangodb.com/). The concept being inspired by existing projects like
[prisma](https://github.com/graphcool/prisma) and
[join-monster](https://github.com/stems/join-monster), cruddl exploits the expressiveness of the
Arango Query Language (AQL) to generate one tailored query for each GraphQL request.
**[Try it online](https://aeb-labs.github.io/cruddl/)**
## 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](https://www.arangodb.com/) and create a new database.
```typescript
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.
```typescript
import { InMemoryAdapter } from 'cruddl';
const db = new InMemoryAdapter();
```
Define your data model and create a project:
```typescript
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 }) => ({ authContext: { authRoles: ['users'] } }),
getOperationIdentifier: ({ context }) => context as object, // each operation is executed with an unique context object
});
```
Then, create the GraphQL schema and serve it:
```typescript
import { ApolloServer } from 'apollo-server';
const schema = project.createSchema(db);
db.updateSchema(project.getModel()); // create missing collections
const server = new ApolloServer({
schema,
context: ({ req }) => req, // pass request as context so we have a unique context object for each operation
});
server.listen(4000, () => console.log('Server is running on http://localhost:4000/'));
```
See the [modelling guide](docs/modelling.md) and the [api documentation](docs/api.md) 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`.
## Running Tests
For consistency, tests shall be run against a single arangodb node:
1. npm i
2. npm run start_arangodb
3. ensure you have access to console at http://localhost:8529
4. npm run test
When done, stop the instance with `npm run stop_arangodb`
## Documentation
- [Modelling guide](docs/modelling.md)
- [GraphQL API](docs/api.md)
- [I18n](docs/i18n.md)
## Supported versions
cruddl currently supports the following versions of ArangoDB:
- 3.11
- 3.12
ArangoDB 3.8 is still included in the CI tests, but no longer supported officially, and the CI tests
will be removed in a future minor or patch release.
Starting with ArangoDB 3.12, the default locale for new databases has been changed from `en_US` to
`en_US_POSIX`. cruddl does not support `en_US_POSIX` at the moment. If you don't have a locale
configured on your operating system (`LANG` is not set), you need to change the locale to `en_US`.
You can either configure the locale on the operating system, or use the `--default-language=en_US`
option. Do _not_ use `--icu-language`, as this will change the behavior in a different way, which is
also currently not supported by cruddl.