Your First GocciaScript Program

For developers who know JavaScript and want to learn GocciaScript — a guided walkthrough from hello world to a multi-file async program.

Executive Summary#

• Familiar syntax — GocciaScript runs modern ECMAScript syntax with sandbox-first recommended defaults; .js files, no transpilation needed
• Key differences — No var, function, traditional for loops, or while loops by default; use let/const, arrow functions, strict equality, for...of/array methods
• Full walkthrough — Variables, arrow functions, arrays, objects, classes, modules, async/await
• Next steps — Links to language restrictions, built-in API reference, and example programs

What is GocciaScript?#

GocciaScript is a FreePascal implementation of ECMAScript with sandbox-first recommended defaults. It keeps modern JavaScript syntax front and center — arrow functions, classes with private fields, async/await, modules, and implicit strict mode — while legacy forms such as var, function, loose equality, traditional for loops, and while loops are available through compatibility flags when conformance or host requirements need them. If you've written modern JavaScript, you already know most of GocciaScript.

Prerequisites#

You need the FreePascal compiler (fpc):

# macOS
brew install fpc

# Ubuntu/Debian
sudo apt-get install fpc

# Windows
choco install freepascal

Clone the repository and build the script loader:

git clone https://github.com/frostney/GocciaScript.git
cd GocciaScript
./build.pas loader

This produces build/GocciaScriptLoader, the command you'll use to run every script in this tutorial.

Hello, World#

Create a file called hello.js:

const message = "Hello from GocciaScript!";
console.log(message);

Run it:

./build/GocciaScriptLoader hello.js

You should see:

Hello from GocciaScript!

That's it — GocciaScript files are plain .js files. No special extension, no transpilation step.

Variables#

GocciaScript has two variable declarations: let (mutable) and const (immutable). There is no var.

const name = "Alice";
let score = 0;

score = score + 10;
console.log(`${name} scored ${score} points`);
// Alice scored 10 points

Attempting to reassign a const throws an error:

const x = 5;
x = 10; // TypeError: Assignment to constant variable

Arrow Functions#

GocciaScript uses arrow functions exclusively. The function keyword does not exist.

// Single expression — implicit return
const double = (n) => n * 2;

// Block body — explicit return
const greet = (name) => {
  const greeting = `Hello, ${name}!`;
  return greeting;
};

console.log(double(21));       // 42
console.log(greet("World"));   // Hello, World!

Arrow functions capture their surrounding scope's this — there's no this rebinding. For methods that need their own this, use shorthand method syntax inside classes or object literals.

Working with Arrays#

GocciaScript keeps traditional for loops and while loops off by default. Use array methods and for...of for new code:

const numbers = [1, 2, 3, 4, 5];

// Transform with map
const doubled = numbers.map((n) => n * 2);
console.log(doubled); // [2, 4, 6, 8, 10]

// Filter
const evens = numbers.filter((n) => n % 2 === 0);
console.log(evens); // [2, 4]

// Reduce
const sum = numbers.reduce((total, n) => total + n, 0);
console.log(sum); // 15

// Iterate with for...of
for (const n of numbers) {
  console.log(n);
}

All the modern array methods you'd expect are available: find, findLast, some, every, flat, flatMap, at, toSorted, toReversed, and more. See the Built-in Objects reference for the full list.

Objects#

Object literals work like JavaScript, including shorthand properties, computed keys, and methods:

const x = 10;
const y = 20;

const point = {
  x,
  y,
  distanceTo(other) {
    const dx = this.x - other.x;
    const dy = this.y - other.y;
    return Math.sqrt(dx ** 2 + dy ** 2);
  },
};

const origin = { x: 0, y: 0 };
console.log(point.distanceTo(origin)); // 22.360679774997898

