Skip to main content

Class: BibleRepository

Defined in: Data/Repositories/BibleRepository.ts:35

Repository for Bible translation module databases (bible_*.db)

This repository handles ALL operations for a Bible translation database:

  • Module information (metadata about the translation)
  • Bible verses (the actual text)
  • Interlinear data (for original language texts)

Example​

const kjvDb = new SqliteProvider('data/modules/bible_kjv.db');
const repo = new BibleRepository(kjvDb);

// Get module info
const info = repo.getModuleInfo();
console.log(info.getDisplayName());

// Get verses
const verse = repo.getVerse(43003016); // John 3:16
const chapter = repo.getChapter(43, 3); // John 3

Extends​

Implements​

Constructors​

Constructor​

new BibleRepository(sql): BibleRepository

Defined in: Data/Repositories/BibleRepository.ts:36

Parameters​

sql​

ISql

Returns​

BibleRepository

Overrides​

BaseModuleRepository.constructor

Methods​

batchInsertVerses()​

batchInsertVerses(verses): void

Defined in: Data/Repositories/BibleRepository.ts:407

Batch insert multiple verses within a single transaction. Significantly faster than calling createVerse individually.

Parameters​

verses​

BibleVerse[]

Array of BibleVerse objects to insert

Returns​

void

Implementation of​

IBibleRepository.batchInsertVerses

buildBookIndex()​

buildBookIndex(bookNumber): void

Defined in: Data/Repositories/BibleRepository.ts:591

Build search index for a specific book This indexes the entire book text for proximity searches

Parameters​

bookNumber​

number

Returns​

void

Implementation of​

IBibleRepository.buildBookIndex

createVerse()​

createVerse(verse): BibleVerse

Defined in: Data/Repositories/BibleRepository.ts:334

Create a new verse (for module creation/import).

Always writes v2 content: the structured VerseFormatting payload, serialized by the shared stringifyVerseFormatting. Only the destination column name adapts to the connected database (formatting on v2, formatting_data on v1), and text_plain is populated only where the column still exists. Pass-2 deletion point: drop the column selection.

Parameters​

verse​

BibleVerse

Returns​

BibleVerse

Implementation of​

IBibleRepository.createVerse

deleteVerse()​

deleteVerse(verseId): boolean

Defined in: Data/Repositories/BibleRepository.ts:393

Delete a verse

Parameters​

verseId​

number

Returns​

boolean

Implementation of​

IBibleRepository.deleteVerse

ensureSearchTablesExist()​

ensureSearchTablesExist(): boolean

Defined in: Data/Repositories/BibleRepository.ts:489

Ensure the book-level search tables exist, returning whether they are usable.

R-12: these tables are a DERIVED INDEX, not module content. v2 removed them from the shipped schema — they existed with zero rows in all 53 bible modules — and a v2 module is an immutable artifact carrying a content_sha256, so creating tables inside one both invalidates that hash and mutates a file the user may treat as read-only.

This therefore never throws. On a read-only database it reports false and the read paths degrade to "not indexed", so proximity search falls back to ordinary verse search instead of crashing the caller.

Returns​

boolean

true when the tables are present and usable.

Implementation of​

IBibleRepository.ensureSearchTablesExist

getBook()​

getBook(book): BibleVerse[]

Defined in: Data/Repositories/BibleRepository.ts:196

Get all verses for a book

Parameters​

book​

number

Returns​

BibleVerse[]

Example​

// Using book number
const verses1 = repo.getBook(43); // Book of John

// Using Book enum
const verses2 = repo.getBook(Book.John); // Book of John

Implementation of​

IBibleRepository.getBook

getBookTextForIndex()​

getBookTextForIndex(book): string

Defined in: Data/Repositories/BibleRepository.ts:423

Get complete book text for indexing Returns concatenated plain text of all verses in the book with spaces between verses

Parameters​

book​

number

Returns​

string

getBookVersePositions()​

getBookVersePositions(book, moduleAbbr): BibleSearchVersePosition[]

Defined in: Data/Repositories/BibleRepository.ts:441

Get verse positions within book text for indexing Returns an array of BibleSearchVersePosition objects mapping each verse to its character positions in the concatenated book text

Parameters​

book​

number

moduleAbbr​

string

Returns​

BibleSearchVersePosition[]

Deprecated​

Use buildBookIndex() instead for module-level indexing

getChapter()​

getChapter(book, chapter): BibleVerse[]

Defined in: Data/Repositories/BibleRepository.ts:176

Get all verses for a chapter

Parameters​

book​

number

chapter​

number

Returns​

BibleVerse[]

Example​

// Using book number
const verses1 = repo.getChapter(43, 3); // John 3

// Using Book enum
const verses2 = repo.getChapter(Book.John, 3); // John 3

Implementation of​

IBibleRepository.getChapter

getCoveredBooks()​

getCoveredBooks(): number[]

Defined in: Data/Repositories/BibleRepository.ts:318

Get which books have content in this module Returns an array of book numbers (1-66) that have at least one verse

Returns​

number[]

Implementation of​

IBibleRepository.getCoveredBooks

