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

| Library | Extension(s) | Read | Write | |------------------------|-----------------|--------------------|--------------------| | Comma Separated Values | .csv | :x: | :x: | | EndNote ENL | .enl | :x: | :x: | | EndNote ENLX | .enlx | :x: | :x: | | EndNote XML | .xml | :heavy_check_mark: | :heavy_check_mark: | | JSON | .json | :heavy_check_mark: | :heavy_check_mark: | | Medline | .nbib | :heavy_check_mark: | :heavy_check_mark: | | RIS | .ris / .txt | :heavy_check_mark: | :heavy_check_mark: | | Tab Separated Values | .tsv | :x: | :x: |

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.

| Field | Type | Description | |------------------|-----------------|----------------------------------------------------------------------------------------| | recNumber | number | The sorting number of the reference. Not present in RIS files | | type | string | A supported reference type (e.g. journalArticle) | | title | string | The reference's main title | | journal | string | The reference's secondary title, this is usually the journal for most published papers | | authors | array<string> | An array of each Author in the originally specified format | | date | string | The raw, internal date of the reference | | urls | array<string> | An array of each URL for the reference | | pages | string | The page reference, usually in the format 123-4 | | volume | string | | | number | string | | | isbn | string | | | abstract | string | | | label | string | | | caption | string | | | notes | string | | | address | string | | | researchNotes | string | | | keywords | array<string> | Optional list of keywords that apply to the reference | | accessDate | string | | | accession | string | Accession numbers spec, can sometimes be the PubMed ID | | doi | string | | | section | string | | | language | string | | | researchNotes | string | | | databaseProvider | string | | | database | string | | | workType | string | | | custom1 | string | | | custom2 | string | | | custom3 | string | | | custom4 | string | | | custom5 | string | | | custom6 | string | | | custom7 | string | |

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:

| Key | Type | Description | |--------------|-----------------|------------------------------------------------------------------------| | id | String | The unique ID of that module (same as object key) | | title | String | Longer, human readable title of the module | | titleShort | String | Shorter, human readable title of the module | | ext | Array<String> | Array of output file extensions, first extension should be the default | | canRead | boolean | Whether the format is supported when reading a citation library | | canWrite | boolean | Whether the format is supported when writing a citation library |

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.