ts-evaluator
v2.0.0
Published
An interpreter for Typescript that can evaluate an arbitrary Node within a Typescript AST
Downloads
322,045
Maintainers
Readme
An interpreter for Typescript that can evaluate an arbitrary Node within a Typescript AST
Description
This library is an implementation of an interpreter for Typescript that can evaluate any Expression
, ExpressionStatement
or Declaration
within a Typescript AST.
Rather than interpreting a program, or a sequence of Statement
s, this library takes a Node within an existing AST and evaluates it based on its' lexical environment.
This makes the library an effective companion if you're building a linter, framework, language service, partial evaluator, or something else where you may want to know the computed value of a specific Node at any point in an AST.
One strength of this plugin is that it opens up entirely new use cases such as partial evaluation directly in the editor experience, for example to catch non-syntactic bugs that would only occur on runtime, or more advanced diagnostic for frameworks.
To that end, several policy options can be provided to configure restrictions in terms of what is allowed to be evaluated, such as IO and Network access.
Additionally, ts-evaluator
supports both a Browser environment, a Node environment, and a pure ECMAScript environment. See Setting up an environment for more details.
If you are looking for a Typescript REPL, or a way to execute a full Typescript program, you're looking for something like ts-node instead.
Features
- Evaluate any Node within a Typescript AST and get an actual value back
- Supports browser-, node, and ECMA environments.
- Supports several reporting- and diagnostic hooks you can use use
- Is a full-featured JavaScript virtual machine
- Supports policy restrictions and sandboxing
Backers
Patreon
Table of Contents
Install
npm
$ npm install ts-evaluator
Yarn
$ yarn add ts-evaluator
pnpm
$ pnpm add ts-evaluator
Peer Dependencies
ts-evaluator
depends on typescript
, so you need to manually install this as well.
You may also need to install jsdom
depending on the features you are going to use. Refer to the documentation for the specific cases where it may be relevant.
Usage
Let's start off with a very basic example:
import {evaluate} from "ts-evaluator";
const result = evaluate({
node: someNode,
typeChecker: someTypeChecker
});
// If a value was produced
if (result.success) {
console.log(result.value);
}
// If an error occurred
else {
console.log(result.reason);
}
In this example, the referenced bindings within the lexical environment of the Node will be discovered and evaluated before producing a final value. This means that you don't have to evaluate the entire program to produce a value which may potentially be a much faster operation.
Behavior without a typechecker
If you do not have access to a typechecker, for example if you don't have a TypeScript Program to work with, you can avoid passing in a typechecker as an option.
This won't be as robust as when a typechecker is given, as ts-evaluator
won't understand the full type hierarchy of your Program, and most importantly not understand
how to resolve and dealias symbols and identifiers across source files, but it will still be able to resolve and evaluate identifiers and symbols that are located in the same
SourceFile. Uou may find that it works perfectly well for your use case.
Setting up an environment
You can define the kind of environment that evaluate()
assumes when evaluating the given Node. By default, a CommonJS-based Node
environment is assumed, to align with what you would get simply by running node
with no arguments.
The following environment presets are supported:
ECMA
- Assumes a pure ECMAScript environment. This means that no other globals than those that are defined in the ECMAScript spec such asMath
,Promise
,Object
, etc, are available.NODE
(default) - Assumes a CommonJS-based Node.js environment. This means that built-in modules such asfs
andpath
can be resolved, and Node-specific globals such asprocess
is present, as well as ones that are only present in a CommonJS-based Node.js environment, such asrequire
,__dirname
, and__filename
.NODE_CJS
- An alias forNODE
.NODE_ESM
- Assumes an ESM-based Node.js environment. This means that built-in modules such asfs
andpath
can be resolved, and Node-specific globals such asprocess
is present, as well as ones that are only present in an ESM-based Node.js environment, such asimport.meta
.BROWSER
- Assumes a Browser environment. This means that DOM APIs are available and Browser-specific globals such aswindow
is present.
Beyond presets, you can provide additional globals or override those that comes from the presets. Here's how you can configure environment options:
const result = evaluate({
// ...
environment: {
// The "Node" environment is the default one. You can simply omit this key if you are targeting a CommonJS-based Node environment
preset: "NODE",
extra: {
someGlobal: "someValue"
}
}
});
Setting up Policies
With great power comes great responsibility. If you are embedding this plugin in, say, a language service plugin to enhance the editing experience in an editor, you may want to apply some restrictions as to what can be evaluated.
By default, IO writes, network calls, and spawning child processes are restricted. You can customize this to your liking:
const result = evaluate({
// ...
policy: {
deterministic: false,
network: false,
console: false,
maxOps: Infinity,
maxOpDuration: Infinity,
io: {
read: true,
write: false
},
process: {
exit: false,
spawnChild: false
}
}
});
Here's an explainer of the individual policies:
deterministic
(default:false
) - Ifdeterministic
istrue
, only code constructs that always evaluate to the same value is permitted. This means that things likeMath.random()
ornew Date()
without arguments, as well as network calls are restricted. This is useful if you are trying to statically analyze something and need to make sure that the value won't change for each invocation.network
(default:false
) - Ifnetwork
istrue
, network activity is allowed, such as sending an HTTP request or hooking up a server.console
(default:false
) - Ifconsole
istrue
, logging to the console within evaluated code will produce the side-effect of actually logging to the console of the parent process. Usually, this is unwanted, since you're most likely only interested in the evaluated value, not so much the side-effects, but you can override this behavior by settingconsole
totrue
.maxOps
(default:Infinity
) - IfmaxOps
is anything less than Infinity, evaluation will stop when the provided amount of operations has been performed. This is useful to opt-out of running CPU-intensive code, especially if you are embedding this library in an editor or a linter.maxOpDuration
(default:Infinity
) - IfmaxOpDuration
is anything less than Infinity, evaluation will stop when the provided amount of milliseconds have passed. This is useful to opt-out of long-running operations, especially if you are embedding this library in an editor or a linter.io
(default:{read: true, write: false}
) - Ifio
permitsREAD
operations, files can be read from disk. Ifio
permitsWRITE
operations, files can be written to disk.process
(default:{exit: false, spawnChild: false}
) - Ifprocess
permitsexit
operations, the evaluated code is permitted to exit the parent process. Ifprocess
permitsspawnChild
operations, the evaluated code is permitted to spawn child processes.
Custom TypeScript version
You can provide a specific version of TypeScript to use as an option to evaluate
. This may come in handy if you're using
multiple TypeScript versions in your project or if you're receiving the TypeScript version to use as an argument from a third party.
const result = evaluate({
// ...
typescript: someTypescriptModule
});
Logging
You can get information about the evaluation process with various levels of logging. By default, nothing is logged, but you can override this behavior:
const result = evaluate({
// ...
logLevel: LogLevelKind.DEBUG
});
Here's an explainer of the different log levels:
LogLevelKind.SILENT
(default) - By default, nothing is logged to the console.LogLevelKind.INFO
- Intermediate results are logged to the console.LogLevelKind.VERBOSE
- Everything that is logged withLogLevelKind.INFO
as well as lexical environment bindings are logged to the consoleLogLevelKind.DEBUG
- Everything that is logged withLogLevelKind.VERBOSE
as well as all visited Nodes during evaluation are logged to the console
Reporting
You can tap into the evaluation process with reporting hooks that will be invoked with useful information while an evaluation is in progress. These are useful if you want to understand more about the execution path and work with it programmatically.
const result = evaluate({
// ...
reporting: {
reportBindings: entry => doSomething(entry),
reportTraversal: entry => someArray.push(entry.node),
reportIntermediateResults: entry => doSomeOtherThing(entry),
reportErrors: entry => doSomethingWithError(entry)
}
});
Here's an explainer of the different reporting hooks:
reportBindings(entry: IBindingReportEntry) => void|(Promise<void>)
- Will be invoked for each time a value is bound to the lexical environment of a Node. This is useful to track mutations throughout code execution, for example to understand when and where variables are declared and/or mutated.reportTraversal(entry: ITraversalReportEntry) => void|(Promise<void>)
- Will be invoked for each time a new Node is visited while evaluating. This is useful to track the path through the AST, for example to compute code coverage.reportIntermediateResults(entry: IIntermediateResultReportEntry) => void|(Promise<void>)
- Will be invoked for each intermediate result that has been evaluated before producing a final result. This allows you to work programmatically with all expression values during code execution.reportErrors(entry: IErrorReportEntry) => void|(Promise<void>)
- Will be invoked for each error that is thrown, both when evaluating a result, and for subsequent invocations on, for example, returned function instances. Holds a reference to the error, as well ast the AST node that threw or caused the Error.
Module overrides
Sometimes, evaluating identifiers require resolving identifiers across source files. When a typechecker is passed in, so long as the identifier is resolvable as part of the compilation unit,
this won't ever be an issue. However, when a type checker is not passed in, or in case you want to override the result of requiring an external module, you can use the moduleOverrides
option.
For example, you may want to pass in as shim for a built-in module. To use it, pass a record where the keys are module specifiers and the value is what requiring that module should resolve to. For example:
{
fs: {
readFileSync: () => {},
// ...
}
}
Contributing
Do you want to contribute? Awesome! Please follow these recommendations.
Maintainers
| | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Frederik WessbergTwitter: @FredWessbergGithub: @wessbergLead Developer |
FAQ
How fast is this?
This is, after all, a virtual machine written on top of another virtual machine (V8), which is built in a dynamically typed high-level language (EcmaScript). This library is not built to be
comparable in performance to raw V8 execution speed. However, since ts-evaluator
doesn't require a compile-step and works directly on an AST, for small operations it will most likely be several magnitudes faster than
both ts-node
and compiling to JavaScript with tsc
and executing directly.
License
MIT © Frederik Wessberg (@FredWessberg) (Website)