Skip to content

Release Notes - RFC 4180 Compliance Update

Choose a tag to compare

View all tags
@iuccio iuccio released this 19 Mar 15:15
· 203 commits to master since this release
v4.0.0
4d36951

Release Notes - RFC 4180 Compliance Update

Version 4.0. - RFC 4180 Compliance

Overview

This release makes csvToJson fully compliant with RFC 4180, the standard format specification for CSV files. This is a significant update that improves standards compliance, reliability, and compatibility with CSV data from various sources.

RFC 4180 (Common Format and MIME Type for Comma-Separated Values (CSV) Files) is the official standard specification for CSV file formatting, maintained by the Internet Engineering Task Force (IETF).

🚀 Key Features

1. RFC 4180 Compliant CSV Parsing

  • Full support for RFC 4180 standard CSV format
  • Proper handling of quoted fields with embedded delimiters
  • Support for multi-line fields (fields containing newlines)
  • Correct quote escaping using double quotes ("")

2. Default Comma Delimiter (Breaking Change)

  • NEW: Comma (,) is now the default field delimiter (RFC 4180 standard)
  • BREAKING: Previous default was semicolon (;)
  • Allows parsing standard CSV files without explicit configuration
  • Maintains backward compatibility through explicit fieldDelimiter() calls

3. Improved Quoted Field Handling

  • Properly handles fields wrapped in quotes
  • Correctly processes escaped quotes within quoted fields
  • Supports empty quoted fields ("")
  • Handles fields containing delimiters, newlines, and special characters

4. Line Ending Support

  • Support for CRLF (\r\n) - Windows standard
  • Support for LF (\n) - Unix/Linux standard
  • Support for CR (\r) - older Mac standard
  • Automatic detection and handling

5. Code Quality Improvements

  • Refactored for better readability and maintainability
  • Added comprehensive JSDoc comments
  • Extracted complex logic into focused helper methods
  • Removed deprecated substr() method (replaced with slice())
  • Added braces to all conditional statements
  • Removed deprecated jsonToCsv() function

6. Comprehensive Test Coverage

  • 12 new RFC 4180 compliance tests
  • 12 new comma-delimiter tests
  • 109 total tests (up from 94)
  • Edge case handling verification

⚠️ Breaking Changes

1. Default Delimiter Changed to Comma

BEFORE:

const csvToJson = require('convert-csv-to-json');
// Default delimiter was semicolon (;)
let result = csvToJson.getJsonFromCsv('data.csv');

AFTER (RFC 4180 standard):

const csvToJson = require('convert-csv-to-json');
// Default delimiter is now comma (,)
let result = csvToJson.getJsonFromCsv('data.csv');
// File should be comma-delimited

Migration: If your CSV files use semicolons or other delimiters, explicitly set the delimiter:

csvToJson.fieldDelimiter(';').getJsonFromCsv('data.csv');

2. Removed Deprecated Function

The jsonToCsv() function has been removed. This was a deprecated alias.

BEFORE:

csvToJson.jsonToCsv('input.csv', 'output.json');

AFTER:

csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');

3. Stricter Quoted Field Parsing

RFC 4180 compliant quote handling may parse some edge cases differently:

Example - Proper Quote Escaping:

// Input CSV: "name","description"
//            "John","He said ""Hello""" 
// Note: Double quotes "" represent a single quote

// Before: Might include literal quote characters
// After (RFC 4180): Correctly unescapes to: He said "Hello"

📋 Migration Guide

Quick Start for Existing Users

No changes needed if you:

  • Already explicitly set field delimiters with .fieldDelimiter()
  • Use quoted field support with .supportQuotedField(true)

Action required if you:

  • Rely on semicolon (;) as default delimiter
  • Use the removed jsonToCsv() function
  • Parse CSV files with quoted fields containing special characters

Step-by-Step Migration

Step 1: Update Delimiter Usage

If your files use a special delimiter, add explicit configuration:

// For semicolon-delimited files
csvToJson.fieldDelimiter(';').getJsonFromCsv('data.csv');

// For tab-delimited files
csvToJson.fieldDelimiter('\t').getJsonFromCsv('data.csv');

// For pipe-delimited files
csvToJson.fieldDelimiter('|').getJsonFromCsv('data.csv');

Step 2: Replace Deprecated Functions

Replace any usage of jsonToCsv():

// Old code
csvToJson.jsonToCsv('input.csv', 'output.json');

// New code
csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');

Step 3: Test with RFC 4180 CSV Files

Test parsing standard CSV files without explicit delimiter:

// This now works with standard CSV files (comma-delimited)
let result = csvToJson.getJsonFromCsv('standard.csv');

📊 Feature Comparison

