glossarist 0.4.37 → 0.4.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "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/bibliography-data.ts

@@ -0,0 +1,64 @@
+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.js → bibliography-entry.ts}

@@ -1,7 +1,21 @@
 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 {
-  constructor(data = {}) {
+  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;
@@ -10,8 +24,8 @@ export class BibliographyEntry extends GlossaristModel {
     this.type = data.type ?? null;
   }
 
-  toJSON() {
-    const obj = {};
+  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;
@@ -20,7 +34,7 @@ export class BibliographyEntry extends GlossaristModel {
     return obj;
   }
 
-  static fromJSON(data) {
+  static override fromJSON(data: BibliographyEntryJson): BibliographyEntry {
     return new BibliographyEntry(data);
   }
 }

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/detailed-definition.ts

@@ -0,0 +1,92 @@
+import { GlossaristModel } from './base.js';
+import { Citation } from './citation.js';
+import { canonicalJson } from '../diff/canonical-json.js';
+
+export interface DetailedDefinitionJson {
+  content?: string;
+  sources?: ReadonlyArray<unknown>;
+  examples?: ReadonlyArray<unknown>;
+}
+
+export interface WalkTextEntry {
+  text: string;
+  source: string;
+}
+
+export class DetailedDefinition extends GlossaristModel {
+  readonly content: string;
+  private readonly _rawSources: ReadonlyArray<unknown>;
+  private readonly _rawExamples: ReadonlyArray<unknown>;
+  private _sources: ReadonlyArray<Citation> | null = null;
+  private _examples: ReadonlyArray<DetailedDefinition> | null = null;
+
+  constructor(data: DetailedDefinitionJson = {}) {
+    super();
+    this.content = data.content ?? '';
+    this._rawSources = data.sources ?? [];
+    this._rawExamples = data.examples ?? [];
+  }
+
+  get sources(): ReadonlyArray<Citation> {
+    return this._lazy<Citation>(
+      '_sources',
+      '_rawSources',
+      (s) => (s instanceof Citation ? s : new Citation(s as never)),
+    );
+  }
+
+  get examples(): ReadonlyArray<DetailedDefinition> {
+    return this._lazy<DetailedDefinition>(
+      '_examples',
+      '_rawExamples',
+      (e) =>
+        e instanceof DetailedDefinition
+          ? e
+          : new DetailedDefinition(e as DetailedDefinitionJson),
+    );
+  }
+
+  override toJSON(): DetailedDefinitionJson {
+    const obj: DetailedDefinitionJson = { content: this.content };
+    this._serialize(obj as Record<string, unknown>, 'sources', '_sources', '_rawSources');
+    this._serialize(obj as Record<string, unknown>, 'examples', '_examples', '_rawExamples');
+    return obj;
+  }
+
+  /**
+   * Yield this definition's content and the content of every nested
+   * example (recursively). Each item carries `{ text, source }` where
+   * `source` is `<path>.content` rooted at the `path` argument.
+   */
+  *walkTexts(path: string): Generator<WalkTextEntry> {
+    if (typeof this.content === 'string' && this.content.length > 0) {
+      yield { text: this.content, source: `${path}.content` };
+    }
+    const examples = this.examples;
+    for (let i = 0; i < examples.length; i++) {
+      const example = examples[i];
+      if (example) {
+        yield* example.walkTexts(`${path}.examples[${i}]`);
+      }
+    }
+  }
+
+  static identityOf(
+    value: { toJSON?: () => unknown } | unknown | null,
+  ): string {
+    if (value == null) return '';
+    if (typeof value === 'object' && value !== null && 'toJSON' in value &&
+        typeof (value as { toJSON: unknown }).toJSON === 'function') {
+      return canonicalJson((value as { toJSON: () => unknown }).toJSON());
+    }
+    return canonicalJson(value);
+  }
+
+  override identity(): string {
+    return DetailedDefinition.identityOf(this);
+  }
+
+  static override fromJSON(data: DetailedDefinitionJson): DetailedDefinition {
+    return new DetailedDefinition(data);
+  }
+}

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);

package/src/models/grammar-info.ts

@@ -0,0 +1,78 @@
+import { GlossaristModel } from './base.js';
+
+export type GrammarGender = 'm' | 'f' | 'n' | 'c' | string;
+export type GrammarNumber = 'singular' | 'dual' | 'plural' | string;
+export type GrammarPartOfSpeech =
+  | 'noun'
+  | 'verb'
+  | 'adj'
+  | 'adverb'
+  | 'preposition'
+  | 'participle'
+  | string;
+
+export const GRAMMAR_GENDERS: ReadonlyArray<string> = Object.freeze([
+  'm', 'f', 'n', 'c',
+]);
+export const GRAMMAR_NUMBERS: ReadonlyArray<string> = Object.freeze([
+  'singular', 'dual', 'plural',
+]);
+export const GRAMMAR_PARTS_OF_SPEECH: ReadonlyArray<string> = Object.freeze([
+  'noun', 'verb', 'adj', 'adverb', 'preposition', 'participle',
+]);
+
+export interface GrammarInfoJson {
+  gender?: GrammarGender | null;
+  number?: GrammarNumber | null;
+  part_of_speech?: GrammarPartOfSpeech | null;
+  partOfSpeech?: GrammarPartOfSpeech | null;
+  noun?: boolean;
+  verb?: boolean;
+  adj?: boolean;
+  adverb?: boolean;
+  preposition?: boolean;
+  participle?: boolean;
+}
+
+export class GrammarInfo extends GlossaristModel {
+  readonly gender: GrammarGender | null;
+  readonly number: GrammarNumber | null;
+  readonly partOfSpeech: GrammarPartOfSpeech | null;
+  readonly noun: boolean;
+  readonly verb: boolean;
+  readonly adj: boolean;
+  readonly adverb: boolean;
+  readonly preposition: boolean;
+  readonly participle: boolean;
+
+  constructor(data: GrammarInfoJson = {}) {
+    super();
+    this.gender = data.gender ?? null;
+    this.number = data.number ?? null;
+    this.partOfSpeech = data.part_of_speech ?? data.partOfSpeech ?? null;
+    this.noun = data.noun ?? false;
+    this.verb = data.verb ?? false;
+    this.adj = data.adj ?? false;
+    this.adverb = data.adverb ?? false;
+    this.preposition = data.preposition ?? false;
+    this.participle = data.participle ?? false;
+  }
+
+  override toJSON(): GrammarInfoJson {
+    const obj: GrammarInfoJson = {};
+    if (this.gender != null) obj.gender = this.gender;
+    if (this.number != null) obj.number = this.number;
+    if (this.partOfSpeech != null) obj.part_of_speech = this.partOfSpeech;
+    if (this.noun) obj.noun = true;
+    if (this.verb) obj.verb = true;
+    if (this.adj) obj.adj = true;
+    if (this.adverb) obj.adverb = true;
+    if (this.preposition) obj.preposition = true;
+    if (this.participle) obj.participle = true;
+    return obj;
+  }
+
+  static override fromJSON(data: GrammarInfoJson): GrammarInfo {
+    return new GrammarInfo(data);
+  }
+}