Getting started

1. Install#

npm install totalfusion

The package is on npm.

You need Node.js 20 or newer, and Python 3.9 or newer for the Python runtime. Rust and Go are needed only to build a worker in that language, never to run one.

2. Your first function, in any Node.js program#

# python/hello.py
def greet(data):
    return {'message': 'Hello ' + data['name']}

// app.js
const fusion = require('totalfusion');

fusion.configure({ python: { path: './python' } });

fusion.python('hello.greet', { name: 'world' }).then(result => {
    console.log(result);            // { message: 'Hello world' }
    return fusion.shutdown();
});

A pool of Python processes starts on the first call and stays alive. examples/basic.js is a version of this that you can run.

3. In a Total.js 5 application#

Declare what the function takes and returns, and it becomes an action of Total.js:

# python/hello.py
from totalfusion import action

@action(summary='Greets someone', input='*name:String', output='message:String')
def greet(data):
    return {'message': 'Hello ' + data['name']}

// definitions/fusion.js
const fusion = REQUIRE('totalfusion');

exports.install = function() {
    fusion.register({ python: { path: PATH.root('python') }, watch: DEBUG });
    ROUTE('API  /api/  +hello_greet  -->  hello/greet');
};

Now ACTION('hello/greet', { name: 'x' }) and POST /api/ work, Total.js rejects an input without name before Python runs, and with watch: DEBUG the next request uses your edits. The whole application is in examples/totaljs-app. More in Total.js 5.

4. Rust#

If a function is heavy on the CPU, write it in Rust, build a binary and call it the same way:

fusion.configure({ rust: { binary: './worker/target/release/worker' } });
await fusion.rust('collatz.longest', { limit: 3000000 });

See Rust and examples/rust.js.

5. Go#

If a function is network or infrastructure code, or you want one binary that you can build for any system, write it in Go and call it the same way:

fusion.configure({ go: { binary: './worker/worker' } });
await fusion.go('net.check', { host: 'example.com' });

See Go and examples/go.js.

6. Check your setup#

npx totalfusion doctor --path ./python

It tells you which libraries are missing and the exact command to install them in the right Python. Nothing is imported, run or installed. See Development and diagnosis.

Where to go next#