@eightyfourthousand/data-access 2026.3.0 → 2026.4.0

package/src/lib/passage/pagination.ts

@@ -0,0 +1,277 @@
+import { DataClient, PassageRowDTO } from '../types';
+
+type ApiPaginationDirection = 'FORWARD' | 'BACKWARD' | 'AROUND';
+
+export type PassageConnectionNode = {
+  uuid: string;
+  workUuid: string;
+  content: string;
+  label: string | null;
+  sort: number;
+  type: string;
+  toh: string | null;
+  xmlId: string | null;
+};
+
+export type PassageConnectionPage = {
+  nodes: PassageConnectionNode[];
+  nextCursor: string | null;
+  prevCursor: string | null;
+  hasMoreAfter: boolean;
+  hasMoreBefore: boolean;
+};
+
+const EMPTY_PASSAGE_CONNECTION: PassageConnectionPage = {
+  nodes: [],
+  nextCursor: null,
+  prevCursor: null,
+  hasMoreAfter: false,
+  hasMoreBefore: false,
+};
+
+const DEFAULT_PASSAGE_CONNECTION_LIMIT = 20;
+const MAX_PASSAGE_CONNECTION_LIMIT = 100;
+
+function buildPassageConnection(
+  nodes: PassageConnectionNode[],
+  nextCursor: string | null,
+  prevCursor: string | null,
+  hasMoreAfter: boolean,
+  hasMoreBefore: boolean,
+): PassageConnectionPage {
+  return {
+    nodes,
+    nextCursor,
+    prevCursor,
+    hasMoreAfter,
+    hasMoreBefore,
+  };
+}
+
+function rowToPassageConnectionNode(
+  row: PassageRowDTO,
+  workUuid: string,
+): PassageConnectionNode {
+  return {
+    uuid: row.uuid,
+    workUuid,
+    content: row.content,
+    label: row.label,
+    sort: row.sort,
+    type: row.type,
+    toh: row.toh ?? null,
+    xmlId: row.xmlId ?? null,
+  };
+}
+
+export const getWorkPassagesConnection = async ({
+  client,
+  workUuid,
+  cursor,
+  limit = DEFAULT_PASSAGE_CONNECTION_LIMIT,
+  filter,
+  direction = 'FORWARD',
+}: {
+  client: DataClient;
+  workUuid: string;
+  cursor?: string;
+  limit?: number;
+  filter?: { type?: string; types?: string[]; label?: string };
+  direction?: ApiPaginationDirection;
+}): Promise<PassageConnectionPage> => {
+  const clampedLimit = Math.min(
+    Math.max(limit, 1),
+    MAX_PASSAGE_CONNECTION_LIMIT,
+  );
+
+  if (direction === 'AROUND') {
+    return getWorkPassagesAround({
+      client,
+      workUuid,
+      cursor,
+      limit: clampedLimit,
+      filter,
+    });
+  }
+
+  const isForward = direction === 'FORWARD';
+  let cursorSort: number | null = null;
+  if (cursor) {
+    const { data: cursorPassage } = await client
+      .from('passages')
+      .select('sort')
+      .eq('uuid', cursor)
+      .single();
+
+    if (cursorPassage) {
+      cursorSort = cursorPassage.sort;
+    }
+  }
+
+  let query = client
+    .from('passages')
+    .select('uuid, content, label, sort, type, toh, xmlId, work_uuid')
+    .eq('work_uuid', workUuid)
+    .order('sort', { ascending: isForward })
+    .limit(clampedLimit + 1);
+
+  if (cursorSort !== null) {
+    query = isForward
+      ? query.gt('sort', cursorSort)
+      : query.lt('sort', cursorSort);
+  }
+
+  if (filter?.types && filter.types.length > 0) {
+    query = query.in('type', filter.types);
+  } else if (filter?.type) {
+    query = query.filter('type', 'match', `${filter.type}.*`);
+  }
+
+  if (filter?.label) {
+    query = query.ilike('label', filter.label);
+  }
+
+  const { data, error } = await query;
+
+  if (error) {
+    console.error('Error fetching passages:', error);
+    return EMPTY_PASSAGE_CONNECTION;
+  }
+
+  const passages = (data ?? []) as PassageRowDTO[];
+  const hasMore = passages.length > clampedLimit;
+  let resultPassages = hasMore ? passages.slice(0, clampedLimit) : passages;
+
+  if (!isForward) {
+    resultPassages = resultPassages.reverse();
+  }
+
+  const hasMoreAfter = isForward ? hasMore : cursorSort !== null;
+  const hasMoreBefore = isForward ? cursorSort !== null : hasMore;
+
+  if (resultPassages.length === 0) {
+    return buildPassageConnection([], null, null, false, hasMoreBefore);
+  }
+
+  const nodes = resultPassages.map((row) =>
+    rowToPassageConnectionNode(row, workUuid),
+  );
+  const firstPassage = resultPassages[0];
+  const lastPassage = resultPassages[resultPassages.length - 1];
+
+  return buildPassageConnection(
+    nodes,
+    hasMoreAfter ? lastPassage.uuid : null,
+    hasMoreBefore ? firstPassage.uuid : null,
+    hasMoreAfter,
+    hasMoreBefore,
+  );
+};
+
+export const getWorkPassagesAround = async ({
+  client,
+  workUuid,
+  cursor,
+  limit,
+  filter,
+}: {
+  client: DataClient;
+  workUuid: string;
+  cursor?: string;
+  limit: number;
+  filter?: { type?: string; types?: string[]; label?: string };
+}): Promise<PassageConnectionPage> => {
+  if (!cursor) {
+    console.error('AROUND direction requires a cursor');
+    return EMPTY_PASSAGE_CONNECTION;
+  }
+
+  const { data: cursorPassage } = await client
+    .from('passages')
+    .select('sort')
+    .eq('uuid', cursor)
+    .single();
+
+  if (!cursorPassage) {
+    console.error('Cursor passage not found');
+    return EMPTY_PASSAGE_CONNECTION;
+  }
+
+  const cursorSort = cursorPassage.sort;
+  const limitBefore = Math.floor(limit / 2);
+  const limitAfter = limit - limitBefore;
+  const baseSelect = 'uuid, content, label, sort, type, toh, xmlId, work_uuid';
+
+  let beforeQuery = client
+    .from('passages')
+    .select(baseSelect)
+    .eq('work_uuid', workUuid)
+    .lt('sort', cursorSort)
+    .order('sort', { ascending: false })
+    .limit(limitBefore + 1);
+
+  let afterQuery = client
+    .from('passages')
+    .select(baseSelect)
+    .eq('work_uuid', workUuid)
+    .gte('sort', cursorSort)
+    .order('sort', { ascending: true })
+    .limit(limitAfter + 1);
+
+  if (filter?.types && filter.types.length > 0) {
+    beforeQuery = beforeQuery.in('type', filter.types);
+    afterQuery = afterQuery.in('type', filter.types);
+  } else if (filter?.type) {
+    const pattern = `${filter.type}.*`;
+    beforeQuery = beforeQuery.filter('type', 'match', pattern);
+    afterQuery = afterQuery.filter('type', 'match', pattern);
+  }
+
+  if (filter?.label) {
+    beforeQuery = beforeQuery.ilike('label', filter.label);
+    afterQuery = afterQuery.ilike('label', filter.label);
+  }
+
+  const [beforeResult, afterResult] = await Promise.all([
+    beforeQuery,
+    afterQuery,
+  ]);
+
+  if (beforeResult.error || afterResult.error) {
+    console.error(
+      'Error fetching passages around:',
+      beforeResult.error || afterResult.error,
+    );
+    return EMPTY_PASSAGE_CONNECTION;
+  }
+
+  const passagesBefore = (beforeResult.data ?? []) as PassageRowDTO[];
+  const passagesAfter = (afterResult.data ?? []) as PassageRowDTO[];
+  const hasMoreBefore = passagesBefore.length > limitBefore;
+  const hasMoreAfter = passagesAfter.length > limitAfter;
+  const trimmedBefore = hasMoreBefore
+    ? passagesBefore.slice(0, limitBefore)
+    : passagesBefore;
+  const trimmedAfter = hasMoreAfter
+    ? passagesAfter.slice(0, limitAfter)
+    : passagesAfter;
+  const resultPassages = [...trimmedBefore.reverse(), ...trimmedAfter];
+
+  if (resultPassages.length === 0) {
+    return EMPTY_PASSAGE_CONNECTION;
+  }
+
+  const nodes = resultPassages.map((row) =>
+    rowToPassageConnectionNode(row, workUuid),
+  );
+  const firstPassage = resultPassages[0];
+  const lastPassage = resultPassages[resultPassages.length - 1];
+
+  return buildPassageConnection(
+    nodes,
+    hasMoreAfter ? lastPassage.uuid : null,
+    hasMoreBefore ? firstPassage.uuid : null,
+    hasMoreAfter,
+    hasMoreBefore,
+  );
+};