Feature Before After
Default Delimiter ; (semicolon) , (comma) - RFC 4180
Quoted Fields Partial support Full RFC 4180 support
Multi-line Fields Not supported Fully supported
Empty Quoted Fields Issues Correctly handled
Quote Escaping Partial RFC 4180 compliant ("")
Line Endings Limited CRLF, LF, CR all supported
Code Quality Basic Refactored & maintainable

🧪 Testing

All changes have been validated with comprehensive test coverage:

  • 109+ tests across 13 test suites
  • RFC 4180 compliance tests - 15 tests
  • Comma delimiter tests - 12 tests
  • Backward compatibility tests - All existing tests pass

Run tests:

npm test              # All tests with coverage
npm test -- --no-coverage    # Quick test run
npm test test/rfc4180.spec.js            # RFC 4180 tests only
npm test test/comma-delimiter.spec.js    # Comma delimiter tests

📚 Documentation

New Resources

  • Comprehensive RFC 4180 Migration Guide - See RFC4180_MIGRATION_GUIDE.md
  • RFC 4180 Compliance Tests - See test/rfc4180.spec.js
  • Comma Delimiter Tests - See test/comma-delimiter.spec.js

RFC 4180 Standard

  • Official RFC 4180 specification: https://tools.ietf.org/html/rfc4180
  • Key points:
    • Comma is the field delimiter
    • Quoted fields with embedded delimiters/newlines
    • Double quotes escape quotes within fields
    • CRLF line endings recommended

🔄 Backward Compatibility

Partially Compatible - Most applications will work without changes if they:

  • Already use .fieldDelimiter() explicitly
  • Use .supportQuotedField(true) for quoted fields
  • Don't rely on the removed jsonToCsv() function

Requires Updates if you:

  • Rely on semicolon as default delimiter
  • Parse semicolon-delimited CSV files without explicit configuration

💡 Examples

Example 1: Parse Standard CSV File (Default Comma)

const csvToJson = require('convert-csv-to-json');

// CSV file: name,age,city
//            John,30,NYC
//            Jane,25,LA

let result = csvToJson.getJsonFromCsv('data.csv');
// [{ name: 'John', age: '30', city: 'NYC' },
//  { name: 'Jane', age: '25', city: 'LA' }]

Example 2: Parse CSV String with Quoted Fields

let csv = 'name,email,status\n' +
          '"Smith, John","john@example.com","Active"\n' +
          '"Doe, Jane","jane@example.com","Inactive"\n';

let result = csvToJson.supportQuotedField(true).csvStringToJson(csv);
// [{ name: 'Smith, John', email: 'john@example.com', status: 'Active' },
//  { name: 'Doe, Jane', email: 'jane@example.com', status: 'Inactive' }]

Example 3: Parse Multi-line Fields

let csv = 'id,description\n' +
          '1,"This is a\nmulti-line\ndescription"\n' +
          '2,"Single line"\n';

let result = csvToJson.supportQuotedField(true).csvStringToJson(csv);
// [{ id: '1', description: 'This is a\nmulti-line\ndescription' },
//  { id: '2', description: 'Single line' }]

Example 4: Migrate from Semicolon-Delimited

// For backward compatibility with semicolon-delimited files
let result = csvToJson.fieldDelimiter(';').getJsonFromCsv('data.csv');

🐛 Bug Fixes

  • Fixed handling of empty quoted fields ("")
  • Fixed multi-line field parsing within quoted regions
  • Fixed quote escaping detection (RFC 4180 compliant)
  • Fixed line ending detection (CRLF, LF, CR)
  • Removed deprecated substr() usage

✨ Internal Improvements

  • Refactored parseRecords() method - Clearer line-ending detection with getLineEndingLength() helper
  • Refactored split() method - Extracted quote handling into isEscapedQuote() and isEmptyQuotedField() helpers
  • Named constants - QUOTE_CHAR, CRLF, LF, CR for clarity
  • JSDoc comments - Comprehensive documentation for all complex methods
  • Code consistency - All if statements now have braces

📦 Installation

npm install convert-csv-to-json@latest

Or update existing installation:

npm update convert-csv-to-json

🤝 Support

For issues, questions, or migration assistance:

📝 Changelog

v4.0.0 (2026-03-19)

  • ✨ RFC 4180 compliance achieved
  • 🔄 Default delimiter changed to comma
  • 🧹 Code refactored for maintainability
  • ✅ 109+ comprehensive tests
  • 📚 Full documentation updates
  • ⚠️ Removed deprecated jsonToCsv() function

Thank you for using csvToJson! We believe this RFC 4180 update makes the library more standards-compliant and reliable for real-world CSV parsing needs.

Assets 2
Loading