ts-evaluator is an advanced interpreter for TypeScript that enables the evaluation of arbitrary AST (Abstract Syntax Tree) Nodes, specifically Expressions, ExpressionStatements, or Declarations, within a given TypeScript AST. Unlike tools such as `ts-node` that execute full TypeScript programs, this library focuses on partial evaluation based on a node's lexical environment. The current stable version is 2.0.0. Release cadence appears to be driven by significant TypeScript and JSDOM version updates, typically with several minor and patch releases in between. Its key differentiators include the ability to evaluate specific nodes, support for browser, Node.js, and pure ECMAScript environments, and configurable policy options for sandboxing and restricting operations like I/O or network access. This makes it a valuable tool for linters, language services, partial evaluators, and frameworks requiring deep AST introspection and computation.
npm install ts-evaluatorVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to parse a TypeScript code string into an AST, locate a specific node (a binary expression in this case), and then use `ts-evaluator` to evaluate that node within a configured context, including a TypeChecker and policy restrictions.
Upgrade your Node.js runtime to version 18.20.0 or higher. For example, using nvm: `nvm install 18.20.0 && nvm use 18.20.0`.
Prefer `import ... from 'ts-evaluator'` over `require()` statements. For CommonJS projects, ensure proper interoperability or consider migrating to ESM if possible. If using TypeScript, ensure your `tsconfig.json` has `"module": "Node16"` or `"module": "ESNext"` and `"moduleResolution": "Bundler"` or `"Node16"`.
Manually install `typescript` and `jsdom` in your project with versions compatible with `ts-evaluator`'s peer dependency range (e.g., `npm install typescript@5 jsdom@22`). Check the `package.json` for specific ranges.
Always provide a `typeChecker` created from a TypeScript program when initializing the evaluation context, especially for code involving type-dependent operations, interfaces, or generics. `createEvaluationContext({ typeChecker: program.getTypeChecker() })`.Identify the specific `ts.Node` (Expression, ExpressionStatement, or Declaration) you intend to evaluate. If you need to execute full programs, consider tools like `ts-node`.
Provide `ModuleOverrides` in `createEvaluationContext` to map module specifiers to their resolved values or mock implementations. Example: `createEvaluationContext({ moduleOverrides: new Map([['my-module', { foo: 123 }]]) })`.Ensure the `ts.Node` passed to `evaluate()` is a valid and existing node from the parsed `SourceFile`. Add null/undefined checks before calling `evaluate`.
Ensure your project is configured for ES Modules (`"type": "module"` in `package.json`, `.mjs` files), or that your bundler correctly handles ESM to CJS transpilation. Prefer `import` syntax.
Update your Node.js environment to the version specified in the `engines` field of the `ts-evaluator` package. Use `nvm` or your preferred Node.js version manager.