@eightyfourthousand/data-access 2026.3.0

package/src/lib/types/annotation/annotation-type.ts

@@ -0,0 +1,219 @@
+import { TohokuCatalogEntry } from '../toh';
+
+export type AnnotationDTOType =
+  | 'abbreviation'
+  | 'audio'
+  | 'blockquote'
+  | 'code'
+  | 'deprecated-internal-link'
+  | 'end-note-link'
+  | 'glossary-instance'
+  | 'has-abbreviation'
+  | 'heading'
+  | 'image'
+  | 'indent'
+  | 'inline-title'
+  | 'internal-link'
+  | 'leading-space'
+  | 'line'
+  | 'line-group'
+  | 'link'
+  | 'list'
+  | 'list-item'
+  | 'mantra'
+  | 'mention'
+  | 'paragraph'
+  | 'quote'
+  | 'quoted'
+  | 'reference'
+  | 'span'
+  | 'table'
+  | 'table-body-data'
+  | 'table-body-header'
+  | 'table-body-row'
+  | 'trailer'
+  | 'unknown';
+
+export type AnnotationType =
+  | 'abbreviation'
+  | 'audio'
+  | 'blockquote'
+  | 'code'
+  | 'deprecated'
+  | 'endNoteLink'
+  | 'glossaryInstance'
+  | 'hasAbbreviation'
+  | 'heading'
+  | 'image'
+  | 'indent'
+  | 'inlineTitle'
+  | 'internalLink'
+  | 'leadingSpace'
+  | 'line'
+  | 'lineGroup'
+  | 'link'
+  | 'list'
+  | 'listItem'
+  | 'mantra'
+  | 'mention'
+  | 'paragraph'
+  | 'quote'
+  | 'quoted'
+  | 'reference'
+  | 'span'
+  | 'table'
+  | 'tableBodyData'
+  | 'tableBodyHeader'
+  | 'tableBodyRow'
+  | 'trailer'
+  | 'unknown';
+
+export const ANNOTATION_TYPE_DTO_TO_TYPE: Record<
+  AnnotationDTOType,
+  AnnotationType
+> = {
+  abbreviation: 'abbreviation',
+  audio: 'audio',
+  blockquote: 'blockquote',
+  code: 'code',
+  'deprecated-internal-link': 'deprecated',
+  'end-note-link': 'endNoteLink',
+  'glossary-instance': 'glossaryInstance',
+  'has-abbreviation': 'hasAbbreviation',
+  heading: 'heading',
+  image: 'image',
+  indent: 'indent',
+  'inline-title': 'inlineTitle',
+  'internal-link': 'internalLink',
+  'leading-space': 'leadingSpace',
+  line: 'line',
+  'line-group': 'lineGroup',
+  link: 'link',
+  list: 'list',
+  'list-item': 'listItem',
+  mantra: 'mantra',
+  mention: 'mention',
+  paragraph: 'paragraph',
+  quote: 'quote',
+  quoted: 'quoted',
+  reference: 'reference',
+  span: 'span',
+  table: 'table',
+  'table-body-data': 'tableBodyData',
+  'table-body-header': 'tableBodyHeader',
+  'table-body-row': 'tableBodyRow',
+  trailer: 'trailer',
+  unknown: 'unknown',
+} as const;
+
+export const annotationTypeFromDTO = (
+  type: AnnotationDTOType,
+): AnnotationType => {
+  return ANNOTATION_TYPE_DTO_TO_TYPE[type] || 'unknown';
+};
+
+export const ANNOTATION_TYPE_TO_DTO: Record<AnnotationType, AnnotationDTOType> =
+  {
+    abbreviation: 'abbreviation',
+    audio: 'audio',
+    blockquote: 'blockquote',
+    code: 'code',
+    deprecated: 'deprecated-internal-link',
+    endNoteLink: 'end-note-link',
+    glossaryInstance: 'glossary-instance',
+    hasAbbreviation: 'has-abbreviation',
+    heading: 'heading',
+    image: 'image',
+    indent: 'indent',
+    inlineTitle: 'inline-title',
+    internalLink: 'internal-link',
+    leadingSpace: 'leading-space',
+    line: 'line',
+    lineGroup: 'line-group',
+    link: 'link',
+    list: 'list',
+    listItem: 'list-item',
+    mantra: 'mantra',
+    mention: 'mention',
+    paragraph: 'paragraph',
+    quote: 'quote',
+    quoted: 'quoted',
+    reference: 'reference',
+    span: 'span',
+    table: 'table',
+    tableBodyData: 'table-body-data',
+    tableBodyHeader: 'table-body-header',
+    tableBodyRow: 'table-body-row',
+    trailer: 'trailer',
+    unknown: 'unknown',
+  } as const;
+
+export type AnnotationDTOContentKey =
+  | 'authority'
+  | 'endnote_xmlId'
+  | 'glossary_xmlId'
+  | 'heading-level'
+  | 'heading-type'
+  | 'href'
+  | 'label'
+  | 'lang'
+  | 'link-text'
+  | 'link-text-lookup'
+  | 'link-type'
+  | 'list-item-style'
+  | 'list-spacing'
+  | 'media-type'
+  | 'nesting'
+  | 'paragraph'
+  | 'quote_xmlId'
+  | 'src'
+  | 'text-style'
+  | 'text'
+  | 'type'
+  | 'title'
+  | 'uuid'
+  | 'same_work'
+  | 'subtype'
+  | 'toh';
+
+export type AnnotationDTOContent = Partial<
+  Record<AnnotationDTOContentKey, unknown>
+>;
+
+export type AnnotationDTO = {
+  content: AnnotationDTOContent[];
+  end: number;
+  start: number;
+  type: AnnotationDTOType;
+  uuid: string;
+  passage_uuid?: string;
+  passageUuid?: string;
+  toh?: TohokuCatalogEntry;
+};
+
+export type AnnotationsDTO = AnnotationDTO[];
+
+export const annotationTypeToDTO = (
+  type: AnnotationType,
+): AnnotationDTOType => {
+  return ANNOTATION_TYPE_TO_DTO[type] || 'unknown';
+};
+
+export const ANNOTATIONS_TO_IGNORE: AnnotationDTOType[] = [
+  'deprecated-internal-link',
+  'quoted',
+  'reference',
+  'unknown',
+];
+
+export type AnnotationsToIgnore = (typeof ANNOTATIONS_TO_IGNORE)[number];
+
+export type AnnotationBase = {
+  end: number;
+  start: number;
+  type: AnnotationType;
+  uuid: string;
+  passageUuid: string;
+  validated?: boolean;
+  toh?: TohokuCatalogEntry;
+};

