glossarist 0.4.50 → 0.4.51

package/src/models/base.ts

@@ -1,110 +0,0 @@
-/**
- * GlossaristModel — abstract base for every domain model.
- *
- * Subclasses implement `toJSON()` (wire shape) and `identity()`
- * (stable string key for diff/dedupe). `equals()` and `clone()`
- * default to comparing via JSON serialization; subclasses may
- * override for performance.
- */
-
-/**
- * Any value that can be the output of `JSON.stringify`. Used as the
- * return type of {@link GlossaristModel.toJSON} so subclasses with
- * non-object JSON output (e.g. `NonVerbalReference.toJSON()` returns
- * a bare string for the no-display case) can override without
- * breaking variance. The object case accepts any object to avoid
- * forcing `<Model>Json` interfaces to declare explicit string index
- * signatures (TS interfaces don't have implicit index signatures).
- */
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | object;
-
-export abstract class GlossaristModel {
-  /** Wire-shape serialization. Subclasses MUST override. */
-  toJSON(): JsonValue {
-    throw new Error(`${this.constructor.name} must implement toJSON()`);
-  }
-
-  /** Stable identity string for diff, dedupe, registry keys. */
-  identity(): string {
-    throw new Error(`${this.constructor.name} must implement identity()`);
-  }
-
-  /** Default: structural equality via JSON. Override for semantic equality. */
-  equals(other: this): boolean {
-    if (!(other instanceof this.constructor)) return false;
-    return JSON.stringify(this.toJSON()) === JSON.stringify(other.toJSON());
-  }
-
-  /** Deep clone via JSON round-trip. Subclasses with non-JSON-safe
-   *  fields must override. */
-  clone(): this {
-    const Ctor = this.constructor as new (data: unknown) => this;
-    return new Ctor(JSON.parse(JSON.stringify(this.toJSON())));
-  }
-
-  /**
-   * Subclasses MUST override. Declared on the abstract base so callers
-   * who only have `typeof GlossaristModel` get a typed call site
-   * (rather than the static disappearing under `abstract`).
-   */
-  static fromJSON(_data: unknown): GlossaristModel {
-    throw new Error(`${this.name} must implement fromJSON()`);
-  }
-
-  /**
-   * Lazily wrap a raw array (plain hashes) into model instances.
-   * Used by Concept's lazy `figures`/`tables`/`formulas` getters so
-   * the wrap cost is only paid on first access.
-   *
-   * `cacheKey` and `rawKey` are private field names on `this`. The
-   * bracket access here is the only legitimate reflective pattern in
-   * the codebase (lazy field init). It is bracket-typed through a
-   * local alias rather than the public surface.
-   *
-   * Underscore-prefixed (not `protected`) so JS subclasses during the
-   * TS migration transition can call it without TS4094 on anonymous
-   * class expressions. Once all subclasses are .ts this can move to
-   * `protected`.
-   */
-  _lazy<TItem>(
-    cacheKey: string,
-    rawKey: string,
-    wrapFn: (raw: unknown) => TItem,
-  ): TItem[] {
-    const cache = this as unknown as Record<string, TItem[] | null | undefined>;
-    const raw = this as unknown as Record<string, unknown[] | undefined>;
-    if (cache[cacheKey] === null || cache[cacheKey] === undefined) {
-      const rawArr = raw[rawKey] ?? [];
-      cache[cacheKey] = rawArr.map((r) => wrapFn(r));
-    }
-    return cache[cacheKey] ?? [];
-  }
-
-  /**
-   * Helper for `toJSON()`: serialize a lazy-or-raw array under
-   * `jsonKey` only when it has items. Model instances go through
-   * `toJSON()`; primitives pass through.
-   */
-  _serialize(
-    obj: Record<string, unknown>,
-    jsonKey: string,
-    cacheKey: string,
-    rawKey: string,
-  ): void {
-    const self = this as unknown as Record<string, unknown[] | null | undefined>;
-    const cached = self[cacheKey];
-    const raw = self[rawKey];
-    const items = cached ?? (Array.isArray(raw) && raw.length > 0 ? raw : []);
-    if (items.length > 0) {
-      obj[jsonKey] = items.map((i) =>
-        i instanceof GlossaristModel ? i.toJSON() : i,
-      );
-    }
-  }
-}

