What the Class Is Used For

Use Chilkat.Js when an application needs to execute JavaScript internally while retaining control over what the script is allowed to access. By default, JavaScript executes in a closed, sandboxed environment with only the JavaScript language and standard library available. The host application may then selectively enable Chilkat classes, with optional filesystem access restrictions.

Run Embedded JavaScript Execute JavaScript code from a StringBuilder using Eval.

Call Script Functions Use CallFunction to call a JavaScript function by passing function name and arguments in JSON.

Sandbox Chilkat Access All Chilkat classes are disabled by default. Use SetCkPermission to enable specific classes or all classes with controlled filesystem permissions.

Prevent Infinite Loops Set TimeoutSeconds so JavaScript cannot run indefinitely.

Engine Characteristics

The Chilkat.Js engine is designed for embedding JavaScript inside applications with a small footprint and fast startup. It was originally derived from QuickJS and has since been modified, refactored, hardened, converted from C to C++, and integrated into the Chilkat runtime. It is now maintained as a separate closed-source Chilkat engine and does not track or merge future upstream QuickJS changes.

Characteristic	Meaning
Small and lightweight	Intended for embedded use without requiring a browser engine or Node.js runtime.
Fast startup	Prioritizes quick startup and embedded execution rather than long-running JIT-style optimization.
No external dependencies	Designed to be included as part of the Chilkat library without depending on large external JavaScript runtimes.
Cross-language and cross-platform	Works with programming languages and operating systems supported by Chilkat.
Sandboxed by default	JavaScript has no built-in operating-system access unless the host application explicitly enables selected Chilkat classes.
Modern JavaScript support	Supports modern ECMAScript capabilities such as ES2023 features, modules, async/await, generators, proxies, BigInt, typed arrays, and standard library objects.

Typical Workflow

Create a Js object.
Set TimeoutSeconds if scripts should be prevented from running indefinitely.
Enable any Chilkat classes the JavaScript is allowed to create by calling SetCkPermission.
Load the JavaScript source code into a StringBuilder.
Call Eval to execute the script and receive output or errors in a JsonObject.
Optionally call CallFunction to invoke a JavaScript function after evaluating the script.
Retrieve console output from the last Eval call using ConsoleOutputSb.
Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept	Meaning	Important Members
Embedded JavaScript Runtime	JavaScript runs inside the host application without a browser or Node.js.	Eval, CallFunction
Sandbox	The default execution environment exposes only JavaScript language features and standard library objects.	SetCkPermission
Chilkat Class Permissions	The host application decides whether JavaScript may instantiate Chilkat classes, and whether those classes can read or write the local filesystem.	SetCkPermission
Script Evaluation	A complete JavaScript script is executed, and output/errors are returned in JSON.	Eval
Function Calling	A specific JavaScript function can be called by passing its name and arguments as JSON.	CallFunction
Execution Timeout	A timeout can prevent JavaScript from running forever, such as in an infinite loop.	TimeoutSeconds

Properties

Property	Purpose	Guidance
TimeoutSeconds	Sets the maximum number of seconds a JavaScript script is allowed to run.	Default is 0, meaning no timeout is set. Without a timeout, an infinite loop will continue forever.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Script Execution Methods

Method	Purpose	Inputs	Output
Eval	Runs JavaScript as a script.	JavaScript source in a StringBuilder.	Returns output and errors in a JsonObject.
CallFunction	Calls a JavaScript function.	Function name and arguments in a JsonObject.	Function result in a JsonObject.
ConsoleOutputSb	Retrieves console output from the last call to Eval.	A target StringBuilder.	The console output is placed in the supplied StringBuilder.

Result handling: Eval and CallFunction both return a Boolean success/failure value and place structured output in the supplied JsonObject.

Sandbox and Permissions

By default, all Chilkat classes are disabled inside the JavaScript environment. JavaScript code cannot create Chilkat objects unless the host application enables the needed classes before calling Eval or CallFunction.

Permission	Object Creation	Filesystem Access	Typical Use
disable	Not allowed.	None.	Block JavaScript from creating instances of a Chilkat class.
sandbox	Allowed.	No local filesystem read or write access.	Allow a Chilkat class while preventing local file access.
readOnly	Allowed.	Read-only local filesystem access.	Allow scripts to use classes that need to read local files but not modify them.
writeOnly	Allowed.	Write-only local filesystem access.	Allow scripts to write local files without reading existing local content.
readWrite	Allowed.	Read and write local filesystem access.	Allow full local filesystem access for that Chilkat class.

