@metaxia/scriptures-core

@metaxia/scriptures-core

The foundational engine for the Scriptures JS ecosystem. Provides a unified API for querying scripture texts, computing gematria, parsing morphology, and working with lexicon data.

v3.0.0 Breaking Changes

• New hebrew namespace: Gematria and temurah (letter ciphers) are now under hebrew.gematria.* and hebrew.temurah.*
• 9 gematria systems: All derived from primary historical sources with full citations
• 2 temurah ciphers: Atbash and Albam with source documentation
• Musafi modifier: Phrase-level modifier as documented in JE (1906)
• No more shorthand names: Use proper Hebrew names (misparHechrachi not standard)

Installation

npm install @metaxia/scriptures-core

You'll also need at least one data source package:

npm install @metaxia/scriptures-source-byztxt-tr      # Greek NT (Byzantine)
npm install @metaxia/scriptures-source-openscriptures-ohb  # Hebrew OT

Quick Start

// Import a data source to auto-register it
import '@metaxia/scriptures-source-openscriptures-ohb';

import { hebrew, getVerse, listEditions } from '@metaxia/scriptures-core';

// List available editions
console.log(listEditions()); // ['openscriptures-OHB']

// Get a verse
const verse = await getVerse('Genesis', 1, 1, { edition: 'openscriptures-OHB' });
console.log(verse.text);

// Compute gematria using Hebrew system names
console.log(hebrew.gematria.misparHechrachi('בראשית')); // 913
console.log(hebrew.gematria.misparKatan('בראשית'));     // 22
console.log(hebrew.gematria.misparGadol('בראשית'));     // 913

// Apply temurah (letter cipher)
console.log(hebrew.temurah.atbash('בבל')); // 'ששכ' (Babel -> Sheshakh)

API Reference

Verse Queries

getVerse(book, chapter, verse, options)

Retrieve a single verse.

import { getVerse } from '@metaxia/scriptures-core';

const verse = await getVerse('Genesis', 1, 1, { edition: 'openscriptures-OHB' });

// Verse structure:
// {
//   id: 'openscriptures-OHB:Genesis.1.1',
//   book: 'Genesis',
//   chapter: 1,
//   number: 1,
//   text: 'בְּרֵאשִׁ֖ית בָּרָ֣א אֱלֹהִ֑ים ...',  // includes cantillation marks
//   words: [...],
//   gematria: { ... },      // computed on-demand, excludes colophon words
//   gematriaWithColophons: { ... },  // computed on-demand, includes all words
// }

getChapter(book, chapter, options)

Retrieve all verses in a chapter.

import { getChapter } from '@metaxia/scriptures-core';

const verses = await getChapter('John', 1, { edition: 'byztxt-TR' });
console.log(verses.length); // 51

getVersesInRange(book, chapter, start, end, options)

Retrieve a range of verses.

import { getVersesInRange } from '@metaxia/scriptures-core';

const verses = await getVersesInRange('Psalms', 23, 1, 6, { edition: 'openscriptures-OHB' });

getParallelVerses(book, chapter, verse)

Get the same verse from all registered editions.

import { getParallelVerses } from '@metaxia/scriptures-core';

const parallels = await getParallelVerses('John', 1, 1);
// Map { 'byztxt-TR' => Verse, 'another-edition' => Verse }

listBooks(edition)

List available books for an edition.

import { listBooks } from '@metaxia/scriptures-core';

const books = listBooks('byztxt-TR');
// ['Matthew', 'Mark', 'Luke', 'John', ...]

Hebrew Gematria

Nine letter-value systems derived from primary historical sources.

import { hebrew } from '@metaxia/scriptures-core';

// Basic usage
hebrew.gematria.misparHechrachi('שלום')  // 376 - standard value
hebrew.gematria.misparGadol('שלום')      // 376 - major value (finals as 500-900)
hebrew.gematria.misparKatan('שלום')      // 16  - reduced value (1-9)

// With musafi modifier (adds letter or word count)
hebrew.gematria.misparHechrachi('שלום', { musafi: 'letters' })  // 380 (376 + 4)
hebrew.gematria.misparHechrachi('שלום עולם', { musafi: 'words' }) // 782 (780 + 2)

// Compute all systems at once
hebrew.gematria.computeAll('שלום')
// { misparHechrachi: 376, misparGadol: 376, misparKatan: 16, ... }

// Get system metadata with source citation
hebrew.gematria.getSystem('misparHechrachi')
// { name: 'misparHechrachi', hebrewName: 'מספר הכרחי', source: { ... }, ... }

Available Systems

