<div align="center">

above logo does not represent any religious affiliation , it is simply a stylized representation of "Xmas" as in "ECMAScript".

Xmas.JS

A Modern System Scripting Runtime for the JavaScript Era

Features • Installation • Quick Start • Benchmarks • Documentation • Contributing

</div>

---

🎯 What is Xmas.JS?

Xmas.JS is a lightweight, high-performance JavaScript/TypeScript runtime designed to replace traditional system scripting languages like Lua, Perl, and Python for system administration, automation, and glue code tasks.

Unlike Node.js, Deno, or Bun which target web applications and server-side development, Xmas.JS is purpose-built for:

• 🔧 System scripting and automation - Replace Bash, PowerShell, Python scripts
• ⚡ Serverless and edge computing - Cold start in milliseconds, not seconds
• 🪶 Embedded scripting - Minimal memory footprint (<5MB)
• 🔌 CLI tools and utilities - Fast startup for command-line applications
• 🧩 System integration - Native Rust modules for deep system access

Note: The word "Xmas" is pronounced like "ECMAS" (ECMAScript), not a religious reference. "JavaScript" in this context refers to ECMAScript/TypeScript, not Oracle's JavaScript™ trademark.

---

🚀 Why Xmas.JS?

The Problem with Existing Runtimes

QuickJS does not use any sort of JIT compilation, making it ideal for fast startup and low memory usage, but less suited for long-running web servers.

Modern JavaScript runtimes like Node.js, Deno, and Bun are excellent for web servers and applications, but they're overkill for scripting:

| Runtime | Cold Start | Memory (Idle) | Best Use Case | | ----------- | ----------- | ------------- | ----------------------------------------- | | Node.js | ~100-200ms | ~30-50MB | Web servers, long-running apps | | Deno | ~150-300ms | ~40-60MB | Secure web apps, TypeScript projects | | Bun | ~50-100ms | ~25-35MB | Fast web development | | Xmas.JS | ~5-15ms | ~3-8MB | System scripts, CLI tools, serverless |

The Xmas.JS Difference

Traditional System Scripts          Modern System Scripts with Xmas.JS
┌─────────────────────────┐        ┌─────────────────────────┐
│  Python + libraries     │        │  Xmas.JS + TypeScript   │
│  Slow startup           │   →    │  Instant startup        │
│  Heavy dependencies     │        │  Zero dependencies      │
│  Version hell           │        │  Single binary          │
│  Limited async          │        │  Native async/await     │
└─────────────────────────┘        └─────────────────────────┘

Performance Targets:

• ⚡ 10x faster startup than Node.js/Deno
• 💰 2x lower cost on serverless platforms
• 🪶 5x smaller memory footprint than traditional runtimes
• 🔥 Native performance via Rust integration

---

✨ Features

Core Capabilities

• ✅ WinterTC Compatible APIs - Standard Web APIs (fetch, crypto, streams, etc.)
• ✅ Modern JavaScript/TypeScript - Full ES2023+ support including async/await, modules, decorators
• ✅ Ultra-Fast Startup - Cold start in ~5-15ms, perfect for CLI and serverless
• ✅ Minimal Memory Footprint - Runs comfortably in <5MB RAM
• ✅ Async I/O - Powered by Tokio for high-performance concurrent operations
• ✅ Rust Extensions - Native module system for system-level access
• ✅ Interactive REPL - Built-in read-eval-print loop for rapid prototyping

In Development

• 🚧 Package Manager - Built-in dependency management (no need for npm/pnpm)
• 🚧 Cross-Platform Shell - Execute package.json scripts anywhere
• 🚧 Built-in Toolchain - Bundler, minifier, TypeScript compiler, linter (powered by OXC)
• 🚧 Bytecode Compilation - Bundle scripts as bytecode for security and performance
• 🚧 Full WinterTC Coverage - Complete Web API compatibility

---

🏗️ Virtual System Layer

Xmas.JS uses a pluggable virtual system layer called vsys to abstract all system-level operations. This enables:

• 🔒 Sandboxed execution for serverless/edge computing
• 💾 Custom filesystem implementations (in-memory, virtual, restricted)
• 🌐 Custom network implementations (proxied, restricted, mocked)
• � Custom module loading (load from DB, bundle, remote URL)
• 🔐 Fine-grained permissions control

