Built-in Objects

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, Performance, TextEncoder/TextDecoder, URL, fetch, Headers, Response, AbortController/AbortSignal, EventTarget/Event) and import-only goccia: runtime modules
• Runtime opt-ins — Testing, benchmarking, FFI, data-format APIs, and SemVer extend the runtime surface through concrete runtime extension classes
• Goccia runtime modules — Non-standard data-format APIs and SemVer are named-export-only modules (goccia:csv, goccia:json5, goccia:jsonl, goccia:toml, goccia:tsv, goccia:yaml, goccia:semver); use namespace imports for CSV.parse(...)-style call sites
• 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 and runtime modules live behind runtime extensions so binaries can import only the runtime surface they need. Test assertions, benchmarks, data-format modules, SemVer, 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, Performance, TextEncoder/TextDecoder, URL, fetch, Headers, Response, AbortController/AbortSignal, EventTarget/Event) are registered by the loader runtime profile and runtime extension classes under source/units/Goccia.RuntimeExtensions.*.pas. The same runtime profile also installs named-export-only Goccia modules for non-standard data-format APIs and SemVer: goccia:csv, goccia:json5, goccia:jsonl, goccia:toml, goccia:tsv, goccia:yaml, and goccia:semver. It additionally registers the goccia:test module namespace without injecting any testing global, so the testing API is importable from every host that applies the profile. CLI hosts such as GocciaScriptLoader and GocciaREPL call ApplyLoaderRuntimeProfile; GocciaTestRunner applies the loader runtime profile with the module-only testing install suppressed and installs TGocciaTestingLibraryRuntimeExtension with global injection enabled instead, which is why it is the only binary with global describe/test/expect; GocciaBenchmarkRunner applies the loader runtime profile plus TGocciaBenchmarkRuntimeExtension. See Test Framework API for the per-binary table. 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 runtime 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.

ShadowRealm is a core language built-in but, like the Function constructor's dynamic-code capability, is installed only on demand. The engine registers globalThis.ShadowRealm (Goccia.Builtins.GlobalShadowRealm.pas) when --unsafe-shadowrealm is passed or "unsafe-shadowrealm": true is set in config, because ShadowRealm.prototype.evaluate performs dynamic source evaluation and ShadowRealm.prototype.importValue imports modules into the child realm. See ADR 0073 and the TC39 proposal table.

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)

JSON is the standard ECMAScript global. JSON5, YAML, JSONL, CSV, TSV, and TOML are import-only Goccia runtime modules with named exports and no default export. See Data Format Built-ins for the complete JSON and Goccia data-format module 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.

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. This shim policy is not a commitment to broad Annex B support; browser-only Annex B semantics are deferred before 1.0 unless a future Web API/browser-compatibility profile re-opens them. See ADR 0085.

Current default shims:

Goccia.build

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

goccia:semver module

The SemVer 2.0.0 API is provided by the loader runtime profile as the named-export-only module goccia:semver. It is not part of the bare engine namespace, not a property of Goccia, and not installed as a global. Use either named imports or a namespace import:

import { valid, SemVer } from "goccia:semver";
import * as semver from "goccia:semver";

There is no default export. The module exposes an 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. Properties are enumerated the way StructuredSerialize does, with EnumerableOwnPropertyNames (ECMA-262 §7.3.23): own, enumerable, string-keyed, each value taken with Get. Non-enumerable own properties are therefore skipped. Accessor properties (getters/setters) are read via the getter and the resulting value is cloned — the accessor itself is never preserved, so a getter that throws propagates out of structuredClone and one that returns an unserializable value raises DataCloneError. This applies to array indices exactly as it does to ordinary keys, and non-index own properties of an array are cloned too. Because deserialization installs each property with CreateDataProperty, descriptor flags do not survive the round trip: every property on the clone is a writable, enumerable, configurable data property, and a frozen source yields an unfrozen clone. Array holes are preserved, and the length is snapshotted before any getter runs.

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, EvalError, TypeError, ReferenceError, RangeError, SyntaxError, URIError, AggregateError, SuppressedError, 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), the Stage 4 Joint Iteration proposal (Iterator.zip), and the Stage 3 Iterator Includes proposal.

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, includes) do consume the iterator. includes closes the source when it finds a match, but leaves a normally exhausted source closed by exhaustion alone.

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 provides Node-compatible filesystem operations over the sandbox virtual filesystem. Its documented method set includes synchronous, callback, and promise forms, Stats, and Node-shaped errors while keeping every path inside the sandbox namespace; it never reads from or writes to the host filesystem. This covers the listed fs surface, not the entire Node.js host or every Node fs method.

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

