@eightyfourthousand/data-access 2026.3.1 → 2026.4.0

package/src/lib/replace.spec.ts

@@ -0,0 +1,154 @@
+import type { Annotation, Passage } from './types';
+import {
+  findLiteralOccurrences,
+  getPassageOccurrences,
+  replacePassageText,
+} from './replace';
+
+const createAnnotation = ({
+  end,
+  start,
+  uuid,
+}: {
+  end: number;
+  start: number;
+  uuid: string;
+}): Annotation => ({
+  end,
+  start,
+  passageUuid: 'passage-1',
+  type: 'paragraph',
+  uuid,
+});
+
+const createPassage = (
+  content: string,
+  annotations: Annotation[] = [],
+): Passage => ({
+  annotations,
+  content,
+  label: '1.1',
+  sort: 1,
+  type: 'translation',
+  uuid: 'passage-1',
+  workUuid: 'work-1',
+});
+
+describe('findLiteralOccurrences', () => {
+  it('returns non-overlapping matches in order', () => {
+    expect(findLiteralOccurrences('aba aba aba', 'aba')).toEqual([
+      { start: 0, end: 3 },
+      { start: 4, end: 7 },
+      { start: 8, end: 11 },
+    ]);
+  });
+
+  it('returns no matches for an empty search string', () => {
+    expect(findLiteralOccurrences('abc', '')).toEqual([]);
+  });
+});
+
+describe('getPassageOccurrences', () => {
+  it('flattens matches across passages with stable indices', () => {
+    expect(
+      getPassageOccurrences(
+        [
+          { uuid: 'p1', content: 'foo foo' },
+          { uuid: 'p2', content: 'foo' },
+        ],
+        'foo',
+      ),
+    ).toEqual([
+      { passageUuid: 'p1', start: 0, end: 3, index: 0, passageOccurrenceIndex: 0 },
+      { passageUuid: 'p1', start: 4, end: 7, index: 1, passageOccurrenceIndex: 1 },
+      { passageUuid: 'p2', start: 0, end: 3, index: 2, passageOccurrenceIndex: 0 },
+    ]);
+  });
+});
+
+describe('replacePassageText', () => {
+  it('replaces one indexed occurrence inside a single passage', () => {
+    const result = replacePassageText({
+      passage: createPassage('foo foo foo'),
+      searchText: 'foo',
+      replaceText: 'bar',
+      occurrenceIndex: 1,
+    });
+
+    expect(result.passage.content).toBe('foo bar foo');
+    expect(result.replacementsApplied).toBe(1);
+  });
+
+  it('replaces all occurrences when no occurrence index is provided', () => {
+    const result = replacePassageText({
+      passage: createPassage('foo foo'),
+      searchText: 'foo',
+      replaceText: 'x',
+    });
+
+    expect(result.passage.content).toBe('x x');
+    expect(result.replacementsApplied).toBe(2);
+  });
+
+  it('preserves an annotation spanning across replaced text', () => {
+    const result = replacePassageText({
+      passage: createPassage('0123456789', [
+        createAnnotation({ uuid: 'a1', start: 1, end: 9 }),
+      ]),
+      searchText: '345',
+      replaceText: 'XX',
+    });
+
+    expect(result.passage.annotations[0]).toMatchObject({ start: 1, end: 8 });
+    expect(result.updatedAnnotationCount).toBe(1);
+  });
+
+  it('clamps an annotation that overlaps the left edge of the replaced range', () => {
+    const result = replacePassageText({
+      passage: createPassage('0123456789', [
+        createAnnotation({ uuid: 'a1', start: 2, end: 4 }),
+      ]),
+      searchText: '345',
+      replaceText: 'XYZ',
+    });
+
+    expect(result.passage.annotations[0]).toMatchObject({ start: 2, end: 6 });
+  });
+
+  it('shifts annotations that occur entirely after the replaced text', () => {
+    const result = replacePassageText({
+      passage: createPassage('0123456789', [
+        createAnnotation({ uuid: 'a1', start: 8, end: 10 }),
+      ]),
+      searchText: '34',
+      replaceText: 'ABCDE',
+    });
+
+    expect(result.passage.annotations[0]).toMatchObject({ start: 11, end: 13 });
+  });
+
+  it('deletes an annotation that is fully removed by an empty replacement', () => {
+    const result = replacePassageText({
+      passage: createPassage('abc', [
+        createAnnotation({ uuid: 'a1', start: 0, end: 3 }),
+      ]),
+      searchText: 'abc',
+      replaceText: '',
+    });
+
+    expect(result.passage.annotations).toEqual([]);
+    expect(result.deletedAnnotationCount).toBe(1);
+  });
+
+  it('maps an annotation contained within the replaced range onto the inserted replacement', () => {
+    const result = replacePassageText({
+      passage: createPassage('abc def ghi', [
+        createAnnotation({ uuid: 'a1', start: 4, end: 7 }),
+      ]),
+      searchText: 'def',
+      replaceText: 'uvwxyz',
+    });
+
+    expect(result.passage.annotations[0]).toMatchObject({ start: 4, end: 10 });
+  });
+});

