npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ephrem

v0.11.0

Published

Ephrem is a light-weight API wrapper for API.Bible, built using NodeJS and Typescript. Ephrem validates bible references and fetches scripture text corresponding to the references.

Downloads

841

Readme

Ephrem is a powerful, lightweight NodeJS package designed to provide seamless access to the Bible’s rich and diverse content from multiple translations and languages, leveraging the API.Bible service. Whether you are a developer creating Bible-based applications, a scholar seeking quick access to scripture, or a layperson wanting to deepen your understanding of the Word, Ephrem allows you to easily fetch Bible passages using standard references. It supports both modern and ancient translations, making it an invaluable resource for all.

This package is uniquely equipped to handle citations in left-to-right (LTR) and right-to-left (RTL) scripts, making it essential for users across various linguistic backgrounds, including English, Arabic, Malayalam, and more. Additionally, Ephrem allows you to customize Bible abbreviations, ensuring your application or study tool can adapt to local preferences and regional variations in Bible translation names.

Ephrem will remain non-commercial and open-source, dedicated to glorifying God and providing accessible scripture for everyone.

Features

  1. Multilingual Support with RTL/LTR Compatibility

Ephrem accommodates citations in various languages, recognizing both left-to-right (LTR) and right-to-left (RTL) scripts. This ensures that users around the world can access scripture in their native languages and scripts without losing accuracy or clarity. Examples include:

  • "John 3-4 (KJV)" or "(KJV) إنجيل يوحنا 3-4" to retrieve the same passages from the Gospel of John, Chapters 3-4, in the King James Version (KJV).
  • "John 3-4 (MAL10RO)", "യോഹന്നാൻ 3-4 (MAL10RO)" or "(MAL10RO) إنجيل يوحنا 3-4" to fetch the same chapters in the Malayalam Sathyavedapusthakam (മലയാളം സത്യവേദപുസ്തകം) 1910 Edition.
  1. Customizable Bible Abbreviations

The package offers flexibility in specifying custom Bible abbreviations, allowing users to override default abbreviations with those more familiar to their region or language.

For example, if the official abbreviation of a Bible is in English characters, you can define a local-language abbreviation that suits your needs.

  1. Passage Options for Flexible Output

Ephrem supports the options from API.Bible to control the format and content of the retrieved scripture text. These options give you control over how much information is displayed, whether you want a plain text version of scripture or a more detailed format that includes chapter and verse numbers, notes, and titles.

  1. Support for Deuterocanonical Books and USFM Codes
  • Ephrem makes it easy to fetch passages from the Deuterocanonical books, ensuring that translations and traditions that include these additional texts are fully supported.
  • It also supports citations using USFM Book codes, widely used in many digital Bible formats, ensuring compatibility with a variety of Bible texts and formats.
  1. Integration with Other Tools

Ephrem can easily be integrated with frameworks like MDX and React to display and share scripture on web applications. This allows developers to create interactive Bible study tools, responsive applications, and engaging content that can enhance spiritual learning.

Usage

Installation

To install Ephrem, run the following command:

npm i ephrem

Setup (One-time Configuration)

Before using Ephrem, you’ll need to configure it by fetching Bible and book data for the languages you need from API.Bible. The package requires the API.Bible API key to be set as an environment variable.

Setting the API_BIBLE_API_KEY Environment Variable

Follow the steps below based on your platform to set the environment variable.

Windows
  1. Open Start and search for “Environment Variables”.
  2. Click on Edit the system environment variables.
  3. In the System Properties window, click Environment Variables.
  4. Under User variables, click New.
  5. Set the Variable name to API_BIBLE_API_KEY and the Variable value to your API.Bible key.
  6. Click OK to save.

Alternatively, if you are using PowerShell, you can set it temporarily with:

$env:API_BIBLE_API_KEY = "your-api-bible-key"
macOS / Linux
  1. Open a Terminal.
  2. Use the following command to set the environment variable temporarily (only for the current session):
export API_BIBLE_API_KEY="your-api-bible-key"
  1. To set the environment variable permanently, add the above line to your shell configuration file:
  • If using bash, add it to your ~/.bashrc or ~/.bash_profile.
  • If using zsh, add it to your ~/.zshrc.

