API Reference

This page lists all the Transit functions you can use in your JavaScript code.

Importing Transit

import { transit } from "transit";

This gives you the main transit object. Everything starts from here.

---

Setting Up Languages

transit.rust(directory)

Tells Transit to look for Rust functions in the given folder.

const rs = transit.rust("./rust");

What it does:

1. Scans the folder for Rust files
2. Finds all pub fn functions
3. Loads the compiled Rust code (the .node file)
4. Returns an object you can use to call those functions

You need:

• The folder must contain Rust source files
• The Rust code must be compiled (cargo build --release)
• The compiled .node file must be in the folder or target/release/

Example:

const rs = transit.rust("./rust");
console.log(await rs.greet("World"));  // Calls the greet function in Rust

---

transit.java(directory, options?)

Tells Transit to look for Java functions in the given folder.

const jv = transit.java("./java/src/main/java");

What it does:

1. Scans the folder for Java files
2. Finds all public methods
3. On first function call, starts a Java process in the background
4. Returns an object you can use to call those functions

Options:

• classpath (string): Path to compiled Java classes. Transit auto-detects this by looking for build/, out/, or target/ directories, but you can specify it explicitly.
• mainClass (string): Fully qualified main class name. Default: transit.java.TransitService.

You need:

• The folder must contain Java source files
• The Java code must be compiled (javac)
• Java JDK 21+ must be installed

Examples:

// Auto-detect classpath
const jv = transit.java("./java/src/main/java");

// Explicit classpath and main class
const jv = transit.java("./java", {
  classpath: "./java/build",
  mainClass: "com.example.App"
});

---

transit.python(directory, options?)

Tells Transit to look for Python functions in the given folder.

const py = transit.python("./python");

What it does:

1. Scans the folder for Python files
2. Finds all top-level def functions
3. On first function call, starts a Python process in the background
4. Returns an object you can use to call those functions

Options:

• serverScript (string): Custom entry point filename. Transit auto-detects transit_service.py, service.py, main.py, app.py, server.py, and filters.py. Use this if your file has a different name.

You need:

• The folder must contain Python files
• The file must be named one of: transit_service.py, service.py, main.py, app.py, server.py, or filters.py (or specify serverScript)
• The file must import and use transit_server.py (see getting-started guide)
• Python 3.10+ must be installed

Important: Your Python functions receive a JSON string, not a dictionary. Always use json.loads(args) to parse it.

Examples:

// Auto-detect entry point
const py = transit.python("./python");

// Custom entry point
const py = transit.python("./python", { serverScript: "filters.py" });

---

transit.c(directory)

Tells Transit to look for C functions in the given folder.

const c = transit.c("./c");

What it does:

1. Scans the folder for C files
2. Finds all exported functions (matching the C glue header signatures)
3. On first function call, loads the compiled native addon (.node file)
4. Returns an object you can use to call those functions

You need:

• The folder must contain C source files
• The C code must be compiled with a binding.gyp or node-gyp setup
• A C glue header (transit_c_glue.gen.h) generated by transit build
• The compiled .node file must be in the folder

Example:

const c = transit.c("./c");
console.log(await c.processChunk({ data: [1, 2, 3] }));

---

transit.cpp(directory)

Tells Transit to look for C++ functions in the given folder.

const cpp = transit.cpp("./cpp");

What it does:

1. Scans the folder for C++ files
2. Finds all exported functions (matching the C++ glue header signatures)
3. On first function call, loads the compiled native addon (.node file)
4. Returns an object you can use to call those functions

You need:

• The folder must contain C++ source files
• The C++ code must be compiled with a binding.gyp or node-gyp setup
• A C++ glue header (transit_cpp_glue.gen.h) generated by transit build
• The compiled .node file must be in the folder

Example:

const cpp = transit.cpp("./cpp");
console.log(await cpp.fastCompute({ n: 42 }));

---

Calling Functions

Once you have set up a language, you call its functions like normal JavaScript functions:

const rs = transit.rust("./rust");
const py = transit.python("./python");
const c = transit.c("./c");
const cpp = transit.cpp("./cpp");

// Call Rust functions
const greeting = await rs.greet("World");
const sum = await rs.add(10, 20);

// Call Python functions
const result = await py.processData({ items: [1, 2, 3] });
const stats = await py.getStats();

// Call C functions
const chunk = await c.processChunk({ data: [1, 2, 3] });

// Call C++ functions
const computed = await cpp.fastCompute({ n: 42 });

Important: Always use await when calling Transit functions. The first call may take a moment (especially for Python and Java), but subsequent calls are fast.

---

Listing Discovered Functions

transit.info()

Prints a list of all functions Transit found:

transit.info();

Output:

rust (./rust): 2 functions
  - greet [tier 1] (pub fn greet(name: String) -> String)
  - add [tier 1] (pub fn add(a: i32, b: i32) -> i32)
python (./python): 2 functions
  - processData [tier 1] (def process_data(args_json))
  - getStats [tier 1] (def get_stats(args_json))

This is helpful for debugging — if your function does not appear here, Transit did not find it.

---

Handling Multiple Files with the Same Name

If two files export functions with the same name, use the file name to pick which one:

// If lib.rs and utils.rs both have a "process" function:
await rs["lib"]["process"](data)    // Calls lib.rs's process
await rs["utils"]["process"](data)  // Calls utils.rs's process

// Dot notation also works:
await rs.lib.process(data)

---

Cleaning Up

py._bridge.stop()

Shuts down the Python process that Transit started in the background:

await py._bridge.stop();

jv._bridge.stop()

Shuts down the Java process:

await jv._bridge.stop();

When to use this: When your application is shutting down and you want to cleanly stop background processes. In most cases, you do not need to call this — the processes will stop when your application exits.

---

Configuration

transit.config

The current Transit configuration (read-only):

console.log(transit.config.build.rust.command);  // "cargo build --release"
console.log(transit.config.maxRestarts);          // 3

transit.reloadConfig(directory?)

Reloads the configuration from disk. Use this if you change transit.config.json while your app is running:

transit.reloadConfig();        // Reload from current directory
transit.reloadConfig("/app");  // Reload from a different directory

---

Error Handling

When a function call fails, Transit throws an error with useful information:

try {
    await rs.nonexistentFunction(data);
} catch (err) {
    console.error(err.message);
    // "Function \"nonexistentFunction\" not found in rust. Available: greet, add"
}

If a Python or Java function raises an error, Transit wraps it:

try {
    await py.processData(badData);
} catch (err) {
    console.error(err.message);
    // "[python] processData: Division by zero"
}

---

Advanced: Scanning a Single File

If you are building a file watcher and want to scan one file at a time:

import { scanFileSync } from "transit";

const entries = scanFileSync("./src/lib.rs");
console.log(entries);  // Array of discovered functions in that file

---

Advanced: Cache Management

Transit caches scan results to speed up subsequent startups. You can manage the cache:

import { invalidateFileCache, clearScanCache } from "transit";

// Remove one file from the cache (e.g., when a file is deleted)
invalidateFileCache("./rust", "./rust/src/lib.rs");

// Clear the entire cache for a directory
clearScanCache("./rust");