NioJS v0.3.0

Native Acceleration Guide

NioJS achieves its incredible performance through Hybrid Execution. By combining lightweight QuickJS for fast startup and business logic with a Rust host that compiles supported numeric work for heavy lifting, you get the best of both worlds.

How /** @native */ Works

At build time, NioJS parses annotated functions and validates the supported operations. Numeric functions using local variables, arithmetic, branches, and loops are lowered to a portable plan in the capsule. At worker startup, the Rust host compiles the plan to machine code with Cranelift. Each loop checks the request deadline.

Pure object and array expressions, including the Array.from pattern below, run through a bounded Rust JSON builder. A response created during route registration is cached as bytes and served directly by Rust.

The original JavaScript body stays in the capsule. Calls with unsupported argument types, or functions that use operations outside the supported subset, run as JavaScript. This keeps closures, side effects, and exceptions intact. The annotation is an optimization hint, not a compiler for every JavaScript feature.

Example: CPU-Heavy Loops

Consider a tight mathematical loop that would normally choke an interpreter:

import { get } from 'nio.js';

/** @native */
function cpuIntensiveTask(): string {
  let value = 42;
  for (let i = 0; i < 100_000; i++) {
    value = (value * 1664525 + 1013904223) | 0;
  }
  return value.toString();
}

get('/cpu', () => cpuIntensiveTask());

Example: JSON & Static Caching

You can also create a JSON response once at route registration and serve its cached bytes on every request:

import { get } from 'nio.js';

/** @native */
function generateLargePayload(): Record {
    return {
        message: "Hello World",
        items: Array.from({ length: 20 }, (_, i) => ({ id: i, name: `item-${i}` }))
    };
}

get('/json', generateLargePayload());

Real-world example: queue capacity planning

An operations endpoint can estimate how long a job backlog will take to clear. The route validates query parameters in JavaScript; the annotated function runs the repeated numeric calculation. It returns -1 if the queue cannot clear within an hour.

Save this as app.ts and run nio-js run app.ts --port 3000:

import { get, reply } from 'nio.js';

/** @native */
function estimateDrainSeconds(backlog: number, arrivalsPerSecond: number,
                              workers: number, jobsPerWorkerPerSecond: number): number {
  if (backlog <= 0) return 0;
  let queued = backlog;
  const capacity = workers * jobsPerWorkerPerSecond;
  for (let second = 1; second <= 3600; second++) {
    queued = queued + arrivalsPerSecond - capacity;
    if (queued <= 0) return second;
  }
  return -1; // The queue does not clear within an hour.
}

get('/ops/queue-drain', ({ query }) => {
  const [backlog, arrivals, workers, rate] =
    [query.backlog, query.arrivals, query.workers, query.rate].map(Number);
  if (![backlog, arrivals, workers, rate].every(Number.isFinite) ||
      backlog < 0 || arrivals < 0 || workers <= 0 || rate <= 0) {
    return reply({ error: 'Supply nonnegative backlog/arrivals and positive workers/rate' },
                 { status: 400 });
  }
  return { estimatedSeconds: estimateDrainSeconds(backlog, arrivals, workers, rate) };
});
curl 'http://127.0.0.1:3000/ops/queue-drain?backlog=1000&arrivals=10&workers=4&rate=20'
# {"estimatedSeconds":15}

Real-world example: shard manifest API

A service can expose a default shard manifest and generate a bounded manifest for a requested shard count. The default response is created once during route registration and served from cached bytes. The parameterized response uses the Rust JSON builder for the annotated function's supported object and Array.from expression. Validate and bound user input in the route before passing it to @native.

Save this as a separate app.ts and run nio-js run app.ts --port 3000:

import { get, reply } from 'nio.js';

/** @native */
function shardManifest(shards: number): Record<string, unknown> {
  return {
    version: 1,
    shards: Array.from({ length: shards }, (_, id) => ({
      id,
      label: `shard-${id}`,
      replica: id % 3
    }))
  };
}

get('/ops/default-shards', shardManifest(3));
get('/ops/shards', ({ query }) => {
  const count = Number(query.count);
  if (!Number.isInteger(count) || count < 1 || count > 32) {
    return reply({ error: 'count must be an integer from 1 to 32' }, { status: 400 });
  }
  return shardManifest(count);
});
curl 'http://127.0.0.1:3000/ops/shards?count=3'
# {"version":1,"shards":[{"id":0,"label":"shard-0","replica":0},{"id":1,"label":"shard-1","replica":1},{"id":2,"label":"shard-2","replica":2}]}

Native work has a call overhead, so measure the full endpoint with your workload before choosing where to annotate functions.

Supported Operations and Limits

Numeric functions can use up to 16 numeric parameters, local let/const declarations, arithmetic and bitwise operators, comparisons, if, for, while, break, continue, selected Math functions, and a numeric or stringified numeric return. Pure JSON expressions can contain objects, arrays, strings, booleans, numbers, template strings with numeric values, and bounded Array.from generation.

Calls involving closures, custom objects, or other JavaScript features use the original implementation. Native execution follows the configured request deadline and response-size limit. Rebuild existing .njs capsules to use this implementation.