Overview

Relevant source files

• .github/agents/route_validation.js
• AGENTS.md
• ARCHITECTURE.md
• CONTRIBUTING.md
• README.md
• SECURITY.md
• docs/repo/testing.md
• examples/jit/run.js
• examples/server/server.js
• include/ant.h
• include/internal.h
• meson.build
• src/ant.c
• src/main.c
• src/modules/fetch.c
• src/modules/io.c
• src/modules/server.c
• tests/test_array_flat_prototype_indices.cjs
• tests/test_concurrent_scope.cjs
• tests/test_fs_error_messages.cjs

This page provides a high-level introduction to the Ant JavaScript runtime, covering its design philosophy, core architectural components, and key subsystems.

Purpose and Scope

Ant is a lightweight, high-performance JavaScript runtime built from scratch in C. It executes JavaScript and TypeScript code using a custom bytecode virtual machine (Silver VM) and a 64-bit NaN-boxing value representation src/ant.c77-86 include/internal.h16-54 It is specifically designed for environments where binary size and startup time are critical, such as serverless functions, edge computing, and CLI tools README.md37-40

The runtime features:

• A custom-built engine, Ant Silver, rather than a wrapper around V8 or JSC README.md33-35
• A compact binary size of approximately 9MB (or ~6MB with -Os) README.md9-14
• Rapid cold start times (~5ms) README.md32 README.md74-77
• Integrated package management via a Zig-based component libpkg.a meson.build89-109
• Native TypeScript support via type stripping using the OXC Rust library src/main.c23-25 AGENTS.md38-39
• A built-in high-performance HTTP server API via Ant.serve() src/modules/server.c34-44

Sources: src/ant.c77-86 README.md1-40 meson.build89-109 src/main.c23-25 src/modules/server.c34-44 AGENTS.md38-39

Design Philosophy

Ant is built around several core technical principles:

• Compact Value Representation: Uses 64-bit NaN-boxing to store all JavaScript types (numbers, objects, strings, booleans) in a single ant_value_t (uint64_t) src/ant.c77-79 include/internal.h51-54
• Efficient Execution: The Silver VM uses a stack-based architecture and a JIT compiler powered by a fork of the MIR backend to enable near-compiled performance README.md39-40 src/ant.c33-35
• Native TypeScript Execution: Rather than external transpilation, Ant integrates the OXC Rust library to strip type annotations at load time src/main.c25
• Memory Efficiency: Employs a virtual memory arena system include/internal.h9-12 and a mark-and-compact garbage collector src/ant.c24-25
• Node.js Compatibility: Implements a significant subset of Node.js APIs (e.g., fs, path, process, buffer) to support existing ecosystem tools src/main.c38-103

Sources: src/ant.c77-86 src/main.c1-110 README.md1-40 src/ant.c24-25 include/internal.h9-54

Core Runtime Architecture

The Ant runtime is structured around a central context structure ant_isolate_t (often referred to via the ant_t typedef) that coordinates all major subsystems include/internal.h136-268

Runtime Context Diagram

Sources: include/ant.h40-53 src/ant.c23-35 src/main.c12-28 include/internal.h136-268

Initialization and Lifecycle

1. Context Creation: js_create_dynamic() initializes the ant_t runtime structure include/ant.h41
2. Runtime Setup: Built-in modules like fs, os, and process are registered via src/main.c to provide the standard environment src/main.c38-103
3. Code Loading: Source code is read; if it is TypeScript, it is stripped via the OXC library integration src/main.c25
4. Bytecode Execution: The compiler generates bytecode which is executed by functions like js_eval_bytecode() include/ant.h47-51
5. Event Loop: The system integrates with libuv to manage asynchronous tasks like promises and timers src/ant.c39 src/main.c20

Sources: src/main.c1-110 include/ant.h40-53 src/ant.c39

Value Representation (NaN-Boxing)

Ant uses a 64-bit ant_value_t to represent all values. This relies on the IEEE 754 specification where specific NaN patterns are used as "tags" for non-numeric types include/internal.h16-54