package/src/lib/types/annotation/annotation.ts

@@ -0,0 +1,244 @@
+import { ExtendedTranslationLanguage } from '../language';
+import {
+  AnnotationBase,
+  AnnotationDTO,
+  annotationTypeFromDTO,
+  annotationTypeToDTO,
+} from './annotation-type';
+
+export type AbbreviationAnnotation = AnnotationBase & {
+  type: 'abbreviation';
+  abbreviation: string;
+};
+
+export type AudioAnnotation = AnnotationBase & {
+  type: 'audio';
+  src: string;
+  mediaType: string;
+};
+
+export type BlockquoteAnnotation = AnnotationBase & {
+  type: 'blockquote';
+};
+
+export type CodeAnnotation = AnnotationBase & {
+  type: 'code';
+};
+
+export type DeprecatedAnnotation = AnnotationBase & {
+  type: 'deprecated';
+};
+
+export type EndNoteLinkAnnotation = AnnotationBase & {
+  type: 'endNoteLink';
+  endNote: string;
+  label?: string;
+};
+
+export type GlossaryInstanceAnnotation = AnnotationBase & {
+  type: 'glossaryInstance';
+  glossary: string;
+  authority: string;
+};
+
+export type HasAbbreviationAnnotation = AnnotationBase & {
+  type: 'hasAbbreviation';
+  abbreviation: string;
+};
+
+export type HeadingClass =
+  | 'section-label'
+  | 'section-title'
+  | 'supplementary'
+  | 'table-label';
+
+export type HeadingAnnotation = AnnotationBase & {
+  type: 'heading';
+  level: number;
+  class?: HeadingClass;
+};
+
+export type ImageAnnotation = AnnotationBase & {
+  type: 'image';
+  src: string;
+};
+
+export type IndentAnnotation = AnnotationBase & {
+  type: 'indent';
+};
+
+export type InlineTitleAnnotation = AnnotationBase & {
+  type: 'inlineTitle';
+  lang: ExtendedTranslationLanguage;
+};
+
+export type InternalLinkAnnotation = AnnotationBase & {
+  type: 'internalLink';
+  linkType: string;
+  href?: string;
+  label?: string;
+  entity?: string;
+  isPending?: boolean;
+  isSameWork?: boolean;
+  subtype?: string;
+  linkToh?: string;
+};
+
+export type LeadingSpaceAnnotation = AnnotationBase & {
+  type: 'leadingSpace';
+};
+
+export type LineGroupAnnotation = AnnotationBase & {
+  type: 'lineGroup';
+};
+
+export type LineAnnotation = AnnotationBase & {
+  type: 'line';
+};
+
+export type LinkAnnotation = AnnotationBase & {
+  type: 'link';
+  href: string;
+  text: string;
+};
+
+export type ListItemAnnotation = AnnotationBase & {
+  type: 'listItem';
+};
+
+export type ListAnnotation = AnnotationBase & {
+  type: 'list';
+  spacing?: string;
+  nesting?: number;
+  itemStyle?: string;
+};
+
+export type MantraAnnotation = AnnotationBase & {
+  type: 'mantra';
+  lang: ExtendedTranslationLanguage;
+};
+
+export type MentionAnnotation = AnnotationBase & {
+  type: 'mention';
+  entity: string;
+  linkType: string;
+  text?: string;
+  displayText?: string;
+  isSameWork?: boolean;
+  subtype?: string;
+  linkToh?: string;
+};
+
+export type ParagraphAnnotation = AnnotationBase & {
+  type: 'paragraph';
+};
+
+export type QuoteAnnotation = AnnotationBase & {
+  type: 'quote';
+  quote?: string;
+};
+
+export type QuotedAnnotation = AnnotationBase & {
+  type: 'quoted';
+  quote?: string;
+};
+
+export type ReferenceAnnotation = AnnotationBase & {
+  type: 'reference';
+};
+
+export type SpanAnnotation = AnnotationBase & {
+  type: 'span';
+  textStyle?: string;
+  lang?: ExtendedTranslationLanguage;
+};
+
+export type TableAnnotation = AnnotationBase & {
+  type: 'table';
+};
+
+export type TableBodyDataAnnotation = AnnotationBase & {
+  type: 'tableBodyData';
+};
+
+export type TableBodyHeaderAnnotation = AnnotationBase & {
+  type: 'tableBodyHeader';
+};
+
+export type TableBodyRowAnnotation = AnnotationBase & {
+  type: 'tableBodyRow';
+};
+
+export type TrailerAnnotation = AnnotationBase & {
+  type: 'trailer';
+};
+
+export type UnknownAnnotation = AnnotationBase & {
+  type: 'unknown';
+};
+
+export type Annotation =
+  | AbbreviationAnnotation
+  | AudioAnnotation
+  | BlockquoteAnnotation
+  | CodeAnnotation
+  | DeprecatedAnnotation
+  | EndNoteLinkAnnotation
+  | GlossaryInstanceAnnotation
+  | HasAbbreviationAnnotation
+  | HeadingAnnotation
+  | ImageAnnotation
+  | IndentAnnotation
+  | InlineTitleAnnotation
+  | InternalLinkAnnotation
+  | LeadingSpaceAnnotation
+  | LineAnnotation
+  | LineGroupAnnotation
+  | LinkAnnotation
+  | ListAnnotation
+  | ListItemAnnotation
+  | MantraAnnotation
+  | MentionAnnotation
+  | ParagraphAnnotation
+  | QuoteAnnotation
+  | QuotedAnnotation
+  | ReferenceAnnotation
+  | SpanAnnotation
+  | TableAnnotation
+  | TableBodyDataAnnotation
+  | TableBodyHeaderAnnotation
+  | TableBodyRowAnnotation
+  | TrailerAnnotation
+  | UnknownAnnotation;
+
+export type Annotations = Annotation[];
+
+export type AnnotationTransformer = (dto: AnnotationDTO) => Annotation;
+
+export const baseAnnotationFromDTO = (dto: AnnotationDTO): AnnotationBase => {
+  const passageUuid = dto.passage_uuid || dto.passageUuid || '';
+
+  return {
+    uuid: dto.uuid,
+    start: dto.start,
+    end: dto.end,
+    type: annotationTypeFromDTO(dto.type),
+    toh: dto.toh,
+    passageUuid,
+    validated: true,
+  };
+};
+
+export type AnnotationExporter = (annotation: Annotation) => AnnotationDTO;
+
+export const baseAnnotationToDto = (
+  annotation: AnnotationBase,
+): AnnotationDTO => ({
+  end: annotation.end,
+  start: annotation.start,
+  type: annotationTypeToDTO(annotation.type),
+  uuid: annotation.uuid,
+  passage_uuid: annotation.passageUuid,
+  toh: annotation.toh,
+  content: [],
+});