getGlossesForStrongs()​

getGlossesForStrongs(strongsVariants): string[]

Defined in: Data/Repositories/BibleRepository.ts:971

Get the distinct English glosses for a Strong's number. Returns the most common gloss first.

Parameters​

strongsVariants​

string[]

Returns​

string[]

Implementation of​

IBibleRepository.getGlossesForStrongs

getInterlinearWords()​

getInterlinearWords(verseId): InterlinearWord[]

Defined in: Data/Repositories/BibleRepository.ts:868

Get interlinear words for a specific verse (original language texts only) Returns empty array if no interlinear data exists

Parameters​

verseId​

number

Returns​

InterlinearWord[]

Implementation of​

IBibleRepository.getInterlinearWords

getInterlinearWordsForChapter()​

getInterlinearWordsForChapter(book, chapter): Map<number, InterlinearWord[]>

Defined in: Data/Repositories/BibleRepository.ts:884

Get interlinear words for all verses in a chapter (batch query) Much more efficient than calling getInterlinearWords() per verse Returns a Map of verse_id to InterlinearWord[]

Parameters​

book​

number

chapter​

number

Returns​

Map<number, InterlinearWord[]>

Implementation of​

IBibleRepository.getInterlinearWordsForChapter

getModuleInfo()​

getModuleInfo(): BibleModuleInfo | undefined

Defined in: Data/Repositories/BaseModuleRepository.ts:137

Get module metadata from the module_info table. Every module database has exactly one row in module_info (info_id = 1).

Returns​

BibleModuleInfo | undefined

Implementation of​

IBibleRepository.getModuleInfo

Inherited from​

BaseModuleRepository.getModuleInfo

getVerse()​

getVerse(verseId): BibleVerse | undefined

Defined in: Data/Repositories/BibleRepository.ts:107

Get a single verse by its calculated verse ID.

Parameters​

verseId​

number

Calculated verse ID (book * 1000000 + chapter * 1000 + verse). Use VerseIdHelper.calculate to compute this value.

Returns​

BibleVerse | undefined

The verse data, or undefined if the verse does not exist in this module

Implementation of​

IBibleRepository.getVerse

getVerseCount()​

getVerseCount(): number

Defined in: Data/Repositories/BibleRepository.ts:307

Get total verse count

Returns​

number

Implementation of​

IBibleRepository.getVerseCount

getVerseIdAtPosition()​

getVerseIdAtPosition(bookNumber, position): number | undefined

Defined in: Data/Repositories/BibleRepository.ts:643

Get verse ID at a specific character position in book text

Parameters​

bookNumber​

number

position​

number

Returns​

number | undefined

Implementation of​

IBibleRepository.getVerseIdAtPosition

getVersePosition()​

getVersePosition(bookNumber, verseId): { endIndex: number; startIndex: number; } | undefined

Defined in: Data/Repositories/BibleRepository.ts:656

Get verse position range

Parameters​

bookNumber​

number

verseId​

number

Returns​

{ endIndex: number; startIndex: number; } | undefined

Implementation of​

IBibleRepository.getVersePosition

getVerseRange()​

getVerseRange(startVerseId, endVerseId): BibleVerse[]

Defined in: Data/Repositories/BibleRepository.ts:153

Get all verses within a verse ID range (inclusive).

Parameters​

startVerseId​

number

Starting verse ID (inclusive)

endVerseId​

number

Ending verse ID (inclusive)

Returns​

BibleVerse[]

Array of verses ordered by verse ID

Implementation of​

IBibleRepository.getVerseRange

getVersesWithHeadings()​

getVersesWithHeadings(): BibleVerse[]

Defined in: Data/Repositories/BibleRepository.ts:288

Get verses with section headings.

v2 stores the heading at formatting.block.heading; v1 stored it as formatting_data.sectionHeading. The LIKE pattern follows the column. Pass-2 deletion point: keep only the v2 branch.

Returns​

BibleVerse[]

Implementation of​

IBibleRepository.getVersesWithHeadings

getVerseTexts()​

getVerseTexts(verseIds): Map<number, BibleVerse>

Defined in: Data/Repositories/BibleRepository.ts:124

Get multiple verses by their IDs in a single query. Returns only verse text data (no interlinear). Useful for batch display in topical indexes, cross-references, etc.

Parameters​

verseIds​

number[]

Array of calculated verse IDs

Returns​

Map<number, BibleVerse>

Map of verse ID to BibleVerse for found verses

Implementation of​

IBibleRepository.getVerseTexts

hasInterlinearData()​

hasInterlinearData(): boolean

Defined in: Data/Repositories/BibleRepository.ts:915

Check if this module has interlinear data Checks if the interlinear_word table exists and has data Uses EXISTS for fast O(1) check instead of COUNT(*) which scans all rows

Returns​

boolean

Implementation of​

IBibleRepository.hasInterlinearData

isBookIndexed()​

isBookIndexed(bookNumber): boolean

Defined in: Data/Repositories/BibleRepository.ts:575

Check if a specific book is indexed for proximity search

Parameters​

bookNumber​

number

Returns​

boolean

