Built-in Objects

<!-- doc-length-limit: 1000 -->

For contributors adding or modifying built-in objects, and for script authors looking up available APIs.

Executive Summary#

• Core vs runtime registration — TGocciaEngine always registers core language built-ins (Math, Object, Array, String, Number, RegExp, JSON, Symbol, Set, Map, Promise, Temporal, Intl, ArrayBuffer, SharedArrayBuffer, Atomics, TypedArrays, Proxy, Reflect, Iterator, DisposableStack, etc.); Goccia.Runtime provides optional runtime globals (Console, JSON5, JSONL, TOML, YAML, CSV, TSV, Performance, TextEncoder/TextDecoder, URL, fetch, Headers, Response, SemVer)
• Runtime opt-ins — Testing, benchmarking, FFI, and data-format APIs extend the runtime surface through concrete runtime extension classes
• Sandbox modules — GocciaSandboxRunner installs import-only "fs" and "goccia" modules for sandbox filesystem and shell/nested-execution access; they are not globals
• ECMAScript shims — Legacy standard names such as global parseInt, parseFloat, isNaN, isFinite, Date, __proto__, and legacy getter/setter helpers are installed through Goccia.shims
• Adding new built-ins — See Adding Built-in Types for the step-by-step recipe
• Always-present globals — globalThis and Goccia namespace are registered after all built-ins

GocciaScript provides a set of built-in global objects that mirror JavaScript's standard library. Core language built-ins are implemented as Pascal units and registered by the engine. Runtime globals live behind runtime extensions so binaries can import only the runtime surface they need. Test assertions, benchmarks, and FFI are runtime-level opt-ins.

Registration System#

Core language built-ins (Math, Object, Array, Number, JSON, Symbol, Set, Map, WeakSet, WeakMap, Promise, Temporal, Intl, ArrayBuffer, SharedArrayBuffer, Atomics, Proxy, Reflect, etc.) are always registered unconditionally by the engine.

Runtime globals (Console, JSON5, JSONL, TOML, YAML, CSV, TSV, Performance, TextEncoder/TextDecoder, URL, fetch, Headers, Response, SemVer) are registered by the loader runtime profile and runtime extension classes under source/units/Goccia.RuntimeExtensions.*.pas. CLI hosts such as GocciaScriptLoader and GocciaREPL call ApplyLoaderRuntimeProfile; GocciaTestRunner applies the loader runtime profile plus TGocciaTestingLibraryRuntimeExtension; GocciaBenchmarkRunner applies the loader runtime profile plus TGocciaBenchmarkRuntimeExtension. GocciaScriptLoaderBare does not attach a runtime and exposes only a CLI-local print(...args) helper by default; the test262 conformance runner may opt into private test262 host capabilities with --test262-host.

GocciaSandboxRunner applies the loader runtime profile and then installs TGocciaSandboxRuntimeExtension. That extension registers sandbox capabilities as import-only global modules named "fs" and "goccia"; it does not create global fs, $, or runScript bindings.

FFI is not part of the loader runtime profile. CLI tools install TGocciaFFIRuntimeExtension when --unsafe-ffi is passed or "unsafe-ffi": true is set in config.

Adding a New Built-in#

See Adding a New Built-in Type for the complete step-by-step guide with code templates, GC considerations, and a checklist.

Available Built-ins#

Console (Goccia.Builtins.Console.pas)#

Implements the WHATWG Console Standard. Not implemented: console.dirxml, console.groupCollapsed, console.profile, console.profileEnd, console.timeStamp.

Output capture: The console supports an OutputCallback hook for capturing output programmatically (see Embedding — Console Output Capture).

Separately, the TGocciaCLIApplication-based CLI hosts use LogCallback for --log=<file>, which writes every console call to the specified file in [method] line format while preserving normal stdout output.

Math (Goccia.Builtins.Math.pas)#

Implements the ECMAScript Math object. See MDN Math reference for the full API.

Full standard compliance — all standard constants and methods are available.

Extras:

Data Formats (JSON, JSON5, YAML, JSONL, CSV, TSV, TOML)#

