glossarist 0.1.1 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glossarist",
-  "version": "0.1.1",
-  "description": "JavaScript library for reading Glossarist GCR packages and v2 concept data",
+  "version": "0.1.3",
+  "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -24,14 +24,24 @@
       "types": "./src/concept-reader.d.ts",
       "import": "./src/concept-reader.js",
       "default": "./src/concept-reader.js"
+    },
+    "./models": {
+      "types": "./src/models/index.d.ts",
+      "import": "./src/models/index.js",
+      "default": "./src/models/index.js"
+    },
+    "./validators": {
+      "types": "./src/validators/index.d.ts",
+      "import": "./src/validators/index.js",
+      "default": "./src/validators/index.js"
     }
   },
   "scripts": {
     "lint": "eslint src/ test/",
     "pretest": "node test/fixtures/build-fixtures.js",
-    "test": "node --test test/*.test.js",
-    "test:verbose": "node --test --test-reporter spec test/*.test.js",
-    "test:coverage": "node --test --experimental-test-coverage test/*.test.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"
   },
   "keywords": [

package/src/concept-collection.js

@@ -0,0 +1,109 @@
+import { naturalSort } from './gcr-reader.js';
+
+const _items = Symbol('items');
+
+export class ConceptCollection {
+  constructor(concepts = []) {
+    this[_items] = Array.from(concepts);
+    return new Proxy(this, _handler);
+  }
+
+  get length() { return this[_items].length; }
+  [Symbol.iterator]() { return this[_items][Symbol.iterator](); }
+
+  at(index) { return this[_items].at(index); }
+  indexOf(item) { return this[_items].indexOf(item); }
+  find(fn) { return this[_items].find(fn); }
+  findIndex(fn) { return this[_items].findIndex(fn); }
+  forEach(fn) { this[_items].forEach(fn); }
+  map(fn) { return this[_items].map(fn); }
+  reduce(fn, init) { return this[_items].reduce(fn, init); }
+  includes(item) { return this[_items].includes(item); }
+  push(...items) { return this[_items].push(...items); }
+  splice(...args) { return this[_items].splice(...args); }
+  set(index, item) { this[_items][index] = item; }
+
+  byId(id) {
+    return this[_items].find(c => c.id === id || c.termid === id);
+  }
+
+  byPrefix(prefix) {
+    return new ConceptCollection(this[_items].filter(c => c.id.startsWith(prefix)));
+  }
+
+  byLanguage(lang) {
+    return new ConceptCollection(this[_items].filter(c => c.hasLocalization(lang)));
+  }
+
+  byStatus(status) {
+    return new ConceptCollection(this[_items].filter(c => {
+      const langs = c.languages;
+      return langs.length > 0 && c.localization(langs[0])?.entryStatus === status;
+    }));
+  }
+
+  index() {
+    const map = new Map();
+    for (const c of this[_items]) map.set(c.id, c);
+    return map;
+  }
+
+  sorted() {
+    const copy = [...this[_items]];
+    copy.sort((a, b) => naturalSort(a.id, b.id));
+    return new ConceptCollection(copy);
+  }
+
+  search(query) {
+    const q = query.toLowerCase();
+    return new ConceptCollection(this[_items].filter(c => {
+      for (const lang of c.languages) {
+        const lc = c.localization(lang);
+        if (!lc) continue;
+        for (const t of lc.terms) {
+          if ((t.designation ?? '').toLowerCase().includes(q)) return true;
+        }
+        for (const d of lc.definitions) {
+          if ((d.content ?? '').toLowerCase().includes(q)) return true;
+        }
+      }
+      return false;
+    }));
+  }
+
+  allLanguages() {
+    const set = new Set();
+    for (const c of this[_items]) {
+      for (const lang of c.languages) set.add(lang);
+    }
+    return [...set].sort();
+  }
+
+  filter(fn) { return new ConceptCollection(this[_items].filter(fn)); }
+  slice(...args) { return new ConceptCollection(this[_items].slice(...args)); }
+  concat(...args) { return new ConceptCollection(this[_items].concat(...args)); }
+}
+
+const _handler = {
+  get(target, prop, receiver) {
+    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
+      return target[_items][Number(prop)];
+    }
+    if (prop === 'length') return target[_items].length;
+    const value = Reflect.get(target, prop, receiver);
+    return typeof value === 'function' ? value.bind(target) : value;
+  },
+  set(target, prop, value) {
+    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
+      target[_items][Number(prop)] = value;
+      return true;
+    }
+    return Reflect.set(target, prop, value);
+  },
+  has(target, prop) {
+    if (typeof prop === 'string' && /^\d+$/.test(prop)) {
+      return Number(prop) in target[_items];
+    }
+    return Reflect.has(target, prop);
+  },
+};

