themackabu.com / ant
MIRROR: javascript for 🐜's, a tiny runtime with big ambitions
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

shrink readme.md, plan for docs.md

theMackabu 297d89a9 15a0ae49

+5 -242
+5 -242
README.md
··· 2 2 3 3 **Ant-sized JavaScript Runtime** 4 4 5 - A JavaScript runtime that fits in your pocket — Full async/await, modules, HTTP servers, crypto, and more. 5 + A JavaScript runtime that fits in your pocket. <br> 6 + Full async/await, modules, HTTP servers, crypto, and more. 6 7 7 8 📖 [Read the blog post about Ant](https://s.tail.so/js-in-one-month) 8 9 ··· 18 19 ## Build from Source 19 20 20 21 ```bash 21 - meson setup build && meson compile -C build 22 - ``` 23 - 24 - ## Quick Example 25 - 26 - See `examples/server/server.js` for a complete server example using `Ant.serve()` with `rou3` routing, parameter handling, and various response types. 27 - 28 - ## Modules 29 - 30 - ### HTTP & Networking 31 - 32 - | API | Description | 33 - | ------------- | ----------------------------------------------- | 34 - | `Ant.serve()` | HTTP server with uv_tcp (TLS support via tlsuv) | 35 - | `fetch()` | HTTP client with TLS support (GET, POST, etc.) | 36 - | URL imports | Import directly from URLs | 37 - 38 - ### Timers & Scheduling (built-in) 39 - 40 - | API | Description | 41 - | ------------------ | ---------------------------------------- | 42 - | `setTimeout()` | Execute callback after delay | 43 - | `setInterval()` | Execute callback repeatedly | 44 - | `setImmediate()` | Execute callback on next event loop tick | 45 - | `clearTimeout()` | Cancel scheduled timeout | 46 - | `clearInterval()` | Cancel scheduled interval | 47 - | `queueMicrotask()` | Queue microtask for execution | 48 - 49 - ### File System 50 - 51 - ```js 52 - import { readFile, writeFile } from 'ant:fs'; 53 - ``` 54 - 55 - **Async:** 56 - `readFile()`, `writeFile()`, `unlink()`, `mkdir()`, `rmdir()`, `readdir()`, `stat()` 57 - 58 - **Sync:** 59 - `readFileSync()`, `writeFileSync()`, `unlinkSync()`, `mkdirSync()`, `rmdirSync()`, `readdirSync()`, `statSync()` 60 - 61 - ### Shell Commands 62 - 63 - ```js 64 - import { $ } from 'ant:shell'; 65 - 66 - const result = $`ls -la`; 67 - console.log(result.text()); 68 - ``` 69 - 70 - | Property | Description | 71 - | ----------------- | ---------------------------- | 72 - | `result.text()` | Get stdout as string | 73 - | `result.lines()` | Get stdout as array of lines | 74 - | `result.exitCode` | Command exit code | 75 - | `result.stdout` | Raw stdout | 76 - | `result.stderr` | Raw stderr | 77 - 78 - ### Child Process 79 - 80 - ```js 81 - import { spawn, exec } from 'child_process'; 82 - ``` 83 - 84 - `spawn()`, `exec()`, `execSync()`, `spawnSync()`, `fork()`, `kill()` 85 - 86 - Events: `on('exit')`, `on('close')`, `on('error')`, `on('data')` 87 - 88 - ### Readline 89 - 90 - ```js 91 - import { createInterface } from 'readline'; 92 - ``` 93 - 94 - `createInterface()`, `question()`, `on('line')`, `on('close')`, `pause()`, `resume()`, `close()` 95 - 96 - Includes command history with navigation support. 97 - 98 - ### OS 99 - 100 - ```js 101 - import os from 'os'; 102 - ``` 103 - 104 - `arch()`, `platform()`, `type()`, `release()`, `version()`, `hostname()`, `homedir()`, `tmpdir()`, `cpus()`, `totalmem()`, `freemem()`, `uptime()`, `networkInterfaces()`, `userInfo()`, `constants`, `EOL` 105 - 106 - ### Navigator 107 - 108 - ```js 109 - navigator.userAgent; // User agent string 110 - navigator.platform; // Platform string 111 - navigator.hardwareConcurrency; // CPU thread count 112 - navigator.locks; // Web Locks API 22 + meson subprojects download 23 + meson setup build 24 + meson compile -C build 113 25 ``` 114 - 115 - ### Cryptography 116 - 117 - ```js 118 - crypto.random(); // Secure random number 119 - crypto.randomBytes(); // Generate random bytes 120 - crypto.randomUUID(); // UUID v4 121 - crypto.randomUUIDv7(); // UUID v7 (time-ordered) 122 - crypto.getRandomValues(); // Fill TypedArray with random values 123 - btoa(); // Base64 encoding (built-in) 124 - atob(); // Base64 decoding (built-in) 125 - ``` 126 - 127 - ### Path Utilities 128 - 129 - ```js 130 - import { join, resolve, basename } from 'ant:path'; 131 - ``` 132 - 133 - `basename()`, `dirname()`, `extname()`, `join()`, `resolve()`, `normalize()`, `isAbsolute()` 134 - 135 - ### Process 136 - 137 - ```js 138 - Ant.process.env; // Environment variables (with .env support) 139 - Ant.process.cwd; // Current working directory 140 - Ant.process.argv; // Command line arguments 141 - Ant.process.pid; // Process ID 142 - Ant.process.exit(); // Exit with code 143 - Ant.process.cpuUsage(); // CPU usage statistics 144 - ``` 145 - 146 - ### Performance 147 - 148 - ```js 149 - performance.now(); // High-resolution timestamp 150 - performance.timeOrigin; // Time origin for measurements 151 - ``` 152 - 153 - ### Ant Global 154 - 155 - ```js 156 - Ant.version; // Runtime version 157 - Ant.target; // Build target 158 - Ant.revision; // Git revision 159 - Ant.buildDate; // Build date 160 - Ant.serve(); // Start HTTP server 161 - Ant.signal(); // Register signal handlers 162 - Ant.sleep(); // Sleep in seconds 163 - Ant.msleep(); // Sleep in milliseconds 164 - Ant.usleep(); // Sleep in microseconds 165 - Ant.gc(); // Trigger garbage collection 166 - Ant.alloc(); // Get memory allocation info 167 - Ant.stats(); // Get runtime statistics 168 - Ant.typeof(); // Get internal type name 169 - ``` 170 - 171 - ### Foreign Function Interface (FFI) 172 - 173 - ```js 174 - import { dlopen, define } from 'ant:ffi'; 175 - ``` 176 - 177 - `dlopen()`, `define()`, `alloc()`, `free()`, `read()`, `write()`, `callback()`, `freeCallback()`, `pointer()`, `readPtr()`, `suffix`, `FFIType` 178 - 179 - ### Binary Data 180 - 181 - **Buffers:** `ArrayBuffer`, `SharedArrayBuffer`, `Buffer` 182 - 183 - **TypedArrays:** `Int8Array`, `Uint8Array`, `Uint8ClampedArray`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array`, `Float32Array`, `Float64Array`, `BigInt64Array`, `BigUint64Array` 184 - 185 - **Utilities:** `DataView`, `TextEncoder`, `TextDecoder` 186 - 187 - ### Atomic Operations 188 - 189 - ```js 190 - Atomics.add() Atomics.sub() Atomics.and() 191 - Atomics.or() Atomics.xor() Atomics.load() 192 - Atomics.store() Atomics.exchange() Atomics.compareExchange() 193 - Atomics.wait() Atomics.notify() Atomics.isLockFree() 194 - ``` 195 - 196 - ### Web Storage 197 - 198 - **localStorage** (file-persistent): 199 - 200 - ```js 201 - localStorage.setFile('./data.json'); // Required before use 202 - localStorage.setItem('key', 'value'); 203 - localStorage.getItem('key'); 204 - ``` 205 - 206 - **sessionStorage** (in-memory): Same API without `setFile()`. 207 - 208 - ### Module System 209 - 210 - ```js 211 - import 'ant:fs' // Built-in fs module 212 - import 'ant:path' // Built-in path module 213 - import 'ant:shell' // Built-in shell module 214 - import 'ant:ffi' // Built-in FFI module 215 - import 'node:*' // Node.js-style aliases 216 - import from 'https://...' // Import from URLs 217 - import data from './data.json' // JSON imports 218 - import text from './file.txt' // Text imports 219 - ``` 220 - 221 - ## TypeScript Support 222 - 223 - Built-in TypeScript type stripping via oxc (no type checking, strip only): 224 - 225 - ```bash 226 - ./build/ant script.ts 227 - ``` 228 - 229 - Type annotations are stripped at parse time. Full type definitions available in `src/types/`. 230 - 231 - ## JavaScript Features 232 - 233 - ### ES1-ES5 Core 234 - 235 - 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. 236 - 237 - ### ES6+ Extensions 238 - 239 - 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. 240 - 241 - ## Concurrency 242 - 243 - - Minicoro-based coroutines for async/await 244 - - Event loop with microtask queue 245 - - Atomic operations for lock-free concurrent programming 246 - - SharedArrayBuffer for shared memory between workers 247 - - Atomics.wait/notify for thread synchronization 248 - - Virtual memory allocation for coroutine stacks 249 - 250 - ## System 251 - 252 - - Signal handlers (SIGINT, SIGTERM, etc.) via `Ant.signal()` 253 - - Mark-copy compacting garbage collector + Boehm-Demers-Weiser 254 - - libuv-based async I/O for files and networking 255 - - TLS support via mbedtls or tlsuv 256 - - LTO (Link Time Optimization) build support 257 - - Gzip compression support for HTTP responses 258 - - Native library integration via FFI 259 - 260 - ## License 261 - 262 - MIT License - See [LICENSE.txt](LICENSE.txt) for details.