{"id":31700500,"url":"https://github.com/frostney/gocciascript","last_synced_at":"2026-04-22T21:02:07.102Z","repository":{"id":296911036,"uuid":"990259012","full_name":"frostney/GocciaScript","owner":"frostney","description":"A drop of JavaScript - An embeddable and sandboxed runtime (being a ECMAScript 2027 subset) for AI agents and humans","archived":false,"fork":false,"pushed_at":"2026-04-19T12:28:57.000Z","size":15108,"stargazers_count":9,"open_issues_count":20,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-19T13:23:16.461Z","etag":null,"topics":["ecmascript","fpc","freepascal","interpreter","javascript","jsx","object-pascal","pascal","runtime","typescript"],"latest_commit_sha":null,"homepage":"","language":"Pascal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frostney.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-25T20:21:09.000Z","updated_at":"2026-04-19T10:58:04.000Z","dependencies_parsed_at":"2025-06-03T10:02:09.922Z","dependency_job_id":"0faf039f-4af3-4de3-a6bf-323b889b8226","html_url":"https://github.com/frostney/GocciaScript","commit_stats":null,"previous_names":["frostney/gocciascript"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/frostney/GocciaScript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frostney%2FGocciaScript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frostney%2FGocciaScript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frostney%2FGocciaScript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frostney%2FGocciaScript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frostney","download_url":"https://codeload.github.com/frostney/GocciaScript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frostney%2FGocciaScript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32154688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecmascript","fpc","freepascal","interpreter","javascript","jsx","object-pascal","pascal","runtime","typescript"],"created_at":"2025-10-08T20:40:53.469Z","updated_at":"2026-04-22T21:02:07.060Z","avatar_url":"https://github.com/frostney.png","language":"Pascal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GocciaScript\n\n![GocciaScript logo](./logo.png)\n\nA drop of JavaScript — A subset of ECMAScript 2027+ implemented in FreePascal\n\nIt'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](docs/language.md) for the full rationale.\n\n## Features\n\nGocciaScript implements a modern subset of ECMAScript: `let`/`const`, arrow functions, classes with private fields, `for...of`, async/await, ES modules (named only), decorators, and TypeScript-style type annotations. Features that are error-prone, redundant, or security risks (`var`, `function` keyword, `==`/`!=`, `eval`, traditional loops) are intentionally excluded.\n\nSee [Language](docs/language.md) for the complete specification of supported features, TC39 proposals, and exclusions.\n\n### Built-in Objects\n\n`console`, `Math`, `JSON`, `JSON5`, `TOML`, `YAML`, `JSONL`, `CSV`, `TSV`, `Object`, `Array`, `Number`, `String`, `RegExp`, `Symbol`, `Set`, `Map`, `Promise`, `Temporal`, `Iterator`, `Proxy`, `Reflect`, `ArrayBuffer`, `SharedArrayBuffer`, TypedArrays (`Int8Array`, `Uint8Array`, `Uint8ClampedArray`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array`, `Float32Array`, `Float64Array`) with ArrayBuffer and SharedArrayBuffer backing, `fetch`, `Headers`, `Response` ([WHATWG Fetch](https://fetch.spec.whatwg.org/) — GET/HEAD only), `URL`, `URLSearchParams`, `TextEncoder`, `TextDecoder`, plus error constructors (`Error`, `TypeError`, `ReferenceError`, `RangeError`, `DOMException`).\n\nSee [Built-in Objects](docs/built-ins.md) for the complete API reference.\n\n## Example\n\n```javascript\nclass CoffeeShop {\n  #name = \"Goccia Coffee\";\n  #beans = [\"Arabica\", \"Robusta\", \"Ethiopian\"];\n  #prices = { espresso: 2.5, latte: 4.0, cappuccino: 3.75 };\n\n  getMenu() {\n    return this.#beans.map((bean) =\u003e `${bean} blend`);\n  }\n\n  calculateTotal(order) {\n    return order.reduce((total, item) =\u003e total + (this.#prices[item] ?? 0), 0);\n  }\n\n  get name() {\n    return this.#name;\n  }\n}\n\nconst shop = new CoffeeShop();\nconst order = [\"espresso\", \"latte\"];\nconst total = shop.calculateTotal(order);\n\nconsole.log(`Welcome to ${shop.name}!`);\nconsole.log(`Your order total: $${total.toFixed(2)}`);\n```\n\n## Getting Started\n\n### Prerequisites\n\n- [FreePascal](https://www.freepascal.org/) compiler (`fpc`)\n  - macOS: `brew install fpc`\n  - Ubuntu/Debian: `sudo apt-get install fpc`\n  - Windows: `choco install freepascal`\n\n### Build\n\n```bash\n# Dev build of everything (default — debug info, heap trace, checks)\n./build.pas\n\n# Production build (O4, stripped, smart-linked)\n./build.pas --prod\n\n# Build specific components\n./build.pas loader           # Dev build of script executor\n./build.pas --prod loader    # Production build of script executor\n./build.pas repl             # Interactive REPL\n./build.pas testrunner       # Test runner\n./build.pas benchmarkrunner  # Benchmark runner\n```\n\n### Run a Script\n\n```bash\n./build.pas loader \u0026\u0026 ./build/GocciaScriptLoader example.js\nprintf \"const x = 2 + 2; x;\" | ./build/GocciaScriptLoader\n```\n\nScript files may start with a Unix shebang line like `#!/usr/bin/env goccia`; GocciaScript ignores that first line during lexing.\n\n### Run via Bytecode\n\nGocciaScript includes a bytecode execution backend. The public bytecode artifact is `.gbc`.\n\n```bash\n# Compile and execute via bytecode\n./build/GocciaScriptLoader example.js --mode=bytecode\nprintf \"const x = 2 + 2; x;\" | ./build/GocciaScriptLoader --mode=bytecode\n\n# Compile to .gbc bytecode file (no execution) — use GocciaBundler\n./build/GocciaBundler example.js\n./build/GocciaBundler example.js --output=out.gbc\n\n# Load and execute a pre-compiled .gbc file\n./build/GocciaScriptLoader example.gbc\n\n# Emit structured JSON for programmatic consumers\nprintf \"console.log('hi'); 2 + 2;\" | ./build/GocciaScriptLoader --output=json\n\n# Inject globals from the CLI\nprintf \"x + y;\" | ./build/GocciaScriptLoader --global x=10 --global y=20\nprintf \"name;\" | ./build/GocciaScriptLoader --globals=context.json --output=json\nprintf \"name;\" | ./build/GocciaScriptLoader --globals=context.json5 --output=json\nprintf \"name;\" | ./build/GocciaScriptLoader --globals=context.toml --output=json\nprintf \"name;\" | ./build/GocciaScriptLoader --globals=context.yaml --output=json\n# `--global name=value` parses inline values as JSON only; `--globals=file` accepts JSON, JSON5, TOML, or YAML by file extension.\n# Injected globals can override earlier injected values, but not built-in globals like console\n\n# Abort long-running scripts\nprintf \"const f = () =\u003e f(); f();\" | ./build/GocciaScriptLoader --timeout=100\n```\n\nSee [Bytecode VM](docs/bytecode-vm.md) for the current bytecode backend architecture.\n\n### Start the REPL\n\n```bash\n./build.pas repl \u0026\u0026 ./build/GocciaREPL\n```\n\n### Run Tests\n\nGocciaScript has 3400+ JavaScript unit tests covering language features, built-in objects, and edge cases.\n\n```bash\n# Run all tests (GocciaScript TestRunner)\n./build.pas testrunner \u0026\u0026 ./build/GocciaTestRunner tests\n\n# Run a specific test\n./build.pas testrunner \u0026\u0026 ./build/GocciaTestRunner tests/language/expressions/addition/basic-addition.js\n\n# Run tests with 4 parallel workers\n./build.pas testrunner \u0026\u0026 ./build/GocciaTestRunner tests --jobs=4\n\n# Run tests in standard JavaScript (Vitest) for cross-compatibility\nnpx vitest run\n```\n\n### Run Benchmarks\n\n```bash\n# Run all benchmarks\n./build.pas benchmarkrunner \u0026\u0026 ./build/GocciaBenchmarkRunner benchmarks\n\n# Run a specific benchmark\n./build/GocciaBenchmarkRunner benchmarks/fibonacci.js\n\n# Run a benchmark from stdin\nprintf 'suite(\"stdin\", () =\u003e { bench(\"sum\", { run: () =\u003e 1 + 1 }); });\\n' | ./build/GocciaBenchmarkRunner\n\n# Run benchmarks sequentially (single worker)\n./build/GocciaBenchmarkRunner benchmarks --jobs=1\n\n# Export as JSON or CSV\n./build/GocciaBenchmarkRunner benchmarks --format=json --output=results.json\n./build/GocciaBenchmarkRunner benchmarks --format=csv --output=results.csv\n```\n\nThe 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](docs/benchmarks.md#configuring-benchmark-parameters).\n\n## Quick Tour\n\nGocciaScript looks like modern JavaScript — with a few intentional differences:\n\n- **Arrow functions only** — `const greet = (name) =\u003e \\`Hello, ${name}!\\`;` (no `function` keyword)\n- **No traditional loops** — `numbers.map((n) =\u003e n * 2)` or `for (const n of numbers) { ... }`\n- **Classes** with private fields — `class Account { #balance = 0; ... }`\n- **Named imports/exports only** — `import { add } from \"./math.js\";` (no default exports)\n- **Strict equality only** — `===` and `!==` (no `==` or `!=`)\n\nThe CLI tools share WHATWG-style import map support with `--import-map=\u003cfile.json\u003e`, `--alias key=value`, and automatic `goccia.json` discovery for project-level module aliases.\n\nStructured data files and text assets can also be imported directly:\n\n```javascript\nimport { name, version } from \"./package.json\";\nimport { name as packageName } from \"./config.toml\";\nimport { name as appName } from \"./config.yaml\";\nimport { content, metadata } from \"./README.md\";\n```\n\nRuntime parsers are available for JSON5, TOML, YAML, JSONL, CSV, and TSV. See [Built-in Objects](docs/built-ins.md) and [Language](docs/language.md) for the full data format reference.\n\n`TOML.parse(sourceText)` parses TOML 1.1.0 configuration data. `YAML.parse(sourceText)` handles common configuration files including block scalars, anchors/aliases, merge keys, and YAML 1.2 tag resolution. See [Language](docs/language.md#modules) and [Decision Log](docs/decision-log.md) for the full conformance details.\n\nJSONL parsing is also available via `JSONL.parse(text)` and `JSONL.parseChunk(text)`, and `.jsonl` files can be imported as structured-data modules.\n\n**Async/await** with full Promise support, including top-level `await`:\n\n```javascript\nconst fetchData = async () =\u003e {\n  const result = await Promise.resolve({ status: \"ok\" });\n  return result;\n};\n\n// Top-level await (ES2022+)\nconst data = await fetchData();\n```\n\n**Strict equality only** — `===` and `!==` (no `==` or `!=`).\n\nFor a full guided walkthrough, see the [Tutorial](docs/tutorial.md). For the complete list of what's supported and excluded, see [Language](docs/language.md).\n\n## Architecture\n\nGocciaScript supports two execution backends that share the same frontend (lexer, parser, AST):\n\n```mermaid\nflowchart LR\n    Source[\"Source Code\"] --\u003e Lexer --\u003e Parser --\u003e AST\n    AST --\u003e Interpreter[\"Tree-Walk Interpreter\"] --\u003e Result1[\"Result\"]\n    AST --\u003e Compiler[\"Bytecode Compiler\"] --\u003e VM[\"Goccia VM\"] --\u003e Result2[\"Result\"]\n```\n\nBoth backends share the same value types, built-ins, scope chain, and mark-and-sweep GC. The bytecode backend is a Goccia-owned VM with tagged `TGocciaRegister` values (unboxed scalars) that fall back to `TGocciaValue` for heap objects, not a generic VM layer.\n\nSee [Architecture](docs/architecture.md) for pipelines and layers, [Interpreter](docs/interpreter.md) for the tree-walk backend, [Bytecode VM](docs/bytecode-vm.md) for the bytecode backend, and [Core patterns](docs/core-patterns.md) for implementation patterns and internal terminology.\n\n## Design Principles\n\n- **Explicitness**: Modules, classes, methods, and properties use explicit, descriptive names even at the cost of verbosity. Shortcuts are avoided.\n- **OOP over everything**: Rely on type safety of specialized classes rather than generic data structures.\n- **Define vs Assign**: `Define` creates a new variable binding; `Assign` changes an existing one. These are distinct operations throughout the codebase (see [Core patterns](docs/core-patterns.md#define-vs-assign)).\n- **Pure evaluation**: The evaluator is composed of pure functions with no side effects.\n- **No global mutable state**: All runtime state flows through explicit parameters — the evaluation context, the scope chain, and value objects.\n- **Virtual dispatch**: Property access (`GetProperty`/`SetProperty`), type discrimination (`IsPrimitive`/`IsCallable`), and scope chain resolution (`GetThisValue`/`GetOwningClass`/`GetSuperClass`) all use virtual methods, replacing type checks with single VMT calls.\n\nSee [Core patterns](docs/core-patterns.md) and [Interpreter](docs/interpreter.md) for the design rationale.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Project Goals](docs/goals.md) | Why GocciaScript exists: sandboxed AI agent runtime and embeddable desktop platform |\n| [Tutorial](docs/tutorial.md) | Your first GocciaScript program — a guided walkthrough for newcomers |\n| [Language](docs/language.md) | ECMAScript subset, excluded features, and rationale |\n| [Language Tables](docs/language-tables.md) | Quick-reference: ECMAScript feature matrix and TC39 proposal status |\n| [Built-in Objects](docs/built-ins.md) | Available built-ins and API reference |\n| [Temporal Built-ins](docs/built-ins-temporal.md) | Temporal API: dates, times, durations, time zones |\n| [Binary Data Built-ins](docs/built-ins-binary-data.md) | ArrayBuffer, SharedArrayBuffer, TypedArray API |\n| [Errors](docs/errors.md) | Error types, parser/runtime display, JSON output, `Error.cause`, `try`/`catch`/`finally` |\n| [Architecture](docs/architecture.md) | Pipelines, main layers, design direction, duplication boundaries |\n| [Interpreter](docs/interpreter.md) · [Bytecode VM](docs/bytecode-vm.md) | Tree-walk and bytecode execution backends |\n| [Core patterns](docs/core-patterns.md) | Recurring implementation patterns, internal terminology |\n| [Value System](docs/value-system.md) | Type hierarchy, virtual property access, primitives, objects |\n| [Garbage Collector](docs/garbage-collector.md) | Mark-and-sweep GC: architecture, contributor rules, design rationale |\n| [Adding Built-in Types](docs/adding-built-in-types.md) | Step-by-step guide for adding new built-in types |\n| [Embedding the Engine](docs/embedding.md) | Embedding GocciaScript in FreePascal applications |\n| [Testing](docs/testing.md) | Test organization, running tests, coverage, CI |\n| [Test Framework API](docs/testing-api.md) | Assertions, mocks, lifecycle hooks, async patterns |\n| [Benchmarks](docs/benchmarks.md) | Benchmark runner, output formats, writing benchmarks |\n| [Build System](docs/build-system.md) | Build commands, compiler configuration, CI/CD |\n| [Profiling](docs/profiling.md) | Bytecode VM profiling: opcodes, functions, output formats |\n| [Decision Log](docs/decision-log.md) | Chronological record of key architectural decisions |\n| [Contributing](CONTRIBUTING.md) | Single contribution standard: workflow, mandatory rules, testing, FreePascal style |\n| [AGENTS.md](AGENTS.md) | Agent operating manual for coding assistants; [CONTRIBUTING.md](CONTRIBUTING.md) is the contributing guide for everyone |\n\n## Contributing\n\n**[CONTRIBUTING.md](CONTRIBUTING.md)** is the **contributing guide for all contributors** (humans and AI): workflow, mandatory rules, testing, FreePascal code style, `./format.pas`, editor setup, build/run quick reference, and the documentation index.\n\n**[AGENTS.md](AGENTS.md)** (and **CLAUDE.md**, which points to it) is **only for AI assistants**—how to use the repo and defer to CONTRIBUTING. It is not a second contributing guide and should stay short.\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrostney%2Fgocciascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrostney%2Fgocciascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrostney%2Fgocciascript/lists"}