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.
npm install bible-resolveA 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 devOpens on localhost:3460 — search for books by name, abbreviation, or prefix in English and French.
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]Full return shapes
// 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
}]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.
More about OSIS values
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.
Classification Keys
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 |
Data Exports
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']- 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.)
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).
BSD-3-Clause