@bernierllc/csv-mapper

Intelligent column mapping functionality for CSV data with field variations, auto-mapping, and type conversion.

Features

- Column Mapping: Map CSV columns to structured field names
- Field Variations: Handle multiple possible column names for the same field
- Auto-Mapping: Intelligent column name matching and suggestions
- Type Conversion: Convert string data to appropriate types
- Mapping Validation: Validate mapping configurations
- Bulk Operations: Process entire datasets with mapping rules

Installation

``bash
npm install @bernierllc/csv-mapper
`

Quick Start

$3

`typescript
import { CSVMapper, FieldType } from '@bernierllc/csv-mapper';

const mapper = new CSVMapper();

const mapping = {
'email_address': { targetField: 'email', type: FieldType.EMAIL },
'first_name': { targetField: 'firstName', type: FieldType.STRING },
'last_name': { targetField: 'lastName', type: FieldType.STRING },
'phone': { targetField: 'phone', type: FieldType.PHONE },
'dob': { targetField: 'dateOfBirth', type: FieldType.DATE }
};

const csvRow = ['john@example.com', 'John', 'Doe', '555-1234', '1990-01-01'];
const mappedRow = mapper.mapRow(csvRow, mapping);

// Result: {
// email: 'john@example.com',
// firstName: 'John',
// lastName: 'Doe',
// phone: '5551234',
// dateOfBirth: Date('1990-01-01')
// }
`

$3

`typescript
const headers = ['email_address', 'first_name', 'last_name', 'phone_number'];
const targetFields = ['email', 'firstName', 'lastName', 'phone'];

// Generate mapping suggestions
const suggestions = mapper.suggestMapping(headers, targetFields);
console.log(suggestions);
// [
// { csvColumn: 'email_address', targetField: 'email', confidence: 0.95, reasoning: 'Field variation' },
// { csvColumn: 'first_name', targetField: 'firstName', confidence: 0.95, reasoning: 'Field variation' },
// ...
// ]

// Auto-generate mapping
const autoMapping = mapper.autoMap(headers, targetFields);
`

$3

`typescript
const csvRows = [
['john@example.com', 'John', 'Doe', '555-1234'],
['jane@example.com', 'Jane', 'Smith', '555-5678']
];

const mappedRows = mapper.mapRows(csvRows, mapping);
`

API Reference

$3

Main class for CSV mapping operations.

#### Constructor

`typescript
new CSVMapper(config?: MapperConfig)
`

#### Methods

- mapRow(row: string[], mapping: ColumnMapping): MappedRow
- mapRows(rows: string[][], mapping: ColumnMapping): MappedRow[]
- suggestMapping(headers: string[], targetFields: string[]): MappingSuggestion[]
- autoMap(headers: string[], targetFields: string[]): ColumnMapping
- validateMapping(mapping: ColumnMapping, headers: string[]): ValidationResult

$3

Supported field types for data conversion:

- FieldType.STRING - String values
- FieldType.NUMBER - Numeric values
- FieldType.BOOLEAN - Boolean values
- FieldType.DATE - Date values
- FieldType.EMAIL - Email addresses
- FieldType.PHONE - Phone numbers
- FieldType.URL - URLs
- FieldType.JSON - JSON data

$3

Built-in field variations handle common CSV column name variations:

- email → ['email', 'e-mail', 'email_address', 'emailaddress', 'mail']
- firstName → ['first_name', 'firstname', 'first name', 'fname', 'given_name']
- lastName → ['last_name', 'lastname', 'last name', 'lname', 'family_name']
- And many more...

Advanced Usage

$3

`typescript
import { FieldVariationManager } from '@bernierllc/csv-mapper';

// Add custom variations
FieldVariationManager.addVariations('customField', ['custom_field', 'customfield', 'cf']);

// Get variations for a field
const variations = FieldVariationManager.getVariations('email');
`

$3

`typescript
import { TypeConverter, FieldType } from '@bernierllc/csv-mapper';

// Convert values
const result = TypeConverter.convert('john@example.com', FieldType.EMAIL);
console.log(result); // { value: 'john@example.com', isValid: true }

// Infer types
const inferredType = TypeConverter.inferType('123.45');
console.log(inferredType); // FieldType.NUMBER
`

$3

`typescript
const mapper = new CSVMapper({
caseSensitive: false,
fuzzyMatching: true,
fuzzyThreshold: 0.7,
enableAutoMapping: true,
strictMode: false
});
`

Error Handling

The mapper provides detailed error information:

`typescript
const mappedRow = mapper.mapRow(csvRow, mapping);

if (mappedRow._mappingErrors) {
console.log('Mapping errors:', mappedRow._mappingErrors);
// [
// {
// column: 'email_address',
// field: 'email',
// error: 'Invalid email format',
// value: 'invalid-email'
// }
// ]
}
``

Performance

Optimized for large datasets:

- Small files (< 1MB): < 100ms processing time
- Medium files (1-10MB): < 1s processing time
- Large files (> 10MB): < 10s processing time

License

Bernier LLC - All rights reserved.