csv-types - npm Package Compare versions

Comparing version 0.3.0 to 0.3.1

CHANGELOG.md

 # CHANGELOG
 
+## v0.3.1 (2017-11-05)
+
+**News:**
+
+- Added target inch and online tool (grade A reach).
+- Source file documented following jsdoc3.
+- Concise docs are included in the repo (GitHub pages).
+- New "patch" version to update the minor changes.
+- New NPM package version.
+
 ## v0.3.0 (2017-11-05)
@@ -4,0 +14,0 @@

package.json

 {
   "name": "csv-types",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "CSV Types (csv-types-js) is a JavaScript library to parse CSV strings (comma separated values and text files with fields delimited by a character) and produce a JavaScript AST (abstract syntax tree) with the data. It also supports *types specs*: multiple headers-values (tables) per csv string.",
@@ -9,2 +9,4 @@ "main": "src/index.js",
     "test-stop": "./node_modules/.bin/mocha --bail test/mocha.js",
+    "docs": "./node_modules/.bin/jsdoc -c .jsdoc.json",
+    "inch": "./node_modules/.bin/inchjs list",
     "lint": "./node_modules/.bin/eslint src && echo 'OK Lint'",
@@ -32,3 +34,6 @@ "coverage": "./node_modules/.bin/nyc ./node_modules/.bin/mocha test/mocha.js",
   ],
-  "author": "nozalr",
+  "author": {
+    "name": "nozalr",
+    "company": "Group4Layers"
+  },
   "license": "MIT",
