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

1. Always use --preview first for safety
2. Back up important files before processing
3. Check --skip-list before modifications
4. Process directories individually
5. Use --apply-only for targeted changes
6. Test with sample files first
7. Review statistics after processing
8. Check warnings and error messages

Release Notes

Version 1.0.4 🚀 (January 20, 2025)

New Features 🎉

1. Multiple Pass Transformations

   • Support for deeply nested chains
   • Configurable iteration count
   • Improved nested property handling

2. Enhanced Configuration

   • File size limits
   • Directory exclusions
   • Binary file handling
   • Customizable extensions

3. Improved Error Handling

   • Detailed error context
   • Better error messages
   • Warning detection
   • Statistics tracking

4. 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

MIT © [Dasari Uma Mahesh (Mahesh)]

Author

Dasari Uma Mahesh (Mahesh)

Links

• GitHub Repository
• NPM Package
• Issue Tracker