@helloao/tools 0.2.0 → 0.3.0

package/dist/types/parser/usx-parser.d.ts

@@ -1,10 +1,11 @@
 import { Chapter, ChapterContent, FootnoteReference, ParseTree, Verse, Text, HebrewSubtitle, InlineLineBreak } from './types.js';
 import { RewindableIterator } from './iterators.js';
+import { AnnotatedContent } from './words.js';
 /**
  * The version of the parser.
  * Used to determine whether input files need to be re-parsed.
  */
-export declare const PARSER_VERSION = 3;
+export declare const PARSER_VERSION = 4;
 /**
  * Defines a class that is able to parse USX content.
  */
@@ -25,13 +26,13 @@ export declare class USXParser {
     parse(usx: string): ParseTree;
     iterateRootContent(usxElement: Element): Generator<ParseTree['content'][0]>;
     iterateChapterContent(chapter: Chapter, nodes: RewindableIterator<Node>): IterableIterator<ChapterContent>;
-    iterateVerseContent(chapter: Chapter, verse: Verse, nodes: RewindableIterator<Node>, previousVerse?: Verse | null): IterableIterator<string | FootnoteReference | Text | InlineLineBreak>;
+    iterateVerseContent(chapter: Chapter, verse: Verse, nodes: RewindableIterator<Node>, previousVerse?: Verse | null): IterableIterator<string | FootnoteReference | Text | InlineLineBreak | AnnotatedContent<string | Text>>;
     parseVerse(element: Element, chapter: Chapter, nodes: RewindableIterator<Node>): Verse;
     parseHebrewSubtitle(para: Element, chapter: Chapter, nodes: RewindableIterator<Node>): IterableIterator<HebrewSubtitle | Verse>;
-    iterateHebrewSubtitleContent(element: Element, chapter: Chapter, nodes: RewindableIterator<Node>): IterableIterator<Verse | string | Text | FootnoteReference | InlineLineBreak>;
-    iterateNodeTextContent(nodes: RewindableIterator<Node>, node: Node, chapter: Chapter, verse?: Verse): IterableIterator<string | Text | FootnoteReference | InlineLineBreak>;
+    iterateHebrewSubtitleContent(element: Element, chapter: Chapter, nodes: RewindableIterator<Node>): IterableIterator<Verse | string | Text | FootnoteReference | InlineLineBreak | AnnotatedContent<string | Text>>;
+    iterateNodeTextContent(nodes: RewindableIterator<Node>, node: Node, chapter: Chapter, verse?: Verse): IterableIterator<string | Text | FootnoteReference | InlineLineBreak | AnnotatedContent<string | Text>>;
     iterateCharContent(char: Element): IterableIterator<string | Text>;
     iterateNote(nodes: RewindableIterator<Node>, node: Element, chapter: Chapter, verse?: Verse): IterableIterator<FootnoteReference>;
-    iterateChar(nodes: RewindableIterator<Node>, node: Element): IterableIterator<string | Text>;
+    iterateChar(nodes: RewindableIterator<Node>, node: Element): IterableIterator<string | Text | AnnotatedContent<string | Text>>;
 }
 //# sourceMappingURL=usx-parser.d.ts.map

package/dist/types/parser/words.d.ts

@@ -0,0 +1,104 @@
+import { Chapter, ChapterWord } from './types.js';
+/**
+ * The annotations that a source associated with a word, without any information
+ * about where the word is located.
+ */
+export type WordAnnotations = Omit<ChapterWord, 'contentIndex' | 'start' | 'end'>;
+/**
+ * Defines an interface that represents a range of characters within a single
+ * piece of text, along with the annotations that apply to it.
+ */
+export interface WordRange {
+    /**
+     * The index of the first character of the word.
+     */
+    start: number;
+    /**
+     * The index after the last character of the word.
+     */
+    end: number;
+    /**
+     * The annotations that apply to the word.
+     */
+    annotations: WordAnnotations;
+}
+/**
+ * Defines an interface that pairs a piece of verse content with the word
+ * annotations that apply to it, so that the annotations can be passed along
+ * with the content while it is being parsed.
+ *
+ * The ranges are relative to the text of the content, and are never included in
+ * the final parse tree.
+ */
+export interface AnnotatedContent<T> {
+    /**
+     * The content that the annotations apply to.
+     */
+    annotatedContent: T;
+    /**
+     * The ranges of the content that are annotated.
+     */
+    words: WordRange[];
+}
+/**
+ * Determines whether the given value is content that has word annotations
+ * attached to it.
+ * @param value The value to test.
+ */
+export declare function isAnnotatedContent(value: unknown): value is AnnotatedContent<unknown>;
+/**
+ * Reads the word annotations that are attached to the given element.
+ * Returns null if the element doesn't have any recognized annotations.
+ * @param element The element to read the annotations from.
+ */
+export declare function readWordAnnotations(element: Element): WordAnnotations | null;
+/**
+ * Shrinks the given range so that it doesn't include any leading or trailing
+ * whitespace. Returns null if the range only contains whitespace.
+ * @param text The text that the range is in.
+ * @param start The index of the first character of the range.
+ * @param end The index after the last character of the range.
+ */
+export declare function trimWordRange(text: string, start: number, end: number): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Collapses the whitespace in the given text in the same manner that the
+ * parsers normalize text (each run of whitespace becomes a single space, and the
+ * result is trimmed), and returns a map from the indexes in the given text to
+ * the indexes in the returned text.
+ *
+ * The map contains an entry for every index in the given text, plus one for the
+ * index just past the end of it, so that both ends of a range can be mapped.
+ * @param text The text to collapse.
+ */
+export declare function collapseWhitespaceMap(text: string): {
+    text: string;
+    map: number[];
+};
+/**
+ * Moves the words that apply to the given content item to the indexes that they
+ * have after the item's text was collapsed with collapseWhitespaceMap().
+ * Words that no longer cover any characters are removed.
+ * @param words The words to remap.
+ * @param contentIndex The index of the content item that was collapsed.
+ * @param map The index map that collapseWhitespaceMap() returned.
+ */
+export declare function remapChapterWords(words: ChapterWord[], contentIndex: number, map: number[]): void;
+/**
+ * Removes the words that apply to the given content item, and moves the words
+ * that apply to later items back by one to account for the item being removed.
+ * @param words The words to update.
+ * @param contentIndex The index of the content item that was removed.
+ */
+export declare function removeChapterWordsForContent(words: ChapterWord[], contentIndex: number): void;
+/**
+ * Adds the given words to the chapter for the given verse number.
+ * Does nothing if there are no words.
+ * @param chapter The chapter to add the words to.
+ * @param verseNumber The number of the verse that the words are in.
+ * @param words The words to add.
+ */
+export declare function addChapterWords(chapter: Chapter, verseNumber: number, words: ChapterWord[]): void;
+//# sourceMappingURL=words.d.ts.map

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@helloao/tools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A set of tools for managing HelloAO's Free Bible API",
+  "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
   "exports": {
@@ -49,7 +50,7 @@
   "author": "Kallyn Gowdy <kal@helloao.org>",
   "license": "MIT",
   "dependencies": {
-    "lodash": "4.17.21",
+    "es-toolkit": "1.46.1",
     "zod": "^4.4.3",
     "papaparse": "5.4.1"
   },