@eightyfourthousand/data-access 2026.3.0 → 2026.4.0

package/src/lib/passage/save.ts

@@ -0,0 +1,324 @@
+import {
+  ANNOTATIONS_TO_IGNORE,
+  DataClient,
+  Passage,
+  passagesToDTO,
+  passagesToRowDTO,
+} from '../types';
+
+const SAVE_PAGE_SIZE = 500;
+
+export const savePassages = async ({
+  client,
+  passages,
+}: {
+  client: DataClient;
+  passages: Passage[];
+}) => {
+  /**
+   * 1. Extract all annotations from savePassages
+   * 2. Query the database for all current annotations for the savePassages
+   * 3. Determine which annotations need to be deleted or upserted
+   * 4. Upsert the passages
+   * 5. Upsert the annotations
+   * 6. Delete the annotations that are no longer present
+   */
+  const dtos = passagesToDTO(passages);
+  const passageRowDtos = passagesToRowDTO(passages);
+  const passageUuids = passages.map((p) => p.uuid);
+  const annotations = dtos.flatMap((p) => p.annotations || []);
+
+  const { data: existingAnnotations } = await client
+    .from('passage_annotations')
+    .select(`uuid`)
+    .in('passage_uuid', passageUuids)
+    .not('type', 'in', `(${ANNOTATIONS_TO_IGNORE.join(',')})`);
+
+  const annotationsToDelete = existingAnnotations?.filter(
+    (ea) => !annotations.find((a) => a.uuid === ea.uuid),
+  );
+
+  const { error: passageError } = await client
+    .from('passages')
+    .upsert(passageRowDtos, { onConflict: 'uuid' });
+
+  if (passageError) {
+    console.error('Error saving passages:', passageError);
+    return;
+  }
+
+  if (annotations.length > 0) {
+    const { error: annotationError } = await client
+      .from('passage_annotations')
+      .upsert(annotations, { onConflict: 'uuid' });
+
+    if (annotationError) {
+      console.error('Error saving annotations:', annotationError);
+      throw annotationError;
+    }
+  }
+
+  if (annotationsToDelete && annotationsToDelete.length > 0) {
+    const { error: deleteError } = await client
+      .from('passage_annotations')
+      .delete()
+      .in(
+        'uuid',
+        annotationsToDelete.map((a) => a.uuid),
+      );
+
+    if (deleteError) {
+      console.error('Error deleting annotations:', deleteError);
+      throw deleteError;
+    }
+  }
+};
+
+async function normalizePassageLabelsAfter({
+  client,
+  workUuid,
+  fromSort,
+  fromLabel,
+  delta,
+}: {
+  client: DataClient;
+  workUuid: string;
+  fromSort: number;
+  fromLabel: string;
+  delta: number;
+}): Promise<void> {
+  const parts = fromLabel.split('.');
+  const depth = parts.length;
+  const prefix = depth > 1 ? `${parts.slice(0, -1).join('.')}.` : '';
+  let nextInt = Number.parseInt(parts[depth - 1], 10) + Math.max(delta, 0);
+  let lastSort = fromSort;
+  let done = false;
+
+  while (!done) {
+    const { data, error } = await client
+      .from('passages')
+      .select('uuid, label, sort')
+      .eq('work_uuid', workUuid)
+      .gt('sort', lastSort)
+      .order('sort', { ascending: true })
+      .limit(SAVE_PAGE_SIZE);
+
+    if (error || !data || data.length === 0) break;
+
+    const labelUpdates: { uuid: string; label: string }[] = [];
+    const prefixRenames: { oldPrefix: string; newPrefix: string }[] = [];
+
+    for (const row of data) {
+      const rowParts = (row.label ?? '').split('.');
+
+      if (rowParts.length < depth || !row.label?.startsWith(prefix)) {
+        done = true;
+        break;
+      }
+
+      if (rowParts.length > depth) continue;
+
+      const expectedLabel = prefix + nextInt;
+      if (row.label === expectedLabel) {
+        done = true;
+        break;
+      }
+
+      labelUpdates.push({ uuid: row.uuid, label: expectedLabel });
+      prefixRenames.push({
+        oldPrefix: `${row.label}.`,
+        newPrefix: `${expectedLabel}.`,
+      });
+      nextInt++;
+    }
+
+    if (labelUpdates.length > 0) {
+      const { error: upsertError } = await client
+        .from('passages')
+        .upsert(labelUpdates, { onConflict: 'uuid' });
+      if (upsertError) {
+        console.error('Error normalizing passage labels:', upsertError);
+      }
+
+      for (const { oldPrefix, newPrefix } of prefixRenames) {
+        const { error: prefixError } = await client.rpc(
+          'rename_passage_label_prefix',
+          {
+            p_work_uuid: workUuid,
+            p_old_prefix: oldPrefix,
+            p_new_prefix: newPrefix,
+          },
+        );
+        if (prefixError) {
+          console.error('Error renaming passage label prefix:', prefixError);
+        }
+      }
+    }
+
+    if (done || data.length < SAVE_PAGE_SIZE) break;
+    lastSort = data[data.length - 1].sort;
+  }
+}
+
+export type SavePassagesWithDeletionsResult = {
+  success: boolean;
+  savedCount: number;
+  deletedCount?: number;
+  error?: string;
+};
+
+export const savePassagesWithDeletions = async ({
+  client,
+  passages,
+  deletedUuids = [],
+}: {
+  client: DataClient;
+  passages: Passage[];
+  deletedUuids?: string[];
+}): Promise<SavePassagesWithDeletionsResult> => {
+  const inputUuids = passages.map((p) => p.uuid);
+  const { data: existingRows } = await client
+    .from('passages')
+    .select('uuid')
+    .in('uuid', inputUuids);
+  const existingUuidSet = new Set((existingRows ?? []).map((r) => r.uuid));
+  const newPassages = passages.filter((p) => !existingUuidSet.has(p.uuid));
+  const sortedNewPassages = [...newPassages].sort((a, b) => b.sort - a.sort);
+
+  for (const passage of sortedNewPassages) {
+    const { error } = await client.rpc('shift_passage_sorts', {
+      p_work_uuid: passage.workUuid,
+      p_from_sort: passage.sort,
+      p_delta: 1,
+    });
+    if (error) {
+      console.error('Error shifting passage sorts:', error);
+    }
+  }
+
+  for (const passage of sortedNewPassages) {
+    await normalizePassageLabelsAfter({
+      client,
+      workUuid: passage.workUuid,
+      fromSort: passage.sort,
+      fromLabel: passage.label,
+      delta: 1,
+    });
+  }
+
+  let deletedCount = 0;
+  if (deletedUuids.length > 0) {
+    const { data: deletedPassages } = await client
+      .from('passages')
+      .select('uuid, sort, label, work_uuid')
+      .in('uuid', deletedUuids);
+
+    if (deletedPassages && deletedPassages.length > 0) {
+      const sortedDeleted = [...deletedPassages].sort(
+        (a, b) => b.sort - a.sort,
+      );
+      for (const deletedPassage of sortedDeleted) {
+        await normalizePassageLabelsAfter({
+          client,
+          workUuid: deletedPassage.work_uuid,
+          fromSort: deletedPassage.sort,
+          fromLabel: deletedPassage.label,
+          delta: -1,
+        });
+      }
+
+      const { error: deleteAnnotationsError } = await client
+        .from('passage_annotations')
+        .delete()
+        .in('passage_uuid', deletedUuids);
+
+      if (deleteAnnotationsError) {
+        console.error(
+          'Error deleting annotations for deleted passages:',
+          deleteAnnotationsError,
+        );
+      }
+
+      const { error: deletePassagesError } = await client
+        .from('passages')
+        .delete()
+        .in('uuid', deletedUuids);
+
+      if (deletePassagesError) {
+        console.error('Error deleting passages:', deletePassagesError);
+        return {
+          success: false,
+          savedCount: 0,
+          error: `Failed to delete passages: ${deletePassagesError.message}`,
+        };
+      }
+
+      deletedCount = deletedPassages.length;
+    }
+  }
+
+  const dtos = passagesToDTO(passages);
+  const passageRowDtos = passagesToRowDTO(passages);
+  const passageUuids = passages.map((p) => p.uuid);
+  const annotations = dtos.flatMap((p) => p.annotations || []);
+  const { data: existingAnnotations } = await client
+    .from('passage_annotations')
+    .select('uuid')
+    .in('passage_uuid', passageUuids)
+    .not('type', 'in', `(${ANNOTATIONS_TO_IGNORE.join(',')})`);
+
+  const annotationsToDelete = existingAnnotations?.filter(
+    (existingAnnotation) =>
+      !annotations.find(
+        (annotation) => annotation.uuid === existingAnnotation.uuid,
+      ),
+  );
+
+  const { error: passageError } = await client
+    .from('passages')
+    .upsert(passageRowDtos, { onConflict: 'uuid' });
+
+  if (passageError) {
+    console.error('Error saving passages:', passageError);
+    return {
+      success: false,
+      savedCount: 0,
+      error: `Failed to save passages: ${passageError.message}`,
+    };
+  }
+
+  if (annotations.length > 0) {
+    const { error: annotationError } = await client
+      .from('passage_annotations')
+      .upsert(annotations, { onConflict: 'uuid' });
+
+    if (annotationError) {
+      console.error('Error saving annotations:', annotationError);
+      return {
+        success: false,
+        savedCount: passages.length,
+        error: `Passages saved but annotations failed: ${annotationError.message}`,
+      };
+    }
+  }
+
+  if (annotationsToDelete && annotationsToDelete.length > 0) {
+    const { error: deleteError } = await client
+      .from('passage_annotations')
+      .delete()
+      .in(
+        'uuid',
+        annotationsToDelete.map((annotation) => annotation.uuid),
+      );
+
+    if (deleteError) {
+      console.error('Error deleting annotations:', deleteError);
+    }
+  }
+
+  return {
+    success: true,
+    savedCount: passages.length,
+    deletedCount,
+  };
+};

