@iebh/reflib 2.4.2 → 2.4.4

package/lib/downloadFile.js

@@ -4,7 +4,7 @@ import {writeStream} from './writeStream.js';
 /**
 * Prompt the user for a file to save as and Write a given array of citations
 *
-* @param {Array<Ref>} Collection of references to write
+* @param {Array<ReflibRef>} refs Collection of references to write
 *
 * @param {Object} [options] Additional options when prompting the user
 * @param {String} [options.filename='References.xml'] The filename to download

package/lib/formats.js

@@ -5,7 +5,7 @@
 * @property {string} titleShort Shorter title of the format
 * @property {string} input Input format required by parser
 * @property {string} output Output format required by formatter
-* @property {array>string>} ext File extensions of this format, the first entry is generally used as the output default
+* @property {Array<String>} ext File extensions of this format, the first entry is generally used as the output default
 * @property {boolean} canRead Whether the format is supported when reading a citation library
 * @property {boolean} canWrite Whether the format is supported when writing a citation library
 */
@@ -46,7 +46,7 @@ export let formats = {
 		id: 'ris',
 		title: 'RIS',
 		titleShort: 'RIS',
-		ext: ['.ris','.txt'],
+		ext: ['.ris','.txt', '.cgi'],
 		canRead: true,
 		canWrite: true,
 	},

package/lib/getModule.js

