type-arango

type-arango copied to clipboard

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.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`
    }
}

⚡ 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