trealla-js

~~Javascript~~ TypeScript bindings for Trealla Prolog.

Trealla is a quick and lean ISO Prolog interpreter.

Trealla is built targeting WASI and should be useful for browsers, serverless runtimes, and edge.

Demo: https://php.energy/trealla.html

Status: beta!

Get

trealla-js embeds the Trealla WASM binary. Simply import the module, load it, and you're good to go.

$3

You can import Trealla directly from a CDN that supports ECMAScript Modules.

For now, it's best to pin a version as in: https://esm.sh/trealla@X.Y.Z.

``js
import { load, Prolog } from 'https://esm.sh/trealla';
import { load, Prolog } from 'https://esm.run/trealla';
import { load, Prolog } from 'https://unpkg.com/trealla';
import { load, Prolog } from 'https://cdn.skypack.dev/trealla';
`

$3

This package is available on NPM as trealla.

`bash
npm install trealla
`

`js
import { load, Prolog } from 'trealla';
`

$3

By default, trealla-js bundles the Trealla WASM binary as a buffer in the source.

This is unsupported by some runtimes that disallow WebAssembly compilation (i.e. Cloudflare Workers).

For these runtimes, trealla-js offers trealla/unbundled module with alternative WASM bundling.
The WASM binary is bundled as a standalone file and imported as a module at the run time.

`js
import { load, Prolog } from 'trealla/unbundled';
`

The rest of the API stays the same.

Example

$3

`html


`

`javascript
{
"status": "success",
"answer": {"X": 2, "Y": 4},
"stdout": "(2,4)\n"
}
// ...
`

$3

Experimental. With great power comes great responsibility 🤠

#### Writing a Prolog predicate in Javascript 🆕

You can implement Prolog predicates using Javascript.

This is useful for taking advantage of browser functionality, or utilizing JS's async runtime.

`typescript
// Native predicates are fully type-safe :-)
export type PredicateFunction =
(pl: Prolog, subq: Ptr, goal: G, ctrl: Ctrl) =>
Continuation | Promise> | AsyncIterable>;
export type Continuation = G | boolean;
export type Goal = Atom | Compound;
`

Create a new Predicate with new Predicate(...) and register it with pl.register(...).

The return value of all predicates is a "continuation" that is either:
- A goal that will be unified with the call
- Boolean true to succeed unconditionally
- Boolean false to fail unconditionally

Throwing a Prolog term will cause throw/1 to be called by the guest.
Throwing a non-Term will become throw(error(system_error(js_exception, "details..."), foo/N)).

`typescript
// Example of between/3 implemented in JS
export const betwixt_3 = new Predicate>(
"betwixt", 3,
async function*(_pl, _subquery, goal) {
const [min, max, n] = goal.args;
if (!isNumber(min))
throw type_error("number", min, goal.pi);
if (!isNumber(max))
throw type_error("number", max, goal.pi);

for (let i = isNumber(n) ? n : min; i <= max; i++) {
goal.args[2] = i;
if (i == max)
return goal;
yield goal;
}
});

await pl.register(betwixt_3, / optional module name /);
`

The fanciest predicate function is an async generator, in which you can use yield to create choice points, and return as a kind of internal cut.

You can also use regular async functions (i.e. functions that return a Promise) or plain functions.

The Prolog interpreter will automatically yield to the host when calling a native predicate backed by an async function or generator.

#### Evaluating JS code from Prolog

NOTE: work in progress, see examples/{hostcall,yield}.mjs

The JS host will evaluate the expression you give it ~~and marshal it to JSON~~.
You can use js_eval/2 to grab the result.

`prolog
greet :-
js_eval("return prompt('Name?');", Name),
format("Greetings, ~s.", [Name]).

here(URL) :-
js_eval("return new trealla.Atom(location.href);", URL).
% URL = 'https://php.energy/trealla.html'
`

If your evaluated code returns a promise, Prolog will yield to the host to evaluate the promise.
Hopefully this should be transparent to the user.

`prolog
?- js_eval("return fetch('http://example.com').then(x => x.text());", Src).
Src = "