See Data Format Built-ins for the complete JSON, JSON5, YAML, JSONL, CSV, TSV, and TOML API reference.

Object (Goccia.Builtins.GlobalObject.pas)#

Implements the ECMAScript Object. See MDN Object reference for the full API.

Full standard compliance — all standard static methods and prototype methods are available.

GocciaScript-specific behavior: Object.hasOwn supports class values and checks static properties (not private fields).

Array (Goccia.Builtins.GlobalArray.pas)#

Implements the ECMAScript Array. Not implemented: Array.prototype.reduceRight.

Static methods:

Prototype methods (implemented directly on TGocciaArrayValue):

Number (Goccia.Builtins.GlobalNumber.pas)#

Implements the ECMAScript Number. See MDN Number reference for the full API.

Full standard compliance — all standard static methods, constants, and prototype methods are available.

Default guidance: Prefer Number.parseInt, Number.parseFloat, Number.isNaN, and Number.isFinite in new code. The legacy global names are installed as shims for ECMAScript compatibility; parseInt and parseFloat delegate to their Number.* counterparts, while isNaN and isFinite preserve the standard global coercion behavior.

BigInt (Goccia.Builtins.GlobalBigInt.pas)#

Implements ECMAScript BigInt (ES2020). See MDN BigInt reference for the full API.

Related: BigInt64Array and BigUint64Array are implemented — see Binary Data Built-ins.

String (Goccia.Builtins.GlobalString.pas)#

Implements the ECMAScript String.

String constructor available as String().

Static methods:

String prototype methods are implemented on string values:

charAt, charCodeAt, codePointAt, indexOf, lastIndexOf, includes, startsWith, endsWith, slice, substring, toLowerCase, toUpperCase, toLocaleLowerCase, toLocaleUpperCase, trim, trimStart, trimEnd, repeat, replace, replaceAll, split, match, matchAll, search, padStart, padEnd, concat, at, localeCompare, normalize, isWellFormed, toWellFormed, [Symbol.iterator]

replace, replaceAll, split, match, matchAll, and search also honor custom objects implementing the corresponding Symbol.replace, Symbol.split, Symbol.match, Symbol.matchAll, or Symbol.search hooks.

[Symbol.iterator]() returns an iterator that yields individual characters.

RegExp (Goccia.Builtins.GlobalRegExp.pas)#

Implements the ECMAScript RegExp including modifiers, duplicate named groups, and RegExp.escape.

RegExp is available as both RegExp() and new RegExp(). Regex literals (/pattern/flags) are also supported in interpreter mode and bytecode mode. Calling RegExp(existingRegExp) without new and without an explicit flags argument returns the original regex object; new RegExp(existingRegExp) clones it.

Supported flags: d, g, i, m, s, u, v, y

Constructor properties:

Static methods:

Prototype methods:

Behavior notes:

• Inline modifier groups ((?ims-ims:...)) are supported per the RegExp Modifiers specification. Only i (ignoreCase), m (multiline), and s (dotAll) are valid modifier flags. The colon form is required — bare (?ims) without : is a SyntaxError. Duplicate flags and flags appearing in both enable and disable sections are rejected. Modifiers are scoped to the group body; outer flags are unaffected.
• Named capture groups ((?<name>...)) are supported. Group names must use valid identifier-name code points. Match results include a groups property (an object with null prototype) mapping group names to matched strings. Non-participating named groups are undefined. When no named groups exist, groups is undefined.
• Duplicate named capture groups: the same group name may appear in different alternatives of a disjunction (|). For example, /(?<year>\d{4})-\d{2}|\d{2}-(?<year>\d{4})/. The groups property on the match result returns the value from whichever alternative participated; non-participating duplicates are undefined. Using the same name in the same alternative (where both groups could participate) is a SyntaxError.
• Named backreferences (\k<name>) reference a previously captured named group within the same pattern. With duplicate named capture groups, \k<name> resolves to the group with that name in the same alternative branch.
• Replacement strings in replace() and replaceAll() support $$, $&, the pre-match token $ followed by a backtick, $', numeric captures such as $1, and named group references $<name> for regex matches with named groups. An unmatched $<name> produces an empty string when named groups exist; $< without a closing > is literal.
• When the replacer is a function and named groups are present, the groups object is passed as the last argument after input.
• RegExp prototype symbol methods accept RegExp protocol objects with a callable exec method, while exec() and test() still require real RegExp instances.
• String.prototype.match, matchAll, replace, replaceAll, search, and split dispatch through the corresponding well-known symbol hooks, so custom protocol objects work as expected.
• matchAll() returns a lazy iterator that advances matches on demand per the specification.
• The u flag enables Unicode-aware pattern matching. Unicode property escapes (\p{Letter}, \P{ASCII}, etc.) are matched against Unicode code point range tables. Unicode code point escapes (\u{41}, \u{1F600}) are converted to UTF-8 byte sequences. Supported properties: L/Letter, Lu/Uppercase_Letter, Ll/Lowercase_Letter, N/Number, Nd/Decimal_Number, P/Punctuation, S/Symbol, Z/Separator, Cc/Control, ASCII, ASCII_Hex_Digit, White_Space. Unsupported properties throw SyntaxError. With i, Unicode-aware matching uses Unicode simple case folding, including single-code-point folds such as ſ to s, K to k, and ẞ to ß; it does not use full multi-code-point expansions such as ß to ss. The u flag enables correct AdvanceStringIndex for multi-byte UTF-8 sequences.
• The v flag (Unicode sets) is accepted and exposed through .flags and .unicodeSets. The u and v flags are mutually exclusive. Full Unicode set notation and properties of strings in character classes are not yet implemented beyond basic u flag behavior.
• The d flag (indices) is accepted and exposed through .flags and .hasIndices. Match arrays include indices entries as UTF-16 code unit [start, end] pairs, plus indices.groups for named captures.

Global Constants, Functions, and Error Constructors (Goccia.Builtins.Globals.pas)#

These core constants, functions, and error constructors are always registered (not flag-gated). Runtime extensions can add more globals or namespace properties.

Constants: undefined, NaN, Infinity, globalThis

globalThis is a const binding that holds a plain object populated with global scope bindings. It includes a self-referential globalThis property (globalThis.globalThis === globalThis). Runtime extensions and global-injection helpers call TGocciaEngine.RefreshGlobalThis after adding globals so enumeration and property access reflect the new bindings; the public refresh method delegates to the engine's internal global-object registration routine.

`Goccia` object:

A const global providing engine metadata and Goccia-owned utility APIs:

Goccia.shims

Goccia.shims lists the shim names registered by the engine for the current realm. These shims are active by default and are part of the ECMAScript conformance track, not a recommendation for new userland code. When a legacy ECMAScript global or prototype surface has a newer JavaScript spelling, the older surface should live here as a shim over the newer implementation.

Current default shims:

`Goccia.build`

Goccia.build exposes compile-time platform information, mirroring Deno.build:

`Goccia.semver`

Goccia.semver is provided by TGocciaRuntime; it is not part of the bare engine namespace. GocciaScriptLoaderBare exposes Goccia but does not expose Goccia.semver.

Goccia.semver exposes a SemVer 2.0.0 API modeled after the main node-semver export plus its documented module-group aliases:

Top-level methods follow node-semver naming and nullability conventions. The currently exposed main-export surface is:

valid, clean, parse, inc, prerelease, major, minor, patch, intersects, gt, gte, lt, lte, eq, neq, cmp, compare, rcompare, compareBuild, compareLoose, diff, sort, rsort, validRange, satisfies, maxSatisfying, minSatisfying, minVersion, gtr, ltr, outside, simplifyRange, subset, toComparators, coerce.

The constructor-backed objects mirror the node-semver public fields and core instance methods:

Global functions:

queueMicrotask shares the same microtask queue used by Promise reactions. Callbacks run after the current synchronous code completes but before the engine returns control. If a callback throws, the error is surfaced as an uncaught host callback error.

