CSVT-Parse

A powerful Node.js library for parsing and writing CSV files with typed column definitions. CSVT-Parse provides comprehensive type validation and robust error handling for working with structured CSV data.

Features

• 🎯 Typed Column Definitions: Define column types directly in the CSV header (name:string,age:number)
• 🔍 Comprehensive Type Validation: Built-in validation for 20+ data types including primitives, dates, URLs, emails, UUIDs, and more
• 🔧 Enum Types: Define columns with restricted value sets (status:enum(pending,approved,rejected))
• 🔀 Union Types: Support multiple types per column (value:string|number|boolean)
• 🌟 Any Type: Auto-detecting flexible type that infers the best match (data:any)
• 📁 File I/O Support: Read from and write to files with async/sync APIs
• 🛡️ Error Handling: Comprehensive error reporting with line and column context
• 🚀 High Performance: Optimized parsing with minimal overhead
• 📦 TypeScript First: Full TypeScript support with complete type definitions
• 🔒 Source Protection: Obfuscated distribution for commercial use

Installation

npm install @abdullah_zughbi/csvt-parse

Quick Start

Basic Usage

const csvt = require('@abdullah_zughbi/csvt-parse');

// Parse CSVT content with typed columns
const csvtContent = `name:string,age:number,active:boolean
"John Doe",30,true
"Jane Smith",25,false`;

const result = csvt.parseCSVTSync(csvtContent);
console.log(result.data);
// Output: [
//   { name: "John Doe", age: 30, active: true },
//   { name: "Jane Smith", age: 25, active: false }
// ]

File Operations

// Read from CSVT file
const fileData = csvt.readFileSync('data.csvt');
console.log(fileData.data);

// Write to CSVT file
const data = [
  { name: 'Alice', score: 95, active: true },
  { name: 'Bob', score: 87, active: false }
];

const columns = [
  { name: 'name', type: 'string' },
  { name: 'score', type: 'number' },
  { name: 'active', type: 'boolean' }
];

csvt.writeFileSync('output.csvt', data, columns);

Complex Data Types

// JSON objects and arrays
const complexCSVT = `user:string,preferences:json,history:array
"alice","{""theme"":""dark"",""lang"":""en""}","[""login"",""purchase""]"`;

const result = csvt.parseCSVTSync(complexCSVT);
console.log(result.data[0]);
// Output: {
//   user: "alice",
//   preferences: { theme: "dark", lang: "en" },
//   history: ["login", "purchase"]
// }

Enum Types

// Restricted value sets
const enumCSVT = `status:enum(pending,approved,rejected),priority:enum(low,medium,high)
"pending","high"
"approved","medium"
"rejected","low"`;

const enumResult = csvt.parseCSVTSync(enumCSVT);
console.log(enumResult.data);
// Output: [
//   { status: "pending", priority: "high" },
//   { status: "approved", priority: "medium" },
//   { status: "rejected", priority: "low" }
// ]

Union Types

// Multiple type options per column
const unionCSVT = `id:string|number,value:number|boolean,mixed:string|number|boolean
"user123",42,true
"456",3.14,"hello"
"789",0,false`;

const unionResult = csvt.parseCSVTSync(unionCSVT);
console.log(unionResult.data);
// Output: [
//   { id: "user123", value: 42, mixed: "true" },
//   { id: "456", value: 3.14, mixed: "hello" },
//   { id: "789", value: 0, mixed: "false" }
// ]

Any Type

// Auto-detecting flexible type
const anyCSVT = `name:string,data:any,info:any
"John",42,"text value"
"Jane",true,"[1,2,3]"
"Bob","{""key"":""value""}",123.45`;

const anyResult = csvt.parseCSVTSync(anyCSVT);
console.log(anyResult.data);
// Output: [
//   { name: "John", data: 42, info: "text value" },
//   { name: "Jane", data: true, info: [1,2,3] },
//   { name: "Bob", data: {"key":"value"}, info: 123.45 }
// ]

Escape Sequences

// Enable escape sequence processing for string fields
const escapeCSVT = `message:string,path:string
"Line 1\\nLine 2","C:\\\\Users\\\\file.txt"`;