Method	Hebrew Name	Source	Description
misparHechrachi	מספר הכרחי	JE §E.1	Standard: א-ט=1-9, י-צ=10-90, ק-ת=100-400
misparGadol	מספר גדול	JE §E.11	Major: finals as 500-900
misparKatan	מספר קטן	JE §E.2	Reduced: all values 1-9
misparKolel	מספר כולל	JE §E.3	Inclusive: cumulative sums
misparPerati	מספר פרטי	JE §E.6	Squared: each letter²
misparMeshulash	מספר משולש	JE §E.15	Cubed: each letter³
misparChitzon	מספר חיצוני	JE §E.10	External: every letter = 1
misparSiduri	מספר סידורי	Pardes	Ordinal: position 1-22
misparHakadmi	מספר הקדמי	Pardes	Prior: triangular numbers

Hebrew Temurah (Letter Ciphers)

Two letter substitution ciphers. These transform letters, not compute values.

import { hebrew } from '@metaxia/scriptures-core';

// Atbash - mirror positions (first↔last)
hebrew.temurah.atbash('בבל')     // 'ששכ' (Babel -> Sheshakh, Jer 25:26)
hebrew.temurah.atbash('כשדים')   // 'לבקמי' (Kasdim -> Lev Kamai, Jer 51:1)

// Albam - half-alphabet swap (position n ↔ n+11)
hebrew.temurah.albam('אלהים')    // 'למהיב'

// Both ciphers are symmetric (applying twice returns original)
hebrew.temurah.atbash(hebrew.temurah.atbash('שלום')) // 'שלום'

// Combine cipher with gematria
const transformed = hebrew.temurah.atbash('בבל');
hebrew.gematria.misparHechrachi(transformed)  // 620

Available Ciphers

Cipher	Hebrew	Source	Description
atbash	אתב״ש	JE + Pardes	Mirror positions: את, בש, etc.
albam	אלב״ם	Pardes 30:5	Half swap: אל, במ, etc.

Morphology

Parse morphological codes from tagged texts.

import { parseMorphCode, HebrewMorphologyParser } from '@metaxia/scriptures-core';

// Parse a morphology code
const parsed = parseMorphCode('HVqp3ms');
// { partOfSpeech: 'verb', stem: 'qal', aspect: 'perfect', person: '3', gender: 'masculine', number: 'singular' }

// Use the Hebrew parser directly
const parser = new HebrewMorphologyParser();
const result = parser.parse('HNcmsa');
// { partOfSpeech: 'noun', gender: 'masculine', number: 'singular', state: 'absolute' }

Lexicon

Look up words by Strong's number or lemma.

import { lookupStrongs, normalizeStrongs } from '@metaxia/scriptures-core';

// Normalize Strong's numbers
normalizeStrongs('H07225'); // 'H7225'
normalizeStrongs('g3056');  // 'G3056'

// Look up (requires a lexicon source package)
const entry = await lookupStrongs('H7225');
// { strongs: 'H7225', lemma: 'רֵאשִׁית', transliteration: 'reshith', ... }

Registry

Manage scripture data sources.

import {
  registerSource,
  unregisterSource,
  getSource,
  listEditions,
  hasEdition,
} from '@metaxia/scriptures-core';

// Check what's registered
console.log(listEditions());    // ['byztxt-TR', 'openscriptures-OHB']
console.log(hasEdition('KJV')); // false

// Get source metadata
const source = getSource('byztxt-TR');
console.log(source?.metadata.language); // 'Greek'

Versification

