CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-csv-writer

Convert objects/arrays into a CSV string or write them into a CSV file

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

CSV Writer

CSV Writer converts objects/arrays into a CSV string or write them into a CSV file. It respects RFC 4180 for the output CSV format, providing reliable CSV generation with proper quoting and escaping for Node.js applications.

Package Information

  • Package Name: csv-writer
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install csv-writer

Core Imports

import { 
  createObjectCsvWriter, 
  createArrayCsvWriter,
  createObjectCsvStringifier,
  createArrayCsvStringifier 
} from "csv-writer";

For CommonJS:

const { 
  createObjectCsvWriter, 
  createArrayCsvWriter,
  createObjectCsvStringifier,
  createArrayCsvStringifier 
} = require("csv-writer");

Basic Usage

Writing Object Records to File

import { createObjectCsvWriter } from "csv-writer";

const csvWriter = createObjectCsvWriter({
  path: 'path/to/file.csv',
  header: [
    { id: 'name', title: 'NAME' },
    { id: 'lang', title: 'LANGUAGE' }
  ]
});

const records = [
  { name: 'Bob', lang: 'French, English' },
  { name: 'Mary', lang: 'English' }
];

await csvWriter.writeRecords(records);
// Creates: NAME,LANGUAGE
//          Bob,"French, English"
//          Mary,English

Generating CSV String

import { createObjectCsvStringifier } from "csv-writer";

const csvStringifier = createObjectCsvStringifier({
  header: [
    { id: 'name', title: 'NAME' },
    { id: 'lang', title: 'LANGUAGE' }
  ]
});

console.log(csvStringifier.getHeaderString());
// => 'NAME,LANGUAGE\n'

console.log(csvStringifier.stringifyRecords(records));
// => 'Bob,"French, English"\nMary,English\n'

Capabilities

Object CSV Writer Creation

Creates a CSV writer for object-based records with field mapping and optional headers.

function createObjectCsvWriter(params: ObjectCsvWriterParams): CsvWriter<ObjectMap<Field>>;

interface ObjectCsvWriterParams {
  path: string;
  header: ObjectStringifierHeader;
  fieldDelimiter?: string;
  recordDelimiter?: string;
  headerIdDelimiter?: string;
  alwaysQuote?: boolean;
  encoding?: string;
  append?: boolean;
}

Usage Examples:

// Basic object writer
const writer = createObjectCsvWriter({
  path: 'output.csv',
  header: [
    { id: 'name', title: 'Name' },
    { id: 'age', title: 'Age' }
  ]
});

// Writer with custom delimiters
const semicolonWriter = createObjectCsvWriter({
  path: 'output.csv',
  header: ['name', 'age'], // String headers (no title line)
  fieldDelimiter: ';',
  recordDelimiter: '\r\n'
});

// Writer for nested objects
const nestedWriter = createObjectCsvWriter({
  path: 'output.csv',
  header: [
    { id: 'user.name', title: 'Name' },
    { id: 'user.profile.age', title: 'Age' }
  ],
  headerIdDelimiter: '.'
});

Array CSV Writer Creation

Creates a CSV writer for array-based records with optional header row.

function createArrayCsvWriter(params: ArrayCsvWriterParams): CsvWriter<Field[]>;

interface ArrayCsvWriterParams {
  path: string;
  header?: string[];
  fieldDelimiter?: string;
  recordDelimiter?: string;
  alwaysQuote?: boolean;
  encoding?: string;
  append?: boolean;
}

Usage Examples:

// Array writer with headers
const writer = createArrayCsvWriter({
  path: 'output.csv',
  header: ['NAME', 'LANGUAGE']
});

const records = [
  ['Bob', 'French, English'],
  ['Mary', 'English']
];

await writer.writeRecords(records);

// Array writer without headers
const noHeaderWriter = createArrayCsvWriter({
  path: 'data.csv'
});

Object CSV Stringifier Creation

Creates a CSV stringifier for converting object records to CSV strings without file output.