package/src/lib/types/annotation/audio.ts

@@ -0,0 +1,33 @@
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type AudioAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+import { AnnotationDTO, AnnotationDTOContent } from './annotation-type';
+
+export const transformer: AnnotationTransformer = (dto): AudioAnnotation => {
+  const baseAnnotation = baseAnnotationFromDTO(dto);
+  const audio = baseAnnotation as AudioAnnotation;
+  dto.content.forEach((content) => {
+    if (content.src) {
+      audio.src = content.src as string;
+    }
+    if (content['media-type']) {
+      audio.mediaType = content['media-type'] as string;
+    }
+  });
+
+  return audio;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  const { src, mediaType } = annotation as AudioAnnotation;
+  const dto = baseAnnotationToDto(annotation);
+  dto.content.push({
+    src,
+    'media-type': mediaType,
+  } as AnnotationDTOContent);
+  return dto;
+};

package/src/lib/types/annotation/blockquote.ts

@@ -0,0 +1,18 @@
+import type { AnnotationDTO } from './annotation-type';
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type BlockquoteAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+
+export const transformer: AnnotationTransformer = (
+  dto,
+): BlockquoteAnnotation => {
+  return baseAnnotationFromDTO(dto) as BlockquoteAnnotation;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  return baseAnnotationToDto(annotation);
+};

