Type-arango NPM

divider

⭐ 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

divider

💨 Shortcuts

divider

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

size

divider

📝 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.find(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`
    }
}

divider

⚡ 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.

Swagger Screenshot Screenshot from ArangoDBs Web Interface

divider

🛫 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.

divider

2. Install

yarn add --D type-arango

npm i --save-dev type-arango

divider

3. Create the Entities

Read the 📘 Examples or dive into the 📗 API Reference

divider

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()

divider

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).

divider