{"id":25019052,"url":"https://github.com/sillsdev/scripture","last_synced_at":"2026-03-08T22:15:14.615Z","repository":{"id":176787645,"uuid":"658572660","full_name":"sillsdev/scripture","owner":"sillsdev","description":"TypeScript port of the 'libpalaso/SIL.Scripture' library that provides classes for working with Scripture data such as references and versifications.","archived":false,"fork":false,"pushed_at":"2025-04-30T21:48:05.000Z","size":567,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-08-14T19:35:30.889Z","etag":null,"topics":["js","language","linguistics","reference","scripture","scripture-open-components","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/sillsdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2023-06-26T04:33:21.000Z","updated_at":"2025-04-30T21:47:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"4ba7134a-ab82-4ea6-b68c-d213537008b3","html_url":"https://github.com/sillsdev/scripture","commit_stats":null,"previous_names":["sillsdev/scripture"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/sillsdev/scripture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fscripture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fscripture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fscripture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fscripture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sillsdev","download_url":"https://codeload.github.com/sillsdev/scripture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fscripture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275198474,"owners_count":25422334,"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","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["js","language","linguistics","reference","scripture","scripture-open-components","typescript"],"created_at":"2025-02-05T11:19:53.380Z","updated_at":"2026-03-08T22:15:09.579Z","avatar_url":"https://github.com/sillsdev.png","language":"TypeScript","readme":"# scripture\n\n\u003cdiv align=\"center\"\u003e\n\n[![Build Status][github-actions-status]][github-actions-url]\n[![CodeQL][gitghub-codeql-status]][gitghub-codeql-url]\n[![codecov][github-codecov-status]][github-codecov-url]\n[![Github Tag][github-tag-image]][github-tag-url]\n\n\u003c/div\u003e\n\nTypeScript partial port of the C# library [libpalaso/SIL.Scripture][github-libpalaso-scripture]. These libraries are used by [Paratext](https://paratext.org/) and provides classes for working with Scripture data such as references and versifications.\n\nv1 is a minimal partial port in TypeScript that supports use on the frontend while still using the full C# version on the backend.\n\n## Features\n\n- {object} Canon - Canon information. Also, contains static information on complete list of books.\n- {class} VerseRef - Stores a reference to a specific verse in Scripture.\n  - Represents a single reference, e.g. `'GEN 2:3'`.\n  - Represents a reference range, e.g. `'LUK 3:4-5'`.\n  - Represents a reference sequence, e.g. `'GEN 1:1-3,5'`.\n  - Represents a reference with a segment, e.g. `'LUK 3:4b'`.\n  - Validate references.\n  - Supports versification types: Unknown, Original, Septuagint, Vulgate, English, RussianProtestant, RussianOrthodox.\n\n## Installation\n\n```sh\nnpm install @sillsdev/scripture\n```\n\n## Usage\n\n### VerseRef\n\nThere are lots of options to construct a `VerseRef`. If an appropriate versification is not supplied, a default one will be used (defaults to English):\n\n```typescript\nimport { ScrVers, VerseRef } from '@sillsdev/scripture';\n\n// construct from book, chapter and verse numbers (with specific versification)\nlet verseRef = new VerseRef(1, 2, 3, ScrVers.Septuagint);\nconsole.log(verseRef.valid); // true\n\n// construct from book, chapter and verse strings (default versification)\nverseRef = new VerseRef('LUK', '3', '4b-5a');\nconsole.log(verseRef.versification); // VerseRef.defaultVersification (ScrVers.English)\n\n// construct from a single verse string (with range and segments)\nverseRef = new VerseRef('LUK 3:4b-5a');\nconsole.log(verseRef.chapterNum); // 3\nconsole.log(verseRef.verse); // '4b-5a'\nconsole.log(verseRef.verseNum); // 4\n\n// construct from a bbbcccvvv number\nverseRef = new VerseRef(42003004);\nconsole.log(verseRef.bookNum); // 42\nconsole.log(verseRef.chapterNum); // 3\nconsole.log(verseRef.verseNum); // 4\n\n// construct from an existing VerseRef\nverseRef = new VerseRef(verseRef);\nconsole.log(verseRef.book); // 'LUK'\nconsole.log(verseRef.bookNum); // 42\nconsole.log(verseRef.chapter); // '3'\n\n// construct an empty VerseRef\nverseRef = new VerseRef();\n```\n\n`VerseRef` can be used to validate a reference, such as with user form validation:\n\n```typescript\nfunction isVerseReferenceValid(verseStr: string): boolean {\n  const { verseRef } = VerseRef.tryParse(verseStr);\n  return verseRef.valid;\n}\n\nconsole.log(isVerseReferenceValid('NOOB 200:300')); // false\nconsole.log(isVerseReferenceValid('GEN 2:3')); // true\nconsole.log(isVerseReferenceValid('LUK 3:4b-5a')); // true\n```\n\n`VerseRef` can be JSON stringified and deserialized:\n\n```ts\nlet verseRef = new VerseRef('LUK', '3', '4b-5a');\nconsole.log(JSON.stringify(verseRef)); // '{\"book\":\"LUK\",\"chapterNum\":3,\"verseNum\":4,\"verse\":\"4b-5a\",\"versificationStr\":\"English\"}'\n\nverseRef = new VerseRef(1, 2, 3, ScrVers.Septuagint);\nconsole.log(JSON.stringify(verseRef)); // '{\"book\":\"GEN\",\"chapterNum\":2,\"verseNum\":3,\"versificationStr\":\"Septuagint\"}'\n\nverseRef = VerseRef.fromJSON({\n  book: 'LUK',\n  chapterNum: 3,\n  verseNum: 4,\n  verse: '4b-5a',\n  versificationStr: 'English',\n});\nconsole.log(verseRef.book); // 'LUK'\nconsole.log(verseRef.chapterNum); // 3\nconsole.log(verseRef.verse); // '4b-5a'\n```\n\nUseful properties:\n\n- `book: string` - 3-letter book ID (abbreviation in capital letters), e.g. `'LUK'`\n- `chapter: string` - chapter of the reference, e.g. `'3'`\n- `verse: string` - verse of the reference, including range, segments, and sequences, e.g. `'4'`, or `'4b-5a, 7'`\n- `bookNum: number` - book number, e.g. `42`\n- `chapterNum: number` - chapter number e.g. `3`\n- `verseNum: number` - verse start number, e.g. `4`\n- `versification: ScrVers` - versification of the reference, e.g. `ScrVers.English`\n- `valid: boolean` - Determines if the reference is valid.\n- `validStatus: ValidStatusType` - The valid status for this reference.\n- `BBBCCC: number` - The reference as a comparable integer where the book, chapter, and verse each occupy three digits and the verse is 0, e.g. `42003000`.\n- `BBBCCCVVV: number` - The reference as a comparable integer where the book, chapter, and verse each occupy three digits, e.g. `42003004`.\n\nUseful methods and functions:\n\n- `parse(verseStr: string): void` - Parses the reference in the specified string.\n- `simplify(): void` - Simplifies this verse ref so that it has no bridging of verses or verse segments like '1a'.\n- `clone(): VerseRef` - Makes a clone of the reference.\n- `equals(verseRef: VerseRef): boolean` - Compares this `VerseRef` with supplied one.\n- `allVerses(specifiedVersesOnly = false, verseRangeSeparators: string[] = VerseRef.verseRangeSeparators, verseSequenceSeparators: string[] = VerseRef.verseSequenceIndicators): VerseRef[]` - Enumerate all individual verses contained in a VerseRef. Verse ranges are indicated by \"-\" and consecutive verses by \",\"s.\n- `validateVerse(verseRangeSeparators: string[], verseSequenceSeparators: string[]): ValidStatusType` - Validates a verse number using the supplied separators rather than the defaults.\n\nUseful static functions:\n\n- `static isVerseParseable(verse: string): boolean` - Determines if the verse string is in a valid format (does not consider versification).\n- `static tryParse(str: string): { success: boolean; verseRef: VerseRef }` - Tries to parse the specified string into a verse reference.\n- `static getBBBCCCVVV(bookNum: number, chapterNum: number, verseNum: number): number` - Gets the reference as a comparable integer where the book, chapter, and verse each occupy 3 digits.\n\n### Canon\n\n`Canon` contains various useful tools:\n\n```typescript\nimport { Canon } from '@sillsdev/scripture';\n\nconsole.log(Canon.bookIdToNumber('MAT')); // 40\n\nconsole.log(Canon.bookNumberToId(1)); // 'GEN'\nconsole.log(Canon.bookNumberToId(40)); // 'MAT'\n\nconsole.log(Canon.bookNumberToEnglishName(1)); // 'Genesis'\n\nconsole.log(Canon.bookIdToEnglishName('GEN')); // 'Genesis'\n\nconsole.log(Canon.isBookIdValid('MAT')); // true\n\nconsole.log(Canon.isBookNT('MAT')); // true\nconsole.log(Canon.isBookNT(1)); // false\n\nconsole.log(Canon.isBookOT('MAT')); // false\nconsole.log(Canon.isBookOT(1)); // true\n\nconsole.log(Canon.isBookOTNT('MAT')); // true\nconsole.log(Canon.isBookOTNT(1)); // true\n\nconsole.log(Canon.isBookDC('TOB')); // true\nconsole.log(Canon.isBookDC(1)); // false\n\nconsole.log(Canon.isCanonical('XXA')); // false\nconsole.log(Canon.isCanonical(1)); // true\n\nconsole.log(Canon.isExtraMaterial('XXA')); // true\nconsole.log(Canon.isExtraMaterial(1)); // false\n\nconsole.log(Canon.isObsolete(87)); // true\n```\n\n## License\n\n[MIT][github-license] © [SIL International](https://www.sil.org/)\n\n## Future\n\nv3 might include a more complete port of the C# such that it can be used in a node-based backend.\n\n## Contributing\n\nContributions via Pull Request are welcome. Keep changes to porting the C# source. Please port appropriate tests from [libpalaso/SIL.Scripture.Tests][github-libpalaso-scripture-tests] along with the [libpalaso/SIL.Scripture][github-libpalaso-scripture] source code.\n\n\u003c!-- define variables used above --\u003e\n\n[github-actions-status]: https://github.com/sillsdev/scripture/actions/workflows/ci-test-publish.yml/badge.svg\n[github-actions-url]: https://github.com/sillsdev/scripture/actions\n[gitghub-codeql-status]: https://github.com/sillsdev/scripture/actions/workflows/codeql-analysis.yml/badge.svg\n[gitghub-codeql-url]: https://github.com/sillsdev/scripture/actions/workflows/codeql-analysis.yml\n[github-codecov-status]: https://codecov.io/gh/sillsdev/scripture/branch/main/graph/badge.svg?token=N51WM8PR2E\n[github-codecov-url]: https://codecov.io/gh/sillsdev/scripture\n[github-tag-image]: https://img.shields.io/github/tag/sillsdev/scripture.svg?label=version\n[github-tag-url]: https://github.com/sillsdev/scripture/releases/latest\n[github-license]: https://github.com/sillsdev/scripture/blob/main/LICENSE\n[github-libpalaso-scripture]: https://github.com/sillsdev/libpalaso/tree/master/SIL.Scripture\n[github-libpalaso-scripture-tests]: https://github.com/sillsdev/libpalaso/tree/master/SIL.Scripture.Tests\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsillsdev%2Fscripture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsillsdev%2Fscripture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsillsdev%2Fscripture/lists"}