@iebh/reflib v2.2.2

RefLib

Reference library processing for Node.

This library provides various read/write functionality to process citation libraries and handle individual references (henceforth "Refs").

This module forms part of the Systematic Review Accelerator

Compatibility

Notes on different formats:

• Medline seems to implement a totally different publication type system than others. RefLib will attempt to guess the best match, storing the original type in the medlineType key. Should the citation library be exported back to Medline / .nbib files this key will take precedence to avoid data loss

Reference Structure

RefLib creates a simple Plain-Old-JavaScript-Object (POJO) for each reference it parses, or writes to a file format when given a collection of the same.

Each reference has the following standardized fields, these are translated from whatever internal format each module uses - e.g. the TY RIS field is automatically translated to title.

Reference Types

As with refs the following ref types are supported and translated from the module internal formats.

aggregatedDatabase
ancientText
artwork
audioVisualMaterial
bill
blog
book
bookSection
case
catalog
chartOrTable
classicalWork
computerProgram
conferencePaper
conferenceProceedings
dataset
dictionary
editedBook
electronicArticle
electronicBook
electronicBookSection
encyclopedia
equation
figure
filmOrBroadcast
generic
governmentDocument
grant
hearing
journalArticle
legalRuleOrRegulation
magazineArticle
manuscript
map
music
newspaperArticle
onlineDatabase
onlineMultimedia
pamphlet
patent
personalCommunication
report
serial
standard
statute
thesis
unknown
unpublished
web

API

Each API is available either from the default reflib object or as a separate import.

import reflib from 'reflib'; // Import everything as `reflib`
reflib.readFile(path);
reflib.writeFile(path, refs);


import {readFile, writeFile} from 'reflib'; // Import specific functions
readFile(path);
writeFile(path, refs);

formats

Available: Node + Browser A lookup object of all supported citation library formats. Each key is the unique ID of that module.

Properties are:

identifyFormat(path)

Available: Node + Browser Attempt to determine the format of a file on disk from its path. The file does not need to actually exist.

identifyFormat('My Refs.csv') //= csv
identifyFormat('My Refs.json') //= json
identifyFormat('My Refs.nbib') //= nbib
identifyFormat('My Refs.txt.ris') //= ris
identifyFormat('MY REFS.TXT.RIS') //= ris
identifyFormat('My Refs.data.tsv') //= tsv
identifyFormat('My Refs.xml') //= endnoteXml

readFile(path, options)

Available: Node Read a file on disk, returning a Promise which will resolve with an array of all Refs extracted.

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:

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 Prompt the user for a file and process it into an array of citations.

reflib.uploadFile({ // Additional options
	file, // Optional File object if known, if omitted this function will prompt the user to select a file
	onStart, // Async function called as `(File)` when starting the read stage
	onProgress, // Function called as `(position, totalSize)` when processing the file
	onEnd, // Async function called as `()` when the read stage has completed
})
	.then(refs => /* Do something with Ref collection */)

writeFile(path, refs, options)

Available: Node Write a file back to disk, returning a Promise which will resolve when done.

reflib.writeFile('MyRefs.xml', refs);

readStream(moduleId, inputStream, options)

Available: Node + Browser Low level worker of readFile(). Accept an input Stream.Readable and return a emitter which will emit each Ref found.

reflib.readStream('json', createReadStream('./data/json/json1.json'))
	.on('end', ()=> /* Finished reading */)
	.on('error', err => /* Deal with errors */)
	.on('ref', ref => /* Do something with extracted Ref */)

writeStream(moduleId, outputStream, options)

Available: Node + Browser Low level worker of writeFile(). Return an object with methods to call to write to a given stream. The returned object will have a start(), end() and write(ref) function which can be called to write to the original input stream.

// Convert a JSON file to EndNoteXML via a stream
let output = reflib.writeStream('json', createWriteStream('./MyRefs.xml'));

output.start(); // Begin stream writing

reflib.readStream('json', createReadStream('./data/json/json1.json'))
	.on('ref', ref => output.write(ref))
	.on('end', ()=> output.end())

Credits

Developed for the Bond University Institute for Evidence-Based Healthcare. Please contact the author with any issues.