@@ -39,2 +44,5 @@ "devDependencies": {
     "eslint": "^4.10.0",
+    "inchjs": "^0.4.1",
+    "jsdoc": "^3.5.5",
+    "minami": "^1.2.3",
     "mocha": "^4.0.1",
@@ -41,0 +49,0 @@ "nyc": "^11.2.1"

README.md

@@ -7,3 +7,3 @@ # CSV Types (csv-types-js)
 
-Online tools: [![Build Status](https://travis-ci.org/Group4Layers/csv-types-js.svg?branch=master)](https://travis-ci.org/Group4Layers/csv-types-js) [![Coverage Status](https://coveralls.io/repos/github/Group4Layers/csv-types-js/badge.svg?branch=master)](https://coveralls.io/github/Group4Layers/csv-types-js?branch=master) [![Ebert](https://ebertapp.io/github/Group4Layers/csv-types-js.svg)](https://ebertapp.io/github/Group4Layers/csv-types-js)
+Online tools: [![Build Status](https://travis-ci.org/Group4Layers/csv-types-js.svg?branch=master)](https://travis-ci.org/Group4Layers/csv-types-js) [![Coverage Status](https://coveralls.io/repos/github/Group4Layers/csv-types-js/badge.svg?branch=master)](https://coveralls.io/github/Group4Layers/csv-types-js?branch=master) [![Ebert](https://ebertapp.io/github/Group4Layers/csv-types-js.svg)](https://ebertapp.io/github/Group4Layers/csv-types-js) [![Inline Docs](https://inch-ci.org/github/Group4Layers/csv-types-js.svg)](https://inch-ci.org/github/Group4Layers/csv-types-js)
 
@@ -151,3 +151,3 @@ This library is commonly used with [FlexTable](https://github.com/Group4Layers/flextable) to facilitate the data manipulation produced by CSV Types (the data structure is consumed by FlexTable).
 ```js
-const CSV = require('csv-types');
+const CSV = require('csv-types').CSV;
 let lCSV = new CSV();
@@ -154,0 +154,0 @@ let results = lCSV.parse(`#type-a,col1,col2

src/index.js

@@ -0,2 +1,101 @@
+/**
+ * @file CSV Types.
+ * @author nozalr <[e-mail]> (Group4Layers®).
+ * @copyright 2017 nozalr (Group4Layers®).
+ * @license MIT
+ * @version 0.3.1
+ * @description
+ *
+ * This docs are generated from the source code, and therefore, they are concise and simple.
+ *
+ * **For a complete documentation full of examples, use cases, general overview and the most
+ * important points of the API, please, see the README.md in [csv-types-js](https://github.com/Group4Layers/csv-types-js)**.
+ */
+
+/**
+ * @typedef {Object} Options - Valid options to be configured.
+ * @prop {function} fail - function to fail (error is capturable).
+ * @prop {boolean} trim - trim space in value (headers are always trimmed).
+ * @prop {boolean} trimEscaped - trim s
+ * @prop {boolean} trimEscaped - trim space in those escaped values (eg. " a " to "a").
+ * @prop {boolean} types - use types (allows multiple definitions per string).
+ * @prop {boolean} headers - you can omit headers when used with no types (flexible values).
+ * @prop {boolean} firstLineHeader - headers are in the first not empty line (and not commented).
+ * @prop {char} delimiter - column character delimiter.
+ * @prop {char} escape - column escape character.
+ * @prop {char} comment - comment char (omits the line).
+ * @prop {(boolean|function)} cast - cast function for every value (by default false: no casting).
+ * @prop {(boolean|function)} row - row function for every row values.
+ * @description
+ *
+ * Options to be configured in CSV.
+ *
+ * By default:
+ *
+ * ```JavaScript
+ * const opts = {
+ *   fail: function(m){
+ *     console.log(m);
+ *     return {
+ *       fail: m,
+ *     };
+ *   },
+ *   trim: true,
+ *   trimEscaped: false,
+ *   types: false,
+ *   headers: true,
+ *   firstLineHeader: false,
+ *   delimiter: ',',
+ *   escape: '"',
+ *   comment: '#',
+ *   cast: false,
+ *   row: false,
+ * };
+ * ```
+ *
+ * If the cast function receives `true` it casts values that match the regexp `/^[-+]?[\d.]+$/` to numbers. Those that do not match are not casted, so, they are considered strings.
+ *
+ * The option `firstLineHeader` only works if `headers` is true.
+ *
+ * The option `headers` only works if `types` is false (because types needs headers always).
+ *
+ * The cast function receives this parameters:
+ * - `value` (`any`): the value (after the trimming, if applicable)
+ * - `isHeader` (`bool`): true if it is a header or not
+ * - `type` (`string`): type of the row (receives an empty string `''` if types are not used)
+ * - `column` (`int`): the column index starting from 0 (the first)
+ * - `row` (`int`): the row index starting from 0 (the first).
+ *
+ * And the value returned is inserted as the column value.
+ *
+ * ```js
+ * function cast(value, isHeader, type, column, row){
+ *   // the return value is used for this column
+ * }
+ * ```
+ *
+ * The row function is not called for the headers and it receives this parameters:
+ * - `value` (`any[]`): array of values
+ * - `type` (`string`): type of the row (receives `''` if no types)
+ * - `definition` (`Definition{}`): the global object with definitions (headers) and values so far
+ * - `row` (`int`): the row index starting from 0 (the first)
+ *
+ * And if `false` is returned, the row is not inserted in `values`.
+ *
+ * ```js
+ * function row(value, type, definition, row){
+ *   // if false is returned, the row is omitted
+ * }
+ * ```
+ */
+
+/**
+ * @private
+ * @type Options
+ */
 const defOpts = {
+  /**
+   * @param {string} m - message that shows the failing.
+   * @returns {any} Returned value from the capturable failing.
+   */
   fail: function(m){
@@ -20,6 +119,31 @@ console.log(m);
 
+
+/**
+ * Data structure produced by the parser (per values-headers found).
+ * @typedef {Object} Definition - Data structure.
+ * @prop {string[]} headers - can be empty if no headers.
+ * @prop {int} hlength - number of headers.
+ * @prop {any[]} values - can be empty if no values.
+ * @prop {int} vlength - number of values (rows).
+ */
+
+/**
+ * @class
+ * @see Options
+ * @see Definition
+ */
 class CSV {
+  /**
+   * Constructor. It accepts an Options object.
+   * @param {(Options|null)} cfg - Options to be configured.
+   * @see Options
+   */
   constructor(cfg){
     this.configure(cfg);
   }
+  /**
+   * Configure the options.
+   * @param {(Options|null)} cfg - Options to be configured.
+   * @see Options
+   */
   configure(cfg){
@@ -77,2 +201,9 @@ if (cfg == null){
   }
+  /**
+   * Parse the input string based on the options configured.
+   * @param {string} str - input string to be parsed (CSV string).
+   * @returns {Definition|any} Data structure produced (or return value from fail function).
+   * @see Definition
+   * @see Options
+   */
   parse(str){
@@ -347,2 +478,9 @@ let types = {};
 const casters = {
+  /**
+   * Number caster function. It returns a string or a number.
+   * It casts the string to a number if it matches this regexp: /^[-+]?[\d.]+$/.
+   * @param {string} value - value to be casted.
+   * @param {boolean} isHeader - the value comes from a header.
+   * @returns {(string|number)} Casted value.
+   */
   number: function(value, isHeader){
@@ -359,8 +497,19 @@ let ret = value;
 
-
-
+/**
+ * CSV Types module.
+ * @module csv-types
+ */
 module.exports = {
-  version: { major: 0, minor: 3, patch: 0 },
+  /**
+   * CSV Types version.
+   */
+  version: { major: 0, minor: 3, patch: 1 },
+  /**
+   * CSV class.
+   */
   CSV,
+  /**
+   * CSV Types casters (expose global casting functions).
+   */
   casters
 };

No alert changes

Improved metrics

Total package byte prevSize

41192

increased by15.61%

Lines of code

494

increased by42.36%

Worsened metrics

Dev dependency count

8

increased by60%

No dependency changes