glossarist 0.4.35 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.35",
+  "version": "0.4.37",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",
@@ -65,14 +65,16 @@
   },
   "scripts": {
     "lint": "eslint src/ test/",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
     "sync:model": "node scripts/sync-concept-model.mjs",
     "gen:predicates": "node scripts/gen-predicates.mjs",
     "prebuild": "npm run gen:predicates",
     "pretest": "node test/fixtures/build-fixtures.js",
-    "test": "find test -name '*.test.js' | sort | xargs node --test",
-    "test:verbose": "find test -name '*.test.js' | sort | xargs node --test --test-reporter spec",
-    "test:coverage": "find test -name '*.test.js' | sort | xargs node --test --experimental-test-coverage",
-    "prepublishOnly": "npm test"
+    "test": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test",
+    "test:verbose": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test --test-reporter spec",
+    "test:coverage": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test --experimental-test-coverage",
+    "prepublishOnly": "npm run typecheck && npm test"
   },
   "keywords": [
     "glossarist",
@@ -108,7 +110,14 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@rdfjs/types": "^2.0.1",
+    "@types/node": "^26.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.3.0",
-    "globals": "^17.6.0"
+    "globals": "^17.6.0",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0"
   }
 }

package/src/models/abstract-hyperedge.ts

@@ -0,0 +1,164 @@
+// AbstractHyperedge — shared base for directed 1→N hyperedges
+// (PartitiveHyperedge, GenericHyperedge, SequentialHyperedge, future
+// AssociativeHyperedge, etc.).
+//
+// Carries the common shape:
+//   - comprehensive: ConceptRef
+//   - members: 2+ MECE dimensioned concept refs (≥2 per ISO 704)
+//   - completeness: complete | partial
+//   - criterion: localized subdivision criterion (ISO 12620)
+//   - sources / notes / status: administrative metadata
+//
+// See docs/design/abstract-hyperedge.md (concept-model repo).
+
+import { GlossaristModel } from './base.js';
+import { ConceptRef } from './concept-ref.js';
+import type { ConceptRefJson } from './concept-ref.js';
+import { DEFAULT_COMPLETENESS, isValidCompleteness } from './completeness.js';
+import type { Completeness } from './completeness.js';
+import type { HyperedgeMember } from './hyperedge-member.js';
+import type { LocalizedString } from './generic-member.js';
+
+export interface AbstractHyperedgeJson {
+  comprehensive: ConceptRefJson;
+  members: ReadonlyArray<unknown>;
+  completeness: Completeness;
+  criterion?: LocalizedString;
+  sources?: ReadonlyArray<unknown>;
+  notes?: Record<string, unknown> | null;
+  status?: string | null;
+  /** PartitiveHyperedge wire alias (only present on PartitiveHyperedge JSON). */
+  partitives?: ReadonlyArray<unknown>;
+}
+
+export type CriterionInput = string | LocalizedString | null | undefined;
+
+export abstract class AbstractHyperedge extends GlossaristModel {
+  readonly comprehensive: ConceptRef;
+  readonly members: ReadonlyArray<HyperedgeMember>;
+  readonly completeness: Completeness;
+  readonly criterion: LocalizedString | null;
+  readonly sources: ReadonlyArray<unknown>;
+  readonly notes: Record<string, unknown> | null;
+  readonly status: string | null;
+
+  constructor(
+    data: AbstractHyperedgeJson = {
+      comprehensive: {},
+      members: [],
+      completeness: 'complete',
+    },
+  ) {
+    super();
+    this.comprehensive = _ensureComprehensive(data.comprehensive);
+    this.members = _ensureMembers(
+      data.members,
+      this.constructor.name,
+    ) as ReadonlyArray<HyperedgeMember>;
+    this.completeness = _resolveCompleteness(data.completeness);
+    this.criterion = _normalizeCriterion(data.criterion);
+    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
+    this.notes = (data.notes as Record<string, unknown> | null) ?? null;
+    this.status = data.status ?? null;
+
+    _assertNoSelfLoop(this.comprehensive, this.members);
+  }
+
+  get isComplete(): boolean { return this.completeness === 'complete'; }
+  get isPartial(): boolean { return this.completeness === 'partial'; }
+  get isCoordinate(): boolean { return this.members.length >= 2; }
+
+  hasCriterion(): boolean { return this.criterion != null; }
+
+  override identity(): string {
+    const Ctor = this.constructor as unknown as { identityOf: (v: unknown) => string };
+    return Ctor.identityOf(this);
+  }
+
+  override toJSON(): AbstractHyperedgeJson {
+    const obj: AbstractHyperedgeJson = {
+      comprehensive: this.comprehensive.toJSON(),
+      members: this.members.map((m) => m.toJSON()),
+      completeness: this.completeness,
+    };
+    if (this.criterion != null) obj.criterion = { ...this.criterion };
+    if (this.sources.length > 0) obj.sources = [...this.sources];
+    if (this.notes != null) obj.notes = { ...this.notes };
+    if (this.status != null) obj.status = this.status;
+    return obj;
+  }
+}
+
+function _ensureComprehensive(
+  value: ConceptRefJson | ConceptRef | null | undefined,
+): ConceptRef {
+  const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
+  if (!ref.source && !ref.id && !ref.text) {
+    throw new Error(
+      'AbstractHyperedge.comprehensive must be a non-empty ConceptReference ' +
+      '(source, id, or text required)',
+    );
+  }
+  return ref;
+}
+
+function _ensureMembers(
+  values: ReadonlyArray<unknown> | null | undefined,
+  typeName: string,
+): ReadonlyArray<unknown> {
+  if (!Array.isArray(values)) {
+    throw new Error(
+      `${typeName}.members must be an array (got ${values === null ? 'null' : typeof values})`,
+    );
+  }
+  if (values.length < 2) {
+    throw new Error(
+      `${typeName} requires ≥2 partitives (ISO 704); got ${values.length}`,
+    );
+  }
+  return values;
+}
+
+function _resolveCompleteness(
+  value: Completeness | null | undefined,
+): Completeness {
+  const c = value ?? DEFAULT_COMPLETENESS;
+  if (!isValidCompleteness(c)) {
+    throw new Error(
+      `completeness has invalid value ${JSON.stringify(value)}`,
+    );
+  }
+  return c;
+}
+
+function _normalizeCriterion(value: CriterionInput): LocalizedString | null {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    return value.length > 0 ? { default: value } : null;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value).filter(
+      ([, v]) => typeof v === 'string',
+    );
+    return entries.length > 0
+      ? (Object.fromEntries(entries) as LocalizedString)
+      : null;
+  }
+  return null;
+}
+
+function _assertNoSelfLoop(
+  comprehensive: ConceptRef,
+  members: ReadonlyArray<{ ref?: { source?: string | null; id?: string | null } }>,
+): void {
+  const cKey = `${comprehensive.source ?? ''}:${comprehensive.id ?? ''}`;
+  for (const m of members) {
+    const ref = m.ref;
+    const pKey = `${ref?.source ?? ''}:${ref?.id ?? ''}`;
+    if (pKey === cKey && (ref?.source || ref?.id)) {
+      throw new Error(
+        'Relation.members cannot include the comprehensive (no self-loops)',
+      );
+    }
+  }
+}

