{"id":13640459,"url":"https://github.com/Snapchat/ModJS","last_synced_at":"2025-04-20T02:33:44.376Z","repository":{"id":68337903,"uuid":"265036067","full_name":"Snapchat/ModJS","owner":"Snapchat","description":"A Javascript Module for KeyDB and Redis","archived":false,"fork":false,"pushed_at":"2023-03-19T22:18:55.000Z","size":78,"stargazers_count":196,"open_issues_count":8,"forks_count":10,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-08-03T01:16:53.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Snapchat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-05-18T19:07:39.000Z","updated_at":"2024-08-02T04:36:16.000Z","dependencies_parsed_at":"2024-01-14T09:11:55.647Z","dependency_job_id":"540791bf-ef46-480a-9b81-b6ae809e87a2","html_url":"https://github.com/Snapchat/ModJS","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snapchat%2FModJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snapchat%2FModJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snapchat%2FModJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snapchat%2FModJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Snapchat","download_url":"https://codeload.github.com/Snapchat/ModJS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223816598,"owners_count":17207887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:01:11.374Z","updated_at":"2024-11-09T10:31:15.926Z","avatar_url":"https://github.com/Snapchat.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# ModJS\nA Javascript Module for KeyDB and Redis.\n\nModJS 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.\n\n## Quick Start Guide\n\nThe fastest way to install ModJS is with \u003ca href=\"https://github.com/JohnSully/ModJS#docker-with-modjs\"\u003edocker\u003c/a\u003e.\n\nOnce installed there are two ways to use ModJS, the first is similar to Lua with the EVALJS Command:\n\n    \u003e EVALJS \"redis.call('get', 'testkey')\"\n    \nWhile EVALJS is quick and easy, a much more powerful method exists in the form of startup scripts. \nIn a startup script you can define your own custom commands and call them from any client as though they were built-in.  In addition,\nthese commands can skip the parsing step of EVALJS and so will execute much faster.\n\n### Adding a Command\n\nAll 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.\n\nBelow 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.\nWe then register this function with the server so that it will be directly callable from Redis or KeyDB clients.\n\n    function concat(key1, key2) {\n        var str1 = redis.call('get', key1);\n        var str2 = redis.call('get', key2);\n        return str1 + str2;\n    }\n    \n    keydb.register(concat);\n\n*Note: The redis and keydb objects may be used interchangebly.*\n\nTo run this script on startup simply add the path as a module parameter, e.g. ``loadmodule /path/to/modjs.so /path/to/startup.js``\n\nWe may now use this command from any client.  E.g.:\n\n    127.0.0.1:6379\u003e set keyA foo\n    OK\n    127.0.0.1:6379\u003e set keyB bar\n    OK\n    127.0.0.1:6379\u003e concat keyA keyB\n    \"foobar\"\n\n### Importing scripts from npm\n\nThe above examples were simple enough not to require external libraries, however for more complex tasks it may be desireable to import modules fetched via npm.  ModJS implements the require() api with similar semantics to node.js.  \n\nIn this example we will use the popular lodash library, installed with: ``npm install loadash``.  Below we've updated our example script to use the camelCase() function in lodash:\n\n    var _ = require(\"lodash\")\n\n    function concat(key1, key2) {\n        var str1 = redis.call('get', key1);\n        var str2 = redis.call('get', key2);\n        return _.camelCase(str1 + \" \" + str2)\n    }\n    \n    keydb.register(concat);\n\nThe lodash module is imported with require() as it would be in a node.js script.  Note that require() will search for modules starting from the working directory of Redis or KeyDB.  Once loaded this new script will concatenate the two strings using camel case.\n\nA quick note on compatibility:  ModJS does not implement most I/O functionality available in Node. As a result libraries that open files, sockets, etc may not run in ModJS.  This limitation is to ensure correct replication behavior of scripts.  In the future we may enable an unsafe mode that provides more of this functionality.\n\n### Consistency Gurantees and Programming Model\n\nModJS 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.  \n\nGlobal 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. \n\n# Compiling ModJS\n\nModJS requires you to first build V8, as a result we recommend using a pre-compiled docker image.  However if you wish to compile ModJS first follow the instructions to download and build V8 here: https://v8.dev/docs/build\n\nOnce you have built the core V8 library we must then build the monolith with the following command:\n\n    /path/to/v8/$ ninja -C out.gn/x64.release.sample v8_monolith \n    \nIf V8 compiled successfully you are now ready to build ModJS.  ModJS can be built with one line:\n\n    make V8_PATH=/path/to/v8\n    \n\n## Docker with ModJS\n\n* Visit the official Docker Repository here: [eqalpha/modjs](https://hub.docker.com/r/eqalpha/modjs)\n* Dockerfiles can be found [here](https://github.com/JohnSully/ModJS/tree/master/Dockerfiles)\n\n### Launch a container with ModJS\n\n\u003cb\u003eKeyDB:\u003c/b\u003e\n```\n$ sudo docker run eqalpha/modjs\n```\n\n\u003cb\u003eRedis\u003c/b\u003e\n```\n$ sudo docker run eqalpha/modjs:redis-latest\n```\n\n\u003cb\u003eLaunch container bound to host:\u003c/b\u003e\n```\n$ sudo docker run -p 6379:6379 eqalpha/modjs\n```\n\n### Launch with Startup Script\n\nWhen 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:\n\n\u003cb\u003eWith Redis:\u003c/b\u003e\n```\n$ 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\n```\n\n\u003cb\u003eWith KeyDB:\u003c/b\u003e\n```\n$ 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\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnapchat%2FModJS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSnapchat%2FModJS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnapchat%2FModJS/lists"}