// Default behavior - preserves literal backslashes
const defaultResult = csvt.parseCSVTSync(escapeCSVT, { processEscapes: false });
console.log(defaultResult.data[0].message); // "Line 1\\nLine 2"

// With escape processing - converts sequences to actual characters
const processedResult = csvt.parseCSVTSync(escapeCSVT, { processEscapes: true });
console.log(processedResult.data[0].message); 
// Output: "Line 1
//          Line 2"

// Supported escape sequences: \\n \\t \\r \\" \\\\

Supported Types

Basic Types

| Type | Description | Example | |----------|--------------------|--------------------------| | string | Text values | "Hello World" | | number | Integer or float | 42, 3.14 | | boolean| Boolean values | true, false, 1, 0, yes, no | | array | JSON arrays | ["item1", "item2"] | | json | JSON objects | {"key": "value"} | | any | Auto-detecting type| Auto-infers best type | | void | Null/empty values | null, "" |

Date & Time Types

| Type | Description | Example | |------------|------------------|----------------------------| | date | Date only | "2024-01-15" | | datetime | Date with time | "2024-01-15T10:30:00Z" | | time | Time only | "10:30:00" |

Web & Network Types

| Type | Description | Example | |-------------|-----------------|--------------------------------| | url | HTTP/HTTPS URLs | "https://example.com" | | email | Email addresses | "[email protected]" | | ipaddress | IP addresses | "192.168.1.1" |

Visual Types

| Type | Description | Example | |-------------|------------------|----------------------| | hexcolor | Hex colors | "#FF0000" | | rgba | RGBA colors | "rgba(255,0,0,0.5)"| | color | Named/hex colors | "red", "#FF0000"|

Identifier Types

| Type | Description | Example | |--------------|-------------|--------------------------------| | uuid | UUIDs | "550e8400-e29b-41d4-a716-446655440000" | | percentage | Percentages | "75%" |

Advanced Types

| Type | Description | Example | |---------|--------------------------|----------------------------------| | enum | Restricted value set | status:enum(pending,approved,rejected) | | union | Multiple type options | value:string\|number\|boolean |

Length-Specified Text

| Type | Description | Example | |---------------|--------------------------------|----------------------------| | text | Unlimited text length | description:text | | varchar(n) | Variable length, max n chars | name:varchar(50) | | char(n) | Fixed length, padded to n chars | code:char(10) |

API Reference

Parsing Functions

• parseCSVTSync(content, options) - Synchronous parsing
• parseCSVT(content, options) - Asynchronous parsing (returns Promise)

File Operations

• readFileSync(filename, options) - Synchronous file reading
• readFile(filename, options) - Asynchronous file reading
• writeFileSync(filename, data, columns, options) - Synchronous file writing
• writeFile(filename, data, columns, options) - Asynchronous file writing

Error Handling

try {
  const result = csvt.parseCSVTSync(content, { strict: true });
} catch (error) {
  if (error instanceof csvt.ValidationError) {
    console.log(`Error in column "${error.column}" at line ${error.line}`);
    console.log(`Expected: ${error.expectedType}, Got: ${error.actualValue}`);
  }
}

Options

const options = {
  delimiter: ',',        // Field delimiter
  quote: '"',           // Quote character
  escape: '"',          // Escape character
  skipEmptyLines: true, // Skip empty lines
  trim: true,           // Trim whitespace
  strict: false,        // Strict error handling
  processEscapes: false // Process escape sequences in string fields
};

Escape Sequence Processing

When processEscapes: true is enabled, the following escape sequences are processed in string fields:

| Sequence | Result | Description | |----------|---------|-------------| | \\n | \n | Newline character | | \\t | \t | Tab character | | \\r | \r | Carriage return | | \\" | " | Quote character | | \\\\ | \ | Backslash character |

Important Notes:

• Escape processing only applies to string type fields
• For union types, processing applies only if the final parsed value is a string
• Complex types like json and array are not affected by escape processing
• Default behavior preserves literal backslashes for compatibility

License

MIT License © 2025 Abdullah Zughbi