chainsafe 🔗

A CLI tool to automatically add optional chaining to TypeScript and JavaScript files.

Installation

npm install -g chainsafe

Usage

chainsafe <path> [options]

Options

chainsafe --help

Options:
  --type ts|js          Process only TypeScript or JavaScript files
  --skip <names>        Add names to built-in globals to be skipped
  --no-skip <names>     Remove names from built-in globals skip list
  --skip-list           Print current built-in globals list
  --preview             Preview changes without writing to files
  --skip-none           Ignore built-in globals and apply optional chaining to everything
  --skip-only <names>   Only skip the specified names, ignore built-in globals
  --apply-only <names>  Only apply optional chaining to specified modules/variables
  --help                Show help information

Features

✨ Automatic optional chaining transformation
🔄 Supports both TypeScript and JavaScript files
🎯 Smart detection of potentially nullable expressions
🛡️ Preserves existing optional chaining
⚡ Fast and efficient processing
🔒 Safe transformation with built-in globals protection
📝 Preview mode for safe checking
📁 Process single files or entire directories
🚫 Skip specific globals as needed
🎯 Selective application to specific modules
🌐 Global application with skip-none mode
🔍 Fine-grained control over transformations
🔁 Multiple pass transformations for nested chains
📊 Detailed statistics and error reporting
🛠️ Advanced configuration options

Examples

Process all files in a directory

chainsafe src/

Process only TypeScript files

chainsafe src/ --type ts

Process only JavaScript files

chainsafe src/ --type js

Skip certain globals

chainsafe src/ --skip axios,lodash

Remove items from built-in globals list

chainsafe src/ --no-skip Array,Object

Preview changes without writing

chainsafe src/ --preview

View current skip list

chainsafe src/ --skip-list

Apply optional chaining to everything

chainsafe src/ --skip-none

Only skip specific modules

chainsafe src/ --skip-only axios,lodash

Only apply to specific modules

chainsafe src/ --apply-only axios,process

Multiple Pass Transformations

The tool performs multiple passes (default: 5) to handle deeply nested chains:

Before:

const data = service.getData().process().validate();
const nested = obj.deeply.nested.property.access;
const mixed = api.get().data.process().validate().result;

After:

const data = service?.getData()?.process()?.validate();
const nested = obj?.deeply?.nested?.property?.access;
const mixed = api?.get()?.data?.process()?.validate()?.result;

Built-in Globals

The following globals are protected by default and won't receive optional chaining:

Array
Object
String
Number
Boolean
Date
Math
JSON
RegExp
Error
Map
Set
Promise
Function
console
Buffer
process

You can:

Add to this list using --skip
Remove from this list using --no-skip
Replace entirely using --skip-only
Ignore this list using --skip-none
Target specific modules using --apply-only

Technical Details

Parser Features

Uses @babel/parser for accurate TypeScript/JavaScript parsing
Intelligent AST (Abstract Syntax Tree) analysis
Preserves source code formatting
Handles complex nested expressions
Supports .ts, .tsx, .js, and .jsx files

Configuration

Maximum file size limit (default: 10MB)
Configurable ignored directories
Customizable file extensions
Binary file detection and skipping
Multiple pass iterations for nested chains

TypeScript Support

Enhanced enum handling
Improved type reference detection
Optimized plugin configuration
Support for TypeScript-specific constructs
Proper handling of type assertions

Error Handling

The tool provides:

Detailed error context (phase, expression, location)
Clear parsing error messages
File processing statistics
Warning detection and reporting
Safe file transformation
Validation of skip/apply options
Original file preservation on failure

Statistics and Reporting

Each run provides:

Number of files processed
Number of files modified
Errors encountered
Warnings detected
Processing time
Transformation details

Advanced Usage

Targeted Transformations

# Transform specific modules with preview
chainsafe src/ --apply-only axios,lodash --preview

# Exclude specific modules
chainsafe src/ --skip-only axios,fetch

# Transform everything
chainsafe src/ --skip-none

Option Combinations

# Preview TypeScript transformations
chainsafe src/ --type ts --preview

# Target specific modules in TypeScript
chainsafe src/ --type ts --apply-only axios

Best Practices

Always use --preview first for safety
Back up important files before processing
Check --skip-list before modifications
Process directories individually
Use --apply-only for targeted changes
Test with sample files first
Review statistics after processing
Check warnings and error messages

Release Notes

Version 1.0.4 🚀 (January 20, 2025)

New Features 🎉

Multiple Pass Transformations
- Support for deeply nested chains
- Configurable iteration count
- Improved nested property handling
Enhanced Configuration
- File size limits
- Directory exclusions
- Binary file handling
- Customizable extensions
Improved Error Handling
- Detailed error context
- Better error messages
- Warning detection
- Statistics tracking
TypeScript Improvements
- Better enum handling
- Enhanced type support
- Optimized plugins

Improvements 🔨

Optimized AST traversal
Better skip logic
Improved performance
Enhanced error reporting
Better TypeScript support
Clearer documentation

Breaking Changes ⚠️

None. All new features are backward compatible.

Known Issues 🚧

Complex computed properties might need review
Some edge cases in TypeScript type assertions
Very large files might need multiple runs

Installation & Upgrade

# New installation
npm install -g chainsafe

# Upgrade existing installation
npm update -g chainsafe

Contributing

Please submit issues and pull requests on GitHub at https://github.com/dasariumamahesh/chainsafe.

License

Author

Dasari Uma Mahesh (Mahesh)

dasariumamahesh/chainsafe