7.2 KiB

Raw Blame History

JavaScript Modules

@NAVIGATE_JSModules @EMBEDTOC{JSModulesTOC}

Introduction to Javascript Modules

The ArangoDB uses a CommonJS compatible module and package concept. You can use the function require in order to load a module or package. It returns the exported variables and functions of the module or package.

There are some extensions to the CommonJS concept to allow ArangoDB to load Node.js modules as well.

CommonJS Modules

Unfortunately, the JavaScript libraries are just in the process of being standardized. CommonJS has defined some important modules. ArangoDB implements the following

"console" is a well known logging facility to all the JavaScript developers. ArangoDB implements all of the functions described here, with the exceptions of profile and count.
"fs" provides a file system API for the manipulation of paths, directories, files, links, and the construction of file streams. ArangoDB implements most of Filesystem/A functions described here.
Modules are implemented according to Modules/1.1.1
Packages are implemented according to Packages/1.0

ArangoDB Specific Modules

A lot of the modules, however, are ArangoDB specific. These modules are described in the following chapters.

Node Modules

ArangoDB also support some node modules.

"assert" implements assertion and testing functions.
"buffer" implements a binary data type for JavaScript.
"path" implements functions dealing with filenames and paths.
"punycode" implements conversion functions for punycode encoding.
"querystring" provides utilities for dealing with query strings.
"stream" provides a streaming interface.
"url" has utilities for URL resolution and parsing.

Node Packages

The following node packages are preinstalled.

"buster-format"
"Cheerio.JS"
"coffee-script" implements a coffee-script to JavaScript compiler. ArangoDB supports the compile function of the package, but not the eval functions.
"htmlparser2"
"Sinon.JS"
"underscore" is a utility-belt library for JavaScript that provides a lot of the functional programming support that you would expect in Prototype.js (or Ruby), but without extending any of the built-in JavaScript objects.

require

@FUN{require(@FA{path})}

@FN{require} checks if the module or package specified by @FA{path} has already been loaded. If not, the content of the file is executed in a new context. Within the context you can use the global variable exports in order to export variables and functions. This variable is returned by @FN{require}.

Assume that your module file is test1.js and contains

exports.func1 = function() {
  print("1");
};

exports.const1 = 1;

Then you can use @FN{require} to load the file and access the exports.

unix> ./arangosh
arangosh> var test1 = require("test1");

arangosh> test1.const1;
1

arangosh> test1.func1();
1

@FN{require} follows the specification Modules/1.1.1.

Modules Path versus Modules Collection

ArangoDB comes with predefined modules defined in the file-system under the path specified by @CO{startup.startup-directory}. In a standard installation this point to the system share directory. Even if you are an administrator of ArangoDB you might not have write permissions to this location. On the other hand, in order to deploy some extension for ArangoDB, you might need to install additional JavaScript modules. This would require you to become root and copy the files into the share directory. In order to ease the deployment of extensions, ArangoDB uses a second mechanism to look up JavaScript modules.

JavaScript modules can either be stored in the filesystem as regular file or in the database collection _modules.

If you execute

require("com/example/extension")

then ArangoDB will try to locate the corresponding JavaScript as file as follows

There is a cache for the results of previous require calls. First of all ArangoDB checks if com/example/extension is already in the modules cache. If it is, the export object for this module is returned. No further JavaScript is executed.
ArangoDB will then check, if there is a file called

com/example/extension.js

in the system search path. If such a file exists, it is executed in a new module context and the value of exports object is returned. This value is also stored in the module cache.
If no file can be found, ArangoDB will check if the collection _modules contains a document of the form
```
{
  path: "/com/example/extension",
  content: "...."
}
```
Note that the leading /´ is important - even if you call requirewithout a leading/´. If such a document exists, then the value of the content attribute must contain the JavaScript code of the module. This string is executed in a new module context and the value of exports object is returned. This value is also stored in the module cache.

Modules Cache

As require uses a module cache to store the exports objects of the required modules, changing the design documents for the modules in the _modules collection might have no effect at all.

You need to clear the cache, when manually changing documents in the _modules collection.

arangosh> require("internal").flushServerModules()

This initiate a flush of the modules in the ArangoDB server process.

Please note, that the ArangoDB JavaScript shell uses the same mechanism as the server to locate JavaScript modules. But the do not share the same module cache. If you flush the server cache, this will not flush the shell cache - and vice versa.

In order to flush the modules cache of the JavaScript shell, you should use

arangosh> require("internal").flushModuleCache()

@BNAVIGATE_JSModules

7.2 KiB Raw Blame History Unescape Escape