Convert JavaScript values to ESTree expressions

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` to import `estree-util-value-to-estree` in a pure ESM context (e.g., in a Node.js module with `"type": "module"` in `package.json` or a `.mjs` file).
  fix Change your import statement to use ES module syntax: `import { valueToEstree } from 'estree-util-value-to-estree';`

• Error: Unknown value type for serialization.

  cause You are attempting to serialize a value type that is not natively supported by `estree-util-value-to-estree`, and no custom `serialize` option has been provided to handle it.
  fix Implement a `serialize` function in the options object passed to `valueToEstree` to explicitly define how to convert the unsupported value into an ESTree node. For example, `valueToEstree(myCustomValue, { serialize: (value) => value instanceof MyClass ? { type: 'NewExpression', callee: { type: 'Identifier', name: 'MyClass' }, arguments: [] } : undefined })`.

Warnings

• breaking A critical vulnerability (CVE-2025-32014) was identified where converting an object with a `__proto__` property could lead to prototype pollution in the generated ESTree. This allows an attacker to inject arbitrary properties into `Object.prototype`, affecting all objects in the application.
  Fix: Upgrade to version `3.3.3` or newer. This version fixes the `__proto__` property emit to prevent prototype pollution.
• gotcha When working with `Temporal` types (e.g., `Temporal.Instant`, `Temporal.PlainDate`), ensure that the `Temporal` global object is available or polyfilled in the environment where the generated code will run. While the library itself was updated in v3.3.1 to not crash if `Temporal` is undefined, the resulting AST for `Temporal` objects will rely on the `Temporal` global being present.
  Fix: If supporting `Temporal` types, include `@js-temporal/polyfill` or ensure a native `Temporal` implementation is available in your target environment.
• gotcha For unsupported JavaScript values or custom class instances, the default behavior of `valueToEstree` might not produce the desired AST representation. For example, a custom class instance might be serialized as a plain object or might lead to an error if not handled.
  Fix: Utilize the `options.serialize` function to provide custom logic for converting specific types or instances into appropriate ESTree nodes. This gives you full control over how non-standard values are represented.

Install

• npm install estree-util-value-to-estree npm
• yarn add estree-util-value-to-estree yarn
• pnpm add estree-util-value-to-estree pnpm

Imports

• valueToEstree
  wrong:

  const valueToEstree = require('estree-util-value-to-estree')

  correct:

  import { valueToEstree } from 'estree-util-value-to-estree'

  This package is designed for ESM consumption. While CommonJS might work in some transpiled environments, native ESM import is the intended and recommended approach.
• Options

  import type { Options } from 'estree-util-value-to-estree'

  Type import for the configuration options of the valueToEstree function, useful for TypeScript projects.

Quickstart

This quickstart demonstrates converting a complex JavaScript object into an ESTree expression, then generating JavaScript code from that ESTree. It includes an example of using the `serialize` option to handle custom class instances and `Buffer` objects, which are not natively supported as simple literals.

import { valueToEstree } from 'estree-util-value-to-estree';
import { generate } from 'astring'; // Commonly used to convert ESTree to code

const exampleValue = {
  id: 123,
  name: 'Example Item',
  enabled: true,
  price: 99.95,
  details: ['alpha', 'beta', null],
  config: new Map([['key1', 'value1'], ['key2', 42n]]),
  created: new Date('2024-01-01T10:00:00Z'),
  pattern: /test/g,
  complex: {
    nested: Symbol.for('unique-id'),
    buffer: Buffer.from('hello'),
    // Unsupported types will require a custom serializer
    customClass: new class MyCustom { constructor() { this.prop = 'value'; } }()
  }
};

// Convert a standard JavaScript value to an ESTree expression
const estreeExpression = valueToEstree(exampleValue);
console.log('Generated ESTree (partial):', estreeExpression.type);
console.log('Generated Code for standard value:\n', generate(estreeExpression));

// Example with a custom serializer for the custom class
const estreeWithCustom = valueToEstree(exampleValue, {
  serialize(value) {
    if (value instanceof Buffer) {
      // Convert Buffer to a Buffer.from() call
      return {
        type: 'CallExpression',
        callee: { type: 'MemberExpression', object: { type: 'Identifier', name: 'Buffer' }, property: { type: 'Identifier', name: 'from' }, computed: false, optional: false },
        arguments: [{ type: 'Literal', value: value.toString('hex') }, { type: 'Literal', value: 'hex' }]
      };
    }
    if (value && typeof value === 'object' && value.constructor.name === 'MyCustom') {
      // Convert MyCustom instance to a new MyCustom() expression
      return {
        type: 'NewExpression',
        callee: { type: 'Identifier', name: 'MyCustom' },
        arguments: []
      };
    }
    // Let the default logic handle other types
    return undefined;
  }
});
console.log('\nGenerated Code with custom serializer:\n', generate(estreeWithCustom));