@glossarist/concept-browser 0.1.0

package/src/adapters/DatasetAdapter.ts

@@ -0,0 +1,270 @@
+import type {
+  Manifest,
+  ConceptIndex,
+  ConceptSummary,
+  ConceptEntry,
+  ConceptDocument,
+  SearchHit,
+  GraphEdge,
+} from './types';
+import { UriRouter } from './UriRouter';
+
+export class DatasetAdapter {
+  private positionIndex = new Map<string, number>();
+  readonly registerId: string;
+  private baseUrl: string;
+  manifest: Manifest | null = null;
+  index: ConceptIndex | null = null;
+
+  private conceptCache = new Map<string, ConceptDocument>();
+  private summaryMap = new Map<string, ConceptSummary>();
+  private loadedChunks = new Set<number>();
+  private indexMeta: { conceptCount: number; chunkSize: number; chunks: { file: string; count: number }[] } | null = null;
+
+  constructor(registerId: string, baseUrl: string) {
+    this.registerId = registerId;
+    this.baseUrl = baseUrl;
+  }
+
+  async loadManifest(): Promise<Manifest> {
+    const resp = await fetch(`${this.baseUrl}/manifest.json`);
+    if (!resp.ok) throw new Error(`Failed to load manifest for ${this.registerId}: ${resp.status}`);
+    this.manifest = (await resp.json()) as Manifest;
+    return this.manifest;
+  }
+
+  async loadIndex(): Promise<ConceptIndex> {
+    const manifest = this.manifest;
+    const isLarge = manifest && manifest.conceptCount > 1000;
+
+    if (isLarge) {
+      return this.loadIndexChunked();
+    }
+
+    const resp = await fetch(`${this.baseUrl}/index.json`);
+    if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}: ${resp.status}`);
+    this.index = (await resp.json()) as ConceptIndex;
+    this.summaryMap.clear();
+    this.positionIndex.clear();
+    for (let i = 0; i < this.index.concepts.length; i++) {
+      this.summaryMap.set(this.index.concepts[i].id, this.index.concepts[i]);
+      this.positionIndex.set(this.index.concepts[i].id, i);
+    }
+    return this.index;
+  }
+
+  private async loadIndexChunked(): Promise<ConceptIndex> {
+    const metaResp = await fetch(`${this.baseUrl}/index-meta.json`);
+    let meta: { registerId: string; schemaVersion: string; conceptCount: number; chunkSize: number; chunks: { file: string; count: number }[] };
+    if (metaResp.ok) {
+      meta = await metaResp.json();
+    } else {
+      const resp = await fetch(`${this.baseUrl}/index.json`);
+      if (!resp.ok) throw new Error(`Failed to load index for ${this.registerId}`);
+      this.index = (await resp.json()) as ConceptIndex;
+      this.summaryMap.clear();
+      this.positionIndex.clear();
+      for (let i = 0; i < this.index.concepts.length; i++) {
+        this.summaryMap.set(this.index.concepts[i].id, this.index.concepts[i]);
+        this.positionIndex.set(this.index.concepts[i].id, i);
+      }
+      return this.index;
+    }
+
+    this.indexMeta = {
+      conceptCount: meta.conceptCount,
+      chunkSize: meta.chunkSize,
+      chunks: meta.chunks,
+    };
+
+    // Pre-allocate array so positions match concept order — undefined = not loaded yet
+    this.index = {
+      registerId: meta.registerId,
+      schemaVersion: meta.schemaVersion,
+      conceptCount: meta.conceptCount,
+      chunkSize: meta.chunkSize,
+      chunks: meta.chunks,
+      concepts: new Array(meta.conceptCount),
+    };
+
+    await this.loadChunkAsSummaries(0);
+
+    return this.index;
+  }
+
+  async loadChunk(chunkIndex: number): Promise<ConceptEntry[]> {
+    if (this.loadedChunks.has(chunkIndex)) return [];
+    const chunkFile = `index-${String(chunkIndex).padStart(4, '0')}.json`;
+    const resp = await fetch(`${this.baseUrl}/chunks/${chunkFile}`);
+    if (!resp.ok) throw new Error(`Failed to load chunk ${chunkIndex} for ${this.registerId}`);
+    const data = await resp.json();
+    this.loadedChunks.add(chunkIndex);
+    return data.concepts as ConceptEntry[];
+  }
+
+  private async loadChunkAsSummaries(chunkIndex: number): Promise<void> {
+    if (this.loadedChunks.has(chunkIndex)) return;
+
+    const chunkFile = `index-${String(chunkIndex).padStart(4, '0')}.json`;
+    const resp = await fetch(`${this.baseUrl}/chunks/${chunkFile}`);
+    if (!resp.ok) return;
+    const data = await resp.json();
+    this.loadedChunks.add(chunkIndex);
+
+    const entries = data.concepts as ConceptEntry[];
+    const startPos = chunkIndex * (this.indexMeta?.chunkSize ?? 500);
+
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      const summary: ConceptSummary = {
+        id: entry.id,
+        eng: entry.designations?.eng || Object.values(entry.designations || {})[0] || '',
+        status: entry.status,
+      };
+      (this.index!.concepts as (ConceptSummary | undefined)[])[startPos + i] = summary;
+      this.summaryMap.set(entry.id, summary);
+      this.positionIndex.set(entry.id, startPos + i);
+    }
+  }
+
+  async ensureChunksForRange(offset: number, limit: number): Promise<void> {
+    if (!this.indexMeta) return;
+    const { chunkSize, chunks } = this.indexMeta;
+    const firstChunk = Math.floor(offset / chunkSize);
+    const lastChunk = Math.floor((offset + limit - 1) / chunkSize);
+    const toLoad: number[] = [];
+    for (let c = firstChunk; c <= Math.min(lastChunk, chunks.length - 1); c++) {
+      if (!this.loadedChunks.has(c)) toLoad.push(c);
+    }
+    if (toLoad.length === 0) return;
+    await Promise.all(toLoad.map(c => this.loadChunkAsSummaries(c)));
+  }
+
+  async ensureAllChunksLoaded(): Promise<void> {
+    if (!this.indexMeta) return;
+    const { chunks } = this.indexMeta;
+    const toLoad = chunks.map((_, i) => i).filter(i => !this.loadedChunks.has(i));
+    // Load in parallel batches of 5 to avoid overwhelming the browser
+    for (let i = 0; i < toLoad.length; i += 5) {
+      const batch = toLoad.slice(i, i + 5);
+      await Promise.all(batch.map(c => this.loadChunkAsSummaries(c)));
+    }
+  }
+
+  isRangeLoaded(offset: number, limit: number): boolean {
+    if (!this.index?.concepts) return false;
+    const arr = this.index.concepts as (ConceptSummary | undefined)[];
+    for (let i = offset; i < Math.min(offset + limit, arr.length); i++) {
+      if (arr[i] === undefined) return false;
+    }
+    return true;
+  }
+
+  async fetchConcept(conceptId: string): Promise<ConceptDocument> {
+    const cached = this.conceptCache.get(conceptId);
+    if (cached) return cached;
+
+    const resp = await fetch(`${this.baseUrl}/concepts/${conceptId}.json`);
+    if (!resp.ok) throw new Error(`Concept ${conceptId} not found in ${this.registerId}`);
+    const doc = (await resp.json()) as ConceptDocument;
+    this.conceptCache.set(conceptId, doc);
+    return doc;
+  }
+
+  getIndexEntry(conceptId: string): ConceptSummary | undefined {
+    return this.summaryMap.get(conceptId);
+  }
+
+  getConcepts(): ConceptSummary[] {
+    return this.index?.concepts ?? [];
+  }
+
+  getConceptCount(): number {
+    return this.index?.conceptCount ?? this.indexMeta?.conceptCount ?? 0;
+  }
+
+  getConceptPosition(conceptId: string): number {
+    return this.positionIndex.get(conceptId) ?? -1;
+  }
+
+  getAdjacentConcepts(conceptId: string): { prev: string | null; next: string | null } {
+    const concepts = this.index?.concepts as (ConceptSummary | undefined)[] | undefined;
+    if (!concepts) return { prev: null, next: null };
+    const idx = this.getConceptPosition(conceptId);
+    if (idx === -1) return { prev: null, next: null };
+    // Scan backward for prev (skip undefined)
+    let prev: string | null = null;
+    for (let i = idx - 1; i >= 0; i--) {
+      if (concepts[i]) { prev = concepts[i]!.id; break; }
+    }
+    // Scan forward for next (skip undefined)
+    let next: string | null = null;
+    for (let i = idx + 1; i < concepts.length; i++) {
+      if (concepts[i]) { next = concepts[i]!.id; break; }
+    }
+    return { prev, next };
+  }
+
+  search(query: string, lang: string = 'eng'): SearchHit[] {
+    const q = query.toLowerCase();
+    const hits: SearchHit[] = [];
+    const arr = this.index?.concepts as (ConceptSummary | undefined)[] | undefined;
+    if (!arr) return hits;
+
+    for (const entry of arr) {
+      if (!entry) continue;
+      const term = entry.eng || '';
+      if (term.toLowerCase().includes(q) || entry.id.toLowerCase().includes(q)) {
+        hits.push({
+          conceptId: entry.id,
+          registerId: this.registerId,
+          designation: term,
+          language: lang,
+          matchField: 'designation',
+        });
+      }
+    }
+    return hits;
+  }
+
+  extractEdges(concept: ConceptDocument): GraphEdge[] {
+    const edges: GraphEdge[] = [];
+    const sourceUri = concept['@id'];
+
+    for (const [_lang, lc] of Object.entries(concept['gl:localizedConcept'] || {})) {
+      if (lc['gl:references']) {
+        for (const ref of lc['gl:references']) {
+          if (ref['@id'] && ref['@id'] !== sourceUri) {
+            const parsed = UriRouter.parseUri(ref['@id']);
+            edges.push({
+              source: sourceUri,
+              target: ref['@id'],
+              type: 'references',
+              label: ref['gl:term'],
+              register: parsed?.registerId ?? this.registerId,
+            });
+          }
+        }
+      }
+    }
+
+    return edges;
+  }
+
+  async loadEdgeIndex(): Promise<GraphEdge[]> {
+    const resp = await fetch(`${this.baseUrl}/edges.json`);
+    if (!resp.ok) return [];
+    const data = await resp.json();
+    return data.edges ?? [];
+  }
+
+  async loadGraphNodes(): Promise<{ uriPrefix: string; nodes: [string, string, string, string][] }> {
+    const resp = await fetch(`${this.baseUrl}/graph-nodes.json`);
+    if (!resp.ok) return { uriPrefix: '', nodes: [] };
+    return await resp.json();
+  }
+
+  getLanguages(): string[] {
+    return this.manifest?.languages ?? [];
+  }
+}

package/src/adapters/ReferenceResolver.ts

@@ -0,0 +1,95 @@
+import type { Resolution } from './types';
+import type { RoutingEntry } from '../config/types';
+
+interface DatasetEntry {
+  id: string;
+  uriPatterns: string[];
+}
+
+function extractConceptId(uri: string, pattern: string): string | null {
+  if (!pattern.endsWith('*')) return null;
+  const base = pattern.slice(0, -1);
+  if (!uri.startsWith(base)) return null;
+  const remainder = uri.slice(base.length);
+
+  if (uri.startsWith('https://') || uri.startsWith('http://')) {
+    const match = remainder.match(/^\/?concept\/([^/?#]+)/);
+    return match ? match[1] : null;
+  }
+  if (uri.startsWith('urn:')) {
+    return remainder || null;
+  }
+  return null;
+}
+
+function matchUriPattern(uri: string, pattern: string): boolean {
+  if (!pattern.endsWith('*')) return uri === pattern;
+  return uri.startsWith(pattern.slice(0, -1));
+}
+
+export class ReferenceResolver {
+  private datasets: DatasetEntry[] = [];
+  private routing: RoutingEntry[] = [];
+
+  registerDataset(id: string, uriPatterns: string[]): void {
+    this.datasets.push({ id, uriPatterns });
+  }
+
+  loadRouting(entries: RoutingEntry[]): void {
+    this.routing = entries;
+  }
+
+  resolveReference(uri: string, sourceDatasetId?: string): Resolution {
+    // Step 1: Check provided datasets
+    for (const ds of this.datasets) {
+      for (const pattern of ds.uriPatterns) {
+        if (matchUriPattern(uri, pattern)) {
+          const conceptId = extractConceptId(uri, pattern);
+          if (conceptId) {
+            return {
+              type: 'internal',
+              registerId: ds.id,
+              conceptId,
+              crossDataset: sourceDatasetId != null && sourceDatasetId !== ds.id,
+            };
+          }
+        }
+      }
+    }
+
+    // Step 2: Check routing table
+    for (const entry of this.routing) {
+      if (matchUriPattern(uri, entry.uri)) {
+        if (entry.type === 'site') {
+          return {
+            type: 'site',
+            baseUrl: entry.baseUrl!,
+            conceptUri: uri,
+            label: entry.label,
+          };
+        }
+        if (entry.type === 'url') {
+          const template = entry.url!;
+          const conceptId = this.extractConceptIdFromRouting(uri, entry.uri);
+          const url = template.includes('{conceptId}') && conceptId
+            ? template.replace('{conceptId}', conceptId)
+            : template;
+          return { type: 'url', url, label: entry.label };
+        }
+      }
+    }
+
+    return { type: 'unresolved', uri };
+  }
+
+  private extractConceptIdFromRouting(uri: string, pattern: string): string | null {
+    for (const ds of this.datasets) {
+      for (const dsPattern of ds.uriPatterns) {
+        if (matchUriPattern(uri, dsPattern)) {
+          return extractConceptId(uri, dsPattern);
+        }
+      }
+    }
+    return extractConceptId(uri, pattern);
+  }
+}

package/src/adapters/UriRouter.ts

@@ -0,0 +1,41 @@
+import type { Manifest } from './types';
+
+const URI_REGISTER_RE = /\/([^/]+)\/concept\/([^/]+)$/;
+
+export class UriRouter {
+  private registerMap = new Map<string, { baseUrl: string; manifest: Manifest | null; uriBase: string }>();
+
+  registerDataset(registerId: string, baseUrl: string, manifest?: Manifest) {
+    this.registerMap.set(registerId, {
+      baseUrl,
+      manifest: manifest ?? null,
+      uriBase: manifest?.uriBase ?? 'https://glossarist.org',
+    });
+  }
+
+  resolveUri(uri: string): { registerId: string; conceptId: string } | null {
+    for (const [registerId, info] of this.registerMap) {
+      const prefix = `${info.uriBase}/${registerId}/concept/`;
+      if (uri.startsWith(prefix)) {
+        return { registerId, conceptId: uri.slice(prefix.length) };
+      }
+    }
+    return null;
+  }
+
+  /** Extract registerId and conceptId from any glossarist URI (no registration needed). */
+  static parseUri(uri: string): { registerId: string; conceptId: string } | null {
+    const m = uri.match(URI_REGISTER_RE);
+    return m ? { registerId: m[1], conceptId: m[2] } : null;
+  }
+
+  buildUri(registerId: string, conceptId: string): string {
+    const info = this.registerMap.get(registerId);
+    const uriBase = info?.uriBase ?? 'https://glossarist.org';
+    return `${uriBase}/${registerId}/concept/${conceptId}`;
+  }
+
+  getRegisteredIds(): string[] {
+    return [...this.registerMap.keys()];
+  }
+}

package/src/adapters/factory.ts

@@ -0,0 +1,78 @@
+import type { DatasetRegistry, Manifest, Resolution } from './types';
+import type { RoutingEntry as ConfigRoutingEntry } from '../config/types';
+import { DatasetAdapter } from './DatasetAdapter';
+import { UriRouter } from './UriRouter';
+import { ReferenceResolver } from './ReferenceResolver';
+
+export class AdapterFactory {
+  private adapters = new Map<string, DatasetAdapter>();
+  readonly router = new UriRouter();
+  readonly resolver: ReferenceResolver;
+
+  constructor() {
+    this.resolver = new ReferenceResolver();
+  }
+
+  async discoverDatasets(datasetsUrl: string): Promise<DatasetAdapter[]> {
+    const resp = await fetch(datasetsUrl);
+    if (!resp.ok) throw new Error(`Failed to load dataset registry: ${resp.status}`);
+    const registry = (await resp.json()) as DatasetRegistry[];
+
+    const adapters: DatasetAdapter[] = [];
+    for (const reg of registry) {
+      const adapter = new DatasetAdapter(reg.id, `/data/${reg.id}`);
+      this.adapters.set(reg.id, adapter);
+      adapters.push(adapter);
+    }
+
+    await Promise.all(adapters.map(a => a.loadManifest().catch(() => {})));
+
+    return adapters;
+  }
+
+  getAdapter(registerId: string): DatasetAdapter | undefined {
+    return this.adapters.get(registerId);
+  }
+
+  getAdapters(): DatasetAdapter[] {
+    return [...this.adapters.values()];
+  }
+
+  async loadDataset(registerId: string): Promise<DatasetAdapter> {
+    const adapter = this.adapters.get(registerId);
+    if (!adapter) throw new Error(`Unknown dataset: ${registerId}`);
+
+    const manifest = await adapter.loadManifest();
+    await adapter.loadIndex();
+
+    this.router.registerDataset(registerId, `/data/${registerId}`, manifest);
+
+    const uriPatterns = [
+      manifest.datasetUri,
+      ...(manifest.uriAliases ?? []),
+      `https://glossarist.org/${registerId}/*`,
+    ];
+    this.resolver.registerDataset(registerId, uriPatterns);
+
+    return adapter;
+  }
+
+  loadRouting(entries: ConfigRoutingEntry[]): void {
+    this.resolver.loadRouting(entries);
+  }
+
+  resolve(uri: string, sourceDatasetId?: string): Resolution {
+    return this.resolver.resolveReference(uri, sourceDatasetId);
+  }
+}
+
+let _instance: AdapterFactory | null = null;
+
+export function getFactory(): AdapterFactory {
+  if (!_instance) _instance = new AdapterFactory();
+  return _instance;
+}
+
+export function resetFactory(): void {
+  _instance = null;
+}