@@ -4,10 +4,12 @@ let hasSetup = new Set(); // Modules we have already setup
 
 /**
 * Simple wrapper which loads the named module as a keyed lirary of functions
+*
 * @param {string} module The module ID as per `lib/formats.js`
 * @param {Object} [options] Additional options to use when fetching the module
 * @param {boolean} [options.setup=true] Call the `setup()` function on any module requested before use
-* @return {Object} The loaded module as an object of standardised functionality
+*
+* @returns {Object} The loaded module as an object of standardised functionality
 */
 export function getModule(module, options) {
 	// Sanity checking

package/lib/readFile.js

@@ -14,8 +14,8 @@ import {readStream} from './readStream.js';
 * @returns {Promise<Array>} An eventual array of all references parsed from the file
 * @property {EventEmitter} emitter An event emitter which will fire the below events
 *
-* @fires progress Emitted as `({readBytes: Number, totalSize: Number, refsFound: Number})`
-* @fires end Emitted as `({refsFound: Number})` when the reading operation has completed
+* @emits progress Emitted as `({readBytes: Number, totalSize: Number, refsFound: Number})`
+* @emits end Emitted as `({refsFound: Number})` when the reading operation has completed
 */
 export function readFile(path, options) {
 	let settings = {
@@ -28,7 +28,7 @@ export function readFile(path, options) {
 	let promiseEmitter = Promise.resolve()
 		.then(()=> stat(path))
 		.then(stats => new Promise((resolve, reject) => {
-			let refs = []; // eslint-disable-line no-unused-vars
+			let refs = [];
 
 			readStream(
 				module,

package/lib/uploadFile.js

@@ -10,7 +10,7 @@ import StreamEmitter from '../shared/streamEmitter.js';
 * @param {function} [options.onStart] Async function called as `(File)` when starting the read stage
 * @param {function} [options.onProgress] Function called as `(position, totalSize, refCount)` when processing the file
 * @param {function} [options.onEnd] Async function called as `()` when the read stage has completed
-* @param {*} [options.*] Additional settings to pass to `readStream()`
+* @param {...*} [options...] Additional settings to pass to `readStream()`
 * @returns {Promise} A promise which will resolve with an array of extracted citations
 */
 export function uploadFile(options) {

package/lib/writeFile.js

@@ -6,7 +6,7 @@ import {writeStream} from './writeStream.js';
 * Write a file to disk via the appropriate module
 *
 * @param {string} path The file path to write, the module to use will be determined from this
-* @param {Array<Ref>} Collection of references to write
+* @param {Array<ReflibRef>} refs Collection of references to write
 * @param {Object} [options] Additional options to pass to the file writer
 * @param {string} [options.module] The module to use if overriding from the file path
 *

package/modules/endnoteXml.js

@@ -5,7 +5,10 @@ import Emitter from '../shared/emitter.js';
 import { WritableStream as XMLParser } from 'htmlparser2/lib/WritableStream';
 
 /**
+* Read an EndnoteXML file, returning a stream analogue
 * @see modules/inhterface.js
+* @param {Stream} stream Stream primative to encapsulate
+* @returns {Object} A readable stream analogue defined in `modules/interface.js`
 */
 export function readStream(stream) {
 	let emitter = Emitter();
@@ -103,18 +106,14 @@ export function readStream(stream) {
 
 	// Queue up the parser in the next tick (so we can return the emitter first)
 	setTimeout(() => {
-
 		if (typeof stream.pipe === 'function') {
 			let parser = new XMLParser(parserOptions);
 			stream.on('data', ()=> emitter.emit('progress', stream.bytesRead))
 			stream.pipe(parser)
 			return;
-		}
-
-		else {
+		} else {
 			console.error('Error with stream, check "streamEmitter.js" if on browser')
 		}
-
 	})
 
 	return emitter;
@@ -123,11 +122,15 @@ export function readStream(stream) {
 
 /**
 * @see modules/interface.js
+*
+* @param {Stream} stream Writable stream to output to
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='journalArticle'] Default citation type to assume when no other type is specified
 * @param {string} [options.filePath="c:\\"] "Fake" internal source file path the citation library was exported from, must end with backslashes
 * @param {string} [options.fileName="EndNote.enl"] "Fake" internal source file name the citation library was exported from
 * @param {function} [options.formatDate] Date formatter to translate between a JS Date object and the EndNote YYYY-MM-DD format
+*
+* @returns {Object} A writable stream analogue defined in `modules/interface.js`
 */
 export function writeStream(stream, options) {
 	let settings = {

package/modules/interface.js

@@ -2,7 +2,7 @@
 * Generic module interface
 * This file serves no purpose other than to document the methods that each module can itself expose
 */
-/* eslint-disable no-unused-vars */
+/* eslint-disable jsdoc/require-returns-check, no-unused-vars */
 
 
 /**

package/modules/json.js

@@ -3,7 +3,12 @@ import Emitter from '../shared/emitter.js';
 import JSONStream from 'JSONStream';
 
 /**
+* Read a JSON stream and emit references
 * @see modules/interface.js
+*
+* @param {Stream} stream Stream primative to encapsulate
+*
+* @returns {Object} A readable stream analogue defined in `modules/interface.js`
 */
 export function readStream(stream) {
 	let recNumber = 1;
@@ -35,9 +40,15 @@ export function readStream(stream) {
 
 
 /**
+* Write to a stream object
+*
 * @see modules/interface.js
+*
+* @param {Steam} [stream] The stream to write to
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.lineSuffix='\n'] Optional line suffix for each output line of JSON
+*
+* @returns {Object} A writable stream analogue defined in `modules/interface.js`
 */
 export function writeStream(stream, options) {
 	let settings = {

package/modules/medline.js

@@ -1,7 +1,10 @@
 import Emitter from '../shared/emitter.js';
 
 /**
+* Read a Medline file as a stream
+*
 * @see modules/interface.js
+* @param {Stream} stream A readable stream analogue
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='journalArticle'] Default citation type to assume when no other type is specified
 * @param {string} [options.delimeter='\r'] How to split multi-line items
@@ -16,6 +19,8 @@ import Emitter from '../shared/emitter.js';
 * @param {string} options.fieldsReplace.to Field to copy/move the value to
 * @param {string} [options.fieldsReplace.delete=true] Whether to remove the orignal 'from' field if successful (i.e. reformat doesn't return false)
 * @param {function} [options.fieldsReplace.reformat] Optional function called as `(value, ref)` to provide the new field value. If return value is boolean `false` no action is taken
+*
+* @returns {Object} A readable stream analogue defined in `modules/interface.js`
 */
 export function readStream(stream, options) {
 	let settings = {
@@ -90,7 +95,7 @@ export function readStream(stream, options) {
 			from: 'medlineArticleID',
 			to: 'doi',
 			delete: false,
-			reformat: v => /(?<doi>[\w\.\/_]+) \[doi\]/.exec(v)?.groups.doi || false, // eslint-disable-line no-useless-escape
+			reformat: v => /(?<doi>[\w\.\/_]+) \[doi\]/.exec(v)?.groups.doi || false,
 		});
 
 	// Allow parsing of years
@@ -130,7 +135,7 @@ export function readStream(stream, options) {
 
 				let bufferSegment;
 
-				while (bufferSegment = bufferSplitter.exec(buffer)) { // eslint-disable-line no-cond-assign
+				while (bufferSegment = bufferSplitter.exec(buffer)) {
 					let parsedRef = parseRef(buffer.substring(bufferCrop, bufferSegment.index), settings); // Parse the ref from the start+end points
 					emitter.emit('ref', parsedRef);
 
@@ -156,10 +161,15 @@ export function readStream(stream, options) {
 
 
 /**
+* Write a Medline citation file to a stream
 * @see modules/interface.js
+*
+* @param {Stream} stream The stream to write to
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='journalArticle'] Default citation type to assume when no other type is specified
 * @param {string} [options.delimeter='\r'] How to split multi-line items
+*
+* @returns {Object} A writable stream analogue defined in `modules/interface.js`
 */
 export function writeStream(stream, options) {
 	let settings = {
@@ -220,8 +230,11 @@ export function writeStream(stream, options) {
 /**
 * Parse a single RIS format reference from a block of text
 * This function is used internally by parseStream() for each individual reference
+*
 * @param {string} refString Raw RIS string composing the start -> end of the ref
 * @param {Object} settings Additional settings to pass, this should be initialized + parsed by the calling function for efficiency, see readStream() for full spec
+*
+* @returns {ReflibRef} A single reference, parsed form the incoming string
 */
 export function parseRef(refString, settings) {
 	let ref = {}; // Reference under construction

package/modules/ris.js

@@ -1,10 +1,16 @@
 import Emitter from '../shared/emitter.js';
 
 /**
+* Parse a RIS file from a readable stream
+*
 * @see modules/interface.js
+*
+* @param {Stream} stream The readable stream to accept data from
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='report'] Default citation type to assume when no other type is specified
 * @param {string} [options.delimeter='\r'] How to split multi-line items
+*
+* @returns {Object} A readable stream analogue defined in `modules/interface.js`
 */
 export function readStream(stream, options) {
 	let settings = {
@@ -28,7 +34,7 @@ export function readStream(stream, options) {
 				let bufferSplitter = /(\r\n|\n)ER\s+-\s*(\r\n|\n)/g; // RegExp to use per segment (multiple calls to .exec() stores state because JS is a hellscape)
 
 				let bufferSegment;
-				while (bufferSegment = bufferSplitter.exec(buffer)) { // eslint-disable-line no-cond-assign
+				while (bufferSegment = bufferSplitter.exec(buffer)) {
 					let parsedRef = parseRef(buffer.substring(bufferCrop, bufferSegment.index), settings); // Parse the ref from the start+end points
 
 					emitter.emit('ref', parsedRef);
@@ -55,10 +61,17 @@ export function readStream(stream, options) {
 
 
 /**
+* Write a RIS file to a writable stream
+*
 * @see modules/interface.js
+*
+* @param {Stream} stream The writable stream to write to
+*
 * @param {Object} [options] Additional options to use when parsing
 * @param {string} [options.defaultType='journalArticle'] Default citation type to assume when no other type is specified
 * @param {string} [options.delimeter='\r'] How to split multi-line items
+*
+* @returns {Object} A writable stream analogue defined in `modules/interface.js`
 */
 export function writeStream(stream, options) {
 	let settings = {
@@ -116,8 +129,10 @@ export function writeStream(stream, options) {
 /**
 * Parse a single RIS format reference from a block of text
 * This function is used internally by parseStream() for each individual reference
+*
 * @param {string} refString Raw RIS string composing the start -> end of the ref
 * @param {Object} settings Additional settings to pass, this should be initialized + parsed by the calling function for efficiency, see readStream() for full spec
+* @returns {ReflibRef} The parsed reference
 */
 export function parseRef(refString, settings) {
 	let ref = {}; // Reference under construction

package/modules/shims/JSONStream-browser.js

@@ -16,13 +16,15 @@ export default class BrowserJSONStream {
 		try {
 			// Parse this.text as JSON
 			const jsonArray = JSON.parse(this.text);
+
 			// Free memory
 			this.text = '';
 
 			// For each entry in the json array (as ref):
-			jsonArray.forEach(ref => {
-				this.emitter.emit('data', ref);
-			});
+			if (Array.isArray(jsonArray))
+				jsonArray.forEach(ref => {
+					this.emitter.emit('data', ref);
+				});
 
 			// Finished
 			this.emitter.emit('end');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/reflib",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "Reference / Citation reference library utilities",
   "scripts": {
     "lint": "eslint .",
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/IEBH/Reflib"
+    "url": "git+https://github.com/IEBH/Reflib.git"
   },
   "keywords": [
     "reflib",

package/shared/camelCase.js

@@ -1,8 +1,9 @@
 /**
 * Camel case any input string
 * This is functionally the same as Lodash's camelCase() function
+*
 * @param {string} input The input string to camelize
-* @return {string} The input string in camelCase format
+* @returns {string} The input string in camelCase format
 * @url https://github.com/MomsFriendlyDevCo/Nodash
 */
 export default function(input) {

package/shared/emitter.js

@@ -3,6 +3,8 @@ import Mitt from 'mitt';
 /**
 * Generic wrapper for an event emitter
 * This module returns a wrapped version of `mitt` stand-alone event emitter (+ support for method chaining)
+*
+* @returns {Object} A wrapped version of the NPM Mitt event emitter with chainable functionality
 */
 export default function emitter() {
 	let emitter = Mitt();