Setting Up Ephrem

Once the environment variable is set, run the setup-ephrem command to fetch and store Bible data for the languages you need:

setup-ephrem -l eng,mal,arb

-l or --languages must be used to specify a comma-separated list of language IDs (ISO-639-3; lower case). Default is eng. The above-mentioned command will set up Ephrem for English, Malayalam, and Arabic languages.

The API key is securely picked up from the API_BIBLE_API_KEY environment variable. This setup will download the necessary Bible data and store it for efficient future use.

Fetching a Bible Passage

To retrieve a Bible passage with additional details about the Bible and the Book referenced, use the getPassageWithDetails function. The second parameter allows you to pass in custom PassageOptions (such as contentType: text), giving you control over the format of the retrieved passage.

import { getPassageWithDetails } from "ephrem";

getPassageWithDetails("John 3:16 (KJV)", {
	contentType: "text",
	includeTitles: false,
})
	.then((details) => {
		console.log(`- - ${details.passage.reference} - -`);
		console.log(details.passage.content);
	})
	.catch((err) => console.error(`Error fetching passage: ${err.message}`));
- - John 3:16 - -
     [16] ¶ For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.
import { getPassageWithDetails } from "ephrem";

getPassageWithDetails("Tobit 13:6 (engLXXup)", {
	contentType: "text",
	includeTitles: false,
})
	.then((details) => {
		console.log(`- - ${details.passage.reference} - -`);
		console.log(details.passage.content);
	})
	.catch((err) => console.error(`Error fetching passage: ${err.message}`));
- - Tobit 13:6 - -
     [6] If ye turn to him with your whole heart, and with your whole mind, and deal uprightly before him, then will he turn unto you, and will not hide his face from you. Therefore see what he will do with you, and confess him with your whole mouth, and praise the Lord of might, and extol the everlasting King. In the land of my captivity do I praise him, and declare his might and majesty to a sinful nation. O ye sinners, turn and do justice before him: who can tell if he will accept you, and have mercy on you?
import { getPassageWithDetails } from "ephrem";

getPassageWithDetails("Genesis 1:1-2 (MAL10RO)", {
	contentType: "text",
	includeTitles: false,
})
	.then((details) => {
		console.log(`- - ${details.passage.reference} - -`);
		console.log(details.passage.content);
	})
	.catch((err) => console.error(`Error fetching passage: ${err.message}`));
- - ഉല്പത്തി 1:1-2 - -
     [1] ആദിയിൽ ദൈവം ആകാശവും ഭൂമിയും സൃഷ്ടിച്ചു.  [2] ഭൂമി പാഴായും ശൂന്യമായും ഇരുന്നു; ആഴത്തിന്മീതെ ഇരുൾ ഉണ്ടായിരുന്നു. ദൈവത്തിന്റെ ആത്മാവു വെള്ളത്തിൻ മീതെ പരിവർത്തിച്ചുകൊണ്ടിരുന്നു.

Customizing Bible Abbreviations

If you want to provide custom labels or abbreviations for Bible translations, you can use the getBibleAbbreviationsFilepath function to retrieve the path to the Bible abbreviations file:

import { getBibleAbbreviationsFilepath } from "ephrem";

console.log(`Bible Abbreviations Filepath: ${getBibleAbbreviationsFilepath()}`);

This allows you to customize how users refer to different Bible versions, ensuring a more localized and user-friendly experience.

Contributing

We welcome contributions from developers, theologians, and anyone interested in improving access to the scriptures. Please feel free to submit pull requests or report issues.

License

Ephrem is licensed under the MIT License, which is widely regarded as one of the most user-friendly open-source licenses. Here’s why:

  • Freedom to Use: You are free to use, copy, modify, and distribute this package in both personal and commercial projects without restrictions.
  • Minimal Restrictions: The license ensures you can build upon the package or integrate it into larger applications, while simply requiring that the original license text is retained in the distribution.
  • Flexibility for Innovation: The MIT License encourages collaboration and innovation by making it easy for developers and scholars to adapt Ephrem to their specific needs, without legal concerns.
  • Open to Contributions: You can contribute back to the project or fork it, fostering a community of shared knowledge.

Contributors

💙 This package was templated with create-typescript-app.