package/src/adapters/types.ts

@@ -0,0 +1,162 @@
+/** Core types for the vocabulary browser data model. */
+
+export interface Manifest {
+  id: string;
+  datasetUri: string;
+  uriAliases?: string[];
+  title: string;
+  description: string;
+  owner: string;
+  baseUrl: string;
+  languages: string[];
+  conceptCount: number;
+  conceptUrlTemplate: string;
+  indexUrl: string;
+  contextUrl: string;
+  uriBase: string;
+  status: string;
+  schemaVersion: string;
+  tags: string[];
+  lastUpdated: string;
+  sourceRepo: string;
+  chunkSize: number;
+  color?: string;
+  shortname?: string;
+  languageOrder?: string[];
+  languageStats?: Record<string, { terms: number; definitions: number }>;
+  availableFormats?: string[];
+}
+
+export interface ConceptIndex {
+  registerId: string;
+  schemaVersion: string;
+  conceptCount: number;
+  chunkSize: number;
+  chunks: { file: string; count: number }[];
+  concepts: ConceptSummary[];
+}
+
+export interface ConceptSummary {
+  id: string;
+  eng: string;
+  status: string;
+}
+
+export interface ConceptEntry {
+  id: string;
+  designations: Record<string, string>;
+  groups: string[];
+  status: string;
+}
+
+export interface ConceptDocument {
+  '@context': string;
+  '@id': string;
+  '@type': string;
+  'gl:identifier': string;
+  'gl:localizedConcept': Record<string, LocalizedConcept>;
+}
+
+export interface LocalizedConcept {
+  '@id': string;
+  '@type': string;
+  'gl:languageCode': string;
+  'gl:entryStatus'?: string;
+  'gl:designation'?: Designation[];
+  'gl:definition'?: DetailedDefinition[];
+  'gl:notes'?: DetailedDefinition[];
+  'gl:examples'?: DetailedDefinition[];
+  'gl:source'?: ConceptSource[];
+  'gl:release'?: number;
+  'gl:reviewDate'?: string;
+  'gl:reviewDecisionDate'?: string;
+  'gl:reviewDecisionEvent'?: string;
+  'gl:reviewStatus'?: string;
+  'gl:reviewDecision'?: string;
+  'gl:reviewDecisionNotes'?: string;
+  'gl:dates'?: ConceptDate[];
+  'gl:references'?: CrossReference[];
+}
+
+export interface Designation {
+  '@type': string;
+  'gl:normativeStatus': string;
+  'gl:term': string;
+  'gl:gender'?: string;
+  'gl:plurality'?: string;
+  'gl:international'?: boolean;
+}
+
+export interface DetailedDefinition {
+  '@type': string;
+  'gl:content': string;
+}
+
+export interface ConceptSource {
+  '@type': string;
+  'gl:sourceType'?: string;
+  'gl:sourceStatus'?: string;
+  'gl:modification'?: string;
+  'gl:origin'?: {
+    '@type': string;
+    'gl:ref'?: string;
+    'gl:clause'?: string;
+    'gl:link'?: string;
+  };
+}
+
+export interface ConceptDate {
+  'gl:dateType': string;
+  'gl:date': string;
+}
+
+export interface CrossReference {
+  '@id': string;
+  'gl:term': string;
+}
+
+export interface DatasetRegistry {
+  id: string;
+  manifestUrl: string;
+}
+
+export interface GraphEdge {
+  source: string; // concept URI
+  target: string; // concept URI
+  type: string;
+  label?: string;
+  register: string;
+}
+
+export interface GraphNode {
+  uri: string;
+  register: string;
+  conceptId: string;
+  designations: Record<string, string>;
+  status: string;
+  loaded: boolean;
+}
+
+export interface SearchHit {
+  conceptId: string;
+  registerId: string;
+  designation: string;
+  language: string;
+  matchField: 'designation' | 'definition';
+  snippet?: string;
+}
+
+export type RelationType =
+  | 'related'
+  | 'narrower'
+  | 'broader'
+  | 'see'
+  | 'references'
+  | 'replaces'
+  | 'superseded';
+
+export type Resolution =
+  | { type: 'internal'; registerId: string; conceptId: string; crossDataset: boolean }
+  | { type: 'site'; baseUrl: string; conceptUri: string; label: string }
+  | { type: 'url'; url: string; label: string }
+  | { type: 'unresolved'; uri: string };