┌─────────────────────────────────────────────────────────────────┐
│                    modules (JS Binding Layer)                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐  │
│  │ fs/mod   │ │http/mod  │ │module/   │ │Other JS Modules    │  │
│  │(ModuleDef│ │(ModuleDef│ │loader    │ │(Only registration, │  │
│  │  only)   │ │  only)   │ │resolver  │ │  calls vsys)       │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────────┬──────────┘  │
└───────┼────────────┼────────────┼─────────────────┼─────────────┘
        │            │            │                 │
        ▼            ▼            ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                     vsys (Virtual System Layer)                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  pub struct VsysVTable {                                    ││
│  │      // Filesystem                                          ││
│  │      pub fs_read, fs_write, fs_stat, fs_readdir, ...        ││
│  │      // Network                                             ││
│  │      pub http_request, dns_lookup, ...                      ││
│  │      // Module Loading (key for serverless!)                ││
│  │      pub module_resolve, module_load, module_exists, ...    ││
│  │      // Permissions                                         ││
│  │      pub check_fs_permission, check_net_permission, ...     ││
│  │  }                                                          ││
│  └─────────────────────────────────────────────────────────────┘│
│              ┌───────────────┴───────────────┐                  │
│              ▼                               ▼                  │
│  ┌─────────────────────┐        ┌─────────────────────┐         │
│  │  Default Impl       │        │  User Custom Impl   │         │
│  │  (std::fs, tokio,   │   OR   │  (VFS, sandboxed,   │         │
│  │   hyper, etc.)      │        │   in-memory, etc.)  │         │
│  └─────────────────────┘        └─────────────────────┘         │
└─────────────────────────────────────────────────────────────────┘

What Problems Does vsys Solve?

| Scenario | Problem Without vsys | With vsys | | ---------------------- | --------------------------------------------------- | ------------------------------------------------- | | Serverless/Edge | Runtime has full system access, security risk | Sandboxed execution, only expose what you allow | | Multi-tenant SaaS | Tenant A can access Tenant B's files | Each tenant gets isolated virtual filesystem | | Database Scripting | Scripts need real filesystem, deployment complexity | Virtual FS backed by database, zero external deps | | Bundled Deploy | Need node_modules on disk, slow cold start | Load modules from single bundle or remote URL | | Testing | Need real network/files, slow and flaky tests | Mock everything, fast and deterministic | | Embedded/IoT | Heavy system dependencies | Minimal footprint, platform-agnostic | | Game Scripting | Lua-style sandboxing is complex | Built-in isolation, expose only game APIs |

Example: Secure Serverless Function

// User's untrusted code can only:
// - Read from /app/data (virtual, mapped to S3)
// - Make HTTP requests to allowlisted domains
// - Load modules from pre-bundled package (no filesystem access)
// - No filesystem writes, no arbitrary network access
let runtime = XmasRuntime::new()
    .with_vsys(VsysVTable::new()
        .fs_read_only(s3_virtual_fs("/app/data"))
        .module_loader(bundled_modules("app.bundle"))
        .net_allowlist(&["api.example.com", "cdn.example.com"])
        .deny_all_else()
    );

---

📦 Installation

🚧 From Binary (Coming soon ❄️)

# Coming soon - pre-built binaries for major platforms
# Windows
curl -fsSL https://xmas.js.org/install.ps1 | powershell

# macOS / Linux
curl -fsSL https://xmas.js.org/install.sh | sh

---

🚀 Quick Start

Running Scripts

# Run a TypeScript/JavaScript file directly
xmas script.ts
xmas app.js

# Run with verbose output
xmas -v script.ts

# Run in a specific directory
xmas --cwd ./my-project script.ts

Interactive REPL

# Start the REPL (default when no arguments)
xmas

# Or explicitly
xmas repl

The REPL supports TypeScript, TSX, and JSX syntax with syntax highlighting:

🎄 >> const x: number = 42
🎄 >> console.log(`Hello, ${x}!`)
Hello, 42!
🎄 >> const element = <div>Hello World</div>

Package Management

Xmas.JS includes a built-in package manager (no need for npm/pnpm/yarn):

# Install dependencies from