@krulod/bible

A one-stop JS library for working with the Bible.

It is a part of the krulod/bible project. See there for content format information, lists of translations and books.

Install

pnpm add @krulod/bible

Content packages

The recommended way to import content is auto-generated npm packages. If this is not suitable for you, see Custom sources.

Every translation is available through a package with name following the @krulod/bible-{translation} format. See all available translation values in the Translations section of the project documentation. For example, for King James Version translation you should install @krulod/bible-kjv.

Each translation exports two variables:

• {translation}_import: an async Bible that uses dynamic imports to fetch books
• {translation}_inline: a sync Bible that imports all books statically

Book collections

Regardless of the way to import content you use, you will work with Bible objects that encapsulate the logic of book fetching. They all have an _ids property that stores a list of identifiers of all books you can access through this object. For every identifier in _ids there is a corresponding property called entry. If the underlying content source is asynchronous, every entry is a memoized getter that returns a promise of BibleBook representing the book loading state. Otherwise, entries return BibleBook which you can use immediately.

declare const syncBible: BibleSync<'some_book_id' | 'another_book_id'>
syncBible._ids //=> ['some_book_id', 'another_book_id']
syncBible.some_book_id //=> BibleBook {...}

declare const asyncBible: BibleAsync<'some_book_id' | 'another_book_id'>
asyncBible.some_book_id //=> Promise<BibleBook>

Accessing content

All BibleBook-s have these members for accessing their contents:

• title: translated book title
• chaptersCount(): returns total chapter count
• chapters(): returns an array of all chapter numbers
• versesCount(chapter): returns verses count of a chapter
• verses(chapter): returns an array of verse numbers of a chapter
• verseText(chapter, verse): returns a specified verse's text

declare const book: BibleBook

const bookVerses = book.chapters().flatMap( chapter => {
	return book.verses(chapter).map( verse => {
		const verseText = book.verseText(chapter, verse)
		return `${book.title} ${chapter}:${verse} — ${verseText}`
	} )
} )

Verse spans

You can use span method of BibleBook that accepts two verse references to retrieve references to all verses between them inclusively:

declare const book: BibleBook
declare const spanStart: [chapter: number, verse: number]
declare const spanEnd: [chapter: number, verse: number]

const spanVerses = book.span(spanStart, spanEnd).map( ( [chapter, verse] ) => {
	const verseText = book.verseText(chapter, verse)
	return `${book.title} ${chapter}:${verse} — ${verseText}`
} )

Cache

With BibleCache* functions you can "decorate" any Bible instance to make it store books in some kind of storage for offline access. Such storage is called a cache layer and is represented as an object with get and set methods with signatures similiar to that ones of Map.

declare const syncCacheLayer: {
	get: (key: string) => BibleBook | undefined
	set: (key: string, value: BibleBook) => void
}
const cachedBible = BibleCacheSync(originalBible, syncCacheLayer) //=> sync if originalBible is sync as well

declare const asyncCacheLayer: {
	get: (key: string) => Promise<BibleBook | undefined>
	set: (key: string, value: BibleBook) => Promise<void>
}
const cachedBible = BibleCacheAsync(originalBible, asyncCacheLayer) //=> always async

Cache: IndexedDB example

This example uses unstorage library and its indexedDbDriver API. Since createStorage return values have get and set methods, we can use one as a cache layer directly:

import {BibleCacheAsync} from '@krulod/bible'
import {vulgata_import} from '@krulod/bible-vulgata'
import {createStorage} from 'unstorage'
import indexedDbDriver from 'unstorage/drivers/indexedb'

const cache = createStorage( {
	driver: indexedDbDriver( {base: 'bible:'} ),
} )
const vulgataCached = BibleCacheAsync(vulgata_import, cache)

await vulgataCached.gen //=> BibleBook {...}
await cache.get('bible:gen') //=> {title: 'Liber Genesis', raw: {...}}

Custom sources

You can use the BibleFrom function to create Bible objects like {translation}_import/{translation}_inline from Content packages.

import {BibleFrom, BibleBookRawParse} from '@krulod/bible'
import {createStorage} from 'unstorage'
import githubDriver from 'unstorage/drivers/github'

const storage = createStorage( {
	driver: githubDriver( {
		repo: 'krulod/bible',
		branch: 'master',
		dir: 'txt/vulgata',
	} ),
} )
const titles = JSON.parse( await storage.get('_titles.json') )
const vulgata = BibleFrom(
	Object.keys(titles),
	async id => {
		const title = titles[id]
		const content = await storage.get(`${id}.txt`)
		return new BibleBook( {title, content} )
	}
)

vulgata._ids //=> [...]
await vulgata.gen //=> BibleBook {...}