ReefVM/README.md

🪸 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
• 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_TYPESCRIPT

Special

• HALT

Test Status

✅ 40 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_LEN)
• All dictionary operations (MAKE_DICT, DICT_GET, DICT_SET, DICT_HAS)
• 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

🚧 Still TODO:

• Exception handling (PUSH_TRY, POP_TRY, THROW)
• Function operations (MAKE_FUNCTION, CALL, TAIL_CALL, RETURN)
• TypeScript interop (CALL_TYPESCRIPT)

Note: BREAK and CONTINUE are implemented but need CALL/RETURN to be properly tested with the iterator pattern.