package/src/lib/types/annotation/code.ts

@@ -0,0 +1,16 @@
+import type { AnnotationDTO } from './annotation-type';
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type CodeAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+
+export const transformer: AnnotationTransformer = (dto): CodeAnnotation => {
+  return baseAnnotationFromDTO(dto) as CodeAnnotation;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  return baseAnnotationToDto(annotation);
+};

package/src/lib/types/annotation/deprecated.ts

@@ -0,0 +1,18 @@
+import type { AnnotationDTO } from './annotation-type';
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type DeprecatedAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+
+export const transformer: AnnotationTransformer = (
+  dto,
+): DeprecatedAnnotation => {
+  return baseAnnotationFromDTO(dto) as DeprecatedAnnotation;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  return baseAnnotationToDto(annotation);
+};

package/src/lib/types/annotation/end-note-link.ts

@@ -0,0 +1,35 @@
+import type { AnnotationDTO } from './annotation-type';
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type EndNoteLinkAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+
+export const transformer: AnnotationTransformer = (
+  dto,
+): EndNoteLinkAnnotation => {
+  const baseAnnotation = baseAnnotationFromDTO(dto);
+  const endNote = baseAnnotation as EndNoteLinkAnnotation;
+  dto.content.forEach((content) => {
+    if (content.uuid) {
+      endNote.endNote = content.uuid as string;
+    }
+
+    if (content.label) {
+      endNote.label = content.label as string;
+    }
+  });
+
+  return endNote;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  const { endNote: uuid } = annotation as EndNoteLinkAnnotation;
+  const dto = baseAnnotationToDto(annotation);
+  dto.content.push({
+    uuid,
+  });
+  return dto;
+};

