Overview

Bible Reference Index is a Christian Bible reference verse index and index validation system. It provides a standard way to index and reference verses in the Bible. The package is built to address the lack of a standard book abbreviation or Bible reference ID system.

Installation

To install the package via npm, run:

npm i @biblebytes/bible-reference

Book IDs

This table categorizes the books of the Bible into Old and New Testaments, providing their standard ID/abbreviations according to the Digital Bible Library USX Standard.

| Old Testament | ID | New Testament | ID | |----------------------|-------|----------------------|-------| | Genesis | GEN | Matthew | MAT | | Exodus | EXO | Mark | MRK | | Leviticus | LEV | Luke | LUK | | Numbers | NUM | John | JHN | | Deuteronomy | DEU | Acts | ACT | | Joshua | JOS | Romans | ROM | | Judges | JDG | 1 Corinthians | 1CO | | Ruth | RUT | 2 Corinthians | 2CO | | 1 Samuel | 1SA | Galatians | GAL | | 2 Samuel | 2SA | Ephesians | EPH | | 1 Kings | 1KI | Philippians | PHP | | 2 Kings | 2KI | Colossians | COL | | 1 Chronicles | 1CH | 1 Thessalonians | 1TH | | 2 Chronicles | 2CH | 2 Thessalonians | 2TH | | Ezra | EZR | 1 Timothy | 1TI | | Nehemiah | NEH | 2 Timothy | 2TI | | Esther | EST | Titus | TIT | | Job | JOB | Philemon | PHM | | Psalms | PSA | Hebrews | HEB | | Proverbs | PRO | James | JAS | | Ecclesiastes | ECC | 1 Peter | 1PE | | Song of Songs | SNG | 2 Peter | 2PE | | Isaiah | ISA | 1 John | 1JN | | Jeremiah | JER | 2 John | 2JN | | Lamentations | LAM | 3 John | 3JN | | Ezekiel | EZK | Jude | JUD | | Daniel | DAN | Revelation | REV | | Hosea | HOS | | | | Joel | JOL | | | | Amos | AMO | | | | Obadiah | OBA | | | | Jonah | JON | | | | Micah | MIC | | | | Nahum | NAM | | | | Habakkuk | HAB | | | | Zephaniah | ZEP | | | | Haggai | HAG | | | | Zechariah | ZEC | | | | Malachi | MAL | | |

Reference Class

The Reference class is the main component of this package, allowing you to create and validate Bible references.

Reference ID strings can use a mix of delimiter between sections (\s, -, ., :, ,) for example, EXO 2:5-10, EXO:2:5:10, and EXO-2:5-10 are all treated the same.

import { Reference, Language } from '@biblebytes/bible-reference';

// Creating a new reference
const ref1 = new Reference(Language.English);
console.log(ref1.toString()); // Output: "GEN:1:1"

// Creating a reference with a verse range
const ref2 = new Reference(Language.English, "EXO 2:5-10");
console.log(ref2.toString(true)); // Output: "Exodus 2:5-10"

// Creating a reference with mixed delimiters
const ref3 = new Reference(Language.English, "EXO:2:5:10");
console.log(ref3.toString(true)); // Output: "Exodus 2:5-10"

// Setting a new reference
ref1.Set("MAT 5:9");
console.log(ref1.toString()); // Output: "MAT:5:9"

// Setting a reference, mixed delimiters
ref1.Set("MAT.5.9");
console.log(ref1.toString()); // Output: "MAT:5:9"

Structure

class Reference {
    public language: Language;
    public book: Book;
    public chapter: number;
    public verse: number;
    public chapterEnd?: number;
    public verseEnd?: number;

    constructor(language: Language, reference?: string);
    public Set(reference: string): void;
    public GetError(): string | undefined;
    public toString(pretty?: boolean): string;
}

Methods

constructor

Creates an instance of Reference. Throws error if invalid verse.

constructor(language: Language, reference?: string)

• language: The language of the reference.
• reference: (optional) The reference string to parse.

Examples:

const ref1 = new Reference(Language.English, "GEN 1:1");
const ref2 = new Reference(Language.English, "PSM 23:1-6");
const ref3 = new Reference(Language.English, "EXO 2:5-3:10");

// using any delimiter or mix of delimiters
const ref4 = new Reference(Language.English, "EXO:2:5:3:10");
const ref4 = new Reference(Language.English, "EXO-2-5-3-10");

Set

Sets the reference details by parsing the reference string. Throws error if invalid verse.

public Set(reference: string): void

• reference: The reference string to parse.

Examples:

const ref = new Reference(Language.English);
ref.Set("MAT 5:9");
ref.Set("REV 21:3-4");

// using any delimiter or mix of delimiters
ref.Set("MAT:5:9");
ref.Set("REV:21:3-4");

IsFollowedBy

Checks if the current verse is followed by the specified verse (nextVerse), within the same chapter. Note: does not utilize chapter end or verse end; thus GEN 1:1-5 is followed by GEN 1:2.

public IsFollowedBy(nextVerse: Reference): boolean

• reference: The verse to check if it comes after the current verse.
• Returns: Returns true if the current verse is followed by nextVerse; otherwise, it returns false.

