ochre-sdk 1.0.7 → 1.0.9

package/dist/index.d.mts

@@ -1044,9 +1044,11 @@ declare function fetchGallery<const TLanguages extends ReadonlyArray<string> | u
 }, options?: FetchGalleryBaseOptions<TLanguages>): Promise<{
   gallery: Gallery<FetchGalleryLanguages<TLanguages>>;
   error: null;
+  detailedError: null;
 } | {
   gallery: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/fetchers/item-links.d.ts
@@ -1071,9 +1073,11 @@ declare function fetchItemLinks<const TContainedItemCategory extends ContainedIt
 }): Promise<{
   items: Array<Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLinksLanguages<TLanguages>, "embedded">>;
   error: null;
+  detailedError: null;
 } | {
   items: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/fetchers/item.d.ts
@@ -1115,9 +1119,11 @@ declare function fetchItem<const TContainedItemCategory extends ContainedItemCat
 }): Promise<{
   item: Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>;
   error: null;
+  detailedError: null;
 } | {
   item: null;
   error: string;
+  detailedError: string;
 }>;
 declare function fetchItem<const TCategory extends ItemContainerCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
   category: TCategory;
@@ -1125,9 +1131,11 @@ declare function fetchItem<const TCategory extends ItemContainerCategory, const
 }): Promise<{
   item: Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>;
   error: null;
+  detailedError: null;
 } | {
   item: null;
   error: string;
+  detailedError: string;
 }>;
 declare function fetchItem<const TCategory extends ItemCategory, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
   category: TCategory;
