A stack-based programming language that compiles to JavaScript.

"Hello, World!" peek;

In jth, values are pushed onto a stack. Operators pop their arguments off the stack, do their work, and push results back. It is a simple model that turns out to be surprisingly powerful.

npm install -g jth-cli

jth run hello.jth

jth run -c '2 3 + peek;'
# Output: 5

jth compile program.jth output.mjs

jth

REPL dot-commands: .help, .peek, .count, .clear, .stack, .exit

Every value you write gets pushed onto the stack:

42;       // stack: [42]
"hello";  // stack: [42, "hello"]
true;     // stack: [42, "hello", true]

The peek operator logs the top of the stack without removing it. The peek-all operator logs the entire stack.

42 peek;     // logs: 42, stack: [42]
1 2 3 peek-all; // logs: 1 2 3, stack: [1, 2, 3]

Supported value types:

Semicolons separate statements.

Operators pop their arguments from the stack and push back the result:

2 3 +;   // stack: [5]       — pops 2 and 3, pushes 5
10 3 -;  // stack: [7]       — pops 10 and 3, pushes 7
4 5 *;   // stack: [20]
15 4 /;  // stack: [3.75]
17 5 %;  // stack: [2]       — modulo
2 8 **;  // stack: [256]     — exponentiation

You can chain operations. The stack carries values forward:

2 3 + 4 *;  // (2 + 3) * 4 = 20, stack: [20]

These operators rearrange what is on the stack:

5 dupe;      // stack: [5, 5]       — duplicate the top
3 7 swap;    // stack: [7, 3]       — swap top two
1 2 3 drop;  // stack: [1, 2]       — discard the top
1 2 3 count; // stack: [1, 2, 3, 3] — push the stack depth
clear;       // stack: []           — empty the stack

reverse reverses the entire stack. copy duplicates the entire stack. collect gathers all items into an array.

A block is an anonymous function wrapped in #[ ]. It operates on the stack when executed:

#[ dupe * ] :square;   // define "square" as an operator
5 square peek;         // 25

:name pops the top of the stack and registers it as a named operator. Blocks become callable operators; plain values (numbers, strings) are pushed onto the stack when the operator is used.

3.14159 :PI;
PI peek;   // 3.14159 — PI pushes the value onto the stack

::name pops a value into a JavaScript const. This is primarily used for interop with inline JS — it is not accessible as a jth operator name.

if — pops a condition, a true-block, and a false-block:

// Syntax: #[ false-block ] #[ true-block ] condition if

#[ "odd" ] #[ "even" ] 10 2 % 0 = if peek;
// 10 % 2 = 0, 0 = 0 is true, so "even" is printed

The order on the stack before if executes is: false-block (bottom), true-block, condition (top). In code you write the false-block first, then the true-block, then the condition.

if/elseif/else chains — flat conditional chaining without nesting:

dupe 15 % 0 = #[ drop "FizzBuzz" ] swap if
dupe 3 % 0 = #[ drop "Fizz" ] swap elseif
dupe 5 % 0 = #[ drop "Buzz" ] swap elseif
#[ ] else

if in 2-arg mode starts a chain. elseif checks additional conditions. else is the fallback. Only the first matching branch executes.

times — runs a block N times:

#[ "hi" peek ] 3 times;
// logs "hi" three times

when — keeps a value only if the condition is truthy:

42 true when;    // stack: [42]
42 false when;   // stack: []

try wraps a block and catches any error:

#[ "oops" throw ] try;   // stack: [Error("oops")]
error? peek;              // true

throw pops a message and throws an error. error? checks whether the top of the stack is an Error.

Arrays use square brackets with space-separated values:

[1 2 3] peek;         // [1, 2, 3]
[1 2 3] 4 push peek;  // [1, 2, 3, 4]
[1 2 3] ...;       // spreads onto stack: 1, 2, 3

Array operators include push, pop, shift, unshift, flatten, suppose (add to collection), ... (spread), and collect (gather stack into array).

"hello" upper peek;              // "HELLO"
"hello" "world" strcat peek;     // "helloworld"
"hello world" len peek;          // 11
"  hello  " trim peek;           // "hello"

Objects use { } with alternating key-value pairs:

{ "name" "jth" "version" 2 } peek;
// { name: "jth", version: 2 }

{ "a" 1 "b" 2 } keys peek;      // ["a", "b"]
{ "a" 1 "b" 2 } values peek;    // [1, 2]

Both // and # start comments. // also acts as a statement terminator:

42 peek  // this logs 42
7 peek   // and this logs 7

Import operators from another jth file:

::import "./math.jth" { square cube };
5 square peek;   // 25

Export operators from a module:

#[ dupe * ] :square;
#[ dupe dupe * * ] :cube;
::export square cube;

Prefix a number to an operator to create a partial application. The semantics are N op x — the prefix number comes first:

10 3+;      // 3 + 10 = 13  (commutative, same either way)
7 2*;       // 2 * 7 = 14   (commutative)
100 10log;  // log base 10 of 100 = 2
8 2log;     // log base 2 of 8 = 3

For non-commutative operators, the prefix number is the left operand: 3- means 3 - x, 2/ means 2 / x.

Double parentheses embed raw JavaScript. The expression is treated as a value:

((Math.random())) peek;           // random number
((x => x * 2)) :double;
5 double peek;                    // 10

_ awaits a promise. __ runs Promise.all on an array of promises:

((fetch("https://api.example.com/data"))) _ peek;

All statistics operators are variadic — they consume the entire stack.

Prefix any number to an arithmetic operator. Semantics: N op x (N is left operand):

jth run <file>              # Compile and execute a .jth file
jth run -c '<code>'         # Run inline jth code
jth compile <file> [output] # Compile .jth to .mjs
jth compile -c '<code>'     # Compile inline code to stdout
jth --version, -v           # Show version
jth --help, -h              # Show help

jth is organized as a monorepo with 7 packages:

# Install dependencies
npm install

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run end-to-end tests
npm run test:e2e