🐜 Ant

Ant-sized JavaScript Runtime

A JavaScript runtime that fits in your pocket — Full async/await, modules, HTTP servers, crypto, and more.

📖 Read the blog post about Ant

Installation

curl -fsSL https://ant.themackabu.com/install | bash

# or with MbedTLS (darwin only)
curl -fsSL https://ant.themackabu.com/install | MBEDTLS=1 bash

Build from Source

meson setup build && meson compile -C build

Quick Example

See examples/server/server.js for a complete server example using Ant.serve() with rou3 routing, parameter handling, and various response types.

Modules

HTTP & Networking

Timers & Scheduling (built-in)

File System

js
import { readFile, writeFile } from 'ant:fs';

Async: readFile(), writeFile(), unlink(), mkdir(), rmdir(), readdir(), stat()

Sync: readFileSync(), writeFileSync(), unlinkSync(), mkdirSync(), rmdirSync(), readdirSync(), statSync()

Shell Commands

js
import { $ } from 'ant:shell';

const result = $`ls -la`;
console.log(result.text());

Child Process

js
import { spawn, exec } from 'child_process';

spawn(), exec(), execSync(), spawnSync(), fork(), kill()

Events: on('exit'), on('close'), on('error'), on('data')

Readline

js
import { createInterface } from 'readline';

createInterface(), question(), on('line'), on('close'), pause(), resume(), close()

Includes command history with navigation support.

OS

js
import os from 'os';

arch(), platform(), type(), release(), version(), hostname(), homedir(), tmpdir(), cpus(), totalmem(), freemem(), uptime(), networkInterfaces(), userInfo(), constants, EOL

Navigator

js
navigator.userAgent;            // User agent string
navigator.platform;             // Platform string
navigator.hardwareConcurrency;  // CPU thread count
navigator.locks;                // Web Locks API

Cryptography

js
crypto.random();           // Secure random number
crypto.randomBytes();      // Generate random bytes
crypto.randomUUID();       // UUID v4
crypto.randomUUIDv7();     // UUID v7 (time-ordered)
crypto.getRandomValues();  // Fill TypedArray with random values
btoa();                    // Base64 encoding (built-in)
atob();                    // Base64 decoding (built-in)

Path Utilities

js
import { join, resolve, basename } from 'ant:path';

basename(), dirname(), extname(), join(), resolve(), normalize(), isAbsolute()

Process

js
Ant.process.env;         // Environment variables (with .env support)
Ant.process.cwd;         // Current working directory
Ant.process.argv;        // Command line arguments
Ant.process.pid;         // Process ID
Ant.process.exit();      // Exit with code
Ant.process.cpuUsage();  // CPU usage statistics

Performance

js
performance.now();       // High-resolution timestamp
performance.timeOrigin;  // Time origin for measurements

Ant Global

js
Ant.version;    // Runtime version
Ant.target;     // Build target
Ant.revision;   // Git revision
Ant.buildDate;  // Build date
Ant.serve();    // Start HTTP server
Ant.signal();   // Register signal handlers
Ant.sleep();    // Sleep in seconds
Ant.msleep();   // Sleep in milliseconds
Ant.usleep();   // Sleep in microseconds
Ant.gc();       // Trigger garbage collection
Ant.alloc();    // Get memory allocation info
Ant.stats();    // Get runtime statistics
Ant.typeof();   // Get internal type name

Foreign Function Interface (FFI)

js
import { dlopen, define } from 'ant:ffi';

dlopen(), define(), alloc(), free(), read(), write(), callback(), freeCallback(), pointer(), readPtr(), suffix, FFIType

Binary Data

Buffers: ArrayBuffer, SharedArrayBuffer, Buffer

TypedArrays: Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, BigInt64Array, BigUint64Array

Utilities: DataView, TextEncoder, TextDecoder

Atomic Operations

js
Atomics.add()      Atomics.sub()       Atomics.and()
Atomics.or()       Atomics.xor()       Atomics.load()
Atomics.store()    Atomics.exchange()  Atomics.compareExchange()
Atomics.wait()     Atomics.notify()    Atomics.isLockFree()

Web Storage

localStorage (file-persistent):

js
localStorage.setFile('./data.json'); // Required before use
localStorage.setItem('key', 'value');
localStorage.getItem('key');

sessionStorage (in-memory): Same API without setFile().

Module System

js
import 'ant:fs'                 // Built-in fs module
import 'ant:path'               // Built-in path module
import 'ant:shell'              // Built-in shell module
import 'ant:ffi'                // Built-in FFI module
import 'node:*'                 // Node.js-style aliases
import from 'https://...'       // Import from URLs
import data from './data.json'  // JSON imports
import text from './file.txt'   // Text imports

TypeScript Support

Built-in TypeScript type stripping via oxc (no type checking, strip only):

./build/ant script.ts

Type annotations are stripped at parse time. Full type definitions available in src/types/.

JavaScript Features

ES1-ES5 Core

Automatic Semicolon Insertion (ASI), var hoisting, try/catch/finally, for...in loops, regular expressions, strict mode, Object.defineProperty(), Object.freeze()/seal()/preventExtensions(), Function.prototype.call/apply/bind, Array methods (map, filter, reduce, forEach, etc.), String methods, Math object, arguments object, labeled statements.

ES6+ Extensions

Async/await and Promises, arrow functions, classes with private fields (#privateField), template literals, destructuring, spread/rest operators, optional chaining (?.), nullish coalescing (??), logical assignment (??=, &&=, ||=), for...of loops, let/const, BigInt, numeric separators (1_000_000), Map/Set/WeakMap/WeakSet, Symbol, Proxy/Reflect, default parameters, computed property names, shebang support.

Concurrency

• Minicoro-based coroutines for async/await
• Event loop with microtask queue
• Atomic operations for lock-free concurrent programming
• SharedArrayBuffer for shared memory between workers
• Atomics.wait/notify for thread synchronization
• Virtual memory allocation for coroutine stacks

System

• Signal handlers (SIGINT, SIGTERM, etc.) via Ant.signal()
• Mark-copy compacting garbage collector + Boehm-Demers-Weiser
• libuv-based async I/O for files and networking
• TLS support via mbedtls or tlsuv
• LTO (Link Time Optimization) build support
• Gzip compression support for HTTP responses
• Native library integration via FFI

License

MIT License - See [LICENSE.txt](LICENSE.txt) for details.