Map a verse reference between numbering traditions — MT (Hebrew/Masoretic), LXX (Septuagint), and English (KJV). The Old Testament is numbered differently across these traditions (Psalm superscriptions counted as verse 1, the Greek Psalter's one-off offset, Joel/Malachi chapter boundaries…). mapVerse translates a reference from one scheme to another, returning null when the source reference has no equivalent in the target scheme.

import { mapVerse } from '@metaxia/scriptures-core';

mapVerse('Psalms', 51, 1, 'MT', 'English'); // -> null  (Hebrew superscription; no KJV verse)
mapVerse('Psalms', 51, 3, 'MT', 'English'); // -> { chapter: 51, verse: 1 }
mapVerse('Joel', 3, 1, 'MT', 'English');    // -> { chapter: 2, verse: 28 }
mapVerse('Genesis', 1, 1, 'MT', 'English'); // -> { chapter: 1, verse: 1 } (identity)

Core ships a built-in mapping registered at priority: 0. Richer, data-driven sources register through the same inversion-of-control as text sources and override it. @metaxia/scriptures-source-stepbible-versification (STEPBible TVTMS) registers at priority: 10, so importing it makes mapVerse prefer the validated TVTMS table for the pairs it covers:

import '@metaxia/scriptures-source-stepbible-versification'; // auto-registers (priority 10)
import { getVersificationSources } from '@metaxia/scriptures-core';

getVersificationSources().map(s => s.id); // ['builtin', 'stepbible-versification']

To register a custom source, implement the VersificationSource contract and call registerVersification:

import { registerVersification, type VersificationSource } from '@metaxia/scriptures-core';

const mySource: VersificationSource = {
  id: 'my-versification',
  systems: ['MT', 'English'], // the traditions this source bridges
  priority: 20,               // higher wins; built-in = 0
  mapRef(book, chapter, verse, from, to) {
    // return { chapter, verse } — or null if no equivalent in `to`
    return { chapter, verse };
  },
};
registerVersification(mySource);

mapVerse routes each from/to pair to the highest-priority registered source whose systems cover both schemes.

Errors

Custom error classes for handling specific failure cases:

import {
  EditionNotFoundError,
  BookNotFoundError,
  VerseNotFoundError,
  GematriaError,
} from '@metaxia/scriptures-core';

try {
  await getVerse('Genesis', 1, 1, { edition: 'nonexistent' });
} catch (error) {
  if (error instanceof EditionNotFoundError) {
    console.log(`Edition not found: ${error.edition}`);
  }
}

Data Model

Verse

interface Verse {
  id: string;           // e.g., 'byztxt-TR:John.1.1'
  book: string;
  chapter: number;
  number: number;
  text: string;         // Full verse text (with diacritics/cantillation)
  words: Word[];        // Individual words with annotations
  gematria?: GematriaValues;      // Computed on-demand, excludes colophon words
  gematriaWithColophons?: GematriaValues;  // Computed on-demand, includes all words
  metadata?: Record<string, unknown>;
}

Word

interface Word {
  position: number;
  text: string;
  lexiconEntry?: LexiconEntry;
  morphology?: Morphology;
  strongs?: string[];   // e.g., ['H7225']
  gematria?: GematriaValues;  // Computed on-demand
  metadata?: Record<string, unknown>;
}

Creating a Data Source Package

To create your own scripture data source:

import { registerSource, type ScriptureSource } from '@metaxia/scriptures-core';

const mySource: ScriptureSource = {
  edition: 'my-edition',
  metadata: {
    name: 'My Edition',
    language: 'Hebrew',
    description: 'Custom scripture edition',
  },
  loadVerse: async (book, chapter, verse) => {
    // Return VerseData
  },
  loadChapter: async (book, chapter) => {
    // Return VerseData[]
  },
  loadCache: async (cacheName) => {
    // Return cached data or throw
  },
  listBooks: () => ['Genesis', 'Exodus', ...],
};

registerSource(mySource);

Sources and Citations

The Hebrew gematria and temurah implementations in this library are derived exclusively from primary historical sources in the public domain.

Primary Sources

Jewish Encyclopedia (1906)

The foundational source for gematria system definitions.

Schechter, Solomon, and Caspar Levias. "Gematria." The Jewish Encyclopedia: A Descriptive Record of the History, Religion, Literature, and Customs of the Jewish People from the Earliest Times to the Present Day, edited by Isidore Singer, vol. 5, Funk and Wagnalls, 1906, pp. 589–592.

• Online: jewishencyclopedia.com/articles/6564-gematria
• Archive.org: archive.org/details/the-jewish-encyclopedia-vol.-5 (pages 589–592)
• License: Public Domain (published 1906, copyright expired)

Systems derived from JE (1906):

• §E.1: Mispar Hechrachi (Normal Value)
• §E.2: Mispar Katan (Cyclical/Minor Value)
• §E.3: Mispar Kolel (Inclusive Value)
• §E.4: Musafi modifier (Additory Value)
• §E.6: Mispar Perati (Square Value of Letter)
• §E.10: Mispar Chitzon (External Value)
• §E.11: Mispar Gadol (Major Value)
• §E.15: Mispar Meshulash (Cube Value of Letter)
• §II.2: Atbash cipher

Pardes Rimonim (1548)

Historical primary source for additional systems.

Cordovero, Moses ben Jacob. Pardes Rimonim [פרדס רמונים], Gate 30 ("Sha'ar ha-Gematria"), Chapters 5–8. Safed, 1548.

• Online: sefaria.org/Pardes_Rimmonim.30
• License: Public Domain (published 1548)

Systems derived from Pardes Rimonim:

• Gate 30, Ch. 8: Mispar HaKadmi (Prior Value)
• Gate 30, Ch. 8: Mispar Siduri (Ordinal Value, implicit)
• Gate 30, Ch. 5: Albam cipher
• Gate 30, Ch. 5–6: Atbash cipher

Derivation Notes

All letter-value tables are computed from explicit statements in the sources. Where a source describes a method without enumerating all values (e.g., JE §E.11 says "finals count as hundreds" without listing 500–900), the values are derived by applying the stated method to the standard Hebrew alphabet. Such derivations are documented in the source code.

License

MIT