glossarist 0.4.38 → 0.4.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.38",
+  "version": "0.4.40",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/models/base.ts

@@ -7,9 +7,26 @@
  * 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(): object {
+  toJSON(): JsonValue {
     throw new Error(`${this.constructor.name} must implement toJSON()`);
   }
 

package/src/models/citation.ts

@@ -0,0 +1,98 @@
+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-reference.js → concept-reference.ts}

@@ -1,7 +1,21 @@
 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 {
-  constructor(data = {}) {
+  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;
@@ -9,20 +23,20 @@ export class ConceptReference extends GlossaristModel {
     this.urn = data.urn ?? null;
   }
 
-  get isLocal() {
+  get isLocal(): boolean {
     return this.urn == null && this.source == null;
   }
 
-  get isExternal() {
+  get isExternal(): boolean {
     return !this.isLocal;
   }
 
-  static domain(conceptId) {
+  static domain(conceptId: string): ConceptReference {
     return new ConceptReference({ concept_id: conceptId, ref_type: 'domain' });
   }
 
-  toJSON() {
-    const obj = {};
+  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;
@@ -30,7 +44,7 @@ export class ConceptReference extends GlossaristModel {
     return obj;
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: ConceptReferenceJson): ConceptReference {
     return new ConceptReference(data);
   }
 }

package/src/models/designation-relationship.ts

@@ -0,0 +1,39 @@
+import { GlossaristModel } from './base.js';
+
+export const DESIGNATION_RELATIONSHIP_TYPES: ReadonlyArray<string> = Object.freeze([
+  // TBX (ISO 30042) / ISO 12620 term-level relationships
+  'abbreviated_form_for', 'short_form_for',
+]);
+
+export type DesignationRelationshipType = string;
+
+export interface DesignationRelationshipJson {
+  type?: DesignationRelationshipType | null;
+  content?: string | null;
+  target?: string | null;
+}
+
+export class DesignationRelationship extends GlossaristModel {
+  readonly type: DesignationRelationshipType | null;
+  readonly content: string | null;
+  readonly target: string | null;
+
+  constructor(data: DesignationRelationshipJson = {}) {
+    super();
+    this.type = data.type ?? null;
+    this.content = data.content ?? null;
+    this.target = data.target ?? null;
+  }
+
+  override toJSON(): DesignationRelationshipJson {
+    const obj: DesignationRelationshipJson = {};
+    if (this.type != null) obj.type = this.type;
+    if (this.content != null) obj.content = this.content;
+    if (this.target != null) obj.target = this.target;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationRelationshipJson): DesignationRelationship {
+    return new DesignationRelationship(data);
+  }
+}

package/src/models/designation.ts

@@ -0,0 +1,297 @@
+import { RegistrableModel } from './registrable.js';
+import { ConceptSource } from './concept-source.js';
+import type { ConceptSourceJson } from './concept-source.js';
+import { Pronunciation } from './pronunciation.js';
+import type { PronunciationJson } from './pronunciation.js';
+import { GrammarInfo } from './grammar-info.js';
+import type { GrammarInfoJson } from './grammar-info.js';
+import { RelatedConcept } from './related-concept.js';
+import type { RelatedConceptJson } from './related-concept.js';
+import {
+  DesignationRelationship,
+  DESIGNATION_RELATIONSHIP_TYPES,
+} from './designation-relationship.js';
+import type { DesignationRelationshipJson } from './designation-relationship.js';
+
+export type DesignationType =
+  | 'expression'
+  | 'abbreviation'
+  | 'symbol'
+  | 'letter_symbol'
+  | 'graphical symbol'
+  | 'graphical_symbol'
+  | string;
+
+export type NormativeStatus = 'preferred' | 'deprecated' | 'admitted' | 'deprecated_' | string | null;
+
+const SKOS_LABEL_BY_NORMATIVE_STATUS: Readonly<Record<string, string>> = Object.freeze({
+  preferred: 'prefLabel',
+  deprecated: 'hiddenLabel',
+  admitted: 'altLabel',
+  deprecated_: 'altLabel',
+});
+
+export interface DesignationJson {
+  type?: DesignationType;
+  designation?: string;
+  normative_status?: NormativeStatus;
+  normativeStatus?: NormativeStatus;
+  absent?: boolean | null;
+  field_of_application?: string | null;
+  fieldOfApplication?: string | null;
+  usage_info?: string | null;
+  usageInfo?: string | null;
+  geographical_area?: string | null;
+  geographicalArea?: string | null;
+  language?: string | null;
+  script?: string | null;
+  system?: string | null;
+  international?: boolean | null;
+  term_type?: string | null;
+  termType?: string | null;
+  pronunciation?: ReadonlyArray<PronunciationJson | Pronunciation>;
+  sources?: ReadonlyArray<ConceptSourceJson | ConceptSource>;
+  related?: ReadonlyArray<DesignationRelationshipJson | DesignationRelationship | RelatedConceptJson | RelatedConcept>;
+  prefix?: string | null;
+  grammar_info?: ReadonlyArray<GrammarInfoJson | GrammarInfo>;
+  acronym?: boolean;
+  initialism?: boolean;
+  truncation?: boolean;
+  text?: string | null;
+  image?: string | null;
+}
+
+export class Designation extends RegistrableModel {
+  readonly designation: string;
+  readonly type: DesignationType;
+  readonly normativeStatus: NormativeStatus;
+  readonly absent: boolean | null;
+  readonly fieldOfApplication: string | null;
+  readonly usageInfo: string | null;
+  readonly geographicalArea: string | null;
+  readonly language: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly international: boolean | null;
+  readonly termType: string | null;
+  readonly pronunciations: ReadonlyArray<Pronunciation>;
+  readonly sources: ReadonlyArray<ConceptSource>;
+  readonly related: ReadonlyArray<DesignationRelationship | RelatedConcept>;
+
+  constructor(data: DesignationJson = {}) {
+    super();
+    this.designation = data.designation ?? '';
+    this.type = data.type ?? 'expression';
+    this.normativeStatus = data.normative_status ?? data.normativeStatus ?? null;
+    this.absent = data.absent ?? null;
+    this.fieldOfApplication = data.field_of_application ?? data.fieldOfApplication ?? null;
+    this.usageInfo = data.usage_info ?? data.usageInfo ?? null;
+    this.geographicalArea = data.geographical_area ?? data.geographicalArea ?? null;
+    this.language = data.language ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.international = data.international ?? null;
+    this.termType = data.term_type ?? data.termType ?? null;
+    this.pronunciations = (data.pronunciation ?? []).map((p) =>
+      p instanceof Pronunciation ? p : new Pronunciation(p as PronunciationJson),
+    );
+    this.sources = (data.sources ?? []).map((s) =>
+      s instanceof ConceptSource ? s : new ConceptSource(s as ConceptSourceJson),
+    );
+    this.related = (data.related ?? []).map((r) => {
+      if (r instanceof DesignationRelationship || r instanceof RelatedConcept) return r;
+      const hash = r as { type?: string };
+      if (hash?.type && DESIGNATION_RELATIONSHIP_TYPES.includes(hash.type)) {
+        return DesignationRelationship.fromJSON(hash as DesignationRelationshipJson);
+      }
+      return RelatedConcept.fromJSON(hash as RelatedConceptJson);
+    });
+  }
+
+  override toJSON(): DesignationJson {
+    const obj: DesignationJson = { type: this.type, designation: this.designation };
+    if (this.normativeStatus != null) obj.normative_status = this.normativeStatus;
+    if (this.absent != null) obj.absent = this.absent;
+    if (this.fieldOfApplication != null) obj.field_of_application = this.fieldOfApplication;
+    if (this.usageInfo != null) obj.usage_info = this.usageInfo;
+    if (this.geographicalArea != null) obj.geographical_area = this.geographicalArea;
+    if (this.language != null) obj.language = this.language;
+    if (this.script != null) obj.script = this.script;
+    if (this.system != null) obj.system = this.system;
+    if (this.international != null) obj.international = this.international;
+    if (this.termType != null) obj.term_type = this.termType;
+    if (this.pronunciations.length > 0) {
+      obj.pronunciation = this.pronunciations.map((p) => p.toJSON());
+    }
+    if (this.sources.length > 0) {
+      obj.sources = this.sources.map((s) => s.toJSON());
+    }
+    if (this.related.length > 0) {
+      obj.related = this.related.map((r) => r.toJSON() as never);
+    }
+    return obj;
+  }
+
+  /** RDF class local-name for this designation subtype. */
+  rdfClass(): string {
+    return 'Expression';
+  }
+
+  /** SKOS label predicate URI appropriate for this designation's normative status. */
+  skosLabelPredicate(skosNs: string): string {
+    return `${skosNs}${this._skosLabelLocalName()}`;
+  }
+
+  /** SKOS-XL label predicate URI. */
+  skosxlLabelPredicate(skosxlNs: string): string {
+    return `${skosxlNs}${this._skosLabelLocalName()}`;
+  }
+
+  protected _skosLabelLocalName(): string {
+    const statusVal = this.normativeStatus == null ? '' : String(this.normativeStatus);
+    const status = statusVal
+      .split(/[/#]/)
+      .pop() ?? '';
+    return SKOS_LABEL_BY_NORMATIVE_STATUS[status] ?? 'altLabel';
+  }
+
+  static identityOf(value: { type?: string; designation?: string } | null | undefined): string {
+    const v = value ?? {};
+    const type = v.type ?? 'expression';
+    const text = String(v.designation ?? '').toLowerCase().trim();
+    return `${type}|${text}`;
+  }
+
+  override identity(): string {
+    return Designation.identityOf(this);
+  }
+
+  static override fromJSON(data: DesignationJson): Designation {
+    return Designation.fromData(data);
+  }
+}
+
+export class Expression extends Designation {
+  readonly prefix: string | null;
+  readonly grammarInfo: ReadonlyArray<GrammarInfo>;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.prefix = data.prefix ?? null;
+    this.grammarInfo = (data.grammar_info ?? []).map((g) =>
+      g instanceof GrammarInfo ? g : new GrammarInfo(g as GrammarInfoJson),
+    );
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.prefix != null) obj.prefix = this.prefix;
+    if (this.grammarInfo.length > 0) {
+      obj.grammar_info = this.grammarInfo.map((g) => g.toJSON());
+    }
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): Expression {
+    return new Expression(data);
+  }
+}
+
+Designation.register('expression', Expression);
+
+export class Abbreviation extends Expression {
+  readonly acronym: boolean;
+  readonly initialism: boolean;
+  readonly truncation: boolean;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.acronym = data.acronym ?? false;
+    this.initialism = data.initialism ?? false;
+    this.truncation = data.truncation ?? false;
+  }
+
+  override rdfClass(): string {
+    return 'Abbreviation';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.acronym) obj.acronym = true;
+    if (this.initialism) obj.initialism = true;
+    if (this.truncation) obj.truncation = true;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): Abbreviation {
+    return new Abbreviation(data);
+  }
+}
+
+Designation.register('abbreviation', Abbreviation);
+
+export class Symbol extends Designation {
+  override rdfClass(): string {
+    return 'Symbol';
+  }
+
+  static override fromJSON(data: DesignationJson): Symbol {
+    return new Symbol(data);
+  }
+}
+
+Designation.register('symbol', Symbol);
+
+export class LetterSymbol extends Symbol {
+  readonly text: string | null;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.text = data.text ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'LetterSymbol';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.text != null) obj.text = this.text;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): LetterSymbol {
+    return new LetterSymbol(data);
+  }
+}
+
+Designation.register('letter_symbol', LetterSymbol);
+
+export class GraphicalSymbol extends Symbol {
+  readonly text: string | null;
+  readonly image: string | null;
+
+  constructor(data: DesignationJson = {}) {
+    super(data);
+    this.text = data.text ?? null;
+    this.image = data.image ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'GraphicalSymbol';
+  }
+
+  override toJSON(): DesignationJson {
+    const obj = super.toJSON();
+    if (this.text != null) obj.text = this.text;
+    if (this.image != null) obj.image = this.image;
+    return obj;
+  }
+
+  static override fromJSON(data: DesignationJson): GraphicalSymbol {
+    return new GraphicalSymbol(data);
+  }
+}
+
+Designation.register('graphical symbol', GraphicalSymbol);
+Designation.register('graphical_symbol', GraphicalSymbol);

package/src/models/figure.ts

@@ -0,0 +1,110 @@
+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 FigureImageJson {
+  src?: string | null;
+  format?: string | null;
+  role?: string | null;
+  width?: number | string | null;
+  height?: number | string | null;
+  scale?: number | string | null;
+}
+
+export class FigureImage {
+  readonly src: string | null;
+  readonly format: string | null;
+  readonly role: string | null;
+  readonly width: number | string | null;
+  readonly height: number | string | null;
+  readonly scale: number | string | null;
+
+  constructor(data: FigureImageJson = {}) {
+    this.src = data.src ?? null;
+    this.format = data.format ?? null;
+    this.role = data.role ?? null;
+    this.width = data.width ?? null;
+    this.height = data.height ?? null;
+    this.scale = data.scale ?? null;
+  }
+
+  toJSON(): FigureImageJson {
+    const obj: FigureImageJson = {};
+    if (this.src != null) obj.src = this.src;
+    if (this.format != null) obj.format = this.format;
+    if (this.role != null) obj.role = this.role;
+    if (this.width != null) obj.width = this.width;
+    if (this.height != null) obj.height = this.height;
+    if (this.scale != null) obj.scale = this.scale;
+    return obj;
+  }
+
+  static fromJSON(data: FigureImageJson): FigureImage {
+    return new FigureImage(data);
+  }
+}
+
+export interface FigureJson extends SharedNonVerbalEntityJson {
+  images?: ReadonlyArray<FigureImageJson>;
+  subfigures?: ReadonlyArray<FigureJson | Figure>;
+}
+
+export class Figure extends SharedNonVerbalEntity {
+  protected readonly _rawImages: ReadonlyArray<FigureImageJson | FigureImage>;
+  protected readonly _rawSubfigures: ReadonlyArray<FigureJson | Figure>;
+  protected _images: ReadonlyArray<FigureImage> | null = null;
+  protected _subfigures: ReadonlyArray<Figure> | null = null;
+
+  constructor(data: FigureJson = {}) {
+    super(data);
+    this._rawImages = data.images ?? [];
+    this._rawSubfigures = data.subfigures ?? [];
+  }
+
+  override rdfClass(): string {
+    return 'Figure';
+  }
+
+  get images(): ReadonlyArray<FigureImage> {
+    return this._lazy<FigureImage>(
+      '_images',
+      '_rawImages',
+      (i) => (i instanceof FigureImage ? i : new FigureImage(i as FigureImageJson)),
+    );
+  }
+
+  get subfigures(): ReadonlyArray<Figure> {
+    return this._lazy<Figure>(
+      '_subfigures',
+      '_rawSubfigures',
+      (s) => (s instanceof Figure ? s : new Figure(s as FigureJson)),
+    );
+  }
+
+  override findById(targetId: string): this | null {
+    if (this.id === targetId) return this;
+    for (const sub of this.subfigures) {
+      const found = sub.findById(targetId);
+      if (found) return found as this;
+    }
+    return null;
+  }
+
+  override allIds(): string[] {
+    const ids = this.id != null ? [this.id] : [];
+    return [...ids, ...this.subfigures.flatMap((s) => s.allIds())];
+  }
+
+  override toJSON(): FigureJson {
+    const obj = super.toJSON() as FigureJson;
+    this._serialize(obj as unknown as Record<string, unknown>, 'images', '_images', '_rawImages');
+    this._serialize(obj as unknown as Record<string, unknown>, 'subfigures', '_subfigures', '_rawSubfigures');
+    return obj;
+  }
+
+  static override fromJSON(data: FigureJson): Figure {
+    return new Figure(data);
+  }
+}
+
+NonVerbalEntity.register('figure', Figure);

package/src/models/formula.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 FormulaJson extends SharedNonVerbalEntityJson {
+  expression?: string | null;
+  notation?: string | null;
+}
+
+export class Formula extends SharedNonVerbalEntity {
+  readonly expression: string | null;
+  readonly notation: string | null;
+
+  constructor(data: FormulaJson = {}) {
+    super(data);
+    this.expression = data.expression ?? null;
+    this.notation = data.notation ?? null;
+  }
+
+  override rdfClass(): string {
+    return 'Formula';
+  }
+
+  override toJSON(): FormulaJson {
+    const obj = super.toJSON() as FormulaJson;
+    if (this.expression != null) obj.expression = this.expression;
+    if (this.notation != null) obj.notation = this.notation;
+    return obj;
+  }
+
+  static override fromJSON(data: FormulaJson): Formula {
+    return new Formula(data);
+  }
+}
+
+NonVerbalEntity.register('formula', Formula);