package/src/lib/types/annotation/export.ts

@@ -0,0 +1,69 @@
+import { AnnotationType } from './annotation-type';
+import { AnnotationExporter } from './annotation';
+import { exporter as abbreviation } from './abbreviation';
+import { exporter as audio } from './audio';
+import { exporter as blockquote } from './blockquote';
+import { exporter as code } from './code';
+import { exporter as deprecated } from './deprecated';
+import { exporter as endNoteLink } from './end-note-link';
+import { exporter as glossaryInstance } from './glossary-instance';
+import { exporter as hasAbbreviation } from './has-abbreviation';
+import { exporter as heading } from './heading';
+import { exporter as image } from './image';
+import { exporter as indent } from './indent';
+import { exporter as inlineTitle } from './inline-title';
+import { exporter as internalLink } from './internal-link';
+import { exporter as leadingSpace } from './leading-space';
+import { exporter as line } from './line';
+import { exporter as lineGroup } from './line-group';
+import { exporter as link } from './link';
+import { exporter as list } from './list';
+import { exporter as listItem } from './list-item';
+import { exporter as mantra } from './mantra';
+import { exporter as mention } from './mention';
+import { exporter as paragraph } from './paragraph';
+import { exporter as quote } from './quote';
+import { exporter as quoted } from './quoted';
+import { exporter as reference } from './reference';
+import { exporter as span } from './span';
+import { exporter as table } from './table';
+import { exporter as tableBodyData } from './table-body-data';
+import { exporter as tableBodyHeader } from './table-body-header';
+import { exporter as tableBodyRow } from './table-body-row';
+import { exporter as trailer } from './trailer';
+import { exporter as unknown } from './unknown';
+
+export const annotationToDtoMap: Record<AnnotationType, AnnotationExporter> = {
+  abbreviation,
+  audio,
+  blockquote,
+  code,
+  deprecated,
+  endNoteLink,
+  glossaryInstance,
+  hasAbbreviation,
+  heading,
+  image,
+  indent,
+  inlineTitle,
+  internalLink,
+  leadingSpace,
+  line,
+  lineGroup,
+  link,
+  list,
+  listItem,
+  mantra,
+  mention,
+  paragraph,
+  quote,
+  quoted,
+  reference,
+  span,
+  table,
+  tableBodyData,
+  tableBodyHeader,
+  tableBodyRow,
+  trailer,
+  unknown,
+};

package/src/lib/types/annotation/glossary-instance.ts

@@ -0,0 +1,34 @@
+import type { AnnotationDTO } from './annotation-type';
+import {
+  type AnnotationExporter,
+  type AnnotationTransformer,
+  type GlossaryInstanceAnnotation,
+  baseAnnotationFromDTO,
+  baseAnnotationToDto,
+} from './annotation';
+
+export const transformer: AnnotationTransformer = (
+  dto,
+): GlossaryInstanceAnnotation => {
+  const baseAnnotation = baseAnnotationFromDTO(dto);
+  const glossaryInstance = baseAnnotation as GlossaryInstanceAnnotation;
+  dto.content.forEach((content) => {
+    if (content.uuid) {
+      glossaryInstance.glossary = content.uuid as string;
+    }
+
+    if (content.authority) {
+      glossaryInstance.authority = content.authority as string
+    }
+  });
+  return glossaryInstance;
+};
+
+export const exporter: AnnotationExporter = (annotation): AnnotationDTO => {
+  const { glossary: uuid } = annotation as GlossaryInstanceAnnotation;
+  const dto = baseAnnotationToDto(annotation);
+  dto.content.push({
+    uuid,
+  });
+  return dto;
+};