https://github.com/awoken-bible/reference
NPM package for bible verse reference parsing, formating and meta data
https://github.com/awoken-bible/reference
bible-verse-references npm-package parser
Last synced: 10 months ago
JSON representation
NPM package for bible verse reference parsing, formating and meta data
- Host: GitHub
- URL: https://github.com/awoken-bible/reference
- Owner: awoken-bible
- License: mit
- Created: 2019-09-09T19:09:42.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-01-23T13:28:36.000Z (about 2 years ago)
- Last Synced: 2025-04-18T16:49:51.622Z (10 months ago)
- Topics: bible-verse-references, npm-package, parser
- Language: JavaScript
- Homepage:
- Size: 1.7 MB
- Stars: 11
- Watchers: 1
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.yaml
- License: LICENSE
Awesome Lists containing this project
README
# Awoken Bible Reference [](https://travis-ci.org/awoken-bible/reference) [](https://coveralls.io/github/awoken-bible/reference?branch=master)
_Bible verse reference parsing, formating and manipulation_
[Click for public API reference docs](https://awoken-bible.github.io/reference/index.html).
## Quick Start Guide
### Node JS
To use the default versification scheme, simple import the libary and use the global [API functions](https://awoken-bible.github.io/reference/index.html).
```typescript
import AwokenRef from 'awoken-bible-reference';
let vref = AwokenRef.parseOrThrow('Genesis 1');
if(AwokenRef.countVerses(vref) > 10)){
vref = AwokenRef.firstNVerses(vref, 10);
}
vref = AwokenRef.getIntersection(vref, AwokenRef.parseOrThrow('GEN 1 v6,9-20'));
// Print as human readable verse reference (IE: "Genesis 1:6,9-10")
console.log(AwokenRef.format(vref));
// Print as url encodable reference (IE: "gen1v6,9-10")
console.log(AwokenRef.format(vref, { url: true }));
// Inspect the object, will yield:
// [ { book: 'GEN', chapter: 1, verse: 6 },
// { is_range : true,
// start : { book: 'GEN', chapter: 1, verse: 9 },
// end : { book: 'GEN', chapter: 1, verse: 10 },
// }
// ]
console.dir(vref);
```
Non-standard versification schemes can be used by instead creating an instance of the library. This allows support to be added for the Apocrypha, or translations that use a different split of verses per chapter.
```typescript
import __AwokenRef__ from 'awoken-bible-reference';
const AwokenRef = new __AwokenRef__(my_versificaton);
let vref = AwokenRef.parse('MyBook 100:999');
```
The full list of methods on the `AwokenRef` object can be found in the [API docs](https://awoken-bible.github.io/reference/index.html).
### Browser
If using plain javascript in the browser with no build-system to bundle your dependencies, you may simply reference the file found in `./dist.browser/awoken-ref.js`.
This will create a global "AwokenRef` variable, which can be used as both an instance of the library, and a constructor to create new instances with non-default versification schemes.
```html
var refs = AwokenRef.parseOrThrow('Tobit 1.1'); // error!
var lib = new AwokenRef(myCustomVersificationWithApocrytha);
var myRefs = lib.parseOrThrow('Tobit 1.1'); // success!
```
# Type Representations
## Bible Verses
`awoken-bible-reference` can represent (and convert between) the following representations of a Bible verse:
What
Typescript Type
Example 1
Example 2
Human readable string
string
Genesis 1:1
Revelation 22:21
Verse Index
number
0
33021
JSON
```typescript
interface BibleVerse {
book : string,
chapter : number,
verse : number,
}
```
```json
{
"book" : "GEN",
"chapter" : 1,
"verse" : 1,
}
```
```json
{
"book" : "REV",
"chapter" : 22,
"verse" : 21,
}
```
> Note that the verse index representation should be avoided unless you are sure that all translations you care about utalize the exact same [versification scheme](https://en.wikipedia.org/wiki/Chapters_and_verses_of_the_Bible). While it is useful for assigning unique IDs and computing offsets etc, it should probably not be used as a portable data exchange format.
The `book` field is always a 3 character mix of upper case letters and digits, as per the [USFM specification](https://ubsicap.github.io/usfm/identification/books.html).
## BibleRanges
BibleRanges are represented by an object of the form:
```typescript
/** Representation of continous block of verses */
interface BibleRange {
is_range : true,
start : BibleVerse,
end : BibleVerse,
};
```
## Mixed Sets
Note that most API function can take either `BibleRange` or `BibleVerse` objects (or lists thereof), and thus the `is_range` field can be used to easily distinguish the types from one another.
The following union type is also exported for convenience:
```typescript
/** Generic reference to verse or range */
type BibleRef = BibleVerse | BibleRange;
```
# Overview of Functionality
API methods include functionality to:
- Parse partial references, ranges, and comma separated lists there of:
- `Genesis 1:1-10,12, 2:14`
- `EXO 3:1 - DEU 4:1`
- `Matt 1; Luke3.16; Mark 1 v 2-3,5`
- Generate verbose human readable reference strings, and compact URL encodable equivalents
- `Genesis 10 v6-10` vs `gen10v6-10`
- `Song of Solomon` vs `sng`
- Validate and fix references, including out of range chapters and verses, and inverted ranges:
- `validate({book: 'GEN', chapter: 51, verse: 1})`
becomes
`{ message: "Genesis has only 50 chapters", got: 51, max_value: 50, ... }`
- `fixErrors({book: 'GEN', chapter: 51, verse: 1})`
becomes
`{book: 'GEN', chapter: 50, verse: 26}`
- Sorting a list of references
- Counting the number of verses in a list of `BibleRef` instances
- Iterating/Splitting by book/chapter/verse
- Truncating a list of `BibleRef`s to contain only the first N verses (useful for pagination, or short previews of a longer text)
- Combining/Simplifying ranges, as well as finding the intersection/union of ranges
For a full list of the exported functions and data types, see the [generated typedoc API reference](https://awoken-bible.github.io/reference/index.html).
# Build Targets
The published copy of this library multiple output targets. Node.js projects should autoload the correct version, and there also exists a browser bundle.
- `dist/awoken-ref.cjs.js` - CommonJS module loadable via require() in nodejs project - built via esbuild
- `dist/awoken-ref.esm.mjs` - ESModule loadable via import() in nodejs type=module projects - built via esbuild
- `dist/awoken-ref.min.js` - Browser bundle, loadable via `` tag, and will create a global AwokenRef variable with attached functions using the default versification, or you can create a new instance with `new AwokenRef(customVersification)` - built via webpack/babel
- `dist/types` - Contains typescript declaration (.d.ts) files - package.json is setup such that these should be auto-loaded by typescript consumers of this library