Callback methods require a callable trailing callback and return undefined. Filesystem work and callback delivery are deferred through the engine's microtask job queue. Promise methods use the same deferred operation path and return a pending Promise. This preserves asynchronous sandbox behavior, but it does not reproduce Node's libuv event-loop phase ordering.

On success, readFile, readdir, and stat call (null, value); write/append/remove/rename/copy call (null); recursive mkdir calls (null, firstCreatedPath); and exists calls (boolean). Callback methods other than exists pass a filesystem Error as their only failure argument; exists converts filesystem failures to false. Unsupported Node-only paths and options such as file descriptors, URLs, AbortSignals, Dirent, bigint Stats, non-default copy modes, and alternate encodings are outside the supported subset. Callback methods throw a TypeError synchronously; Promise methods return a rejected Promise.

readFile supports UTF-8 text options, while mkdir and rm support the existing object-shaped recursive option.

Stats snapshots expose atime, mtime, ctime, and birthtime as lazy Date accessors on a realm-owned shared prototype. Each access returns a fresh Date; the corresponding *Ms number remains part of the original snapshot. isFile() and isDirectory() report the virtual node kind, while isSymbolicLink() always returns false because the sandbox VFS does not support symbolic links.

The VFS tracks the four timestamps independently. Reads advance access time; writes and truncation advance modification and change time; renames preserve access, modification, and birth time while advancing change time and affected directory metadata. Birth time is immutable. Copies receive fresh timestamps, while VFS forks used for baselines preserve the source timestamps.

Filesystem failures are real JavaScript Error objects with Node-shaped code, errno, path, syscall, and optional dest metadata. Synchronous methods throw them, callback methods pass them as their only argument, and promise methods reject with the same shape. See Sandbox filesystem errors for the full mapping and message format.

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());

failureKind says why a run ended, so an orchestrating script does not have to match on error text to tell a buggy child from one that hit a ceiling:

const child = runScript("/child.js");
if (child.failureKind === "resource-limit") {
  // Raise the ceiling or split the work; retrying unchanged will not help.
}

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,
  diffMetadata: 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. diffMetadata: true implies an isolated diff and adds timestamp changes as a separate metadata dimension; ordinary diffs remain content/namespace-only.

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, --diff-metadata, and --diff-format json|unified. --diff-metadata implies a diff. Child diffs are appended to command stdout only when a diff is requested.

FFI (Goccia.Builtins.GlobalFFI.pas)

See FFI Built-ins for the complete native-library, aggregate type, callback, lifetime, and safety reference.

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, onTestFinished

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). The benchmark API is import-only from "goccia:microbench"; it does not install ambient suite, bench, or runBenchmarks globals. See benchmarks.md for usage, output formats, and CI integration.

Benchmark structure:

import { bench, group } from "goccia:microbench";
​
group("group name", () => {
  bench("benchmark name", () => {
    // Code to benchmark — called many times during measurement
    someOperation();
  });
});

Functions:

Result object (returned by run()):

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 runtime APIs

The focused WHATWG fetch, Headers, Response, AbortController, AbortSignal, EventTarget, and Event surface is documented in Fetch Runtime APIs. AbortSignal inherits from EventTarget, so addEventListener, onabort, and the one-shot abort event are available; see ADR 0104.

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.