package/src/models/bibliography-data.ts

@@ -1,64 +0,0 @@
-import * as yaml from 'js-yaml';
-import { GlossaristModel } from './base.js';
-import { BibliographyEntry } from './bibliography-entry.js';
-import type { BibliographyEntryJson } from './bibliography-entry.js';
-
-export interface BibliographyDataJson {
-  bibliography?: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-  entries?: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-}
-
-export class BibliographyData extends GlossaristModel {
-  private readonly _rawEntries: ReadonlyArray<BibliographyEntryJson | BibliographyEntry>;
-  private _entries: ReadonlyArray<BibliographyEntry> | null = null;
-
-  constructor(data: BibliographyDataJson | ReadonlyArray<BibliographyEntryJson | BibliographyEntry> = {}) {
-    super();
-    let entriesData: ReadonlyArray<BibliographyEntryJson | BibliographyEntry> | undefined;
-    if (Array.isArray(data)) {
-      entriesData = data;
-    } else {
-      entriesData = (data as BibliographyDataJson)?.bibliography ?? (data as BibliographyDataJson)?.entries ?? [];
-    }
-    this._rawEntries = Array.isArray(entriesData) ? entriesData : [];
-  }
-
-  get entries(): ReadonlyArray<BibliographyEntry> {
-    return this._lazy<BibliographyEntry>(
-      '_entries',
-      '_rawEntries',
-      (e) => (e instanceof BibliographyEntry ? e : new BibliographyEntry(e as BibliographyEntryJson)),
-    );
-  }
-
-  find(id: string): BibliographyEntry | null {
-    return this.entries.find((e) => e.id === id) ?? null;
-  }
-
-  get keys(): ReadonlyArray<string | null> {
-    return this.entries.map((e) => e.id);
-  }
-
-  override toJSON(): BibliographyDataJson {
-    if (this.entries.length === 0) return { bibliography: [] };
-    return { bibliography: this.entries.map((e) => e.toJSON()) };
-  }
-
-  toYAML(): string {
-    return yaml.dump(this.toJSON());
-  }
-
-  static fromYAML(yamlString: string): BibliographyData {
-    const parsed = yaml.load(yamlString) as
-      | BibliographyDataJson
-      | ReadonlyArray<BibliographyEntryJson>
-      | undefined;
-    return new BibliographyData(parsed ?? {});
-  }
-
-  static override fromJSON(
-    data: BibliographyDataJson | ReadonlyArray<BibliographyEntryJson>,
-  ): BibliographyData {
-    return new BibliographyData(data);
-  }
-}

package/src/models/bibliography-entry.ts

@@ -1,40 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export interface BibliographyEntryJson {
-  id?: string | null;
-  reference?: string | null;
-  title?: string | null;
-  link?: string | null;
-  type?: string | null;
-}
-
-export class BibliographyEntry extends GlossaristModel {
-  readonly id: string | null;
-  readonly reference: string | null;
-  readonly title: string | null;
-  readonly link: string | null;
-  readonly type: string | null;
-
-  constructor(data: BibliographyEntryJson = {}) {
-    super();
-    this.id = data.id ?? null;
-    this.reference = data.reference ?? null;
-    this.title = data.title ?? null;
-    this.link = data.link ?? null;
-    this.type = data.type ?? null;
-  }
-
-  override toJSON(): BibliographyEntryJson {
-    const obj: BibliographyEntryJson = {};
-    if (this.id != null) obj.id = this.id;
-    if (this.reference != null) obj.reference = this.reference;
-    if (this.title != null) obj.title = this.title;
-    if (this.link != null) obj.link = this.link;
-    if (this.type != null) obj.type = this.type;
-    return obj;
-  }
-
-  static override fromJSON(data: BibliographyEntryJson): BibliographyEntry {
-    return new BibliographyEntry(data);
-  }
-}

package/src/models/citation.ts