package/src/models/base.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+export abstract class GlossaristModel {
+  /** Wire-shape serialization. Subclasses MUST override. */
+  toJSON(): object {
+    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/{completeness.js → completeness.ts}

@@ -5,14 +5,11 @@
 // ISO 704 depicts this as the rake's backline: a backline ending with
 // a tooth is complete; a backline continuing without a tooth is
 // partial.
-//
-// Renamed from the v1 `PartitiveEnumeration` (closed|open) per
-// TODO.partitive-relation-v2 item 02. The semantic claim being
-// expressed is completeness of the decomposition, not "enumeration"
-// (which is a neutral-sounding word that doesn't convey the claim).
 
 import { makeEnum } from './enum.js';
 
+export type Completeness = 'complete' | 'partial';
+
 export const COMPLETENESS = makeEnum('COMPLETENESS', {
   COMPLETE: 'complete',
   PARTIAL: 'partial',
@@ -21,4 +18,4 @@ export const COMPLETENESS = makeEnum('COMPLETENESS', {
 export const COMPLETENESS_VALUES = COMPLETENESS.VALUES;
 export const isValidCompleteness = COMPLETENESS.isValid;
 
-export const DEFAULT_COMPLETENESS = COMPLETENESS.COMPLETE;
+export const DEFAULT_COMPLETENESS: Completeness = COMPLETENESS.COMPLETE;

package/src/models/concept-date.ts

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,64 @@
+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-source.ts

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,39 @@
+// 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;