Note that the distanceTo method uses shorthand method syntax (distanceTo() { ... }), not an arrow function. This is important: shorthand methods receive the call-site this (the object they're called on), while arrow functions inherit this from their enclosing scope.

Classes#

Classes support constructors, private fields, getters, setters, static methods, and inheritance:

Private names are validated at parse time: using an undeclared #name is a SyntaxError. Getter-only and setter-only private accessors also follow normal accessor semantics, so invalid writes or reads throw TypeError. Private static names are brand-checked against the actual class receiver, so inherited static calls like Derived.methodFromBase() cannot read or write Base's private static state through this.

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();
console.log(`Welcome to ${shop.name}!`);
console.log("Menu:", shop.getMenu());

const order = ["espresso", "latte"];
console.log(`Total: $${shop.calculateTotal(order).toFixed(2)}`);

Inheritance uses extends and super:

class Animal {
  constructor(name) {
    this.name = name;
  }

  speak() {
    return `${this.name} makes a sound`;
  }
}

class Dog extends Animal {
  speak() {
    return `${this.name} barks`;
  }
}

const dog = new Dog("Rex");
console.log(dog.speak());            // Rex barks
console.log(dog instanceof Animal);  // true

Modules#

GocciaScript supports ES-style default, named, and namespace imports and exports. Project examples prefer named exports for internal modules because explicit import names make refactors easier to review; default exports are supported when a module intentionally exposes a primary value or interoperates with code that uses default exports.

Create a file called math.js:

export const add = (a, b) => a + b;
export const multiply = (a, b) => a * b;

Import it from another file called app.js in the same directory:

import { add, multiply } from "./math.js";

console.log(add(2, 3));       // 5
console.log(multiply(4, 5));  // 20

Run the entry point:

./build/GocciaScriptLoader app.js

You can also rename imports with as:

import { add as sum } from "./math.js";
console.log(sum(1, 2)); // 3

Or import the full namespace object when you want all exports under one binding:

import * as math from "./math.js";
import * as config from "./config.json";

console.log(math.add(2, 3));   // 5
console.log(config.version);   // top-level JSON/TOML/YAML keys are namespace properties

Named imports and exports also support string-literal export names when a module exposes a name that is not a valid identifier:

import { "foo-bar" as fooBar } from "./config.json";
import { "0" as firstDoc } from "./multi.yaml";

const localValue = 42;
export { localValue as "0" };

And re-export from one module to another:

export { add, multiply } from "./math.js";

Async/Await#

Async functions and await work as you'd expect from modern JavaScript:

const fetchUser = async (id) => {
  const result = await Promise.resolve({ id, name: "Alice" });
  return result;
};

const main = async () => {
  const user = await fetchUser(1);
  console.log(`User: ${user.name}`);
};

main();

Promises are fully supported — .then(), .catch(), .finally(), Promise.all(), Promise.race(), Promise.any(), Promise.allSettled(), and Promise.withResolvers().

GocciaScript uses a synchronous microtask queue: all pending .then() callbacks are drained after synchronous code completes.

Strict Equality by Default#

GocciaScript uses strict equality by default. Use === and !== for predictable comparisons:

console.log(1 === 1);     // true
console.log(1 === "1");   // false
console.log(null === undefined); // false

The loose equality operators (== and !=) are available only in compatibility mode with --compat-loose-equality.

What's Different from JavaScript#

Here's a quick reference of GocciaScript's key restrictions:

These restrictions are intentional — they eliminate common sources of bugs and security issues. See Language for the full rationale.

Next Steps#

You now have a working understanding of GocciaScript. Here's where to go from here:

• [Language](language.md) — Full list of what's supported and what's excluded, with rationale
• [Built-in Objects](built-ins.md) — Complete API reference for all built-in objects (Array, String, Map, Set, Promise, Temporal, etc.)
• [`examples/`](../examples/) — More example programs: classes, promises, and unsupported feature demos
• [Architecture](architecture.md) — Pipelines and main layers
• [Interpreter](interpreter.md) and [Bytecode VM](bytecode-vm.md) — Tree-walk vs bytecode execution modes
• [Core patterns](core-patterns.md) — Recurring implementation patterns
• [GocciaScript Context](../CONTEXT.md) — Canonical project terminology