@iebh/reflib 2.0.5 → 2.1.0

package/README.md

@@ -193,6 +193,19 @@ reflib.readFile('./data/json/json1.json')
 	.then(refs => /* Do something with Ref collection */)
 ```
 
+An emitter is available to track progress while reading. Note that due to the chainable nature of promises the first return contains the `emitter` key only:
+
+```javascript
+let reader = reflib.readFile('./data/json/json1.json');
+
+reader.emitter
+	.on('progress', ({readBytes, totalSize, refsFound}) => /* Report progress somehow */);
+	.on('end', ({refsFound}) => /* Report progress somehow */);
+
+reader
+	.then(refs => /* Do something with Ref collection */)
+```
+
 uploadFile(options)
 ===================
 Available: Browser
@@ -257,12 +270,3 @@ Credits
 =======
 Developed for the [Bond University Institute for Evidence-Based Healthcare](https://iebh.bond.edu.au).
 Please contact [the author](mailto:matt_carter@bond.edu.au) with any issues.
-
-
-TODO
-====
-- [x] Basic parsing iterfaces
-- [ ] "progress" emitter for files
-- [x] `.uploadFile()` browser compatibility
-- [ ] `.downloadFile()` browser compatibility
-- [x] `setup()` functions per module to avoid things like map calculations unless the module is actually needed

package/lib/readFile.js

@@ -1,4 +1,5 @@
 import {createReadStream} from 'node:fs';
+import Emitter from '../shared/emitter.js';
 import {stat} from 'node:fs/promises';
 import {identifyFormat} from './identifyFormat.js';
 import {readStream} from './readStream.js';
@@ -9,16 +10,26 @@ import {readStream} from './readStream.js';
 * @param {string} path The file path to parse
 * @param {Object} [options] Additional options to pass to the parser
 * @param {string} [options.module] The module to use if overriding from the file path
+*
 * @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
 */
 export function readFile(path, options) {
-	let settings = {...options};
+	let settings = {
+		progressTotal: false,
+		...options,
+	};
 	let module = options?.module || identifyFormat(path)?.id;
 	if (!module) throw new Error(`Unable to identify reference library format for file path "${path}"`);
 
-	return stat(path)
+	let promiseEmitter = Promise.resolve()
+		.then(()=> stat(path))
 		.then(stats => new Promise((resolve, reject) => {
-			let refs = [];
+			let refs = []; // eslint-disable-line no-unused-vars
+
 			readStream(
 				module,
 				createReadStream(path),
@@ -30,5 +41,23 @@ export function readFile(path, options) {
 				.on('end', ()=> resolve(refs))
 				.on('error', reject)
 				.on('ref', ref => refs.push(ref))
+				.on('progress', readBytes => promiseEmitter.emitter.emit('progress', {
+					readBytes,
+					totalSize: stats.size,
+					refsFound: refs.length,
+				}))
 		}))
+		.then(refs => {
+			promiseEmitter.emitter.emit('end', {refsFound: refs.length})
+			return refs;
+		})
+
+	// Extend our base promise with an emitter subkey
+	return Object.defineProperties(promiseEmitter, {
+		emitter: {
+			value: Emitter(),
+			enumerable: true,
+			writable: false,
+		},
+	});
 }

package/modules/endnoteXml.js

@@ -108,6 +108,7 @@ export function readStream(stream) {
 		if (typeof stream.pipe === 'function') {
 			// We are on the node.js client
 			let parser = new XMLParser(parserOptions);
+			stream.on('data', ()=> emitter.emit('progress', stream.bytesRead))
 			stream.pipe(parser)
 			return;
 		}

package/modules/interface.js

@@ -14,6 +14,7 @@
 * @emits ref Emitted with a single ref object when found
 * @emits end Emitted when parsing has completed
 * @emits error Emitted when an error has been raised
+* @emits progress Emitted as (bytesRead) when reading a stream
 */
 export function readStream(stream, options) {
 	// Stub

package/modules/json.js

@@ -9,7 +9,8 @@ export function readStream(stream) {
 	let emitter = Emitter();
 
 	// Queue up the parser in the next tick (so we can return the emitter first)
-	setTimeout(()=>
+	setTimeout(()=> {
+		stream.on('data', ()=> emitter.emit('progress', stream.bytesRead));
 		stream.pipe(
 			JSONStream.parse('*')
 				.on('data', ref => emitter.emit('ref', {
@@ -19,7 +20,7 @@ export function readStream(stream) {
 				.on('end', ()=> emitter.emit('end'))
 				.on('error', emitter.emit.bind('error'))
 		)
-	);
+	});
 
 	return emitter;
 }

package/modules/medline.js

@@ -122,6 +122,7 @@ export function readStream(stream, options) {
 	setTimeout(()=> {
 		stream
 			.on('data', chunkBuffer => {
+				emitter.emit('progress', stream.bytesRead);
 				buffer += chunkBuffer.toString(); // Append incomming data to the partial-buffer we're holding in memory
 
 				let bufferCrop = 0; // How many bytes to shift off the front of the buffer based on the last full reference we saw, should end up at the last byte offset of buffer that is valid to shift-truncate to

package/modules/ris.js

@@ -21,6 +21,7 @@ export function readStream(stream, options) {
 	setTimeout(()=> {
 		stream
 			.on('data', chunkBuffer => {
+				emitter.emit('progress', stream.bytesRead);
 				buffer += chunkBuffer.toString(); // Append incomming data to the partial-buffer we're holding in memory
 
 				let bufferCrop = 0; // How many bytes to shift off the front of the buffer based on the last full reference we saw, should end up at the last byte offset of buffer that is valid to shift-truncate to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iebh/reflib",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "Reference / Citation reference library utilities",
   "scripts": {
     "lint": "eslint lib modules shared test",