🪸 ReefVM

It's where Shrimp live.

Quickstart

bun install
bun test

TODO (tests)

Stack Operations

• PUSH
• POP
• DUP

Variables

• LOAD
• STORE

Arithmetic

• ADD
• SUB
• MUL
• DIV
• MOD

Comparison

• EQ
• NEQ
• LT
• GT
• LTE
• GTE

Logical

• NOT
• AND pattern (using JUMP_IF_FALSE for short-circuiting)
• OR pattern (using JUMP_IF_TRUE for short-circuiting)

Control Flow

• JUMP
• JUMP_IF_FALSE
• JUMP_IF_TRUE
• BREAK
• CONTINUE

Exception Handling

• PUSH_TRY
• PUSH_FINALLY
• POP_TRY
• THROW

Functions

• MAKE_FUNCTION
• CALL
• TAIL_CALL
• RETURN

Arrays

• MAKE_ARRAY
• ARRAY_GET
• ARRAY_SET
• ARRAY_LEN

Dictionaries

• MAKE_DICT
• DICT_GET
• DICT_SET
• DICT_HAS

TypeScript Interop

• CALL_NATIVE

Special

• HALT

Test Status

✅ 91 tests passing covering:

• All stack operations (PUSH, POP, DUP)
• All arithmetic operations (ADD, SUB, MUL, DIV, MOD)
• All comparison operations (EQ, NEQ, LT, GT, LTE, GTE)
• Logical operations (NOT, AND/OR patterns with short-circuiting)
• Variable operations (LOAD, STORE)
• Control flow with relative jumps (JUMP, JUMP_IF_FALSE, JUMP_IF_TRUE, BREAK, CONTINUE)
• All array operations (MAKE_ARRAY, ARRAY_GET, ARRAY_SET, ARRAY_PUSH, ARRAY_LEN)
• All dictionary operations (MAKE_DICT, DICT_GET, DICT_SET, DICT_HAS)
• Function operations (MAKE_FUNCTION, CALL, TAIL_CALL, RETURN) with parameter binding
• Variadic functions with positional rest parameters (...rest)
• Named arguments (kwargs) that collect unmatched named args into a dict (@kwargs)
• Mixed positional and named arguments with proper priority binding
• Tail call optimization with unbounded recursion (10,000+ iterations without stack overflow)
• Exception handling (PUSH_TRY, PUSH_FINALLY, POP_TRY, THROW) with nested try/finally blocks and call stack unwinding
• Native function interop (CALL_NATIVE) with sync and async functions
• HALT instruction

Design Decisions

• Relative jumps: All JUMP instructions use PC-relative offsets instead of absolute addresses, making bytecode position-independent
• Simple truthiness: Only null and false are falsy (unlike JavaScript where 0, "", etc. are also falsy)
• Short-circuiting via compiler: No AND/OR opcodes—compilers use JUMP patterns for proper short-circuit evaluation
• Variadic parameters: Functions can collect remaining positional arguments into an array using ...rest syntax
• Named parameters (kwargs): Functions can collect unmatched named arguments into a dict using @kwargs syntax
• Argument binding priority: Named args can bind to regular params first, with unmatched ones going to @kwargs