Registry / serialization / subscript

subscript

JSON →
library1.15.2jsnpmunverified

Subscript is a modular and extensible expression parser and evaluator for JavaScript and TypeScript. It provides a lightweight core for building custom Domain Specific Languages (DSLs) and offers several ready-to-use presets, including `subscript` (common expressions), `justin` (JSON, templates, arrow functions, optional chaining), and `jessie` (a JavaScript subset supporting statements, functions, and control flow). The package is currently at version 10.3.2 and maintains an active release cadence with frequent minor and major updates introducing new syntax features, performance improvements, and API refinements. Key differentiators include its small bundle size (~2KB core), high performance for both parsing and evaluation, a minimal JSON-compatible Abstract Syntax Tree (AST), and built-in sandboxing to prevent prototype pollution and global access. It is designed to be universal, fast, and safe, making it suitable for templates, calculators, safe evaluation environments, and language subsets.

npm install subscript
INSTALL
IMPORT
SIG · SUBSCRIPT
S
subscript
serializationjavascriptv1.15.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

subscript
import subscript from 'subscript'
const subscript = require('subscript')
The main `subscript` preset is the default export. All versions >=10.0.0 are ESM-only.
justin
import justin from 'subscript/justin.js'
import { justin } from 'subscript'
The `justin` preset is a named export from a specific module path, requiring the `.js` extension in ESM environments.
parse
import { parse } from 'subscript'
import { parse } from 'subscript/parse'
The `parse` function, along with `compile`, `binary`, `operator`, etc., are named exports from the main package entry point.
codegen
import { codegen } from 'subscript/util/stringify.js'
import { stringify } from 'subscript/util/stringify.js'
The AST codegeneration utility is `codegen`, not `stringify`, and is located in a specific utility path.

Demonstrates parsing and evaluating a Jessie preset expression with functions and control flow, showcasing sandboxed execution and context passing.

import jessie from 'subscript/jessie.js' // Jessie is a JavaScript subset supporting statements, functions, and control flow. // It's ideal for safely evaluating user-defined logic or custom DSLs. let expression = ` function calculateFactorial(n) { if (n <= 1) return 1; return n * calculateFactorial(n - 1); } let result = calculateFactorial(process.env.FACTORIAL_NUMBER ? parseInt(process.env.FACTORIAL_NUMBER) : 5); result; `; // Compile the expression into an executable function. // The function takes a context object for variables and methods. let compiledFn = jessie(expression); // Execute the compiled function with a context. // Here, we're demonstrating a simple `process.env` access for dynamic input. // If process.env.FACTORIAL_NUMBER is '7', it will calculate factorial of 7. const context = {}; // Jessie expressions have no access to global scope by default. const result = compiledFn(context); console.log(`The factorial result is: ${result}`); // Expected output if FACTORIAL_NUMBER is 5: The factorial result is: 120
Debug
Known issues
breakingSubscript versions 10.0.0 and above are ESM-only. Direct `require()` calls for the main package or its presets will result in an `ERR_REQUIRE_ESM` error. Ensure your project uses ES modules or a build step for compatibility.
fix
Migrate your import statements from `const pkg = require('pkg')` to `import pkg from 'pkg'` or `import { named } from 'pkg'`. If using Node.js, ensure your package.json specifies `"type": "module"` or use `.mjs` file extensions.
affects: >=10.0.0
breakingThe Abstract Syntax Tree (AST) structure has undergone significant changes across major versions (e.g., v6.0.0 removed Lisp tree, v7.0.0 reintroduced it, v9.0.0 refined groupings, v10.0.0 added template tags and new node types). If you have custom parsers, compilers, or AST transformers, they will likely break when upgrading between major versions.
fix
Consult the `spec.md` and release changelogs for the specific version you are targeting to understand the new AST format. Update your custom logic to align with the revised node kinds and structures.
affects: >=6.0.0
breakingThe API for registering operators and literals (`set`, `parse.unary`, `parse.binary`, `parse.nary`) has evolved. For example, v6.0.0 simplified `set`, v7.1.1 added explicit `parse.unary`/`binary`/`nary` methods, and v8.0.0 changed primitive wrapping. Custom extensions may require significant refactoring.
fix
Refer to the `docs.md` for the current API on extending Subscript. Use the explicit `binary('op', precedence)` and `operator('op', (a,b)=>...)` methods for registering new syntax and their compilation logic, as shown in the README example.
affects: >=6.0.0
breakingVersion 10.1.0 changed the JSON serialization format for regex literals (from `[, new RegExp('abc', 'gi')]` to `['//', 'abc', 'gi']`) and `undefined` values (from `[, undefined]` to `[]`). This impacts any applications that rely on round-tripping the AST through JSON serialization.
fix
If you serialize/deserialize Subscript ASTs, update your deserialization logic to account for the new regex and `undefined` formats. This is primarily a concern for storage or network transfer of ASTs.
affects: >=10.1.0
gotchaSubscript is designed for safety and explicitly blocks access to sensitive global objects and prototype chain manipulation by default (e.g., `__proto__`, `constructor`, `prototype`). Attempting to use these will result in `undefined` or a blocked operation.
fix
Do not attempt to access or manipulate global objects or the prototype chain within Subscript expressions. Design your expressions and provided context (`ctx` object) to contain only necessary and safe data/functions.
affects: >=5.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/subscript/index.js not supported.
Attempting to import `subscript` using CommonJS `require()` syntax in a project that's configured for ES modules or for a Subscript version that is ESM-only.
fix
Change `const subscript = require('subscript')` to `import subscript from 'subscript'`. Ensure your Node.js environment or build setup correctly handles ES modules (e.g., `"type": "module"` in `package.json`).
SyntaxError: Unknown operator '<operator>'
The expression contains an operator or syntax feature not recognized by the default `subscript` preset or the chosen preset (e.g., `justin`, `jessie`).
fix
If the feature is standard JavaScript, try using the `justin` or `jessie` presets. If it's a custom or domain-specific operator, you'll need to extend the parser using `binary`, `unary`, or `nary` registration methods.
TypeError: Cannot read properties of undefined (reading '__proto__')
An expression is attempting to access a forbidden property like `__proto__`, `constructor`, or `prototype`, which are blocked by Subscript's sandboxing for security.
fix
Modify the expression to avoid accessing these properties. The sandbox is intentional. Ensure your expression logic operates strictly within the provided context and its safe members.
The structure of the generated AST from parse() is different than expected.
You have upgraded Subscript across major versions, and the internal representation of the Abstract Syntax Tree (AST) has changed.
fix
Consult the `spec.md` file in the `subscript` repository for the specific version you are using to understand the current AST structure. Update any custom AST traversal, transformation, or compilation logic accordingly.
Upgrade
Version history
1.15.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Resources