glossarist 0.4.37 → 0.4.38

package/package.json

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

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/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/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);
+  }
+}

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/{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/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);
-  }
-}

package/src/models/detailed-definition.js

@@ -1,59 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Citation } from './citation.js';
-import { canonicalJson } from '../diff/canonical-json.js';
-
-export class DetailedDefinition extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.content = data.content ?? '';
-    this._rawSources = data.sources ?? [];
-    this._rawExamples = data.examples ?? [];
-    this._sources = null;
-    this._examples = null;
-  }
-
-  get sources() {
-    return this._lazy('_sources', '_rawSources',
-      s => s instanceof Citation ? s : new Citation(s));
-  }
-
-  get examples() {
-    return this._lazy('_examples', '_rawExamples',
-      e => e instanceof DetailedDefinition ? e : new DetailedDefinition(e));
-  }
-
-  toJSON() {
-    const obj = { content: this.content };
-    this._serialize(obj, 'sources', '_sources', '_rawSources');
-    this._serialize(obj, '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) {
-    if (typeof this.content === 'string' && this.content.length > 0) {
-      yield { text: this.content, source: `${path}.content` };
-    }
-    for (let i = 0; i < this.examples.length; i++) {
-      yield* this.examples[i].walkTexts(`${path}.examples[${i}]`);
-    }
-  }
-
-  static identityOf(value) {
-    if (value == null) return '';
-    if (typeof value.toJSON === 'function') return canonicalJson(value.toJSON());
-    return canonicalJson(value);
-  }
-
-  identity() {
-    return DetailedDefinition.identityOf(this);
-  }
-
-  static fromJSON(data) {
-    return new DetailedDefinition(data);
-  }
-}

package/src/models/grammar-info.js

@@ -1,40 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export const GRAMMAR_GENDERS = Object.freeze(['m', 'f', 'n', 'c']);
-export const GRAMMAR_NUMBERS = Object.freeze(['singular', 'dual', 'plural']);
-export const GRAMMAR_PARTS_OF_SPEECH = Object.freeze([
-  'noun', 'verb', 'adj', 'adverb', 'preposition', 'participle',
-]);
-
-export class GrammarInfo extends GlossaristModel {
-  constructor(data = {}) {
-    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;
-  }
-
-  toJSON() {
-    const obj = {};
-    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 fromJSON(data) {
-    return new GrammarInfo(data);
-  }
-}

package/src/models/localized-string.js

@@ -1,19 +0,0 @@
-const FALLBACK_LANG = 'eng';
-
-export function fetchLocalizedString(hash, lang, fallback = FALLBACK_LANG) {
-  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) {
-  return hash == null || (typeof hash === 'object' && Object.keys(hash).length === 0);
-}
-
-export function localizedStringIsPresent(hash) {
-  return !localizedStringIsEmpty(hash);
-}