oneecmaDocs
oneecma docs
Everything about OneEcma: getting started, host bindings, the error reports and their JSON form, source maps, record and replay, limits, how each built-in behaves, and how it is checked.
Start
Getting startedInstall OneEcma for .NET 10, evaluate JavaScript from C#, pass values and functions in, read the error report when a script fails, run untrusted code under limits, and check source without running it.OverviewOneEcma is not affiliated with or endorsed by Ecma International. ECMAScript® is a registered trademark of Ecma International.
Hosting
Host APIThe host API is the base layer: [JsExport] bindings, the JSON-Schema tool helper and ScriptEngine.Evaluate are all written with only the public types below, so a host can build its own happy path the same way. Nothing here uses reflection or emits code; it is safe under…[JsExport] bindingsMark a type with [JsExport] and a Roslyn generator (the RecursiveAI.OneEcma.Generators package, analyzer-only) writes its binding at build time. There is no reflection at run time, so it works under NativeAOT and trimming. Only exported members exist in script.Runtime, limits and the hostThis is the contract for code under Builtins/. You can write a built-in area (a constructor, its prototype and its static functions) from this page and the spec alone, without reading the VM. Everything here is internal to RecursiveAI.OneEcma unless marked public.
Reports
JSON reportThe JSON form of a report. It carries everything the text report shows, as data, so a host, an editor or an agent tool can read it without parsing text. The schema is docs/diagnostic-report.schema.json (JSON Schema 2020-12, $id urn:oneecma:diagnostic-report:1). The writer is…Stack traceserr.stack follows V8's format and the engine matches Node's output on the differential corpus (testdata/errors/cases.txt, 213 snippets; expected.json is what Node v24.22.1 printed, recorded by tools/errors-diff/record.js). The report's = stack: line and the JSON stack array…How help lines are chosenThe = help: line of a runtime report names the fix. It reads live values from a traced replay and never runs script.Syntax error wordingThe headline of every syntax error and early error is word for word what V8 puts in err.message, so scripts and error-reporting libraries that match on it keep working. The parser never invents a headline: explanations go in the label, help and note lines of the report.Auto-repair tableChanges since v1: R012 added (rank 7; every later rank moves down one), R001 also removes a run of adjacent unmatched closers, R007 also erases the annotation of a const/let/var declaration whose first error is the missing initializer, and the machine-readable file is…Source mapsReports about minified, bundled or transpiled code point at the source the author wrote. The consumer follows ECMA-426 (https://tc39.es/ecma426/); this page lists what it does where the specification leaves room, and how reports use it. Types live in…Record log and replayA record log holds everything a run took from outside the engine, in order, so the run can be replayed in a fresh engine and give the same values, exceptions and report bytes. Recording is on by default (ScriptEngine.RecordLog, or pass your own through…
Language and built-ins
Arrays and iteratorsImplementation notes for Array, the array iterators, Iterator and the iterator helpers. The algorithms follow ECMA-262 (17th edition) step by step; this page records only what the specification leaves open or what differs from it on purpose.Binary dataNormative notes for the binary-data built-ins (ECMA-262 17th edition, clauses 23.2, 23.3, 25.1-25.4). Where the specification leaves room, this file says what the engine does.String, Number, JSONWhat these built-ins do where ECMA-262 leaves room, the wording of the errors they raise, and where they differ from the reference engine (Node v24.22.1). The recorded evidence is in testdata/builtins/ (scripts plus the reference output; BuiltinsDifferentialTests replays them).Collections and ProxyNormative notes for the places where ECMA-262 leaves room or where the engine chooses a mechanism.DateNormative description of Date as implemented in Builtins/Date*.cs: ECMA-262 17th edition 21.4 and Annex B.2.3.RegExpNormative description of the pattern parser, compiler, matcher, limits and data tables in src/RecursiveAI.OneEcma/RegExp/. A port reproduces the behaviour from this page, ECMA-262 (17th edition) §22.2 and Annex B.1.2, and the V8 wording table at the end.
Intl and Unicode
IntlNormative description of the engine-internal services behind Intl.NumberFormat, PluralRules, ListFormat, RelativeTimeFormat, DisplayNames, DateTimeFormat, DurationFormat, time zone identifiers and the locale machinery, as implemented in RecursiveAI.OneEcma.Intl. The…Locale dataNormative description of the data the Intl implementation reads: where it comes from, the embedded format, and how to add a locale. A port must be able to reproduce the format from this text.Text servicesNormative description of the three Unicode text services the engine builds on: normalization (UAX #15), collation (UTS #10 with the CLDR root order and UTS #35 tailorings) and segmentation (UAX #29). They are internal C# services in RecursiveAI.OneEcma.TextServices…
Internals
Syntax treeNormative description of what JsParser.Parse produces. A port must reproduce the tree shape, the scope information and the error behavior described here.The executorResult of a measured spike (a throwaway study project). Two executors were built over the real syntax tree and benchmarked against each other and against Jint 4.17.0 on the same sources.BenchmarksThroughput is not the product, but it has a floor: real page scripts must stay usable. The floor is roughly at most 2× Jint's time on a small suite. This page records how the suite is run and the latest numbers.
Reference
Docs mapThese files describe behaviour the specifications leave open, the formats the engine writes, and the choices behind them. They are written so a port to another language can reproduce the behaviour from the text.ChangelogAll notable changes are listed here. The format follows Keep a Changelog and versions follow Semantic Versioning.