package/src/lib/replace.ts

@@ -0,0 +1,244 @@
+import type { Annotation, Passage } from './types';
+
+export interface PassageOccurrence {
+  end: number;
+  index: number;
+  passageOccurrenceIndex: number;
+  passageUuid: string;
+  start: number;
+  type: 'passage' | 'alignment';
+}
+
+export interface PassageReplacementResult {
+  deletedAnnotationCount: number;
+  nextSearchStart?: number;
+  passage: Passage;
+  replacementsApplied: number;
+  updatedAnnotationCount: number;
+}
+
+interface RemapAnnotationsResult {
+  annotations: Annotation[];
+  deletedAnnotationCount: number;
+  updatedAnnotationCount: number;
+}
+
+export const findLiteralOccurrences = (
+  content: string,
+  searchText: string,
+): Array<{ end: number; start: number }> => {
+  if (!searchText) {
+    return [];
+  }
+
+  const matches: Array<{ end: number; start: number }> = [];
+  let fromIndex = 0;
+
+  while (fromIndex <= content.length - searchText.length) {
+    const start = content.indexOf(searchText, fromIndex);
+    if (start === -1) {
+      break;
+    }
+
+    matches.push({
+      start,
+      end: start + searchText.length,
+    });
+    fromIndex = start + searchText.length;
+  }
+
+  return matches;
+};
+
+export const getPassageOccurrences = (
+  passages: { content: string; uuid: string; type: 'passage' | 'alignment' }[],
+  searchText: string,
+): PassageOccurrence[] => {
+  let index = 0;
+
+  return passages.flatMap((passage) =>
+    findLiteralOccurrences(passage.content, searchText).map((match, passageIndex) => ({
+      ...match,
+      index: index++,
+      passageOccurrenceIndex: passageIndex,
+      passageUuid: passage.uuid,
+      type: passage.type,
+    })),
+  );
+};
+
+const mapEditPosition = ({
+  delta,
+  editEnd,
+  editStart,
+  position,
+  replacementLength,
+  stickTo,
+}: {
+  delta: number;
+  editEnd: number;
+  editStart: number;
+  position: number;
+  replacementLength: number;
+  stickTo: 'end' | 'start';
+}) => {
+  if (position <= editStart) {
+    return position;
+  }
+
+  if (position >= editEnd) {
+    return position + delta;
+  }
+
+  return stickTo === 'start' ? editStart : editStart + replacementLength;
+};
+
+const remapAnnotationsForEdit = ({
+  annotations,
+  editEnd,
+  editStart,
+  replacementLength,
+}: {
+  annotations: Annotation[];
+  editEnd: number;
+  editStart: number;
+  replacementLength: number;
+}): RemapAnnotationsResult => {
+  const delta = replacementLength - (editEnd - editStart);
+  const nextAnnotations: Annotation[] = [];
+  let deletedAnnotationCount = 0;
+  let updatedAnnotationCount = 0;
+
+  for (const annotation of annotations) {
+    if (annotation.end <= editStart) {
+      nextAnnotations.push(annotation);
+      continue;
+    }
+
+    if (annotation.start >= editEnd) {
+      nextAnnotations.push({
+        ...annotation,
+        start: annotation.start + delta,
+        end: annotation.end + delta,
+      });
+      updatedAnnotationCount++;
+      continue;
+    }
+
+    const nextStart = mapEditPosition({
+      delta,
+      editEnd,
+      editStart,
+      position: annotation.start,
+      replacementLength,
+      stickTo: 'start',
+    });
+    const nextEnd = mapEditPosition({
+      delta,
+      editEnd,
+      editStart,
+      position: annotation.end,
+      replacementLength,
+      stickTo: 'end',
+    });
+
+    if (nextStart === nextEnd && replacementLength === 0) {
+      deletedAnnotationCount++;
+      continue;
+    }
+
+    if (nextStart !== annotation.start || nextEnd !== annotation.end) {
+      updatedAnnotationCount++;
+      nextAnnotations.push({
+        ...annotation,
+        start: nextStart,
+        end: nextEnd,
+      });
+      continue;
+    }
+
+    nextAnnotations.push(annotation);
+  }
+
+  return {
+    annotations: nextAnnotations,
+    deletedAnnotationCount,
+    updatedAnnotationCount,
+  };
+};
+
+export const replacePassageText = ({
+  occurrenceIndex,
+  passage,
+  replaceText,
+  searchText,
+}: {
+  occurrenceIndex?: number;
+  passage: Passage;
+  replaceText: string;
+  searchText: string;
+}): PassageReplacementResult => {
+  if (!searchText || occurrenceIndex === null) {
+    return {
+      passage,
+      replacementsApplied: 0,
+      updatedAnnotationCount: 0,
+      deletedAnnotationCount: 0,
+    };
+  }
+
+  const matches = findLiteralOccurrences(passage.content, searchText);
+  const matchesToApply =
+    occurrenceIndex === undefined
+      ? matches
+      : matches.filter((_, index) => index === occurrenceIndex);
+
+  if (matchesToApply.length === 0) {
+    return {
+      passage,
+      replacementsApplied: 0,
+      updatedAnnotationCount: 0,
+      deletedAnnotationCount: 0,
+    };
+  }
+
+  let content = passage.content;
+  let annotations = passage.annotations.map((annotation) => ({ ...annotation }));
+  let cumulativeDelta = 0;
+  let updatedAnnotationCount = 0;
+  let deletedAnnotationCount = 0;
+  let nextSearchStart: number | undefined;
+
+  for (const match of matchesToApply) {
+    const editStart = match.start + cumulativeDelta;
+    const editEnd = match.end + cumulativeDelta;
+
+    content =
+      content.slice(0, editStart) + replaceText + content.slice(editEnd);
+
+    const remappedAnnotations = remapAnnotationsForEdit({
+      annotations,
+      editStart,
+      editEnd,
+      replacementLength: replaceText.length,
+    });
+
+    annotations = remappedAnnotations.annotations;
+    updatedAnnotationCount += remappedAnnotations.updatedAnnotationCount;
+    deletedAnnotationCount += remappedAnnotations.deletedAnnotationCount;
+    nextSearchStart = editStart + replaceText.length;
+    cumulativeDelta += replaceText.length - (match.end - match.start);
+  }
+
+  return {
+    passage: {
+      ...passage,
+      content,
+      annotations,
+    },
+    nextSearchStart,
+    replacementsApplied: matchesToApply.length,
+    updatedAnnotationCount,
+    deletedAnnotationCount,
+  };
+};

