ochre-sdk 1.0.78 → 1.1.0

package/dist/fetchers/item.mjs

@@ -1,27 +1,14 @@
-import { XML_PARSER_OPTIONS } from "../constants.mjs";
-import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
-import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS, ITEM_CONTAINER_CATEGORIES, isItemCategoryWithEmbeddedItems, isItemContainerCategory } from "../categories.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { uuidSchema } from "../schemas.mjs";
+import { parseRequestedLanguages } from "../parsers/languages.mjs";
 import { parseItem } from "../parsers/index.mjs";
 import { XMLData } from "../xml/schemas.mjs";
+import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import { parseWebpageView } from "../parsers/website/index.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/item.ts
-function isItemContainerCategory(category) {
-	return category === "tree" || category === "set";
-}
-function isItemCategoryWithEmbeddedItems(category) {
-	return [
-		"tree",
-		"bibliography",
-		"concept",
-		"spatialUnit",
-		"period",
-		"resource",
-		"set"
-	].includes(category);
-}
 function isItemWithEmbeddedItems(item) {
 	return isItemCategoryWithEmbeddedItems(item.category);
 }
@@ -49,14 +36,8 @@ function buildXQuery(parameters) {
 	let itemNodesExpression = "$ochre/node()";
 	if (shouldOmitEmbeddedItems) {
 		letClauses.push(`let $item := (
-  $ochre/tree,
-  $ochre/bibliography,
-  $ochre/concept,
-  $ochre/spatialUnit,
-  $ochre/period,
-  $ochre/resource,
-  $ochre/set
-)[1]`, `let $embedded-child-name := if (local-name($item) = ("tree", "set")) then "items" else local-name($item)`);
+${ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS.map((category) => `  $ochre/${category}`).join(",\n")}
+)[1]`, `let $embedded-child-name := if (local-name($item) = (${ITEM_CONTAINER_CATEGORIES.map((category) => stringLiteral(category)).join(", ")})) then "items" else local-name($item)`);
 		itemNodesExpression = `(
       for $node in $ochre/node()
       return
@@ -65,69 +46,36 @@ function buildXQuery(parameters) {
         else $node
     )`;
 	}
-	return `xquery version "1.0-ml";
-
-${SUPPLEMENTAL_XQUERY_PROLOG}
-
-${letClauses.join("\n")}
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `${letClauses.join("\n")}
 return
   if (empty($ochre)) then ()
   else element ochre {
     $ochre/@*,
     ${omitSupplemental(itemNodesExpression)}
-  }`;
+  }` });
 }
 function omitEmbeddedItems(item) {
 	const { items: _items, ...itemWithoutEmbeddedItems } = item;
 	return itemWithoutEmbeddedItems;
 }
-/**
-* Validate language codes while preserving literal tuple inference.
-*/
-function parseLanguages(languages) {
-	for (const language of languages) v.parse(iso639_3Schema, language);
-	return languages;
-}
-/**
-* Defines a reusable languages tuple with validation and literal type inference.
-*
-* Inline arrays can be passed directly to fetchItem:
-* `fetchItem(uuid, { languages: ["eng", "spa"] })`.
-*
-* Use this helper when the language set is stored separately:
-* `const languages = defineLanguages("eng", "spa")`.
-*/
-function defineLanguages(...languages) {
-	return parseLanguages(languages);
-}
-/**
-* @deprecated Pass inline language arrays directly to fetchItem, or use
-* defineLanguages("eng", "spa") for reusable language tuples.
-*/
-function withLanguages(languages) {
-	return parseLanguages(languages);
-}
 async function fetchItem(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
 		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
-		const languages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery({
+		const languages = parseRequestedLanguages(options?.languages);
+		const output = await requestOchre({
+			xquery: buildXQuery({
 				uuid: parsedUuid,
 				shouldOmitEmbeddedItems
 			}),
-			headers: { "Content-Type": "application/xquery" }
+			schema: XMLData,
+			label: "OCHRE item",
+			options,
+			checkRawData: (data) => {
+				if (data.result?.ochre?.uuid == null) throw new Error(`No OCHRE item found for UUID "${parsedUuid}"`, { cause: data });
+			}
 		});
-		if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		if (data.result?.ochre?.uuid == null) throw new Error(`No OCHRE item found for UUID "${parsedUuid}"`, { cause: dataRaw });
-		const { success, issues, output } = v.safeParse(XMLData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE data", issues);
-		restoreXMLMetadata(output, data);
 		const parsedItem = parseItem(output, {
 			category: options?.category,
 			containedItemCategory: options?.containedItemCategory,
@@ -148,4 +96,4 @@ async function fetchItem(uuid, options) {
 	}
 }
 //#endregion
-export { defineLanguages, fetchItem, withLanguages };
+export { fetchItem };

package/dist/fetchers/request.d.mts

@@ -0,0 +1,70 @@
+import { FetchFunction } from "../parsers/helpers.mjs";
+import * as v from "valibot";
+//#region src/fetchers/request.d.ts
+export type OchreRequestOptions = {
+  fetch?: FetchFunction;
+  signal?: AbortSignal;
+  timeoutMilliseconds?: number;
+};
+/**
+ * Turn an OCHRE XML response into validated data
+ *
+ * The XML parser, the schema check and the metadata graft are one step: the
+ * graft has to follow validation because `v.safeParse` drops the
+ * non-enumerable source offsets `fast-xml-parser` records, and skipping it
+ * leaves a value that is the right shape but has lost its source order. Kept
+ * separate from the request so a caller holding an XML string, such as a test,
+ * gets exactly what the network path produces.
+ * @param parameters - The decode parameters
+ * @param parameters.xml - The raw XML response body
+ * @param parameters.schema - The schema the response must satisfy
+ * @param parameters.label - What is being decoded, used in failure messages
+ * @param parameters.checkRawData - Guard run against the parsed XML before validation
+ * @returns The validated response, with XML source metadata restored
+ * @throws When the guard rejects or validation fails
+ * @internal
+ */
+export declare function decodeOchreResponse<TOutput>(parameters: {
+  xml: string;
+  schema: v.GenericSchema<unknown, TOutput>;
+  label: string;
+  checkRawData?: (data: unknown) => void;
+}): TOutput;
+/**
+ * Post an XQuery to the OCHRE API and validate the response
+ *
+ * Owns every fact about talking to OCHRE: the endpoint, the request shape and
+ * the failure policy. Decoding the body is {@link decodeOchreResponse}.
+ * @param parameters - The request parameters
+ * @param parameters.xquery - The XQuery to post
+ * @param parameters.schema - The schema the response must satisfy
+ * @param parameters.label - What is being fetched, used in failure messages
+ * @param parameters.options - Transport options
+ * @param parameters.checkRawData - Guard run against the parsed XML before validation
+ * @returns The validated response, with XML source metadata restored
+ * @throws When the request fails, the guard rejects, or validation fails
+ * @internal
+ */
+export declare function requestOchre<TOutput>(parameters: {
+  xquery: string;
+  schema: v.GenericSchema<unknown, TOutput>;
+  label: string;
+  options?: OchreRequestOptions;
+  checkRawData?: (data: unknown) => void;
+}): Promise<TOutput>;
+/**
+ * Post a JSON payload to the OCHRE API
+ * @param parameters - The request parameters
+ * @param parameters.body - The JSON payload to post
+ * @param parameters.label - What is being posted, used in failure messages
+ * @param parameters.options - Transport options
+ * @returns Whether the API accepted the payload
+ * @throws When the request cannot be completed at all
+ * @internal
+ */
+export declare function isOchreJsonAccepted(parameters: {
+  body: unknown;
+  label: string;
+  options?: OchreRequestOptions;
+}): Promise<boolean>;
+//#endregion

package/dist/fetchers/request.mjs

@@ -0,0 +1,100 @@
+import { OCHRE_ENDPOINT, XML_PARSER_OPTIONS } from "../constants.mjs";
+import { createSchemaValidationError } from "../errors.mjs";
+import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/request.ts
+const OCHRE_XQUERY_ENDPOINT = `${OCHRE_ENDPOINT}?xquery&xsl=none&lang="*"`;
+const xmlParser = new XMLParser(XML_PARSER_OPTIONS);
+function resolveSignal(options) {
+	const { signal, timeoutMilliseconds } = options ?? {};
+	if (timeoutMilliseconds == null) return signal;
+	const timeoutSignal = AbortSignal.timeout(timeoutMilliseconds);
+	return signal == null ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
+}
+/**
+* Turn an OCHRE XML response into validated data
+*
+* The XML parser, the schema check and the metadata graft are one step: the
+* graft has to follow validation because `v.safeParse` drops the
+* non-enumerable source offsets `fast-xml-parser` records, and skipping it
+* leaves a value that is the right shape but has lost its source order. Kept
+* separate from the request so a caller holding an XML string, such as a test,
+* gets exactly what the network path produces.
+* @param parameters - The decode parameters
+* @param parameters.xml - The raw XML response body
+* @param parameters.schema - The schema the response must satisfy
+* @param parameters.label - What is being decoded, used in failure messages
+* @param parameters.checkRawData - Guard run against the parsed XML before validation
+* @returns The validated response, with XML source metadata restored
+* @throws When the guard rejects or validation fails
+* @internal
+*/
+function decodeOchreResponse(parameters) {
+	const { xml, schema, label, checkRawData } = parameters;
+	const data = xmlParser.parse(xml);
+	checkRawData?.(data);
+	const { success, issues, output } = v.safeParse(schema, data);
+	if (!success) throw createSchemaValidationError(`Failed to parse ${label}`, issues);
+	restoreXMLMetadata(output, data);
+	return output;
+}
+/**
+* Post an XQuery to the OCHRE API and validate the response
+*
+* Owns every fact about talking to OCHRE: the endpoint, the request shape and
+* the failure policy. Decoding the body is {@link decodeOchreResponse}.
+* @param parameters - The request parameters
+* @param parameters.xquery - The XQuery to post
+* @param parameters.schema - The schema the response must satisfy
+* @param parameters.label - What is being fetched, used in failure messages
+* @param parameters.options - Transport options
+* @param parameters.checkRawData - Guard run against the parsed XML before validation
+* @returns The validated response, with XML source metadata restored
+* @throws When the request fails, the guard rejects, or validation fails
+* @internal
+*/
+async function requestOchre(parameters) {
+	const { xquery, schema, label, options, checkRawData } = parameters;
+	const response = await (options?.fetch ?? fetch)(OCHRE_XQUERY_ENDPOINT, {
+		method: "POST",
+		body: xquery,
+		headers: { "Content-Type": "application/xquery" },
+		signal: resolveSignal(options)
+	});
+	if (!response.ok) throw new Error(`Failed to fetch ${label}: OCHRE API responded with status ${response.status}`, { cause: response.statusText });
+	return decodeOchreResponse({
+		xml: await response.text(),
+		schema,
+		label,
+		checkRawData
+	});
+}
+/**
+* Post a JSON payload to the OCHRE API
+* @param parameters - The request parameters
+* @param parameters.body - The JSON payload to post
+* @param parameters.label - What is being posted, used in failure messages
+* @param parameters.options - Transport options
+* @returns Whether the API accepted the payload
+* @throws When the request cannot be completed at all
+* @internal
+*/
+async function isOchreJsonAccepted(parameters) {
+	const { body, label, options } = parameters;
+	let response;
+	try {
+		response = await (options?.fetch ?? fetch)(OCHRE_ENDPOINT, {
+			method: "POST",
+			body: JSON.stringify(body),
+			headers: { "Content-Type": "application/json" },
+			signal: resolveSignal(options)
+		});
+	} catch (error) {
+		throw new Error(`Failed to post ${label}`, { cause: error });
+	}
+	if (response.status >= 500) throw new Error(`Failed to post ${label}: OCHRE API responded with status ${response.status}`, { cause: response.statusText });
+	return response.ok;
+}
+//#endregion
+export { decodeOchreResponse, isOchreJsonAccepted, requestOchre };

package/dist/fetchers/set/items.mjs

@@ -1,40 +1,13 @@
-import { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../../constants.mjs";
-import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../../utilities.mjs";
-import { iso639_3Schema, setItemsParametersSchema } from "../../schemas.mjs";
-import { restoreXMLMetadata } from "../../xml/metadata.mjs";
+import { getErrorOutput } from "../../errors.mjs";
+import { requestOchre } from "../request.mjs";
+import { setItemsParametersSchema } from "../../schemas.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../../parsers/languages.mjs";
 import { parseSetItems } from "../../parsers/index.mjs";
 import { XMLSetItemsData } from "../../xml/schemas.mjs";
-import { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
+import { stringLiteral } from "../../xquery.mjs";
+import { compileSetItemsQuery } from "../../query.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/items.ts
-function parseLanguages(languages) {
-	for (const language of languages) v.parse(iso639_3Schema, language);
-	return languages;
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function collectContentLanguages(value, languages) {
-	if (Array.isArray(value)) {
-		for (const item of value) collectContentLanguages(item, languages);
-		return;
-	}
-	if (!isRecord(value)) return;
-	const content = value.content;
-	if (Array.isArray(content)) for (const contentItem of content) {
-		if (!isRecord(contentItem)) continue;
-		const language = contentItem.lang;
-		if (typeof language === "string" && language !== "zxx") languages.add(language);
-	}
-	for (const child of Object.values(value)) collectContentLanguages(child, languages);
-}
-function resolveSetItemsLanguages(data, requestedLanguages) {
-	if (requestedLanguages.length > 0) return requestedLanguages;
-	const languages = /* @__PURE__ */ new Set();
-	collectContentLanguages(data.result.ochre.items, languages);
-	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
-}
 function hasArray(items) {
 	return items != null && items.length > 0;
 }
@@ -138,60 +111,41 @@ function buildOrderedItemsClause(sort) {
 function buildXQuery(parameters) {
 	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = parameters;
 	const startPosition = (page - 1) * pageSize + 1;
-	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
-	const compiledQueryPlan = buildQueryPlan({
+	return compileSetItemsQuery({
+		setScopeUuids,
+		belongsToCollectionScopeUuids,
 		queries,
-		baseItemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*",
-		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
-	});
-	const orderedItemsClause = buildOrderedItemsClause(sort);
-	const xqueryDeclarations = [
-		"xquery version \"1.0-ml\";",
-		setScopeDeclaration,
-		SUPPLEMENTAL_XQUERY_PROLOG
-	];
-	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
-	return `${xqueryDeclarations.join("\n\n")}
-
-<ochre>{
-${compiledQueryPlan.itemsClause}
-  let $totalCount := count($items)
-  ${orderedItemsClause}
+		body: ({ items, omitSupplemental }) => `  let $totalCount := count(${items})
+  ${buildOrderedItemsClause(sort)}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
 
   return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
     ${omitSupplemental("$pagedItems")}
-  }</items>
-}</ochre>`;
+  }</items>`
+	});
 }
 async function fetchSetItems(parameters, containedItemCategories, options) {
 	try {
 		const { setScopeUuids, belongsToCollectionScopeUuids, queries, sort, page, pageSize } = v.parse(setItemsParametersSchema, parameters);
-		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const xquery = buildXQuery({
-			setScopeUuids,
-			belongsToCollectionScopeUuids,
-			queries,
-			sort,
-			page,
-			pageSize
-		});
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: xquery,
-			headers: { "Content-Type": "application/xquery" }
+		const requestedLanguages = parseRequestedLanguages(options?.languages);
+		const output = await requestOchre({
+			xquery: buildXQuery({
+				setScopeUuids,
+				belongsToCollectionScopeUuids,
+				queries,
+				sort,
+				page,
+				pageSize
+			}),
+			schema: XMLSetItemsData,
+			label: "OCHRE Set items",
+			options
 		});
-		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`, { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(XMLSetItemsData, data);
-		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));
 			if (missingCategories.length > 0) throw new Error(`No Set items found for item categories: ${missingCategories.join(", ")}`, { cause: missingCategories });
 		}
-		const languages = resolveSetItemsLanguages(output, requestedLanguages);
+		const languages = resolveContentLanguages(output.result.ochre.items, requestedLanguages);
 		const items = parseSetItems(output.result.ochre.items, {
 			containedItemCategories,
 			languages

package/dist/fetchers/set/property-values.d.mts

@@ -1,4 +1,5 @@
 import { PropertyValueQueryItem, Query, SetAttributeValueQueryItem } from "../../types/index.mjs";
+import { OchreRequestOptions } from "../request.mjs";
 //#region src/fetchers/set/property-values.d.ts
 /**
  * Fetches and parses Set property values from the OCHRE API
@@ -23,9 +24,7 @@ export declare function fetchSetPropertyValues(parameters: {
     periods: boolean;
   };
   isLimitedToLeafPropertyValues?: boolean;
-}, options?: {
-  fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
-}): Promise<{
+}, options?: OchreRequestOptions): Promise<{
   propertyValues: Array<PropertyValueQueryItem>;
   propertyValuesByPropertyVariableUuid: Record<string, Array<PropertyValueQueryItem>>;
   attributeValues: {