structuredClone creates a deep copy following the HTML spec's structured clone algorithm. Primitives are returned as-is. Objects, arrays, Maps, and Sets are recursively cloned. Circular references and shared references within the object graph are preserved (the same cloned object is reused). Non-serializable values (functions, symbols, WeakMaps, WeakSets, WeakRefs, FinalizationRegistries) throw a DOMException with name: "DataCloneError" and code: 25, matching browser and Node.js behavior. Accessor properties (getters/setters) are read via the getter and the resulting value is cloned as a data property on the clone.

btoa encodes a string to base64 following the WHATWG HTML spec §8.3. Each character in the input must have a code point ≤ U+00FF (Latin-1 range); characters outside this range throw a DOMException with name "InvalidCharacterError" and legacy code 5. The input is interpreted as a byte sequence where each code point maps 1:1 to a byte value.

atob decodes a base64 string following the WHATWG forgiving-base64-decode algorithm. ASCII whitespace (U+0009, U+000A, U+000C, U+000D, U+0020) is stripped before decoding. Missing = padding is tolerated. Invalid characters or an invalid length (length mod 4 = 1 after cleanup) throw a DOMException with name "InvalidCharacterError" and legacy code 5. The decoded bytes are returned as a string where each byte becomes a character (Latin-1 interpretation).

encodeURI / decodeURI / encodeURIComponent / decodeURIComponent follow the ECMA-262 URI handling specification. The shared encoding/decoding logic lives in Goccia.URI.pas and is also used by import.meta.url for file-path percent-encoding. Multi-byte Unicode characters are encoded as UTF-8 octets, each percent-encoded individually (e.g., encodeURIComponent("中") → %E4%B8%AD). Lone surrogates (U+D800–U+DFFF) throw URIError. Decoding validates UTF-8 well-formedness: overlong encodings, truncated sequences, and code points above U+10FFFF all throw URIError. decodeURI re-emits reserved characters as uppercase percent-encoded sequences even when the input uses lowercase hex digits (e.g., %2f → %2F).

Error constructors: Error, TypeError, ReferenceError, RangeError, SyntaxError, URIError, AggregateError, DOMException

Prototype chain: All error types follow the standard prototype hierarchy. TypeError.prototype, RangeError.prototype, etc. inherit from Error.prototype. Each error prototype has a constructor property pointing back to its constructor (e.g., Error.prototype.constructor === Error), so new TypeError("x").constructor.name === "TypeError". instanceof checks and cross-type checks also work correctly: new TypeError("msg") instanceof TypeError is true, new TypeError("msg") instanceof Error is true, and new TypeError("msg") instanceof RangeError is false.

Runtime errors: Errors thrown internally by the engine (e.g., TypeError from accessing a property on null/undefined, or RangeError from invalid ArrayBuffer length) have the same prototype chain as user-constructed errors. This means instanceof checks work correctly in catch blocks:

try { null.x; } catch (e) {
  e instanceof TypeError; // true
  e instanceof Error;     // true
}

Static methods:

Prototype methods:

All error constructors accept an optional second argument options with a cause property. AggregateError takes (errors, message, options?) where errors is an array of error objects. DOMException takes (message?, name?) where name defaults to "Error" — the code property is automatically set from the legacy error code mapping (e.g., "DataCloneError" → 25).

Each creates an error object with name, message, and stack properties. The stack property is a formatted string with the following structure:

ErrorName: message
    at functionName (filePath:line:col)
    at outerFunction (filePath:line:col)

Iterator (Goccia.Values.IteratorValue.pas, Iterator.Concrete.pas, Iterator.Lazy.pas, Iterator.Concat.pas, Iterator.Generic.pas)#

Implements the ECMAScript Iterator Helpers, Iterator Sequencing (Iterator.concat), and the Stage 3 Joint Iteration proposal (Iterator.zip).

All built-in iterators (Array, String, Map, Set) share a common Iterator.prototype with helper methods per the ECMAScript Iterator Helpers proposal:

Lazy helpers: map, filter, take, drop, and flatMap return new lazy iterators that advance the source on-demand — they do not eagerly consume the underlying iterator. Consuming methods (forEach, reduce, toArray, some, every, find) do consume the iterator.