Class scope: The chilkatClassName argument is case-insensitive and may be a specific class name such as Http, Rest, MailMan, Ftp2, or Ssh. It may also be all to apply a permission to all Chilkat classes.

Default security posture: All Chilkat classes are disabled by default. Enable only the classes and filesystem permissions that the script actually needs.

SetCkPermission

Argument	Meaning	Examples
chilkatClassName	The Chilkat class whose JavaScript access should be configured.	Http, Rest, MailMan, Ftp2, Ssh, all
permission	The sandbox permission applied to the class.	disable, sandbox, readOnly, writeOnly, readWrite

Failure behavior: If JavaScript attempts to create an instance of a Chilkat class that is disabled, a JavaScript exception is thrown.

Execution Safety

Risk	Relevant Member	How to Manage It
Infinite loop or long-running script	TimeoutSeconds	Set a non-zero timeout before evaluating untrusted, user-provided, or potentially long-running JavaScript.
Unwanted local filesystem access	SetCkPermission	Keep classes disabled, or use sandbox, readOnly, or writeOnly instead of readWrite.
Unexpected network or protocol access	SetCkPermission	Enable only the Chilkat classes needed by the script. For example, do not enable Http, Rest, Ssh, or Ftp2 unless the script should use them.
Hard-to-debug script failures	Eval, CallFunction, ConsoleOutputSb, LastErrorText	Inspect the result JSON, retrieve console output, and check diagnostic text.

Method Summary

Category	Members	Purpose
Script execution	Eval, CallFunction	Execute a full script or call a specific JavaScript function.
Script output	ConsoleOutputSb	Retrieve console output from the last script evaluation.
Sandbox control	SetCkPermission	Enable, disable, or restrict Chilkat class access inside JavaScript.
Execution control	TimeoutSeconds	Limit how long JavaScript may run.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Script never returns	TimeoutSeconds	Set a non-zero timeout before calling Eval or CallFunction.
JavaScript cannot create a Chilkat object	SetCkPermission	Confirm the needed class has been enabled before running the script. All classes are disabled by default.
JavaScript gets a filesystem access error	SetCkPermission	Confirm the class permission allows the required access: readOnly, writeOnly, or readWrite.
No console output is visible	ConsoleOutputSb	Call ConsoleOutputSb after Eval to retrieve console output from the last evaluation.
Function call result is unexpected	CallFunction	Verify that the function name and arguments in the input JSON match the JavaScript function that was defined by the evaluated script.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected script execution, permission setup, or function calling.

Common Pitfalls

Pitfall	Better Approach
Assuming JavaScript can use Chilkat classes by default.	Call SetCkPermission before Eval or CallFunction.
Granting readWrite access to all classes unnecessarily.	Enable only the specific classes required, and choose the narrowest permission that works.
Leaving TimeoutSeconds at 0 for untrusted scripts.	Set a timeout to prevent infinite loops from running forever.
Expecting ConsoleOutputSb to return output from every prior execution.	It returns console output from the last call to Eval.
Trying to call a function before evaluating the script that defines it.	Use Eval first, then CallFunction.
Ignoring the result JSON.	Eval and CallFunction return output and errors in the supplied JsonObject.

Best Practices

Recommendation	Reason
Set TimeoutSeconds for scripts that are not fully trusted.	It prevents accidental or malicious infinite loops from running indefinitely.
Enable only the Chilkat classes that are needed.	The default disabled state is the safest starting point.
Prefer sandbox permission when filesystem access is not required.	It allows object creation while preventing local filesystem reads and writes.
Use readOnly or writeOnly before choosing readWrite.	Narrow permissions reduce the effect of script bugs or unexpected behavior.
Inspect result JSON and console output during development.	These provide the clearest view of script output and script errors.
Use CallFunction for repeated structured calls into evaluated JavaScript.	It lets the host application pass function name and arguments in JSON and receive structured results in JSON.
Check LastErrorText after failures.	It provides useful diagnostic detail for script execution, permission configuration, function calling, and timeout-related failures.

Summary

Chilkat.Js is the Chilkat class for embedding and controlling a lightweight JavaScript engine inside an application. It can evaluate scripts, call JavaScript functions, return console output, limit execution time, and selectively enable Chilkat classes inside a sandboxed JavaScript environment. The engine is derived from QuickJS but has evolved into a separate closed-source Chilkat-maintained JavaScript engine.

The most important practical guidance is to keep the sandbox restrictive by default, explicitly enable only the Chilkat classes needed by the script, choose the narrowest filesystem permission that works, set a timeout for safety, and inspect the result JSON, console output, and LastErrorText when troubleshooting.

Chilkat.Js Class Overview