glossarist 0.4.37 → 0.4.39

package/src/models/{locality.js → locality.ts}

@@ -1,22 +1,34 @@
 import { GlossaristModel } from './base.js';
 
+export interface LocalityJson {
+  type?: string | null;
+  reference_from?: string | null;
+  referenceFrom?: string | null;
+  reference_to?: string | null;
+  referenceTo?: string | null;
+}
+
 export class Locality extends GlossaristModel {
-  constructor(data = {}) {
+  readonly type: string | null;
+  readonly referenceFrom: string | null;
+  readonly referenceTo: string | null;
+
+  constructor(data: LocalityJson = {}) {
     super();
     this.type = data.type ?? null;
     this.referenceFrom = data.reference_from ?? data.referenceFrom ?? null;
     this.referenceTo = data.reference_to ?? data.referenceTo ?? null;
   }
 
-  toJSON() {
-    const obj = {};
+  override toJSON(): LocalityJson {
+    const obj: LocalityJson = {};
     if (this.type != null) obj.type = this.type;
     if (this.referenceFrom != null) obj.reference_from = this.referenceFrom;
     if (this.referenceTo != null) obj.reference_to = this.referenceTo;
     return obj;
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: LocalityJson): Locality {
     return new Locality(data);
   }
 }

package/src/models/localized-string.ts

@@ -0,0 +1,32 @@
+const FALLBACK_LANG = 'eng';
+
+export type LocalizedStringHash = Readonly<Record<string, string>>;
+
+export function fetchLocalizedString(
+  hash: LocalizedStringHash | null | undefined,
+  lang: string,
+  fallback: string | null = FALLBACK_LANG,
+): string | null {
+  if (hash == null || typeof hash !== 'object') return null;
+  const direct = hash[lang] ?? hash[String(lang)];
+  if (direct != null) return direct;
+  if (fallback != null && fallback !== lang) {
+    return hash[fallback] ?? hash[String(fallback)] ?? null;
+  }
+  return null;
+}
+
+export function localizedStringIsEmpty(
+  hash: LocalizedStringHash | null | undefined,
+): boolean {
+  return (
+    hash == null ||
+    (typeof hash === 'object' && Object.keys(hash).length === 0)
+  );
+}
+
+export function localizedStringIsPresent(
+  hash: LocalizedStringHash | null | undefined,
+): boolean {
+  return !localizedStringIsEmpty(hash);
+}

package/src/models/non-verb-rep.ts

@@ -0,0 +1,48 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import type { NonVerbalEntityJson } from './non-verbal-entity.js';
+import { FigureImage } from './figure.js';
+import type { FigureImageJson } from './figure.js';
+
+export const NON_VERBAL_TYPES: ReadonlyArray<string> = Object.freeze([
+  'image', 'table', 'formula',
+]);
+
+export interface NonVerbRepJson extends NonVerbalEntityJson {
+  type?: string | null;
+  images?: ReadonlyArray<FigureImageJson | FigureImage>;
+}
+
+export class NonVerbRep extends NonVerbalEntity {
+  readonly type: string | null;
+  protected readonly _rawImages: ReadonlyArray<FigureImageJson | FigureImage>;
+  protected _images: ReadonlyArray<FigureImage> | null = null;
+
+  constructor(data: NonVerbRepJson = {}) {
+    super(data);
+    this.type = data.type ?? null;
+    this._rawImages = data.images ?? [];
+  }
+
+  override rdfClass(): string {
+    return 'NonVerbalRepresentation';
+  }
+
+  get images(): ReadonlyArray<FigureImage> {
+    return this._lazy<FigureImage>(
+      '_images',
+      '_rawImages',
+      (i) => (i instanceof FigureImage ? i : new FigureImage(i as FigureImageJson)),
+    );
+  }
+
+  override toJSON(): NonVerbRepJson {
+    const obj = super.toJSON() as NonVerbRepJson;
+    if (this.type != null) obj.type = this.type;
+    this._serialize(obj as unknown as Record<string, unknown>, 'images', '_images', '_rawImages');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbRepJson): NonVerbRep {
+    return new NonVerbRep(data);
+  }
+}

package/src/models/non-verbal-entity.ts

@@ -0,0 +1,65 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+import type { ConceptSourceJson } from './concept-source.js';
+
+export interface NonVerbalEntityJson {
+  caption?: string | null;
+  description?: string | null;
+  alt?: string | null;
+  sources?: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  type?: string | null;
+}
+
+export class NonVerbalEntity extends RegistrableModel {
+  readonly caption: string | null;
+  readonly description: string | null;
+  readonly alt: string | null;
+  protected readonly _rawSources: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  protected _sources: ReadonlyArray<ConceptSource> | null = null;
+
+  constructor(data: NonVerbalEntityJson = {}) {
+    super();
+    this.caption = data.caption ?? null;
+    this.description = data.description ?? null;
+    this.alt = data.alt ?? null;
+    this._rawSources = data.sources ?? [];
+  }
+
+  get sources(): ReadonlyArray<ConceptSource> {
+    return this._lazy<ConceptSource>(
+      '_sources',
+      '_rawSources',
+      (s) => (s instanceof ConceptSource ? s : new ConceptSource(s as ConceptSourceJson)),
+    );
+  }
+
+  /**
+   * Ontology class local-name. Subtypes override to return their specific
+   * class (Figure/Table/Formula). Used by the RDF emitter so a new subtype
+   * registers without editing the emitter (OCP).
+   */
+  rdfClass(): string {
+    return 'NonVerbalEntity';
+  }
+
+  findById(_targetId: string): NonVerbalEntity | null {
+    return null;
+  }
+
+  allIds(): string[] {
+    return [];
+  }
+
+  override toJSON(): NonVerbalEntityJson {
+    const obj: NonVerbalEntityJson = {};
+    if (this.caption != null) obj.caption = this.caption;
+    if (this.description != null) obj.description = this.description;
+    if (this.alt != null) obj.alt = this.alt;
+    this._serialize(obj as unknown as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    return obj;
+  }
+
+  static override fromJSON(data: NonVerbalEntityJson): NonVerbalEntity {
+    return NonVerbalEntity.fromData(data);
+  }
+}

package/src/models/non-verbal-reference.ts

@@ -0,0 +1,73 @@
+import { RegistrableModel } from './registrable.js';
+
+export interface NonVerbalReferenceJson {
+  entityId?: string | null;
+  entity_id?: string | null;
+  ref?: string | null;
+  id?: string | null;
+  display?: string | null;
+  type?: string;
+}
+
+/**
+ * Polymorphic JSON for NonVerbalReference: either a bare string (the
+ * entity id) or an object with `{ ref, display?, type? }`.
+ */
+export type NonVerbalReferenceInput =
+  | NonVerbalReferenceJson
+  | string
+  | NonVerbalReference;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyCtor = new (...args: any[]) => any;
+
+export class NonVerbalReference extends RegistrableModel {
+  readonly entityId: string | null;
+  readonly display: string | null;
+
+  constructor(data: NonVerbalReferenceJson = {}) {
+    super();
+    this.entityId = data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    this.display = data.display ?? null;
+  }
+
+  get dedupKey(): [string, string | null] {
+    return [this.constructor.name, this.entityId];
+  }
+
+  override toJSON(): NonVerbalReferenceJson | string {
+    if (this.display != null) {
+      return { ref: this.entityId ?? '', display: this.display };
+    }
+    return this.entityId ?? '';
+  }
+
+  static override fromJSON<T extends NonVerbalReference>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this: new (...args: any[]) => T,
+    data: NonVerbalReferenceInput,
+  ): T | NonVerbalReference {
+    if (data instanceof NonVerbalReference) return data;
+    if (typeof data === 'string') {
+      return new (this as new (d: NonVerbalReferenceJson) => T)({ entityId: data });
+    }
+    const entityId =
+      data.entityId ?? data.entity_id ?? data.ref ?? data.id ?? null;
+    const display = data.display ?? null;
+    const type = data.type;
+    const Self = this as unknown as { _registry(): Map<string, AnyCtor> };
+    if (type) {
+      const Cls = Self._registry().get(type);
+      if (Cls) {
+        return new (Cls as new (d: NonVerbalReferenceJson) => T)({
+          entityId: entityId ?? undefined,
+          display: display ?? undefined,
+        });
+      }
+    }
+    return new (this as new (d: NonVerbalReferenceJson) => T)({
+      entityId: entityId ?? undefined,
+      display: display ?? undefined,
+    });
+  }
+}

package/src/models/non-verbal-references.ts

@@ -0,0 +1,29 @@
+import { NonVerbalReference } from './non-verbal-reference.js';
+import type { NonVerbalReferenceInput } from './non-verbal-reference.js';
+
+export class FigureReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FigureReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FigureReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('figure', FigureReference);
+
+export class TableReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): TableReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as TableReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('table', TableReference);
+
+export class FormulaReference extends NonVerbalReference {
+  static override fromJSON(
+    data: NonVerbalReferenceInput,
+  ): FormulaReference | NonVerbalReference {
+    return NonVerbalReference.fromJSON(data) as FormulaReference | NonVerbalReference;
+  }
+}
+NonVerbalReference.register('formula', FormulaReference);

package/src/models/{pronunciation.js → pronunciation.ts}

@@ -1,7 +1,21 @@
 import { GlossaristModel } from './base.js';
 
+export interface PronunciationJson {
+  content?: string | null;
+  language?: string | null;
+  script?: string | null;
+  system?: string | null;
+  country?: string | null;
+}
+
 export class Pronunciation extends GlossaristModel {
-  constructor(data = {}) {
+  readonly content: string | null;
+  readonly language: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly country: string | null;
+
+  constructor(data: PronunciationJson = {}) {
     super();
     this.content = data.content ?? null;
     this.language = data.language ?? null;
@@ -10,8 +24,8 @@ export class Pronunciation extends GlossaristModel {
     this.country = data.country ?? null;
   }
 
-  toJSON() {
-    const obj = {};
+  override toJSON(): PronunciationJson {
+    const obj: PronunciationJson = {};
     if (this.content != null) obj.content = this.content;
     if (this.language != null) obj.language = this.language;
     if (this.script != null) obj.script = this.script;
@@ -20,7 +34,7 @@ export class Pronunciation extends GlossaristModel {
     return obj;
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: PronunciationJson): Pronunciation {
     return new Pronunciation(data);
   }
 }

package/src/models/registrable.ts

@@ -0,0 +1,48 @@
+import { GlossaristModel } from './base.js';
+
+/**
+ * Per-class registry of named subtypes. The registry is keyed by
+ * `type` discriminator and maps to the constructor function. Used by
+ * NonVerbalEntity (Figure/Table/Formula), NonVerbalReference
+ * (Figure/Table/Formula references), and any future RegistrableModel
+ * subclass that needs polymorphic dispatch on a string discriminator.
+ *
+ * Stored as a WeakMap keyed by the base class function, so each base
+ * gets its own namespace (NonVerbalEntity.register does not collide
+ * with NonVerbalReference.register).
+ *
+ * The registry stores constructors as `Function` because TS's strict
+ * variance on constructor params makes a typed constraint reject
+ * subclasses with narrower param types. The dispatch site casts the
+ * result back to the specific subclass.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see docstring.
+type AnyCtor = new (...args: any[]) => any;
+
+const _registries = new WeakMap<object, Map<string, AnyCtor>>();
+
+export class RegistrableModel extends GlossaristModel {
+  static _registry(): Map<string, AnyCtor> {
+    const existing = _registries.get(this) ?? new Map();
+    if (!_registries.has(this)) _registries.set(this, existing);
+    return existing;
+  }
+
+  static register(type: string, cls: AnyCtor): void {
+    this._registry().set(type, cls);
+  }
+
+  static fromData<T extends RegistrableModel>(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- any ctor signature accepted.
+    this: new (...args: any[]) => T,
+    data: unknown,
+  ): T {
+    if (data instanceof this) return data;
+    const type = (data as { type?: string } | null)?.type;
+    const Self = this as unknown as { _registry(): Map<string, AnyCtor> };
+    const registry = Self._registry();
+    const Cls = type ? (registry.get(type) ?? (this as AnyCtor)) : (this as AnyCtor);
+    return new (Cls as new (data: unknown) => T)(data);
+  }
+}

package/src/models/{related-concept.js → related-concept.ts}

@@ -1,7 +1,9 @@
 import { GlossaristModel } from './base.js';
 import { ConceptRef } from './concept-ref.js';
+import type { ConceptRefJson } from './concept-ref.js';
+import type { LocalizedString } from './generic-member.js';
 
-export const RELATIONSHIP_TYPES = Object.freeze([
+export const RELATIONSHIP_TYPES: ReadonlyArray<string> = Object.freeze([
   // Lifecycle (ISO 10241-1)
   'deprecates', 'deprecated_by', 'supersedes', 'superseded_by',
   'replaces', 'replaced_by', 'invalidates', 'invalidated_by',
@@ -25,10 +27,9 @@ export const RELATIONSHIP_TYPES = Object.freeze([
   // Associative (ISO 10241-1 / ISO 25964)
   'see', 'related_concept', 'related_concept_broader', 'related_concept_narrower',
   'references',
-  // ExternalConcept resolution (Glossarist extension — v2 partitive-relation)
-  // Direction: real concept `provides` substance for an external concept;
-  // external concept `provided_by` real concept. Stored on the
-  // ExternalConcept. See TODO.partitive-relation-v2 item 07.
+  // ExternalConcept resolution (Glossarist extension). Direction: real
+  // concept `provides` substance for an external concept; external concept
+  // `provided_by` real concept. Stored on the ExternalConcept.
   'provides', 'provided_by',
   // Comparative (ISO 10241-1)
   'compare', 'contrast',
@@ -38,56 +39,79 @@ export const RELATIONSHIP_TYPES = Object.freeze([
   'homograph', 'false_friend',
 ]);
 
+export type RelationshipType = string;
+
+export interface RelatedConceptJson {
+  type?: RelationshipType;
+  content?: LocalizedString | string | null;
+  ref?: ConceptRefJson | ConceptRef | null;
+}
+
 export class RelatedConcept extends GlossaristModel {
-  constructor(data = {}) {
+  readonly type: RelationshipType;
+  readonly content: LocalizedString | null;
+  readonly ref: ConceptRef | null;
+
+  constructor(data: RelatedConceptJson = {}) {
     super();
     this.type = data.type ?? 'see';
-    this.content = normalizeContent(data.content);
+    this.content = _normalizeContent(data.content);
     this.ref = data.ref
-      ? (data.ref instanceof ConceptRef ? data.ref : new ConceptRef(data.ref))
+      ? data.ref instanceof ConceptRef
+        ? data.ref
+        : new ConceptRef(data.ref)
       : null;
   }
 
-  // Convenience reader: returns the first available string value
-  // from the localized hash, or null if absent. Mirrors
-  // PartitiveHyperedge#contentString.
-  get contentString() {
+  /**
+   * Convenience reader: returns the first available string value from
+   * the localized hash, or null if absent.
+   */
+  get contentString(): string | null {
     if (!this.content) return null;
     const values = Object.values(this.content);
-    return values.length > 0 ? values[0] : null;
+    return values.length > 0 ? (values[0] ?? null) : null;
   }
 
-  toJSON() {
-    const obj = { type: this.type };
+  override toJSON(): RelatedConceptJson {
+    const obj: RelatedConceptJson = { type: this.type };
     if (this.content != null) obj.content = this.content;
     if (this.ref != null) obj.ref = this.ref.toJSON();
     return obj;
   }
 
-  static identityOf(value) {
+  static identityOf(
+    value: {
+      type?: string;
+      ref?: { source?: string | null; id?: string | null } | null;
+    } | null | undefined,
+  ): string {
     const v = value ?? {};
-    const ref = v?.ref;
+    const ref = v.ref;
     return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
   }
 
-  identity() {
+  override identity(): string {
     return RelatedConcept.identityOf(this);
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: RelatedConceptJson): RelatedConcept {
     return new RelatedConcept(data);
   }
 }
 
-// Content is a localized string (language → text). Plain strings on
-// input are normalized to `{ default: '...' }` so callers always see
-// the same shape. Mirrors PartitiveHyperedge's normalizeContent.
-function normalizeContent(value) {
+function _normalizeContent(
+  value: LocalizedString | string | null | undefined,
+): LocalizedString | null {
   if (value == null) return null;
   if (typeof value === 'string') return { default: value };
   if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(([, v]) => typeof v === 'string');
-    return entries.length > 0 ? Object.fromEntries(entries) : null;
+    const entries = Object.entries(value).filter(
+      ([, v]) => typeof v === 'string',
+    );
+    return entries.length > 0
+      ? (Object.fromEntries(entries) as LocalizedString)
+      : null;
   }
   return null;
 }

package/src/models/shared-non-verbal-entity.ts

@@ -0,0 +1,36 @@
+import { NonVerbalEntity } from './non-verbal-entity.js';
+import type { NonVerbalEntityJson } from './non-verbal-entity.js';
+
+export interface SharedNonVerbalEntityJson extends NonVerbalEntityJson {
+  id?: string | null;
+  identifier?: string | null;
+}
+
+export class SharedNonVerbalEntity extends NonVerbalEntity {
+  readonly id: string | null;
+  readonly identifier: string | null;
+
+  constructor(data: SharedNonVerbalEntityJson = {}) {
+    super(data);
+    this.id = data.id ?? null;
+    this.identifier = data.identifier ?? null;
+  }
+
+  override findById(targetId: string): this | null {
+    return this.id === targetId ? this : null;
+  }
+  override allIds(): string[] {
+    return this.id != null ? [this.id] : [];
+  }
+
+  override toJSON(): SharedNonVerbalEntityJson {
+    const obj = super.toJSON() as SharedNonVerbalEntityJson;
+    if (this.id != null) obj.id = this.id;
+    if (this.identifier != null) obj.identifier = this.identifier;
+    return obj;
+  }
+
+  static override fromJSON(data: SharedNonVerbalEntityJson): SharedNonVerbalEntity {
+    return SharedNonVerbalEntity.fromData(data);
+  }
+}

package/src/models/table.ts

@@ -0,0 +1,36 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import type { SharedNonVerbalEntityJson } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export interface TableJson extends SharedNonVerbalEntityJson {
+  content?: string | null;
+  format?: string | null;
+}
+
+export class Table extends SharedNonVerbalEntity {
+  readonly content: string | null;
+  readonly format: string | null;
+
+  constructor(data: TableJson = {}) {
+    super(data);
+    this.content = data.content ?? null;
+    this.format = data.format ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'Table';
+  }
+
+  override toJSON(): TableJson {
+    const obj = super.toJSON() as TableJson;
+    if (this.content != null) obj.content = this.content;
+    if (this.format != null) obj.format = this.format;
+    return obj;
+  }
+
+  static override fromJSON(data: TableJson): Table {
+    return new Table(data);
+  }
+}
+
+NonVerbalEntity.register('table', Table);

package/src/models/bibliography-data.js

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