Iterators are consumed once — calling next() past the end returns {value: undefined, done: true} forever. Spread ([...iter]), destructuring, and Array.from() all consume iterators via the [Symbol.iterator] protocol.

User-defined iterables: Objects with a [Symbol.iterator]() method that returns a plain {next()} object are fully supported. They work with spread, destructuring, Array.from(), and Iterator.from().

Static methods:

Symbol (Goccia.Builtins.GlobalSymbol.pas)#

Implements ECMAScript Symbol. Symbols are unique, immutable primitive values used as property keys. Also includes Symbol.metadata (TC39 decorator metadata), Symbol.dispose, Symbol.asyncDispose (TC39 explicit resource management), and Symbol.customMatcher (Stage 1 TC39 pattern matching) beyond the base standard.

Symbols can be used as computed property keys:

const sym = Symbol("myKey");
const obj = { [sym]: "value" };
obj[sym]; // "value"

Object.defineProperty and Object.getOwnPropertySymbols also support symbol keys. The in operator checks for symbol-keyed properties, including global registry symbols created via Symbol.for().

Prototype: Symbol.prototype is an object containing toString() and a description getter, matching ECMAScript semantics. All symbol instances share this prototype.

Coercion semantics: Implicit conversion of a symbol to string or number throws TypeError. Use String(symbol) or symbol.toString() for explicit string conversion. See value-system.md for details.

Set (Goccia.Values.SetValue.pas)#

Implements the ECMAScript Set including Set methods (union, intersection, difference, symmetricDifference, isSubsetOf, isSupersetOf, isDisjointFrom).

A collection of unique values with insertion-order iteration. Set operation methods accept either another Set or a set-like object with size, has(value), and keys().

Sets are iterable: [...mySet] spreads the set's values into an array.

WeakSet (Goccia.Values.WeakSetValue.pas)#

Implements the ECMAScript WeakSet.

A weak collection of object and non-registered symbol values. Entries do not keep their values alive; they are removed by GC after the value becomes unreachable elsewhere.

WeakSets intentionally do not expose size, clear, forEach, iteration, keys, values, or entries. Values must satisfy ECMAScript CanBeHeldWeakly: objects and non-registered symbols are accepted; primitives and Symbol.for() registry symbols throw from add() and construction.

Map (Goccia.Builtins.GlobalMap.pas)#

Implements the ECMAScript Map including Map.prototype.getOrInsert/getOrInsertComputed.

A collection of key-value pairs with insertion-order iteration. Any value (including objects) can be a key.

Static methods:

Maps are iterable: [...myMap] spreads the map into an array of [key, value] pairs.

WeakMap (Goccia.Values.WeakMapValue.pas)#

Implements the ECMAScript WeakMap including ES2026 WeakMap.prototype.getOrInsert and WeakMap.prototype.getOrInsertComputed.

A weak key-value collection where keys are objects or non-registered symbols. WeakMap entries do not keep keys alive. Values are traced only while their key is reachable from outside the WeakMap.

WeakMaps intentionally do not expose size, clear, forEach, iteration, keys, values, or entries. Keys must satisfy ECMAScript CanBeHeldWeakly: objects and non-registered symbols are accepted; primitives and Symbol.for() registry symbols throw from set(), upsert methods, and construction.

WeakRef (Goccia.Values.WeakRefValue.pas)#

Implements the ECMAScript WeakRef.

A weak reference to an object or non-registered symbol target. A WeakRef does not keep its target alive, but new WeakRef(target) and weakRef.deref() add the target to the current job's kept-objects set so it remains stable until the next job checkpoint.

Targets must satisfy ECMAScript CanBeHeldWeakly: objects and non-registered symbols are accepted; primitives and Symbol.for() registry symbols throw from construction. WeakRef.prototype[Symbol.toStringTag] is "WeakRef".

FinalizationRegistry (Goccia.Values.FinalizationRegistryValue.pas)#

Implements the ECMAScript FinalizationRegistry.

A finalization registry associates weakly held targets with held values. When a target becomes unreachable and Goccia.gc() runs, GocciaScript enqueues a cleanup job; cleanup callbacks run after the normal microtask queue rather than synchronously inside Goccia.gc().

