GitHub - LemonHX/Xmas.JS: Xmas.JS is a lightweight, high-performance JavaScript/TypeScript runtime

🎯 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:

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?

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 package.json
xmas install
xmas i              # shorthand

# Add a package
xmas add lodash
xmas add -D vitest  # add as devDependency
xmas add --pin zod  # pin to exact version

# Remove a package
xmas remove lodash
xmas rm lodash      # shorthand

# Run a script from package.json
xmas run dev
xmas run build --watch src/

# Update lockfile
xmas update

# Upgrade packages to latest versions
xmas upgrade
xmas upgrade --pin  # pin upgraded versions

# Clean node_modules and cache
xmas clean

# Execute a command
xmas exec tsc --version

# Find why a package is installed
xmas why lodash
xmas why lodash 4.17.21

# Create new project from starter kit
xmas create vite

# Download and execute a package (like npx)
xmas x create-react-app my-app

Bundling

Bundle TypeScript/JavaScript files using Rolldown:

# Basic bundle
xmas bun src/index.ts

# Bundle with options
xmas bun src/index.ts -o build -n app.js

# Bundle with minification and source maps
xmas bun src/index.ts -m -s

# Bundle multiple entry points
xmas bun src/index.ts src/worker.ts

# Bundle with custom format
xmas bun src/index.ts -f cjs      # CommonJS
xmas bun src/index.ts -f esm      # ES Modules (default)
xmas bun src/index.ts -f iife     # Immediately Invoked Function Expression

# Exclude packages from bundle
xmas bun src/index.ts -e react -e react-dom

CLI Reference

xmas [OPTIONS] [SCRIPT]... [COMMAND]

Commands:
  install (i)     Install packages defined in package.json
  add (a)         Add package to package.json
  remove (rm)     Remove package from package.json
  run             Run a script defined in package.json
  update          Prepare and save a newly planned lockfile
  upgrade         Update packages to the latest available version
  clean           Clean node_modules and cache
  exec            Execute a command (not a script)
  why             Find all uses of a given package
  create          Create new project from a starter kit
  x               Download and execute a package (like npx)
  bun (bundle)    Bundle TypeScript/JavaScript files
  repl            Start the interactive REPL

Options:
  -v, --verbose       Print verbose logs
      --cwd <PATH>    Run in a custom working directory
  -h, --help          Print help
  -V, --version       Print version

📊 Benchmarks

Startup Time Comparison

Python 3.11:     █████████████████████ 45ms
Node.js 20:      ███████████████ 120ms
Deno 1.38:       ██████████████████ 180ms
Bun 1.0:         █████████ 75ms
Xmas.JS:         ██ 12ms ⚡

Memory Usage (Idle)

Python 3.11:     ████████████████ 15MB
Node.js 20:      ████████████████████████████ 45MB
Deno 1.38:       ██████████████████████████████ 55MB
Bun 1.0:         ████████████████████ 28MB
Xmas.JS:         ███ 5MB 🪶

Benchmarks performed on Windows 11, AMD Ryzen 9 5900X, 64GB RAM

🎯 Use Cases

Perfect For:

• ✅ System Administration Scripts - Replace Python/Perl scripts with modern JavaScript
• ✅ Build Tools & Automation - Fast CLI tools that start instantly
• ✅ Serverless Functions - Minimal cold start on AWS Lambda, Cloudflare Workers, etc.
• ✅ IoT & Embedded Devices - Small memory footprint for resource-constrained environments
• ✅ Game Scripting - Embed as a game scripting engine (like Lua)
• ✅ Configuration Scripts - Replace complex Bash/PowerShell scripts

Not Ideal For:

• ❌ Large Web Applications - Use Node.js/Deno/Bun instead
• ❌ Production-Ready Today - Still in active development

🗺️ Roadmap

See TODO.md for detailed progress.

2025 Q4

• Core runtime foundation
• Basic WinterTC APIs
• Async I/O with Tokio
• REPL implementation
• TypeScript support (repl also supports tsx/jsx)
• Bytecode compilation

2026 Q1

• supporting WASM modules
• Package manager
• Built-in toolchain (OXC integration)
• Documentation site
• 1.0 release candidate

🤝 Contributing

We welcome contributions! Xmas.JS is in active development and needs help with:

• 🐛 Bug reports and testing
• 📝 Documentation improvements
• ✨ New features and APIs
• 🔧 Performance optimizations
• 🌍 Translations

See CONTRIBUTING.md for guidelines.

❓ FAQ

Is TypeScript support first-class or is there transpilation?

TypeScript/TSX/JSX is transpiled to JavaScript before execution. Xmas.JS uses OXC (a high-performance Rust-based toolchain) to transform TypeScript to JavaScript on-the-fly. This means:

