glossarist 0.4.10 → 0.4.12

package/package.json

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

package/src/rdf/agents-emitter.js

@@ -33,8 +33,8 @@ const RDFS = {
   seeAlso: `${RDFS_NS}seeAlso`,
 };
 
-const DEFAULT_AGENT_BASE = 'https://glossarist.org/agent';
-const DEFAULT_ORG_BASE = 'https://glossarist.org/org';
+// No hardcoded default agent/org base URIs. Callers MUST pass agentBase
+// explicitly so agent IRIs reflect the consumer's domain.
 
 /**
  * @typedef {Object} Contributor
@@ -64,7 +64,8 @@ export function slugify(input) {
  * Builds AgentInput records from raw contributor declarations.
  * Useful for callers that want to inspect the IRIs before emission.
  */
-export function agentsFromContributors(contributors, agentBase = DEFAULT_AGENT_BASE) {
+export function agentsFromContributors(contributors, agentBase) {
+  if (!agentBase) throw new Error('agentsFromContributors requires agentBase — the deployment canonical URI root for agents (e.g. https://www.example.org/agent). glossarist-js does NOT default to glossarist.org.');
   return (contributors ?? []).map(c => {
     const slug = slugify(c.name);
     return {
@@ -92,7 +93,8 @@ export function agentsFromContributors(contributors, agentBase = DEFAULT_AGENT_B
  * @returns {Generator<Quad, void, unknown>}
  */
 export function* agentsToQuads(agents, options = {}) {
-  const orgBase = options.orgBase ?? DEFAULT_ORG_BASE;
+  const orgBase = options.orgBase;
+  if (!orgBase) throw new Error('agentsToQuads requires options.orgBase — the deployment canonical URI root for organizations.');
   const emittedOrgs = new Set();
 
   for (const a of agents ?? []) {

package/src/rdf/bibliography-emitter.js

@@ -28,7 +28,8 @@ const FOAF = {
   page: `${FOAF_NS}page`,
 };
 
-const DEFAULT_BASE_URI = 'https://glossarist.org';
+// No hardcoded default base URI. Callers MUST pass baseUri explicitly
+// so instance IRIs reflect the consumer's domain, not the library's.
 
 /**
  * @typedef {Object} BibliographyEntry
@@ -52,7 +53,8 @@ const DEFAULT_BASE_URI = 'https://glossarist.org';
  * @param {string} entryId
  * @param {string} [baseUri]
  */
-export function bibliographyEntryIri(registerId, entryId, baseUri = DEFAULT_BASE_URI) {
+export function bibliographyEntryIri(registerId, entryId, baseUri) {
+  if (!baseUri) throw new Error('bibliographyEntryIri requires baseUri — the deployment canonical URI root. glossarist-js does NOT default to glossarist.org because instance data identity must reflect the consumer domain.');
   return `${baseUri}/${registerId}/bib/${entryId}`;
 }
 
@@ -64,7 +66,8 @@ export function bibliographyEntryIri(registerId, entryId, baseUri = DEFAULT_BASE
  * @returns {Generator<Quad, void, unknown>}
  */
 export function* bibliographyToQuads(input) {
-  const baseUri = input.baseUri ?? DEFAULT_BASE_URI;
+  const baseUri = input.baseUri;
+  if (!baseUri) throw new Error('bibliographyToQuads requires input.baseUri — the deployment canonical URI root.');
   const parentIri = `${baseUri}/${input.registerId}/`;
 
   for (const entry of input.entries ?? []) {

package/src/rdf/build-activity-emitter.js

@@ -76,7 +76,8 @@ export function buildActivityIri(input) {
  * @returns {Generator<Quad, void, unknown>}
  */
 export function* buildActivityToQuads(input) {
-  const baseUri = input.baseUri ?? 'https://glossarist.org';
+  const baseUri = input.baseUri;
+  if (!baseUri) throw new Error('buildActivityToQuads requires input.baseUri — the deployment canonical URI root. glossarist-js does NOT default to glossarist.org because instance data identity must reflect the consumer domain.');
   const activityIri = `${baseUri}/${buildActivityIri(input)}`;
   const activity = namedNode(activityIri);
 

package/src/rdf/image-variant-emitter.js

@@ -28,7 +28,7 @@ const DCAT = {
 };
 const XSD_INTEGER = `${XSD_NS}integer`;
 
-const DEFAULT_BASE_URI = 'https://glossarist.org';
+// No hardcoded default base URI. Callers MUST pass baseUri explicitly.
 
 /**
  * @typedef {'svg' | 'png' | 'webp' | 'jpg' | 'gif'} ImageFormat
@@ -55,7 +55,8 @@ const MIME_BY_FORMAT = Object.freeze({
  * Returns the canonical IRI for an image variant. Includes the lang
  * segment when the variant is localized, otherwise omits it.
  */
-export function imageVariantIri(input, baseUri = DEFAULT_BASE_URI) {
+export function imageVariantIri(input, baseUri) {
+  if (!baseUri) throw new Error('imageVariantIri requires baseUri — the deployment canonical URI root.');
   const langSuffix = input.lang ? `${input.lang}.` : '';
   return `${baseUri}/${input.registerId}/image/${input.figureId}/${langSuffix}${input.format}`;
 }
@@ -63,7 +64,8 @@ export function imageVariantIri(input, baseUri = DEFAULT_BASE_URI) {
 /**
  * Emits foaf:Image quads for one image variant.
  */
-export function* imageVariantToQuads(input, baseUri = DEFAULT_BASE_URI) {
+export function* imageVariantToQuads(input, baseUri) {
+  if (!baseUri) throw new Error('imageVariantToQuads requires baseUri — the deployment canonical URI root.');
   const img = namedNode(imageVariantIri(input, baseUri));
   yield quad(img, namedNode(RDF_TYPE), namedNode(FOAF.Image));
   yield quad(img, namedNode(DCTERMS.format), literal(MIME_BY_FORMAT[input.format] ?? 'application/octet-stream'));

package/src/rdf/index.d.ts

@@ -256,6 +256,7 @@ export interface WriteTurtleOptions {
 }
 
 export declare function writeTurtle(quads: Iterable<Quad>, options?: WriteTurtleOptions): Promise<string>;
+export declare function writeTurtleSync(quads: Iterable<Quad>, options?: WriteTurtleOptions): string;
 export declare function writeNTriples(quads: Iterable<Quad>): Promise<string>;
 
 export interface WriteJsonldOptions {

package/src/rdf/index.js

@@ -41,4 +41,5 @@ export {
   writeJsonld,
   sortQuads,
 } from './document-writer.js';
+export { writeTurtleSync } from './write-turtle-sync.js';
 export { validateShacl, loadShapes, clearShapesCache, quadsToDataset } from './shacl.js';

package/src/rdf/write-turtle-sync.js

@@ -0,0 +1,166 @@
+// Sync Turtle writer — produces Turtle from RDF/JS Quads without
+// n3's callback API. Designed for UI use cases (Vue computed, React
+// render) that need synchronous output.
+//
+// Format matches n3's Turtle output closely but may differ in:
+// - Indent width (2 spaces vs n3's 4)
+// - Blank node label format (_:bXXXX)
+// - Subject ordering (sorted by value for determinism)
+//
+// For byte-equivalent n3 output, use the async writeTurtle() instead.
+
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+/**
+ * Serializes RDF/JS Quads to a Turtle string synchronously.
+ *
+ * @param {Iterable<Quad>} quads
+ * @param {{ prefixes?: Record<string, string> }} [options]
+ * @returns {string}
+ */
+export function writeTurtleSync(quads, options = {}) {
+  const prefixes = options.prefixes ?? {};
+  const sorted = [...quads].sort(compareQuadSync);
+  const grouped = groupBySubject(sorted);
+
+  const lines = [];
+
+  // Prefix declarations — sorted by prefix name for deterministic output.
+  for (const [prefix, iri] of Object.entries(prefixes).sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`@prefix ${prefix}: <${iri}> .`);
+  }
+
+  for (const { subject, triples } of grouped) {
+    lines.push('');
+    lines.push(...writeResource(subject, triples, prefixes));
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function writeResource(subject, triples, prefixes) {
+  const subjectStr = formatTermSync(subject, prefixes);
+  const types = triples.filter(t => t.predicate.value === RDF_TYPE);
+  const others = triples.filter(t => t.predicate.value !== RDF_TYPE);
+
+  if (types.length === 0 && others.length === 0) {
+    return [`${subjectStr} .`];
+  }
+
+  const lines = [];
+  const allPredObjs = [];
+
+  if (types.length > 0) {
+    const typeStrs = types.map(t => formatTermSync(t.object, prefixes));
+    allPredObjs.push({ predStr: 'a', objStrs: typeStrs });
+  }
+
+  // Group by predicate for multi-value compaction (predicate only appears once
+  // with comma-separated objects).
+  const byPredicate = new Map();
+  for (const t of others) {
+    const predStr = formatTermSync(t.predicate, prefixes);
+    if (!byPredicate.has(predStr)) byPredicate.set(predStr, []);
+    byPredicate.get(predStr).push(formatTermSync(t.object, prefixes));
+  }
+  for (const [predStr, objStrs] of byPredicate) {
+    allPredObjs.push({ predStr, objStrs });
+  }
+
+  lines.push(`${subjectStr} ${allPredObjs[0].predStr} ${allPredObjs[0].objStrs.join(', ')} ;`);
+  for (let i = 1; i < allPredObjs.length; i++) {
+    lines.push(`  ${allPredObjs[i].predStr} ${allPredObjs[i].objStrs.join(', ')} ;`);
+  }
+  // Replace trailing ; with .
+  lines[lines.length - 1] = lines[lines.length - 1].replace(/ ;$/, ' .');
+  return lines;
+}
+
+function formatTermSync(term, prefixes) {
+  switch (term.termType) {
+    case 'NamedNode':
+      return compactIriSync(term.value, prefixes);
+    case 'BlankNode':
+      return `_:${term.value}`;
+    case 'Literal':
+      return formatLiteralSync(term);
+    case 'DefaultGraph':
+      return '';
+    default:
+      return String(term.value ?? term);
+  }
+}
+
+function formatLiteralSync(lit) {
+  const escaped = escapeLiteralSync(lit.value);
+  if (lit.language) return `"${escaped}"@${lit.language}`;
+  const dt = lit.datatype?.value;
+  if (dt && dt !== 'http://www.w3.org/2001/XMLSchema#string') {
+    return `"${escaped}"^^<${dt}>`;
+  }
+  return `"${escaped}"`;
+}
+
+function escapeLiteralSync(s) {
+  return String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
+function compactIriSync(iri, prefixes) {
+  // If no prefixes, always use <>
+  if (!prefixes || Object.keys(prefixes).length === 0) {
+    return `<${iri}>`;
+  }
+  // Try longest prefix match
+  let bestPrefix = null;
+  let bestLen = 0;
+  for (const [prefix, base] of Object.entries(prefixes)) {
+    if (iri.startsWith(base) && base.length > bestLen) {
+      // Reject if local part contains characters that can't appear in a
+      // Turtle pname-local (e.g. leading digit is fine per Turtle 1.1,
+      // but // is not).
+      const local = iri.slice(base.length);
+      if (!local.startsWith('//')) {
+        bestPrefix = prefix;
+        bestLen = base.length;
+      }
+    }
+  }
+  if (!bestPrefix) return `<${iri}>`;
+  const local = iri.slice(bestLen);
+  const escaped = local.replace(/([/])/g, '\\$1');
+  return `${bestPrefix}:${escaped}`;
+}
+
+function compareQuadSync(a, b) {
+  let cmp = cmpTermSync(a.subject, b.subject);
+  if (cmp !== 0) return cmp;
+  cmp = cmpTermSync(a.predicate, b.predicate);
+  if (cmp !== 0) return cmp;
+  return cmpTermSync(a.object, b.object);
+}
+
+function cmpTermSync(a, b) {
+  if (a.termType !== b.termType) return a.termType.localeCompare(b.termType);
+  return String(a.value).localeCompare(String(b.value));
+}
+
+function groupBySubject(quads) {
+  const map = new Map();
+  for (const q of quads) {
+    const key = termKey(q.subject);
+    if (!map.has(key)) {
+      map.set(key, { subject: q.subject, triples: [] });
+    }
+    map.get(key).triples.push({ predicate: q.predicate, object: q.object });
+  }
+  return [...map.values()];
+}
+
+function termKey(term) {
+  return `${term.termType}:${term.value}`;
+}

package/src/transforms/concept-to-gloss.transform.js

@@ -16,7 +16,8 @@ import {
   writeJsonld,
 } from '../rdf/document-writer.js';
 
-const DEFAULT_URI_BASE = 'https://glossarist.org';
+// No hardcoded default URI base. Callers MUST pass options.uriBase so
+// concept IRIs reflect the consumer's domain.
 
 // Writer registry. Each entry is `{ write: (quads, transform) => Promise<string> }`.
 // Adding a new output format is a single entry here, not six new methods.
@@ -29,7 +30,8 @@ const WRITERS = Object.freeze({
 export class ConceptToGlossTransform {
   constructor(options = {}) {
     this.registerId = options.registerId;
-    this.uriBase = (options.uriBase ?? DEFAULT_URI_BASE).replace(/\/+$/, '');
+    this.uriBase = options.uriBase?.replace(/\/+$/, '');
+    if (!this.uriBase) throw new Error('ConceptToGlossTransform requires options.uriBase — the deployment canonical URI root.');
     this.jsonldContext = options.jsonldContext;
   }