{"id":26781796,"url":"https://github.com/awoken-bible/reference","last_synced_at":"2025-04-19T13:40:52.561Z","repository":{"id":42893082,"uuid":"207384992","full_name":"awoken-bible/reference","owner":"awoken-bible","description":"NPM package for bible verse reference parsing, formating and meta data","archived":false,"fork":false,"pushed_at":"2024-01-23T13:28:36.000Z","size":1780,"stargazers_count":11,"open_issues_count":7,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-18T16:49:51.622Z","etag":null,"topics":["bible-verse-references","npm-package","parser"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awoken-bible.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.yaml","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-09T19:09:42.000Z","updated_at":"2023-12-28T15:30:22.000Z","dependencies_parsed_at":"2024-10-04T12:58:07.545Z","dependency_job_id":"8378af56-a8d0-48cb-bd0c-dae65d9a1c12","html_url":"https://github.com/awoken-bible/reference","commit_stats":{"total_commits":201,"total_committers":5,"mean_commits":40.2,"dds":"0.45273631840796025","last_synced_commit":"e0f8cbebed05466210dc7c65fd0e55795a0438e4"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awoken-bible%2Freference","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awoken-bible%2Freference/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awoken-bible%2Freference/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awoken-bible%2Freference/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awoken-bible","download_url":"https://codeload.github.com/awoken-bible/reference/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249704700,"owners_count":21313185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bible-verse-references","npm-package","parser"],"created_at":"2025-03-29T08:18:00.021Z","updated_at":"2025-04-19T13:40:52.539Z","avatar_url":"https://github.com/awoken-bible.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":" # Awoken Bible Reference [![Build Status](https://travis-ci.org/awoken-bible/reference.svg?branch=master)](https://travis-ci.org/awoken-bible/reference) [![Coverage Status](https://coveralls.io/repos/github/awoken-bible/reference/badge.svg?branch=master)](https://coveralls.io/github/awoken-bible/reference?branch=master)\n\n_Bible verse reference parsing, formating and manipulation_\n\n[Click for public API reference docs](https://awoken-bible.github.io/reference/index.html).\n\n## Quick Start Guide\n\n### Node JS\n\nTo use the default versification scheme, simple import the libary and use the global [API functions](https://awoken-bible.github.io/reference/index.html).\n\n```typescript\nimport AwokenRef from 'awoken-bible-reference';\n\nlet vref = AwokenRef.parseOrThrow('Genesis 1');\nif(AwokenRef.countVerses(vref) \u003e 10)){\n\tvref = AwokenRef.firstNVerses(vref, 10);\n}\nvref = AwokenRef.getIntersection(vref, AwokenRef.parseOrThrow('GEN 1 v6,9-20'));\n\n// Print as human readable verse reference (IE: \"Genesis 1:6,9-10\")\nconsole.log(AwokenRef.format(vref));\n\n// Print as url encodable reference (IE: \"gen1v6,9-10\")\nconsole.log(AwokenRef.format(vref, { url: true }));\n\n// Inspect the object, will yield:\n// [ { book: 'GEN', chapter: 1, verse: 6 },\n//   { is_range : true,\n//     start    : { book: 'GEN', chapter: 1, verse:  9 },\n//     end      : { book: 'GEN', chapter: 1, verse: 10 },\n//   }\n// ]\nconsole.dir(vref);\n```\n\nNon-standard versification schemes can be used by instead creating an instance of the library. This allows support to be added for the Apocrypha, or translations that use a different split of verses per chapter.\n\n```typescript\nimport __AwokenRef__ from 'awoken-bible-reference';\n\nconst AwokenRef = new __AwokenRef__(my_versificaton);\n\nlet vref = AwokenRef.parse('MyBook 100:999');\n```\n\nThe full list of methods on the `AwokenRef` object can be found in the [API docs](https://awoken-bible.github.io/reference/index.html).\n\n### Browser\n\nIf using plain javascript in the browser with no build-system to bundle your dependencies, you may simply reference the file found in `./dist.browser/awoken-ref.js`.\n\nThis will create a global \"AwokenRef` variable, which can be used as both an instance of the library, and a constructor to create new instances with non-default versification schemes.\n\n```html\n\n\u003cscript src=\"[path]/awoken-ref.js\"/\u003e\n\n\n\u003cscript\u003e\n\tvar refs = AwokenRef.parseOrThrow('Tobit 1.1'); // error!\n\n\tvar lib = new AwokenRef(myCustomVersificationWithApocrytha);\n\tvar myRefs = lib.parseOrThrow('Tobit 1.1'); // success!\n\u003c/script\u003e\n```\n\n# Type Representations\n\n## Bible Verses\n\n`awoken-bible-reference` can represent (and convert between) the following representations of a Bible verse:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eWhat\u003c/th\u003e\n\u003cth\u003eTypescript Type\u003c/th\u003e\n\u003cth\u003eExample 1\u003c/th\u003e\n\u003cth\u003eExample 2\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eHuman readable string\u003c/td\u003e\n\u003ctd\u003estring\u003c/td\u003e\n\u003ctd\u003eGenesis 1:1\u003c/td\u003e\n\u003ctd\u003eRevelation 22:21\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eVerse Index\u003c/td\u003e\n\u003ctd\u003enumber\u003c/td\u003e\n\u003ctd\u003e0\u003c/td\u003e\n\u003ctd\u003e33021\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003eJSON\u003c/td\u003e\n\u003ctd\u003e\n\n```typescript\ninterface BibleVerse {\n  book    : string,\n  chapter : number,\n  verse   : number,\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```json\n{\n  \"book\"    : \"GEN\",\n  \"chapter\" : 1,\n  \"verse\"   : 1,\n}\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```json\n{\n  \"book\"    : \"REV\",\n  \"chapter\" : 22,\n  \"verse\"   : 21,\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e Note that the verse index representation should be avoided unless you are sure that all translations you care about utalize the exact same [versification scheme](https://en.wikipedia.org/wiki/Chapters_and_verses_of_the_Bible). While it is useful for assigning unique IDs and computing offsets etc, it should probably not be used as a portable data exchange format.\n\nThe `book` field is always a 3 character mix of upper case letters and digits, as per the [USFM specification](https://ubsicap.github.io/usfm/identification/books.html).\n\n## BibleRanges\n\nBibleRanges are represented by an object of the form:\n\n```typescript\n/** Representation of continous block of verses */\ninterface BibleRange {\n\tis_range : true,\n\tstart    : BibleVerse,\n\tend      : BibleVerse,\n};\n```\n\n## Mixed Sets\n\nNote that most API function can take either `BibleRange` or `BibleVerse` objects (or lists thereof), and thus the `is_range` field can be used to easily distinguish the types from one another.\n\nThe following union type is also exported for convenience:\n\n```typescript\n/** Generic reference to verse or range */\ntype BibleRef = BibleVerse | BibleRange;\n```\n\n# Overview of Functionality\n\nAPI methods include functionality to:\n\n- Parse partial references, ranges, and comma separated lists there of:\n  - `Genesis 1:1-10,12, 2:14`\n  - `EXO 3:1 - DEU 4:1`\n  - `Matt 1; Luke3.16; Mark 1 v 2-3,5`\n- Generate verbose human readable reference strings, and compact URL encodable equivalents\n  - `Genesis 10 v6-10` vs `gen10v6-10`\n  - `Song of Solomon` vs `sng`\n- Validate and fix references, including out of range chapters and verses, and inverted ranges:\n  - `validate({book: 'GEN', chapter: 51, verse: 1})`\u003cbr/\u003e\n     becomes\u003cbr/\u003e\n    `{ message: \"Genesis has only 50 chapters\", got: 51, max_value: 50, ... }`\n  - `fixErrors({book: 'GEN', chapter: 51, verse: 1})`\u003cbr/\u003e\n     becomes\u003cbr/\u003e\n    `{book: 'GEN', chapter: 50, verse: 26}`\n- Sorting a list of references\n- Counting the number of verses in a list of `BibleRef` instances\n- Iterating/Splitting by book/chapter/verse\n- Truncating a list of `BibleRef`s to contain only the first N verses (useful for pagination, or short previews of a longer text)\n- Combining/Simplifying ranges, as well as finding the intersection/union of ranges\n\nFor a full list of the exported functions and data types, see the [generated typedoc API reference](https://awoken-bible.github.io/reference/index.html).\n\n# Build Targets\n\nThe published copy of this library multiple output targets. Node.js projects should autoload the correct version, and there also exists a browser bundle.\n\n\n- `dist/awoken-ref.cjs.js` - CommonJS module loadable via require() in nodejs project - built via esbuild\n- `dist/awoken-ref.esm.mjs` - ESModule loadable via import() in nodejs type=module projects - built via esbuild\n- `dist/awoken-ref.min.js` - Browser bundle, loadable via `\u003cscript\u003e` tag, and will create a global AwokenRef variable with attached functions using the default versification, or you can create a new instance with `new AwokenRef(customVersification)` - built via webpack/babel\n- `dist/types` - Contains typescript declaration (.d.ts) files - package.json is setup such that these should be auto-loaded by typescript consumers of this library\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawoken-bible%2Freference","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawoken-bible%2Freference","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawoken-bible%2Freference/lists"}