bible-resolve

Bible reference resolver — book name resolution with chapter/verse support, prefix matching, abbreviations and multi-language support (EN/FR). Returns a ranked list of candidates from the very first character, making it a natural building block for autocomplete and search features.

Installation

npm install bible-resolve

Demo

A live demo is available at bible-resolve-demo.b-cdn.net.

The demo source is included in the demo/ folder. To run it locally:

cd demo
npm install
npm run dev

Opens on localhost:3460 — search for books by name, abbreviation, or prefix in English and French.

Usage

import { resolveRef } from 'bible-resolve';

resolveRef('Mat');
// [{book: {name: 'Matthew', osis: 'Matt', ...}, osis: 'Matt', ref: 'Matthew', matchType: 'prefix', ...}]

resolveRef('John 3:16');
// [{book: {name: 'John', osis: 'John', ...}, osis: 'John.3.16', ref: 'John 3:16', ...}]

resolveRef('Jude 5');
// [{book: {name: 'Jude', osis: 'Jude', ...}, osis: 'Jude.1.5', ref: 'Jude 1:5', ...}]

resolveRef('Luk', 'fr', /* crossLang */ true);
// [{book: {name: 'Luc', osis: 'Luke', ...}, osis: 'Luke', ref: 'Luc', matchedViaLang: 'en', ...}]

resolveRef('Jea', 'fr');
// [{book: {name: 'Jean', osis: 'John', ...}, osis: 'John', ref: 'Jean', ...}, ...4 more]

// resolveRef('Mat')
[{
    book: {
        name: 'Matthew',
        osis: 'Matt',
        bookNum: 40,
        chapters: 28,
        classificationKey: 'nt_gospels',
        altNames: ['Gospel of Matthew', ...]
    },
    osis: 'Matt',
    ref: 'Matthew',
    matchType: 'prefix',
    matchedTerm: 'Matthew',
    score: 642.88
}]

// resolveRef('John 3:16')
[{
    book: { name: 'John', osis: 'John', bookNum: 43, chapters: 21, ... },
    osis: 'John.3.16',
    ref: 'John 3:16',
    matchType: 'exact',
    matchedTerm: 'John',
    score: 2050.02
}]

// resolveRef('Jude 5')
[{
    book: { name: 'Jude', osis: 'Jude', bookNum: 65, chapters: 1, ... },
    osis: 'Jude.1.5',
    ref: 'Jude 1:5',
    matchType: 'exact',
    matchedTerm: 'Jude',
    score: 2050.00
}]

API

resolveRef(query, lang?, crossLang?)

Search for Bible books by name or abbreviation.

| Parameter | Type | Default | Description | | ----------- | -------------- | ------- | -------------------------------------------------------------------------------- | | query | string | — | Search string (book name, abbreviation, prefix, or reference like "John 3:16") | | lang | 'en' \| 'fr' | 'en' | Primary language | | crossLang | boolean | false | Enable cross-language fallback |

Returns an array of results sorted by score (highest first):

[{
    book: {
        name: 'Genesis',                   // Localized book name
        osis: 'Gen',                        // OSIS standard code — stable book identifier
        bookNum: 1,                         // Canonical order (1–66)
        chapters: 50,                       // Number of chapters in this book
        altNames: ['Book of Genesis', ...], // Alternative names and abbreviations
        classificationKey: 'ot_pentateuch'  // Book classification
    },
    osis: 'Gen.1.1',            // Resolved OSIS reference (book, chapter, or verse level)
    ref: 'Genesis 1:1',         // Human-readable display reference (localized name + chapter:verse)
    // matchType ranks: exact > space-prefix > prefix > multiword-not-prefix > word-prefix
    matchType: 'exact',         // How the query matched
    matchedTerm: 'Gen',         // The specific name or abbreviation that matched
    score: 1150,                // Ranking score — higher is better; compare relatively, not against thresholds
    matchedViaLang: 'en'        // Only present with crossLang: which language matched
}]

Throws Error if lang is not a supported language.

Each book is identified by its OSIS code — a language-independent abbreviation from the Open Scripture Information Standard. OSIS codes are stable, widely adopted in Bible software, and align with the dominant npm parser (bible-passage-reference-parser). bible-resolve uses all 66 canonical codes exactly as specified by the standard.

Each book includes a classificationKey field. These keys are subject to change and can typically be ignored — they are useful only for special use cases such as combining with other data to provide visual grouping or categorisation of search results.

| Key | Books | | ------------------- | --------------------- | | ot_pentateuch | Genesis – Deuteronomy | | ot_historical | Joshua – Esther | | ot_wisdom | Job – Song of Solomon | | ot_major_prophets | Isaiah – Daniel | | ot_minor_prophets | Hosea – Malachi | | nt_gospels | Matthew – John | | nt_history | Acts | | nt_pauline | Romans – Philemon | | nt_general | Hebrews – Jude | | nt_apocalyptic | Revelation |

These exports provide direct access to the underlying data. They are not designed to be as stable as resolveRef — their shape may change between versions.

import { books, names, languages } from 'bible-resolve';

// Language-independent book metadata
books; // → [{ osis: 'Gen', bookNum: 1, classificationKey: 'ot_pentateuch', chapters: 50 }, ...]
books.length; // → 66

// Language-specific names, keyed by language code
names.en; // → [{ osis: 'Gen', name: 'Genesis', altNames: [...] }, ...]
names.fr; // → [{ osis: 'Gen', name: 'Genèse', altNames: [...] }, ...]

// Supported languages
languages; // → ['en', 'fr']

Supported Languages

• English ('en') — 66 books with common abbreviations (Gen, Ex, Lev, Jn, Rev, etc.)
• French ('fr') — 66 books with French names and abbreviations (Gn, Ex, Lv, Jn, Ap, etc.)

Q & A

How does this compare to bible-passage-reference-parser?

Different goals. bible-passage-reference-parser extracts exact, unambiguous references from text — given "John 3:16" it returns one precise result. bible-resolve is designed for the opposite end: incomplete, ambiguous input. Given "Jo" it returns a ranked list of every matching book (John, Joshua, Joel, Jonah…) from the very first keystroke. Typically when bible-passage-reference-parser resolves a book, our top result will agree — but we provide multiple scored candidates, which is what you need behind an autocomplete or search UI.

How does chapter/verse parsing work?

Queries like "John 3:16", "John 3.16", or "John 3,16" are parsed into book + chapter + verse. The osis field on each result reflects the most precise valid reference: "John.3.16" for a verse, "John.3" for a chapter, or "John" for a book. The ref field provides the same detail in human-readable form using the localized book name (e.g., "John 3:16", "Jean 3:16"). Invalid chapters (e.g., "Rev 23" — Revelation has 22 chapters) fall back to the book level. Verse ranges and lists (e.g., "John 3:14-18") are not supported — the verse is discarded and the result is chapter-level.

For single-chapter books (Obadiah, Philemon, 2 John, 3 John, Jude), a bare number is treated as a verse: "Jude 5" → "Jude.1.5". The explicit form "Jude 1:5" also works. An invalid chapter like "Jude 2:3" falls back to "Jude".

When a chapter is provided and valid for a matched book, that book receives a score boost. This means "Ti 4" ranks 1 Timothy and 2 Timothy (which have chapter 4) above Titus (which has only 3 chapters).

License

BSD-3-Clause