glossarist 0.1.4 → 0.1.6

package/README.md

@@ -58,6 +58,66 @@ const buf = await createGcr([concept], { shortname: 'test' });
 fs.writeFileSync('out.gcr', buf);
 ```
 
+### Compiled / machine formats in GCR
+
+GCR packages can contain pre-compiled machine formats (TBX, JSON-LD, Turtle, JSONL) inside a `compiled/` directory. This mirrors the Ruby glossarist gem's `COMPILED_EXTENSIONS` convention.
+
+```js
+import { loadGcr } from 'glossarist';
+
+const pkg = await loadGcr(fs.readFileSync('dataset.gcr'));
+
+// Discover which compiled formats are present
+const formats = await pkg.compiledFormats();       // ['tbx', 'jsonld', 'turtle']
+
+// List entry IDs for a specific format
+const ids = await pkg.compiledFormatIds('jsonld'); // ['3.1.1.1', '3.1.1.2']
+
+// Read a single compiled file as string
+const jsonld = await pkg.compiledFile('jsonld', '3.1.1.1');
+
+// Read a single compiled file as binary
+const buf = await pkg.compiledFileBuffer('jsonld', '3.1.1.1');
+
+// Iterate all entries for a format
+await pkg.eachCompiledFile('turtle', (id, content) => {
+  console.log(id, content.length);
+});
+
+// Load all entries for a format into a Map
+const allTurtle = await pkg.allCompiledFiles('turtle');
+
+// Check if a format is present
+await pkg.hasCompiledFormat('tbx'); // true
+```
+
+#### Write compiled formats into a GCR package
+
+```js
+import { GcrWriter } from 'glossarist';
+
+const buf = await GcrWriter.createBuffer({
+  concepts: [...],
+  metadata: { shortname: 'my-dataset' },
+  compiledFormats: {
+    tbx:    { 'my-dataset': tbxXmlString },
+    jsonld: { '3.1.1.1': jsonldString, '3.1.1.2': jsonldString },
+    turtle: { '3.1.1.1': ttlString },
+  },
+});
+```
+
+#### Format registry
+
+```js
+import { COMPILED_FORMATS, COMPILED_EXTENSIONS, isKnownFormat } from 'glossarist';
+
+COMPILED_FORMATS;                           // ['tbx', 'jsonld', 'turtle', 'jsonl']
+COMPILED_EXTENSIONS.get('tbx');             // 'tbx.xml'
+COMPILED_EXTENSIONS.get('turtle');           // 'ttl'
+isKnownFormat('csv');                        // false
+```
+
 ### Domain model
 
 Every domain entity is a class instance with `toJSON()`, `fromJSON()`, `equals()`, and `clone()`:
@@ -208,6 +268,7 @@ Public API (index.js)
 ├── Parsing           → ConceptParser (canonical + managed format detection)
 ├── Serialization     → ConceptSerializer (canonical + managed YAML output)
 ├── I/O               → loadGcr, readConcepts, createGcr, writeConcepts
+├── Compiled formats  → CompiledFormatRegistry (TBX, JSON-LD, Turtle, JSONL in GCR)
 ├── Collections       → ConceptCollection (Proxy-based, queryable), ManagedConceptCollection
 ├── Validation        → ConceptValidator, RegisterValidator, ValidationRule (pluggable)
 ├── Utilities         → conceptUuid, referenceResolver, V1Reader

package/package.json

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

package/src/compiled-format.js

@@ -0,0 +1,89 @@
+/**
+ * Registry of compiled/machine formats that can be bundled inside a GCR package.
+ *
+ * Mirrors the Ruby glossarist gem's GcrPackage::COMPILED_EXTENSIONS:
+ *   tbx    → TBX-Basic XML (ISO 30042)
+ *   jsonld → JSON-LD (SKOS vocabulary)
+ *   turtle → Turtle/RDF (SKOS vocabulary)
+ *   jsonl  → JSON Lines (one concept per line)
+ */
+
+/**
+ * Maps format name to the file extension used inside the GCR `compiled/` directory.
+ * Keys are the canonical format identifiers; values are the extension including
+ * the leading dot (for simple lookup) or the multi-part extension for TBX.
+ * @type {ReadonlyMap<string, string>}
+ */
+const COMPILED_EXTENSIONS = Object.freeze(new Map([
+  ['tbx', 'tbx.xml'],
+  ['jsonld', 'jsonld'],
+  ['turtle', 'ttl'],
+  ['jsonl', 'jsonl'],
+]));
+
+/** Canonical format identifiers, in a stable order. */
+const COMPILED_FORMATS = Object.freeze([...COMPILED_EXTENSIONS.keys()]);
+
+/**
+ * Returns the filename (without directory) for a compiled-format entry.
+ *
+ * @param {string} format - e.g. 'tbx', 'jsonld'
+ * @param {string} id - concept ID or document name (e.g. '3.1.1.1', 'glossary')
+ * @returns {string} e.g. '3.1.1.1.jsonld', 'glossary.tbx.xml'
+ */
+function compiledFilename(format, id) {
+  const ext = COMPILED_EXTENSIONS.get(format);
+  if (!ext) throw new RangeError(`Unknown compiled format: ${format}`);
+  return `${id}.${ext}`;
+}
+
+/**
+ * Returns the full ZIP path for a compiled-format entry.
+ *
+ * @param {string} format
+ * @param {string} id
+ * @returns {string} e.g. 'compiled/jsonld/3.1.1.1.jsonld'
+ */
+function compiledPath(format, id) {
+  return `compiled/${format}/${compiledFilename(format, id)}`;
+}
+
+/**
+ * Checks whether a format name is a known compiled format.
+ * @param {string} format
+ * @returns {boolean}
+ */
+function isKnownFormat(format) {
+  return COMPILED_EXTENSIONS.has(format);
+}
+
+/**
+ * Extracts the entry ID (concept ID or document name) from a compiled-format ZIP path.
+ * Returns null if the path doesn't match the expected pattern.
+ *
+ * @param {string} zipPath - e.g. 'compiled/jsonld/3.1.1.1.jsonld'
+ * @returns {{ format: string, id: string } | null}
+ */
+function parseCompiledPath(zipPath) {
+  if (!zipPath.startsWith('compiled/')) return null;
+  const rest = zipPath.slice('compiled/'.length);
+  const slash = rest.indexOf('/');
+  if (slash === -1) return null;
+  const format = rest.slice(0, slash);
+  const ext = COMPILED_EXTENSIONS.get(format);
+  if (!ext) return null;
+  const filename = rest.slice(slash + 1);
+  const suffix = `.${ext}`;
+  if (!filename.endsWith(suffix)) return null;
+  const id = filename.slice(0, -suffix.length);
+  return { format, id };
+}
+
+export {
+  COMPILED_EXTENSIONS,
+  COMPILED_FORMATS,
+  compiledFilename,
+  compiledPath,
+  isKnownFormat,
+  parseCompiledPath,
+};

package/src/gcr-reader.d.ts

@@ -68,6 +68,23 @@ export class GcrPackage {
   eachConcept(callback: (concept: Concept, index: number) => void | Promise<void>): Promise<void>;
   /** Load all concepts into an array. */
   allConcepts(): Promise<Concept[]>;
+
+  // Compiled / machine formats (TBX, JSON-LD, Turtle, JSONL)
+
+  /** List compiled format directories present in this package. */
+  compiledFormats(): Promise<string[]>;
+  /** List entry IDs for a given compiled format. */
+  compiledFormatIds(format: string): Promise<string[]>;
+  /** Check whether a compiled format is present. */
+  hasCompiledFormat(format: string): Promise<boolean>;
+  /** Read a single compiled-format file as a string. */
+  compiledFile(format: string, id: string): Promise<string | null>;
+  /** Read a single compiled-format file as a Uint8Array. */
+  compiledFileBuffer(format: string, id: string): Promise<Uint8Array | null>;
+  /** Iterate all entries for a compiled format. */
+  eachCompiledFile(format: string, callback: (id: string, content: string) => void | Promise<void>): Promise<void>;
+  /** Load all entries for a compiled format into a Map. */
+  allCompiledFiles(format: string): Promise<Map<string, string>>;
 }
 
 /** Parse raw concept YAML (canonical or managed format) into a normalized Concept. */

package/src/gcr-reader.js

@@ -2,6 +2,7 @@ import JSZip from 'jszip';
 import yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
 import { InvalidInputError } from './errors.js';
+import { COMPILED_EXTENSIONS, parseCompiledPath, compiledPath } from './compiled-format.js';
 
 const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 
@@ -149,6 +150,106 @@ export class GcrPackage {
     return concepts;
   }
 
+  // --- Compiled / machine formats (TBX, JSON-LD, Turtle, JSONL) ---
+
+  /**
+   * List compiled format directories present in this package.
+   * Only returns formats whose `compiled/{format}/` directory contains at least one file.
+   * @returns {Promise<string[]>}
+   */
+  async compiledFormats() {
+    const seen = new Set();
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir) {
+        const parsed = parseCompiledPath(relativePath);
+        if (parsed) seen.add(parsed.format);
+      }
+    });
+    return COMPILED_EXTENSIONS.keys
+      ? [...COMPILED_EXTENSIONS.keys()].filter((f) => seen.has(f))
+      : [...seen];
+  }
+
+  /**
+   * List entry IDs for a given compiled format.
+   * @param {string} format - e.g. 'tbx', 'jsonld', 'turtle', 'jsonl'
+   * @returns {Promise<string[]>}
+   */
+  async compiledFormatIds(format) {
+    const prefix = `compiled/${format}/`;
+    const ids = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith(prefix)) {
+        const parsed = parseCompiledPath(relativePath);
+        if (parsed && parsed.format === format) ids.push(parsed.id);
+      }
+    });
+    return ids.sort(naturalSort);
+  }
+
+  /**
+   * Check whether a compiled format is present.
+   * @param {string} format
+   * @returns {Promise<boolean>}
+   */
+  async hasCompiledFormat(format) {
+    const prefix = `compiled/${format}/`;
+    let found = false;
+    this._zip.forEach((relativePath, entry) => {
+      if (!found && !entry.dir && relativePath.startsWith(prefix)) {
+        found = true;
+      }
+    });
+    return found;
+  }
+
+  /**
+   * Read a single compiled-format file as a string.
+   * @param {string} format - e.g. 'jsonld'
+   * @param {string} id - concept ID or document name (e.g. '3.1.1.1', 'glossary')
+   * @returns {Promise<string | null>} null if the file doesn't exist
+   */
+  async compiledFile(format, id) {
+    return this._readText(compiledPath(format, id));
+  }
+
+  /**
+   * Read a single compiled-format file as a Uint8Array (for binary content).
+   * @param {string} format
+   * @param {string} id
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async compiledFileBuffer(format, id) {
+    const entry = this._zip.file(compiledPath(format, id));
+    if (!entry) return null;
+    return entry.async('uint8array');
+  }
+
+  /**
+   * Iterate all entries for a compiled format.
+   * @param {string} format
+   * @param {(id: string, content: string) => void | Promise<void>} callback
+   * @returns {Promise<void>}
+   */
+  async eachCompiledFile(format, callback) {
+    const ids = await this.compiledFormatIds(format);
+    for (const id of ids) {
+      const content = await this.compiledFile(format, id);
+      if (content !== null) await callback(id, content);
+    }
+  }
+
+  /**
+   * Load all entries for a compiled format into a Map (id → content).
+   * @param {string} format
+   * @returns {Promise<Map<string, string>>}
+   */
+  async allCompiledFiles(format) {
+    const map = new Map();
+    await this.eachCompiledFile(format, (id, content) => { map.set(id, content); });
+    return map;
+  }
+
   /** @private @param {string} filePath @returns {Promise<string | null>} */
   async _readText(filePath) {
     const entry = this._zip.file(filePath);

package/src/gcr-writer.d.ts

@@ -1,5 +1,8 @@
 import { Concept } from './models/index';
 
+/** Compiled formats map: format name → id → content string. */
+export type CompiledFormatsMap = Record<string, Record<string, string> | Map<string, string>>;
+
 export class GcrWriter {
   static createBuffer(options: {
     concepts: Concept[];
@@ -7,6 +10,7 @@ export class GcrWriter {
     register?: Record<string, unknown>;
     uuidFn?: () => string;
     format?: 'canonical' | 'managed' | 'auto';
+    compiledFormats?: CompiledFormatsMap;
   }): Promise<Uint8Array>;
 }
 

package/src/gcr-writer.js

@@ -1,6 +1,7 @@
 import JSZip from 'jszip';
 import { conceptSerializer } from './concept-serializer.js';
 import { InvalidInputError } from './errors.js';
+import { compiledPath, isKnownFormat } from './compiled-format.js';
 
 export class GcrWriter {
   static async createBuffer(options) {
@@ -29,8 +30,24 @@ export class GcrWriter {
       zip.file(`concepts/${concept.id}.yaml`, y);
     }
 
+    if (options.compiledFormats) {
+      GcrWriter._writeCompiledFormats(zip, options.compiledFormats);
+    }
+
     return zip.generateAsync({ type: 'uint8array' });
   }
+
+  static _writeCompiledFormats(zip, compiledFormats) {
+    for (const [format, entries] of Object.entries(compiledFormats)) {
+      if (!isKnownFormat(format)) {
+        throw new RangeError(`Unknown compiled format: ${format}`);
+      }
+      const map = entries instanceof Map ? entries : new Map(Object.entries(entries));
+      for (const [id, content] of map) {
+        zip.file(compiledPath(format, id), content);
+      }
+    }
+  }
 }
 
 export async function createGcr(concepts, metadata) {

package/src/index.d.ts

@@ -39,3 +39,11 @@ export { V1Reader, migrateV1ToV2 } from './v1-reader';
 
 // Errors
 export { GlossaristError, InvalidInputError, YamlParseError } from './errors';
+
+// Compiled format registry
+export const COMPILED_EXTENSIONS: ReadonlyMap<string, string>;
+export const COMPILED_FORMATS: readonly string[];
+export function isKnownFormat(format: string): boolean;
+export function compiledFilename(format: string, id: string): string;
+export function compiledPath(format: string, id: string): string;
+export function parseCompiledPath(zipPath: string): { format: string; id: string } | null;

package/src/index.js

@@ -10,6 +10,15 @@ export { ReferenceResolver, Reference, referenceResolver } from './reference-res
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
 export { GlossaristError, InvalidInputError, YamlParseError } from './errors.js';
 
+export {
+  COMPILED_EXTENSIONS,
+  COMPILED_FORMATS,
+  isKnownFormat,
+  compiledFilename,
+  compiledPath,
+  parseCompiledPath,
+} from './compiled-format.js';
+
 export {
   GlossaristModel,
   Concept, LocalizedConcept,

package/src/models/citation.js

@@ -21,6 +21,10 @@ export class Citation extends GlossaristModel {
     }
   }
 
+  get isStructured() {
+    return typeof this.source === 'object' && this.source !== null;
+  }
+
   toString() {
     if (this.ref) return this.ref;
     if (typeof this.source === 'string') return this.source;

package/src/models/index.d.ts

@@ -70,6 +70,7 @@ export class Citation extends GlossaristModel {
   readonly version: string | null;
   readonly clause: string | null;
   readonly link: string | null;
+  readonly isStructured: boolean;
   toString(): string;
 }