@stackline/redeyed

Source-preserving JavaScript token transforms with immutable configuration and pluggable parsers.

Docs and transformer | npm | GitHub | Migration | Security | Changelog

Current package version: 1.0.2

This package is an independent, maintained continuation of redeyed. It preserves the established 2.1.1 callable API and Esprima defaults while removing config mutation, safely handling property-like token names, and supporting current array-returning tokenizers as an opt-in extension.

Install

npm install @stackline/redeyed

Preserve existing require('redeyed') calls with an npm alias:

npm install redeyed@npm:@stackline/redeyed

Quick Start

const redeyed = require('@stackline/redeyed')

const result = redeyed(
  'const answer = 42',
  {
    Keyword: { _default: '<strong>:</strong>' },
    Numeric: { _default: '<mark>:</mark>' }
  }
)

console.log(result.code)
// <strong>const</strong> answer = <mark>42</mark>

A string transform uses before:after. Object and function forms are also supported:

const config = {
  Identifier: {
    answer: { _before: '[', _after: ']' },
    _default: (source, info) => {
      return info.tokenIndex === 0 ? source.toUpperCase() : source
    }
  }
}

The caller's config is never changed. Frozen objects, null-prototype maps, and token names such as hasOwnProperty, __proto__, constructor, and prototype are processed as data.

API

redeyed(code, config[, options])

Returns:

{
  ast,
  tokens,
  comments,
  splits,
  code
}

Options:

| Option | Default | Purpose | | --- | --- | --- | | buildAst | false | Parse and return an AST instead of tokenizer-only operation | | jsx | false | Enable the historical JSX parsing path | | nojoin | false | Return splits without joining transformed code | | parser | Esprima 4 | Supply an Esprima-compatible or array-returning parser | | parserOptions | {} | Pass parser-specific settings |

Function transforms receive (tokenSource, info). info contains the merged token index, tokens and comments, AST when requested, and source. A transform can return a string or:

{
  replacement: 'new source',
  skipPastToken: info.tokens[targetIndex]
}

Modern Syntax

Esprima remains the default to avoid silently changing token labels and ASTs. For modern syntax, opt in to a parser already used by your application:

npm install espree

const espree = require('espree')
const redeyed = require('@stackline/redeyed')

const result = redeyed(
  'class Box { #value = 1_000n }',
  {
    PrivateIdentifier: { _default: '<:>' },
    Numeric: { _default: '[:]' }
  },
  {
    parser: espree,
    parserOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module'
    }
  }
)

Parser-specific token types remain parser-specific. Array tokenizers can expose comments only when their return data includes comments; buildAst: true uses the parser's AST tokens and comments.

Modules And Browser

• Callable CommonJS entry
• Native ESM default and named exports
• First-party TypeScript declarations, including TypeScript 3.9 consumers
• Self-contained browser CJS, ESM, and global bundles
• Original UMD behavior retained in redeyed.js
• Node.js 12 and newer at runtime

The package also exports starter configs:

const config = require('@stackline/redeyed/config')
const es5Config = require('@stackline/redeyed/config-es5')

Package Integrity

The old 2.1.1 npm artifact includes an example that references jQuery 1.8.1. That example is not runtime code, but it triggers dependency scanners. The Stackline artifact ships only runtime entries, configs, types, documentation, licenses, and generated browser bundles. No redeyed runtime CVE is claimed.

The maintained suite includes all 187 upstream assertions, more than 1,000 differential executions, immutable and hostile-key configs, modern parser adapters, hashbang edges, browser/modules/types, package audits, and a direct cardinal adoption check.

The historical dependency key esprima resolves exactly to the maintained @stackline/[email protected] compatibility package. It preserves the Esprima 4.0.1 API while keeping the complete production chain under Stackline release, CI, audit, and provenance controls. A clean install reports no warnings and zero audit findings.

Security

Report vulnerabilities privately as described in SECURITY.md. Please do not publish an unpatched report in a public issue.

Provenance

The source history, decisions, and preserved boundary are recorded in UPSTREAM_AUDIT.md, COMPATIBILITY_CONTRACT.md, and NOTICE. Stackline is not affiliated with or endorsed by the upstream author.

License

MIT. The original copyright and permission notice remain in LICENSE. Browser bundles also retain Esprima's BSD-2-Clause legal terms in THIRD_PARTY_LICENSES.md.