package/src/concept-parser.js

@@ -0,0 +1,78 @@
+import yaml from 'js-yaml';
+import { Concept } from './models/concept.js';
+import { InvalidInputError, YamlParseError } from './errors.js';
+
+const STRUCTURAL_KEYS = new Set(['termid', 'term']);
+
+export class ConceptParser {
+  parse(raw, context) {
+    const label = context ?? 'concept';
+
+    if (raw == null) {
+      throw new InvalidInputError(
+        `parseConceptYaml requires a non-empty YAML string (${label})`,
+        'non-null string',
+      );
+    }
+    if (typeof raw !== 'string' || raw.trim() === '') {
+      throw new InvalidInputError(
+        `parseConceptYaml requires a non-empty YAML string (${label})`,
+        'non-empty string',
+      );
+    }
+
+    let docs;
+    try {
+      docs = yaml.loadAll(raw, null, { schema: yaml.DEFAULT_SCHEMA });
+    } catch (err) {
+      throw new YamlParseError(label, err);
+    }
+
+    return this._detectFormat(docs, label) === 'managed'
+      ? this._parseManaged(docs)
+      : this._parseCanonical(docs[0]);
+  }
+
+  _detectFormat(docs, label) {
+    if (docs.length >= 1 && docs[0]?.data?.identifier !== undefined) return 'managed';
+    if (docs[0] == null) throw new YamlParseError(label, new Error('YAML document is empty'));
+    return 'canonical';
+  }
+
+  _parseCanonical(doc) {
+    const localizations = {};
+    for (const key of Object.keys(doc)) {
+      if (!STRUCTURAL_KEYS.has(key) && typeof doc[key] === 'object' && doc[key] !== null) {
+        localizations[key] = doc[key];
+      }
+    }
+    return new Concept({
+      id: String(doc.termid),
+      term: doc.term || null,
+      localizations,
+      raw: doc,
+    });
+  }
+
+  _parseManaged(docs) {
+    const mc = docs[0];
+    const localizations = {};
+
+    for (const doc of docs.slice(1)) {
+      if (!doc?.data?.language_code) continue;
+      const lang = doc.data.language_code;
+      const lcData = { ...doc.data };
+      delete lcData.language_code;
+      localizations[lang] = lcData;
+    }
+
+    return new Concept({
+      id: String(mc.data.identifier),
+      term: null,
+      localizations,
+      raw: mc,
+    });
+  }
+}
+
+export const conceptParser = new ConceptParser();

package/src/concept-reader.js

