csv-builder - npm Package Compare versions

Comparing version 0.0.4 to 1.0.0

index.js

@@ -1,1 +0,1 @@
-module.exports = require('./lib/csvBuilder');
+module.exports = require('./lib/CsvBuilder')

package.json

 {
   "name": "csv-builder",
-  "author": "Nick Pisacane <[e-mail]> (http://nickpisacane.com)",
-  "version": "0.0.4",
-  "description": "Create csv formated streams from Arrays of Objects.",
+  "author": "Nick Pisacane <[e-mail]>",
+  "version": "1.0.0",
+  "description": "Easily encode complex JSON objects to CSV with CsvBuilder's schema-like API",
   "license": "MIT",
@@ -13,19 +13,28 @@ "repository": {
     "csv",
-    "array",
-    "stream",
-    "array to csv",
+    "csv encoder",
+    "json to csv",
     "object to csv",
-    "csv stream"
+    "csv stream",
+    "csv exporter"
   ],
   "dependencies": {
-    "lodash": "~3.8.0",
-    "through": "~2.3.7"
+    "lodash.get": "^4.4.2",
+    "lodash.pick": "^4.4.0"
   },
   "scripts": {
-    "test": "mocha test/**/*.test.js"
+    "lint": "standard",
+    "test": "npm run lint && mocha test/**/*.test.js",
+    "test:watch": "watch-run -i -p 'lib/**/*.js,test/**/*.js' npm run test"
   },
   "devDependencies": {
-    "mocha": "^3.2.0",
-    "testable-stream": "0.0.1"
+    "chai": "^3.5.0",
+    "mocha": "^3.3.0",
+    "standard": "^10.0.2",
+    "watch-run": "^1.2.5"
+  },
+  "standard": {
+    "ignore": [
+      "test"
+    ]
   }
 }

