Skip to content

πŸ₯‘ TypeArango manages ArangoDB collections, documents, relations and routes by taking advantage of TypeScript typings.

License

Notifications You must be signed in to change notification settings

RienNeVaPlus/type-arango

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

TYPE-ARANGO

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.

divider

⭐ Features

divider

πŸ’¨ Shortcuts

divider

🌞 TypeArango is in development and will receive additional features. Contributors wanted πŸ™‹

Mentioned in Awesome ArangoDB last-commit version npm license 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

or

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

πŸ“š Documentation

Read the πŸ“˜ Examples first, then dive into the πŸ“— API Reference.

divider

🌻 Credits

About

πŸ₯‘ TypeArango manages ArangoDB collections, documents, relations and routes by taking advantage of TypeScript typings.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published