@@ -1135,9 +1143,11 @@ declare function fetchItem<const TCategory extends ItemCategory, const TLanguage
 }): Promise<{
   item: Item<TCategory, ContainedItemCategory<TCategory>, FetchItemLanguages<TLanguages>>;
   error: null;
+  detailedError: null;
 } | {
   item: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/fetchers/set/items.d.ts
@@ -1175,12 +1185,14 @@ declare function fetchSetItems<const TContainedItemCategories extends ReadonlyAr
   pageSize: number;
   items: Array<SetItem<FetchSetItemsCategory<TContainedItemCategories>, FetchSetItemsLanguages<TLanguages>>>;
   error: null;
+  detailedError: null;
 } | {
   totalCount: null;
   page: null;
   pageSize: null;
   items: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/fetchers/set/property-values.d.ts
@@ -1217,11 +1229,13 @@ declare function fetchSetPropertyValues(params: {
     periods: Array<SetAttributeValueQueryItem> | null;
   };
   error: null;
+  detailedError: null;
 } | {
   propertyValues: null;
   propertyValuesByPropertyVariableUuid: null;
   attributeValues: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/types/website.d.ts
@@ -1734,9 +1748,11 @@ declare function fetchWebsite<const T extends LanguageCodes = LanguageCodes>(abb
 }): Promise<{
   website: Website<T>;
   error: null;
+  detailedError: null;
 } | {
   website: null;
   error: string;
+  detailedError: string;
 }>;
 //#endregion
 //#region src/getters.d.ts

package/dist/index.mjs

@@ -487,72 +487,139 @@ var MultilingualString = class MultilingualString {
 };
 //#endregion
 //#region src/utils.ts
-const MAX_SCHEMA_VALIDATION_ISSUES = 3;
 const PSEUDO_UUID_REGEX = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
-function getSchemaValidationLeafIssues(issues, leaves = []) {
-	for (const issue of issues) {
-		if (issue.issues != null && issue.issues.length > 0) {
-			getSchemaValidationLeafIssues(issue.issues, leaves);
-			continue;
-		}
-		leaves.push(issue);
-	}
-	return leaves;
+function isRecord$5(value) {
+	return typeof value === "object" && value != null;
 }
-function formatSchemaValidationIssue(issue) {
-	const path = v.getDotPath(issue);
-	return `${path != null && path.length > 0 ? path : "(root)"}: ${issue.message}`;
+function isSchemaValidationIssue(value) {
+	if (!isRecord$5(value)) return false;
+	return typeof value.kind === "string" && typeof value.type === "string" && typeof value.message === "string";
 }
-/**
-* Formats Valibot validation issues for compact error messages.
-* @param issues - The validation issues to format
-* @internal
-*/
-function formatSchemaValidationIssues(issues) {
-	const leafIssues = getSchemaValidationLeafIssues(issues);
-	const issuesToFormat = leafIssues.length > 0 ? leafIssues : issues;
-	const formattedIssues = [];
-	for (const issue of issuesToFormat.slice(0, MAX_SCHEMA_VALIDATION_ISSUES)) formattedIssues.push(formatSchemaValidationIssue(issue));
-	const hiddenIssueCount = issuesToFormat.length - formattedIssues.length;
-	if (hiddenIssueCount > 0) formattedIssues.push(`+${hiddenIssueCount.toLocaleString("en-US")} more`);
-	return `Schema validation failed: ${formattedIssues.join("; ")}`;
+function isSchemaValidationIssues(value) {
+	if (!Array.isArray(value) || value.length === 0) return false;
+	for (const item of value) if (!isSchemaValidationIssue(item)) return false;
+	return true;
 }
-/**
-* Creates an Error whose message includes compact schema-validation details.
-* @param message - The base error message
-* @param issues - The validation issues to include
-* @internal
-*/
-function createSchemaValidationError(message, issues) {
-	return new Error(`${message}. ${formatSchemaValidationIssues(issues)}`, { cause: issues });
+function getIssuePath(issue) {
+	const path = v.getDotPath(issue);
+	return path != null && path.length > 0 ? path : "(root)";
+}
+function formatPrimitiveValue(value) {
+	if (value == null) return String(value);
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") return String(value);
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof RegExp) return String(value);
+	return null;
 }
-/**
-* Logs Valibot validation issues to the console with detailed formatting
-* @param issues - The validation issues to log
-* @param depth - The depth of the issues for indentation
-* @internal
-*/
-function logIssues(issues, depth = 0) {
-	if (issues == null) return;
+function appendSchemaValidationIssues(lines, issues, depth = 0, prefix = "") {
+	let index = 0;
 	for (const issue of issues) {
+		index += 1;
+		const number = prefix.length > 0 ? `${prefix}.${index}` : String(index);
 		const indent = "  ".repeat(depth);
-		const prefix = depth === 0 ? "❌" : "└─";
-		const pathStr = issue.path != null && issue.path.length > 0 ? ` at ${v.getDotPath(issue)}` : "";
-		const typeInfo = `[${issue.kind}:${issue.type}]`;
-		console.error(`${indent}${prefix} ${typeInfo} ${issue.message}${pathStr}`);
-		if (issue.expected != null) {
-			console.error(`${indent}   Expected: ${issue.expected}`);
-			console.error(`${indent}   Received: ${issue.received}`);
-		}
-		if (issue.input !== void 0 && typeof issue.input !== "object") console.error(`${indent}   Input: ${JSON.stringify(issue.input)}`);
-		if (issue.requirement !== void 0) console.error(`${indent}   Requirement: ${JSON.stringify(issue.requirement)}`);
+		lines.push(`${indent}${number}. ${getIssuePath(issue)}`, `${indent}   Message: ${issue.message}`, `${indent}   Type: ${issue.kind}:${issue.type}`);
+		if (issue.expected != null) lines.push(`${indent}   Expected: ${issue.expected}`);
+		if (issue.received.length > 0) lines.push(`${indent}   Received: ${issue.received}`);
+		const input = formatPrimitiveValue(issue.input);
+		if (input != null) lines.push(`${indent}   Input: ${input}`);
+		const requirement = formatPrimitiveValue(issue.requirement);
+		if (requirement != null) lines.push(`${indent}   Requirement: ${requirement}`);
 		if (issue.issues != null && issue.issues.length > 0) {
-			console.error(`${indent}   Nested issues:`);
-			logIssues(issue.issues, depth + 1);
+			lines.push(`${indent}   Nested issues:`);
+			appendSchemaValidationIssues(lines, issue.issues, depth + 1, number);
 		}
-		if (depth === 0) console.error("");
 	}
 }
+function formatCauseValue(value) {
+	if (typeof value === "string") return value.length > 0 ? value : null;
+	const primitiveValue = formatPrimitiveValue(value);
+	if (primitiveValue != null) return primitiveValue;
+	if (Array.isArray(value)) {
+		const values = [];
+		for (const item of value) {
+			const formattedItem = typeof item === "string" && item.length > 0 ? item : formatPrimitiveValue(item);
+			if (formattedItem != null && formattedItem.length > 0) values.push(formattedItem);
+		}
+		return values.length > 0 ? values.join(", ") : null;
+	}
+	if (isRecord$5(value)) {
+		const values = [];
+		for (const [key, entryValue] of Object.entries(value)) {
+			const formattedEntryValue = formatPrimitiveValue(entryValue);
+			if (formattedEntryValue != null) values.push(`${key}: ${formattedEntryValue}`);
+		}
+		return values.length > 0 ? values.join("; ") : null;
+	}
+	return null;
+}
+function appendDetailedError(lines, error, fallbackMessage, depth, seenErrors) {
+	const indent = "  ".repeat(depth);
+	if (error instanceof Error) {
+		if (seenErrors.has(error)) {
+			lines.push(`${indent}Error: [Circular cause]`);
+			return;
+		}
+		seenErrors.add(error);
+		lines.push(`${indent}Error`);
+		if (error.name !== "Error") lines.push(`${indent}Name: ${error.name}`);
+		lines.push(`${indent}Message: ${error.message}`);
+		if (error instanceof AggregateError && error.errors.length > 0) {
+			lines.push("", `${indent}Contained errors`);
+			let index = 0;
+			for (const containedError of error.errors) {
+				index += 1;
+				lines.push(`${indent}${index}.`);
+				appendDetailedError(lines, containedError, "Unknown error", depth + 1, seenErrors);
+			}
+		}
+		if (error.cause != null) {
+			const causeLines = [];
+			if (appendDetailedCause(causeLines, error.cause, depth, seenErrors)) lines.push("", ...causeLines);
+		}
+		return;
+	}
+	lines.push(`${indent}Error`, `${indent}Message: ${fallbackMessage}`);
+	const value = formatCauseValue(error);
+	if (value != null) lines.push(`${indent}Value: ${value}`);
+}
+function appendDetailedCause(lines, cause, depth, seenErrors) {
+	const indent = "  ".repeat(depth);
+	if (isSchemaValidationIssues(cause)) {
+		lines.push(`${indent}Schema validation`);
+		appendSchemaValidationIssues(lines, cause, depth);
+		return true;
+	}
+	if (cause instanceof Error) {
+		lines.push(`${indent}Cause`);
+		appendDetailedError(lines, cause, cause.message, depth + 1, seenErrors);
+		return true;
+	}
+	const formattedCause = formatCauseValue(cause);
+	if (formattedCause != null) {
+		lines.push(`${indent}Cause`, `${indent}${formattedCause}`);
+		return true;
+	}
+	return false;
+}
+function getErrorMessage(error, fallbackMessage) {
+	return error instanceof Error ? error.message : fallbackMessage;
+}
+function getDetailedError(error, fallbackMessage = "Unknown error") {
+	const lines = [];
+	appendDetailedError(lines, error, fallbackMessage, 0, /* @__PURE__ */ new Set());
+	return lines.join("\n");
+}
+function getErrorOutput(error, fallbackMessage) {
+	const message = getErrorMessage(error, fallbackMessage);
+	return {
+		error: message,
+		detailedError: getDetailedError(error, message)
+	};
+}
+function createSchemaValidationError(message, issues) {
+	return new Error(message, { cause: issues });
+}
 /**
 * Validates a pseudo-UUID string
 * @param value - The string to validate
@@ -3672,20 +3739,17 @@ async function fetchGallery(params, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLGalleryData, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse gallery XML", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse gallery XML", issues);
 		restoreXMLMetadata(output, data);
 		return {
 			gallery: parseGallery(output, { languages: resolveGalleryLanguages(output, requestedLanguages) }),
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			gallery: null,
-			error: error instanceof Error ? error.message : "Failed to fetch gallery"
+			...getErrorOutput(error, "Failed to fetch gallery")
 		};
 	}
 }
@@ -3782,10 +3846,7 @@ async function fetchItemLinks(uuid, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLItemLinksData, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse OCHRE item links", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item links", issues);
 		restoreXMLMetadata(output, data);
 		const languages = resolveItemLinksLanguages(output, requestedLanguages);
 		return {
@@ -3793,13 +3854,13 @@ async function fetchItemLinks(uuid, options) {
 				containedItemCategory: options?.containedItemCategory,
 				languages
 			}),
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			items: null,
-			error: error instanceof Error ? error.message : "Unknown error"
+			...getErrorOutput(error, "Unknown error")
 		};
 	}
 }
@@ -3883,10 +3944,7 @@ async function fetchItem(uuid, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLData, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse OCHRE data", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE data", issues);
 		restoreXMLMetadata(output, data);
 		const category = options?.category ?? inferFetchItemCategory(output.result.ochre);
 		assertItemCategoryAllowed(category, options?.containedItemCategory);
@@ -3896,13 +3954,13 @@ async function fetchItem(uuid, options) {
 				containedItemCategory: options?.containedItemCategory,
 				languages
 			}),
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			item: null,
-			error: error instanceof Error ? error.message : "Unknown error"
+			...getErrorOutput(error, "Unknown error")
 		};
 	}
 }
@@ -4957,10 +5015,7 @@ async function fetchSetItems(params, containedItemCategories, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLSetItemsData, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse OCHRE Set items", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE Set items", issues);
 		restoreXMLMetadata(output, data);
 		if (containedItemCategories != null) {
 			const missingCategories = containedItemCategories.filter((category) => !hasSetItemsCategory(output.result.ochre.items, category));
@@ -4979,16 +5034,16 @@ async function fetchSetItems(params, containedItemCategories, options) {
 			page: output.result.ochre.items.page,
 			pageSize: output.result.ochre.items.pageSize,
 			items: uniqueItems,
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			totalCount: null,
 			page: null,
 			pageSize: null,
 			items: null,
-			error: error instanceof Error ? error.message : "Failed to fetch Set items"
+			...getErrorOutput(error, "Failed to fetch Set items")
 		};
 	}
 }
@@ -5415,7 +5470,8 @@ async function fetchSetPropertyValues(params, options) {
 				bibliographies: null,
 				periods: null
 			},
-			error: null
+			error: null,
+			detailedError: null
 		};
 		const xquery = buildXQuery({
 			setScopeUuids,
@@ -5434,10 +5490,7 @@ async function fetchSetPropertyValues(params, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(responseSchema, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse OCHRE Set property values", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE Set property values", issues);
 		const parsedPropertyValues = [];
 		const parsedAttributeValues = [];
 		if (output.result.ochre.propertyValue != null) parsedPropertyValues.push(...Array.isArray(output.result.ochre.propertyValue) ? output.result.ochre.propertyValue : [output.result.ochre.propertyValue]);
@@ -5487,15 +5540,15 @@ async function fetchSetPropertyValues(params, options) {
 				bibliographies: attributes.bibliographies ? sortAttributeValues(attributeValuesByType.bibliographies) : null,
 				periods: attributes.periods ? sortAttributeValues(attributeValuesByType.periods) : null
 			},
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			propertyValues: null,
 			propertyValuesByPropertyVariableUuid: null,
 			attributeValues: null,
-			error: error instanceof Error ? error.message : "Failed to fetch property values"
+			...getErrorOutput(error, "Failed to fetch property values")
 		};
 	}
 }
@@ -6577,11 +6630,8 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			};
 			break;
 		}
-		default:
-			console.warn(`Invalid or non-implemented component name “${unparsedComponentName.toString()}” for the following element: “${parseStringContent(elementResource.identification.label, options)}”`);
-			break;
+		default: throw new Error(`Invalid or non-implemented component name “${unparsedComponentName.toString()}” for the following element: “${parseStringContent(elementResource.identification.label, options)}”`);
 	}
-	if (properties === null) throw new Error(formatComponentError("Properties not found", componentName, elementResource), { cause: componentProperty });
 	return properties;
 }
 function parseWebTitle(properties, identification, overrides) {
@@ -7162,20 +7212,17 @@ async function fetchWebsite(abbreviation, options) {
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLWebsiteData, data);
-		if (!success) {
-			logIssues(issues);
-			throw createSchemaValidationError("Failed to parse website XML", issues);
-		}
+		if (!success) throw createSchemaValidationError("Failed to parse website XML", issues);
 		restoreXMLMetadata(output, data);
 		return {
 			website: parseWebsite(output, { languages: options?.languages }),
-			error: null
+			error: null,
+			detailedError: null
 		};
 	} catch (error) {
-		console.error(error);
 		return {
 			website: null,
-			error: error instanceof Error ? error.message : "Unknown error"
+			...getErrorOutput(error, "Unknown error")
 		};
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -52,7 +52,7 @@
     "@antfu/eslint-config": "^9.0.0",
     "@types/node": "^24.12.4",
     "bumpp": "^11.1.0",
-    "eslint": "^10.3.0",
+    "eslint": "^10.4.0",
     "prettier": "^3.8.3",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",