@kksiuda/csv NPM

Overview

No dependency CSV parsing and stringifying, synchronously or via stream, typed or untyped

Installation

yarn install @kksiuda/csv

npm install @kksiuda/csv

API

parseCsv

Parses string synchronously.

input
- string: string
- columns?: CsvColumns
- params?: CsvParams
output
- when columns are specified it returns array of type inferred from columns, otherwise array of records

Example

import { parseCsv, CsvColumns } from '@kksiuda/csv';

const csvString = 'a,b\n1,2\n';
const columns = {
  a: 'integer',
  b: { type: 'string' },
} satisfies CsvColumns;
console.log(parseCsv(csvString)); // [ { a: '1', b: '2' } ]
console.log(parseCsv(csvString, columns)); // [ { a: 1, b: '2' } ]

stringifyCsv

Stringifies array of records. Note: if columns are not specified the columns will be inferred from the first row.

input
- records: when columns are specified array of type inferred from columns, otherwise array of records
- columns?: CsvColumns
- params?: CsvParams
output
- string

Example

import { stringifyCsv } from '@kksiuda/csv';

const records = [{ a: 1 }, { a: 1, b: 2 }];
const columns = {
  a: 'integer',
  b: { type: 'integer' },
} satisfies CsvColumns;
console.log(stringifyCsv(records)); // 'a\n1\n'
console.log(stringifyCsv(records, columns)); // 'a,b\n1,\n1,2\n'

createParseCsvStream

Creates a transform stream for parsing csv.

input
- columns?: CsvColumns
- params?: CsvParams
output
- Transform stream that takes in strings and outputs records in objectMode

Example