Targets and unregister tokens must satisfy CanBeHeldWeakly. A held value may be any value except the exact same value as the target. Cleanup callbacks receive one held value argument. If a cleanup callback throws, the error is surfaced as an uncaught host callback error.

Promise (Goccia.Builtins.GlobalPromise.pas, Goccia.Values.PromiseValue.pas)#

Implements the ECMAScript Promise including Promise.withResolvers() and Promise.try(). See MDN Promise reference for the standard API.

An implementation of ECMAScript Promises with a synchronous microtask queue. .then() callbacks are always deferred (never synchronous), matching spec behavior.

Constructor:

const p = new Promise((resolve, reject) => {
  // executor runs synchronously
  resolve(42);
});

Prototype methods:

Static methods:

Microtask queue: .then() callbacks are enqueued as microtasks and drained automatically after script execution completes — the script is one macrotask, and microtasks drain after it finishes, matching ECMAScript specification behavior. Thenable adoption (resolving a Promise with another Promise) is deferred via a microtask per the spec's PromiseResolveThenableJob, ensuring correct ordering relative to other microtasks. If the script throws an exception, pending microtasks are discarded via ClearQueue in a finally block, preventing stale callbacks from leaking into subsequent executions. The test framework also drains microtasks after each test callback, so tests can return a Promise and place assertions inside .then() handlers. The benchmark runner drains after each measurement round.

Async test pattern:

test("async test", () => {
  return Promise.resolve(42).then((v) => {
    expect(v).toBe(42);
  });
});

If a test returns a rejected Promise, the test framework automatically fails the test with the rejection reason.

Thenable adoption: Resolving a Promise with another Promise causes it to adopt the inner Promise's state. Resolving a Promise with itself throws a TypeError ("Chaining cycle detected for promise"), matching ECMAScript spec behavior.

Error validation: Static combinator methods (Promise.all, Promise.allSettled, Promise.race, Promise.any) accept any iterable argument (arrays, strings, Sets, Maps). Non-iterable arguments (numbers, booleans, null, undefined, plain objects) cause the returned Promise to reject with a TypeError, matching ECMAScript spec behavior where the rejection is asynchronous rather than a synchronous throw.

Chaining and error recovery:

Promise.resolve(1)
  .then((v) => v + 1)        // 2
  .then((v) => { throw "err"; })
  .catch((e) => "recovered") // "recovered"
  .then((v) => v);           // "recovered"

Performance (Goccia.Builtins.Performance.pas)#

performance is exposed as a global Performance instance, not as a plain namespace object. The global Performance interface object is also exposed, with Performance.prototype === Object.getPrototypeOf(performance). now(), toJSON(), timeOrigin, and Symbol.toStringTag live on the shared prototype.

Core High Resolution Time API:

performance.now() uses TimingUtils.GetNanoseconds, so wall-clock changes do not affect it. performance.timeOrigin is captured once from TimingUtils.GetEpochNanoseconds when the built-in is created.

Performance() and new Performance() both throw TypeError ("Illegal constructor"), matching the web platform's non-constructible interface object behavior.

Temporal#

See Temporal Built-ins for the complete Temporal API reference (PlainDate, PlainTime, PlainDateTime, Duration, Instant, ZonedDateTime, and more).

Binary Data (ArrayBuffer, SharedArrayBuffer, Atomics, DataView, TypedArrays)#

See Binary Data Built-ins for the complete ArrayBuffer, SharedArrayBuffer, Atomics, DataView, and TypedArray API reference.

Sandbox Modules (Goccia.RuntimeExtensions.Sandbox.pas)#

Only available in GocciaSandboxRunner. The sandbox runner installs capabilities as import-only modules; it does not create global fs, $, or runScript bindings.

import fs from "fs";
import { $, runScript } from "goccia";

The "fs" module operates on the sandbox virtual filesystem. It follows a Node.js-shaped subset while keeping every path inside the sandbox namespace; it never reads from or writes to the host filesystem.

readFileSync returns a Uint8Array by default so binary seed entries can round-trip without text coercion.