• ✅ No separate build step required - Just run .ts, .tsx, or .jsx files directly
• ✅ Instant transpilation - OXC is extremely fast (~100x faster than tsc)
• ✅ Full TypeScript syntax support - Including decorators, JSX, and modern features
• ⚠️ No type checking at runtime - Types are stripped during transpilation (same as tsc --transpileOnly)

# Run TypeScript directly - transpilation happens automatically
xmas script.ts

# REPL also supports TypeScript/TSX
🎄 >> const x: number = 42
🎄 >> const element = <div>Hello</div>

For type checking, use your IDE's TypeScript integration or run tsc --noEmit separately.

How is Xmas.JS different from Node.js/Deno/Bun?

Choose Xmas.JS when: You need fast startup, low memory, or are replacing Python/Bash scripts.

Choose Node.js/Deno/Bun when: You're building web servers or compute-intensive applications.

Can I use npm packages with Xmas.JS?

Yes, with some caveats:

• ✅ Pure JavaScript/TypeScript packages - Work out of the box
• ✅ Most polyfilled packages - If they don't rely on Node.js internals
• ⚠️ Native addons (.node files) - Not supported (C++ extensions compiled for Node.js)
• ⚠️ Node.js-specific APIs - Some may not be implemented yet (check our compatibility table)

# Use the built-in package manager
xmas install lodash
xmas install zod

We're continuously improving Node.js API compatibility. Check TODO.md for current status.

Is Xmas.JS production-ready?

Not yet. Xmas.JS is in active development (pre-1.0). We recommend:

• ✅ Use for: Personal scripts, internal tools, prototyping, learning
• ⚠️ Evaluate for: Non-critical production workloads with thorough testing
• ❌ Avoid for: Mission-critical production systems (for now)

We're targeting a stable 1.0 release in Q1 2026.

Why QuickJS instead of V8?

QuickJS was chosen deliberately for our use case:

For short-lived scripts (CLI tools, serverless, automation), the fast startup and low memory of QuickJS outweighs V8's JIT benefits. V8's JIT only helps after the code has run long enough to be optimized.

Does Xmas.JS support WebAssembly?

Planned for Q1 2026. QuickJS has experimental WASM support, and we're working on integrating it with proper WinterTC-compatible APIs.

Can I embed Xmas.JS in my Rust application?

Yes! Xmas.JS is designed to be embeddable:

use xmas_js_modules::prelude::*;

// Create a runtime
let runtime = AsyncRuntime::new()?;
let context = AsyncContext::full(&runtime).await?;

// Run JavaScript
context.with(|ctx| {
    ctx.eval("console.log('Hello from embedded JS!')")?;
    Ok(())
}).await?;

See our embedding guide for detailed instructions.

How does Xmas.JS handle async/await?

Xmas.JS uses Tokio for async I/O, providing:

• ✅ Full async/await support in JavaScript
• ✅ Promise API compatible with web standards
• ✅ Concurrent I/O operations (file system, network, timers)
• ✅ Top-level await in ES modules

// Async operations work just like in Node.js/Deno
const response = await fetch('https://api.example.com/data');
const data = await response.json();

// Parallel operations
const [file1, file2] = await Promise.all([
  fs.promises.readFile('a.txt'),
  fs.promises.readFile('b.txt')
]);

What's the relationship with WinterTC?

WinterTC (Web-interoperable Runtimes Community Group) defines standard APIs for non-browser JavaScript runtimes. Xmas.JS aims to be WinterTC-compatible, meaning:

• ✅ Standard fetch(), Request, Response APIs
• ✅ Web Crypto API (crypto.subtle)
• ✅ Web Streams API
• ✅ URL, URLSearchParams, TextEncoder, TextDecoder
• ✅ console, setTimeout, setInterval

This ensures code portability between Xmas.JS, Deno, Cloudflare Workers, and other WinterTC-compatible runtimes.

📄 License

Xmas.JS is dual-licensed under Apache-2.0 OR GPL-3.0.

Use Apache-2.0 if you want to:

• ✅ Use Xmas.JS in proprietary software
• ✅ Contribute to open source projects
• ✅ Build commercial applications
• ✅ Modify the source code

Use GPL-3.0 if you:

• 🏢 Provide Xmas.JS as a managed service (cloud providers)
• 🔒 Integrate into closed-source infrastructure

This dual-license ensures open collaboration while preventing service provider lock-in.

🙏 Acknowledgments

Xmas.JS stands on the shoulders of giants:

• QuickJS by Fabrice Bellard - The amazing JavaScript engine
• rquickjs - Rust bindings (we maintain a fork)
• LLRT - Inspiration and code for AWS Lambda optimization
• Tokio - Async runtime that powers our I/O
• Cotton - Package manager forked for our needs

Inspired by:

• Deno - Modern JavaScript runtime design
• Node.js - The JavaScript runtime that started it all
• txiki.js - Lightweight runtime approach

🌟 Star History

If you find Xmas.JS useful, please consider giving it a star! ✨

Made with ❤️ by the 🍋 LemonHX & 🎄Xmas.JS team