package/src/lib/types/folio.ts

@@ -3,7 +3,7 @@ export type FolioSide = (typeof FOLIO_SIDES)[number];
 
 export type FolioDTO = {
   folio_uuid: string;
-  content: string;
+  content?: string;
   volume_number: number;
   folio_number: number;
   side: FolioSide;
@@ -20,7 +20,7 @@ export type Folio = {
 export const folioFromDTO = (dto: FolioDTO): Folio => {
   return {
     uuid: dto.folio_uuid,
-    content: dto.content,
+    content: dto.content || '',
     volume: dto.volume_number,
     folio: dto.folio_number,
     side: dto.side,

package/src/lib/types/glossary-page.ts

@@ -62,40 +62,6 @@ export type GlossaryLandingItemDTO = {
   num_glossary_entries?: number;
 };
 
-export type GlossaryDetailDTO = {
-  authority_uuid: string;
-  xmlId?: string;
-  headword: string;
-  headword_language?: GlossaryPageLanguage | null;
-  classifications?: string[] | null;
-  definition?: string | null;
-  tibetan_names?: string[] | null;
-  sanskrit_names?: string[] | null;
-  pali_names?: string[] | null;
-  chinese_names?: string[] | null;
-  english_names?: string[] | null;
-};
-
-export type GlossaryEntityDTO = {
-  related_entity_object_headword: string;
-  related_entity_object_uuid: string;
-  related_entity_subject_headword: string;
-  related_entity_subject_uuid: string;
-};
-
-export type GlossaryInstanceDTO = {
-  glossary_entry_work_uuid: string;
-  glossary_entry_toh: TohokuCatalogEntry;
-  glossary_entry_english?: string | null;
-  glossary_entry_tibetan?: string | null;
-  glossary_entry_sanskrit?: string | null;
-  glossary_entry_chinese?: string | null;
-  glossary_entry_pali?: string | null;
-  glossary_entry_definition?: string | null;
-  glossary_entry_canon?: string | null;
-  glossary_entry_creators?: string[] | null;
-};
-
 export const glossaryLandingItemFromDTO = (
   dto?: GlossaryLandingItemDTO,
 ): GlossaryLandingItem | null => {
@@ -118,87 +84,3 @@ export const glossaryLandingItemFromDTO = (
     numGlossaryEntries: dto.num_glossary_entries || 0,
   };
 };
-
-export const glossaryDetailFromDTO = (
-  dto?: GlossaryDetailDTO,
-): GlossaryDetailItem | null => {
-  if (!dto) {
-    return null;
-  }
-
-  return {
-    authorityUuid: dto.authority_uuid,
-    headword: dto.headword,
-    language: dto.headword_language as GlossaryPageLanguage,
-    classifications: dto.classifications || [],
-    definition: dto.definition || undefined,
-    xmlId: dto.xmlId,
-    english: dto.english_names || [],
-    tibetan: dto.tibetan_names || [],
-    sanskrit: dto.sanskrit_names || [],
-    pali: dto.pali_names || [],
-    chinese: dto.chinese_names || [],
-  };
-};
-
-export const glossaryInstanceFromDTO = (
-  dto?: GlossaryInstanceDTO,
-): GlossaryInstance | null => {
-  if (!dto) {
-    return null;
-  }
-
-  return {
-    workUuid: dto.glossary_entry_work_uuid,
-    toh: dto.glossary_entry_toh,
-    definition: dto.glossary_entry_definition || undefined,
-    canon: dto.glossary_entry_canon || undefined,
-    english: dto.glossary_entry_english ? [dto.glossary_entry_english] : [],
-    tibetan: dto.glossary_entry_tibetan ? [dto.glossary_entry_tibetan] : [],
-    sanskrit: dto.glossary_entry_sanskrit ? [dto.glossary_entry_sanskrit] : [],
-    pali: dto.glossary_entry_pali ? [dto.glossary_entry_pali] : [],
-    chinese: dto.glossary_entry_chinese ? [dto.glossary_entry_chinese] : [],
-    creators: dto.glossary_entry_creators || [],
-  };
-};
-
-export const glossaryEntityFromDTO = (
-  dto?: GlossaryEntityDTO,
-): GlossaryEntity | null => {
-  if (!dto) {
-    return null;
-  }
-
-  return {
-    sourceHeadword: dto.related_entity_subject_headword,
-    sourceUuid: dto.related_entity_subject_uuid,
-    targetHeadword: dto.related_entity_object_headword,
-    targetUuid: dto.related_entity_object_uuid,
-  };
-};
-
-export const glossaryPageItemFromDTO = (
-  detail: GlossaryDetailDTO,
-  instances: GlossaryInstanceDTO[],
-  entities: GlossaryEntityDTO[],
-): GlossaryPageItem => {
-  const detailItem = glossaryDetailFromDTO(detail);
-  if (!detailItem) {
-    throw new Error('Invalid glossary detail item');
-  }
-
-  const relatedInstances =
-    instances
-      .map(glossaryInstanceFromDTO)
-      .filter((i): i is GlossaryInstance => i !== null) || [];
-  const relatedEntities =
-    entities
-      .map(glossaryEntityFromDTO)
-      .filter((e): e is GlossaryEntity => e !== null) || [];
-
-  return {
-    ...detailItem,
-    relatedInstances,
-    relatedEntities,
-  };
-};

package/src/lib/types/glossary.ts

@@ -1,4 +1,3 @@
-
 export type GlossaryItem = {
   authorityUuid: string;
   definition?: string | null;
@@ -46,12 +45,13 @@ export type GlossaryTermInstance = {
     sanskrit?: string;
     tibetan?: string;
     wylie?: string;
+    alternatives?: string;
   };
   passages?: {
     items: Array<{ uuid: string; type: string; label: string }>;
     nextCursor: string | null;
     hasMore: boolean;
-  }
+  };
 };
 
 export type GlossaryTermInstances = GlossaryTermInstance[];
@@ -68,6 +68,7 @@ export type GlossaryTermInstanceDTO = {
     sanskrit?: string;
     tibetan?: string;
     wylie?: string;
+    alternatives?: string;
   };
 };
 

package/src/lib/types/index.ts

@@ -1,9 +1,7 @@
 export * from './alignment';
 export * from './annotation';
 export * from './bibliography';
-export * from './canon';
 export * from './client';
-export * from './contributor';
 export * from './editor-content';
 export * from './toh';
 export * from './folio';
@@ -14,7 +12,6 @@ export * from './language';
 export * from './layout';
 export * from './library';
 export * from './passage';
-export * from './project';
 export * from './semver';
 export * from './title';
 export * from './translation';

package/src/lib/canon.ts

@@ -1,111 +0,0 @@
-import {
-  CanonDTO,
-  CanonDetailDTO,
-  CanonNode,
-  CanonWorksDTO,
-  DataClient,
-  canonDetailFromDTO,
-  canonNodeFromDTO,
-  canonTreeFromDTOs,
-  caononWorksFromDTO,
-} from './types';
-
-export const getCanonSections = async ({
-  client,
-}: {
-  client: DataClient;
-}): Promise<CanonNode[]> => {
-  const { data, error } = await client.rpc('scholar_canon_get_all');
-
-  if (error) {
-    console.error('Error fetching canon sections:', error);
-    return [];
-  }
-
-  return data.map((item: CanonDTO) => canonNodeFromDTO(item));
-};
-
-export const getCanonTree = async ({ client }: { client: DataClient }) => {
-  const { data, error } = await client.rpc('scholar_canon_get_all');
-
-  if (error) {
-    console.error('Error fetching canon tree:', error);
-    return null;
-  }
-
-  return canonTreeFromDTOs(data as CanonDTO[]);
-};
-
-export const getCanonSection = async ({
-  client,
-  uuid,
-}: {
-  client: DataClient;
-  uuid: string;
-}) => {
-  const { data, error } = await client.rpc('scholar_canon_get_detail', {
-    uuid_input: uuid,
-  });
-
-  if (error) {
-    console.error('Error fetching canon section:', error);
-    return null;
-  }
-
-  return canonDetailFromDTO(data[0] as CanonDetailDTO);
-};
-
-export const getCanonWorks = async ({
-  client,
-  uuids,
-}: {
-  client: DataClient;
-  uuids: string[];
-}) => {
-  const { data, error } = await client
-    .rpc('scholar_canon_get_works', {
-      uuids_input: uuids,
-    })
-    .single();
-
-  if (error) {
-    console.error('Error fetching canon works:', error);
-    return null;
-  }
-
-  return caononWorksFromDTO(data as CanonWorksDTO);
-};
-
-/** Travers the canon tree to find a node by its UUID */
-export const findNodeByUuid = (
-  head: CanonNode[],
-  uuid: string,
-): CanonNode | null => {
-  for (const node of head) {
-    if (node.uuid === uuid) {
-      return node;
-    }
-    if (node.children) {
-      const found = findNodeByUuid(node.children, uuid);
-      if (found) {
-        return found;
-      }
-    }
-  }
-  return null;
-};
-
-/** Flatten the canon tree into a list of nodes */
-export const flattenCanonTree = (head: CanonNode): CanonNode[] => {
-  const flatList: CanonNode[] = [head];
-
-  const traverse = (node: CanonNode) => {
-    flatList.push(node);
-    if (node.children) {
-      node.children.forEach(traverse);
-    }
-  };
-
-  head.children?.forEach(traverse);
-  return flatList;
-};