The "goccia" module exposes sandbox runner orchestration helpers.

$ accepts tagged templates or command strings. Tagged-template substitutions are shell-quoted before command parsing.

const name = "hello world";
console.log(await $`echo ${name}`.text());

By default, nested execution shares the current virtual filesystem:

const child = runScript("/child.js");
const viaShell = await $`goccia /child.js`.text();

Pass { sandbox: true } to run the child in a fresh virtual filesystem. Seed entries are sourced from the current sandbox VFS, not from the host:

const child = runScript("/child.js", {
  sandbox: true,
  seed: [
    "/child.js",
    { from: "/lib", to: "/lib" },
    { path: "/input.txt", text: "inline text" },
    { path: "/data.bin", base64: "AQID" },
  ],
  diff: true,
  diffFormat: "json",
});

console.log(child.stdout);
console.log(child.diff);

seed accepts one entry or an array. A string entry copies that parent-VFS path to the same child path. { from, to } copies a parent file or directory into a child target path. When a file seed target ends in /, the file is copied under that directory with its source name. Inline { path, text } and { path, base64 } entries create child-only files.

The sandbox shell exposes the same child mode:

const out = await $`goccia --sandbox --seed /child.js --seed /lib=/lib --diff /child.js`.text();

Shell goccia supports --sandbox, repeatable --seed <from[=to]> / --seed=<from[=to]>, --diff, and --diff-format json|unified. Child diffs are appended to command stdout only when --diff is present.

FFI (Goccia.Builtins.GlobalFFI.pas)#

Foreign Function Interface for calling native shared libraries. Only available when TGocciaFFIRuntimeExtension is installed (CLI tools do this for --unsafe-ffi or "unsafe-ffi": true in config).

FFI global object:

FFILibrary methods:

FFIPointer properties:

Supported FFI types: i8, i16, i32, i64, u8, u16, u32, u64, f32, f64, pointer, cstring, bool, void (return only). i64/u64 are not available on i386. Max 8 arguments per function. Pointer arguments accept FFIPointer, ArrayBuffer, SharedArrayBuffer, TypedArray, or null.

Test Assertions (Goccia.Builtins.TestingLibrary.pas)#

Only available when TGocciaTestingLibraryRuntimeExtension is installed in the runtime.

Test structure:

describe("group name", () => {
  test("test name", () => {
    expect(value).toBe(expected);
  });
});

Functions: describe, describe.skip, describe.skipIf, describe.runIf, describe.only, describe.each, test, it (alias for test), test.skip, test.skipIf, test.runIf, test.only, it.only, test.each, test.todo, beforeAll, beforeEach, afterEach, afterAll

Vitest-style structure helpers:

• beforeAll(fn) / afterAll(fn) run once per suite around that suite's tests
• beforeEach(fn) / afterEach(fn) are suite-scoped and inherited by nested suites
• test.each(table)(name, fn) expands one test per table row and passes row values as callback arguments
• describe.each(table)(name, fn) expands one suite per table row and passes row values as callback arguments
• test.only(...), it.only(...), and describe.only(...) focus execution to the selected tests/suites
• test.todo(name) registers a placeholder test that is reported as skipped but never executed

Matchers:

All matchers support .not negation: expect(value).not.toBe(wrong).

.toMatch() accepts either a string substring or a RegExp object. Regex matches ignore the regex's current lastIndex, matching Jest/Vitest-style assertion ergonomics.

Benchmark (Goccia.Builtins.Benchmark.pas)#

Only available when TGocciaBenchmarkRuntimeExtension is installed in the runtime (used by the GocciaBenchmarkRunner). See benchmarks.md for usage, output formats, and CI integration.

Benchmark structure:

suite("group name", () => {
  bench("benchmark name", () => {
    // Code to benchmark — called many times during measurement
    someOperation();
  });
});

Functions:

Result object (returned by runBenchmarks()):

Each benchmark result includes: name, suite, opsPerSec, meanMs, iterations, totalMs, variancePercentage, and optionally error.

Proxy (Goccia.Builtins.GlobalProxy.pas, Goccia.Values.ProxyValue.pas)#

