Using Typescript for programming ArangoDB FOXX services

Going back from Typescript to Javascript for programming Foxx services for ArangoDB was a nuisance. The documentation informs that it is possible to use typescript to program the Foxx services and after some searching I’ve found that there is not much information about the subject. Maybe because it is really not that difficult, since the Foxx services are essentially Node modules. Searching for programming Node modules in typescript set me in the right direction. Although I’ve had to take care of some particularities, hence this article.

This article depicts a startup repository and its structure for programming Foxx services using Typescript 2.0. Foxx services are attached to a particular database and allow to build a web-accessible API for your database.

This project assumes that:

  • an ArangoDB database is created
  • a Foxx Service is initialized and on development mode

Which you can learn about on the ArangoDB documentation.

Now let’s followup on this project options and particularities.

Source Files

The source files for the Foxx service are on the folder “db/src” of the project. This is completely customizable. I’ve chosen not to put the source files on the root, so one can see the references to the source folder explicitly.

On this folder there are two types of files:

  • *.ts
  • manifest.json

The typescript files will be compiled and their output files – in javascript – will be written directly to the Foxx service path on the database folder. Since the Foxx service is on development mode, the database server will pickup files when they change.

The file manifest.json is completely independent of making the service in typescript or javascript. It pertains to your service configuration, so this project does not provide any management for it. I’ve included it for completeness.

Typescript Configuration

This project assumes the typescript compiler is ran on the “db” folder. This allows to have a compiler running for the db foxx service and other running on the root for the other project files. Of course, I’m assuming a project where the database service is only a part of the development. If the project is only about this database service, all can go to the project’s root folder.

On the “tsconfig.json” file only three entries matter to this project:

  • “target”: “es2015”. The Foxx service javascript files can be in ES2015 although the full support for that specification is being develop (ArangoDB uses the V8 engine). If problems arise, just change this to “es5”.
  • “module”: “commonjs”. Since a Foxx service is a Node module, the module resolution must be the one that Node uses.
  • “outDir”. Just use a relative or absolute path to the folder of the Foxx service on the database.

The “tsconfig.json” file on this project also have a “watch:true” entry. This allows to the compiler to enter a loop compiling on every change of the source files.

Module Resolution

Since the Foxx service files will be run by the database server outside of this project context, there is a difference with module resolution from when compiling to when running.

ArangoDB installation provides a number of Node modules pre-installed and readily available to the Foxx services. When referring to these external module in typescript you should use something like:

import arangodb = require('@arangodb');
import joi = require('joi');

But this poses a problem. The “@arangodb” and “joi” modules are available when the service will be run but not when the typescript files are compiled, within our project. For the “joi” module one solution is to install it on our project, but not so fast with the “@arangodb”. And in fact what is really needed are the typescript types or at least the module presence (when types are not available).

This is solved in two ways.

For the “joi” reference, there are typescript types available (npm package “@types/joi”), so just install it. An extract of the “package.json” file:

"devDependencies": {
 "@types/joi": "^9.0.32",
 "@types/node": "^6.0.45",
 "typescript": "^2.0.3" }

The Node environment will also be referenced, so it must also be installed. Hence the two packages references on package.json. One thing to keep paired are the versions of the types packages and the real packages in use on the ArangoDB database installation, since they must be manually synched.

The other reference, “@arangodb”, has no types available (as I know of) so we’ll just have to make it known to the typescript compiler by means of the file “declarations.d.ts”:

declare module "@arangodb";
declare module "@arangodb/*";

interface NodeModule {
 context: any

The “interface” statement above matches the “context” property that the Foxx Services environment adds to the module where the main javascript file is called.

The only purpose of this “declarations.d.ts” file is to silent some errors of the typescript compiler.

And that’s all. Have some Typescript fun!



Leave a Reply

Your email address will not be published. Required fields are marked *