@iqb/metadata-resolver 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Institute for Educational Quality Improvement (IQB)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,33 @@
1
+ # @iqb/metadata-resolver
2
+
3
+ TypeScript library for loading metadata profiles and vocabularies.
4
+
5
+ ## Installation
6
+ ```bash
7
+ npm install @iqb/metadata-resolver
8
+ ```
9
+
10
+ ## Quick Start
11
+ ```typescript
12
+ import { MetadataResolver } from '@iqb/metadata-resolver';
13
+
14
+ const resolver = new MetadataResolver();
15
+ const data = await resolver.loadProfileWithVocabularies(
16
+ 'https://raw.githubusercontent.com/iqb-vocabs/p16/master/unit.json'
17
+ );
18
+
19
+ console.log(data.profile);
20
+ console.log(data.vocabularies);
21
+ ```
22
+
23
+ ## Documentation
24
+
25
+ See [GETTING_STARTED.md](./GETTING_STARTED.md) for detailed usage guide.
26
+
27
+ ## Version
28
+
29
+ **0.1.0** - Testing phase
30
+
31
+ ## License
32
+
33
+ MIT © IQB Berlin
package/dist/index.cjs ADDED
@@ -0,0 +1,263 @@
1
+
2
+ //#region src/metadata-resolver.ts
3
+ var MetadataResolver = class {
4
+ corsProxy;
5
+ cache = /* @__PURE__ */ new Map();
6
+ vocabulariesStore = /* @__PURE__ */ new Map();
7
+ useCache;
8
+ preferredLanguage;
9
+ requestTimeout;
10
+ constructor(options) {
11
+ this.corsProxy = options?.corsProxy;
12
+ this.useCache = options?.cache ?? true;
13
+ this.preferredLanguage = options?.preferredLanguage || "de";
14
+ this.requestTimeout = options?.requestTimeout || 1e4;
15
+ }
16
+ /**
17
+ * Load a profile from a URL
18
+ */
19
+ async loadProfile(url) {
20
+ const cacheKey = `profile:${url}`;
21
+ if (this.useCache && this.cache.has(cacheKey)) return this.cache.get(cacheKey);
22
+ try {
23
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(url)}` : url;
24
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
25
+ if (!response.ok) throw new Error(`Failed to load profile: ${response.status} ${response.statusText}`);
26
+ const profile = await response.json();
27
+ if (this.useCache) this.cache.set(cacheKey, profile);
28
+ return profile;
29
+ } catch (error) {
30
+ throw new Error(`Error loading profile from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`);
31
+ }
32
+ }
33
+ /**
34
+ * Load metadata from a URL
35
+ */
36
+ async loadMetadata(url) {
37
+ const cacheKey = `metadata:${url}`;
38
+ if (this.useCache && this.cache.has(cacheKey)) return this.cache.get(cacheKey);
39
+ try {
40
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(url)}` : url;
41
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
42
+ if (!response.ok) throw new Error(`Failed to load metadata: ${response.status} ${response.statusText}`);
43
+ const metadata = await response.json();
44
+ if (this.useCache) this.cache.set(cacheKey, metadata);
45
+ return metadata;
46
+ } catch (error) {
47
+ throw new Error(`Error loading metadata from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`);
48
+ }
49
+ }
50
+ /**
51
+ * Extract vocabulary URLs from a profile
52
+ */
53
+ extractVocabularyUrls(profile) {
54
+ const urls = /* @__PURE__ */ new Set();
55
+ profile.groups?.forEach((group) => {
56
+ group.entries?.forEach((entry) => {
57
+ if (entry.type === "vocabulary" && entry.parameters) {
58
+ const params = entry.parameters;
59
+ if (params.url) urls.add(params.url);
60
+ }
61
+ });
62
+ });
63
+ return Array.from(urls);
64
+ }
65
+ /**
66
+ * Load a single vocabulary from URL
67
+ * Uses vocabulariesStore as the cache
68
+ */
69
+ async loadVocabulary(url) {
70
+ if (this.useCache && this.vocabulariesStore.has(url)) return this.vocabulariesStore.get(url);
71
+ try {
72
+ console.log(`Loading vocabulary: ${url}`);
73
+ const jsonLdUrl = await this.resolveJsonLdUrl(url);
74
+ if (jsonLdUrl !== url) console.log(` Resolved to: ${jsonLdUrl}`);
75
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonLdUrl)}` : jsonLdUrl;
76
+ if (this.corsProxy) console.log(` Using CORS proxy`);
77
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
78
+ if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
79
+ const data = await response.json();
80
+ if (!data.hasTopConcept || !Array.isArray(data.hasTopConcept)) throw new Error("Invalid structure: missing hasTopConcept");
81
+ const dictionary = this.buildVocabularyDictionary(data);
82
+ const resolved = {
83
+ url,
84
+ data,
85
+ dictionary
86
+ };
87
+ if (this.useCache) this.vocabulariesStore.set(url, resolved);
88
+ console.log(` Loaded: ${data.hasTopConcept.length} concepts, ${Object.keys(dictionary).length} entries`);
89
+ return resolved;
90
+ } catch (error) {
91
+ const errorMsg = error instanceof Error ? error.message : String(error);
92
+ console.error(` Failed to load vocabulary: ${errorMsg}`);
93
+ return {
94
+ url,
95
+ data: { hasTopConcept: [] },
96
+ dictionary: {},
97
+ error: errorMsg
98
+ };
99
+ }
100
+ }
101
+ /**
102
+ * Load all vocabularies referenced in a profile
103
+ */
104
+ async loadVocabularies(profile) {
105
+ const urls = this.extractVocabularyUrls(profile);
106
+ const vocabularies = (await Promise.allSettled(urls.map((url) => this.loadVocabulary(url)))).filter((result) => result.status === "fulfilled").map((result) => result.value);
107
+ console.log(`Loaded ${vocabularies.length} vocabularies (${this.vocabulariesStore.size} total in store)`);
108
+ return vocabularies;
109
+ }
110
+ /**
111
+ * Build a dictionary from vocabulary data
112
+ */
113
+ buildVocabularyDictionary(vocabData) {
114
+ const dictionary = {};
115
+ const processNode = (node, parentNotation = []) => {
116
+ const notation = node.notation || parentNotation;
117
+ const label = node.prefLabel?.[this.preferredLanguage] || node.prefLabel?.de || node.prefLabel?.en || "";
118
+ dictionary[node.id] = {
119
+ id: node.id,
120
+ notation,
121
+ name: label,
122
+ description: node.description || "",
123
+ text: [{
124
+ lang: this.preferredLanguage,
125
+ value: label
126
+ }]
127
+ };
128
+ if (node.narrower && Array.isArray(node.narrower)) node.narrower.forEach((child) => processNode(child, notation));
129
+ };
130
+ vocabData.hasTopConcept?.forEach((topConcept) => processNode(topConcept));
131
+ return dictionary;
132
+ }
133
+ /**
134
+ * Load a profile and all its vocabularies
135
+ */
136
+ async loadProfileWithVocabularies(profileUrl) {
137
+ const profile = await this.loadProfile(profileUrl);
138
+ return {
139
+ profile,
140
+ vocabularies: await this.loadVocabularies(profile)
141
+ };
142
+ }
143
+ /**
144
+ * Resolve a URL to its JSON-LD representation
145
+ */
146
+ async resolveJsonLdUrl(originalUrl) {
147
+ try {
148
+ console.log(`Resolving URL: ${originalUrl}`);
149
+ console.log(` CORS proxy: ${this.corsProxy || "disabled"}`);
150
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(originalUrl)}` : originalUrl;
151
+ console.log(` Fetching: ${fetchUrl}`);
152
+ const res = await fetch(fetchUrl, {
153
+ method: "GET",
154
+ redirect: "follow",
155
+ signal: AbortSignal.timeout(this.requestTimeout)
156
+ });
157
+ const finalUrl = res.url;
158
+ const contentType = res.headers.get("content-type");
159
+ if (contentType?.includes("application/json") || contentType?.includes("application/ld+json")) return finalUrl;
160
+ if (contentType?.includes("text/html")) {
161
+ if (finalUrl.endsWith(".html")) {
162
+ const jsonldUrl = finalUrl.replace(/\.html$/, ".jsonld");
163
+ try {
164
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonldUrl)}` : jsonldUrl, {
165
+ method: "HEAD",
166
+ signal: AbortSignal.timeout(this.requestTimeout)
167
+ })).ok) {
168
+ console.log(` Found JSON-LD: ${jsonldUrl}`);
169
+ return jsonldUrl;
170
+ }
171
+ } catch (err) {
172
+ console.log(` JSON-LD not available: ${err instanceof Error ? err.message : String(err)}`);
173
+ }
174
+ const jsonUrl = finalUrl.replace(/\.html$/, ".json");
175
+ try {
176
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonUrl)}` : jsonUrl, {
177
+ method: "HEAD",
178
+ signal: AbortSignal.timeout(this.requestTimeout)
179
+ })).ok) {
180
+ console.log(` Found JSON: ${jsonUrl}`);
181
+ return jsonUrl;
182
+ }
183
+ } catch (err) {
184
+ console.log(` JSON not available: ${err instanceof Error ? err.message : String(err)}`);
185
+ }
186
+ }
187
+ const jsonCandidates = [finalUrl.endsWith("/") ? `${finalUrl}index.json` : `${finalUrl}/index.json`, finalUrl.endsWith("/") ? `${finalUrl}index.jsonld` : `${finalUrl}/index.jsonld`];
188
+ for (const candidate of jsonCandidates) try {
189
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(candidate)}` : candidate, {
190
+ method: "HEAD",
191
+ signal: AbortSignal.timeout(this.requestTimeout)
192
+ })).ok) {
193
+ console.log(` Found: ${candidate}`);
194
+ return candidate;
195
+ }
196
+ } catch (err) {
197
+ console.log(` Not available: ${candidate} - ${err instanceof Error ? err.message : String(err)}`);
198
+ }
199
+ console.warn("No JSON file found at HTML URL:", finalUrl);
200
+ return finalUrl;
201
+ }
202
+ return finalUrl;
203
+ } catch (err) {
204
+ console.warn("Failed to resolve JSON-LD URL, falling back to original:", originalUrl, err);
205
+ return originalUrl;
206
+ }
207
+ }
208
+ /**
209
+ * Load both profile with vocabularies and metadata
210
+ */
211
+ async loadAll(profileUrl, metadataUrl) {
212
+ const [profileWithVocabs, metadata] = await Promise.all([this.loadProfileWithVocabularies(profileUrl), this.loadMetadata(metadataUrl)]);
213
+ return {
214
+ profile: profileWithVocabs.profile,
215
+ metadata,
216
+ vocabularies: profileWithVocabs.vocabularies
217
+ };
218
+ }
219
+ /**
220
+ * Extract text from a label (string or multilingual array)
221
+ */
222
+ static extractLabelText(label, preferredLanguage = "de") {
223
+ if (typeof label === "string") return label;
224
+ if (Array.isArray(label)) {
225
+ const preferred = label.find((l) => l.lang === preferredLanguage);
226
+ if (preferred) return preferred.value;
227
+ if (label.length > 0) return label[0].value;
228
+ }
229
+ return "";
230
+ }
231
+ /**
232
+ * Clear all caches (profiles, metadata, and vocabularies)
233
+ */
234
+ clearCache() {
235
+ this.cache.clear();
236
+ this.vocabulariesStore.clear();
237
+ }
238
+ /**
239
+ * Get all loaded vocabularies
240
+ */
241
+ getVocabularies() {
242
+ return Array.from(this.vocabulariesStore.values());
243
+ }
244
+ /**
245
+ * Get a specific vocabulary by URL
246
+ */
247
+ getVocabulary(url) {
248
+ return this.vocabulariesStore.get(url);
249
+ }
250
+ /**
251
+ * Get combined dictionary of all vocabulary entries
252
+ */
253
+ getVocabularyDictionary() {
254
+ const combinedDict = {};
255
+ this.vocabulariesStore.forEach((vocab) => {
256
+ Object.assign(combinedDict, vocab.dictionary);
257
+ });
258
+ return combinedDict;
259
+ }
260
+ };
261
+
262
+ //#endregion
263
+ exports.MetadataResolver = MetadataResolver;
@@ -0,0 +1,170 @@
1
+ import { MDProfile } from "@iqb/metadata";
2
+
3
+ //#region src/types.d.ts
4
+
5
+ /**
6
+ * Configuration options for the MetadataResolver
7
+ */
8
+ interface LoaderOptions {
9
+ /**
10
+ * CORS proxy URL (e.g., 'https://corsproxy.io/?')
11
+ * If provided, all fetch requests will be proxied through this URL
12
+ */
13
+ corsProxy?: string;
14
+ /**
15
+ * Enable caching of loaded resources
16
+ * @default true
17
+ */
18
+ cache?: boolean;
19
+ /**
20
+ * Preferred language for vocabulary labels
21
+ * @default 'de'
22
+ */
23
+ preferredLanguage?: string;
24
+ /**
25
+ * Request timeout in milliseconds
26
+ * @default 10000
27
+ */
28
+ requestTimeout?: number;
29
+ }
30
+ /**
31
+ * Vocabulary concept node structure
32
+ */
33
+ interface VocabConcept {
34
+ id: string;
35
+ notation?: string[];
36
+ prefLabel?: {
37
+ de?: string;
38
+ en?: string;
39
+ [key: string]: string | undefined;
40
+ };
41
+ description?: string;
42
+ narrower?: VocabConcept[];
43
+ }
44
+ /**
45
+ * Raw vocabulary data structure from vocabulary JSON files
46
+ */
47
+ interface VocabularyData {
48
+ id?: string;
49
+ type?: string;
50
+ title?: Record<string, string>;
51
+ hasTopConcept?: VocabConcept[];
52
+ }
53
+ interface VocabularyEntry {
54
+ id: string;
55
+ name: string;
56
+ notation: string[];
57
+ description?: string;
58
+ text: TextWithLanguage[];
59
+ }
60
+ /**
61
+ * Resolved vocabulary with data and lookup dictionary
62
+ */
63
+ interface ResolvedVocabulary {
64
+ url: string;
65
+ data: VocabularyData;
66
+ dictionary: Record<string, VocabularyEntry>;
67
+ error?: string;
68
+ }
69
+ /**
70
+ * Profile loaded with all its vocabularies
71
+ */
72
+ interface ProfileWithVocabularies {
73
+ profile: MDProfile;
74
+ vocabularies: ResolvedVocabulary[];
75
+ }
76
+ /**
77
+ * Complete metadata package with profile, metadata, and vocabularies
78
+ */
79
+ interface MetadataWithProfile {
80
+ profile: MDProfile;
81
+ metadata: any;
82
+ vocabularies: ResolvedVocabulary[];
83
+ }
84
+ /**
85
+ * Multilingual text structure
86
+ */
87
+ interface TextWithLanguage {
88
+ lang: string;
89
+ value: string;
90
+ }
91
+ /**
92
+ * Text with language and ID (for vocabulary references)
93
+ */
94
+ interface TextWithLanguageAndId {
95
+ id: string;
96
+ text: TextWithLanguage[];
97
+ }
98
+ //#endregion
99
+ //#region src/metadata-resolver.d.ts
100
+ declare class MetadataResolver {
101
+ private corsProxy;
102
+ private cache;
103
+ private vocabulariesStore;
104
+ private useCache;
105
+ private preferredLanguage;
106
+ private requestTimeout;
107
+ constructor(options?: LoaderOptions);
108
+ /**
109
+ * Load a profile from a URL
110
+ */
111
+ loadProfile(url: string): Promise<MDProfile>;
112
+ /**
113
+ * Load metadata from a URL
114
+ */
115
+ loadMetadata(url: string): Promise<any>;
116
+ /**
117
+ * Extract vocabulary URLs from a profile
118
+ */
119
+ extractVocabularyUrls(profile: MDProfile): string[];
120
+ /**
121
+ * Load a single vocabulary from URL
122
+ * Uses vocabulariesStore as the cache
123
+ */
124
+ loadVocabulary(url: string): Promise<ResolvedVocabulary>;
125
+ /**
126
+ * Load all vocabularies referenced in a profile
127
+ */
128
+ loadVocabularies(profile: MDProfile): Promise<ResolvedVocabulary[]>;
129
+ /**
130
+ * Build a dictionary from vocabulary data
131
+ */
132
+ private buildVocabularyDictionary;
133
+ /**
134
+ * Load a profile and all its vocabularies
135
+ */
136
+ loadProfileWithVocabularies(profileUrl: string): Promise<ProfileWithVocabularies>;
137
+ /**
138
+ * Resolve a URL to its JSON-LD representation
139
+ */
140
+ private resolveJsonLdUrl;
141
+ /**
142
+ * Load both profile with vocabularies and metadata
143
+ */
144
+ loadAll(profileUrl: string, metadataUrl: string): Promise<MetadataWithProfile>;
145
+ /**
146
+ * Extract text from a label (string or multilingual array)
147
+ */
148
+ static extractLabelText(label: string | Array<{
149
+ lang: string;
150
+ value: string;
151
+ }>, preferredLanguage?: string): string;
152
+ /**
153
+ * Clear all caches (profiles, metadata, and vocabularies)
154
+ */
155
+ clearCache(): void;
156
+ /**
157
+ * Get all loaded vocabularies
158
+ */
159
+ getVocabularies(): ResolvedVocabulary[];
160
+ /**
161
+ * Get a specific vocabulary by URL
162
+ */
163
+ getVocabulary(url: string): ResolvedVocabulary | undefined;
164
+ /**
165
+ * Get combined dictionary of all vocabulary entries
166
+ */
167
+ getVocabularyDictionary(): Record<string, VocabularyEntry>;
168
+ }
169
+ //#endregion
170
+ export { type LoaderOptions, MetadataResolver, type MetadataWithProfile, type ProfileWithVocabularies, type ResolvedVocabulary, type TextWithLanguage, type TextWithLanguageAndId, type VocabConcept, type VocabularyData, type VocabularyEntry };
@@ -0,0 +1,170 @@
1
+ import { MDProfile } from "@iqb/metadata";
2
+
3
+ //#region src/types.d.ts
4
+
5
+ /**
6
+ * Configuration options for the MetadataResolver
7
+ */
8
+ interface LoaderOptions {
9
+ /**
10
+ * CORS proxy URL (e.g., 'https://corsproxy.io/?')
11
+ * If provided, all fetch requests will be proxied through this URL
12
+ */
13
+ corsProxy?: string;
14
+ /**
15
+ * Enable caching of loaded resources
16
+ * @default true
17
+ */
18
+ cache?: boolean;
19
+ /**
20
+ * Preferred language for vocabulary labels
21
+ * @default 'de'
22
+ */
23
+ preferredLanguage?: string;
24
+ /**
25
+ * Request timeout in milliseconds
26
+ * @default 10000
27
+ */
28
+ requestTimeout?: number;
29
+ }
30
+ /**
31
+ * Vocabulary concept node structure
32
+ */
33
+ interface VocabConcept {
34
+ id: string;
35
+ notation?: string[];
36
+ prefLabel?: {
37
+ de?: string;
38
+ en?: string;
39
+ [key: string]: string | undefined;
40
+ };
41
+ description?: string;
42
+ narrower?: VocabConcept[];
43
+ }
44
+ /**
45
+ * Raw vocabulary data structure from vocabulary JSON files
46
+ */
47
+ interface VocabularyData {
48
+ id?: string;
49
+ type?: string;
50
+ title?: Record<string, string>;
51
+ hasTopConcept?: VocabConcept[];
52
+ }
53
+ interface VocabularyEntry {
54
+ id: string;
55
+ name: string;
56
+ notation: string[];
57
+ description?: string;
58
+ text: TextWithLanguage[];
59
+ }
60
+ /**
61
+ * Resolved vocabulary with data and lookup dictionary
62
+ */
63
+ interface ResolvedVocabulary {
64
+ url: string;
65
+ data: VocabularyData;
66
+ dictionary: Record<string, VocabularyEntry>;
67
+ error?: string;
68
+ }
69
+ /**
70
+ * Profile loaded with all its vocabularies
71
+ */
72
+ interface ProfileWithVocabularies {
73
+ profile: MDProfile;
74
+ vocabularies: ResolvedVocabulary[];
75
+ }
76
+ /**
77
+ * Complete metadata package with profile, metadata, and vocabularies
78
+ */
79
+ interface MetadataWithProfile {
80
+ profile: MDProfile;
81
+ metadata: any;
82
+ vocabularies: ResolvedVocabulary[];
83
+ }
84
+ /**
85
+ * Multilingual text structure
86
+ */
87
+ interface TextWithLanguage {
88
+ lang: string;
89
+ value: string;
90
+ }
91
+ /**
92
+ * Text with language and ID (for vocabulary references)
93
+ */
94
+ interface TextWithLanguageAndId {
95
+ id: string;
96
+ text: TextWithLanguage[];
97
+ }
98
+ //#endregion
99
+ //#region src/metadata-resolver.d.ts
100
+ declare class MetadataResolver {
101
+ private corsProxy;
102
+ private cache;
103
+ private vocabulariesStore;
104
+ private useCache;
105
+ private preferredLanguage;
106
+ private requestTimeout;
107
+ constructor(options?: LoaderOptions);
108
+ /**
109
+ * Load a profile from a URL
110
+ */
111
+ loadProfile(url: string): Promise<MDProfile>;
112
+ /**
113
+ * Load metadata from a URL
114
+ */
115
+ loadMetadata(url: string): Promise<any>;
116
+ /**
117
+ * Extract vocabulary URLs from a profile
118
+ */
119
+ extractVocabularyUrls(profile: MDProfile): string[];
120
+ /**
121
+ * Load a single vocabulary from URL
122
+ * Uses vocabulariesStore as the cache
123
+ */
124
+ loadVocabulary(url: string): Promise<ResolvedVocabulary>;
125
+ /**
126
+ * Load all vocabularies referenced in a profile
127
+ */
128
+ loadVocabularies(profile: MDProfile): Promise<ResolvedVocabulary[]>;
129
+ /**
130
+ * Build a dictionary from vocabulary data
131
+ */
132
+ private buildVocabularyDictionary;
133
+ /**
134
+ * Load a profile and all its vocabularies
135
+ */
136
+ loadProfileWithVocabularies(profileUrl: string): Promise<ProfileWithVocabularies>;
137
+ /**
138
+ * Resolve a URL to its JSON-LD representation
139
+ */
140
+ private resolveJsonLdUrl;
141
+ /**
142
+ * Load both profile with vocabularies and metadata
143
+ */
144
+ loadAll(profileUrl: string, metadataUrl: string): Promise<MetadataWithProfile>;
145
+ /**
146
+ * Extract text from a label (string or multilingual array)
147
+ */
148
+ static extractLabelText(label: string | Array<{
149
+ lang: string;
150
+ value: string;
151
+ }>, preferredLanguage?: string): string;
152
+ /**
153
+ * Clear all caches (profiles, metadata, and vocabularies)
154
+ */
155
+ clearCache(): void;
156
+ /**
157
+ * Get all loaded vocabularies
158
+ */
159
+ getVocabularies(): ResolvedVocabulary[];
160
+ /**
161
+ * Get a specific vocabulary by URL
162
+ */
163
+ getVocabulary(url: string): ResolvedVocabulary | undefined;
164
+ /**
165
+ * Get combined dictionary of all vocabulary entries
166
+ */
167
+ getVocabularyDictionary(): Record<string, VocabularyEntry>;
168
+ }
169
+ //#endregion
170
+ export { type LoaderOptions, MetadataResolver, type MetadataWithProfile, type ProfileWithVocabularies, type ResolvedVocabulary, type TextWithLanguage, type TextWithLanguageAndId, type VocabConcept, type VocabularyData, type VocabularyEntry };
package/dist/index.mjs ADDED
@@ -0,0 +1,262 @@
1
+ //#region src/metadata-resolver.ts
2
+ var MetadataResolver = class {
3
+ corsProxy;
4
+ cache = /* @__PURE__ */ new Map();
5
+ vocabulariesStore = /* @__PURE__ */ new Map();
6
+ useCache;
7
+ preferredLanguage;
8
+ requestTimeout;
9
+ constructor(options) {
10
+ this.corsProxy = options?.corsProxy;
11
+ this.useCache = options?.cache ?? true;
12
+ this.preferredLanguage = options?.preferredLanguage || "de";
13
+ this.requestTimeout = options?.requestTimeout || 1e4;
14
+ }
15
+ /**
16
+ * Load a profile from a URL
17
+ */
18
+ async loadProfile(url) {
19
+ const cacheKey = `profile:${url}`;
20
+ if (this.useCache && this.cache.has(cacheKey)) return this.cache.get(cacheKey);
21
+ try {
22
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(url)}` : url;
23
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
24
+ if (!response.ok) throw new Error(`Failed to load profile: ${response.status} ${response.statusText}`);
25
+ const profile = await response.json();
26
+ if (this.useCache) this.cache.set(cacheKey, profile);
27
+ return profile;
28
+ } catch (error) {
29
+ throw new Error(`Error loading profile from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`);
30
+ }
31
+ }
32
+ /**
33
+ * Load metadata from a URL
34
+ */
35
+ async loadMetadata(url) {
36
+ const cacheKey = `metadata:${url}`;
37
+ if (this.useCache && this.cache.has(cacheKey)) return this.cache.get(cacheKey);
38
+ try {
39
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(url)}` : url;
40
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
41
+ if (!response.ok) throw new Error(`Failed to load metadata: ${response.status} ${response.statusText}`);
42
+ const metadata = await response.json();
43
+ if (this.useCache) this.cache.set(cacheKey, metadata);
44
+ return metadata;
45
+ } catch (error) {
46
+ throw new Error(`Error loading metadata from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`);
47
+ }
48
+ }
49
+ /**
50
+ * Extract vocabulary URLs from a profile
51
+ */
52
+ extractVocabularyUrls(profile) {
53
+ const urls = /* @__PURE__ */ new Set();
54
+ profile.groups?.forEach((group) => {
55
+ group.entries?.forEach((entry) => {
56
+ if (entry.type === "vocabulary" && entry.parameters) {
57
+ const params = entry.parameters;
58
+ if (params.url) urls.add(params.url);
59
+ }
60
+ });
61
+ });
62
+ return Array.from(urls);
63
+ }
64
+ /**
65
+ * Load a single vocabulary from URL
66
+ * Uses vocabulariesStore as the cache
67
+ */
68
+ async loadVocabulary(url) {
69
+ if (this.useCache && this.vocabulariesStore.has(url)) return this.vocabulariesStore.get(url);
70
+ try {
71
+ console.log(`Loading vocabulary: ${url}`);
72
+ const jsonLdUrl = await this.resolveJsonLdUrl(url);
73
+ if (jsonLdUrl !== url) console.log(` Resolved to: ${jsonLdUrl}`);
74
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonLdUrl)}` : jsonLdUrl;
75
+ if (this.corsProxy) console.log(` Using CORS proxy`);
76
+ const response = await fetch(fetchUrl, { signal: AbortSignal.timeout(this.requestTimeout) });
77
+ if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
78
+ const data = await response.json();
79
+ if (!data.hasTopConcept || !Array.isArray(data.hasTopConcept)) throw new Error("Invalid structure: missing hasTopConcept");
80
+ const dictionary = this.buildVocabularyDictionary(data);
81
+ const resolved = {
82
+ url,
83
+ data,
84
+ dictionary
85
+ };
86
+ if (this.useCache) this.vocabulariesStore.set(url, resolved);
87
+ console.log(` Loaded: ${data.hasTopConcept.length} concepts, ${Object.keys(dictionary).length} entries`);
88
+ return resolved;
89
+ } catch (error) {
90
+ const errorMsg = error instanceof Error ? error.message : String(error);
91
+ console.error(` Failed to load vocabulary: ${errorMsg}`);
92
+ return {
93
+ url,
94
+ data: { hasTopConcept: [] },
95
+ dictionary: {},
96
+ error: errorMsg
97
+ };
98
+ }
99
+ }
100
+ /**
101
+ * Load all vocabularies referenced in a profile
102
+ */
103
+ async loadVocabularies(profile) {
104
+ const urls = this.extractVocabularyUrls(profile);
105
+ const vocabularies = (await Promise.allSettled(urls.map((url) => this.loadVocabulary(url)))).filter((result) => result.status === "fulfilled").map((result) => result.value);
106
+ console.log(`Loaded ${vocabularies.length} vocabularies (${this.vocabulariesStore.size} total in store)`);
107
+ return vocabularies;
108
+ }
109
+ /**
110
+ * Build a dictionary from vocabulary data
111
+ */
112
+ buildVocabularyDictionary(vocabData) {
113
+ const dictionary = {};
114
+ const processNode = (node, parentNotation = []) => {
115
+ const notation = node.notation || parentNotation;
116
+ const label = node.prefLabel?.[this.preferredLanguage] || node.prefLabel?.de || node.prefLabel?.en || "";
117
+ dictionary[node.id] = {
118
+ id: node.id,
119
+ notation,
120
+ name: label,
121
+ description: node.description || "",
122
+ text: [{
123
+ lang: this.preferredLanguage,
124
+ value: label
125
+ }]
126
+ };
127
+ if (node.narrower && Array.isArray(node.narrower)) node.narrower.forEach((child) => processNode(child, notation));
128
+ };
129
+ vocabData.hasTopConcept?.forEach((topConcept) => processNode(topConcept));
130
+ return dictionary;
131
+ }
132
+ /**
133
+ * Load a profile and all its vocabularies
134
+ */
135
+ async loadProfileWithVocabularies(profileUrl) {
136
+ const profile = await this.loadProfile(profileUrl);
137
+ return {
138
+ profile,
139
+ vocabularies: await this.loadVocabularies(profile)
140
+ };
141
+ }
142
+ /**
143
+ * Resolve a URL to its JSON-LD representation
144
+ */
145
+ async resolveJsonLdUrl(originalUrl) {
146
+ try {
147
+ console.log(`Resolving URL: ${originalUrl}`);
148
+ console.log(` CORS proxy: ${this.corsProxy || "disabled"}`);
149
+ const fetchUrl = this.corsProxy ? `${this.corsProxy}${encodeURIComponent(originalUrl)}` : originalUrl;
150
+ console.log(` Fetching: ${fetchUrl}`);
151
+ const res = await fetch(fetchUrl, {
152
+ method: "GET",
153
+ redirect: "follow",
154
+ signal: AbortSignal.timeout(this.requestTimeout)
155
+ });
156
+ const finalUrl = res.url;
157
+ const contentType = res.headers.get("content-type");
158
+ if (contentType?.includes("application/json") || contentType?.includes("application/ld+json")) return finalUrl;
159
+ if (contentType?.includes("text/html")) {
160
+ if (finalUrl.endsWith(".html")) {
161
+ const jsonldUrl = finalUrl.replace(/\.html$/, ".jsonld");
162
+ try {
163
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonldUrl)}` : jsonldUrl, {
164
+ method: "HEAD",
165
+ signal: AbortSignal.timeout(this.requestTimeout)
166
+ })).ok) {
167
+ console.log(` Found JSON-LD: ${jsonldUrl}`);
168
+ return jsonldUrl;
169
+ }
170
+ } catch (err) {
171
+ console.log(` JSON-LD not available: ${err instanceof Error ? err.message : String(err)}`);
172
+ }
173
+ const jsonUrl = finalUrl.replace(/\.html$/, ".json");
174
+ try {
175
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(jsonUrl)}` : jsonUrl, {
176
+ method: "HEAD",
177
+ signal: AbortSignal.timeout(this.requestTimeout)
178
+ })).ok) {
179
+ console.log(` Found JSON: ${jsonUrl}`);
180
+ return jsonUrl;
181
+ }
182
+ } catch (err) {
183
+ console.log(` JSON not available: ${err instanceof Error ? err.message : String(err)}`);
184
+ }
185
+ }
186
+ const jsonCandidates = [finalUrl.endsWith("/") ? `${finalUrl}index.json` : `${finalUrl}/index.json`, finalUrl.endsWith("/") ? `${finalUrl}index.jsonld` : `${finalUrl}/index.jsonld`];
187
+ for (const candidate of jsonCandidates) try {
188
+ if ((await fetch(this.corsProxy ? `${this.corsProxy}${encodeURIComponent(candidate)}` : candidate, {
189
+ method: "HEAD",
190
+ signal: AbortSignal.timeout(this.requestTimeout)
191
+ })).ok) {
192
+ console.log(` Found: ${candidate}`);
193
+ return candidate;
194
+ }
195
+ } catch (err) {
196
+ console.log(` Not available: ${candidate} - ${err instanceof Error ? err.message : String(err)}`);
197
+ }
198
+ console.warn("No JSON file found at HTML URL:", finalUrl);
199
+ return finalUrl;
200
+ }
201
+ return finalUrl;
202
+ } catch (err) {
203
+ console.warn("Failed to resolve JSON-LD URL, falling back to original:", originalUrl, err);
204
+ return originalUrl;
205
+ }
206
+ }
207
+ /**
208
+ * Load both profile with vocabularies and metadata
209
+ */
210
+ async loadAll(profileUrl, metadataUrl) {
211
+ const [profileWithVocabs, metadata] = await Promise.all([this.loadProfileWithVocabularies(profileUrl), this.loadMetadata(metadataUrl)]);
212
+ return {
213
+ profile: profileWithVocabs.profile,
214
+ metadata,
215
+ vocabularies: profileWithVocabs.vocabularies
216
+ };
217
+ }
218
+ /**
219
+ * Extract text from a label (string or multilingual array)
220
+ */
221
+ static extractLabelText(label, preferredLanguage = "de") {
222
+ if (typeof label === "string") return label;
223
+ if (Array.isArray(label)) {
224
+ const preferred = label.find((l) => l.lang === preferredLanguage);
225
+ if (preferred) return preferred.value;
226
+ if (label.length > 0) return label[0].value;
227
+ }
228
+ return "";
229
+ }
230
+ /**
231
+ * Clear all caches (profiles, metadata, and vocabularies)
232
+ */
233
+ clearCache() {
234
+ this.cache.clear();
235
+ this.vocabulariesStore.clear();
236
+ }
237
+ /**
238
+ * Get all loaded vocabularies
239
+ */
240
+ getVocabularies() {
241
+ return Array.from(this.vocabulariesStore.values());
242
+ }
243
+ /**
244
+ * Get a specific vocabulary by URL
245
+ */
246
+ getVocabulary(url) {
247
+ return this.vocabulariesStore.get(url);
248
+ }
249
+ /**
250
+ * Get combined dictionary of all vocabulary entries
251
+ */
252
+ getVocabularyDictionary() {
253
+ const combinedDict = {};
254
+ this.vocabulariesStore.forEach((vocab) => {
255
+ Object.assign(combinedDict, vocab.dictionary);
256
+ });
257
+ return combinedDict;
258
+ }
259
+ };
260
+
261
+ //#endregion
262
+ export { MetadataResolver };
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@iqb/metadata-resolver",
3
+ "version": "0.1.0",
4
+ "description": "Framework-agnostic metadata and vocabulary resolver for IQB metadata profiles",
5
+ "main": "dist/index.js",
6
+ "module": "dist/index.mjs",
7
+ "types": "dist/index.d.ts",
8
+ "files": [
9
+ "dist"
10
+ ],
11
+ "scripts": {
12
+ "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
13
+ "dev": "tsdown src/index.ts --format cjs,esm --dts --watch"
14
+ },
15
+ "keywords": [
16
+ "metadata",
17
+ "vocabulary",
18
+ "resolver",
19
+ "iqb"
20
+ ],
21
+ "author": "IQB",
22
+ "license": "MIT",
23
+ "dependencies": {
24
+ "@iqb/metadata": "^1.4.1"
25
+ },
26
+ "devDependencies": {
27
+ "tsdown": "^0.20.0-beta.2",
28
+ "typescript": "^5.3.0"
29
+ },
30
+ "exports": {
31
+ ".": {
32
+ "types": "./dist/index.d.ts",
33
+ "import": "./dist/index.mjs",
34
+ "require": "./dist/index.js"
35
+ }
36
+ },
37
+ "publishConfig": {
38
+ "access": "public"
39
+ }
40
+ }