function createObjectCsvStringifier(params: ObjectCsvStringifierParams): ObjectCsvStringifier;

interface ObjectCsvStringifierParams {
  header: ObjectStringifierHeader;
  fieldDelimiter?: string;
  recordDelimiter?: string;
  headerIdDelimiter?: string;
  alwaysQuote?: boolean;
}

Usage Examples:

const stringifier = createObjectCsvStringifier({
  header: [
    { id: 'name', title: 'NAME' },
    { id: 'lang', title: 'LANGUAGE' }
  ]
});

const headerString = stringifier.getHeaderString();
const csvData = stringifier.stringifyRecords(records);
const fullCsv = headerString + csvData;

Array CSV Stringifier Creation

Creates a CSV stringifier for converting array records to CSV strings without file output.

function createArrayCsvStringifier(params: ArrayCsvStringifierParams): ArrayCsvStringifier;

interface ArrayCsvStringifierParams {
  header?: string[];
  fieldDelimiter?: string;
  recordDelimiter?: string;
  alwaysQuote?: boolean;
}

Usage Examples:

const stringifier = createArrayCsvStringifier({
  header: ['NAME', 'LANGUAGE']
});

const records = [
  ['Bob', 'French, English'],
  ['Mary', 'English']
];

const csvString = stringifier.stringifyRecords(records);

CSV Writing

Writes records to the configured file path.

interface CsvWriter<T> {
  /**
   * Writes array of records to file
   * @param records - Array of records
   * @returns Promise that resolves when writing is complete
   */
  writeRecords(records: T[]): Promise<void>;
}

CSV String Generation

Generates CSV strings from record data.

interface ArrayCsvStringifier {
  /**
   * Returns header string or null if no header
   * @returns Header as CSV string with record delimiter
   */
  getHeaderString(): string | null;
  
  /**
   * Converts array records to CSV string
   * @param records - Array of arrays or iterable iterator
   * @returns CSV formatted string
   */
  stringifyRecords(records: Field[][] | IterableIterator<Field[]>): string;
}

interface ObjectCsvStringifier {
  /**
   * Returns header string or null if no header
   * @returns Header as CSV string with record delimiter
   */
  getHeaderString(): string | null;
  
  /**
   * Converts object records to CSV string
   * @param records - Array of objects or iterable iterator
   * @returns CSV formatted string
   */
  stringifyRecords(records: ObjectMap<Field>[] | IterableIterator<ObjectMap<Field>>): string;
}

Types

// Core field type - accepts any value
type Field = any;

// Header definition for object stringifiers
type ObjectHeaderItem = { 
  id: string;    // Field ID for data extraction
  title: string; // Column title in header row
};

type ObjectStringifierHeader = ObjectHeaderItem[] | string[];

// Generic key-value map
interface ObjectMap<T> {
  [key: string]: T;
}

Configuration Options

Field Delimiters

  • Default: ','
  • Valid values: ',', ';'
  • Controls the separator between fields in each record

Record Delimiters

  • Default: '\n'
  • Valid values: '\n', '\r\n'
  • Controls the separator between records

File Encoding

  • Default: 'utf8'
  • Standard Node.js file encoding options supported

Quoting Behavior

  • Default: false (conditional quoting)
  • alwaysQuote: true: Forces all fields to be quoted regardless of content
  • alwaysQuote: false: Only quotes fields containing delimiters, quotes, or newlines

Append Mode

  • Default: false (overwrite file)
  • append: true: Appends records to existing file (no header written)
  • append: false: Overwrites file with new content including header

Nested Object Access

  • headerIdDelimiter: Specify delimiter for accessing nested object properties
  • Example: 'user.profile.name' with delimiter '.' accesses record.user.profile.name

Error Handling

The library validates configuration parameters and throws errors for:

  • Invalid field delimiters (not ',' or ';')
  • Invalid record delimiters (not '\n' or '\r\n')
  • File system errors during writing operations

All write operations return Promises that reject with appropriate error information.

docs

index.md

tile.json