glossarist 0.1.6 → 0.1.7

package/README.md

@@ -118,6 +118,51 @@ COMPILED_EXTENSIONS.get('turtle');           // 'ttl'
 isKnownFormat('csv');                        // false
 ```
 
+### Bibliography and images in GCR
+
+GCR packages can contain a `bibliography.yaml` file and an `images/` directory, making the archive fully self-contained. This mirrors the Ruby glossarist gem's `DATASET_ASSETS` convention.
+
+```js
+import { loadGcr } from 'glossarist';
+
+const pkg = await loadGcr(fs.readFileSync('dataset.gcr'));
+
+// Bibliography (raw YAML string)
+const bib = await pkg.bibliography();         // 'ISO_19111_2019:\n  ...' or null
+
+// Images
+await pkg.hasImages();                        // true
+const names = await pkg.imageFileNames();     // ['images/fig1.png', ...]
+const img = await pkg.imageFile('fig1.png');  // Uint8Array or null
+const allImages = await pkg.allImageFiles();  // Map<string, Uint8Array>
+```
+
+#### Write bibliography and images into a GCR package
+
+```js
+import { GcrWriter } from 'glossarist';
+
+const buf = await GcrWriter.createBuffer({
+  concepts: [...],
+  metadata: { shortname: 'my-dataset' },
+  bibliography: 'ISO_19111_2019:\n  title: Geographic information',
+  images: {
+    'figure1.png': pngBuffer,
+    'diagrams/schema.svg': svgString,
+  },
+});
+```
+
+#### Dataset asset registry
+
+```js
+import { DATASET_ASSETS, FILE_ASSETS, DIRECTORY_ASSETS } from 'glossarist';
+
+DATASET_ASSETS;   // [{ path: 'bibliography.yaml', type: 'file' }, { path: 'images', type: 'directory' }]
+FILE_ASSETS;      // [{ path: 'bibliography.yaml', type: 'file' }]
+DIRECTORY_ASSETS; // [{ path: 'images', type: 'directory' }]
+```
+
 ### Domain model
 
 Every domain entity is a class instance with `toJSON()`, `fromJSON()`, `equals()`, and `clone()`:
@@ -269,6 +314,7 @@ Public API (index.js)
 ├── Serialization     → ConceptSerializer (canonical + managed YAML output)
 ├── I/O               → loadGcr, readConcepts, createGcr, writeConcepts
 ├── Compiled formats  → CompiledFormatRegistry (TBX, JSON-LD, Turtle, JSONL in GCR)
+├── Dataset assets    → DATASET_ASSETS registry (bibliography.yaml, images/ 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.6",
+  "version": "0.1.7",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/dataset-asset.js

@@ -0,0 +1,65 @@
+/**
+ * Registry of dataset assets that can be bundled inside a GCR package.
+ *
+ * Mirrors the Ruby glossarist gem's GcrPackage::DATASET_ASSETS.
+ * Asset types:
+ *   - file: a single named file at the GCR root (e.g. bibliography.yaml)
+ *   - directory: a named directory with arbitrary nested files (e.g. images/)
+ *
+ * New asset types can be added by appending to DATASET_ASSETS (open/closed).
+ */
+
+const DATASET_ASSETS = Object.freeze([
+  { path: 'bibliography.yaml', type: 'file' },
+  { path: 'images', type: 'directory' },
+]);
+
+const FILE_ASSETS = Object.freeze(
+  DATASET_ASSETS.filter((a) => a.type === 'file'),
+);
+
+const DIRECTORY_ASSETS = Object.freeze(
+  DATASET_ASSETS.filter((a) => a.type === 'directory'),
+);
+
+/**
+ * Find a file asset descriptor by its ZIP path.
+ * @param {string} path
+ * @returns {{ path: string, type: string } | undefined}
+ */
+function findFileAsset(path) {
+  return FILE_ASSETS.find((a) => a.path === path);
+}
+
+/**
+ * Check whether a ZIP path belongs to a directory asset.
+ * Returns the asset descriptor if so, undefined otherwise.
+ * @param {string} zipPath
+ * @returns {{ path: string, type: string } | undefined}
+ */
+function findDirectoryAssetPath(zipPath) {
+  for (const asset of DIRECTORY_ASSETS) {
+    if (zipPath === asset.path || zipPath.startsWith(`${asset.path}/`)) {
+      return asset;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Check if a ZIP path is a dataset asset entry.
+ * @param {string} zipPath
+ * @returns {boolean}
+ */
+function isDatasetAssetPath(zipPath) {
+  return findFileAsset(zipPath) !== undefined || findDirectoryAssetPath(zipPath) !== undefined;
+}
+
+export {
+  DATASET_ASSETS,
+  FILE_ASSETS,
+  DIRECTORY_ASSETS,
+  findFileAsset,
+  findDirectoryAssetPath,
+  isDatasetAssetPath,
+};

package/src/gcr-reader.d.ts

@@ -85,6 +85,21 @@ export class GcrPackage {
   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>>;
+
+  // Dataset assets (bibliography, images)
+
+  /** Read bibliography.yaml from the package as raw YAML string. */
+  bibliography(): Promise<string | null>;
+  /** Check whether the images/ directory is present and non-empty. */
+  hasImages(): Promise<boolean>;
+  /** List all image file paths (relative to ZIP root). */
+  imageFileNames(): Promise<string[]>;
+  /** Read a single image file as Uint8Array. */
+  imageFile(path: string): Promise<Uint8Array | null>;
+  /** Iterate all image files. */
+  eachImageFile(callback: (path: string, content: Uint8Array) => void | Promise<void>): Promise<void>;
+  /** Load all image files into a Map (path → Uint8Array). */
+  allImageFiles(): Promise<Map<string, Uint8Array>>;
 }
 
 /** Parse raw concept YAML (canonical or managed format) into a normalized Concept. */

package/src/gcr-reader.js

@@ -2,7 +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';
+import { COMPILED_FORMATS, parseCompiledPath, compiledPath } from './compiled-format.js';
 
 const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 
@@ -154,7 +154,6 @@ export class GcrPackage {
 
   /**
    * 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() {
@@ -165,9 +164,7 @@ export class GcrPackage {
         if (parsed) seen.add(parsed.format);
       }
     });
-    return COMPILED_EXTENSIONS.keys
-      ? [...COMPILED_EXTENSIONS.keys()].filter((f) => seen.has(f))
-      : [...seen];
+    return COMPILED_FORMATS.filter((f) => seen.has(f));
   }
 
   /**
@@ -250,6 +247,82 @@ export class GcrPackage {
     return map;
   }
 
+  // --- Dataset assets (bibliography, images, etc.) ---
+
+  /**
+   * Read bibliography.yaml from the package as a string (raw YAML).
+   * @returns {Promise<string | null>}
+   */
+  async bibliography() {
+    return this._readText('bibliography.yaml');
+  }
+
+  /**
+   * Check whether the images/ directory is present and non-empty.
+   * @returns {Promise<boolean>}
+   */
+  async hasImages() {
+    let found = false;
+    this._zip.forEach((relativePath, entry) => {
+      if (!found && !entry.dir && relativePath.startsWith('images/')) {
+        found = true;
+      }
+    });
+    return found;
+  }
+
+  /**
+   * List all image file paths (relative to ZIP root).
+   * @returns {Promise<string[]>}
+   */
+  async imageFileNames() {
+    const names = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith('images/')) {
+        names.push(relativePath);
+      }
+    });
+    return names.sort();
+  }
+
+  /**
+   * Read a single image file as a Uint8Array.
+   * @param {string} path - relative path starting with 'images/' or just the filename
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async imageFile(path) {
+    const fullPath = path.startsWith('images/') ? path : `images/${path}`;
+    const entry = this._zip.file(fullPath);
+    if (!entry) return null;
+    return entry.async('uint8array');
+  }
+
+  /**
+   * Iterate all image files.
+   * @param {(path: string, content: Uint8Array) => void | Promise<void>} callback
+   * @returns {Promise<void>}
+   */
+  async eachImageFile(callback) {
+    const names = await this.imageFileNames();
+    for (const name of names) {
+      const entry = this._zip.file(name);
+      if (entry) {
+        const content = await entry.async('uint8array');
+        await callback(name, content);
+      }
+    }
+  }
+
+  /**
+   * Load all image files into a Map (path → Uint8Array).
+   * @returns {Promise<Map<string, Uint8Array>>}
+   */
+  async allImageFiles() {
+    const map = new Map();
+    await this.eachImageFile((path, content) => { map.set(path, 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

@@ -3,6 +3,9 @@ import { Concept } from './models/index';
 /** Compiled formats map: format name → id → content string. */
 export type CompiledFormatsMap = Record<string, Record<string, string> | Map<string, string>>;
 
+/** Images map: relative path → binary content. */
+export type ImagesMap = Record<string, Uint8Array | string | ArrayBuffer> | Map<string, Uint8Array | string | ArrayBuffer>;
+
 export class GcrWriter {
   static createBuffer(options: {
     concepts: Concept[];
@@ -11,6 +14,8 @@ export class GcrWriter {
     uuidFn?: () => string;
     format?: 'canonical' | 'managed' | 'auto';
     compiledFormats?: CompiledFormatsMap;
+    bibliography?: string;
+    images?: ImagesMap;
   }): Promise<Uint8Array>;
 }
 

package/src/gcr-writer.js

@@ -34,6 +34,14 @@ export class GcrWriter {
       GcrWriter._writeCompiledFormats(zip, options.compiledFormats);
     }
 
+    if (options.bibliography) {
+      zip.file('bibliography.yaml', options.bibliography);
+    }
+
+    if (options.images) {
+      GcrWriter._writeImages(zip, options.images);
+    }
+
     return zip.generateAsync({ type: 'uint8array' });
   }
 
@@ -48,6 +56,14 @@ export class GcrWriter {
       }
     }
   }
+
+  static _writeImages(zip, images) {
+    const map = images instanceof Map ? images : new Map(Object.entries(images));
+    for (const [path, content] of map) {
+      const fullPath = path.startsWith('images/') ? path : `images/${path}`;
+      zip.file(fullPath, content);
+    }
+  }
 }
 
 export async function createGcr(concepts, metadata) {

package/src/index.d.ts

@@ -47,3 +47,8 @@ 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;
+
+// Dataset asset registry
+export const DATASET_ASSETS: readonly { path: string; type: string }[];
+export const FILE_ASSETS: readonly { path: string; type: string }[];
+export const DIRECTORY_ASSETS: readonly { path: string; type: string }[];

package/src/index.js

@@ -19,6 +19,12 @@ export {
   parseCompiledPath,
 } from './compiled-format.js';
 
+export {
+  DATASET_ASSETS,
+  FILE_ASSETS,
+  DIRECTORY_ASSETS,
+} from './dataset-asset.js';
+
 export {
   GlossaristModel,
   Concept, LocalizedConcept,

package/src/managed-concept-collection.js

@@ -2,16 +2,20 @@ 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';
+import { GcrWriter } from './gcr-writer.js';
 
 export class ManagedConceptCollection {
   constructor() {
     this._concepts = new ConceptCollection();
     this._register = null;
+    this._bibliography = null;
+    this._images = null;
   }
 
   get concepts() { return this._concepts; }
   get register() { return this._register; }
+  get bibliography() { return this._bibliography; }
+  get images() { return this._images; }
 
   loadFromDirectory(dir) {
     this._concepts = new ConceptCollection(readConcepts(dir));
@@ -23,6 +27,8 @@ export class ManagedConceptCollection {
     const pkg = await loadGcr(input);
     this._concepts = new ConceptCollection(await pkg.allConcepts());
     this._register = await pkg.register();
+    this._bibliography = await pkg.bibliography();
+    this._images = await pkg.allImageFiles();
     return this;
   }
 
@@ -34,7 +40,15 @@ export class ManagedConceptCollection {
   }
 
   async saveToGcr(options = {}) {
-    return createGcr(this._concepts, options.metadata);
+    return GcrWriter.createBuffer({
+      concepts: this._concepts,
+      metadata: options.metadata,
+      register: this._register,
+      format: options.format,
+      compiledFormats: options.compiledFormats,
+      bibliography: this._bibliography,
+      images: this._images,
+    });
   }
 
   add(concept) {
@@ -58,4 +72,14 @@ export class ManagedConceptCollection {
     this._register = data;
     return this;
   }
+
+  setBibliography(yamlString) {
+    this._bibliography = yamlString;
+    return this;
+  }
+
+  setImages(images) {
+    this._images = images instanceof Map ? images : new Map(Object.entries(images));
+    return this;
+  }
 }