eqalpha/modjs repository overview

⁠About ModJS: A Javascript Module for KeyDB and Redis.

ModJS allows you to extend Redis and KeyDB with new functionality implemented in JavaScript (ES6). ModJS uses the V8 JIT engine so complex scripts can execute significantly faster than their Lua equivalents. In addition ModJS supports many node.js modules offering extensive library support for common tasks.

⁠Supported tags and respective Dockerfile links

Dockerfiles are provided as common wrappers to commonly used Redis images and KeyDB. Click links to see the associated Dockerfiles

• keydb-latest, latest⁠
• redis-latest⁠

Tags are also generated to show historic builds referencing both the ModJS version and the KeyDB version: eqalpha/modjs:modjs_vx.x.x-keydb_vx.x.x or eqalpha/modjs:modjs_vx.x.x-redis_vx.x.x

⁠Additional Resources:

• ModJS Github Repo⁠
• License (LGPL-2.1)⁠
• KeyDB Docs⁠

⁠Quick Start Guide

⁠Launch a ModJS docker container

KeyDB:

$ sudo docker run eqalpha/modjs

Redis

$ sudo docker run eqalpha/modjs:redis-latest

Launch container bound to host:

$ sudo docker run -p 6379:6379 eqalpha/modjs

⁠Using ModJS

There are two ways to use ModJS, the first is similar to Lua with the EVALJS Command:

    > EVALJS "redis.call('get', 'testkey')"

While EVALJS is quick and easy, a much more powerful method exists in the form of startup scripts. In a startup script you can define your own custom commands and call them from any client as though they were built-in. In addition, these commands can skip the parsing step of EVALJS and so will execute much faster.

⁠Adding a Command

All commands must be defined at the time the module is loaded in a startup script. A startup script is simply a javascript file who's path is passed to ModJS at load time.

Below we create an example script named startup.js which defines a new command named "concat". This command fetches two keys and returns the string concatenation of the two values. We then register this function with the server so that it will be directly callable from Redis or KeyDB clients.

startup.js

    function concat(key1, key2) {
        var str1 = redis.call('get', key1);
        var str2 = redis.call('get', key2);
        return str1 + str2;
    }
    
    keydb.register(concat);

Note: The redis and keydb objects may be used interchangebly.

⁠Launch Startup Script

To run this script on startup simply add the path as a module parameter, to your keydb.conf/redis.conf file e.g. loadmodule /path/to/modjs.so /path/to/startup.js or specify the path when launching the container.

When launching with the docker container you will need to share your script with the docker container by mounting it as a volume to the "scripts" volume in the container:

With Redis:

$ sudo  docker  run  -p  6379:6379  -v  /path/to/startupjs/vol:/scripts  eqalpha/modjs:redis-latest  redis-server  --loadmodule  /usr/lib/keydb/modules/modjs.so /scripts/startup.js

With KeyDB:

$ sudo  docker  run  -p  6379:6379  -v  /path/to/startupjs/vol:/scripts  eqalpha/modjs  keydb-server  /etc/keydb/keydb.conf  --loadmodule  /usr/lib/keydb/modules/modjs.so  /scripts/startup.js

We may now use this command from any client. E.g.:

    127.0.0.1:6379> set keyA foo
    OK
    127.0.0.1:6379> set keyB bar
    OK
    127.0.0.1:6379> concat keyA keyB
    "foobar"

⁠Consistency Gurantees and Programming Model

ModJS offers the same consistency gurantees as provided with Lua scripts. Each JS command is executed atomically regardless of whether EVALJS or registered commands are used.

Global variables and functions created in startup sripts are available for subsequent use in registered commands and EVALJS functions. Modules imported via the require() method exist in their own javascript context and may only export via the exports object.