README.md

 # Csvbuilder
 ![travis](https://travis-ci.org/nickpisacane/CsvBuilder.svg?branch=master)
 
-Create csv formated streams from Arrays of Objects. CsvBuilder is one of many Csv stream/generator implementations
-on npm. The goal of CsvBuilder is to create Schema's for csv output and let the consumer spawn as many streams
-as needed from a single instance to maintain a specific format. This means the user gets control of the headers, the
-order of the headers, how the headers correspond to consumed objects, virtual properties, value delimiters, and line
-terminators.
+Easily encode complex JSON objects to CSV with CsvBuilder's schema-like API.
 
-## Getting Started
+# Table Of Contents
+* [Usage](#Usage)
+* [New Features](#New-Features)
+* [Installation](#Installation)
+* [API](#API)
+* [Migration To 1.0.0](#Migration-to-1.0.0)
+
+# Usage
 ```js
 
-var CsvBuilder = require('csv-builder');
+const CsvBuilder = require('csv-builder')
 
-// Assuming data takes the following form
-var data = [
-	name: 'Example User',
-	email: '[e-mail]',
-	meta: {
-		active: true
-	}
+const data = [
+  {
+    name: 'Foo Bar',
+    meta: {
+      active: true,
+      roles: [
+        'user',
+        'admin'
+      ]
+    }
+  }
 ]
 
-var usersBuilder = new CsvBuilder({
-	// define headers and order of headers
-	headers: 'Firstname Lastname Email Active',
-	// define object to header correspondance
-	constraints: {
-		// Header: property
-		'Email': 'email'
-		// correspond with a virtual property
-		'Lastname': 'lastname',
-		// Access a nested property
-		'Active': 'meta.active'
-	}
+const builder = new CsvBuilder({
+  headers: ['Firstname', 'Lastname', 'Role 1', 'Role 2', 'Active'],
+  alias: {
+    'Role 1': 'meta.roles[0]',
+    'Role 2': 'meta.roles[1]',
+    'Active': 'meta.active'
+  }
 })
-	// create virtual 'Firstname'
-	.virtual('Firstname', function(obj) {
-		return obj.name.split(' ')[0];
-	})
-	// virtual properties are treated like any propery,
-	// if it is not defined in the headers, it still needs a constraint
-	.virtual('lastname', function(obj) {
-		return obj.name.split(' ')[1];
-	});
+  .virtual('Firstname', user => user.name.split(' ')[0])
+  .virtual('Lastname', user => user.name.split(' ')[1])
 
-// From the `usersBuilder` instance we can now spawn readable or tranform streams.
+/* Each of the following produces the following CSV contents:
 
-// pipe into a newly created duplex
-Model.find().stream()
-	.pipe(usersBuilder.createTransformStream())
-	.pipe(fs.createWriteStream('output.csv'));
+"Firstname","Lastname","Role 1","Role 2","Active"
+"Foo","Bar","user","admin","true"
 
-// Create a readable stream from an Array<Object> payload
-usersBuilder.createReadStream(payload)
-	.pipe(fs.createWriteStream('output.csv'));
+*/
+
+
+// (1) Create from a Stream of objects (like a database)
+getObjectStream()
+  .pipe(builder.createTransformStream())
+  .pipe(fs.createWriteStream('output.csv'))
+
+// (2) Create from an existing payload (`data` is an array of objects)
+builder.createReadStream(data)
+  .pipe(fs.createWriteStream('output.csv'))
+
+// (3) Roll your own
+let csv = ''
+csv += builder.getHeaders()
+data.forEach(item => {
+  csv += builder.getRow(item)
+})
+fs.writeFileSync('output.csv', csv)
 ```
 
-## Installation
+# Installation
 ```bash
-$ npm install csv-builder
+$ npm i -s csv-builder
+# or
+$ yarn add csv-builder
 ```
 
-## Usage
+# New Features
+* More cohesive API
+* Expanded API to support non-stream outputs, i.e. building a CSV string row-by-row with the `getHeaders()` and `getRow(object)` methods respectively.
+* Better CSV encoding (proper quoting by default)
+
+# API
 ##### CsvBuilder([options])
-* headers String|Array Space separated headers, or array of headers **(required)**
-* delimiter String The value delimiter. Default ','
-* terminator String The line terminator. Default '\n'
-* mutate Boolean Mutate incoming objects when creating virtuals. Default true
-* constraints Object {"header": "prop"}
+* `headers` *String|Array<String>* Space separated headers, or array of headers **(required)**
+* `delimiter` *String* The column delimiter. Default `','`
+* `terminator` *String* The row terminator. Default `'\n'`
+* `quoted` *Boolean* Quote columns? Default `true`
+* `alias` *Object* An object in the format of { "csv header": "object prop" }, `object prop` will be aliased to `csv header`. Default `{}`
 
 ## Methods
-##### CsvBuilder#headers(headers)
-* headers String|Array Space separated headers, or array of headers
 
-##### CsvBuilder#set(header, prop)
+##### CsvBuilder#`createReadStream`(payload): *Stream.Readable*
+Creates a readable stream and consumes the payload.
+* `payload` *Array\<Object\>* Incoming data.
+
+##### CsvBuilder#`createTransformStream`(): *Stream.Transform*
+Creates a transform stream. The stream expects either Objects or JSON.
+
+##### CsvBuilder#`headers`(headers): *this*
+* `headers` *String|Array* Space separated headers, or array of headers
+
+##### CsvBuilder#`alias`(header, prop): *this*
 Set single or multiple contraints. If `header` is an object, it will extend any existing constraints, not replace.
-* header String|Object Either object {"header": "property"} Or a string "Header"
-* prop String Property to correspond to header, omit if using object.
+* `header` *String|Object* Either object {"header": "property"} Or a string "Header"
+* `prop` *String|undefined* Property to correspond to header, omit if using object.
 
-##### CsvBuilder#virtual(prop, fn)
+##### CsvBuilder#`virtual`(prop, fn): *this*
 Create a virtual property. Virtual properties are treated the same as normal
-properties, so if no header matches the virtual property name, or no constraint is
-set the virtual property will be omitted.
-* prop String Virtual property name
-* fn Function Returns virtual value, takes the object to be created/mutated as the only argument.
+properties. If there is no corresponding header or alias, the virtual will not be present in resulting CSV.
+* `prop` *String* Virtual property name
+* `fn` *(item: any) => any* Where `item` is an element from the incoming data, and the return value is the corresponding value for the virtualized property.
 
-##### CsvBuilder#createReadStream(payload)
-Create's a readable stream and consumes the payload.
-* payload Array<Object>
+##### CsvBuilder#`getHeaders`(): *String*
+The headers in CSV format
 
-##### CsvBuilder#createTransformStream()
-Create's a transform stream. The stream expects either Objects or JSON.
+##### CsvBuilder#`getRow`(item): *String*
+Returns the CSV formated row for a given `item`.
+*  `item` *Object* A n item matching the "schema".
+
+# Migration to 1.0.0
+* `constraints` attribute in options (for constructor) is deprecated, use `alias` instead.
+* `set(prop, value)` method is deprecated, use `alias(prop, value)` instead.

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

53951

increased by212.22%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

120

increased by27.66%

Number of low supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dev dependency count

4

increased by100%

Number of package files

7

decreased by-30%

Lines of code

132

decreased by-66.07%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedlodash.get@^4.4.2

• + Addedlodash.pick@^4.4.0

• + Addedlodash.get@4.4.2(transitive)

• + Addedlodash.pick@4.4.0(transitive)

• - Removedlodash@~3.8.0

• - Removedthrough@~2.3.7

• - Removedlodash@3.8.0(transitive)

• - Removedthrough@2.3.8(transitive)