Csvier NPM | npm.io

CSVier

is a small, fast and simple library (written in TypeScript) for manipulating and extracting data from CSV strings.

Features

Small (2kb minified and gzipped), lightweight, and fast.
Has no dependencies
Very good at manipulating large CSV files
Runs in both browser (using tools like webpack) and node JS.
Supports custom delimiters
Source code (written in TypeScript) is transpiled to target es3 supporting browser (works on IE8+).

Installation

npm i csvier

in your JS file

const CSVier = require('csvier');

Usage

const CSVier = require('csvier');

let CSVFile = new CSVier( 'hello,world,in CSV', { rowSep: '\n', colSep: ',' });

Extracting the data from the CSVier instance.

Whenever you apply changes to cells inside rows, the change doesn't happen instantly instead for each row CSVier caches the changes and when a row has changed entirely CSVier deletes the old row and constructs a new one.

that's why you must avoid getting data from the _CSVArr property which is a private & internal property that is not even included in the typings.

in other words use the getData() method to safely get your data, once you're done with the CSVier instance and plan to not use it anymore.

API

Here's a collection of methods that exist on the CSVier prototype that you can call from any CSVier object.

Keep in mind that CSVier can't process strings which contain a row count bigger than maximum array size which is 2^(32-1).

Constructor

`CSVier( CSV: string [, options] )`

CSVier object constructor

CSV The string to be parsed
options Configuration object used to map how the CSV file is going to be parsed
All options
- rowSep : The separating delimiter (string) to be used for rows
- colSep : The separating delimiter (string) to be used for Columns
- customHeader : A CSV string (or array) to be added to the CSV Row array as the a table header (aka will be pushed to the beginning of the CSV row array).
- autoFix : If set to true CSVier will attempt to fix disproportionate parts of the CSV string in order to make the column count fully proportionate across all rows, by default this is set to false because of how expensive the operation is.

Search methods

`match( pattern: RegExp, firstMatchOnly?: boolean ): string[]`

Method that tests all items in the CSV string against a regular expression, returns the items that match correctly.

pattern : Regular expression to test against every item in the array.
firstMatchOnly : If set to true the method will stop after the first match, it will still return an array though.

`getPosOf( pattern: RegExp, firstMatchOnly?: boolean ): CSVPos[]`

Gets the position of the items that matches correctly to the regular expression provided

pattern : Regular expression to test every item in the array.
If set to true the method will stop after the first match, it will still return an array though.
CSVPos : an object that stores the position of a particular item inside the CSV string, it has two properties in it, row and col.

Replace methods

`replace(pattern: RegExp, nVal: string, firstMatchOnly?: boolean): void`

Replaces each and every item that matches correctly to the regular expression provided.

pattern : Regular expression to test every item in the array.
nVal : The value to replace with.
firstMatchOnly : If set to true the method will stop after the first replacement.

`replaceByPos( pos: CSVPos, nVal: string ): void`

Replaces an item by it's position.

pos : The position of the item. an object that contains two properties row and col for example {row:0, col: 0}.
nVal : The new value to replace with.

`flipRows( rowIndex1: number, rowIndex2: number ): void`

Flips two rows via their position.

rowIndex1 : The index of the first row (which will be placed in the place of the second).
rowIndex2 : The index of the second row (which will be placed in the place of the first).

`hasEmptyCells( rowIndex: number ): boolean`

checks whether or not a row has empty cells in it.

rowIndex: the index of the row to be checked.

Remove methods

`remove(pos: CSVPos): void`

Removes a value via it's position (i.e replaces it's value with "" an empty string).

pos : The position of the item to be emptied. an object that contains two properties row and col for example {row:0, col: 0}

`removeRow(rowIndex: number): void`

Removes an entire row completely off the CSV row array.

rowIndex : The index of the row to be deleted.

`emptyRow(rowIndex: number): void`

Empties a specified row, i.e sets the value of all items in it to "" (an empty string)

rowIndex : The index of the row to be emptied

Existence checking methods

`exists( pos: CSVPos, getBack?: boolean ): boolean | string`

Checks if an item exists in the CSV array.

pos : The position to be checked. an object that contains two properties row and col for example {row:0, col: 0}.
getBack : if set to true then the item will be returned if it actually exists.

`rowExists( rowIndex: number ): boolean`

Checks if a specific row exists in the array via it's index.

rowIndex : The index of the row

Data extraction methods

`getRow( rowIndex: number ): string`

Fetches a row via it's index from the CSV array, throws an error if the row doesn't exist.

rowIndex : The index of the row.

`getData(): string[]`

The main method used to get the CSV data. very performance intensive (if you made lots of changes to the data) it should be called after being done manipulating the CSV data inside CSVier instance entirely.

Fix methods

`fix(): void`

Fixes disproportionate rows in the CSV array, in other words invoking this method will unify the column count between all rows.

`isRowProportionate( rowIndex: number ): boolean`

Checks if the row is proportionate (has an item/cell count equal to the largest item cell count in the row with the biggest item/cell count).

rowIndex : The index of the row to be checked.

`fixRow(rowIndex: number): void`

Fixes a disproportionate row via it's index.

rowIndex : The index of the row to be fixed.

Row and column insertion methods.

`add(rowIndex: number, item: string, colIndex?: number): void`

Adds an item to a row.

rowIndex The index of the row

item : The item to be added
colIndex : The index of the column

Internal utilities methods

`_loop( cb: (currentItem: string, currentPosition: CSVPos) => boolean ): void`

Function that loops through every item until the provided callback returns true

cb : The call back which must return a boolean value to indicate whether or not to stop looping
Callback Params
- currentItem : The current item.
- currentPosition : The current position of the current item.