@@ -1,98 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Locality } from './locality.js';
-import type { LocalityJson } from './locality.js';
-
-export interface CitationRefJson {
-  source?: string | null;
-  id?: string | null;
-  version?: string | null;
-}
-
-export interface CitationJson {
-  ref?: CitationRefJson | CitationRef | null;
-  locality?: LocalityJson | Locality | null;
-  link?: string | null;
-  original?: string | null;
-  custom_locality?: string | null;
-  customLocality?: string | null;
-}
-
-export class CitationRef extends GlossaristModel {
-  readonly source: string | null;
-  readonly id: string | null;
-  readonly version: string | null;
-
-  constructor(data: CitationRefJson = {}) {
-    super();
-    this.source = data.source ?? null;
-    this.id = data.id ?? null;
-    this.version = data.version ?? null;
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    return parts.join(' ');
-  }
-
-  override toJSON(): CitationRefJson {
-    const obj: CitationRefJson = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.version != null) obj.version = this.version;
-    return obj;
-  }
-
-  static override fromJSON(data: CitationRefJson): CitationRef {
-    return new CitationRef(data);
-  }
-}
-
-export class Citation extends GlossaristModel {
-  /** Backward-compat alias for {@link CitationRef}. Original codebase
-   *  exposed the Ref class via `Citation.Ref`; keep that working. */
-  static readonly Ref = CitationRef;
-
-  readonly ref: CitationRef | null;
-  readonly locality: Locality | null;
-  readonly link: string | null;
-  readonly original: string | null;
-  readonly customLocality: string | null;
-
-  constructor(data: CitationJson | null = {}) {
-    super();
-    const d = data ?? {};
-    this.ref = d.ref
-      ? d.ref instanceof CitationRef
-        ? d.ref
-        : new CitationRef(d.ref)
-      : null;
-    this.locality = d.locality
-      ? d.locality instanceof Locality
-        ? d.locality
-        : new Locality(d.locality)
-      : null;
-    this.link = d.link ?? null;
-    this.original = d.original ?? null;
-    this.customLocality = d.custom_locality ?? d.customLocality ?? null;
-  }
-
-  override toString(): string {
-    return this.ref ? this.ref.toString() : '';
-  }
-
-  override toJSON(): CitationJson {
-    const obj: CitationJson = {};
-    if (this.ref != null) obj.ref = this.ref.toJSON();
-    if (this.locality != null) obj.locality = this.locality.toJSON();
-    if (this.link != null) obj.link = this.link;
-    if (this.original != null) obj.original = this.original;
-    if (this.customLocality != null) obj.custom_locality = this.customLocality;
-    return obj;
-  }
-
-  static override fromJSON(data: CitationJson): Citation {
-    return new Citation(data);
-  }
-}

package/src/models/concept-date.ts

@@ -1,48 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export type ConceptDateType = 'accepted' | 'amended' | 'retired' | string;
-
-export const DATE_TYPES: ReadonlyArray<string> = Object.freeze([
-  'accepted',
-  'amended',
-  'retired',
-]);
-
-export interface ConceptDateJson {
-  date?: string | null;
-  type?: ConceptDateType | null;
-}
-
-export class ConceptDate extends GlossaristModel {
-  readonly date: string | null;
-  readonly type: ConceptDateType | null;
-
-  constructor(data: ConceptDateJson = {}) {
-    super();
-    this.date = data.date ?? null;
-    this.type = data.type ?? null;
-  }
-
-  get parsedDate(): Date | null {
-    return this.date ? new Date(this.date) : null;
-  }
-
-  static identityOf(value: { type?: ConceptDateType | null } | null | undefined): string {
-    return value?.type ?? '';
-  }
-
-  override identity(): string {
-    return ConceptDate.identityOf(this);
-  }
-
-  override toJSON(): ConceptDateJson {
-    const obj: ConceptDateJson = {};
-    if (this.date != null) obj.date = this.date;
-    if (this.type != null) obj.type = this.type;
-    return obj;
-  }
-
-  static override fromJSON(data: ConceptDateJson): ConceptDate {
-    return new ConceptDate(data);
-  }
-}

package/src/models/concept-ref.ts

