@iebh/reflib 2.0.0

package/lib/uploadFile.js

@@ -0,0 +1,69 @@
+import {formats} from './formats.js';
+import {identifyFormat} from './identifyFormat.js';
+import {readStream} from './readStream.js';
+import StreamEmitter from '../shared/streamEmitter.js';
+
+/**
+* Prompt the user for a file then read it as a Reflib event emitter
+* @param {Object} [options] Additional options when prompting the user
+* @param {File} [options.files] The File object to process, omitting this will prompt the user to select a file
+* @param {function} [options.onStart] Async function called as `(File)` when starting the read stage
+* @param {function} [options.onProgress] Function called as `(position, totalSize)` 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()`
+* @returns {Promise} A promise which will resolve with an array of extracted citations
+*/
+export function uploadFile(options) {
+	let settings = {...options};
+
+	if (!settings.file) { // No file provided - prompt the user via the DOM
+		return new Promise(resolve => {
+			// Create hidden layer we will use to wrap the actual file upload input box
+			let fileWrapper = document.createElement('div');
+			fileWrapper.style.display = 'none';
+			document.body.appendChild(fileWrapper);
+
+			// Create upload input
+			let uploader = document.createElement('input');
+			uploader.type = 'file';
+			uploader.accept = Object.values(formats) // Allow only uploading supported file extensions
+				.flatMap(f => f.ext)
+				.join(',');
+
+			uploader.addEventListener('change', e => {
+				document.body.removeChild(fileWrapper);
+				resolve(uploadFile({
+					file: e.target.files[0],
+					...options,
+				}));
+			});
+			fileWrapper.appendChild(uploader);
+			uploader.dispatchEvent(new MouseEvent('click'));
+		});
+	} else { // Read the File object and return an emitter
+		if (!(settings.file instanceof File)) throw new Error('Expected "file" setting to uploadFile() to be a File type');
+		let identifiedType = identifyFormat(settings.file.name);
+		if (!identifiedType) throw new Error(`Unidenfified file format from filename "${settings.file.name}"`);
+
+		let refs = [];
+		return Promise.resolve()
+			.then(()=> settings.onStart && settings.onStart(settings.file))
+			.then(()=> new Promise((resolve, reject) => {
+				let streamer = readStream(
+					identifiedType.id,
+					StreamEmitter(settings.file.stream().getReader()),
+					{
+						...settings,
+						size: settings.file.size,
+					},
+				)
+					.on('end', ()=> resolve(refs))
+					.on('error', reject)
+					.on('ref', ref => refs.push(ref))
+
+				if (settings.onProgress) streamer.on('progress', settings.onProgress);
+			}))
+			.then(()=> settings.onEnd && settings.onEnd())
+			.then(()=> refs)
+	}
+}

package/lib/writeFile.js

@@ -0,0 +1,23 @@
+import {createWriteStream} from 'node:fs';
+import {identifyFormat} from './identifyFormat.js';
+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 {Object} [options] Additional options to pass to the file writer
+* @param {string} [options.module] The module to use if overriding from the file path
+* @returns {Promise} A promise which resolves when the operation has completed
+*/
+export function writeFile(path, refs, options) {
+	let format = options?.module || identifyFormat(path)?.id;
+	if (!format) throw new Error(`Unable to identify reference library format when saving file "${path}"`);
+
+	let writer = writeStream(format, createWriteStream(path), options);
+	return Promise.resolve()
+		.then(()=> writer.start())
+		.then(()=> refs.reduce((chain, ref) => // Write all refs as a series of promises
+			chain.then(()=> writer.write(ref))
+		, Promise.resolve()))
+		.then(()=> writer.end())
+}

package/lib/writeStream.js

@@ -0,0 +1,16 @@
+import {getModule} from './getModule.js';
+
+/**
+* Write an output stream via a given format ID
+* This function is really just a multiplexor around each modules `writeStream` export
+* @param {string} module The module ID as per `lib/formats.js`
+* @param {Stream.Writable} stream Output stream to write to
+* @param {Object} [options] Additional options to pass to the stream writer
+* @returns {Object} An object composed of `{start, write, end}` functions
+*/
+export function writeStream(module, stream, options) {
+	if (!module) throw new Error('No module provided to parse with');
+	if (!stream) throw new Error('No stream provided to parse');
+
+	return getModule(module).writeStream(stream, options);
+}

