GocciaScript

A drop of JavaScript — A subset of ECMAScript 2026+ implemented in FreePascal

It's based on the thought "What if we implement ECMAScript today, but without the quirks of early ECMAScript implementations". Features that are error-prone, redundant, or security risks are intentionally excluded. See Language Restrictions for the full rationale.

Features

Language Features

• Variables: let and const declarations (no var)
• Functions: Arrow functions only (no function keyword)
• Classes: Full class support with private fields (#field), static methods, getters/setters, inheritance, and decorators
• Equality: Strict equality only (=== / !==)
• Strict Mode: Implicit — all code runs in strict mode
• Template Literals: String interpolation with ${expression}
• Destructuring: Array and object destructuring patterns
• Spread/Rest: ... operator for arrays, objects, and function parameters
• Async/Await: async arrow functions and methods, await expressions
• Iteration: for...of loops over iterables (arrays, strings, Sets, Maps, custom iterables)
• Async Iteration: for await...of loops over async iterables
• Regular Expressions: RegExp, regex literals, and string integration via match, matchAll, replace, replaceAll, search, and split
• Modules: ES6-style import/export
• No eval: Excluded for security
• No arguments: Use rest parameters (...args) instead

ES6+ Features

| Feature | Example | |---------|---------| | Template strings | `Hello, ${name}!` | | Object shorthand properties and methods | { x, y, method() {} } | | Computed property names | { [expr]: value } | | Nullish coalescing | a ?? b | | Nullish coalescing assignment | a ??= b | | Optional chaining | obj?.prop?.method?.() | | Arrow functions | (x) => x + 1 | | Rest parameters | (...args) => args | | Destructuring | const { a, b } = obj | | Spread operator | [...arr], { ...obj } | | Unicode escapes | \uXXXX, \u{XXXXX}, \xHH | | Function length and name | fn.length, fn.name | | Symbol | Symbol("desc"), Symbol.iterator | | Promise | Constructor, .then/.catch/.finally, all/allSettled/race/any | | Object.freeze, Object.isFrozen | Immutable objects | | Array.from, Array.of, Array.fromAsync | Array construction (sync and async) | | async/await | async () => { await promise; } | | for...of | for (const x of iterable) { ... } |

ECMAScript 2022–2025 Features

| Feature | Spec | |---------|------| | Private fields, methods, getters, setters | ES2022 | | Array.prototype.at | ES2022 | | Object.hasOwn | ES2022 | | structuredClone | ES2022 | | Array.prototype.findLast, findLastIndex | ES2023 | | Array.prototype.toReversed, toSorted, toSpliced, with | ES2023 | | Object.groupBy, Map.groupBy | ES2024 | | Promise.withResolvers | ES2024 | | String.prototype.isWellFormed, toWellFormed | ES2024 | | Set methods: union, intersection, difference, symmetricDifference, isSubsetOf, isSupersetOf, isDisjointFrom | ES2025 | | Promise.try | ES2025 | | Iterator Helpers: map, filter, take, drop, flatMap, forEach, reduce, toArray, some, every, find | ES2025 |

TC39 Proposals

GocciaScript implements several active TC39 proposals:

| Proposal | Stage | Description | |----------|-------|-------------| | Decorators | 3 | Class, method, field, getter/setter, auto-accessor decorators with addInitializer | | Decorator Metadata | 3 | Symbol.metadata for decorator-attached class metadata with inheritance | | Types as Comments | 1 | TypeScript-style type annotations parsed by the frontend; in bytecode mode, annotations and inferred types provide runtime enforcement (reassignment to incompatible types throws TypeError) | | Enum Declarations | 0 | Frozen, null-prototype enum objects with Symbol.iterator | | Temporal | 3 | Modern date/time API (Temporal.PlainDate, Temporal.Duration, Temporal.Instant, etc.) | | Math.clamp | 3 | Clamp a value to a range | | Math.sumPrecise | 3 | Precise summation of iterables using compensated algorithm | | Map.prototype.getOrInsert | 3 | Get existing value or insert a default / computed value | | Error.isError | 4 | Reliable brand check for error objects via [[ErrorData]] |

See Language Restrictions for details on supported syntax.

Built-in Objects

console, Math, JSON, Object, Array, Number, String, RegExp, Symbol, Set, Map, Promise, Temporal, Iterator, ArrayBuffer, SharedArrayBuffer, TypedArrays (Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array) with ArrayBuffer and SharedArrayBuffer backing, plus error constructors (Error, TypeError, ReferenceError, RangeError, DOMException).

See Built-in Objects for the complete API reference.

Example

class CoffeeShop {
  #name = "Goccia Coffee";
  #beans = ["Arabica", "Robusta", "Ethiopian"];
  #prices = { espresso: 2.5, latte: 4.0, cappuccino: 3.75 };

  getMenu() {
    return this.#beans.map((bean) => `${bean} blend`);
  }

  calculateTotal(order) {
    return order.reduce((total, item) => total + (this.#prices[item] ?? 0), 0);
  }

  get name() {
    return this.#name;
  }
}

const shop = new CoffeeShop();
const order = ["espresso", "latte"];
const total = shop.calculateTotal(order);

console.log(`Welcome to ${shop.name}!`);
console.log(`Your order total: $${total.toFixed(2)}`);

Getting Started

Prerequisites

• FreePascal compiler (fpc)
  • macOS: brew install fpc
  • Ubuntu/Debian: sudo apt-get install fpc
  • Windows: choco install freepascal

Build

# Dev build of everything (default — debug info, heap trace, checks)
./build.pas

# Production build (O4, stripped, smart-linked)
./build.pas --prod

# Build specific components
./build.pas loader           # Dev build of script executor
./build.pas --prod loader    # Production build of script executor
./build.pas repl             # Interactive REPL
./build.pas testrunner       # Test runner
./build.pas benchmarkrunner  # Benchmark runner

Run a Script

./build.pas loader && ./build/ScriptLoader example.js
printf "const x = 2 + 2; x;" | ./build/ScriptLoader

Run via Bytecode

GocciaScript includes a bytecode execution backend. The public bytecode artifact is .gbc, and WASM emission is not supported.

# Compile and execute via bytecode
./build/ScriptLoader example.js --mode=bytecode
printf "const x = 2 + 2; x;" | ./build/ScriptLoader --mode=bytecode

# Compile to .gbc bytecode file (no execution)
./build/ScriptLoader example.js --emit

# Custom output path
./build/ScriptLoader example.js --emit --output=out.gbc
printf "const x = 2 + 2; x;" | ./build/ScriptLoader --emit --output=out.gbc

# Load and execute a pre-compiled .gbc file
./build/ScriptLoader example.gbc

# Emit structured JSON for programmatic consumers
printf "console.log('hi'); 2 + 2;" | ./build/ScriptLoader --output=json

# Inject globals from the CLI
printf "x + y;" | ./build/ScriptLoader --global x=10 --global y=20
printf "name;" | ./build/ScriptLoader --globals=context.json --output=json
printf "name;" | ./build/ScriptLoader --globals=context.yaml --output=json
# `--global name=value` parses inline values as JSON only; `--globals=file` accepts JSON or YAML by file extension.
# Injected globals can override earlier injected values, but not built-in globals like console

# Abort long-running scripts
printf "const f = () => f(); f();" | ./build/ScriptLoader --timeout=100

See Bytecode VM for the current bytecode backend architecture.

Start the REPL

./build.pas repl && ./build/REPL

Run Tests

GocciaScript has 3400+ JavaScript unit tests covering language features, built-in objects, and edge cases.

# Run all tests (GocciaScript TestRunner)
./build.pas testrunner && ./build/TestRunner tests

# Run a specific test
./build.pas testrunner && ./build/TestRunner tests/language/expressions/addition/basic-addition.js

# Run tests in standard JavaScript (Vitest) for cross-compatibility
npx vitest run

Run Benchmarks

# Run all benchmarks
./build.pas benchmarkrunner && ./build/BenchmarkRunner benchmarks

# Run a specific benchmark
./build/BenchmarkRunner benchmarks/fibonacci.js

# Run a benchmark from stdin
printf 'suite("stdin", () => { bench("sum", { run: () => 1 + 1 }); });\n' | ./build/BenchmarkRunner

# Export as JSON or CSV
./build/BenchmarkRunner benchmarks --format=json --output=results.json
./build/BenchmarkRunner benchmarks --format=csv --output=results.csv

The benchmark runner auto-calibrates iterations per benchmark, reports ops/sec with variance (CV%) and engine-level timing breakdown (lex/parse/execute). Output formats: console (default), text, csv, json. Calibration and measurement parameters are configurable via environment variables — see Benchmarks for details.

Quick Tour

GocciaScript looks like modern JavaScript — with a few intentional differences. Here's a taste of the language.

Arrow functions only — no function keyword:

const greet = (name) => `Hello, ${name}!`;
const add = (a, b) => a + b;

**No traditional loo