Constantinople Constant Expression Evaluator

Common errors

• Expression is not constant

  cause You attempted to call `isConstant.toConstant()` on an expression that the library determined was not constant.
  fix Ensure `isConstant()` returns `true` for an expression before calling `isConstant.toConstant()`, or wrap `isConstant.toConstant()` calls in a `try...catch` block to handle this expected error.

• SyntaxError: Unexpected token ...

  cause The input string provided to `isConstant` or `isConstant.toConstant` contained a JavaScript syntax error, preventing successful parsing.
  fix Review and correct the syntax of the input expression string. `isConstant()` will return `false` for syntax errors, while `isConstant.toConstant()` will throw a `SyntaxError`.

• TypeError: isConstant_1.toConstant is not a function

  cause You attempted to import `isConstant` as a named export (`{ isConstant }`) or `toConstant` as a top-level named export. However, `isConstant` is the default export and `toConstant` is a property of that default export.
  fix Import `isConstant` as a default export (`import isConstant from 'constantinople';`) and access `toConstant` as a property of the imported object (`isConstant.toConstant`). For CommonJS, use `const isConstant = require('constantinople');`.

Warnings

• gotcha Providing volatile objects like `Math` or `Date` to the optional `constants` parameter can lead to incorrect `isConstant` evaluations or unexpected `toConstant` results if methods like `Math.random()` or `Date.now()` are present in the expression. The library aims to safely *underestimate* constancy, but user-provided contexts can unintentionally override this safety.
  Fix: Carefully curate the `constants` object, ensuring it only contains truly static values or functions without side effects. Avoid passing global objects that include non-constant methods if the expression might call them.
• gotcha The `toConstant` function will throw an error if the provided expression is determined not to be constant. This behavior is by design, ensuring that only truly constant expressions are evaluated to a direct value.
  Fix: Always wrap calls to `isConstant.toConstant()` in a `try...catch` block, or, preferably, ensure you call `isConstant()` first and only invoke `toConstant()` if `isConstant()` returns `true`.
• gotcha The `isConstant` function returns `false` for expressions with syntax errors rather than throwing an exception. While safe, this means a `false` return could indicate either a non-constant expression or a malformed one. `toConstant` *will* throw on syntax errors when attempting to parse and evaluate.
  Fix: If differentiating between non-constant and syntax errors is crucial, consider pre-validating syntax with a linter or a dedicated parser, or rely on `toConstant`'s error throwing behavior for invalid syntax when precise error types are needed.

Install

• npm install constantinople npm
• yarn add constantinople yarn
• pnpm add constantinople pnpm

Imports

• isConstant
  wrong:

  import { isConstant } from 'constantinople';

  correct:

  import isConstant from 'constantinople';

  The primary function `isConstant` is the default export of the package for ESM usage.
• isConstant (CJS)
  wrong:

  const { isConstant } = require('constantinople');

  correct:

  const isConstant = require('constantinople');

  For CommonJS environments, `isConstant` is the default export, meaning the entire module exports the function directly.
• toConstant
  wrong:

  import { toConstant } from 'constantinople';

  correct:

  import isConstant from 'constantinople';
  const result = isConstant.toConstant('some_expression');

  `toConstant` is a named property of the default `isConstant` export, not a top-level named export. Access it via the default imported `isConstant` object.

Quickstart

This quickstart demonstrates how to use `isConstant` to check if an expression is constant and `toConstant` to evaluate its value, including handling non-constant expressions and custom constant contexts.

import isConstant from 'constantinople';

const expression1 = '"foo" + 5';
const expression2 = 'Math.floor(10.5)';
const expression3 = 'Date.now()'; // Example of a non-constant

// Check and evaluate a simple constant string concatenation
if (isConstant(expression1)) {
  console.log(`'${expression1}' is constant.`);
  try {
    const result = isConstant.toConstant(expression1);
    console.log(`Value: ${result}`); // Expected: "foo5"
  } catch (error: any) {
    console.error(`Error evaluating '${expression1}':`, error.message);
  }
} else {
  console.log(`'${expression1}' is not constant.`);
}

console.log('---\n');

// Check and evaluate with provided constants (e.g., Math object)
// WARNING: Providing global objects like Math might lead to unexpected behavior if they contain non-constant functions like Math.random
if (isConstant(expression2, { Math: Math })) {
  console.log(`'${expression2}' is constant with Math context.`);
  try {
    const result = isConstant.toConstant(expression2, { Math: Math });
    console.log(`Value: ${result}`); // Expected: 10
  } catch (error: any) {
    console.error(`Error evaluating '${expression2}':`, error.message);
  }
} else {
  console.log(`'${expression2}' is not constant with Math context.`);
}

console.log('---\n');

// Demonstrate a non-constant expression
if (isConstant(expression3)) {
  console.log(`'${expression3}' is constant.`);
} else {
  console.log(`'${expression3}' is not constant.`);
  try {
    isConstant.toConstant(expression3); // This will throw an error
  } catch (error: any) {
    console.error(`Attempting to evaluate non-constant '${expression3}' throws: ${error.message}`);
  }
}