{ } qjs-modules

qjs-modules

qjs-modules builds qjsm, a QuickJS-based interpreter with both native C modules and JavaScript modules statically linked in. The modules themselves provide the runtime APIs plain QuickJS doesn't: console, fs, process, streams, sockets, XML/DOM, and more, modeled on their Node.js/Bun/Deno/browser equivalents so scripts written for those runtimes need few changes to run here. Some native modules wrap existing C libraries (libarchive, libmagic, the MariaDB/MySQL client, libpq, SQLite, libserialport, a bundled libbcrypt); the rest, and most of the JavaScript modules, are original implementations or ports of existing JavaScript libraries.

Every module can also be built standalone as a shared library and imported at runtime by any QuickJS build, independent of qjsm. Each quickjs-*.c file provides one native module.

Overview

  • qjsm — the interpreter binary this project builds (see qjsm below): QuickJS plus this project's modules statically linked in, so scripts get console, fs, process, and the rest without any setup.
  • Native C modules (quickjs-*.c, Module index below) — one QuickJS module per file, documented in doc/native/. Some wrap third-party C libraries (libarchive, libmagic, MariaDB/MySQL, libpq, SQLite, libserialport); others are original C implementations.
  • JavaScript modules (lib/*.js) — polyfills of standard APIs, higher-level wrappers over the native modules, and prototype extensions (Array, Map, …), documented in doc/js/.
  • Vendored C libraries (git submodules and bundled sources: libarchive, libbcrypt, libserialport, libutf, tutf8e) that some native modules build against or statically link.
  • Sibling projects (../qjs-lws, ../qjs-glfw, ../qjs-nanovg) — HTTP/WebSocket, windowing/GL, and 2D canvas support. Kept out of this repo so it stays installable on plain QuickJS without pulling in a network stack or a GPU-backed renderer; see Sibling Projects for why.

Building

cmake -B build .
make -C build

The core modules are always built. Some modules depend on external libraries and are gated by CMake options:

OptionModuleDependency
MODULE_ARCHIVEarchivelibarchive (BUILD_LIBARCHIVE builds the bundled one)
MODULE_BCRYPTbcryptbundled libbcrypt
MODULE_MAGICmagiclibmagic
MODULE_MYSQLmysqlMariaDB/MySQL client library
MODULE_PGSQLpgsqllibpq
MODULE_SQLITEsqlitesqlite3
MODULE_SERIALseriallibserialport (BUILD_LIBSERIALPORT builds the bundled one)

In addition to the native modules listed below, the lib/ directory contains pure-JavaScript modules (console, fs, process, repl, require, util, parsers, …) built on top of them; see doc/js/.

Module index

ModuleExportsDescription
archiveArchive, ArchiveEntry, ArchiveMatchRead/write archives via libarchive
arraybuffer_sinkArrayBufferSinkCollect streamed writes into an ArrayBuffer
bcryptgenSalt, hash, comparebcrypt password hashing
bjsonread, writeBinary JSON (QuickJS object serialization)
blobBlobW3C-style binary blob
child_processexec, spawn, ChildProcess, …Spawn and control subprocesses
deepfind, get, set, iterate, …Deep object-tree traversal and manipulation
directoryDirectoryLow-level directory reader (getdents)
gpioGPIOMemory-mapped GPIO (Raspberry Pi)
inspectinspectPretty-print JS values (like Node's util.inspect)
jsonread, write, JsonParserJSON parser/serializer with location info
lexerLexer, Token, LocationRegex-rule based tokenizer
listList, ListIterator, ListNodeDoubly-linked list with Array-like API
locationLocationSource position (file:line:column)
magicMagicFile type detection via libmagic
miscmany functionsGrab-bag of OS, buffer, type and engine utilities
mmapmmap, munmap, …Memory-mapped files as ArrayBuffers
mysqlMySQL, MySQLResult, MySQLErrorNon-blocking (promise-based) MySQL/MariaDB client
pathjoin, basename, resolve, …Path manipulation and filesystem tests
pgsqlPGconn, PGresult, PGerrorNon-blocking PostgreSQL client
pointerPointer, DereferenceErrorObject-graph paths (JSON-pointer-like)
predicatePredicateComposable, callable predicate functions
queueQueueChunked byte FIFO
repeaterRepeaterPush-to-async-iterator bridge
serialSerial, SerialPort, SerialErrorSerial ports via libserialport
socketsSocket, AsyncSocket, SockAddr, …BSD sockets, sync and async
sqliteSQLite3, SQLite3Result, SQLite3ErrorSQLite3 client
streamReadableStream, WritableStream, …WHATWG-style streams
syscallerrorSyscallErrorError class carrying syscall name + errno
textcodeTextDecoder, TextEncoderUTF-8/UTF-16/UTF-32 transcoding
tree_walkerTreeWalker, TreeIteratorDOM-TreeWalker-style object traversal
wasmModule, Instance, Memory, Table, Global, …WebAssembly JS API over wasm3 or WAMR
virtualVirtualPropertiesUniform property access over Map/Array/Object
yamlwriteBlock-YAML writer
xmlread, writeXML parser and serializer

qjsm

qjsm is the interpreter binary this project builds: QuickJS with a curated set of this project's modules statically linked in and registered as builtins, so scripts can import them without any dlopen()/module-path setup. Bare qjs (upstream QuickJS's own shell) has none of this — only std/os, and only when passed --std. qjsm also supports --std, but neither std nor os is loaded unless asked for; nothing here auto-injects globals a script didn't request.

Which modules are builtins is controlled by CMake variables, set at configure time:

VariableMeaningDefault
BUILTINS_COMPILEDPrecompiled JS modules (bytecode)assert console events fs module perf_hooks process repl timers tty url util
BUILTINS_NATIVENative C modules linked in directlypath stream yaml
BUILTINS_NATIVE_EXCLUDENative modules built but not registered as builtins (still importable via a .so, if BUILD_SHARED_MODULES built one)arraybuffer-sink child-process lexer location repeater tree-walker virtual
EXTERNAL_MODULESExternally-built modules (e.g. from ../qjs-glfw) to link in, via <name>_MODULE(empty)
BUILTIN_MODULESConvenience list: mixes module names and external-module build directories, auto-routed into the three variables above(empty)

BUILTINS_NATIVE's short default list isn't the full picture — any builtin's own transitive module dependencies (e.g. stream needs queue) are pulled in automatically by a dependency closure at configure time, regardless of BUILTINS_NATIVE_EXCLUDE. CommonJS require() (lib/require.js) is not a default builtin; add require to BUILTINS_COMPILED to get it.

Every builtin module can still be built as a standalone .so and imported at runtime instead of using the static build — BUILD_SHARED_MODULES/BUILD_STATIC_MODULES (both ON by default) build each module both ways independently. Static linking into qjsm is the convenient default, not the only way to consume a module.