package/modules/default.js

@@ -0,0 +1,4 @@
+export * as json from './json.js';
+export * as endnoteXml from './endnoteXml.js';
+export * as medline from './medline.js';
+export * as ris from './ris.js';

package/modules/endnoteXml.js

@@ -0,0 +1,407 @@
+import camelCase from '../shared/camelCase.js';
+import Emitter from '../shared/emitter.js';
+import {WritableStream as XMLParser} from 'htmlparser2/lib/WritableStream.js';
+
+
+/**
+* @see modules/interface.js
+*/
+export function readStream(stream) {
+	let emitter = Emitter();
+
+	/**
+	* The current reference being appended to
+	* @type {Object}
+	*/
+	let ref = {};
+
+
+	/**
+	* Stack of nodes we are currently traversed into
+	* @type {array<Object>}
+	*/
+	let stack = [];
+
+
+	/**
+	* Whether to append incomming text blocks to the previous block
+	* This is necessary as XMLParser splits text into multiple calls so we need to know whether to append or treat this item as a continuation of the previous one
+	* @type {boolean}
+	*/
+	let textAppend = false;
+
+
+	// Queue up the parser in the next tick (so we can return the emitter first)
+	setTimeout(()=> {
+		let parser = new XMLParser({
+			xmlMode: true,
+			decodeEntities: false, // Handled below
+			onopentag(name, attrs) {
+				textAppend = false;
+				stack.push({
+					name: camelCase(name),
+					attrs,
+				});
+			},
+			onclosetag(name) {
+				if (name == 'record') {
+					if (ref.title) ref.title = ref.title // htmlparser2 handles the '<title>' tag in a really bizare way so we have to pull apart the <style> bits when parsing
+						.replace(/^.*<style.*>(.*)<\/style>.*$/m, '$1')
+						.replace(/^\s+/, '')
+						.replace(/\s+$/, '')
+					emitter.emit('ref', translateRawToRef(ref));
+					stack = []; // Trash entire stack when hitting end of <record/> node
+					ref = {}; // Reset the ref state
+				} else {
+					stack.pop();
+				}
+			},
+			ontext(text) {
+				let parentName = stack[stack.length - 1]?.name;
+				let gParentName = stack[stack.length - 2]?.name;
+				if (parentName == 'title') {
+					if (textAppend) {
+						ref.title += text;
+					} else {
+						ref.title = text;
+					}
+				} else if (parentName == 'style' && gParentName == 'author') {
+					if (!ref.authors) ref.authors = [];
+					if (textAppend) {
+						ref.authors[ref.authors.length - 1] += xmlUnescape(text);
+					} else {
+						ref.authors.push(xmlUnescape(text));
+					}
+				} else if (parentName == 'style' && gParentName == 'keyword') {
+					if (!ref.keywords) ref.keywords = [];
+					if (textAppend) {
+						ref.keywords[ref.keywords.length - 1] += xmlUnescape(text);
+					} else {
+						ref.keywords.push(xmlUnescape(text));
+					}
+				} else if (parentName == 'style') { // Text within <style/> tag
+					if (textAppend || ref[gParentName]) { // Text already exists? Append (handles node-expats silly multi-text per escape character "feature")
+						ref[gParentName] += xmlUnescape(text);
+					} else {
+						ref[gParentName] = xmlUnescape(text);
+					}
+				} else if (['recNumber', 'refType'].includes(parentName)) { // Simple setters like <rec-number/>
+					if (textAppend || ref[parentName]) {
+						ref[parentName] += xmlUnescape(text);
+					} else {
+						ref[parentName] = xmlUnescape(text);
+					}
+				}
+				textAppend = true; // Always set the next call to the text emitter handler as an append operation
+			},
+		})
+
+		stream.pipe(parser)
+			.on('finish', ()=> emitter.emit('end'))
+	});
+
+	return emitter;
+}
+
+
+/**
+* @see modules/interface.js
+* @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 lirary was exported from, must end with backslashes
+* @param {string} [options.fileName="EndNote.enl"] "Fake" internal source file name the citation lirary was exported from
+* @param {function} [options.formatDate] Date formatter to translate between a JS Date object and the EndNote YYYY-MM-DD format
+*/
+export function writeStream(stream, options) {
+	let settings = {
+		defaultType: 'journalArticle',
+		filePath: 'c:\\',
+		fileName: 'EndNote.enl',
+		formatDate: value => value instanceof Date ? value.toISOString().substr(0, 10) : value,
+		...options,
+	};
+
+	// Cached values so we don't need to keep recomputing
+	let encodedName = xmlEscape(settings.fileName);
+	let refsSeen = 0;
+
+	return {
+		start: ()=> {
+			stream.write('<?xml version="1.0" encoding="UTF-8" ?><xml><records>');
+			return Promise.resolve();
+		},
+		write: ref => {
+			let refType = translations.types.rlMap.get(ref.type || settings.defaultType);
+			if (!refType) throw new Error(`Invalid reference type: "${ref.type}"`);
+
+			refsSeen++;
+			let recNumber = ref.recNumber || refsSeen;
+
+			stream.write(
+				'<record>'
+					// Preamble
+					+ `<database name="${settings.fileName}" path="${settings.filePath}${settings.fileName}">${encodedName}</database>`
+					+ `<source-app name="EndNote" version="16.0">EndNote</source-app>`
+					+ `<rec-number>${recNumber}</rec-number>`
+					+ `<foreign-keys><key app="EN" db-id="s55prpsswfsepue0xz25pxai2p909xtzszzv">${recNumber}</key></foreign-keys>`
+
+					// Type
+					+ `<ref-type name="${refType.rawText}">${refType.rawId}</ref-type>`
+
+					// Authors
+					+ '<contributors><authors>'
+						+ (ref.authors || []).map(author => `<author><style face="normal" font="default" size="100%">${xmlEscape(author)}</style></author>`)
+					+ '</authors></contributors>'
+
+					// Titles
+					+ '<titles>'
+						+ (ref.title ? `<title><style face="normal" font="default" size="100%">${xmlEscape(ref.title)}</style></title>` : '')
+						+ (ref.journal ? `<secondary-title><style face="normal" font="default" size="100%">${xmlEscape(ref.journal)}</style></secondary-title>` : '')
+						+ (ref.titleShort ? `<short-title><style face="normal" font="default" size="100%">${xmlEscape(ref.titleShort)}</style></short-title>` : '')
+						+ (ref.journalAlt ? `<alt-title><style face="normal" font="default" size="100%">${xmlEscape(ref.journalAlt)}</style></alt-title>` : '')
+					+ '</titles>'
+
+					// Periodical
+					+ (ref.periodical ? `<periodical><full-title><style face="normal" font="default" size="100%">${xmlEscape(ref.periodical)}</style></full-title></periodical>` : '')
+
+					// Simple field key/vals
+					+ [
+						['abstract', 'abstract'],
+						['accessDate', 'access-date'],
+						['accession', 'accession-num'],
+						['address', 'auth-address'],
+						['caption', 'caption'],
+						['databaseProvider', 'remote-database-provider'],
+						['database', 'remote-database-name'],
+						['doi', 'electronic-resource-num'],
+						['isbn', 'isbn'],
+						['label', 'label'],
+						['language', 'language'],
+						['notes', 'notes'],
+						['number', 'number'],
+						['pages', 'pages'],
+						['researchNotes', 'research-notes'],
+						['section', 'section'],
+						['volume', 'volume'],
+						['workType', 'work-type'],
+						['custom1', 'custom1'],
+						['custom2', 'custom2'],
+						['custom3', 'custom3'],
+						['custom4', 'custom4'],
+						['custom5', 'custom5'],
+						['custom6', 'custom6'],
+						['custom7', 'custom7'],
+					]
+						.filter(([rlKey]) => ref[rlKey]) // Remove empty fields
+						.map(([rlKey, rawKey]) =>
+							`<${rawKey}><style face="normal" font="default" size="100%">${xmlEscape(ref[rlKey])}</style></${rawKey}>`
+						)
+						.join('')
+
+					// Dates
+					+ (
+						ref.date && ref.year && ref.date instanceof Date ?
+							`<dates><year><style face="normal" font="default" size="100%">${xmlEscape(ref.year)}</style></year>`
+							+ `<pub-dates><date><style face="normal" font="default" size="100%">${settings.formatDate(ref.date)}</style></date></pub-dates></dates>`
+						: ref.date && ref.year ?
+							`<dates><year><style face="normal" font="default" size="100%">${xmlEscape(ref.year)}</style></year>`
+							+ `<pub-dates><date><style face="normal" font="default" size="100%">${ref.date}</style></date></pub-dates></dates>`
+						: ref.date ?
+							`<dates><pub-dates><date><style face="normal" font="default" size="100%">${xmlEscape(ref.date)}</style></date></pub-dates></dates>`
+						: ref.year ?
+							`<dates><year><style face="normal" font="default" size="100%">${xmlEscape(ref.year)}</style></year></dates>`
+						: ''
+					)
+
+					// Urls
+					+ (ref.urls ?
+						'<urls><related-urls>'
+						+ (ref.urls || [])
+							.map(url => `<url><style face="normal" font="default" size="100%">${xmlEscape(url)}</style></url>`)
+							.join('')
+						+ '</related-urls></urls>'
+					: '')
+
+					// Keywords
+					+ (ref.keywords ?
+						'<keywords>'
+						+ (ref.keywords || [])
+							.map(keyword => `<keyword><style face="normal" font="default" size="100%">${xmlEscape(keyword)}</style></keyword>`)
+							.join('')
+						+ '</keywords>'
+					: '')
+
+				+ '</record>'
+			);
+			return Promise.resolve();
+		},
+		end: ()=> {
+			stream.write('</records></xml>');
+			return new Promise((resolve, reject) =>
+				stream.end(err => err ? reject(err) : resolve())
+			);
+		},
+	};
+}
+
+
+/**
+* Utility function to take the raw XML output object and translate it into a RefLib object
+* @param {Object} xRef Raw XML object to process
+* @returns {Object} The translated RefLib object output
+*/
+export function translateRawToRef(xRef) {
+	let recOut = {
+		...Object.fromEntries(
+			translations.fields.collection
+				.filter(field => xRef[field.raw]) // Only include fields we have a value for
+				.map(field => [ field.rl, xRef[field.raw] ]) // Translate Raw -> Reflib spec
+		),
+		type: translations.types.rawMap.get(+xRef.refType || 17)?.rl,
+	};
+
+	return recOut;
+}
+
+
+/**
+* Default string -> XML encoder
+* @param {string} str The input string to encode
+* @returns {string} The XML "safe" string
+*/
+export function xmlEscape(str) {
+	return ('' + str)
+		.replace(/&/g, '&amp;')
+		.replace(/\r/g, '&#xD;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;');
+}
+
+
+/**
+* Default XML -> string decodeer
+* @param {string} str The input string to decode
+* @returns {string} The actual string
+*/
+export function xmlUnescape(str) {
+	return ('' + str)
+		.replace(/\&amp;/g, '&')
+		.replace(/\&#xD;/g, '\r')
+		.replace(/\&lt;/g, '<')
+		.replace(/\&gt;/g, '>')
+		.replace(/\&quot;/g, '"')
+		.replace(/\&apos;/g, "'");
+}
+
+
+/**
+* Lookup tables for this module
+* @type {Object}
+* @property {array<Object>} fields Field translations between RefLib (`rl`) and the raw format (`raw`)
+* @property {array<Object>} types Field translations between RefLib (`rl`) and the raw format types as raw text (`rawText`) and numeric ID (`rawId`)
+*/
+export let translations = {
+	// Field translations {{{
+	fields: {
+		collection: [
+			{rl: 'recNumber', raw: 'recNumber'},
+			{rl: 'title', raw: 'title'},
+			{rl: 'journal', raw: 'secondaryTitle'},
+			{rl: 'address', raw: 'authAddress'},
+			{rl: 'researchNotes', raw: 'researchNotes'},
+			{rl: 'type', raw: 'FIXME'},
+			{rl: 'authors', raw: 'authors'},
+			{rl: 'pages', raw: 'pages'},
+			{rl: 'volume', raw: 'volume'},
+			{rl: 'number', raw: 'number'},
+			{rl: 'isbn', raw: 'isbn'},
+			{rl: 'abstract', raw: 'abstract'},
+			{rl: 'label', raw: 'label'},
+			{rl: 'caption', raw: 'caption'},
+			{rl: 'notes', raw: 'notes'},
+			{rl: 'custom1', raw: 'custom1'},
+			{rl: 'custom2', raw: 'custom2'},
+			{rl: 'custom3', raw: 'custom3'},
+			{rl: 'custom4', raw: 'custom4'},
+			{rl: 'custom5', raw: 'custom5'},
+			{rl: 'custom6', raw: 'custom6'},
+			{rl: 'custom7', raw: 'custom7'},
+			{rl: 'doi', raw: 'electronicResourceNum'},
+			{rl: 'year', raw: 'year'},
+			{rl: 'date', raw: 'date'},
+			{rl: 'keywords', raw: 'keywords'},
+			{rl: 'urls', raw: 'urls'},
+		],
+	},
+	// }}}
+	// Ref type translations {{{
+	types: {
+		collection: [
+			{rl: 'aggregatedDatabase', rawText: 'Aggregated Database', rawId: 55},
+			{rl: 'ancientText', rawText: 'Ancient Text', rawId: 51},
+			{rl: 'artwork', rawText: 'Artwork', rawId: 2},
+			{rl: 'audioVisualMaterial', rawText: 'Audiovisual Material', rawId: 3},
+			{rl: 'bill', rawText: 'Bill', rawId: 4},
+			{rl: 'blog', rawText: 'Blog', rawId: 56},
+			{rl: 'book', rawText: 'Book', rawId: 6},
+			{rl: 'bookSection', rawText: 'Book Section', rawId: 5},
+			{rl: 'case', rawText: 'Case', rawId: 7},
+			{rl: 'catalog', rawText: 'Catalog', rawId: 8},
+			{rl: 'chartOrTable', rawText: 'Chart or Table', rawId: 38},
+			{rl: 'classicalWork', rawText: 'Classical Work', rawId: 49},
+			{rl: 'computerProgram', rawText: 'Computer Program', rawId: 9},
+			{rl: 'conferencePaper', rawText: 'Conference Paper', rawId: 47},
+			{rl: 'conferenceProceedings', rawText: 'Conference Proceedings', rawId: 10},
+			{rl: 'dataset', rawText: 'Dataset', rawId: 59},
+			{rl: 'dictionary', rawText: 'Dictionary', rawId: 52},
+			{rl: 'editedBook', rawText: 'Edited Book', rawId: 28},
+			{rl: 'electronicArticle', rawText: 'Electronic Article', rawId: 43},
+			{rl: 'electronicBook', rawText: 'Electronic Book', rawId: 44},
+			{rl: 'electronicBookSection', rawText: 'Electronic Book Section', rawId: 60},
+			{rl: 'encyclopedia', rawText: 'Encyclopedia', rawId: 53},
+			{rl: 'equation', rawText: 'Equation', rawId: 39},
+			{rl: 'figure', rawText: 'Figure', rawId: 37},
+			{rl: 'filmOrBroadcast', rawText: 'Film or Broadcast', rawId: 21},
+			{rl: 'generic', rawText: 'Generic', rawId: 13},
+			{rl: 'governmentDocument', rawText: 'Government Document', rawId: 46},
+			{rl: 'grant', rawText: 'Grant', rawId: 54},
+			{rl: 'hearing', rawText: 'Hearing', rawId: 14},
+			{rl: 'journalArticle', rawText: 'Journal Article', rawId: 17},
+			{rl: 'legalRuleOrRegulation', rawText:', Legal Rule or Regulation', rawId: 50},
+			{rl: 'magazineArticle', rawText: 'Magazine Article', rawId: 19},
+			{rl: 'manuscript', rawText: 'Manuscript', rawId: 36},
+			{rl: 'map', rawText: 'Map', rawId: 20},
+			{rl: 'music', rawText: 'Music', rawId: 61},
+			{rl: 'newspaperArticle', rawText: 'Newspaper Article', rawId: 23},
+			{rl: 'onlineDatabase', rawText: 'Online Database', rawId: 45},
+			{rl: 'onlineMultimedia', rawText: 'Online Multimedia', rawId: 48},
+			{rl: 'pamphlet', rawText: 'Pamphlet', rawId: 24},
+			{rl: 'patent', rawText: 'Patent', rawId: 25},
+			{rl: 'personalCommunication', rawText: 'Personal Communication', rawId: 26},
+			{rl: 'report', rawText: 'Report', rawId: 27},
+			{rl: 'serial', rawText: 'Serial', rawId: 57},
+			{rl: 'standard', rawText: 'Standard', rawId: 58},
+			{rl: 'statute', rawText: 'Statute', rawId: 31},
+			{rl: 'thesis', rawText: 'Thesis', rawId: 32},
+			{rl: 'unpublished', rawText: 'Unpublished Work', rawId: 34},
+			{rl: 'web', rawText: 'Web Page', rawId: 12},
+		],
+		rlMap: new Map(), // Calculated later for quicker lookup
+		rawMap: new Map(), // Calculated later for quicker lookup
+	},
+	// }}}
+};
+
+
+/**
+* @see modules/interface.js
+*/
+export function setup() {
+	// Create lookup object of translations.types with key as .rl / val as the full object
+	translations.types.collection.forEach(c => {
+		translations.types.rlMap.set(c.rl, c);
+		translations.types.rawMap.set(c.rawId, c);
+	});
+}

package/modules/interface.js

@@ -0,0 +1,45 @@
+/**
+* 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 */
+
+
+/**
+* Provide the low-level function for a module to read a stream and emit refs
+* @param {stream.Readable} stream Input stream to read from
+* @param {Object} [options] Additional options to use when parsing
+* @returns {EventEmitter} EventEmitter(-like) that should emit the below events
+*
+* @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
+*/
+export function readStream(stream, options) {
+	// Stub
+}
+
+
+/**
+* Provide the low-level function for a module to write a stream
+* @param {stream.Writable} stream Output stream to write to
+* @param {array<Object>} refs Collection of refs to write
+* @param {Object} [options] Additional options to use when writing
+*
+* @returns {Object} An object which exposes methods to call to start, write and end the writing process. All methods MUST return a Promise
+* @property {function<Promise>} start Function to call when beginning to write
+* @property {function<Promise>} write Function called as `(ref)` when writing a single ref
+* @property {function<Promise>} end Function to call when finishing writing, must resolve its Promise when the stream has closed successfully
+*/
+export function writeStream(stream, refs, options) {
+	// Stub
+}
+
+
+/**
+* Function to run to set up any additional data before the module is needed
+* This is generally used by worker functions which construct maps from collections for efficiency purposes
+*/
+export function setup() {
+	// Stub
+}

package/modules/json.js

@@ -0,0 +1,59 @@
+import Emitter from '../shared/emitter.js';
+import JSONStream from 'JSONStream';
+
+/**
+* @see modules/interface.js
+*/
+export function readStream(stream) {
+	let recNumber = 1;
+	let emitter = Emitter();
+
+	// Queue up the parser in the next tick (so we can return the emitter first)
+	setTimeout(()=>
+		stream.pipe(
+			JSONStream.parse('*')
+				.on('data', ref => emitter.emit('ref', {
+					recNumber: recNumber++,
+					...ref,
+				}))
+				.on('end', ()=> emitter.emit('end'))
+				.on('error', emitter.emit.bind('error'))
+		)
+	);
+
+	return emitter;
+}
+
+
+/**
+* @see modules/interface.js
+* @param {Object} [options] Additional options to use when parsing
+* @param {string} [options.lineSuffix='\n'] Optional line suffix for each output line of JSON
+*/
+export function writeStream(stream, options) {
+	let settings = {
+		lineSuffix: '\n',
+		...options,
+	};
+
+	let lastRef; // Hold last refrence string in memory so we know when we've reached the end (last item shoulnd't have a closing comma)
+
+	return {
+		start: ()=> {
+			stream.write('[\n');
+			return Promise.resolve();
+		},
+		write: ref => {
+			if (lastRef) stream.write(lastRef + ',' + settings.lineSuffix); // Flush last reference to disk with comma
+			lastRef = JSON.stringify(ref);
+			return Promise.resolve();
+		},
+		end: ()=> {
+			if (lastRef) stream.write(lastRef + settings.lineSuffix); // Flush final reference to disk without final comma
+			stream.write(']');
+			return new Promise((resolve, reject) =>
+				stream.end(err => err ? reject(err) : resolve())
+			);
+		},
+	};
+}