package/src/lib/passage/read.ts

@@ -0,0 +1,100 @@
+import {
+  DataClient,
+  PassageDTO,
+  annotationsFromDTO,
+  passageFromDTO,
+} from '../types';
+
+import { PassageConnectionNode } from './pagination';
+
+export const getPassage = async ({
+  client,
+  uuid,
+}: {
+  client: DataClient;
+  uuid: string;
+}) => {
+  const { data } = await client
+    .rpc('get_passage_with_annotations', {
+      uuid_input: uuid,
+    })
+    .single();
+
+  if (!data) {
+    console.warn(`No passage found for uuid: ${uuid}`);
+    return undefined;
+  }
+
+  const dto = data as PassageDTO;
+  return passageFromDTO(
+    dto,
+    annotationsFromDTO(dto?.annotations || [], dto?.content.length || 0),
+  );
+};
+
+export const getPassageByUuidOrXmlId = async ({
+  client,
+  uuid,
+  xmlId,
+}: {
+  client: DataClient;
+  uuid?: string;
+  xmlId?: string;
+}): Promise<PassageConnectionNode | null> => {
+  if (!uuid && !xmlId) {
+    return null;
+  }
+
+  let query = client
+    .from('passages')
+    .select('uuid, content, label, sort, type, xmlId, toh, work_uuid');
+
+  if (uuid) {
+    query = query.eq('uuid', uuid);
+  } else if (xmlId) {
+    query = query.eq('xmlId', xmlId);
+  }
+
+  const { data, error } = await query.single();
+
+  if (error) {
+    console.error(`Error fetching passage ${uuid || xmlId}:`, error);
+    return null;
+  }
+
+  if (!data) {
+    return null;
+  }
+
+  return {
+    uuid: data.uuid,
+    workUuid: data.work_uuid,
+    content: data.content,
+    label: data.label,
+    sort: data.sort,
+    type: data.type,
+    toh: data.toh ?? null,
+    xmlId: data.xmlId ?? null,
+  };
+};
+
+export const getPassageUuidByXmlId = async ({
+  client,
+  xmlId,
+}: {
+  client: DataClient;
+  xmlId: string;
+}) => {
+  const { data, error } = await client
+    .from('passages')
+    .select('uuid, workUuid:work_uuid')
+    .eq('xmlId', xmlId)
+    .single();
+
+  if (error) {
+    console.error(`Error fetching passage uuid for xmlId: ${xmlId}`, error);
+    return;
+  }
+
+  return data?.uuid;
+};

