# 🪸 ReefVM

It's where Shrimp live.

## Quickstart

    bun install
    bun test

## TODO (tests)

### Stack Operations
- [x] PUSH
- [x] POP
- [x] DUP

### Variables
- [x] LOAD
- [x] STORE

### Arithmetic
- [x] ADD
- [x] SUB
- [x] MUL
- [x] DIV
- [x] MOD

### Comparison
- [x] EQ
- [x] NEQ
- [x] LT
- [x] GT
- [x] LTE
- [x] GTE

### Logical
- [x] NOT
- [x] AND pattern (using JUMP_IF_FALSE for short-circuiting)
- [x] OR pattern (using JUMP_IF_TRUE for short-circuiting)

### Control Flow
- [x] JUMP
- [x] JUMP_IF_FALSE
- [x] JUMP_IF_TRUE
- [x] BREAK
- [x] CONTINUE

### Exception Handling
- [x] PUSH_TRY
- [x] PUSH_FINALLY
- [x] POP_TRY
- [x] THROW

### Functions
- [x] MAKE_FUNCTION
- [x] CALL
- [x] TAIL_CALL
- [x] RETURN

### Arrays
- [x] MAKE_ARRAY
- [x] ARRAY_GET
- [x] ARRAY_SET
- [x] ARRAY_LEN

### Dictionaries
- [x] MAKE_DICT
- [x] DICT_GET
- [x] DICT_SET
- [x] DICT_HAS

### TypeScript Interop
- [x] CALL_NATIVE

### Special
- [x] HALT

## Test Status

✅ **83 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
- **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

🚧 **Still TODO**:
- Advanced function features (kwargs, named arguments in CALL)