@@ -1,64 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-/**
- * Wire shape for ConceptRef. All three fields are optional on input
- * (any one is enough to identify a concept; usually source+id pair).
- * `text` is a free-form fallback for references that have no
- * machine-readable source.
- */
-export interface ConceptRefJson {
-  source?: string | null;
-  id?: string | null;
-  text?: string | null;
-}
-
-/**
- * ConceptRef — a reference to a concept by (source, id) pair, or by
- * free-form text when no machine-readable source exists.
- *
- * Identity: `${source ?? ''}|${id ?? ''}`. Two refs with the same
- * (source, id) are equal regardless of `text`.
- */
-export class ConceptRef extends GlossaristModel {
-  readonly source: string | null;
-  readonly id: string | null;
-  readonly text: string | null;
-
-  constructor(data: ConceptRefJson = {}) {
-    super();
-    this.source = data.source ?? null;
-    this.id = data.id ?? null;
-    this.text = data.text ?? null;
-  }
-
-  override toString(): string {
-    const parts: string[] = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    const base = parts.join(' ');
-    if (this.text && base) return `${base} (${this.text})`;
-    if (this.text) return this.text;
-    return base;
-  }
-
-  override toJSON(): ConceptRefJson {
-    const obj: ConceptRefJson = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.text != null) obj.text = this.text;
-    return obj;
-  }
-
-  override identity(): string {
-    return `${this.source ?? ''}|${this.id ?? ''}`;
-  }
-
-  static override fromJSON(data: ConceptRefJson): ConceptRef {
-    return new ConceptRef(data);
-  }
-
-  /** Convenience constructor for the common `(source, id)` form. */
-  static fromPair(source: string, id: string): ConceptRef {
-    return new ConceptRef({ source, id });
-  }
-}

package/src/models/concept-reference.ts

@@ -1,50 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export interface ConceptReferenceJson {
-  concept_id?: string | null;
-  conceptId?: string | null;
-  ref_type?: string | null;
-  refType?: string | null;
-  source?: string | null;
-  urn?: string | null;
-}
-
-export class ConceptReference extends GlossaristModel {
-  readonly conceptId: string | null;
-  readonly refType: string | null;
-  readonly source: string | null;
-  readonly urn: string | null;
-
-  constructor(data: ConceptReferenceJson = {}) {
-    super();
-    this.conceptId = data.concept_id ?? data.conceptId ?? null;
-    this.refType = data.ref_type ?? data.refType ?? null;
-    this.source = data.source ?? null;
-    this.urn = data.urn ?? null;
-  }
-
-  get isLocal(): boolean {
-    return this.urn == null && this.source == null;
-  }
-
-  get isExternal(): boolean {
-    return !this.isLocal;
-  }
-
-  static domain(conceptId: string): ConceptReference {
-    return new ConceptReference({ concept_id: conceptId, ref_type: 'domain' });
-  }
-
-  override toJSON(): ConceptReferenceJson {
-    const obj: ConceptReferenceJson = {};
-    if (this.conceptId != null) obj.concept_id = this.conceptId;
-    if (this.refType != null) obj.ref_type = this.refType;
-    if (this.source != null) obj.source = this.source;
-    if (this.urn != null) obj.urn = this.urn;
-    return obj;
-  }
-
-  static override fromJSON(data: ConceptReferenceJson): ConceptReference {
-    return new ConceptReference(data);
-  }
-}

package/src/models/concept-source.ts

