@leelaing/gematria

Reusable gematria calculations for TypeScript and JavaScript with zero runtime dependencies.

Install

npm install @leelaing/gematria

Basic usage

import { calculateGematria } from '@leelaing/gematria';

const result = calculateGematria('In the beginning', 'english-ordinal');

console.log(result.total);
console.log(result.letters);

Calculate every registered cipher

import { calculateAllGematria } from '@leelaing/gematria';

const results = calculateAllGematria('In the beginning');

for (const result of results) {
  console.log(result.system.name, result.total);
}

If only totals are needed:

import { calculateGematriaTotals } from '@leelaing/gematria';

const totals = calculateGematriaTotals('In the beginning');
console.log(totals['english-ordinal']);

Built-in systems

| ID | Name | Mapping | | ------------------------ | ---------------------- | ----------------------------------------------------------------- | | english-ordinal | English Ordinal | A=1 ... Z=26 | | full-reduction | Full Reduction | Ordinal reduced per letter to 1-9 | | reverse-ordinal | Reverse Ordinal | A=26 ... Z=1 | | reverse-full-reduction | Reverse Full Reduction | Reverse ordinal reduced per letter to 1-9 | | sumerian | Sumerian | Ordinal x 6 | | reverse-sumerian | Reverse Sumerian | Reverse ordinal x 6 | | english-extended | English Extended | A-I=1-9, J-R=10-90, S-Z=100-800 | | francis-bacon | Francis Bacon | 24-letter ordinal; I/J and U/V share values | | satanic | Satanic | A=36 ... Z=61 | | agrippa | Agrippa | Historical Latin/Agrippa values adapted to modern English letters | | latin-tiered | Latin Tiered | Modern 26-letter tiered A-Z mapping | | gematrix-jewish | Gematrix Jewish | Gematrix English-letter cipher; J=600, V=700, W=900 | | hebrew-gematria | Hebrew Gematria | Standard absolute values; final forms retain ordinary values | | greek-isopsephy | Greek Isopsephy | Greek alphabetic numerals, including 6, 90, and 900 letters |

Gematrix Jewish versus Hebrew Gematria

gematrix-jewish is the English-letter cipher used by Gematrix. It is not the native-script hebrew-gematria system. They remain separate so an English compatibility calculation cannot silently replace Hebrew-script Gematria.

calculateGematria('simple', 'gematrix-jewish').total; // 214
calculateGematria('שלום', 'hebrew-gematria').total; // 376

Hebrew and Greek

Both systems accept native-script text directly:

calculateGematria('שלום', 'hebrew-gematria').total; // 376
calculateGematria('ΙΗΣΟΥΣ', 'greek-isopsephy').total; // 888

Hebrew vowel points and Greek diacritics are ignored. Hebrew final forms use the same values as their ordinary forms. Greek final sigma is treated as sigma; stigma/digamma, koppa, and sampi are supported as 6, 90, and 900.

Agrippa versus modern tiered mappings

These are intentionally separate. Historical Agrippa-style Latin values place J, V, and W in special high-value positions. Many modern calculators instead use a straight 26-letter units/tens/hundreds progression. Keeping both systems distinct prevents one convention from silently masquerading as the other.

Detailed result

const result = calculateGematria('Love', 'english-ordinal');

Returns an object shaped like:

{
  text: "Love",
  normalizedText: "LOVE",
  system: { /* cipher definition */ },
  total: 54,
  letters: [
    { character: "L", normalized: "L", value: 12, index: 0 },
    { character: "o", normalized: "O", value: 15, index: 1 },
    { character: "v", normalized: "V", value: 22, index: 2 },
    { character: "e", normalized: "E", value: 5, index: 3 }
  ],
  countedCharacters: 4,
  ignoredCharacters: 0
}

Digits

Digits are ignored by default. They can optionally contribute their numeric value:

calculateGematria('ABC 123', 'english-ordinal', {
  includeDigits: true
});

Custom systems

import { calculateGematria, registerGematriaSystem } from '@leelaing/gematria';

registerGematriaSystem({
  id: 'lee-custom',
  name: 'Lee Custom',
  description: 'Example custom cipher',
  aliases: ['lc'],
  values: {
    A: 1,
    B: 10,
    C: 100
  }
});

console.log(calculateGematria('ABC', 'lee-custom').total); // 111
console.log(calculateGematria('ABC', 'lc').total); // 111

Registry API

import {
  getGematriaSystem,
  listGematriaSystems,
  registerGematriaSystem,
  requireGematriaSystem,
  unregisterGematriaSystem
} from '@leelaing/gematria';

The built-in ciphers are registered automatically when the package is imported.

Normalization

Input is case-insensitive where the script has case. Diacritics are decomposed before lookup, so cafe and café calculate identically under English systems, pointed Hebrew is accepted, and accented Greek maps to its base letters. Spaces and punctuation do not contribute to the value.

Development

npm install
npm run check

npm run check performs:

1. TypeScript type checking
2. Unit tests
3. ESM and CommonJS builds
4. A public export-contract test against both built distributions

That final test is deliberate: it catches functions that exist in src/ but accidentally disappear from the published package API.

License

MIT