@iebh/reflib 2.8.0 → 2.8.1

package/.ignore

@@ -1 +1 @@
-test/data/
+test/data/

package/LICENSE

@@ -1,20 +1,20 @@
-The MIT License (MIT)
-
-Copyright (c) 2022 Bond University Institute for Evidence-Based Healthcare
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2022 Bond University Institute for Evidence-Based Healthcare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,297 +1,297 @@
-@IEBH/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](https://sr-accelerator.com)
-
-
-Compatibility
-=============
-
-| Library                | Extension(s)    | Read               | Write              |
-|------------------------|-----------------|--------------------|--------------------|
-| BibTeX                 | `.bib`          | :heavy_check_mark: | :heavy_check_mark: |
-| Comma Separated Values | `.csv`          | :x:                | :x:                |
-| EndNote ENL            | `.enl`          | :heavy_check_mark: | (untested)         |
-| EndNote ENLX           | `.enlx`         | :heavy_check_mark: | :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`          | :heavy_check_mark: | :heavy_check_mark: |
-| Tab Separated Values   | `.tsv`          | :x:                | :x:                |
-
-
-**Notes on different formats**:
-
-* Not all formats are one-to-one translations, some have differing field definitions or type definitions
-* BibTeX support is only provided for "well-formatted" files - i.e. correct use of newlines rather than one-single-line-per-ref, this is to avoid having to implement a full AST parser
-* Medline seems to implement a totally different [publication type system](https://www.nlm.nih.gov/mesh/pubtypes.html) 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
-
-
-Command Line Interface
-======================
-This NPM ships with a very basic Command Line Interface (CLI) for very basic Reflib files manipulation.
-
-```
-Usage: reflib -i INPUT_FILE [-f FORMAT] [-o -|OUTPUT_FILE]
-
-
--i, --input <file>             Input file to process
-
--o, --output <file>            Output file to save. Use '-' for STDOUT
-
--f, --format <reflib-format>   Override or set the file output type (if omitted the outfile filename
-                               is used to determine the format)
-
--v, --verbose                  Be verbose when processing
-
---version                      Print CLI version and exit
-
--h, --help                     This help screen
-```
-
-
-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](#reference-types) (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](https://support.nlm.nih.gov/knowledgebase/article/KA-03434/en-us), 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.
-
-
-```javascript
-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.
-
-```javascript
-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.
-
-```javascript
-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
-Prompt the user for a file and process it into an array of citations.
-
-```javascript
-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.
-
-```javascript
-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.
-
-```javascript
-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)` (optional `middle(ref)`) function which can be called to write to the original input stream.
-
-```javascript
-// 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](https://iebh.bond.edu.au).
-Please contact [the author](mailto:matt_carter@bond.edu.au) with any issues.
+@IEBH/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](https://sr-accelerator.com)
+
+
+Compatibility
+=============
+
+| Library                | Extension(s)    | Read               | Write              |
+|------------------------|-----------------|--------------------|--------------------|
+| BibTeX                 | `.bib`          | :heavy_check_mark: | :heavy_check_mark: |
+| Comma Separated Values | `.csv`          | :x:                | :x:                |
+| EndNote ENL            | `.enl`          | :heavy_check_mark: | (untested)         |
+| EndNote ENLX           | `.enlx`         | :heavy_check_mark: | :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`          | :heavy_check_mark: | :heavy_check_mark: |
+| Tab Separated Values   | `.tsv`          | :x:                | :x:                |
+
+
+**Notes on different formats**:
+
+* Not all formats are one-to-one translations, some have differing field definitions or type definitions
+* BibTeX support is only provided for "well-formatted" files - i.e. correct use of newlines rather than one-single-line-per-ref, this is to avoid having to implement a full AST parser
+* Medline seems to implement a totally different [publication type system](https://www.nlm.nih.gov/mesh/pubtypes.html) 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
+
+
+Command Line Interface
+======================
+This NPM ships with a very basic Command Line Interface (CLI) for very basic Reflib files manipulation.
+
+```
+Usage: reflib -i INPUT_FILE [-f FORMAT] [-o -|OUTPUT_FILE]
+
+
+-i, --input <file>             Input file to process
+
+-o, --output <file>            Output file to save. Use '-' for STDOUT
+
+-f, --format <reflib-format>   Override or set the file output type (if omitted the outfile filename
+                               is used to determine the format)
+
+-v, --verbose                  Be verbose when processing
+
+--version                      Print CLI version and exit
+
+-h, --help                     This help screen
+```
+
+
+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](#reference-types) (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](https://support.nlm.nih.gov/knowledgebase/article/KA-03434/en-us), 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.
+
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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
+Prompt the user for a file and process it into an array of citations.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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)` (optional `middle(ref)`) function which can be called to write to the original input stream.
+
+```javascript
+// 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](https://iebh.bond.edu.au).
+Please contact [the author](mailto:matt_carter@bond.edu.au) with any issues.