Alexandro.Net

Download README · GitHub release

@stackline/redeyed

Source-preserving JavaScript token transforms with immutable configs and parser adapters.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 1.0.5

Why this package?

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

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.

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.

Compatibility

Item Value
Package @stackline/redeyed@1.0.5
Node.js runtime >=12
CommonJS / primary entry ./redeyed.js
ES module entry ./index.mjs
Type declarations ./index.d.ts

Installation

Install

npm install @stackline/redeyed

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

npm install redeyed@npm:@stackline/redeyed

Usage

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.

Features and Integrations

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

The package also exports starter configs:

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

Security

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

API Surface

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]
}

Local Development

git clone https://github.com/alexandroit/stackline-redeyed.git
cd stackline-redeyed
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

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/esprima@1.0.0 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.

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

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.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.