package/src/lib/passage/replace-persistence.ts

@@ -0,0 +1,153 @@
+import {
+  ANNOTATIONS_TO_IGNORE,
+  AnnotationDTO,
+  DataClient,
+  Passage,
+  passagesToDTO,
+  passagesToRowDTO,
+} from '../types';
+
+export type ReplacePassageRow = {
+  content: string;
+  label: string | null;
+  sort: number;
+  toh: string | null;
+  type: string;
+  uuid: string;
+  work_uuid: string;
+  xmlId: string | null;
+};
+
+export const fetchReplaceRows = async ({
+  client,
+  targetUuids,
+}: {
+  client: DataClient;
+  targetUuids: string[];
+}) => {
+  const { data, error } = await client
+    .from('passages')
+    .select('uuid, work_uuid, content, label, sort, type, toh, xmlId')
+    .in('uuid', targetUuids);
+
+  if (error) {
+    console.error('Error fetching replace targets:', error);
+    return {
+      ok: false as const,
+      error: `Failed to fetch replace targets: ${error.message}`,
+    };
+  }
+
+  const rowsByUuid = new Map((data ?? []).map((row) => [row.uuid, row]));
+  const missingUuids = targetUuids.filter((uuid) => !rowsByUuid.has(uuid));
+  if (missingUuids.length > 0) {
+    return {
+      ok: false as const,
+      error: `Unknown target UUIDs: ${missingUuids.join(', ')}`,
+    };
+  }
+
+  return {
+    ok: true as const,
+    orderedRows: targetUuids
+      .map((uuid) => rowsByUuid.get(uuid))
+      .filter((row): row is ReplacePassageRow => Boolean(row)),
+  };
+};
+
+export const fetchReplaceAnnotations = async ({
+  client,
+  targetUuids,
+}: {
+  client: DataClient;
+  targetUuids: string[];
+}) => {
+  const { data, error } = await client
+    .from('passage_annotations')
+    .select('uuid, content, end, start, type, passage_uuid, toh')
+    .in('passage_uuid', targetUuids)
+    .not('type', 'in', `(${ANNOTATIONS_TO_IGNORE.join(',')})`);
+
+  if (error) {
+    console.error('Error fetching annotations for replace:', error);
+    return {
+      ok: false as const,
+      error: `Failed to fetch annotations: ${error.message}`,
+    };
+  }
+
+  return {
+    ok: true as const,
+    rawAnnotations: (data ?? []) as AnnotationDTO[],
+  };
+};
+
+export const persistReplaceChanges = async ({
+  client,
+  rawAnnotations,
+  updatedPassages,
+}: {
+  client: DataClient;
+  rawAnnotations: AnnotationDTO[];
+  updatedPassages: Passage[];
+}) => {
+  const passageRowDtos = passagesToRowDTO(updatedPassages);
+  const annotationDtos = passagesToDTO(updatedPassages).flatMap(
+    (passage) => passage.annotations || [],
+  );
+  const updatedPassageUuids = updatedPassages.map((passage) => passage.uuid);
+  const updatedAnnotationUuids = new Set(annotationDtos.map((a) => a.uuid));
+  const annotationsToDelete = rawAnnotations.filter(
+    (annotation) =>
+      updatedPassageUuids.includes(annotation.passage_uuid || '') &&
+      !updatedAnnotationUuids.has(annotation.uuid),
+  );
+
+  const { error: passageError } = await client
+    .from('passages')
+    .upsert(passageRowDtos, { onConflict: 'uuid' });
+
+  if (passageError) {
+    console.error('Error saving replaced passages:', passageError);
+    return {
+      ok: false as const,
+      error: `Failed to save replaced passages: ${passageError.message}`,
+    };
+  }
+
+  if (annotationDtos.length > 0) {
+    const { error: annotationError } = await client
+      .from('passage_annotations')
+      .upsert(annotationDtos, { onConflict: 'uuid' });
+
+    if (annotationError) {
+      console.error('Error saving replaced annotations:', annotationError);
+      return {
+        ok: false as const,
+        error: `Failed to save replaced annotations: ${annotationError.message}`,
+      };
+    }
+  }
+
+  if (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 replaced annotations:', deleteError);
+      return {
+        ok: false as const,
+        error: `Failed to delete replaced annotations: ${deleteError.message}`,
+      };
+    }
+  }
+
+  return {
+    ok: true as const,
+  };
+};