Implements the ECMAScript Proxy. See MDN Proxy reference for the full API.

GocciaScript differences: None -- all 13 handler traps are supported with full invariant enforcement. Both string and symbol property keys work. Proxy.revocable() is supported.

Reflect (Goccia.Builtins.GlobalReflect.pas)#

Implements the ECMAScript Reflect. See MDN Reflect reference for the full API.

GocciaScript differences: None -- all 13 Reflect methods are supported with both string and symbol property keys.

TextEncoder (Goccia.RuntimeExtensions.TextEncoding.pas, Goccia.Values.TextEncoderValue.pas)#

Implements the Encoding Standard TextEncoder. See MDN TextEncoder reference for the full API.

GocciaScript differences: None -- full standard compliance (UTF-8 only, with encode and encodeInto).

TextDecoder (Goccia.RuntimeExtensions.TextEncoding.pas, Goccia.Values.TextDecoderValue.pas)#

Implements the Encoding Standard TextDecoder. See MDN TextDecoder reference for the full API.

GocciaScript differences: Only "utf-8" encoding is supported. The fatal and ignoreBOM options are accepted.

URL (Goccia.Builtins.GlobalURL.pas)#

Implements the WHATWG URL Standard. See MDN URL reference for the full API.

GocciaScript differences: None -- full standard compliance.

URLSearchParams (Goccia.Values.URLSearchParamsValue.pas)#

Implements the WHATWG URLSearchParams. See MDN URLSearchParams reference for the full API.

GocciaScript differences: None -- full standard compliance.

fetch (Goccia.Builtins.GlobalFetch.pas)#

Implements a subset of the WHATWG Fetch Standard. Only GET and HEAD methods are supported; other methods throw TypeError.

The options object supports method ("GET" or "HEAD") and headers (plain object or Headers instance). Redirects (301/302/303/307/308) are followed automatically up to 20 hops. HTTPS uses the platform TLS backend: SecureTransport on macOS, SChannel on Windows, and OpenSSL on Linux. macOS and Windows builds do not require OpenSSL libraries for HTTPS; Linux supports OpenSSL 3 runtime-only installs as well as compatible older OpenSSL library names.

Allowed hosts — fetch requires an explicit allowlist of hostnames. Without --allowed-host or an "allowed-hosts" config key in goccia.json, any call to fetch throws TypeError. Add one or more allowed hosts via CLI or config:

./build/GocciaScriptLoader example.js --allowed-host=api.example.com --allowed-host=cdn.example.com

{ "allowed-hosts": ["api.example.com", "cdn.example.com"] }

Host matching is case-insensitive and ignores port, path, and userinfo. Only the hostname portion of the URL is checked.

GocciaScript differences: GocciaScript implements a focused subset of fetch:

• HTTP methods: only GET and HEAD are supported.
• Absent features: no Request object, AbortSignal, streaming body, or CORS.
• Runtime behavior: requests run on fetch-specific background workers and settle their Promise on the owning runtime thread. await fetch(...) still synchronously waits by pumping fetch completions.
• Concurrency cap: each runtime caps active fetch workers at 16; additional calls reject their returned Promise with TypeError until a worker finishes.
• Configuration: requires --allowed-host or an "allowed-hosts" config key in goccia.json.

Headers (Goccia.Values.HeadersValue.pas)#

Implements the WHATWG Fetch Headers interface.

GocciaScript differences: Read-only on Response headers. No append, set, or delete mutations.

Response (Goccia.Values.ResponseValue.pas)#

Implements the WHATWG Fetch Response interface.

GocciaScript differences: No Response.body (ReadableStream), blob(), formData(), or clone(). Body is fully buffered. Each body method can only be called once.

DisposableStack / AsyncDisposableStack (Goccia.Builtins.DisposableStack.pas)#

Implements Explicit Resource Management. See MDN DisposableStack reference for the full API.

GocciaScript differences: None -- full proposal compliance. Both DisposableStack (sync) and AsyncDisposableStack (async) are supported. SuppressedError is thrown when both the block body and a disposer throw, with error (body error) and suppressed (dispose error) properties.