salsacsv v1.0.1

A basic, explicit CSV parsing and formatting library for use in node.js. CSV strings are parsed and formatted using a set of column definitions for converting to and from CSV.

API

Table of Contents

• salsacsv
  • toCSV
    • Parameters
    • Examples
  • fromCSV
    • Parameters
    • Examples
  • cellLabel
    • Parameters
    • Examples
• Column
  • Properties
• Converter
  • Parameters
• ConverterDetails
  • Properties
• Parser
  • Parameters
• ParserDetails
  • Properties

salsacsv

Used for converting data to and from CSV.

toCSV

Converts an array of objects to a CSV string.

Parameters

• rows Array<Object> Array of objects to form rows from.
• columns Array<Column> An array containing columns.
• options Object Parsing options. (optional, default {})
  • options.includeHeader Boolean? Whether the CSV has a header or not, the first line will be skipped if this is set to true.
  • options.delimiter String The delimiter for the CSV string. (optional, default ',')

Examples

toCSV([
    {
        name: 'Cat Chow',
        price: 529
    }
], [
    {
        header: 'Name',
        key: 'name'
    },
    {
        header: 'Price',
        key: 'price',
        converter: (value) => value / 100
    }
], {
    includeHeader: true
});
// "Name","Price"\n"Cat Chow",5.29

Returns String CSV string.

fromCSV

Converts a CSV string into objects.

Parameters

• csvStr String CSV string.
• columns Array<Column> An array containing columns. (optional, default [])
• options Object Parsing options. (optional, default {})
  • options.includeHeader Boolean? Whether the CSV has a header or not.
  • options.includeEmptyValues Boolean? Whether to assign empty values to object or not.
  • options.delimiter String The delimiter of the CSV string. (optional, default ',')

Examples

fromCSV('"Name","Price"\n"Cat Chow",5.29', [
    {
        header: 'Name',
        key: 'name'
    },
    {
        header: 'Price',
        key: 'price',
        parser: (value) => Math.round(parseFloat(value) * 100)
    }
], {
    includeHeader: true
});
// { name: 'Cat Chow', price: 529 }

// using no column definitions
// there will be no type conversions if no parser is given, any returned values will be strings
fromCSV('"Cat Chow",5.29');
// { col1: 'Cat Chow', col2: '5.29' }

// using no column definitions (use header as keys)
fromCSV('"Name","Price"\n"Cat Chow",5.29', null, {
    includeHeader: true
});
// { Name: 'Cat Chow', Price: '5.29' }

Returns Array<Object> Array of objects.

cellLabel

Gets the cell label.

Parameters

• rowNumber Number Zero-based row number.
• columnNumber Number Zero-based column number.

Examples

cellLabel(0, 3); // A3

Returns String Cell label.

Column

An object describing the format of a column.

Type: Object

Properties

• header String? The header to be used for this column.
• key String? The object key for this column.
• required Boolean? Indicates whether the value should be defined when getting value from CSV. Throws an error if the resulting value is null, undefined, or an empty string.
• converter Converter? The function called to convert value to CSV.
• parser Parser? The function called to parse value from CSV. Will not be called unless parseEmpty is set to true.
• parseEmpty Boolean? Whether to parse empty values or not.

Converter

Function to convert value to raw CSV.

Type: Function

Parameters

• value String? Value from object.
• details ConverterDetails? Details of cell.

Returns (String | Number | null | undefined) Value of cell.

ConverterDetails

Converter details

Type: Object

Properties

• obj Object? Source object.
• key String? The key of the value we want to take from the object for this column.
• row Number? Row number.
• column Number? Column number.

Parser

Function to parse value from raw CSV.

Type: Function

Parameters

• value String? Value of cell.
• details ParserDetails? Details of cell.

Returns any Parsed value from CSV string.

ParserDetails

Parser details

Type: Object

Properties

• key String? Name of key to assign to object.
• row Number? Row number.
• column Number? Column number.

License

MIT