A JavaScript parser and interpreter written in Delphi/Object Pascal. It targets ECMAScript 5.1 and adds the ES2015 and later features listed below. The Conformance section describes how it is measured against test262.
JavaScript4D enables Delphi applications to parse and execute JavaScript code natively. It's designed to allow LLMs to write JavaScript functions that can be executed by Delphi code, bridging the gap between AI-generated scripts and native Delphi applications.
- ECMAScript 5.1 core: Most ES5.1 language features and built-ins, measured against test262 (see Conformance)
- ES2015 syntax:
letandconstwith block scope, arrow functions, template literals, enhanced object literals, default and rest parameters, spread, destructuring, andfor-ofover any iterable - Classes: class declarations and expressions with constructors, methods, getters and setters, static members, computed names,
extends(includingnulland the built-in constructors),super()calls,super.propertyin classes and object literal methods, andnew.target. Class fields, private members and static blocks are not supported - Symbol: symbols as property keys,
Symbol.forandSymbol.keyFor, all well-known symbols, and the protocolstoPrimitive,toStringTag,hasInstance,isConcatSpreadable,unscopablesandspecies - Map, Set, WeakMap and WeakSet: constructors that take iterables, SameValueZero keys, insertion order, iteration that sees additions and skips deletions made while it runs,
size,forEach,keys,valuesandentries. WeakMap and WeakSet hold their keys strongly until the engine is freed, which then empties every collection, so entries cannot keep objects alive past the engine - Promise:
Promisewiththen,catchandfinally,resolve,reject,all,allSettled,any,race,withResolversandtry, thenable assimilation, subclassing and species, andAggregateError. See Promises and the Job Queue for when the reactions run - Generators:
function*declarations and expressions, generator methods in object literals and classes,yieldandyield*(which forwardsnext,throwandreturnand closes the inner iterator),next,returnandthrowwithtry/finallysemantics,GeneratorFunction, and generators as iterables infor-of, spread and destructuring. Async generators are not supported - Async functions:
async functiondeclarations and expressions, async arrow functions and async methods in object literals and classes, andawaiton promises, thenables and plain values.Executereturns after the pending jobs have run. A rejected promise is thrown at theawait, and an uncaught error rejects the promise that the call returned. Async iteration (for await, async generators) is not supported __proto__: the__proto__accessor onObject.prototypeand__proto__: valuein object literals (Annex B)- Iterator protocol:
Symbol.iteratoron arrays, strings,arguments, maps and sets, array and string iterators, andfor-of, spread, array destructuring andArray.fromover any iterable, with iterator closing - Proxy and Reflect: all proxy traps with their invariants, and every
Reflectfunction - ArrayBuffer, DataView and typed arrays:
ArrayBuffer,DataViewwith endianness, and all typed array constructors with the%TypedArray%methods,fromandof; the host can detach buffers - ES2015 and later library methods:
Symbol.match,replace,searchandsplitonRegExp.prototypewith the String methods delegating to them, sticky and unicode regular expressions,String.prototype.replaceAll,at,String.fromCodePoint,Object.hasOwn,Object.setPrototypeOf,Object.fromEntries,Array.prototype.at,includes,flatandflatMap, and the**operator - Pure Delphi: No external dependencies or DLLs required
- Recursive Descent Parser: Clean AST-based architecture
- Built-in Objects: Array, String, Number, Object, Math, JSON, Date, RegExp support
- Locale-aware formatting:
toLocaleStringon numbers (decimal, percent and currency styles) and on dates (toLocaleString,toLocaleDateString,toLocaleTimeString) for en-US, en-GB, nl-NL, nl-BE, de-DE, fr-FR, es-ES and it-IT, from built-in tables that give the same output on every platform. TheIntlobject is not provided - String normalization:
String.prototype.normalizefor NFC, NFD, NFKC and NFKD, built on the WindowsNormalizeStringfunction, so it is available on Windows only - Higher-Order Functions: map, filter, reduce, forEach, find, some, every
- Closures: Full support for lexical scoping and closures
- Error Handling: Try/catch/finally with TypeError, RangeError, SyntaxError, etc.
- Native Binding: Easy integration between Delphi and JavaScript
- Interruptible: A step budget and a thread-safe
Cancelstop a runaway script; call depth and allocation limits stop one that would crash the host
uses
JS4D.Engine;
var
Engine: TJSEngine;
begin
Engine := TJSEngine.Create;
try
// Simple expression
var Result := Engine.Evaluate('1 + 2 * 3');
WriteLn(Result.ToString); // Output: 7
// Variables and functions
Engine.Execute('var x = 10;');
Engine.Execute('function double(n) { return n * 2; }');
Result := Engine.Evaluate('double(x)');
WriteLn(Result.ToString); // Output: 20
// Array operations
Engine.Execute('var nums = [1, 2, 3, 4, 5];');
Result := Engine.Evaluate('nums.map(function(x) { return x * 2; }).join(",")');
WriteLn(Result.ToString); // Output: 2,4,6,8,10
// Object literals
Engine.Execute('var person = { name: "John", age: 30 };');
Result := Engine.Evaluate('JSON.stringify(person)');
WriteLn(Result.ToString); // Output: {"name":"John","age":30}
finally
Engine.Free;
end;
end;Executing a script repeatedly in a long-lived engine (for example a render loop at 30 FPS) accumulates the scopes, functions and parsed programs created by each run. Call CollectGarbage to reclaim everything that is no longer reachable from global state, without recreating the engine and losing your globals:
while Running do
begin
Engine.Execute(FrameScript);
Engine.CollectGarbage;
end;Anything still referenced from a global variable, including closures, survives collection. Only script functions and scopes that the host retains directly (raw values held outside the engine) should not be relied upon across a collection; keep persistent state in globals.
CollectGarbage does not reclaim objects that only reference each other (a.b = b; b.a = a); in a running engine they live until the engine is freed. Freeing the engine releases all memory of every object it created, whatever the script did with cycles through objects, arrays, Map and Set entries, proxies, typed arrays, promises and generators.
A value that the host still holds when the engine is freed (a TJSValue returned by Evaluate, for example) keeps its contents, and so does everything it refers to; functions and the collections, promises and generators of the engine are emptied, and a script function or built-in function from the engine can no longer be called: calling it raises a TypeError instead of failing. Releasing a very deep chain of objects, arrays, Map and Set entries, iterators, proxies or promises does not recurse through one destructor per level, so it cannot overflow the stack. A cycle that the host keeps holding is not released by the host letting go of it; break the cycle first.
Promise reactions and the continuations of async functions are jobs in a queue that belongs to the engine. Execute runs the queue empty when the script ends, also when the script throws, so then callbacks and the code after an await have run when Execute returns:
Engine.Execute('Promise.resolve(1).then(function (v) { result = v + 1; });');
// result is already 2 hereJobs that are still waiting after that, because host code queued them outside a script, run with Engine.RunPendingJobs; with an empty queue it does nothing. Jobs count against the step budget like ordinary script code, so StepBudget stops a promise loop that never ends with EJSStepBudgetExceeded. A promise that is never settled leaves its callbacks unrun; freeing the engine releases them. Unhandled rejections are ignored.
A script written by an LLM, or by anyone else you do not control, can loop forever, recurse until the native stack overflows, or build a string until memory runs out. The engine counts the steps it takes and gives the host two ways to stop a run: a step budget it enforces itself, and a Cancel any thread may call. Two further limits, on call depth and on allocation size, are on by default and keep a script from crashing the host before the step budget bites.
A step is one statement executed, one iteration of a while, do-while, for or for-in loop, and one function call. Both checks happen at those points, so any script that runs away, by looping or by recursing, reaches one within a bounded number of steps.
StepBudget caps how many steps a single Execute may take. Zero, the default, means unlimited. Exceeding it raises EJSStepBudgetExceeded, which carries the budget it exceeded in its StepBudget property.
Engine.StepBudget := 1000000;
try
Engine.Execute(ScriptFromTheModel);
except
on E: EJSStepBudgetExceeded do
WriteLn(Format('Script stopped after %d steps', [E.StepBudget]));
end;StepCount reports the steps the last Execute took, whether it finished or was stopped. Set StepBudget before calling Execute: the budget and the count both apply to one run and reset at the start of the next.
Cancel is thread safe and may be called while Execute runs on another thread. The running script stops at the next check and Execute raises EJSExecutionCancelled on the thread that called it.
const Worker = TThread.CreateAnonymousThread(
procedure
begin
try
Engine.Execute(ScriptFromTheModel);
except
on EJSExecutionCancelled do
WriteLn('Script cancelled');
end;
end);
Worker.Start;
if not Worker.WaitFor(TimeoutMilliseconds) then
Engine.Cancel;Execute does not clear the flag. A Cancel that arrives between two runs stays pending, so the next Execute stops at its first check, which is what a host that runs several scripts as one job means by cancelling. The check falls every 1024 steps, or sooner when a step budget is closer, so a run that finishes inside that interval can still complete; the flag stays set and stops the run after it. Nothing clears it: an engine that has been cancelled is done, and work that must run afterwards belongs to a fresh engine.
Every JavaScript call recurses in the interpreter, so unbounded recursion overflows the native stack long before a step budget of a useful size is reached, and a stack overflow can take the host process down. Strings and arrays can likewise grow geometrically. These limits are enforced before the work is done:
| Property | Default | Limits | Raises |
|---|---|---|---|
MaxCallDepth |
100 | Nested calls of script functions | EJSCallDepthExceeded |
MaxStringLength |
16 Mi chars | The length of any string a script builds | EJSAllocationLimitExceeded |
MaxArrayLength |
1 Mi elements | The length of any array a script builds | EJSAllocationLimitExceeded |
What the limits cover. Zero turns a limit off.
MaxCallDepthcounts nested calls of script functions, including calls made throughmap,sort,call,apply,bindandnew. It also caps how deeply nested arrays and objects may be when the engine turns them into text or JSON, soa = [a]repeated thousands of times cannot overflow the stack inString(a),indexOf(a),JSON.stringify(a)and the like.MaxStringLengthapplies to the result of+,+=,concat,repeat,padStart,padEnd,joinandreplace, to every conversion of an array to a string (String(array),array + '', an array used as a property key or printed withconsole.log, and the pieces handed tojoinandconcat), and to the textJSON.stringifyproduces.MaxArrayLengthapplies to array literals,push,unshift,splice,concat,flat,split,Array.fromand assigning to an index past the end.- Other builtins only return results bounded by their own limited input and are not checked.
Checked before the work is done. The length is compared with the limit before the string or array is allocated: 'x'.repeat(1000000000) raises at once instead of asking for 2 GB, and padStart, concat, push, splice and the like do the same. Array-to-text conversion and JSON.stringify check the running length before each piece is appended; JSON.stringify measures the text of each value as it will be written, so many small numbers are not refused on a worst-case estimate.
Checked after the fact. A replace with a regular expression is refused up front when the source length plus the number of matches times the replacement length exceeds the limit, but a replacement that expands $ patterns is only caught by the check on the finished result. JSON.parse does not limit the arrays it builds from its input.
Source text. The parser and the evaluator check how much stack is left, so source of any shape ends in a RangeError instead of a stack overflow: long chains of operators, member accesses and calls are handled in loops, deep nesting of expressions, statements, functions, classes, templates and destructuring patterns is refused, and so is a regular expression whose groups nest too deeply. A regular expression whose matching needs more stack than the thread has left, such as a repeated group over a long text, runs again on a separate thread that reserves 256 MB of stack (128 MB in a Win32 build); a match that needs more than that raises a RangeError as well. Long lists of statements, arguments and array or object elements are not limited by the stack.
Cycles. An array that contains itself converts to a string the way JavaScript does (the repeated array is an empty element) and JSON.stringify of a circular structure raises a TypeError. A running engine does not collect reference cycles (see Memory Management), but a script can build as many as it likes: freeing the engine breaks every one of them.
Host-side conversion. TJSValue.ToString is meant for values the host holds. It caps array nesting at the default call depth but does not limit the text length; inside the engine every conversion goes through ToLimitedString with the engine's limits.
Engine.MaxCallDepth := 50;
Engine.MaxStringLength := 1024 * 1024;
try
Engine.Execute(ScriptFromTheModel);
except
on E: EJSCallDepthExceeded do
WriteLn(Format('Script nested deeper than %d calls', [E.MaxCallDepth]));
on E: EJSAllocationLimitExceeded do
WriteLn(E.Message);
end;EJSAllocationLimitExceeded.Kind tells a string limit (Characters) from an array limit (Elements) and Limit carries the limit that was exceeded. The default call depth leaves a wide margin on a default 1 MB Win64 thread stack: a plain recursion overflows it at roughly 870 nested calls in a Debug build, and scripts that nest more expressions per call overflow it at roughly 465, so the default of 100 keeps at least a 4x margin. A host that runs scripts on a thread with a smaller stack, or that registers native functions which call back into the engine, should lower MaxCallDepth accordingly.
All the interrupting exceptions (the two above and the limit exceptions) derive from EJSExecutionInterrupted and none can be caught by the script itself: a catch block in JavaScript never sees them, and a finally block does not run once one is raised. After a step budget or a limit stopped a script the engine stays usable with its global state intact, so the next Execute starts from wherever the stopped script left the globals.
- Variables (
var,let,constwith block scope and temporal dead zone) - Functions (declaration and expression)
- Control flow (
if,else,for,while,do-while,switch) - Operators (arithmetic, comparison, logical, bitwise)
- Object literals and property access (shorthand properties, methods, computed keys, getters and setters)
- Arrow functions with lexical
thisandarguments - Classes (
class,extends,super,new.target, static members, accessors, computed names) - Generators (
function*,yield,yield*), async functions withawait, and Promises - Nullish coalescing (
??) and numeric separators (1_000); optional chaining and logical assignment are not supported - The
__proto__accessor and__proto__: valuein object literals - Template literals and tagged templates,
String.raw - Default parameters, rest parameters and spread in calls, arrays and objects
- Destructuring in declarations, parameters, assignments and
for-ofheads, with defaults and rest for-ofover arrays, strings and array-likes- Array literals and indexing
- Try/catch/finally
Array Methods
push,pop,shift,unshiftindexOf,lastIndexOf,includesjoin,slice,splice,concat,reversemap,filter,reduce,reduceRightforEach,find,findIndexsome,every,sortfill,copyWithin,flatArray.isArray,Array.from,Array.of,keys,valuesandentries
String Methods
charAt,charCodeAtindexOf,lastIndexOf,includessubstring,substr,slicesplit,trim,trimStart,trimEndtoLowerCase,toUpperCasereplace,concat,repeatstartsWith,endsWithpadStart,padEnd
Object Methods
Object.keys,Object.values,Object.entriesObject.assign,Object.createhasOwnProperty
JSON
JSON.parse,JSON.stringify
Math
- All standard Math functions (
abs,floor,ceil,round,sqrt,pow,min,max,random,sin,cos,tan, etc.)
Global Functions
parseInt,parseFloatisNaN,isFiniteDate.now,Date.parse
JavaScript Source Code
│
▼
┌─────────────────┐
│ Lexer │ → Tokens
└─────────────────┘
│
▼
┌─────────────────┐
│ Parser │ → Abstract Syntax Tree (AST)
└─────────────────┘
│
▼
┌─────────────────┐
│ Interpreter │ → Execution Result
└─────────────────┘
Javascript4D/
├── Source/
│ ├── API/ # Public Engine API
│ ├── Core/ # Types, Errors
│ ├── Lexer/ # Tokenizer
│ ├── Parser/ # AST Builder
│ └── Runtime/ # Interpreter, Built-ins
├── Demo/ # VCL demo application
├── Tests/ # DUnitX unit tests
└── CLAUDE.md # Claude Code instructions
Requires Delphi 10.3 (RAD Studio Rio) or later. The packages folder has a runtime package for each RAD Studio version from 10.3 to 13.0.
Open the project in RAD Studio IDE or use MSBuild:
msbuild Tests/JS4D.Tests.dproj /p:Configuration=Release /p:Platform=Win64
msbuild Demo/JS4D.Demo.dproj /p:Configuration=Release /p:Platform=Win64Run the compiled test executable JS4D.Tests.exe from your build output directory.
The Conformance folder holds a runner for test262, the ECMAScript conformance suite. It runs test/language and test/built-ins against JS4D and reports how many tests pass.
powershell -File Conformance/fetch-test262.ps1
powershell -File Conformance/run-conformance.ps1fetch-test262.ps1 checks out test262 at a pinned commit into Conformance/test262. run-conformance.ps1 always rebuilds the runner before running it, so the pass list never comes from an executable older than the sources. Runner options go through -RunnerArguments, for example -RunnerArguments '-filter=built-ins/Array' for a path prefix, -budget=N for the step budget per script, -results=DIR for the output folder, and -test262=DIR, -exclusions=FILE and -path-exclusions=FILE to point at another test262 checkout or other skip lists.
Conformance/results/baseline.txt holds the pass rate per directory and the totals after a run.
Tests that need features JS4D does not implement are skipped. Conformance/exclusions.txt lists the skipped feature tags and Conformance/excluded-paths.txt the skipped path prefixes; together they are the roadmap: implement a feature, remove its entry, and its tests run. A few skip rules live in Conformance/JS4D.Conformance.Selector.pas instead: fixture files, the flags module, CanBlockIsFalse and CanBlockIsTrue, negative tests of the resolution phase, and tests that use the host members $262.createRealm, $262.agent or $262.IsHTMLDDA. The baseline.txt report counts each skipped test under its reason. Tests with the async flag run: the engine drains the job queue when the script ends and the runner reads the result that $DONE printed.
Results go to Conformance/results: baseline.txt (totals, skips and pass rate per directory), failures.txt (one path [variant] detail line per failing test) and passed.txt (one path [variant] line per passing test, sorted, for comparing runs).
MIT License
Contributions are welcome! Please feel free to submit pull requests.
This library is MIT licensed and free to use. For companies that depend on it commercially we offer support and maintenance agreements with guaranteed response times, and sponsored development of features you need. Contact us at gdksoftware.com/contact-us or open an issue to get in touch.