const ref1 = new Reference(Language.English, "GEN 1:1");
const ref2 = new Reference(Language.English, "GEN 1:2");
ref1.IsFollowedBy(ref2); // returns true

const ref3 = new Reference(Language.English, "MAT 5:3");
const ref4 = new Reference(Language.English, "MAT 5:4");
const ref5 = new Reference(Language.English, "MAT 5:5");
ref3.IsFollowedBy(ref4); // returns true
ref3.IsFollowedBy(ref5); // returns false

Unpack

Unpacks a verse range into it's individual verses, returning a list of verses. For example GEN:1:1-3 can be unpacked into GEN:1:1, GEN:1:2, and GEN:1:3. References can range over both chapters and verses.

public Unpack(): Reference[]

• Returns: a list of reference verses

Examples:

const ref1 = new Reference(Language.English, `GEN:1:1-3`);
ref1.Unpack(); // ["GEN:1:1", "GEN:1:2", "GEN:1:3"]

const ref2 = new Reference(Language.English, `GEN:1:31-2:1`);
ref2.Unpack(); // ["GEN:1:31", "GEN:2:1"]

GetError

Checks if the reference is valid and returns the error as a string if the verse is invalid. For example, this ensures the verse and end of the verse range are valid.

public GetError(): string | undefined

• Returns: undefined if the reference is valid, otherwise returns a string.

Examples:

const ref = new Reference(Language.English);
ref.Set("MAT 5:9");
ref.GetError(); // undefined
ref.Set("MAT 5:1000");
ref.GetError(); // "Invalid verse number"
ref.Set("MAT 5:9-8");
ref.GetError(); // "Invalid verse end number"

toString

Converts the reference to a string representation.

public toString(pretty?: boolean): string

• pretty: (optional) If true, returns a human-readable string.
• Returns: The string representation of the reference.

Examples:

const ref = new Reference(Language.English, "MAT 5:9-10");
console.log(ref.toString()); // Output: "MAT:5:9:10"
console.log(ref.toString(true)); // Output: "MAT 5:9-10"

GetBook

Retrieves book metadata by ID or name.

function GetBook(language: Language, id: number | Book): BookMetadata | undefined

• language: An enumerated language code.
• id: The ID or index of the book to retrieve.
• Returns: The metadata of the book if found, otherwise undefined.

Examples

const genesis = GetBook(Language.English, "GEN");
console.log(genesis);
// Output:
// {
//     id: "GEN",
//     name: "Genesis",
//     chapters: [31, 25, ...]
// }

const exodus = GetBook(Language.English, Book.EXO);
console.log(exodus);
// Output:
// {
//     id: "EXO",
//     name: "Exodus",
//     chapters: [22, 25, 22, ...]
// }

GetAllBooks

Retrieves book metadata for multiple IDs or names.

function GetAllBooks(language: Language, ids?: (number | Book)[] | readonly Book[]): readonly BookMetadata[]

• language: An enumerated language code.
• ids: (optional) An array of IDs or indexes of the books to retrieve.
• Returns: An array containing the metadata of the specified books.

Examples

const books = GetAllBooks(Language.English, ["GEN", "EXO"]);
console.log(books);
// Output:
// [
//     {
//         id: "GEN",
//         name: "Genesis",
//         chapters: [31, 25, 24...]
//     },
//     {
//         id: "EXO",
//         name: "Exodus",
//         chapters: [22, 25, 22...]
//     },
// ]

const books = GetAllBooks(Language.English, BooksOldTestament);
console.log(books);
// Output:
// [
//     {
//         id: "GEN",
//         name: "Genesis",
//         chapters: [31, 25, 24...]
//     },
//     {
//         id: "EXO",
//         name: "Exodus",
//         chapters: [22, 25, 22...]
//     },
//     ...
// ]

Language Enumeration

Enumerates the supported languages.

enum Language {
    English = "EN",
}

Book Enumeration

Enumerates the books of the Bible and assigns each book an ID, regardless of the language.

enum Book {
    Genesis = "GEN",
    Exodus = "EXO",
    // ... other books
    Revelation = "REV",
}

Books

Books is a constant array that contains all the books of the Bible in a standardized format. Each book is represented by its abbreviation as defined in the Book enum.

const Books = [
    Book.GEN,
    Book.EXO,
    // ... other books
    Book.REV
]

BooksOldTestament

BooksOldTestament is a constant array that contains all the books of the Old Testament. Each book is represented by its abbreviation as defined in the Book enum.

const BooksOldTestament = [
    Book.GEN,
    Book.EXO,
    // ... other books
    Book.MAL
]

BooksNewTestament

BooksNewTestament is a constant array that contains all the books of the New Testament. Each book is represented by its abbreviation as defined in the Book enum.

const BooksNewTestament = [
    Book.MAT,
    Book.MRK,
    // ... other books
    Book.REV
]

Metadata

Maps language codes to their corresponding metadata.

const Metadata: { [key in Language]: readonly BookMetadata[] } = {
    [Language.English]: Metadata_EN,
};

License

This project is distributed under the MIT License.