Implementation of​

IBibleRepository.isBookIndexed

searchBookFTS5()​

searchBookFTS5(bookNumber, fts5Query): object[]

Defined in: Data/Repositories/BibleRepository.ts:669

Search book text using FTS5 with custom query (e.g., NEAR for proximity) Note: offsets() doesn't work with NEAR queries, so we return empty offsets

Parameters​

bookNumber​

number

fts5Query​

string

Returns​

object[]

Implementation of​

IBibleRepository.searchBookFTS5

searchByStrongsNumber()​

searchByStrongsNumber(strongsVariants, range?): number[]

Defined in: Data/Repositories/BibleRepository.ts:947

Find all verse IDs containing a given Strong's number. Accepts multiple format variants to handle variable zero-padding.

Parameters​

strongsVariants​

string[]

range?​
endVerseId​

number

startVerseId​

number

Returns​

number[]

Implementation of​

IBibleRepository.searchByStrongsNumber

searchProximityInBook()​

searchProximityInBook(bookNumber, terms, maxDistance): number[]

Defined in: Data/Repositories/BibleRepository.ts:753

Find all verses in a book where all search terms appear within a word-proximity window.

Algorithm overview:

  1. Tokenize -- The entire book text (all verses concatenated) is lowercased and split into words. This gives a flat word-position array spanning the whole book.

  2. Build term position index -- For each search term, record every word index where it appears (exact match or prefix match). This produces a Map<term, number[]> of word positions per term.

  3. Early exit -- If any term has zero occurrences in the book, return immediately (all terms must be present for a proximity match).

  4. Sliding anchor scan (findProximityMatches) -- Iterate over each occurrence of the first term as an "anchor" position. For each anchor, check whether every other term has at least one occurrence within maxDistance words (using linear scan with Array.some). If all terms are nearby, the anchor is recorded as a match.

  5. Expand to nearby terms -- For each match, collect ALL word positions from ALL terms that fall within the proximity window. This ensures that if the matching terms span multiple verses, all relevant verses are included in the result.

  6. Word-to-verse mapping -- Convert each word position back to a character offset (by joining preceding words), then look up which verse contains that character offset using the verse_positions table (populated by buildBookIndex).

Time complexity: O(W * T * P) where W = occurrences of the first term, T = number of terms, P = max occurrences of any other term. The word-to-character conversion in step 6 is O(W_total * W_avg) due to the words.slice(0, pos).join(' ') call per position.

Known limitations:

  • Prefix matching ("walk" matches "walking") may produce false positives for short terms.
  • The word-to-character position conversion rebuilds substrings for each match, which is expensive for books with many proximity matches. A precomputed word-offset array would improve this to O(1) per lookup.
  • The algorithm anchors on the first term only. A term with very few occurrences in a non-first position won't benefit from early pruning.

Parameters​

bookNumber​

number

Book number (1-66) to search within

terms​

string[]

Array of search terms (at least 2 terms expected)

maxDistance​

number

Maximum number of words allowed between any two terms

Returns​

number[]

Sorted array of verse IDs where all terms appear within proximity

Implementation of​

IBibleRepository.searchProximityInBook

searchVerses()​

searchVerses(query, options?): BibleVerse[]

Defined in: Data/Repositories/BibleRepository.ts:215

Search verses using SQLite FTS5 full-text search.

Queries the verse-level FTS5 index (porter stemming + unicode61 tokenizer). Supports all FTS5 query syntax: AND, OR, NOT, quoted phrases, prefix matching.

Parameters​

query​

string

FTS5 query string (e.g., "faith AND works", ""grace of God"")

options?​

Optional search configuration

limit?​

number

Maximum results to return (default 100)

Returns​

BibleVerse[]

Array of matching verses ordered by verse ID

Implementation of​

IBibleRepository.searchVerses

searchVersesWithHighlighting()​

searchVersesWithHighlighting(query, options?): object[]

Defined in: Data/Repositories/BibleRepository.ts:239

Search verses with FTS5 highlighting Returns verses with matched terms highlighted using FTS5's highlight() function. This correctly highlights stemmed variants (e.g., searching "walk" highlights "walking", "walked").

Parameters​

query​

string

FTS5 query string

options?​

Search options (limit)

limit?​

number

Returns​

object[]

Array of objects with verse data and highlighted text

Implementation of​

IBibleRepository.searchVersesWithHighlighting

updateModuleInfo()​

updateModuleInfo(info): void

Defined in: Data/Repositories/BibleRepository.ts:49

Update the module information.

The v2 identity + provenance block (WS-4) is written when the connected database has those columns; on a v1 database only the legacy columns are touched. See buildIdentityAssignments.

Parameters​

info​

BibleModuleInfo

Returns​

void

Implementation of​

IBibleRepository.updateModuleInfo

updateVerse()​

updateVerse(verse): BibleVerse

Defined in: Data/Repositories/BibleRepository.ts:350

Update an existing verse. See createVerse for the v1/v2 column note.

Parameters​

verse​

BibleVerse

Returns​

BibleVerse

Implementation of​

IBibleRepository.updateVerse