llms.txt

# jsesc-es

## Project Overview

A modern TypeScript + ESM refactor of the popular jsesc library with 100% API compatibility. This library provides JavaScript string escaping functionality that generates ASCII-safe output for any input data.

## Key Information

- **Name**: jsesc-es
- **Version**: See package.json for current version
- **License**: MIT
- **Author**: Drswith
- **Repository**: https://github.com/Drswith/jsesc-es
- **Package Manager**: pnpm@9.15.9
- **Node Version**: >=6

## Description

Given some data, jsesc-es returns the shortest possible stringified & ASCII-safe representation of that data. It's similar to JSON.stringify() but with enhanced capabilities:

1. Outputs JavaScript instead of JSON by default
2. Supports ES6 data structures (Maps, Sets)
3. Offers extensive customization options
4. Generates ASCII-safe output using escape sequences
5. Full TypeScript support with comprehensive type definitions
6. Native ES Modules with tree-shaking support
7. Modern development toolchain and improved performance

## Main Features

### TypeScript First
- Built-in type definitions (no @types/jsesc needed)
- Full type safety with JsescOptions interface
- Better IDE support with IntelliSense
- Type-safe option validation at compile time

### Modern Module System
- Native ES Modules with tree-shaking
- Multiple import styles (default, named, mixed)
- CommonJS compatibility for legacy projects
- Optimized bundle size

### Enhanced Performance
- Improved function handling with better type detection
- Optimized escape logic for common use cases
- Modern JavaScript features for better performance
- Reduced bundle overhead

## API

### Main Function
```typescript
jsesc(value: unknown, options?: JsescOptions): string
```

### Options Interface
```typescript
interface JsescOptions {
  escapeEverything?: boolean    // Escape all characters
  minimal?: boolean            // Minimal escaping (default: true)
  isScriptContext?: boolean    // Script context escaping
  quotes?: 'single' | 'double' | 'backtick'  // Quote style
  wrap?: boolean              // Wrap in quotes
  es6?: boolean               // ES6 features support
  json?: boolean              // JSON-compatible output
  compact?: boolean           // Compact output
  lowercaseHex?: boolean      // Lowercase hex escapes
  numbers?: 'decimal' | 'binary' | 'octal' | 'hexadecimal'  // Number format
  indent?: string             // Indentation string
  indentLevel?: number        // Indentation level
}
```

## Usage Examples

### Basic Usage
```typescript
import jsesc from 'jsesc-es'

// Default export
jsesc('foo bar')  // 'foo bar'
jsesc('foo\tbar') // 'foo\\tbar'

// With options
jsesc('foo bar', { quotes: 'double' })  // "foo bar"
jsesc([1, 2, 3], { compact: false })    // [\n\t1,\n\t2,\n\t3\n]
```

### ES6 Features
```typescript
// Maps and Sets
jsesc(new Map([['a', 1], ['b', 2]]))  // new Map([['a', 1], ['b', 2]])
jsesc(new Set([1, 2, 3]))             // new Set([1, 2, 3])
```

## File Structure

```
src/
├── index.ts      # Main entry point with exports
├── jsesc-es.ts   # Core implementation (363 lines)
├── types.ts      # TypeScript type definitions
└── version.ts    # Version information

tests/
├── advanced.test.ts  # Advanced functionality tests
├── common.test.ts    # Common usage tests
└── index.html        # Browser test page

.github/
├── workflows/
│   ├── ci.yml        # Continuous integration
│   └── release.yml   # Release automation
└── FUNDING.yml       # GitHub funding

Configuration files:
├── package.json      # Package configuration
├── tsconfig.json     # TypeScript configuration
├── tsdown.config.ts  # Build tool configuration
├── vitest.config.ts  # Test configuration
├── eslint.config.js  # ESLint configuration
└── .nvmrc           # Node version specification
```

## Keywords

buffer, escape, javascript, json, map, set, string, stringify, tool

## Build and Development

- **Build**: `pnpm build` (uses tsdown)
- **Development**: `pnpm dev` (watch mode with sourcemap)
- **Testing**: Uses Vitest for testing
- **Linting**: ESLint with modern configuration

## Export Formats

- **ES Modules**: `./dist/index.js`
- **CommonJS**: `./dist/index.cjs`
- **TypeScript**: `./dist/index.d.ts`

## Core Implementation Details

The main jsesc function (in jsesc-es.ts) handles:
- String escaping with various options
- Support for different data types (strings, numbers, objects, arrays, Maps, Sets, etc.)
- ASCII-safe output generation
- Customizable escape sequences
- Indentation and formatting options
- TypeScript type checking and validation

## Use Cases

1. **Avoiding mojibake and encoding issues**
2. **Safe JSON-like output for JavaScript parsers**
3. **Handling Unicode characters safely**
4. **Generating ASCII-safe representations**
5. **ES6 data structure serialization**
6. **TypeScript projects requiring type safety**

## Compatibility

- **Node.js**: >=6
- **Browsers**: Modern browsers with ES Module support
- **TypeScript**: Full support with built-in types
- **Build tools**: Webpack, Vite, Rollup (tree-shaking compatible)

## Related

- Original jsesc library by Mathias Bynens
- JSON.stringify() (JavaScript built-in)
- Online demo: https://mothereff.in/js-escapes