@@ -1,96 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Citation } from './citation.js';
-
-/**
- * Local Citation wire-shape alias. Until `citation.ts` lands (Phase
- * 2b), Citation is untyped JS; this alias gives the cross-references
- * a typed shape without forcing the conversion order. When
- * `citation.ts` exports its own `CitationJson`, replace this with
- * `import type { CitationJson } from './citation.js'`.
- */
-export interface CitationJson {
-  ref?: { source?: string | null; id?: string | null; text?: string | null } | null;
-}
-
-export interface ConceptSourceJson {
-  id?: string | null;
-  status?: string | null;
-  type?: string | null;
-  origin?: CitationJson | Citation | null;
-  modification?: string | null;
-  sourcedFrom?: ReadonlyArray<CitationJson | Citation> | null;
-  sourced_from?: ReadonlyArray<CitationJson | Citation> | null;
-}
-
-export class ConceptSource extends GlossaristModel {
-  readonly id: string | null;
-  readonly status: string | null;
-  readonly type: string | null;
-  readonly origin: Citation | null;
-  readonly modification: string | null;
-  readonly sourcedFrom: ReadonlyArray<Citation>;
-
-  constructor(data: ConceptSourceJson = {}) {
-    super();
-    this.id = data.id ?? null;
-    this.status = data.status ?? null;
-    this.type = data.type ?? null;
-    this.origin = data.origin
-      ? data.origin instanceof Citation
-        ? data.origin
-        : new Citation(data.origin)
-      : null;
-    this.modification = data.modification ?? null;
-    const sourcedRaw = data.sourcedFrom ?? data.sourced_from ?? [];
-    this.sourcedFrom = sourcedRaw.map((c) =>
-      c instanceof Citation ? c : new Citation(c),
-    );
-  }
-
-  /**
-   * Backward-compat alias for callers using the snake_case JS field
-   * name. Prefer `.sourcedFrom` going forward; the wire name remains
-   * `sourced_from` (see toJSON).
-   */
-  get sourced_from(): ReadonlyArray<Citation> {
-    return this.sourcedFrom;
-  }
-
-  override toJSON(): ConceptSourceJson {
-    const obj: ConceptSourceJson = {};
-    if (this.id != null) obj.id = this.id;
-    if (this.status != null) obj.status = this.status;
-    if (this.type != null) obj.type = this.type;
-    if (this.origin != null) obj.origin = this.origin.toJSON();
-    if (this.modification != null) obj.modification = this.modification;
-    if (this.sourcedFrom.length > 0) {
-      obj.sourced_from = this.sourcedFrom.map((c) => c.toJSON());
-    }
-    return obj;
-  }
-
-  static identityOf(
-    value: {
-      type?: string | null;
-      origin?: CitationJson | Citation | { ref?: { source?: string; id?: string } | null } | null;
-    } | null | undefined,
-  ): string {
-    const v = value ?? {};
-    const origin = v.origin as CitationJson | Citation | { ref?: { source?: string; id?: string } | null } | null | undefined;
-    const ref =
-      origin instanceof Citation
-        ? origin.ref
-        : origin && typeof origin === 'object'
-          ? (origin as { ref?: { source?: string; id?: string } | null }).ref
-          : null;
-    return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
-  }
-
-  override identity(): string {
-    return ConceptSource.identityOf(this);
-  }
-
-  static override fromJSON(data: ConceptSourceJson): ConceptSource {
-    return new ConceptSource(data);
-  }
-}

package/src/models/concept-system-type.ts

@@ -1,39 +0,0 @@
-// ConceptSystemType — ISO 12620 A.7.1 concept system type enum.
-//
-// Permissible instances per ISO 12620:
-//   generic     — species are part of the extension of the genus
-//   partitive   — based on whole-part relations
-//   sequential  — based on spatial and temporal relations
-//   associative — based on thematic or pragmatic relations
-//   mixed       — two or more of the above (the realistic case)
-
-export type ConceptSystemType =
-  | 'generic'
-  | 'partitive'
-  | 'sequential'
-  | 'associative'
-  | 'mixed';
-
-export const CONCEPT_SYSTEM_TYPE: Readonly<
-  Record<'GENERIC' | 'PARTITIVE' | 'SEQUENTIAL' | 'ASSOCIATIVE' | 'MIXED', ConceptSystemType>
-> = Object.freeze({
-  GENERIC: 'generic',
-  PARTITIVE: 'partitive',
-  SEQUENTIAL: 'sequential',
-  ASSOCIATIVE: 'associative',
-  MIXED: 'mixed',
-});
-
-export const CONCEPT_SYSTEM_TYPE_VALUES: ReadonlyArray<ConceptSystemType> =
-  Object.freeze(Object.values(CONCEPT_SYSTEM_TYPE));
-
-export function isValidConceptSystemType(
-  value: unknown,
-): value is ConceptSystemType {
-  return (
-    typeof value === 'string' &&
-    (CONCEPT_SYSTEM_TYPE_VALUES as readonly string[]).includes(value)
-  );
-}
-
-export default CONCEPT_SYSTEM_TYPE;