Ranty.js

Ranty.js is the TypeScript port of Ranty, a procedural templating language and runtime for generating text and structured values.

This repository is intentionally downstream of the Rust implementation. Shared language, runtime, module, stdlib, and CLI behavior is authored upstream first, then ported here against the checked-in parity contract under ./upstream/ranty/.

Documentation

• Shared Ranty reference: https://insanityfarm.github.io/ranty/
• Local JS-specific reference: this README

How To Use The Ranty Docs From Ranty.js

Use the hosted Ranty reference for:

• language syntax
• standard-library behavior
• module semantics
• runtime concepts
• CLI semantics that are shared across Rust and JS

Use this README for:

• package installation and runtime targets
• Node.js and browser embedding
• the public JS host API
• the ranty-js CLI package and entrypoint
• JS-specific differences from the Rust embedding surface

When the hosted docs talk about embedding Ranty in Rust, keep the shared language and runtime concepts, but ignore the Rust API details. The equivalent JS host surface is documented below.

Runtime Targets

• Node.js >=22.0.0 for library or CLI usage
• browsers with ES2022 and BigInt support
• package name: ranty-js
• CLI command: ranty-js
• browser bundle: dist/ranty.js
• browser namespace: globalThis.Ranty

Install

npm install ranty-js

For contributors working in this repository:

npm install
npm run context:build
npm run verify

Node Library Use

import { Ranty } from "ranty-js";

const ranty = new Ranty({ seed: 0xdeadbeefn });
const program = ranty.compileQuiet(`
[$greet:name] {
  {Hello|Hi|Hey}, <name>!
}
[greet:world]
`);

console.log(ranty.run(program));

The Ranty constructor accepts a partial RantyOptions object. The main options are:

Option	Meaning
useStdlib	Load the built-in globals. Disable it to supply a narrower custom prelude.
debugMode	Emit richer compiler metadata and runtime diagnostics.
topLevelDefsAreGlobals	Keep top-level definitions after a run, which is useful for REPL-like hosts.
seed	Set the initial RNG seed as a number or bigint.
gcAllocationThreshold	Reserved parity option; present on the JS API, but manual GC control does not currently do work.

Useful host-side entrypoints include:

• compileQuiet(), compileNamed(), compileFileQuiet()
• run() and runWith()
• setGlobalConst() and setGlobal()
• usingModuleResolver()
• addDataSource() and clearDataSources()
• Ranty.createVirtualModules()

Browser Use

Ranty.js ships a UMD bundle. In browsers, the exported symbols live under the globalThis.Ranty namespace object.

<script src="./node_modules/ranty-js/dist/ranty.js"></script>
<script>
  const { Ranty, VirtualModuleResolver } = globalThis.Ranty;

  const ranty = new Ranty().usingModuleResolver(
    new VirtualModuleResolver({
      "mods/greetings.ranty": '<%module = (:: hello = "browser world")><module>'
    })
  );

  const program = ranty.compileQuiet(
    '@require "mods/greetings"[greetings/hello]'
  );

  console.log(ranty.run(program));
</script>

Browser @require is synchronous. The runtime does not fetch modules over the network, walk the filesystem, or infer module contents from URLs. Provide modules up front through VirtualModuleResolver or another host-controlled resolver.

CLI Use

The published CLI command is ranty-js.

npx ranty-js --eval '"hello from ranty-js"'
npx ranty-js --seed deadbeef --eval '[rand:1;6]'
npx ranty-js ./example.ranty
printf '"from stdin"' | npx ranty-js

The Node CLI chooses its launch mode in this order:

1. --eval PROGRAM
2. FILE
3. piped stdin
4. REPL

Supported flags:

Flag	Meaning
-e, --eval PROGRAM	Run an inline program string.
-s, --seed SEED	Set the initial RNG seed as 1 to 16 hexadecimal digits, with optional 0x.
-b, --bench-mode	Print compile and execution timing to stderr.
-W, --no-warnings	Suppress compiler warnings.
-D, --no-debug	Disable debug symbol emission during compilation.
-h, --help	Show CLI help.
-V, --version	Show the build version.

Exit codes:

Code	Meaning
0	Success
64	Invalid CLI usage, such as an invalid seed
65	Compilation failed
66	Input file not found
70	Runtime execution failed

Host Integration Example

import { Ranty } from "ranty-js";
import type { DataSource } from "ranty-js";

const buildInfo: DataSource = {
  typeId() {
    return "build-info";
  },

  requestData(args) {
    const channel = String(args[0] ?? "dev");
    return `channel:${channel}`;
  }
};

const ranty = new Ranty();
ranty.addDataSource(buildInfo);

console.log(
  ranty.run(ranty.compileQuiet('[ds-request:"build-info";"stable"]'))
);

Scripts access registered data sources through [ds-request: ...] and can enumerate them through [ds-query-sources].

JS-Specific Differences

Topic	Ranty.js behavior
Package and command names	The npm package is ranty-js, and the packaged binary is ranty-js.
Shared docs split	The hosted docs at https://insanityfarm.github.io/ranty/ are the shared language/runtime reference. This README is the local JS-specific host guide.
Host API naming	The JS API uses camelCase method names such as compileQuiet(), compileNamed(), compileFileQuiet(), usingModuleResolver(), and addDataSource().
Error model	Host-side operations throw normal JS errors such as CompilerError, RuntimeError, ModuleResolveError, and DataSourceError instead of returning Rust Result values.
Return values	run() returns native JS values. Text output is a string; exact integers may be bigint; maps are Map<string, unknown>; list and tuple values are arrays; functions are JS callables.
Exact integers and seeds	Integer-heavy APIs accept number or bigint. RantyInt preserves signed i64 semantics, and toApiValue() returns a number only when the value stays inside the safe integer range.
Node module resolution	DefaultModuleResolver checks the dependant file directory first, then localModulesPath or process.cwd(), then RANTY_MODULES_PATH when global modules are enabled. When no extension is supplied, .ranty is preferred before .rant.
Browser module loading	In browsers, @require only works through host-supplied resolvers such as VirtualModuleResolver. The runtime does not perform ambient filesystem or network lookup.
Data sources	Implement the DataSource interface and register it with addDataSource(). Scripts consume these integrations through [ds-request: ...] and [ds-query-sources].
Bundle shape	dist/ranty.js is a UMD bundle. Browser consumers read exports from globalThis.Ranty, for example globalThis.Ranty.Ranty and globalThis.Ranty.VirtualModuleResolver.
GC and ownership notes	Rust ownership and borrowing guidance does not apply directly. gcAllocationThreshold remains part of the options surface for parity, and collectGarbage() is currently a no-op in the JS runtime.

Upstream Parity

• The Rust repo at insanityfarm/ranty is authoritative for shared language and runtime behavior.
• The vendored upstream bundle lives under ./upstream/ranty/.
• Refresh it with npm run upstream:sync -- --ref=<rust-sha-or-branch>.
• CI runs npm run upstream:check-freshness and only blocks pull requests that touch core, public API, or build-sensitive surfaces while the local parity lock is behind upstream Rust main.

Contributor Workflow

• Read ./spec/README.md.
• Read ./glossary/README.md.
• Read ./AGENTS.md.
• Run npm run context:task -- "<task>" before editing.
• Run npm run context:build after changing glossary terms, subsystem records, or ADRs.
• Run npm run verify before treating a change as done.

License

MIT. See ./LICENSE.