import { createParseCsvStream, createStringifyCsvStream } from '@kksiuda/csv';
import { createReadStream, createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream';
const readable = createReadStream('./input.csv');
const writable = createWriteStream('./output.csv');
const parseStream = createParseCsvStream();
const stringifyStream = createStringifyCsvStream();
pipeline(
  readable,
  parseStream,
  stringifyStream,
  writable,
  (err) => (err ? console.log(err) : console.log('done')) // 'done'
);

createStringifyCsvStream

Creates a transform stream for stringifying csv.

input
- columns?: CsvColumns
- params?: CsvParams
output
- Transform stream that takes records in objectMode and outputs strings

Example: see above

parseCsvFromStream

Takes an string input stream and asynchronously parses csv

input
- stream: Readable | Transform
- columns?: CsvColumns
- params?: CsvParams
output
- Promise of array of types specified in columns when defined or array of records otherwise

Example:

import { parseCsvFromStream } from '@kksiuda/csv';
import { createReadStream } from 'node:fs';

const readable = createReadStream('./input.csv');
(async () => {
  console.log(await parseCsvFromStream(readable)); // array of records
})();

stringifyCsvFromStream

Takes an objectMode input stream and asynchronously stringifies csv

input
- stream: Readable | Transform
- columns?: CsvColumns
- params?: CsvParams
output
- Promise of string

Example:

import { stringifyCsvFromStream, createParseCsvStream } from '@kksiuda/csv';
import { createReadStream } from 'node:fs';

const readable = createReadStream('./input.csv');
const parseStream = createParseCsvStream();

(async () => {
  readable.pipe(parseStream);
  console.log(await stringifyCsvFromStream(parseStream)); // csv string
})();

Types

CsvColumns

type CsvColumns<T extends Record<string, any> = Record<string, any>> = {
  [P in keyof T]?: CsvColumn<T, P> | CsvColumnType;
};
type CsvColumn<T extends Record<string, any>, P extends keyof T = keyof T> = {
  type: CsvColumnType;
  nullable?: boolean;
  stringify?: (val: T[P]) => string;
  parse?: (str: string) => T[P];
  header?: string;
  index?: number;
};

Note: when parsing empty strings will always be parsed as either null or undefined when useNullForEmpty is true

prop: property on the object; when header is not specified it will be used as a header when stringifying csv
type:
- 'text'
  - stringify
    - value is string -> value
    - value is boolean or truthy -> value cast to string
    - else -> ''
  - parse
    - value -> value
- 'integer'
  - stringify
    - value is number and not NaN -> value.toFixed(0)
    - else -> ''
  - parse
    - value -> parseInt(value, 10)
- 'float'
  - stringify
    - value is number and not NaN -> value cast to string
    - else -> ''
  - parse
    - value -> value * 1
- 'percentage'
  - stringify
  - value is number and not NaN -> value * 100 cast to string with '%' at the end
  - else -> ''
  - parse
    - value -> parseInt(value, 10) / 100
- 'boolean'
  - stringify
    - value is not undefined and not null and falsy -> 'FALSE'
    - value is truthy -> 'TRUE'
    - else -> ''
  - parse
    - value is '0', 'N', 'n', 'false', 'FALSE', 'False', 'no', 'NO', or 'No' -> false
    - else -> true
- 'date', 'datetime', 'datetimes', 'timestamp'
  - parses using dateClass supplied in csvParams; see for defaults below
  - parse
    - value can be parsed by casting to built-in Date -> number
  - stringify
    - value is NaN or not of type number -> ''
    - date: 'YYYY-MM-DD'
    - datetime: 'YYYY-MM-DD HH:mm'
    - datetimes: 'YYYY-MM-DD HH:mm:SS'
    - timestamp: 'YYYY-MM-DD HH:mm:SS.sss'
- 'custom'
  - parse
    - uses parse function; defaults to 'string'
  - stringify
    - uses stringify function; defaults to 'string'
stringify
- function that takes value of prop from the record and returns a string
- only used when type is 'custom'
parse
- function that takes csv string and returns the value of prop to go on the record
- only used when type is 'custom'
header
- represents header in the csv
- when not specified defaults to prop

CsvParams

interface CsvParams {
  delimiter?: string;
  quote?: string | null;
  escapeQuote?: string | null;
  rowSeparator?: string;
  ignoreUnderscoredProps?: boolean;
  dateOptions?: {
    locale?: string;
    timezoneOffset?: number | 'local';
    dst?: 'none' | 'eu' | 'us';
  };
  dateFormats?: {
    date?: string;
    dateTime?: string;
    dateTimeSeconds?: string;
    timestamp?: string;
  };
  dateClass?: DateConstructor;
  noHeader?: boolean;
  useNullForEmpty?: boolean;
  titleCaseHeaders?: boolean;
  preserveCarriageReturn?: boolean;
}

Note: when specifying non-default dateOptions or dateFormats dateClass needs to point to a constructor from an external library (see p00dle/datex), otherwise it will throw an error

Note: when both escape and escapeQuote are null no values are considered as quoted in both parsing and stringifying

delimiter - string that separates values in a row; default: ','
quote - string that wraps the value when value contains delimiter, quote, or rowSeparator; default: '"'
escapeQuote - string that is used for escaping quote; default: '""'
rowSeparator - string that separates rows; default: '\n'
ignoreUnderscoredProps - when columns are not specified during the stringifying process all props starting with an underscore will be ignored; has no effect on parsing; default: false
dateOptions
- locale - determines things like month names, ordinals etc.
- timezoneOffset - timezone offset in hours or 'local' to use machine's local timezone offset
- dst - the daylight savings system used to determine when daylight savings are applied
dateFormats
- specify date format for specific column types
dateClass - specify when using an external library
noHeader - when true headers will not be emitted when stringifying; when parsing columns will be assigned using the order of columns (throws when columns are undefined); default: false
useNullForEmpty - when true empty values will be parsed as null, otherwise as undefined; default: true
titleCaseHeaders - when columns are not specified the headers will be parsed from camel case to title case; only applies to stringifying; default: false
preserveCarriageReturn - when true carriage return (\r) are not removed and considered valid characters; default: false