package/src/lib/publications.ts

@@ -1,6 +1,7 @@
 import {
   BodyItemType,
   DataClient,
+  Title,
   TitlesDTO,
   WorkDTO,
   titlesFromDTO,
@@ -14,6 +15,19 @@ import {
   Work,
 } from './types';
 
+type WorksPageInfo = {
+  nextCursor: string | null;
+  prevCursor: string | null;
+  hasMoreAfter: boolean;
+  hasMoreBefore: boolean;
+};
+
+export type WorksPage = {
+  items: Work[];
+  pageInfo: WorksPageInfo;
+  totalCount: number;
+};
+
 export const getTranslationUuids = async ({
   client,
 }: {
@@ -23,6 +37,29 @@ export const getTranslationUuids = async ({
   return data?.map(({ uuid }: { uuid: string }) => uuid) || [];
 };
 
+export const getWorkUuidByToh = async ({
+  client,
+  toh,
+}: {
+  client: DataClient;
+  toh: string;
+}): Promise<string | null> => {
+  const { data, error } = await client
+    .from('work_toh')
+    .select('work_uuid')
+    .eq('toh_clean', toh)
+    .single();
+
+  if (error || !data) {
+    if (error) {
+      console.error('Error fetching work UUID by TOH:', error);
+    }
+    return null;
+  }
+
+  return data.work_uuid ?? null;
+};
+
 export const getTranslationPassages = async ({
   client,
   uuid,
@@ -110,6 +147,54 @@ export const getTranslationTitles = async ({
   return titlesFromDTO(data as TitlesDTO);
 };
 
+export const getWorkTitles = async ({
+  client,
+  uuid,
+}: {
+  client: DataClient;
+  uuid: string;
+}): Promise<Title[]> => {
+  const { data, error } = await client.rpc('get_work_titles', {
+    work_uuid_input: uuid,
+  });
+
+  if (error) {
+    console.error('Error fetching work titles:', error);
+    return [];
+  }
+
+  return titlesFromDTO(data as TitlesDTO);
+};
+
+export const getWorkTitlesByUuids = async ({
+  client,
+  uuids,
+}: {
+  client: DataClient;
+  uuids: readonly string[];
+}): Promise<Map<string, string>> => {
+  const titlesByUuid = new Map<string, string>();
+  if (uuids.length === 0) return titlesByUuid;
+
+  const { data, error } = await client
+    .from('works')
+    .select('uuid, title')
+    .in('uuid', uuids as string[]);
+
+  if (error) {
+    console.error('Error batch loading work titles:', error);
+    return titlesByUuid;
+  }
+
+  for (const work of data ?? []) {
+    if (work.title) {
+      titlesByUuid.set(work.uuid, work.title);
+    }
+  }
+
+  return titlesByUuid;
+};
+
 export const getTranslationMetadataByUuid = async ({
   client,
   uuid,
@@ -211,3 +296,86 @@ export const getTranslationsMetadata = async ({
   const dto = data as WorkDTO[];
   return dto?.map((work) => workFromDTO(work as WorkDTO)) || [];
 };
+
+export const getWorksPage = async ({
+  client,
+  cursor,
+  limit = 50,
+  maxPages,
+}: {
+  client: DataClient;
+  cursor?: string;
+  limit?: number;
+  maxPages?: number;
+}): Promise<WorksPage> => {
+  const clampedLimit = Math.min(limit, 200);
+
+  let query = client
+    .from('works')
+    .select(
+      `
+      uuid,
+      title,
+      description,
+      tohs:work_toh!inner(toh:toh_clean),
+      publicationDate,
+      publicationVersion,
+      pages:source_pages,
+      restriction,
+      breadcrumb
+    `,
+      { count: 'exact' },
+    )
+    .not('toh', 'like', 'toh00%')
+    .order('title', { ascending: true })
+    .limit(clampedLimit + 1);
+
+  if (maxPages) {
+    query = query.lt('source_pages', maxPages);
+  }
+
+  if (cursor) {
+    const { data: cursorWork } = await client
+      .from('works')
+      .select('title')
+      .eq('uuid', cursor)
+      .single();
+
+    if (cursorWork) {
+      query = query.gt('title', cursorWork.title);
+    }
+  }
+
+  const { data, error, count } = await query;
+
+  if (error) {
+    console.error('Error fetching works:', error);
+    return {
+      items: [],
+      pageInfo: {
+        nextCursor: null,
+        prevCursor: null,
+        hasMoreAfter: false,
+        hasMoreBefore: false,
+      },
+      totalCount: 0,
+    };
+  }
+
+  const hasMoreAfter = (data ?? []).length > clampedLimit;
+  const items = hasMoreAfter
+    ? (data ?? []).slice(0, clampedLimit)
+    : (data ?? []);
+  const works = items.map((dto) => workFromDTO(dto as WorkDTO));
+
+  return {
+    items: works,
+    pageInfo: {
+      nextCursor: hasMoreAfter ? (works[works.length - 1]?.uuid ?? null) : null,
+      prevCursor: cursor ?? null,
+      hasMoreAfter,
+      hasMoreBefore: Boolean(cursor),
+    },
+    totalCount: count ?? 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 });
+  });
+});