@@ -1,7 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import yaml from 'js-yaml';
-import { parseConceptYaml, naturalSort } from './gcr-reader.js';
+import { conceptParser } from './concept-parser.js';
+import { naturalSort } from './gcr-reader.js';
 import { InvalidInputError } from './errors.js';
 
 function assertDir(dir, fnName) {
@@ -13,7 +14,7 @@ function assertDir(dir, fnName) {
 /**
  * Read all v2 glossarist concept YAML files from a directory.
  * @param {string} dir - path to directory containing concept YAML files
- * @returns {import('./gcr-reader.js').Concept[]}
+ * @returns {import('./models/concept.js').Concept[]}
  * @throws {InvalidInputError} if dir is missing or empty
  *
  * @example
@@ -29,8 +30,8 @@ export function readConcepts(dir) {
   const concepts = [];
   for (const file of files) {
     const raw = fs.readFileSync(path.join(dir, file), 'utf8');
-    const concept = parseConceptYaml(raw, file);
-    if (concept && concept.termid) {
+    const concept = conceptParser.parse(raw, file);
+    if (concept && concept.id) {
       concepts.push(concept);
     }
   }
@@ -41,7 +42,7 @@ export function readConcepts(dir) {
  * Read a single concept file by ID from a directory.
  * @param {string} dir - path to directory containing concept YAML files
  * @param {string} id - concept identifier (filename without .yaml)
- * @returns {import('./gcr-reader.js').Concept | null}
+ * @returns {import('./models/concept.js').Concept | null}
  * @throws {InvalidInputError} if dir or id is missing or empty
  *
  * @example
@@ -56,7 +57,7 @@ export function readConcept(dir, id) {
   const filePath = path.join(dir, `${id}.yaml`);
   if (!fs.existsSync(filePath)) return null;
   const raw = fs.readFileSync(filePath, 'utf8');
-  return parseConceptYaml(raw, `${id}.yaml`);
+  return conceptParser.parse(raw, `${id}.yaml`);
 }
 
 /**

package/src/concept-serializer.js

@@ -0,0 +1,60 @@
+import yaml from 'js-yaml';
+
+const DUMP_OPTS = { lineWidth: -1, noRefs: true, sortKeys: false, skipInvalid: true };
+
+export class ConceptSerializer {
+  toCanonicalYaml(concept) {
+    const doc = { termid: concept.id };
+    if (concept.term) doc.term = concept.term;
+
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (lc) {
+        const lcObj = lc.toJSON();
+        delete lcObj.language_code;
+        doc[lang] = lcObj;
+      }
+    }
+
+    return yaml.dump(doc, DUMP_OPTS);
+  }
+
+  toManagedYaml(concept, uuidFn) {
+    const genId = uuidFn ?? (() => crypto.randomUUID());
+    const localizedConcepts = {};
+    const langDocs = [];
+
+    for (const lang of concept.languages) {
+      const lc = concept.localization(lang);
+      if (!lc) continue;
+      const lcId = genId();
+      localizedConcepts[lang] = lcId;
+
+      const lcObj = lc.toJSON();
+      langDocs.push({ data: lcObj, id: lcId });
+    }
+
+    const mainDoc = {
+      data: { identifier: concept.id, localized_concepts: localizedConcepts },
+      id: genId(),
+    };
+
+    const parts = [
+      '---\n' + yaml.dump(mainDoc, DUMP_OPTS),
+      ...langDocs.map(d => '---\n' + yaml.dump(d, DUMP_OPTS)),
+    ];
+    return parts.join('');
+  }
+
+  toYaml(concept, uuidFn) {
+    return concept.term
+      ? this.toCanonicalYaml(concept)
+      : this.toManagedYaml(concept, uuidFn);
+  }
+
+  toRegisterYaml(data) {
+    return yaml.dump(data, DUMP_OPTS);
+  }
+}
+
+export const conceptSerializer = new ConceptSerializer();

package/src/concept-writer.d.ts

@@ -0,0 +1,7 @@
+import { Concept } from './models/index';
+
+export function writeConcept(dir: string, concept: Concept, format?: 'canonical' | 'managed' | 'auto'): void;
+export function writeConcepts(dir: string, concepts: Concept[], options?: {
+  register?: Record<string, unknown>;
+  format?: 'canonical' | 'managed' | 'auto';
+}): void;

package/src/concept-writer.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import path from 'path';
+import { conceptSerializer } from './concept-serializer.js';
+import { InvalidInputError } from './errors.js';
+
+function assertDir(dir, fnName) {
+  if (typeof dir !== 'string' || dir.trim() === '') {
+    throw new InvalidInputError(`${fnName} requires a directory path`, 'non-empty string');
+  }
+}
+
+export function writeConcept(dir, concept, format = 'auto') {
+  assertDir(dir, 'writeConcept');
+  if (!concept?.id) {
+    throw new InvalidInputError('writeConcept requires a Concept with an id', 'Concept');
+  }
+
+  const y = format === 'canonical'
+    ? conceptSerializer.toCanonicalYaml(concept)
+    : format === 'managed'
+      ? conceptSerializer.toManagedYaml(concept)
+      : conceptSerializer.toYaml(concept);
+
+  fs.writeFileSync(path.join(dir, `${concept.id}.yaml`), y, 'utf8');
+}
+
+export function writeConcepts(dir, concepts, options = {}) {
+  assertDir(dir, 'writeConcepts');
+  fs.mkdirSync(dir, { recursive: true });
+
+  for (const concept of concepts) {
+    writeConcept(dir, concept, options.format);
+  }
+
+  if (options.register) {
+    fs.writeFileSync(
+      path.join(dir, 'register.yaml'),
+      conceptSerializer.toRegisterYaml(options.register),
+      'utf8',
+    );
+  }
+}

package/src/gcr-reader.js

@@ -1,8 +1,7 @@
 import JSZip from 'jszip';
 import yaml from 'js-yaml';
-import { InvalidInputError, YamlParseError } from './errors.js';
-
-const STRUCTURAL_KEYS = new Set(['termid', 'term']);
+import { conceptParser } from './concept-parser.js';
+import { InvalidInputError } from './errors.js';
 
 const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 
@@ -120,7 +119,7 @@ export class GcrPackage {
   async concept(id) {
     const raw = await this._readText(`concepts/${id}.yaml`);
     if (raw === null) return null;
-    return parseConceptYaml(raw, id);
+    return conceptParser.parse(raw, id);
   }
 
   /**
@@ -163,13 +162,6 @@ export class GcrPackage {
 /**
  * Parse concept YAML (canonical or managed format) into a normalized object.
  *
- * Canonical format (single doc):
- *   { termid: "3.1.1.1", eng: { terms: [...], definition: [...] }, ... }
- *
- * Managed concept format (multi-doc):
- *   doc 0: { data: { identifier: "3.1.1.1", localized_concepts: { eng: "uuid" } }, id: "uuid" }
- *   doc 1+: { data: { language_code: "eng", terms: [...], ... }, id: "uuid" }
- *
  * @param {string} raw - raw YAML string
  * @param {string} [context] - concept ID or filename for error messages
  * @returns {Concept}
@@ -181,73 +173,7 @@ export class GcrPackage {
  * console.log(concept.localizations.eng.terms[0].designation); // "test"
  */
 export function parseConceptYaml(raw, context) {
-  const label = context ?? 'concept';
-
-  if (raw == null) {
-    throw new InvalidInputError(`parseConceptYaml requires a non-empty YAML string (${label})`, 'non-null string');
-  }
-  if (typeof raw !== 'string' || raw.trim() === '') {
-    throw new InvalidInputError(`parseConceptYaml requires a non-empty YAML string (${label})`, 'non-empty string');
-  }
-
-  let docs;
-  try {
-    docs = yaml.loadAll(raw, null, { schema: yaml.DEFAULT_SCHEMA });
-  } catch (err) {
-    throw new YamlParseError(label, err);
-  }
-
-  if (docs.length === 1 && docs[0]?.termid !== undefined) {
-    return normalizeCanonical(docs[0]);
-  }
-
-  if (docs.length >= 1 && docs[0]?.data?.identifier !== undefined) {
-    return normalizeManaged(docs);
-  }
-
-  if (docs[0] == null) {
-    throw new YamlParseError(label, new Error('YAML document is empty'));
-  }
-
-  return normalizeCanonical(docs[0]);
-}
-
-/** @private @param {Record<string, any>} doc @returns {Concept} */
-function normalizeCanonical(doc) {
-  const localizations = {};
-  for (const key of Object.keys(doc)) {
-    if (!STRUCTURAL_KEYS.has(key) && typeof doc[key] === 'object' && doc[key] !== null) {
-      localizations[key] = doc[key];
-    }
-  }
-  return {
-    termid: String(doc.termid),
-    term: doc.term || null,
-    localizations,
-    raw: doc,
-  };
-}
-
-/** @private @param {Record<string, any>[]} docs @returns {Concept} */
-function normalizeManaged(docs) {
-  const mc = docs[0];
-  const termid = String(mc.data.identifier);
-  const localizations = {};
-
-  for (const doc of docs.slice(1)) {
-    if (!doc || !doc.data || !doc.data.language_code) continue;
-    const lang = doc.data.language_code;
-    const lcData = { ...doc.data };
-    delete lcData.language_code;
-    localizations[lang] = lcData;
-  }
-
-  return {
-    termid,
-    term: null,
-    localizations,
-    raw: mc,
-  };
+  return conceptParser.parse(raw, context);
 }
 
 // --- Helpers ---

package/src/gcr-writer.d.ts

@@ -0,0 +1,13 @@
+import { Concept } from './models/index';
+
+export class GcrWriter {
+  static createBuffer(options: {
+    concepts: Concept[];
+    metadata?: Record<string, unknown>;
+    register?: Record<string, unknown>;
+    uuidFn?: () => string;
+    format?: 'canonical' | 'managed' | 'auto';
+  }): Promise<Uint8Array>;
+}
+
+export function createGcr(concepts: Concept[], metadata?: Record<string, unknown>): Promise<Uint8Array>;

package/src/gcr-writer.js

@@ -0,0 +1,38 @@
+import JSZip from 'jszip';
+import { conceptSerializer } from './concept-serializer.js';
+import { InvalidInputError } from './errors.js';
+
+export class GcrWriter {
+  static async createBuffer(options) {
+    if (!options || !options.concepts || typeof options.concepts[Symbol.iterator] !== 'function') {
+      throw new InvalidInputError(
+        'GcrWriter requires { concepts: Concept[] }',
+        'object with concepts array',
+      );
+    }
+
+    const zip = new JSZip();
+
+    if (options.metadata) {
+      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(options.metadata));
+    }
+    if (options.register) {
+      zip.file('register.yaml', conceptSerializer.toRegisterYaml(options.register));
+    }
+
+    for (const concept of options.concepts) {
+      const y = options.format === 'canonical'
+        ? conceptSerializer.toCanonicalYaml(concept)
+        : options.format === 'managed'
+          ? conceptSerializer.toManagedYaml(concept, options.uuidFn)
+          : conceptSerializer.toYaml(concept, options.uuidFn);
+      zip.file(`concepts/${concept.id}.yaml`, y);
+    }
+
+    return zip.generateAsync({ type: 'uint8array' });
+  }
+}
+
+export async function createGcr(concepts, metadata) {
+  return GcrWriter.createBuffer({ concepts, metadata });
+}

package/src/index.d.ts

@@ -1,4 +1,41 @@
+// Models
+export {
+  GlossaristModel,
+  Concept, LocalizedConcept,
+  Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
+  Citation, ConceptSource, RelatedConcept, ConceptDate,
+  DetailedDefinition, NonVerbRep,
+  RELATIONSHIP_TYPES, DATE_TYPES,
+} from './models/index';
+
+// GCR reader
 export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
-export type { Concept, Localization, Term, Definition, Source, GcrMetadata } from './gcr-reader';
+export type { GcrMetadata } from './gcr-reader';
+
+// GCR writer
+export { createGcr, GcrWriter } from './gcr-writer';
+
+// Concept reader
 export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader';
+
+// Concept writer
+export { writeConcept, writeConcepts } from './concept-writer';
+
+// Collections
+export { ConceptCollection } from './concept-collection';
+export { ManagedConceptCollection } from './managed-concept-collection';
+
+// Validators
+export { validateConcept, validateRegister, createConceptValidator, ValidationError, ValidationRule, RegisterValidator } from './validators/index';
+
+// UUID
+export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
+
+// Reference resolution
+export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver';
+
+// V1 support
+export { V1Reader, migrateV1ToV2 } from './v1-reader';
+
+// Errors
 export { GlossaristError, InvalidInputError, YamlParseError } from './errors';

package/src/index.js

@@ -1,3 +1,20 @@
 export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader.js';
 export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader.js';
+export { writeConcept, writeConcepts } from './concept-writer.js';
+export { createGcr, GcrWriter } from './gcr-writer.js';
+export { ConceptCollection } from './concept-collection.js';
+export { ManagedConceptCollection } from './managed-concept-collection.js';
+export { validateConcept, validateRegister, createConceptValidator, ValidationError, ValidationRule, RegisterValidator } from './validators/index.js';
+export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid.js';
+export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver.js';
+export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
 export { GlossaristError, InvalidInputError, YamlParseError } from './errors.js';
+
+export {
+  GlossaristModel,
+  Concept, LocalizedConcept,
+  Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
+  Citation, ConceptSource, RelatedConcept, ConceptDate,
+  DetailedDefinition, NonVerbRep,
+  RELATIONSHIP_TYPES, DATE_TYPES,
+} from './models/index.js';

package/src/managed-concept-collection.js

@@ -0,0 +1,61 @@
+import { ConceptCollection } from './concept-collection.js';
+import { readConcepts, readRegister } from './concept-reader.js';
+import { writeConcepts } from './concept-writer.js';
+import { loadGcr } from './gcr-reader.js';
+import { createGcr } from './gcr-writer.js';
+
+export class ManagedConceptCollection {
+  constructor() {
+    this._concepts = new ConceptCollection();
+    this._register = null;
+  }
+
+  get concepts() { return this._concepts; }
+  get register() { return this._register; }
+
+  loadFromDirectory(dir) {
+    this._concepts = new ConceptCollection(readConcepts(dir));
+    this._register = readRegister(dir);
+    return this;
+  }
+
+  async loadFromGcr(input) {
+    const pkg = await loadGcr(input);
+    this._concepts = new ConceptCollection(await pkg.allConcepts());
+    this._register = await pkg.register();
+    return this;
+  }
+
+  saveToDirectory(dir, options = {}) {
+    writeConcepts(dir, this._concepts, {
+      register: this._register ?? undefined,
+      format: options.format,
+    });
+  }
+
+  async saveToGcr(options = {}) {
+    return createGcr(this._concepts, options.metadata);
+  }
+
+  add(concept) {
+    const existing = this._concepts.byId(concept.id);
+    if (existing) {
+      const idx = this._concepts.indexOf(existing);
+      this._concepts.set(idx, concept);
+    } else {
+      this._concepts.push(concept);
+    }
+    return this;
+  }
+
+  remove(id) {
+    const idx = this._concepts.findIndex(c => c.id === id);
+    if (idx >= 0) this._concepts.splice(idx, 1);
+    return this;
+  }
+
+  setRegister(data) {
+    this._register = data;
+    return this;
+  }
+}