@titanpl/node

Node.js compatibility layer for the TitanPL Gravity Runtime.

This package enables selected Node.js core APIs to work inside TitanPL applications by mapping them to Titan’s native Rust-powered runtime.

It allows many existing npm libraries (sync-based) to run inside TitanPL without modification.

Why This Exists

TitanPL runs on:

• V8 isolates
• Rust core runtime
• No Node.js process
• No libuv
• No Node event loop

Because of this, Node built-ins like fs, crypto, or process do not exist by default.

@titanpl/node provides compatibility shims that redirect Node imports to Titan-native implementations.

🚀 Quick Start (Important)

To enable Node compatibility in an action, import the globals shim first:

import "@titanpl/node/globals";

This sets up:

• process
• Buffer
• global compatibility utilities

Then you can use Node-style imports normally:

import fs from "fs";
import path from "path";

Supported Core Modules (Sync APIs)

• fs
• path
• crypto
• os
• process
• Buffer
• util
• events (basic EventEmitter)

⚠️ Only synchronous APIs are supported. Async Node APIs are not supported because Titan uses drift() for async orchestration.

Example — Basic File Usage

import "@titanpl/node/globals";
import fs from "fs";
import path from "path";

export const hello = defineAction(() => {
  const file = path.join("data", "hello.txt");

  fs.writeFileSync(file, "Hello Titan");
  const content = fs.readFileSync(file, "utf-8");

  return { content };
});

Example — Using Popular npm Libraries

1️⃣ Day.js

import "@titanpl/node/globals";
import dayjs from "dayjs";

export const now = defineAction(() => {
  return { time: dayjs().format() };
});

2️⃣ Lodash

import "@titanpl/node/globals";
import _ from "lodash";

export const shuffle = defineAction(() => {
  return { arr: _.shuffle([1,2,3,4,5]) };
});

3️⃣ Mustache

import "@titanpl/node/globals";
import Mustache from "mustache";

export const render = defineAction(() => {
  const html = Mustache.render("Hello {{name}}", { name: "Titan" });
  return { html };
});

4️⃣ UUID (Works via Titan crypto)

import "@titanpl/node/globals";
import { v4 as uuid } from "uuid";

export const id = defineAction(() => {
  return { id: uuid() };
});

5️⃣ Crypto Hashing

import "@titanpl/node/globals";
import crypto from "crypto";

export const hash = defineAction(() => {
  const h = crypto.createHash("sha256")
    .update("Titan")
    .digest("hex");

  return { hash: h };
});

How It Works

During bundling, Titan rewrites:

import fs from "fs";

into:

import fs from "@titanpl/node/fs";

Each shim internally maps to Titan native APIs:

| Node API | Titan Core | | -------- | ---------- | | fs | t.fs | | path | t.path | | crypto | t.crypto | | process | t.proc | | os | t.os |

This keeps runtime performance native while preserving Node-style DX.

What Will NOT Work

• child_process
• cluster
• native .node addons
• streams requiring real Node internals
• async Node APIs
• libraries that depend on libuv

Titan is not Node.js — it is a native Rust server running V8.

Installation

npm install @titanpl/node

Design Philosophy

• Minimal shim surface
• Sync APIs only
• Performance-first
• Native Rust execution underneath
• Compatible with 50%+ of common utility npm libraries

Recommended Pattern for Production

Always place this at the top of your action file:

import "@titanpl/node/globals";

Then use Node-style imports normally.

License

ISC