glossarist 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Glossarist Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# glossarist-js
+
+[![CI](https://github.com/glossarist/glossarist-js/actions/workflows/ci.yml/badge.svg)](https://github.com/glossarist/glossarist-js/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/glossarist.svg)](https://www.npmjs.com/package/glossarist)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+JavaScript library for reading [Glossarist](https://github.com/glossarist) GCR packages (ZIP archives) and v2 glossarist concept data (YAML files). Works in Node.js and browsers.
+
+## Install
+
+```bash
+npm install glossarist
+```
+
+Requires Node.js 18+.
+
+## Usage
+
+### Reading a GCR package
+
+```js
+import { loadGcr } from 'glossarist';
+import fs from 'fs';
+
+const buf = fs.readFileSync('my-dataset.gcr');
+const pkg = await loadGcr(buf);
+
+// Metadata
+const meta = await pkg.metadata();
+console.log(meta.shortname, meta.version, meta.concept_count);
+
+// List concept IDs
+const ids = await pkg.conceptIds();
+
+// Read a specific concept
+const concept = await pkg.concept('3.1.1.1');
+console.log(concept.termid);
+console.log(concept.localizations.eng.terms[0].designation);
+
+// Iterate all concepts (streaming)
+await pkg.eachConcept((concept) => {
+  console.log(concept.termid);
+});
+```
+
+`loadGcr` accepts `Buffer`, `ArrayBuffer`, `Uint8Array`, `Blob`, or a base64-encoded string.
+
+### Reading concept YAML files from a directory
+
+```js
+import { readConcepts, readConcept, listConceptIds } from 'glossarist';
+
+// Read all concepts
+const concepts = readConcepts('./geolexica-v2/');
+console.log(`Loaded ${concepts.length} concepts`);
+
+// Read a single concept by ID
+const concept = readConcept('./geolexica-v2/', '3.1.1.1');
+
+// List IDs with optional prefix filter
+const ids = listConceptIds('./geolexica-v2/', '3.1.');
+```
+
+### Browser usage
+
+The GCR reader works in browsers via jszip. The concept directory reader requires Node.js `fs`.
+
+```html
+<script type="module">
+  import { loadGcr } from 'glossarist/gcr';
+
+  const response = await fetch('/datasets/isotc204.gcr');
+  const buf = await response.arrayBuffer();
+  const pkg = await loadGcr(buf);
+  const meta = await pkg.metadata();
+</script>
+```
+
+## Concept format
+
+Glossarist-js normalizes both storage formats into a consistent structure:
+
+```js
+{
+  termid: '3.1.1.1',           // concept identifier
+  term: 'entity',               // primary term (canonical format only)
+  localizations: {
+    eng: {
+      terms: [{ type: 'expression', designation: 'entity', normative_status: 'preferred' }],
+      definition: [{ content: 'concrete or abstract thing...' }],
+      notes: [],
+      examples: [],
+      sources: [{ type: 'authoritative', origin: { ref: 'ISO/TS 14812:2022' } }],
+      entry_status: 'valid',
+    },
+    fra: { ... },
+  },
+  raw: { ... },                 // original parsed YAML
+}
+```
+
+Language codes are discovered dynamically from the YAML keys — any ISO 639-3 code works without code changes.
+
+### Supported formats
+
+| Format | Structure | Used by |
+|--------|-----------|---------|
+| **Canonical** | Single YAML document with `termid` and language keys (`eng:`, `fra:`) | IEV (iec-electropedia) |
+| **Managed concept** | Multi-document YAML: first doc has `data.identifier` + `data.localized_concepts`, subsequent docs have `data.language_code` | isotc204, isotc211, osgeo |
+
+## Error handling
+
+All public functions validate inputs and throw descriptive errors with context:
+
+```js
+import { InvalidInputError, YamlParseError } from 'glossarist';
+
+try {
+  await pkg.concept('3.1.1.1');
+} catch (err) {
+  if (err instanceof YamlParseError) {
+    // err.message: "Failed to parse YAML for 3.1.1.1: ..."
+    // err.cause: the original YAML parse error
+  } else if (err instanceof InvalidInputError) {
+    // Invalid input (null, empty string, wrong type)
+  }
+}
+```
+
+Errors include the concept ID or filename in their message, making it easy to locate failures in large datasets.
+
+- **`GlossaristError`** — base class for all library errors
+- **`InvalidInputError`** — null, undefined, empty, or wrong-type arguments
+- **`YamlParseError`** — malformed YAML with `cause` chaining the original error
+
+## TypeScript
+
+TypeScript declarations are included. No `@types/` package needed.
+
+```ts
+import { loadGcr, readConcepts, type Concept, type GcrMetadata } from 'glossarist';
+
+const pkg = await loadGcr(buffer);
+const meta: GcrMetadata | null = await pkg.metadata();
+```
+
+## API
+
+### GCR Package (`glossarist/gcr`)
+
+- `loadGcr(input)` — Load a GCR ZIP from Buffer/ArrayBuffer/Uint8Array/Blob/base64 string. Returns `GcrPackage`.
+- `GcrPackage#metadata()` — Parse `metadata.yaml`.
+- `GcrPackage#register()` — Parse optional `register.yaml`.
+- `GcrPackage#conceptIds()` — Array of concept IDs (natural-sorted).
+- `GcrPackage#concept(id)` — Read and normalize a single concept.
+- `GcrPackage#eachConcept(callback)` — Stream all concepts.
+- `GcrPackage#allConcepts()` — Load all concepts into an array.
+- `parseConceptYaml(raw, context?)` — Parse raw YAML string into normalized concept object. `context` is an optional concept ID or filename for error messages.
+- `naturalSort(a, b)` — Natural sort comparator for concept IDs.
+
+### Concept Directory Reader (`glossarist/concept`)
+
+Node.js only (uses `fs`).
+
+- `readConcepts(dir)` — Read all concept YAML files from a directory.
+- `readConcept(dir, id)` — Read a single concept by ID.
+- `listConceptIds(dir, prefix?)` — List concept IDs, optionally filtered by prefix.
+- `readRegister(dir)` — Read `register.yaml` if present.
+
+### Errors
+
+- `GlossaristError` — base error class
+- `InvalidInputError` — bad input arguments
+- `YamlParseError` — YAML parse failures (has `cause`, includes concept context)
+
+## Development
+
+```bash
+npm install
+npm test                # regenerate fixtures + run all tests
+npm run lint            # lint src/ and test/
+npm run test:coverage   # run with coverage report
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for full guidelines.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "glossarist",
+  "version": "0.1.0",
+  "description": "JavaScript library for reading Glossarist GCR packages and v2 concept data",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./gcr": {
+      "types": "./src/gcr-reader.d.ts",
+      "import": "./src/gcr-reader.js",
+      "default": "./src/gcr-reader.js"
+    },
+    "./concept": {
+      "types": "./src/concept-reader.d.ts",
+      "import": "./src/concept-reader.js",
+      "default": "./src/concept-reader.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",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "glossarist",
+    "gcr",
+    "terminology",
+    "glossary",
+    "iso",
+    "geolexica"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glossarist/glossarist-js.git"
+  },
+  "homepage": "https://github.com/glossarist/glossarist-js#readme",
+  "bugs": {
+    "url": "https://github.com/glossarist/glossarist-js/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.3.0",
+    "globals": "^17.6.0"
+  }
+}

package/src/concept-reader.d.ts

@@ -0,0 +1,13 @@
+import type { Concept } from './gcr-reader';
+
+/** Read all concept YAML files from a directory. */
+export function readConcepts(dir: string): Concept[];
+
+/** Read a single concept by ID from a directory. */
+export function readConcept(dir: string, id: string): Concept | null;
+
+/** List all concept IDs in a directory, optionally filtered by prefix. */
+export function listConceptIds(dir: string, prefix?: string): string[];
+
+/** Read register.yaml from a dataset directory (if present). */
+export function readRegister(dir: string): Record<string, unknown> | null;

package/src/concept-reader.js

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { parseConceptYaml, naturalSort } from './gcr-reader.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');
+  }
+}
+
+/**
+ * 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[]}
+ * @throws {InvalidInputError} if dir is missing or empty
+ *
+ * @example
+ * const concepts = readConcepts('./geolexica-v2/');
+ * console.log(concepts[0].localizations.eng.terms[0].designation);
+ */
+export function readConcepts(dir) {
+  assertDir(dir, 'readConcepts');
+  const files = fs.readdirSync(dir)
+    .filter(f => f.endsWith('.yaml') && f !== 'register.yaml')
+    .sort(naturalSort);
+
+  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) {
+      concepts.push(concept);
+    }
+  }
+  return concepts;
+}
+
+/**
+ * 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}
+ * @throws {InvalidInputError} if dir or id is missing or empty
+ *
+ * @example
+ * const concept = readConcept('./geolexica-v2/', '3.1.1.1');
+ * if (concept) console.log(concept.termid);
+ */
+export function readConcept(dir, id) {
+  assertDir(dir, 'readConcept');
+  if (typeof id !== 'string' || id.trim() === '') {
+    throw new InvalidInputError('readConcept requires a concept ID', 'non-empty string');
+  }
+  const filePath = path.join(dir, `${id}.yaml`);
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return parseConceptYaml(raw, `${id}.yaml`);
+}
+
+/**
+ * List all concept IDs in a directory, optionally filtered by prefix.
+ * @param {string} dir - path to directory
+ * @param {string} [prefix] - optional prefix filter
+ * @returns {string[]}
+ * @throws {InvalidInputError} if dir is missing or empty
+ *
+ * @example
+ * const ids = listConceptIds('./geolexica-v2/', '3.1.'); // ['3.1.1.1', '3.1.1.2', ...]
+ */
+export function listConceptIds(dir, prefix) {
+  assertDir(dir, 'listConceptIds');
+  let files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml') && f !== 'register.yaml');
+  if (prefix) {
+    files = files.filter(f => f.startsWith(prefix));
+  }
+  return files
+    .map(f => f.slice(0, -'.yaml'.length))
+    .sort(naturalSort);
+}
+
+/**
+ * Read register.yaml from a dataset directory (if present).
+ * @param {string} dir - path to directory
+ * @returns {Record<string, unknown> | null}
+ * @throws {InvalidInputError} if dir is missing or empty
+ */
+export function readRegister(dir) {
+  assertDir(dir, 'readRegister');
+  const p = path.join(dir, 'register.yaml');
+  if (!fs.existsSync(p)) return null;
+  return yaml.load(fs.readFileSync(p, 'utf8'));
+}

package/src/errors.d.ts

@@ -0,0 +1,11 @@
+export class GlossaristError extends Error {
+  constructor(message: string, options?: { cause?: Error });
+}
+
+export class InvalidInputError extends GlossaristError {
+  constructor(what: string, expected?: string);
+}
+
+export class YamlParseError extends GlossaristError {
+  constructor(context: string, cause: Error);
+}

package/src/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Base error for all glossarist errors.
+ */
+export class GlossaristError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ cause?: Error }} [options]
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'GlossaristError';
+  }
+}
+
+/**
+ * Thrown when a function receives invalid input (null, undefined, wrong type).
+ */
+export class InvalidInputError extends GlossaristError {
+  /**
+   * @param {string} what - description of the invalid input
+   * @param {string} [expected] - description of what was expected
+   */
+  constructor(what, expected) {
+    const msg = expected ? `${what} (expected ${expected})` : what;
+    super(msg);
+    this.name = 'InvalidInputError';
+  }
+}
+
+/**
+ * Thrown when YAML content cannot be parsed.
+ */
+export class YamlParseError extends GlossaristError {
+  /**
+   * @param {string} context - what was being parsed (e.g. concept ID)
+   * @param {Error} cause - the original YAML parse error
+   */
+  constructor(context, cause) {
+    super(`Failed to parse YAML for ${context}: ${cause.message}`, { cause });
+    this.name = 'YamlParseError';
+  }
+}

package/src/gcr-reader.d.ts

@@ -0,0 +1,77 @@
+/** A single term designation. */
+export interface Term {
+  type: string;
+  designation: string;
+  normative_status?: string;
+}
+
+/** A definition content block. */
+export interface Definition {
+  content: string;
+}
+
+/** A bibliographic source reference. */
+export interface Source {
+  type: string;
+  origin?: { ref: string };
+}
+
+/** Localized concept data for a single language. */
+export interface Localization {
+  terms: Term[];
+  definition?: Definition[];
+  notes?: { content: string }[];
+  examples?: { content: string }[];
+  sources?: Source[];
+  entry_status?: string;
+  normative_status?: string;
+}
+
+/** A normalized glossarist concept. */
+export interface Concept {
+  termid: string;
+  term: string | null;
+  localizations: Record<string, Localization>;
+  raw: Record<string, unknown>;
+}
+
+/** GCR package metadata from metadata.yaml. */
+export interface GcrMetadata {
+  shortname: string;
+  version?: string;
+  title?: string;
+  concept_count?: number;
+  languages?: string[];
+  schema_version?: string;
+  glossarist_version?: string;
+  created_at?: string;
+  statistics?: Record<string, unknown>;
+}
+
+/**
+ * Load a GCR package from a ZIP archive.
+ * Accepts Buffer, ArrayBuffer, Uint8Array, Blob, or base64 string.
+ */
+export function loadGcr(input: Buffer | ArrayBuffer | Uint8Array | Blob | string): Promise<GcrPackage>;
+
+/** A loaded GCR package (ZIP archive of glossarist concept data). */
+export class GcrPackage {
+  /** Read and parse metadata.yaml. */
+  metadata(): Promise<GcrMetadata | null>;
+  /** Read and parse optional register.yaml. */
+  register(): Promise<Record<string, unknown> | null>;
+  /** List all concept IDs, naturally sorted. */
+  conceptIds(): Promise<string[]>;
+  /** Read and normalize a single concept by ID. */
+  concept(id: string): Promise<Concept | null>;
+  /** Iterate all concepts via callback. */
+  eachConcept(callback: (concept: Concept, index: number) => void | Promise<void>): Promise<void>;
+  /** Load all concepts into an array. */
+  allConcepts(): Promise<Concept[]>;
+}
+
+/** Parse raw concept YAML (canonical or managed format) into a normalized Concept. */
+export function parseConceptYaml(raw: string, context?: string): Concept;
+
+/** Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39". */
+export function naturalSort(a: string, b: string): number;

package/src/gcr-reader.js

@@ -0,0 +1,292 @@
+import JSZip from 'jszip';
+import yaml from 'js-yaml';
+import { InvalidInputError, YamlParseError } from './errors.js';
+
+const STRUCTURAL_KEYS = new Set(['termid', 'term']);
+
+const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+
+const NATURAL_SORT_RE = /(\d+|\D+)/g;
+const DIGIT_RE = /^\d+$/;
+
+/**
+ * @typedef {Object} Term
+ * @property {string} type - e.g. 'expression', 'symbol', 'abbreviation'
+ * @property {string} designation - the term text
+ * @property {string} [normative_status] - e.g. 'preferred', 'admitted'
+ */
+
+/**
+ * @typedef {Object} Definition
+ * @property {string} content - the definition text
+ */
+
+/**
+ * @typedef {Object} Source
+ * @property {string} type - e.g. 'authoritative', 'adapted'
+ * @property {{ ref: string }} [origin] - reference to the source standard
+ */
+
+/**
+ * @typedef {Object} Localization
+ * @property {Term[]} terms - term designations
+ * @property {Definition[]} [definition] - definition content
+ * @property {{ content: string }[]} [notes] - editorial notes
+ * @property {{ content: string }[]} [examples] - usage examples
+ * @property {Source[]} [sources] - bibliographic sources
+ * @property {string} [entry_status] - e.g. 'valid', 'draft'
+ * @property {string} [normative_status] - e.g. 'preferred', 'admitted'
+ */
+
+/**
+ * @typedef {Object} Concept
+ * @property {string} termid - concept identifier (e.g. '3.1.1.1', '551-12-39')
+ * @property {string|null} term - primary term (canonical format only)
+ * @property {Record<string, Localization>} localizations - keyed by ISO 639-3 language code
+ * @property {Record<string, unknown>} raw - original parsed YAML
+ */
+
+/**
+ * Load a GCR package from a ZIP archive.
+ *
+ * Accepts a Buffer/ArrayBuffer/Uint8Array (Node or browser), a Blob (browser),
+ * or a base64-encoded string.
+ *
+ * @param {Buffer | ArrayBuffer | Uint8Array | Blob | string} input
+ * @returns {Promise<GcrPackage>}
+ * @throws {InvalidInputError} if input is null or undefined
+ *
+ * @example
+ * import { loadGcr } from 'glossarist';
+ * import fs from 'fs';
+ * const pkg = await loadGcr(fs.readFileSync('dataset.gcr'));
+ * const meta = await pkg.metadata();
+ */
+export async function loadGcr(input) {
+  if (input == null) {
+    throw new InvalidInputError('loadGcr requires a Buffer, ArrayBuffer, Uint8Array, Blob, or base64 string', 'non-null input');
+  }
+  const opts = typeof input === 'string' && BASE64_RE.test(input) ? { base64: true } : undefined;
+  const zip = await JSZip.loadAsync(input, opts);
+  return new GcrPackage(zip);
+}
+
+/**
+ * Represents a loaded GCR package (ZIP archive of glossarist concept data).
+ */
+export class GcrPackage {
+  /** @param {JSZip} zip */
+  constructor(zip) {
+    this._zip = zip;
+  }
+
+  /**
+   * Read and parse metadata.yaml from the package.
+   * @returns {Promise<GcrMetadata | null>}
+   */
+  async metadata() {
+    const raw = await this._readText('metadata.yaml');
+    return raw ? yaml.load(raw) : null;
+  }
+
+  /**
+   * Read and parse optional register.yaml from the package.
+   * @returns {Promise<Record<string, unknown> | null>}
+   */
+  async register() {
+    const raw = await this._readText('register.yaml');
+    return raw ? yaml.load(raw) : null;
+  }
+
+  /**
+   * List all concept IDs (filenames without .yaml), naturally sorted.
+   * @returns {Promise<string[]>}
+   */
+  async conceptIds() {
+    const ids = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith('concepts/') && relativePath.endsWith('.yaml')) {
+        ids.push(relativePath.slice('concepts/'.length, -'.yaml'.length));
+      }
+    });
+    return ids.sort(naturalSort);
+  }
+
+  /**
+   * Read and normalize a single concept by ID.
+   * @param {string} id - concept identifier
+   * @returns {Promise<Concept | null>}
+   */
+  async concept(id) {
+    const raw = await this._readText(`concepts/${id}.yaml`);
+    if (raw === null) return null;
+    return parseConceptYaml(raw, id);
+  }
+
+  /**
+   * Iterate all concepts. Use for large packages to avoid loading everything at once.
+   * @param {(concept: Concept, index: number) => void | Promise<void>} callback
+   * @returns {Promise<void>}
+   */
+  async eachConcept(callback) {
+    const ids = await this.conceptIds();
+    for (let i = 0; i < ids.length; i++) {
+      const concept = await this.concept(ids[i]);
+      if (concept) await callback(concept, i);
+    }
+  }
+
+  /**
+   * Load all concepts into an array. Beware memory for large packages.
+   * @returns {Promise<Concept[]>}
+   */
+  async allConcepts() {
+    const ids = await this.conceptIds();
+    const concepts = [];
+    for (const id of ids) {
+      const c = await this.concept(id);
+      if (c) concepts.push(c);
+    }
+    return concepts;
+  }
+
+  /** @private @param {string} filePath @returns {Promise<string | null>} */
+  async _readText(filePath) {
+    const entry = this._zip.file(filePath);
+    if (!entry) return null;
+    return entry.async('text');
+  }
+}
+
+// --- Concept YAML parsing ---
+
+/**
+ * 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}
+ * @throws {InvalidInputError} if raw is null, undefined, or empty
+ * @throws {YamlParseError} if the YAML content is malformed
+ *
+ * @example
+ * const concept = parseConceptYaml('termid: "001"\neng:\n  terms:\n    - designation: test', '001');
+ * 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,
+  };
+}
+
+// --- Helpers ---
+
+/**
+ * Natural sort comparator for concept IDs like "3.1.1.1", "551-12-39".
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ *
+ * @example
+ * ['3.1.10', '3.1.2', '3.1.1'].sort(naturalSort); // ['3.1.1', '3.1.2', '3.1.10']
+ */
+export function naturalSort(a, b) {
+  const pa = a.match(NATURAL_SORT_RE) || [];
+  const pb = b.match(NATURAL_SORT_RE) || [];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || '';
+    const nb = pb[i] || '';
+    if (DIGIT_RE.test(na) && DIGIT_RE.test(nb)) {
+      const diff = parseInt(na, 10) - parseInt(nb, 10);
+      if (diff !== 0) return diff;
+    } else {
+      const cmp = na.localeCompare(nb);
+      if (cmp !== 0) return cmp;
+    }
+  }
+  return 0;
+}
+
+/**
+ * @typedef {Object} GcrMetadata
+ * @property {string} shortname - dataset short name
+ * @property {string} [version] - dataset version
+ * @property {string} [title] - dataset title
+ * @property {number} [concept_count] - number of concepts
+ * @property {string[]} [languages] - supported language codes
+ * @property {string} [schema_version] - schema version
+ * @property {string} [glossarist_version] - glossarist tool version
+ * @property {string} [created_at] - ISO 8601 creation timestamp
+ * @property {Record<string, unknown>} [statistics] - dataset statistics
+ */

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
+export type { Concept, Localization, Term, Definition, Source, GcrMetadata } from './gcr-reader';
+export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader';
+export { GlossaristError, InvalidInputError, YamlParseError } from './errors';

package/src/index.js

@@ -0,0 +1,3 @@
+export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader.js';
+export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader.js';
+export { GlossaristError, InvalidInputError, YamlParseError } from './errors.js';