GiavaScript

GiavaScript is an open-source, cross-platform JavaScript runtime implemented in Crystal.

It intentionally does not aim for full ECMAScript compliance. Check the reference docs before relying on specific language features.

Quick start

Prerequisites

• Crystal 1.19.1 or later
• Python 3 (only needed to regenerate reference/REFERENCE.md)

Install the CLI

git clone https://github.com/memburg/GiavaScript.git
cd GiavaScript
./install.sh

This installs the giavascript binary to /usr/local/bin by default.

Install to a user-local path instead of /usr/local/bin:

INSTALL_DIR="$HOME/.local/bin" ./install.sh

Make sure your install directory is on PATH.

CLI usage

Start the REPL

giavascript

REPL commands:

• :quit exits the REPL.

Run a file

giavascript path/to/program.js

Behavior to expect:

• Empty files return an error.
• If a runtime error occurs, messages are written to standard error.
• Process exit code is 1 when any Error: message is produced; otherwise 0.

Run without installing

crystal run src/giavascript_cli.cr -- examples/templateLiterals.js

Development workflow

Install dependencies and run tests:

shards install
crystal spec

Regenerate consolidated reference docs after editing files under reference/:

python3 scripts/generate_reference.py

CI verifies that reference/REFERENCE.md matches generated output.

JavaScript feature reference

• Consolidated reference
• Language features
• Type methods and properties
• Math
• JSON

Examples

Sample programs are in examples/:

• examples/templateLiterals.js - string interpolation and expression formatting
• examples/arrayFlatFlatMapSplice.js - array manipulation methods
• examples/dateBasics.js - Date object usage
• examples/functionExpressionsAndOperators.js - function expressions and operators
• examples/multilineMethodChaining.js - method chaining patterns
• examples/objectKeysValuesEntries.js - Object.keys, values, entries
• examples/random.js - random number generation
• examples/tryCatchFinally.js - error handling with try/catch/finally

Run any example with:

giavascript examples/templateLiterals.js

Contributing

See CONTRIBUTING.md for setup, test, and documentation update guidelines.