README.md

Powerful decorators for ArangoDB Foxx Apps when working with TypeScript.

TypeArango manages ArangoDB collections, documents, relations and routes
by taking advantage of TypeScript's typings. It comes with a fast and easy to use permission
system, provides an ORM, event listeners, documented endpoints as well as plenty of
other tools to make it fun to build ReST APIs in a declarative & elegant manner.
_{TypeArango is probably the fastest way of setting up documented & validated endpoints.}

⭐ Features

• Beautiful Code thanks to decorators
• A single Schema for all TypeScript environments
• Manages ArangoDB Collections by deriving their information from entities classes
• Manages ArangoDB Indexes by decorating attributes with @Index(type, options)
• Auto Schema from types derives typing information into joi schemas
• Auto Documentation optimized swagger docs from types and decorators
• Route Decorators for creating and documenting Foxx.Routes as simple as @Route.POST(input => string()).
• Attribute-based authorization with reader and writer roles
• Route-based authorization with creators, readers, updaters and deleters
• Request-based authorization on entity- or global basis
• CRUD like route setup with @Route.use('GET', 'POST', ...)
• Custom Routes with input schemas and access roles
• Validate Input Data by describing the entity or providing joi schemas for routes
• Event Listener on a document or attribute basis to globally modify collection data
• Internationalize document values and return translated strings based upon the session or a parameter
• Advanced ReST features for returning lists and limiting output
• Logging integrated for an easy setup and debugging

💨 Shortcuts

• 🛫 Getting started
• 📘 Tutorial Examples
• 📗 API Reference

🌞 TypeArango is in development and will receive additional features. Contributors wanted 🙋

📝 Example

The example will setup a User entity stored inside a Users collection with a total of 6 documented routes.

Various other examples of how to use typeArango with certain features can be found in the 📘 examples folder.

import { Document, Entity, Type, Collection, Entities, Route, Authorized, Index, Related, Attribute, OneToMany, RouteArg } 
  from 'type-arango'

// `User` document entity
@Document() class User extends Entity {
    @Index(type => 'hash')
    @Attribute(str => str.email())
    email: string;
    
    @Attribute()
    name: string;
    
    @Authorized(readers => ['viewer','admin'], writers => ['admin'])
    @Attribute(nr => nr.min(0).max(100))
    rating: number;
    
    @Attribute()
    createdAt: Type.DateInsert;
    
    @OneToMany(type => Address, Address => Address.owner)
    addresses: Related<Address[]>;
}

// `Users` collection
@Collection(of => User)
@Route.groups(
    creators => ['guest'],
    readers => ['user','admin'],
    writers => ['viewer','admin'],
    deleters => ['admin']
)
@Route.use('GET','POST','PATCH','PUT','DELETE','LIST')
export class Users extends Entities {
    @Route.GET(
        path => ':id/addresses',
        roles => ['viewer'],
        summary => 'Returns User Address[]'
    ) static GET({param}: RouteArg){
        const user = Users.findOne(param.id);
        return user.relation('addresses');
    }
    
    @Route.GET(
        path => 'query',
        $ => ({
            id: $(String).required()
        }),
        roles => ['guest'],
        summary => 'Runs a query'
    )
    static QUERY({_, param: { id }}: RouteArg){
        return _`
            FOR item IN Items
                FILTER item.id == ${id}
                RETURN item
        `;
    }
}

⚡ World's fastest way to create documented endpoints

TypeArango uses the provided entity types to validate and document routes, for example a simple @Route.all creates five fully documented routes with a role system in place.

_{Screenshot from ArangoDBs Web Interface}

🛫 Getting started

1. Setup ArangoDB Foxx service

If you don't have a foxx service running yet, you can create one by using arangodb-typescript-setup.

TypeArango requires ArangoDB 3.4.4 or newer.

2. Install

yarn add --D type-arango

or

npm i --save-dev type-arango

3. Create the Entities

Read the 📘 Examples or dive into the 📗 API Reference

4. Setup

typeArango() has to be called before the entities are imported, it returns a function to be called after the decorators have been applied. It takes an optional 📝 Configuration argument.

shared/entities/index.ts:

import typeArango from 'type-arango'

const complete = typeArango({
    // Configuration
});

export * from './User';

complete();

5. Create routes

When using the @Route decorator, it is required to provide the Foxx.Router to TypeArango by calling createRoutes(router).

foxx-service/main.ts:

import createRouter from '@arangodb/foxx/router';
import {createRoutes} from 'type-arango';

// Initialize all entities before creating the routes
import * as _Entities from 'shared/entities';

// Create the foxx router and hand it to type-arango
const router = createRoutes( createRouter() );

As the routes are built by the @Route.* decorators, it is required to import all entities before calling createRoutes(Foxx.Router).

📚 Documentation

Read the 📘 Examples first, then dive into the 📗 API Reference.

🌻 Credits

• type-arango is inspired by TypeORM and type-graphql