NaN-Boxing Bit Layout

Sources: include/internal.h16-125 src/ant.c77-86 include/ant.h36-38

Encoding and Decoding Logic

Function	Description	File
tov(double d)	Converts a C double to an ant_value_t, canonicalizing NaNs.	src/ant.c210-216
tod(ant_value_t v)	Converts an ant_value_t back to a C double.	src/ant.c218-220
vtype(ant_value_t val)	Extracts the type tag from a value using NANBOX_TYPE_SHIFT.	include/ant.h163 include/internal.h52
vdata(ant_value_t v)	Extracts the 47-bit data/payload using NANBOX_DATA_MASK.	src/ant.c226-228 include/internal.h53
js_obj_ptr(ant_value_t v)	Converts a tagged object value into a raw C pointer to ant_object_t.	src/ant.c230-234

Sources: src/ant.c210-234 include/ant.h163 include/internal.h51-54

Execution Model

The execution pipeline transforms source code into executable bytecode for the Silver VM.

Execution Pipeline

Sources: src/ant.c33-35 src/main.c25 README.md39-40

Key Components:

• Type Stripping: Uses the oxc library (integrated via the Skim subproject) to remove TypeScript types, allowing the runtime to execute .ts files directly src/main.c25 AGENTS.md38-39
• Lexer/Compiler: Tokenizes and compiles source code into internal bytecode instructions src/ant.c33-34 src/ant.c34-35
• Silver VM: A custom interpreter that executes the generated bytecode src/ant.c35
• JIT: High-performance execution path using the MIR backend for hot code README.md39-40

Sources: src/ant.c33-35 README.md39-40 src/main.c25 AGENTS.md38-39

Memory and Garbage Collection

Ant manages memory using a custom allocation system and a garbage collector.

• Garbage Collector: A mark-and-compact GC traces roots to reclaim memory. It is integrated into the core runtime src/ant.c24-25
• String Interning: To optimize property lookups, Ant maintains a table of interned strings using interned_string_t buckets src/ant.c88-112
• Asynchronous Execution: Coroutines (via minicoro.h) are used to implement async/await and generators, integrated with the libuv event loop src/ant.c39-52 include/internal.h251
• Promise System: A built-in promise registry tracks pending tasks and their handlers via ant_promise_state_t src/ant.c148-208

Sources: src/ant.c24-52 src/ant.c88-112 src/ant.c148-208 include/internal.h251

Built-in Modules and Globals

Ant provides a rich set of built-in modules, many of which are Node.js compatible.

Module	Purpose	Source
process	Global process information (argv, env, exit).	src/main.c59
fs	File system operations (read, write, stat).	src/main.c50
buffer	Binary data manipulation and TypedArrays.	src/main.c46
fetch	Promise-based HTTP client via tlsuv.	src/main.c55 src/modules/fetch.c31-52
ffi	Foreign Function Interface for calling C libraries.	src/main.c62
server	High-performance HTTP server API (Ant.serve).	src/main.c52 src/modules/server.c112-137
pkg	Integrated package manager commands (init, install, add, etc.).	src/main.c129-145
io	Console and TTY management with color support.	src/modules/io.c35-66

Sources: src/main.c38-103 src/main.c129-145 src/modules/fetch.c31-52 src/modules/server.c112-137 src/modules/io.c35-66

Build System

The project uses Meson as its primary build system, coordinating C, Rust, and Zig components.

• Meson Configuration: meson.build defines the project, including high-level optimization settings (-O3) and LTO meson.build1-9
• Multi-Language Integration:
  • C: Core runtime and Silver VM meson.build71-87
  • Rust: OXC library for TypeScript stripping src/main.c25
  • Zig: Package manager logic compiled as libpkg.a via pkg_zig target meson.build89-109
• Code Generation: Python scripts generate internal headers for messages (messages.h) and themes (theme.h) meson.build58-70

Sources: meson.build1-152